SPB Git

Repository Public

API.md 38.5 KB 610 lines markdown

1# Guide de l'API — MacLustr Command Center23Guide humain de l'API publique servie par `control-api` sous `/api/v1`. La référence formelle est le contrat4`packages/api-contracts/openapi.yaml` (OpenAPI 3.1, 132 opérations) ; ce guide décrit **ce que le serveur fait au5commit `45f0d03`** et liste en [§8](#8-écarts-connus-entre-contrat-et-implémentation) les points où l'implémentation6s'écarte du contrat. Le protocole des agents (`/agent/v1`) est décrit dans [AGENT-PROTOCOL.md](AGENT-PROTOCOL.md).78Les valeurs des exemples (identifiants, jetons, dates) sont illustratives.910Documents liés : [SECURITY.md](SECURITY.md) · [ARCHITECTURE.md](ARCHITECTURE.md) ·11[`packages/api-contracts/README.md`](../packages/api-contracts/README.md).1213## 1. Bases1415| | |16|---|---|17| Production | `https://clustr.spboucher.ai/api/v1` |18| Développement | `http://localhost:8730/api/v1` |19| Format | JSON (`application/json`), UTF-8 ; corps de requête ≤ 1 Mio |20| Horodatages | RFC 3339 en UTC (`…Z`) |21| Identifiants | UUID v7 |22| Champs optionnels | omis, jamais `null` |23| Corrélation | chaque réponse porte `X-Correlation-Id`, généré par le serveur (un identifiant fourni par le client n'est jamais repris) ; on le retrouve dans `error.correlation_id` et dans l'audit |24| Cache | `Cache-Control: no-store` sur toute réponse d'API |25| Opérations sans session | `GET /health/live`, `GET /health/ready`, `GET /version`, `POST /auth/webauthn/authentication/begin`, `…/finish`, `POST /auth/refresh`, `POST /invitations/exchange` |2627Le serveur est généré depuis le contrat (`services/internal/api/gen.go`) ; la politique de sécurité de chaque28opération vient de la table générée `services/internal/api/ops_gen.go` et est appliquée par `core.admit`29(`services/internal/api/server.go`) avant tout handler.3031## 2. Conventions3233### 2.1 Erreurs3435Toute réponse non 2xx a la même enveloppe :3637```json38{39  "error": {40    "code": "step_up_required",41    "message": "A recent passkey verification is required.",42    "details": {},43    "correlation_id": "019a9c50-0000-7000-8000-00000000cc01"44  }45}46```4748`code` est stable et destiné aux programmes ; `message` est en anglais et destiné aux journaux ; `details` est49facultatif (`permission`, `check`, `action_id`, `fields`, `capability`…). Une erreur inattendue devient un50`500 internal` opaque : le détail est journalisé côté serveur avec l'identifiant de corrélation.5152Codes **réellement émis** par le serveur :5354| HTTP | `code` | Sens | Source |55|---|---|---|---|56| 400 | `validation_failed` | corps, paramètre ou en-tête mal formé | `httpx.Validation` |57| 400 | `challenge_invalid` | défi WebAuthn expiré ou déjà utilisé | `identity.ErrChallenge` |58| 401 | `unauthenticated` | pas de session valide (expirée, révoquée, appareil révoqué, compte désactivé, jeton d'accès expiré : toujours ce même code) | `httpx.ErrUnauthenticated` |59| 401 | `credential_rejected` | passkey refusée (signature, origine, UV, compteur, compte désactivé) | `identity.ErrCredential` |60| 401 | `refresh_rejected` | rafraîchissement impossible (jeton inconnu, expiré, déjà tourné) | `identity.ErrRefresh` |61| 403 | `forbidden` | permission manquante ou `deny` applicable ; `details.permission` | `httpx.ErrForbidden` |62| 403 | `step_up_required` | cérémonie passkey de moins de 5 min requise | `httpx.ErrStepUp` |63| 403 | `csrf_failed` | `X-MCC-CSRF` absent ou invalide, ou `Origin` différent | `httpx.ErrCSRF` |64| 403 | `wrong_account` | invitation `link` ouverte avec un autre compte | `identity.ErrWrongAccount` |65| 404 | `not_found` | ressource inconnue ou cachée à l'appelant | `httpx.ErrNotFound` |66| 409 | `conflict`, `handle_taken`, `last_passkey`, `last_owner`, `self_modification`, `profile_required`, `recovery_pending`, `idempotency_conflict`, `target_locked` | conflits d'état | `identity/service.go`, `actions/store.go` |67| 410 | `invitation_invalid` | invitation inconnue, expirée, consommée ou révoquée (réponse unique) | `identity.ErrInvitation` |68| 410 | `setup_transaction_invalid` | transaction d'invitation expirée ou absente | `identity.ErrSetupTx` |69| 422 | `precheck_failed`, `confirmation_mismatch`, `justification_required`, `agent_offline`, `capability_missing`, `node_in_maintenance`, `action_unavailable`, `unprocessable` | refus d'une action ; `details.check` nomme la pré-vérification | `actions.Refuse` |70| 429 | `rate_limited` | trop de requêtes ; en-tête `Retry-After` (secondes) | `httpx.ErrRateLimited` |71| 500 | `internal` | erreur inattendue | `httpx.WriteError` |72| 501 | `not_implemented` | opération du contrat sans handler (aucune au commit décrit) | `unimplemented_gen.go` |73| 503 | `unavailable` | dépendance indisponible (base, ingestion, web) | `httpx.ErrUnavailable` |74| 503 | `orchestrator_frozen` | gel d'urgence actif | `actions.ErrFrozen` |7576Un client doit tolérer des codes inconnus et se fier d'abord au statut HTTP.7778### 2.2 Pagination7980Curseur opaque : paramètres `limit` (défaut 50, maximum 200) et `cursor` ; réponses `{ "items": […], "next_cursor": "…" }`.81L'absence de `next_cursor` signale la dernière page. La sortie d'une action utilise un curseur numérique propre82(`after`, `next_after`, `truncated`).8384### 2.3 Idempotence8586`POST /actions` et `POST /jobs` exigent l'en-tête `Idempotency-Key` (8 à 128 caractères pour les actions).8788| Cas | Réponse |89|---|---|90| nouvelle demande | `201` + ressource |91| même clé, même corps (même utilisateur) | `200` + la ressource d'origine, rien n'est créé |92| même clé, corps différent | `409 idempotency_conflict` |9394L'empreinte couvre `type`, cible, `params`, `confirm`, `justification` et `override_maintenance`95(`actions.HashRequest`). L'idempotence protège la **demande** ; l'unicité de la commande envoyée à l'agent est une96garantie distincte ([ADR 0010](DECISIONS/0010-at-most-once-commands.md)).9798### 2.4 CSRF99100Pour toute méthode autre que GET, HEAD, OPTIONS :101102- **session par cookie** : en-tête `Origin` égal à l'origine publique **et** en-tête `X-MCC-CSRF` (valeur103  `csrf_token` renvoyée par la connexion et par `GET /me`) ;104- **transaction d'invitation par cookie** : `Origin` égal à l'origine publique ;105- **jeton `Bearer`** ou opération publique : pas de jeton CSRF ; si un `Origin` est envoyé, il doit être l'origine106  publique.107108Échec : `403 csrf_failed`.109110### 2.5 Step-up111112Certaines opérations exigent que la session porte une cérémonie passkey de moins de 5 minutes113(`session.step_up_valid_until`). Sinon : `403 step_up_required`. Le client enchaîne alors114`POST /auth/stepup/begin` → cérémonie → `POST /auth/stepup/finish`, puis rejoue la requête d'origine. Opérations115concernées : colonne « Step-up » du [§6](#6-table-des-permissions), plus `POST /actions` pour les types de criticité116`high` et `critical` (vérifié dans le handler, donc absent de la table).117118### 2.6 Fraîcheur et disponibilité119120Les ressources issues de la télémétrie portent `observed_at` et `freshness`, calculée par le serveur :121122| `freshness` | Âge du dernier rapport |123|---|---|124| `fresh` | < 30 s |125| `stale` | 30 s à 120 s |126| `offline` | > 120 s, ou jamais vu |127128Une valeur qui ne peut pas être mesurée est **absente** et son état est donné par une `Availability` :129`available`, `unavailable` (collecte en échec ce tour-ci), `unsupported` (non mesurable sur ce matériel),130`permission_denied` (mesurable, mais pas avec les droits de l'agent), `stale`, `offline`. Jamais de zéro inventé.131Exemple (extrait de `GET /nodes/{id}`, forme vérifiée par `tests/e2e/local-stack.sh`) :132133```json134{135  "latest": {136    "cpu.usage": { "availability": "available", "value": 27.3 },137    "thermal.temp": { "availability": "unsupported" }138  }139}140```141142Les séries (`GET /nodes/{id}/metrics`) sont des tableaux de points `[ts_ms, avg, min, max]` ; une métrique143étiquetée (interface réseau, volume) donne une série par étiquette (`metric`, `label`, `points`).144145## 3. Authentification146147Le seul moyen d'authentification est la passkey (WebAuthn). Politique : [SECURITY.md §3–§5](SECURITY.md#3-passkeys--webauthn).148149### 3.1 Connexion (sans nom d'utilisateur)150151```http152POST /api/v1/auth/webauthn/authentication/begin153```154155```json156{157  "challenge_id": "019a9c1e-7b10-7c3a-9d54-2f6f1f0f3a11",158  "expires_at": "2026-11-18T21:05:00Z",159  "public_key": {160    "challenge": "3q2-7wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",161    "rpId": "clustr.spboucher.ai",162    "timeout": 300000,163    "userVerification": "required"164  }165}166```167168Le client passe `public_key` à l'API de la plateforme (`navigator.credentials.get`, `ASAuthorization…`), puis :169170```http171POST /api/v1/auth/webauthn/authentication/finish172Content-Type: application/json173Origin: https://clustr.spboucher.ai174175{176  "challenge_id": "019a9c1e-7b10-7c3a-9d54-2f6f1f0f3a11",177  "credential": { "id": "…", "rawId": "…", "type": "public-key",178                  "response": { "clientDataJSON": "…", "authenticatorData": "…", "signature": "…", "userHandle": "…" } },179  "client": { "kind": "web", "label": "Safari · Mac" }180}181```182183Réponse `200` pour un client **web** (`client.kind = "web"`) :184185```http186Set-Cookie: __Host-mcc_session=<opaque>; Path=/; HttpOnly; Secure; SameSite=Strict187Set-Cookie: __Host-mcc_device=<uuid>; Path=/; Max-Age=…; HttpOnly; Secure; SameSite=Strict188```189190```json191{192  "user": { "id": "019a9b00-1111-7aaa-8bbb-000000000001", "handle": "spb", "display_name": "Simon-Pierre",193            "role": "owner", "locale": "fr", "disabled": false, "created_at": "2026-11-18T20:40:00Z" },194  "session": { "id": "019a9c1e-9000-7000-8000-00000000a001", "kind": "cookie", "current": true,195               "device_id": "019a9c1e-9000-7000-8000-00000000d001",196               "authenticated_at": "2026-11-18T21:00:12Z", "step_up_valid_until": "2026-11-18T21:05:12Z",197               "idle_expires_at": "2026-11-18T21:30:12Z", "absolute_expires_at": "2026-11-19T09:00:12Z" },198  "device_id": "019a9c1e-9000-7000-8000-00000000d001",199  "csrf_token": "6fJmC0n1x1c0u0S7wq5a8nq3mVbYb1pZ5nq2dX0v9Qk"200}201```202203Pour un client **natif** (`"kind": "macos"` ou `"ios"`), aucun cookie : la réponse contient à la place204`access_token`, `access_expires_at`, `refresh_token`, `refresh_expires_at`. Le client renvoie ensuite205`Authorization: Bearer <access_token>` et conserve `device_id` pour le représenter dans `client.device_id`.206207Le défi est consommé dès `finish`, quel que soit le résultat : un échec impose de recommencer par `begin`.208209### 3.2 Rafraîchissement (clients natifs)210211```http212POST /api/v1/auth/refresh213Content-Type: application/json214215{ "refresh_token": "<jeton courant>" }216```217218Réponse : nouveau couple `access_token` / `refresh_token` ; l'ancien jeton de rafraîchissement est consommé.219Présenter de nouveau un jeton déjà tourné **révoque la session** (audit `session.refresh_reuse_detected`) et répond220`401 refresh_rejected`.221222### 3.3 Compte courant et jeton CSRF223224```http225GET /api/v1/me226```227228```json229{230  "user": { "id": "…", "handle": "spb", "display_name": "Simon-Pierre", "role": "owner", "locale": "fr",231            "disabled": false, "created_at": "2026-11-18T20:40:00Z" },232  "permissions": ["cluster.read", "nodes.read", "nodes.private.read", "actions.run.low", "actions.run.medium"],233  "session": { "id": "…", "kind": "cookie", "current": true, "step_up_valid_until": "2026-11-18T21:05:12Z" },234  "csrf_token": "6fJmC0n1x1c0u0S7wq5a8nq3mVbYb1pZ5nq2dX0v9Qk"235}236```237238`permissions` liste les permissions globales effectives (défauts du rôle et octrois sans ressource) ; les octrois239limités à une ressource sont évalués par le serveur à chaque requête. `csrf_token` est absent pour une session240`Bearer`.241242### 3.4 Step-up243244```http245POST /api/v1/auth/stepup/begin246X-MCC-CSRF: <csrf_token>247Origin: https://clustr.spboucher.ai248```249250Réponse : un défi de même forme qu'en 3.1, qui n'accepte que les passkeys de l'utilisateur courant. Puis :251252```http253POST /api/v1/auth/stepup/finish254255{ "challenge_id": "…", "credential": { … } }256```257258Réponse : `{ "authenticated_at": "…", "step_up_valid_until": "…" }` ; le step-up est alors valide 5 minutes.259260### 3.5 Invitation → premier accès261262Le lien reçu est `https://clustr.spboucher.ai/setup#<jeton>`.263264```http265POST /api/v1/invitations/exchange266Content-Type: application/json267268{ "token": "<jeton du fragment>", "client": { "kind": "web" } }269```270271```json272{273  "purpose": "new_account",274  "role": "operator",275  "requires_existing_account": false,276  "profile_required": true,277  "expires_at": "2026-11-18T21:15:00Z",278  "inviter_display_name": "Simon-Pierre"279}280```281282Le jeton est consommé atomiquement. Web : cookie `__Host-mcc_setup` (10 min). Natif : champ `transaction_token`,283à renvoyer dans l'en-tête `X-MCC-Setup-Transaction`. Suite :284285| Étape | Appel | Remarque |286|---|---|---|287| relire la transaction | `GET /invitations/transaction` | |288| choisir identifiant et nom | `POST /invitations/transaction/profile` | seulement si `profile_required` ; les valeurs fixées par l'invitant ne sont pas modifiables |289| créer la passkey | `POST /auth/webauthn/registration/begin` puis `…/finish` | `finish` crée le compte, la passkey, termine l'invitation et ouvre la session (réponse `{ passkey, auth }`) |290| lier à un compte existant | `POST /invitations/transaction/link` | invitation `link` : session **de ce compte** + step-up + confirmation |291| abandonner | `DELETE /invitations/transaction` | l'invitation reste consommée |292293Toute invitation inconnue, expirée, déjà utilisée ou révoquée répond le même `410 invitation_invalid`.294Cinq échecs de vérification de passkey révoquent l'invitation.295296### 3.6 Déconnexion, sessions, appareils297298`POST /auth/logout` révoque la session courante. `GET /me/sessions`, `DELETE /me/sessions/{id}`,299`GET /me/devices`, `DELETE /me/devices/{id}` (révoque l'appareil, ses sessions et son jeton push),300`GET /me/passkeys`, `PATCH`/`DELETE /me/passkeys/{id}` (la dernière passkey ne peut pas être supprimée :301`409 last_passkey`).302303## 4. Actions — exemple complet304305Catalogue : `GET /action-types` (schéma JSON des paramètres, criticité, drapeaux `requires_step_up`,306`requires_justification`, `requires_confirmation`, `requires_approval`, `available`).307Règles de sûreté : [SECURITY.md §8](SECURITY.md#8-sûreté-des-actions).308309```http310POST /api/v1/actions311Content-Type: application/json312Idempotency-Key: e2e-smoke-0000000001313X-MCC-CSRF: <csrf_token>314Origin: https://clustr.spboucher.ai315316{317  "type": "diagnostic.run",318  "target": { "kind": "node", "id": "019a9d00-0000-7000-8000-0000000000a1" },319  "params": { "profile": "basic" }320}321```322323Réponse `201` : l'action, dans l'état `queued` (ou `pending_approval` pour une action `critical`). Champs utiles324pour une action critique : `confirm` (alias de la cible, comparé par le serveur), `justification`,325`override_maintenance`.326327États : `pending_approval → queued → dispatched → running → succeeded | failed | timed_out | cancelled`, ainsi que328`rejected` et `expired` (approbation refusée ou non donnée en 30 min).329330| Suivi | Appel |331|---|---|332| état et chronologie | `GET /actions/{id}` → `{ action, … }` ; `action.result.outcome_unknown` vaut `true` quand la commande a été remise sans qu'un résultat revienne |333| sortie expurgée | `GET /actions/{id}/output?after=<n>&limit=500` → `{ items, next_after, truncated }` (exige aussi `logs.read`) |334| annuler | `POST /actions/{id}/cancel` (le demandeur, ou qui peut lancer cette criticité sur le nœud) |335| approuver / rejeter | `POST /actions/{id}/approve`, `…/reject` (autre personne que le demandeur ; `actions.approve` ; step-up pour approuver) |336| temps réel | événements `action.changed` et `action.output` (§5) |337338Ce parcours (création, exécution par un agent réel, sortie, rejeu idempotent, une seule commande émise) est celui339que vérifie `tests/e2e/local-stack.sh`.340341## 5. Flux d'événements (SSE)342343```http344GET /api/v1/events345Accept: text/event-stream346Last-Event-ID: 4812            (facultatif ; ou ?last_event_id=4812)347```348349Paramètre `topics` : liste de sujets séparés par des virgules (par défaut tous ceux que la session peut lire).350Source : `services/internal/api/events_stream.go`, `services/internal/events/events.go`.351352### 5.1 Trames353354```355retry: 3000356event: hello357data: {"head":4812}358359id: 4813360event: action.changed361data: {"action_id":"…","type":"diagnostic.run","state":"running","target":{"kind":"node","id":"…"},"outcome_unknown":false}362363: ping364```365366- La première trame est toujours `hello` (sans `id`) ; `head` est la dernière séquence connue du serveur.367- `id` est la séquence monotone de `events_outbox` ; `data` est directement la charge utile du sujet.368- Battement `: ping` toutes les 15 s.369- Sans `Last-Event-ID`, le flux commence **au présent** : l'état initial se charge par REST.370- Le serveur ferme le flux après 30 minutes et revérifie la session chaque minute ; le client se reconnecte.371372### 5.2 Reprise et resynchronisation373374Avec `Last-Event-ID: n`, le serveur rejoue tout ce qui suit `n` (par lots de 500). Si `n` a été purgé (rétention375d'une heure) ou vient d'une autre génération de base (`n` supérieur à la tête), il envoie :376377```378id: 5120379event: resync380data: {}381```382383puis continue en direct depuis la tête. Le client doit alors recharger son état par REST. Vérifié par384`TestPublishSinceResumeAndResync` (`services/internal/events/events_test.go`), `TestHTTPEventStream`385(`services/internal/api/identity_http_test.go`) et le test Playwright de redémarrage386(`apps/web/e2e/specs/04-realtime.spec.ts`).387388### 5.3 Sujets et charges utiles réellement émises389390Relevé sur tous les appels à `events.Publish` du dépôt. La colonne « Contrat » dit si la charge émise respecte le391schéma `…Event` du contrat.392393| Sujet | Permission | Émetteur (fichier) | Charge utile émise | Contrat |394|---|---|---|---|---|395| `node.state` | `nodes.read` | ingestion (`ingest/report.go`), au plus une fois par rapport en direct | `{node_id, ts, values{…}, availability{…}}` — `values` : sous-ensemble de métriques par nom (`cpu.usage`, `mem.used`, `disk.used`…) ; une métrique étiquetée y est un objet `{étiquette: valeur}` | **non** : le contrat exige `alias`, `freshness`, `maintenance` et propose `headline` |396| `node.updated` | `nodes.read` | API (`cluster_nodes.go`, `admin_agents.go`), orchestrateur (`actions/store.go`), calendrier (`maintenance/scheduler.go`) | `{node_id, change}` avec `change` ∈ `created`, `updated`, `agent`, `retired` | oui |397| `node.updated` | `nodes.read` | ingestion (`ingest/enroll.go`, `ingest/report.go`) | `{node_id, reason}` avec `reason` ∈ `agent_enrolled`, `inventory` | **non** : `change` (requis) est absent |398| `service.changed` | `services.read` | ingestion (`ingest/report.go`), seulement sur changement réel | `{node_id, service_id, manager, name, state, previous_state, gone}` | **partiel** : pour un service disparu, `state` vaut `gone`, valeur absente de l'énumération `ServiceState` (`online`, `stopped`, `errored`, `unknown`) |399| `service.changed` | `services.read` | API (`cluster_services.go`, modification de `managed` / `public_url`) | `{service_id, node_id, manager, name, state, gone?}` | oui |400| `alert.changed` | `alerts.read` | moteur (`alerts/engine.go`), API (`ops_alerts.go`, `cluster_nodes.go`) | `{alert_id, rule_id, state, severity, summary, suppressed, node_id?, incident_id?}` | oui |401| `incident.changed` | `alerts.read` | API (`ops_alerts.go`) | `{incident_id, state, severity, title}` | oui |402| `action.changed` | `actions.read` | `actions/store.go` (API et orchestrateur) | `{action_id, type, state, target{kind,id}, outcome_unknown, node_id?, requested_by?}` | oui |403| `action.output` | `logs.read` | ingestion (`ingest/commands.go`) | `{action_id, command_id, node_id, lines[{id, stream, data}], truncated}` — un lot de lignes | **non** : le contrat décrit une ligne par événement `{action_id, event_id, ts, stream, data}` |404| `job.changed` | `jobs.read` | `actions/store.go` | `{job_id, template, state, node_id?, progress?}` | oui |405| `maintenance.changed` | `maintenance.read` | API (`ops_maintenance.go`), calendrier (`maintenance/scheduler.go`) | `{change, window_id?, note_id?, occurrence?, node_ids?}` | oui |406| `audit.appended` | `audit.read` | `audit/audit.go`, à chaque entrée | `{seq}` | **non** : le contrat exige `ts`, `action`, `actor_label`, `outcome` |407| `resync` | — | flux | `{}` | **non** : le contrat exige `reason` |408| `hello` | — | flux | `{head}` | absent du contrat |409410`model.changed` figure dans la table des permissions du flux et dans le client web, mais **aucun code ne l'émet** et411il n'est pas dans l'énumération `EventTopic` du contrat.412413Conseil d'intégration tant que ces écarts existent : traiter chaque événement comme un **signal de rechargement**414de la ressource REST concernée, sans se fier aux champs facultatifs de la charge utile.415416## 6. Table des permissions417418Générée depuis `services/internal/api/ops_gen.go` (132 opérations). « toute session » = aucune permission419particulière ; les contrôles par ressource (un nœud précis, un service précis, la criticité d'une action) sont faits420en plus dans les handlers. Chemins relatifs à `/api/v1`.421422| Opération | Méthode | Chemin | Authentification | Permission | Step-up |423|---|---|---|---|---|---|424| `ListActionTypes` | GET | `/action-types` | session | `actions.read` | — |425| `ListActions` | GET | `/actions` | session | `actions.read` | — |426| `CreateAction` | POST | `/actions` | session | `actions.run.low` | — |427| `GetAction` | GET | `/actions/{id}` | session | `actions.read` | — |428| `ApproveAction` | POST | `/actions/{id}/approve` | session | `actions.approve` | oui |429| `CancelAction` | POST | `/actions/{id}/cancel` | session | `actions.read` | — |430| `GetActionOutput` | GET | `/actions/{id}/output` | session | `actions.read` | — |431| `RejectAction` | POST | `/actions/{id}/reject` | session | `actions.approve` | — |432| `ListActivity` | GET | `/activity` | session | `cluster.read` | — |433| `GetAdminStatus` | GET | `/admin/status` | session | `settings.manage` | — |434| `ListAgents` | GET | `/agents` | session | `agents.manage` | — |435| `ListEnrollmentTokens` | GET | `/agents/enrollment-tokens` | session | `agents.manage` | — |436| `CreateEnrollmentToken` | POST | `/agents/enrollment-tokens` | session | `agents.manage` | oui |437| `RevokeEnrollmentToken` | DELETE | `/agents/enrollment-tokens/{id}` | session | `agents.manage` | oui |438| `RevokeAgent` | POST | `/agents/{id}/revoke` | session | `agents.manage` | oui |439| `ListAlertRules` | GET | `/alert-rules` | session | `alerts.read` | — |440| `CreateAlertRule` | POST | `/alert-rules` | session | `alerts.manage` | — |441| `ValidateAlertRule` | POST | `/alert-rules/validate` | session | `alerts.manage` | — |442| `DeleteAlertRule` | DELETE | `/alert-rules/{id}` | session | `alerts.manage` | — |443| `GetAlertRule` | GET | `/alert-rules/{id}` | session | `alerts.read` | — |444| `UpdateAlertRule` | PATCH | `/alert-rules/{id}` | session | `alerts.manage` | — |445| `ListAlerts` | GET | `/alerts` | session | `alerts.read` | — |446| `GetAlert` | GET | `/alerts/{id}` | session | `alerts.read` | — |447| `AcknowledgeAlert` | POST | `/alerts/{id}/acknowledge` | session | `alerts.ack` | — |448| `CommentAlert` | POST | `/alerts/{id}/comments` | session | `alerts.ack` | — |449| `ResolveAlert` | POST | `/alerts/{id}/resolve` | session | `alerts.ack` | — |450| `ListAudit` | GET | `/audit` | session | `audit.read` | — |451| `ExportAudit` | GET | `/audit/export` | session | `audit.export` | oui |452| `VerifyAudit` | GET | `/audit/verify` | session | `audit.read` | — |453| `Logout` | POST | `/auth/logout` | session | *(toute session)* | — |454| `RefreshSession` | POST | `/auth/refresh` | aucune | — | — |455| `BeginStepUp` | POST | `/auth/stepup/begin` | session | *(toute session)* | — |456| `FinishStepUp` | POST | `/auth/stepup/finish` | session | *(toute session)* | — |457| `BeginAuthentication` | POST | `/auth/webauthn/authentication/begin` | aucune | — | — |458| `FinishAuthentication` | POST | `/auth/webauthn/authentication/finish` | aucune | — | — |459| `BeginRegistration` | POST | `/auth/webauthn/registration/begin` | session ou setup | *(toute session)* | oui |460| `FinishRegistration` | POST | `/auth/webauthn/registration/finish` | session ou setup | *(toute session)* | oui |461| `GetClusterOverview` | GET | `/cluster/overview` | session | `cluster.read` | — |462| `GetClusterTrends` | GET | `/cluster/trends` | session | `cluster.read` | — |463| `RevokeDevice` | DELETE | `/devices/{id}` | session | `users.manage` | oui |464| `StreamEvents` | GET | `/events` | session | *(toute session)* | — |465| `GetLiveness` | GET | `/health/live` | aucune | — | — |466| `GetReadiness` | GET | `/health/ready` | aucune | — | — |467| `ListIncidents` | GET | `/incidents` | session | `alerts.read` | — |468| `CreateIncident` | POST | `/incidents` | session | `alerts.manage` | — |469| `GetIncident` | GET | `/incidents/{id}` | session | `alerts.read` | — |470| `UpdateIncident` | PATCH | `/incidents/{id}` | session | `alerts.manage` | — |471| `CommentIncident` | POST | `/incidents/{id}/comments` | session | `alerts.ack` | — |472| `ListInvitations` | GET | `/invitations` | session | `invitations.manage` | — |473| `CreateInvitation` | POST | `/invitations` | session | `invitations.manage` | oui |474| `ExchangeInvitation` | POST | `/invitations/exchange` | aucune | — | — |475| `AbandonInvitationTransaction` | DELETE | `/invitations/transaction` | transaction setup | — | — |476| `GetInvitationTransaction` | GET | `/invitations/transaction` | transaction setup | — | — |477| `LinkInvitationToAccount` | POST | `/invitations/transaction/link` | session et setup | *(toute session)* | oui |478| `SetInvitationProfile` | POST | `/invitations/transaction/profile` | transaction setup | — | — |479| `RevokeInvitation` | DELETE | `/invitations/{id}` | session | `invitations.manage` | oui |480| `ListJobSchedules` | GET | `/job-schedules` | session | `jobs.read` | — |481| `CreateJobSchedule` | POST | `/job-schedules` | session | `jobs.submit` | — |482| `DeleteJobSchedule` | DELETE | `/job-schedules/{id}` | session | `jobs.submit` | — |483| `UpdateJobSchedule` | PATCH | `/job-schedules/{id}` | session | `jobs.submit` | — |484| `ListJobTemplates` | GET | `/job-templates` | session | `jobs.read` | — |485| `ListJobs` | GET | `/jobs` | session | `jobs.read` | — |486| `CreateJob` | POST | `/jobs` | session | `jobs.submit` | — |487| `GetJob` | GET | `/jobs/{id}` | session | `jobs.read` | — |488| `CancelJob` | POST | `/jobs/{id}/cancel` | session | `jobs.submit` | — |489| `ExportMaintenanceCalendar` | GET | `/maintenance/calendar.ics` | session | `maintenance.read` | — |490| `ListMaintenanceNotes` | GET | `/maintenance/notes` | session | `maintenance.read` | — |491| `CreateMaintenanceNote` | POST | `/maintenance/notes` | session | `maintenance.write` | — |492| `DeleteMaintenanceNote` | DELETE | `/maintenance/notes/{id}` | session | `maintenance.write` | — |493| `UpdateMaintenanceNote` | PATCH | `/maintenance/notes/{id}` | session | `maintenance.write` | — |494| `ListMaintenanceWindows` | GET | `/maintenance/windows` | session | `maintenance.read` | — |495| `CreateMaintenanceWindow` | POST | `/maintenance/windows` | session | `maintenance.write` | — |496| `CancelMaintenanceWindow` | DELETE | `/maintenance/windows/{id}` | session | `maintenance.write` | — |497| `GetMaintenanceWindow` | GET | `/maintenance/windows/{id}` | session | `maintenance.read` | — |498| `UpdateMaintenanceWindow` | PATCH | `/maintenance/windows/{id}` | session | `maintenance.write` | — |499| `CompleteMaintenanceWindow` | POST | `/maintenance/windows/{id}/complete` | session | `maintenance.write` | — |500| `GetMe` | GET | `/me` | session | *(toute session)* | — |501| `UpdateMe` | PATCH | `/me` | session | *(toute session)* | — |502| `ListMyDashboards` | GET | `/me/dashboards` | session | *(toute session)* | — |503| `DeleteMyDashboard` | DELETE | `/me/dashboards/{name}` | session | *(toute session)* | — |504| `PutMyDashboard` | PUT | `/me/dashboards/{name}` | session | *(toute session)* | — |505| `ListMyDevices` | GET | `/me/devices` | session | *(toute session)* | — |506| `PutMyPushToken` | PUT | `/me/devices/current/push-token` | session | *(toute session)* | — |507| `RevokeMyDevice` | DELETE | `/me/devices/{id}` | session | *(toute session)* | — |508| `ListMyPasskeys` | GET | `/me/passkeys` | session | *(toute session)* | — |509| `DeleteMyPasskey` | DELETE | `/me/passkeys/{id}` | session | *(toute session)* | oui |510| `UpdateMyPasskey` | PATCH | `/me/passkeys/{id}` | session | *(toute session)* | — |511| `ListMySessions` | GET | `/me/sessions` | session | *(toute session)* | — |512| `RevokeMySession` | DELETE | `/me/sessions/{id}` | session | *(toute session)* | — |513| `GetMetricCatalog` | GET | `/metrics/catalog` | session | `nodes.read` | — |514| `CompareMetrics` | GET | `/metrics/compare` | session | `nodes.read` | — |515| `ListInferenceServers` | GET | `/models` | session | `models.read` | — |516| `GetInferenceServer` | GET | `/models/{id}` | session | `models.read` | — |517| `ListNetworkInterfaces` | GET | `/network/interfaces` | session | `nodes.read` | — |518| `GetNetworkTopology` | GET | `/network/topology` | session | `cluster.read` | — |519| `ListNodes` | GET | `/nodes` | session | `nodes.read` | — |520| `CreateNode` | POST | `/nodes` | session | `nodes.write` | — |521| `RetireNode` | DELETE | `/nodes/{id}` | session | `nodes.write` | oui |522| `GetNode` | GET | `/nodes/{id}` | session | `nodes.read` | — |523| `UpdateNode` | PATCH | `/nodes/{id}` | session | `nodes.write` | — |524| `GetNodeHealthHistory` | GET | `/nodes/{id}/health-history` | session | `nodes.read` | — |525| `GetNodeMetrics` | GET | `/nodes/{id}/metrics` | session | `nodes.read` | — |526| `ListNodeProcesses` | GET | `/nodes/{id}/processes` | session | `nodes.read` | — |527| `ListNodeServices` | GET | `/nodes/{id}/services` | session | `services.read` | — |528| `GetPermissionCatalog` | GET | `/permissions` | session | *(toute session)* | — |529| `ListPolicyGrants` | GET | `/policy-grants` | session | `users.manage` | — |530| `CreatePolicyGrant` | POST | `/policy-grants` | session | `users.manage` | oui |531| `DeletePolicyGrant` | DELETE | `/policy-grants/{id}` | session | `users.manage` | oui |532| `Search` | GET | `/search` | session | *(toute session)* | — |533| `ListServices` | GET | `/services` | session | `services.read` | — |534| `GetService` | GET | `/services/{id}` | session | `services.read` | — |535| `UpdateService` | PATCH | `/services/{id}` | session | `settings.manage` | — |536| `GetServiceHistory` | GET | `/services/{id}/history` | session | `services.read` | — |537| `RevokeSession` | DELETE | `/sessions/{id}` | session | `users.manage` | oui |538| `ListSettings` | GET | `/settings` | session | `settings.manage` | — |539| `PutSetting` | PUT | `/settings/{key}` | session | `settings.manage` | oui |540| `ListSilences` | GET | `/silences` | session | `alerts.read` | — |541| `CreateSilence` | POST | `/silences` | session | `alerts.manage` | — |542| `DeleteSilence` | DELETE | `/silences/{id}` | session | `alerts.manage` | — |543| `ListBackups` | GET | `/storage/backups` | session | `cluster.read` | — |544| `ListNasTargets` | GET | `/storage/nas` | session | `cluster.read` | — |545| `CreateNasTarget` | POST | `/storage/nas` | session | `settings.manage` | — |546| `DeleteNasTarget` | DELETE | `/storage/nas/{id}` | session | `settings.manage` | — |547| `ListVolumes` | GET | `/storage/volumes` | session | `nodes.read` | — |548| `ListUsers` | GET | `/users` | session | `users.manage` | — |549| `GetUser` | GET | `/users/{id}` | session | `users.manage` | — |550| `UpdateUser` | PATCH | `/users/{id}` | session | `users.manage` | oui |551| `ListUserDevices` | GET | `/users/{id}/devices` | session | `users.manage` | — |552| `ListUserPasskeys` | GET | `/users/{id}/passkeys` | session | `users.manage` | — |553| `RevokeUserPasskey` | DELETE | `/users/{id}/passkeys/{passkeyId}` | session | `users.manage` | oui |554| `ListUserSessions` | GET | `/users/{id}/sessions` | session | `users.manage` | — |555| `GetVersion` | GET | `/version` | aucune | — | — |556557Compléments non visibles dans la table :558559- `CreateAction` : la table porte `actions.run.low` comme plancher ; le handler exige `actions.run.<criticité>` du560  type demandé, sur le nœud et la cible précis, plus `logs.read` pour `service.logs.tail`, plus le step-up pour561  `high` et `critical`.562- `GetActionOutput` : `actions.read` et `logs.read` sur le nœud.563- `CancelAction` : le demandeur, sinon `actions.run.<criticité>` sur le nœud.564- `PutSetting` pour `orchestrator.frozen` : owner seulement.565- `BeginRegistration` / `FinishRegistration` : le step-up ne s'applique qu'à une session (ajout d'une passkey),566  pas à une transaction d'invitation.567- Champs privés des nœuds (adresses, numéro de série, UUID matériel, cibles NAS) : `nodes.private.read`, par nœud.568- `GET /permissions` renvoie le catalogue des 26 permissions et les défauts par rôle.569570## 7. Limites de débit telles qu'implémentées571572En mémoire, par processus (remises à zéro au redémarrage). Dépassement : `429 rate_limited` + `Retry-After`.573574| Portée | Limite | Clé | Source |575|---|---|---|---|576| Toutes les opérations publiques et de transaction d'invitation, **confondues** (`health/*`, `version`, `authentication/begin|finish`, `refresh`, `invitations/exchange`, `invitations/transaction*`) | 30 par minute, rafale de 15 | adresse IP cliente | `api/server.go` (`authLimiter`) |577| Toute requête authentifiée | 900 par minute, rafale de 300 | session | `api/server.go` (`userLimiter`) |578| `POST /actions` | 30 par minute, rafale de 30 | utilisateur | `api/ops_actions.go` (`actionLimiter`) |579| `POST /agent/v1/enroll` (relais) | 20 par minute, rafale de 10 | adresse IP cliente | `api/agent_proxy.go` |580581Non limitées par adresse : `registration/begin|finish` appelées avec une transaction d'invitation (mode « session582ou setup ») ; elles ne sont bornées que par les 5 échecs par invitation. L'adresse cliente est prise dans583`X-Forwarded-For` uniquement quand le pair est un proxy de confiance (`MCC_TRUSTED_PROXIES`).584585## 8. Écarts connus entre contrat et implémentation586587Chaque ligne a été vérifiée dans le code au commit `45f0d03`.588589| # | Sujet | Contrat (`openapi.yaml`) | Implémentation | Effet |590|---|---|---|---|---|591| 1 | Événement `node.state` | `{node_id, alias, freshness, maintenance, observed_at?, headline?}` | `{node_id, ts, values, availability}` (`ingest/report.go` : `nodeStateEvent`) | le client web applique `freshness` et `maintenance` de l'événement au cache des nœuds (`apps/web/src/shell/realtime.tsx` : `patchNodeState`) : avec la charge réelle ces champs sont indéfinis jusqu'au rechargement REST suivant. Le test Playwright correspondant injecte la forme du contrat, pas celle de l'ingestion ; l'effet à l'écran n'a pas été observé |592| 2 | Événement `action.output` | une ligne : `{action_id, event_id, ts, stream, data}` | un lot : `{action_id, command_id, node_id, lines[], truncated}` (`ingest/commands.go`) | les vues web lisent `event_id` et `data` (`ActionView.tsx`, `useActionOutput.ts`) : la ligne poussée est inexploitable ; l'affichage repose sur l'interrogation périodique de `GET /actions/{id}/output` (toutes les 2,5 s) |593| 3 | Événement `audit.appended` | `seq, ts, action, actor_label, outcome` requis | `{seq}` | le web ne s'en sert que comme signal |594| 4 | Événement `node.updated` émis par l'ingestion | `change` requis | `reason` (`agent_enrolled`, `inventory`) | signal seulement côté web ; un client typé strict peut rejeter la trame |595| 5 | Événement `resync` | `reason` requis | `{}` | idem |596| 5 bis | Événement `service.changed` émis par l'ingestion pour un service disparu | `state` ∈ `online`, `stopped`, `errored`, `unknown` | `state: "gone"` avec `gone: true` (`ingest/report.go`) | signal seulement côté web ; un client typé strict peut rejeter la trame |597| 6 | Trame `hello`, sujet `model.changed` | absents de l'énumération `EventTopic` | `hello` émis à l'ouverture ; `model.changed` déclaré mais jamais émis | à ignorer côté client |598| 7 | Codes d'erreur d'authentification | `401 session_expired`, `401 webauthn_failed`, `401 refresh_reuse_detected`, `410 gone` | `401 unauthenticated`, `401 credential_rejected` / `400 challenge_invalid`, `401 refresh_rejected`, `410 invitation_invalid` / `410 setup_transaction_invalid` | le web teste `code === "webauthn_failed"` (`SignIn.tsx`, `Setup.tsx`) : le message « passkey refusée » spécifique n'est jamais choisi ; les statuts HTTP, eux, concordent |599| 8 | Limites de débit | 10/min par IP (cérémonies), 5/min par IP (échange d'invitation), 30/min par IP (rafraîchissement), 10/min par session (step-up) | voir §7 : un seau commun de 30/min (rafale 15) par IP pour le public, 900/min par session | plus permissif que le contrat sur certaines opérations, plus strict en cumul (les sondes de santé consomment le même seau) |600| 9 | Champs non effaçables par `PATCH` | « champs optionnels omis » : pas de moyen d'exprimer l'effacement | `PATCH /nodes/{id}` : `site`, `role`, `environment` exigent 1 à 64 caractères ; `PATCH /alert-rules/{id}` : `clear_threshold` ne peut pas être retiré une fois posé ; `PATCH /incidents/{id}` : `owner_id` ne peut pas être désassigné. Exception explicite : `public_url` d'un service, effacée par la chaîne vide | pour effacer : recréer la ressource, ou convention à ajouter au contrat |601| 10 | Réglages `retention.*_days`, `alerts.default_*` | réglages modifiables (`PUT /settings/{key}`) | valeurs stockées mais **lues par aucun service** : l'ingestion applique `MCC_RETAIN_*`, la création de règle applique 300 s / 120 s / `warning` codés en dur (`ops_alerts.go`) | modifier ces réglages n'a aucun effet. `retention.action_events_days`, lui, est lu par le ménage mais n'est pas dans la liste modifiable |602| 11 | `limit` hors bornes | 1 à 200 | les listes « cluster » répondent `400` (`clLimit`), les listes « opérations » ramènent silencieusement la valeur dans les bornes (`pageLimit`) | comportement incohérent entre familles d'opérations |603| 12 | Types `model.server.start` / `model.server.stop` | `available: true` au catalogue | aucun agent v1 ne les implémente (`agent/policy/policy.go` : `Implemented`) | toujours refusés par la pré-vérification de capacité |604| 13 | Exigences par type d'action | `DESIGN-BRIEF.md` §4 les présente par type | dérivées de la seule criticité (`actions/catalog.go`) | `service.stop` (`high`) demande un step-up mais ni confirmation ni justification |605| 14 | Version des services | — | `make build` n'estampille que `control-api` ; `/admin/status` affiche `0.1.0-dev` (ingestion) et `dev` (orchestrateur) | cosmétique |606607Sont alignés (anciens points de `INTEGRATION-TODO.md`, vérifiés) : valeurs étiquetées imbriquées lues par l'API et le608moteur d'alertes, clés `cpu_percent` / `rss_bytes` de la charge de l'agent, clé `fingerprint` de `pki.ca`,609horodatages en UTC, relais vers `MCC_INGEST_SIGNED_LISTEN`, clé de réglage `orchestrator.frozen`.610
Files main
Menu

Theme