Guide de l'API — MacLustr Command Center
Guide humain de l'API publique servie par control-api sous /api/v1. La référence formelle est le contrat
packages/api-contracts/openapi.yaml (OpenAPI 3.1, 132 opérations) ; ce guide décrit ce que le serveur fait au
commit 45f0d03 et liste en §8 les points où l'implémentation
s'écarte du contrat. Le protocole des agents (/agent/v1) est décrit dans AGENT-PROTOCOL.md.
Les valeurs des exemples (identifiants, jetons, dates) sont illustratives.
Documents liés : SECURITY.md · ARCHITECTURE.md ·
packages/api-contracts/README.md.
1. Bases
| Production | https://clustr.spboucher.ai/api/v1 |
| Développement | http://localhost:8730/api/v1 |
| Format | JSON (application/json), UTF-8 ; corps de requête ≤ 1 Mio |
| Horodatages | RFC 3339 en UTC (…Z) |
| Identifiants | UUID v7 |
| Champs optionnels | omis, jamais null |
| 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 |
| Cache | Cache-Control: no-store sur toute réponse d'API |
| Opérations sans session | GET /health/live, GET /health/ready, GET /version, POST /auth/webauthn/authentication/begin, …/finish, POST /auth/refresh, POST /invitations/exchange |
Le serveur est généré depuis le contrat (services/internal/api/gen.go) ; la politique de sécurité de chaque
opération vient de la table générée services/internal/api/ops_gen.go et est appliquée par core.admit
(services/internal/api/server.go) avant tout handler.
2. Conventions
2.1 Erreurs
Toute réponse non 2xx a la même enveloppe :
{
"error": {
"code": "step_up_required",
"message": "A recent passkey verification is required.",
"details": {},
"correlation_id": "019a9c50-0000-7000-8000-00000000cc01"
}
}code est stable et destiné aux programmes ; message est en anglais et destiné aux journaux ; details est
facultatif (permission, check, action_id, fields, capability…). Une erreur inattendue devient un
500 internal opaque : le détail est journalisé côté serveur avec l'identifiant de corrélation.
Codes réellement émis par le serveur :
| HTTP | code |
Sens | Source |
|---|---|---|---|
| 400 | validation_failed |
corps, paramètre ou en-tête mal formé | httpx.Validation |
| 400 | challenge_invalid |
défi WebAuthn expiré ou déjà utilisé | identity.ErrChallenge |
| 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 |
| 401 | credential_rejected |
passkey refusée (signature, origine, UV, compteur, compte désactivé) | identity.ErrCredential |
| 401 | refresh_rejected |
rafraîchissement impossible (jeton inconnu, expiré, déjà tourné) | identity.ErrRefresh |
| 403 | forbidden |
permission manquante ou deny applicable ; details.permission |
httpx.ErrForbidden |
| 403 | step_up_required |
cérémonie passkey de moins de 5 min requise | httpx.ErrStepUp |
| 403 | csrf_failed |
X-MCC-CSRF absent ou invalide, ou Origin différent |
httpx.ErrCSRF |
| 403 | wrong_account |
invitation link ouverte avec un autre compte |
identity.ErrWrongAccount |
| 404 | not_found |
ressource inconnue ou cachée à l'appelant | httpx.ErrNotFound |
| 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 |
| 410 | invitation_invalid |
invitation inconnue, expirée, consommée ou révoquée (réponse unique) | identity.ErrInvitation |
| 410 | setup_transaction_invalid |
transaction d'invitation expirée ou absente | identity.ErrSetupTx |
| 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 |
| 429 | rate_limited |
trop de requêtes ; en-tête Retry-After (secondes) |
httpx.ErrRateLimited |
| 500 | internal |
erreur inattendue | httpx.WriteError |
| 501 | not_implemented |
opération du contrat sans handler (aucune au commit décrit) | unimplemented_gen.go |
| 503 | unavailable |
dépendance indisponible (base, ingestion, web) | httpx.ErrUnavailable |
| 503 | orchestrator_frozen |
gel d'urgence actif | actions.ErrFrozen |
Un client doit tolérer des codes inconnus et se fier d'abord au statut HTTP.
2.2 Pagination
Curseur opaque : paramètres limit (défaut 50, maximum 200) et cursor ; réponses { "items": […], "next_cursor": "…" }.
L'absence de next_cursor signale la dernière page. La sortie d'une action utilise un curseur numérique propre
(after, next_after, truncated).
2.3 Idempotence
POST /actions et POST /jobs exigent l'en-tête Idempotency-Key (8 à 128 caractères pour les actions).
| Cas | Réponse |
|---|---|
| nouvelle demande | 201 + ressource |
| même clé, même corps (même utilisateur) | 200 + la ressource d'origine, rien n'est créé |
| même clé, corps différent | 409 idempotency_conflict |
L'empreinte couvre type, cible, params, confirm, justification et override_maintenance
(actions.HashRequest). L'idempotence protège la demande ; l'unicité de la commande envoyée à l'agent est une
garantie distincte (ADR 0010).
2.4 CSRF
Pour toute méthode autre que GET, HEAD, OPTIONS :
- session par cookie : en-tête
Originégal à l'origine publique et en-têteX-MCC-CSRF(valeurcsrf_tokenrenvoyée par la connexion et parGET /me) ; - transaction d'invitation par cookie :
Originégal à l'origine publique ; - jeton
Bearerou opération publique : pas de jeton CSRF ; si unOriginest envoyé, il doit être l'origine publique.
Échec : 403 csrf_failed.
2.5 Step-up
Certaines opérations exigent que la session porte une cérémonie passkey de moins de 5 minutes
(session.step_up_valid_until). Sinon : 403 step_up_required. Le client enchaîne alors
POST /auth/stepup/begin → cérémonie → POST /auth/stepup/finish, puis rejoue la requête d'origine. Opérations
concernées : colonne « Step-up » du §6, plus POST /actions pour les types de criticité
high et critical (vérifié dans le handler, donc absent de la table).
2.6 Fraîcheur et disponibilité
Les ressources issues de la télémétrie portent observed_at et freshness, calculée par le serveur :
freshness |
Âge du dernier rapport |
|---|---|
fresh |
< 30 s |
stale |
30 s à 120 s |
offline |
> 120 s, ou jamais vu |
Une valeur qui ne peut pas être mesurée est absente et son état est donné par une Availability :
available, unavailable (collecte en échec ce tour-ci), unsupported (non mesurable sur ce matériel),
permission_denied (mesurable, mais pas avec les droits de l'agent), stale, offline. Jamais de zéro inventé.
Exemple (extrait de GET /nodes/{id}, forme vérifiée par tests/e2e/local-stack.sh) :
{
"latest": {
"cpu.usage": { "availability": "available", "value": 27.3 },
"thermal.temp": { "availability": "unsupported" }
}
}Les séries (GET /nodes/{id}/metrics) sont des tableaux de points [ts_ms, avg, min, max] ; une métrique
étiquetée (interface réseau, volume) donne une série par étiquette (metric, label, points).
3. Authentification
Le seul moyen d'authentification est la passkey (WebAuthn). Politique : SECURITY.md §3–§5.
3.1 Connexion (sans nom d'utilisateur)
POST /api/v1/auth/webauthn/authentication/begin{
"challenge_id": "019a9c1e-7b10-7c3a-9d54-2f6f1f0f3a11",
"expires_at": "2026-11-18T21:05:00Z",
"public_key": {
"challenge": "3q2-7wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"rpId": "clustr.spboucher.ai",
"timeout": 300000,
"userVerification": "required"
}
}Le client passe public_key à l'API de la plateforme (navigator.credentials.get, ASAuthorization…), puis :
POST /api/v1/auth/webauthn/authentication/finish
Content-Type: application/json
Origin: https://clustr.spboucher.ai
{
"challenge_id": "019a9c1e-7b10-7c3a-9d54-2f6f1f0f3a11",
"credential": { "id": "…", "rawId": "…", "type": "public-key",
"response": { "clientDataJSON": "…", "authenticatorData": "…", "signature": "…", "userHandle": "…" } },
"client": { "kind": "web", "label": "Safari · Mac" }
}Réponse 200 pour un client web (client.kind = "web") :
Set-Cookie: __Host-mcc_session=<opaque>; Path=/; HttpOnly; Secure; SameSite=Strict
Set-Cookie: __Host-mcc_device=<uuid>; Path=/; Max-Age=…; HttpOnly; Secure; SameSite=Strict{
"user": { "id": "019a9b00-1111-7aaa-8bbb-000000000001", "handle": "spb", "display_name": "Simon-Pierre",
"role": "owner", "locale": "fr", "disabled": false, "created_at": "2026-11-18T20:40:00Z" },
"session": { "id": "019a9c1e-9000-7000-8000-00000000a001", "kind": "cookie", "current": true,
"device_id": "019a9c1e-9000-7000-8000-00000000d001",
"authenticated_at": "2026-11-18T21:00:12Z", "step_up_valid_until": "2026-11-18T21:05:12Z",
"idle_expires_at": "2026-11-18T21:30:12Z", "absolute_expires_at": "2026-11-19T09:00:12Z" },
"device_id": "019a9c1e-9000-7000-8000-00000000d001",
"csrf_token": "6fJmC0n1x1c0u0S7wq5a8nq3mVbYb1pZ5nq2dX0v9Qk"
}Pour un client natif ("kind": "macos" ou "ios"), aucun cookie : la réponse contient à la place
access_token, access_expires_at, refresh_token, refresh_expires_at. Le client renvoie ensuite
Authorization: Bearer <access_token> et conserve device_id pour le représenter dans client.device_id.
Le défi est consommé dès finish, quel que soit le résultat : un échec impose de recommencer par begin.
3.2 Rafraîchissement (clients natifs)
POST /api/v1/auth/refresh
Content-Type: application/json
{ "refresh_token": "<jeton courant>" }Réponse : nouveau couple access_token / refresh_token ; l'ancien jeton de rafraîchissement est consommé.
Présenter de nouveau un jeton déjà tourné révoque la session (audit session.refresh_reuse_detected) et répond
401 refresh_rejected.
3.3 Compte courant et jeton CSRF
GET /api/v1/me{
"user": { "id": "…", "handle": "spb", "display_name": "Simon-Pierre", "role": "owner", "locale": "fr",
"disabled": false, "created_at": "2026-11-18T20:40:00Z" },
"permissions": ["cluster.read", "nodes.read", "nodes.private.read", "actions.run.low", "actions.run.medium"],
"session": { "id": "…", "kind": "cookie", "current": true, "step_up_valid_until": "2026-11-18T21:05:12Z" },
"csrf_token": "6fJmC0n1x1c0u0S7wq5a8nq3mVbYb1pZ5nq2dX0v9Qk"
}permissions liste les permissions globales effectives (défauts du rôle et octrois sans ressource) ; les octrois
limités à une ressource sont évalués par le serveur à chaque requête. csrf_token est absent pour une session
Bearer.
3.4 Step-up
POST /api/v1/auth/stepup/begin
X-MCC-CSRF: <csrf_token>
Origin: https://clustr.spboucher.aiRéponse : un défi de même forme qu'en 3.1, qui n'accepte que les passkeys de l'utilisateur courant. Puis :
POST /api/v1/auth/stepup/finish
{ "challenge_id": "…", "credential": { … } }Réponse : { "authenticated_at": "…", "step_up_valid_until": "…" } ; le step-up est alors valide 5 minutes.
3.5 Invitation → premier accès
Le lien reçu est https://clustr.spboucher.ai/setup#<jeton>.
POST /api/v1/invitations/exchange
Content-Type: application/json
{ "token": "<jeton du fragment>", "client": { "kind": "web" } }{
"purpose": "new_account",
"role": "operator",
"requires_existing_account": false,
"profile_required": true,
"expires_at": "2026-11-18T21:15:00Z",
"inviter_display_name": "Simon-Pierre"
}Le jeton est consommé atomiquement. Web : cookie __Host-mcc_setup (10 min). Natif : champ transaction_token,
à renvoyer dans l'en-tête X-MCC-Setup-Transaction. Suite :
| Étape | Appel | Remarque |
|---|---|---|
| relire la transaction | GET /invitations/transaction |
|
| choisir identifiant et nom | POST /invitations/transaction/profile |
seulement si profile_required ; les valeurs fixées par l'invitant ne sont pas modifiables |
| 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 }) |
| lier à un compte existant | POST /invitations/transaction/link |
invitation link : session de ce compte + step-up + confirmation |
| abandonner | DELETE /invitations/transaction |
l'invitation reste consommée |
Toute invitation inconnue, expirée, déjà utilisée ou révoquée répond le même 410 invitation_invalid.
Cinq échecs de vérification de passkey révoquent l'invitation.
3.6 Déconnexion, sessions, appareils
POST /auth/logout révoque la session courante. GET /me/sessions, DELETE /me/sessions/{id},
GET /me/devices, DELETE /me/devices/{id} (révoque l'appareil, ses sessions et son jeton push),
GET /me/passkeys, PATCH/DELETE /me/passkeys/{id} (la dernière passkey ne peut pas être supprimée :
409 last_passkey).
4. Actions — exemple complet
Catalogue : GET /action-types (schéma JSON des paramètres, criticité, drapeaux requires_step_up,
requires_justification, requires_confirmation, requires_approval, available).
Règles de sûreté : SECURITY.md §8.
POST /api/v1/actions
Content-Type: application/json
Idempotency-Key: e2e-smoke-0000000001
X-MCC-CSRF: <csrf_token>
Origin: https://clustr.spboucher.ai
{
"type": "diagnostic.run",
"target": { "kind": "node", "id": "019a9d00-0000-7000-8000-0000000000a1" },
"params": { "profile": "basic" }
}Réponse 201 : l'action, dans l'état queued (ou pending_approval pour une action critical). Champs utiles
pour une action critique : confirm (alias de la cible, comparé par le serveur), justification,
override_maintenance.
États : pending_approval → queued → dispatched → running → succeeded | failed | timed_out | cancelled, ainsi que
rejected et expired (approbation refusée ou non donnée en 30 min).
| Suivi | Appel |
|---|---|
| é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 |
| sortie expurgée | GET /actions/{id}/output?after=<n>&limit=500 → { items, next_after, truncated } (exige aussi logs.read) |
| annuler | POST /actions/{id}/cancel (le demandeur, ou qui peut lancer cette criticité sur le nœud) |
| approuver / rejeter | POST /actions/{id}/approve, …/reject (autre personne que le demandeur ; actions.approve ; step-up pour approuver) |
| temps réel | événements action.changed et action.output (§5) |
Ce parcours (création, exécution par un agent réel, sortie, rejeu idempotent, une seule commande émise) est celui
que vérifie tests/e2e/local-stack.sh.
5. Flux d'événements (SSE)
GET /api/v1/events
Accept: text/event-stream
Last-Event-ID: 4812 (facultatif ; ou ?last_event_id=4812)Paramètre topics : liste de sujets séparés par des virgules (par défaut tous ceux que la session peut lire).
Source : services/internal/api/events_stream.go, services/internal/events/events.go.
5.1 Trames
retry: 3000
event: hello
data: {"head":4812}
id: 4813
event: action.changed
data: {"action_id":"…","type":"diagnostic.run","state":"running","target":{"kind":"node","id":"…"},"outcome_unknown":false}
: ping- La première trame est toujours
hello(sansid) ;headest la dernière séquence connue du serveur. idest la séquence monotone deevents_outbox;dataest directement la charge utile du sujet.- Battement
: pingtoutes les 15 s. - Sans
Last-Event-ID, le flux commence au présent : l'état initial se charge par REST. - Le serveur ferme le flux après 30 minutes et revérifie la session chaque minute ; le client se reconnecte.
5.2 Reprise et resynchronisation
Avec Last-Event-ID: n, le serveur rejoue tout ce qui suit n (par lots de 500). Si n a été purgé (rétention
d'une heure) ou vient d'une autre génération de base (n supérieur à la tête), il envoie :
id: 5120
event: resync
data: {}puis continue en direct depuis la tête. Le client doit alors recharger son état par REST. Vérifié par
TestPublishSinceResumeAndResync (services/internal/events/events_test.go), TestHTTPEventStream
(services/internal/api/identity_http_test.go) et le test Playwright de redémarrage
(apps/web/e2e/specs/04-realtime.spec.ts).
5.3 Sujets et charges utiles réellement émises
Relevé sur tous les appels à events.Publish du dépôt. La colonne « Contrat » dit si la charge émise respecte le
schéma …Event du contrat.
| Sujet | Permission | Émetteur (fichier) | Charge utile émise | Contrat |
|---|---|---|---|---|
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 |
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 |
node.updated |
nodes.read |
ingestion (ingest/enroll.go, ingest/report.go) |
{node_id, reason} avec reason ∈ agent_enrolled, inventory |
non : change (requis) est absent |
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) |
service.changed |
services.read |
API (cluster_services.go, modification de managed / public_url) |
{service_id, node_id, manager, name, state, gone?} |
oui |
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 |
incident.changed |
alerts.read |
API (ops_alerts.go) |
{incident_id, state, severity, title} |
oui |
action.changed |
actions.read |
actions/store.go (API et orchestrateur) |
{action_id, type, state, target{kind,id}, outcome_unknown, node_id?, requested_by?} |
oui |
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} |
job.changed |
jobs.read |
actions/store.go |
{job_id, template, state, node_id?, progress?} |
oui |
maintenance.changed |
maintenance.read |
API (ops_maintenance.go), calendrier (maintenance/scheduler.go) |
{change, window_id?, note_id?, occurrence?, node_ids?} |
oui |
audit.appended |
audit.read |
audit/audit.go, à chaque entrée |
{seq} |
non : le contrat exige ts, action, actor_label, outcome |
resync |
— | flux | {} |
non : le contrat exige reason |
hello |
— | flux | {head} |
absent du contrat |
model.changed figure dans la table des permissions du flux et dans le client web, mais aucun code ne l'émet et
il n'est pas dans l'énumération EventTopic du contrat.
Conseil d'intégration tant que ces écarts existent : traiter chaque événement comme un signal de rechargement de la ressource REST concernée, sans se fier aux champs facultatifs de la charge utile.
6. Table des permissions
Générée depuis services/internal/api/ops_gen.go (132 opérations). « toute session » = aucune permission
particulière ; les contrôles par ressource (un nœud précis, un service précis, la criticité d'une action) sont faits
en plus dans les handlers. Chemins relatifs à /api/v1.
| Opération | Méthode | Chemin | Authentification | Permission | Step-up |
|---|---|---|---|---|---|
ListActionTypes |
GET | /action-types |
session | actions.read |
— |
ListActions |
GET | /actions |
session | actions.read |
— |
CreateAction |
POST | /actions |
session | actions.run.low |
— |
GetAction |
GET | /actions/{id} |
session | actions.read |
— |
ApproveAction |
POST | /actions/{id}/approve |
session | actions.approve |
oui |
CancelAction |
POST | /actions/{id}/cancel |
session | actions.read |
— |
GetActionOutput |
GET | /actions/{id}/output |
session | actions.read |
— |
RejectAction |
POST | /actions/{id}/reject |
session | actions.approve |
— |
ListActivity |
GET | /activity |
session | cluster.read |
— |
GetAdminStatus |
GET | /admin/status |
session | settings.manage |
— |
ListAgents |
GET | /agents |
session | agents.manage |
— |
ListEnrollmentTokens |
GET | /agents/enrollment-tokens |
session | agents.manage |
— |
CreateEnrollmentToken |
POST | /agents/enrollment-tokens |
session | agents.manage |
oui |
RevokeEnrollmentToken |
DELETE | /agents/enrollment-tokens/{id} |
session | agents.manage |
oui |
RevokeAgent |
POST | /agents/{id}/revoke |
session | agents.manage |
oui |
ListAlertRules |
GET | /alert-rules |
session | alerts.read |
— |
CreateAlertRule |
POST | /alert-rules |
session | alerts.manage |
— |
ValidateAlertRule |
POST | /alert-rules/validate |
session | alerts.manage |
— |
DeleteAlertRule |
DELETE | /alert-rules/{id} |
session | alerts.manage |
— |
GetAlertRule |
GET | /alert-rules/{id} |
session | alerts.read |
— |
UpdateAlertRule |
PATCH | /alert-rules/{id} |
session | alerts.manage |
— |
ListAlerts |
GET | /alerts |
session | alerts.read |
— |
GetAlert |
GET | /alerts/{id} |
session | alerts.read |
— |
AcknowledgeAlert |
POST | /alerts/{id}/acknowledge |
session | alerts.ack |
— |
CommentAlert |
POST | /alerts/{id}/comments |
session | alerts.ack |
— |
ResolveAlert |
POST | /alerts/{id}/resolve |
session | alerts.ack |
— |
ListAudit |
GET | /audit |
session | audit.read |
— |
ExportAudit |
GET | /audit/export |
session | audit.export |
oui |
VerifyAudit |
GET | /audit/verify |
session | audit.read |
— |
Logout |
POST | /auth/logout |
session | (toute session) | — |
RefreshSession |
POST | /auth/refresh |
aucune | — | — |
BeginStepUp |
POST | /auth/stepup/begin |
session | (toute session) | — |
FinishStepUp |
POST | /auth/stepup/finish |
session | (toute session) | — |
BeginAuthentication |
POST | /auth/webauthn/authentication/begin |
aucune | — | — |
FinishAuthentication |
POST | /auth/webauthn/authentication/finish |
aucune | — | — |
BeginRegistration |
POST | /auth/webauthn/registration/begin |
session ou setup | (toute session) | oui |
FinishRegistration |
POST | /auth/webauthn/registration/finish |
session ou setup | (toute session) | oui |
GetClusterOverview |
GET | /cluster/overview |
session | cluster.read |
— |
GetClusterTrends |
GET | /cluster/trends |
session | cluster.read |
— |
RevokeDevice |
DELETE | /devices/{id} |
session | users.manage |
oui |
StreamEvents |
GET | /events |
session | (toute session) | — |
GetLiveness |
GET | /health/live |
aucune | — | — |
GetReadiness |
GET | /health/ready |
aucune | — | — |
ListIncidents |
GET | /incidents |
session | alerts.read |
— |
CreateIncident |
POST | /incidents |
session | alerts.manage |
— |
GetIncident |
GET | /incidents/{id} |
session | alerts.read |
— |
UpdateIncident |
PATCH | /incidents/{id} |
session | alerts.manage |
— |
CommentIncident |
POST | /incidents/{id}/comments |
session | alerts.ack |
— |
ListInvitations |
GET | /invitations |
session | invitations.manage |
— |
CreateInvitation |
POST | /invitations |
session | invitations.manage |
oui |
ExchangeInvitation |
POST | /invitations/exchange |
aucune | — | — |
AbandonInvitationTransaction |
DELETE | /invitations/transaction |
transaction setup | — | — |
GetInvitationTransaction |
GET | /invitations/transaction |
transaction setup | — | — |
LinkInvitationToAccount |
POST | /invitations/transaction/link |
session et setup | (toute session) | oui |
SetInvitationProfile |
POST | /invitations/transaction/profile |
transaction setup | — | — |
RevokeInvitation |
DELETE | /invitations/{id} |
session | invitations.manage |
oui |
ListJobSchedules |
GET | /job-schedules |
session | jobs.read |
— |
CreateJobSchedule |
POST | /job-schedules |
session | jobs.submit |
— |
DeleteJobSchedule |
DELETE | /job-schedules/{id} |
session | jobs.submit |
— |
UpdateJobSchedule |
PATCH | /job-schedules/{id} |
session | jobs.submit |
— |
ListJobTemplates |
GET | /job-templates |
session | jobs.read |
— |
ListJobs |
GET | /jobs |
session | jobs.read |
— |
CreateJob |
POST | /jobs |
session | jobs.submit |
— |
GetJob |
GET | /jobs/{id} |
session | jobs.read |
— |
CancelJob |
POST | /jobs/{id}/cancel |
session | jobs.submit |
— |
ExportMaintenanceCalendar |
GET | /maintenance/calendar.ics |
session | maintenance.read |
— |
ListMaintenanceNotes |
GET | /maintenance/notes |
session | maintenance.read |
— |
CreateMaintenanceNote |
POST | /maintenance/notes |
session | maintenance.write |
— |
DeleteMaintenanceNote |
DELETE | /maintenance/notes/{id} |
session | maintenance.write |
— |
UpdateMaintenanceNote |
PATCH | /maintenance/notes/{id} |
session | maintenance.write |
— |
ListMaintenanceWindows |
GET | /maintenance/windows |
session | maintenance.read |
— |
CreateMaintenanceWindow |
POST | /maintenance/windows |
session | maintenance.write |
— |
CancelMaintenanceWindow |
DELETE | /maintenance/windows/{id} |
session | maintenance.write |
— |
GetMaintenanceWindow |
GET | /maintenance/windows/{id} |
session | maintenance.read |
— |
UpdateMaintenanceWindow |
PATCH | /maintenance/windows/{id} |
session | maintenance.write |
— |
CompleteMaintenanceWindow |
POST | /maintenance/windows/{id}/complete |
session | maintenance.write |
— |
GetMe |
GET | /me |
session | (toute session) | — |
UpdateMe |
PATCH | /me |
session | (toute session) | — |
ListMyDashboards |
GET | /me/dashboards |
session | (toute session) | — |
DeleteMyDashboard |
DELETE | /me/dashboards/{name} |
session | (toute session) | — |
PutMyDashboard |
PUT | /me/dashboards/{name} |
session | (toute session) | — |
ListMyDevices |
GET | /me/devices |
session | (toute session) | — |
PutMyPushToken |
PUT | /me/devices/current/push-token |
session | (toute session) | — |
RevokeMyDevice |
DELETE | /me/devices/{id} |
session | (toute session) | — |
ListMyPasskeys |
GET | /me/passkeys |
session | (toute session) | — |
DeleteMyPasskey |
DELETE | /me/passkeys/{id} |
session | (toute session) | oui |
UpdateMyPasskey |
PATCH | /me/passkeys/{id} |
session | (toute session) | — |
ListMySessions |
GET | /me/sessions |
session | (toute session) | — |
RevokeMySession |
DELETE | /me/sessions/{id} |
session | (toute session) | — |
GetMetricCatalog |
GET | /metrics/catalog |
session | nodes.read |
— |
CompareMetrics |
GET | /metrics/compare |
session | nodes.read |
— |
ListInferenceServers |
GET | /models |
session | models.read |
— |
GetInferenceServer |
GET | /models/{id} |
session | models.read |
— |
ListNetworkInterfaces |
GET | /network/interfaces |
session | nodes.read |
— |
GetNetworkTopology |
GET | /network/topology |
session | cluster.read |
— |
ListNodes |
GET | /nodes |
session | nodes.read |
— |
CreateNode |
POST | /nodes |
session | nodes.write |
— |
RetireNode |
DELETE | /nodes/{id} |
session | nodes.write |
oui |
GetNode |
GET | /nodes/{id} |
session | nodes.read |
— |
UpdateNode |
PATCH | /nodes/{id} |
session | nodes.write |
— |
GetNodeHealthHistory |
GET | /nodes/{id}/health-history |
session | nodes.read |
— |
GetNodeMetrics |
GET | /nodes/{id}/metrics |
session | nodes.read |
— |
ListNodeProcesses |
GET | /nodes/{id}/processes |
session | nodes.read |
— |
ListNodeServices |
GET | /nodes/{id}/services |
session | services.read |
— |
GetPermissionCatalog |
GET | /permissions |
session | (toute session) | — |
ListPolicyGrants |
GET | /policy-grants |
session | users.manage |
— |
CreatePolicyGrant |
POST | /policy-grants |
session | users.manage |
oui |
DeletePolicyGrant |
DELETE | /policy-grants/{id} |
session | users.manage |
oui |
Search |
GET | /search |
session | (toute session) | — |
ListServices |
GET | /services |
session | services.read |
— |
GetService |
GET | /services/{id} |
session | services.read |
— |
UpdateService |
PATCH | /services/{id} |
session | settings.manage |
— |
GetServiceHistory |
GET | /services/{id}/history |
session | services.read |
— |
RevokeSession |
DELETE | /sessions/{id} |
session | users.manage |
oui |
ListSettings |
GET | /settings |
session | settings.manage |
— |
PutSetting |
PUT | /settings/{key} |
session | settings.manage |
oui |
ListSilences |
GET | /silences |
session | alerts.read |
— |
CreateSilence |
POST | /silences |
session | alerts.manage |
— |
DeleteSilence |
DELETE | /silences/{id} |
session | alerts.manage |
— |
ListBackups |
GET | /storage/backups |
session | cluster.read |
— |
ListNasTargets |
GET | /storage/nas |
session | cluster.read |
— |
CreateNasTarget |
POST | /storage/nas |
session | settings.manage |
— |
DeleteNasTarget |
DELETE | /storage/nas/{id} |
session | settings.manage |
— |
ListVolumes |
GET | /storage/volumes |
session | nodes.read |
— |
ListUsers |
GET | /users |
session | users.manage |
— |
GetUser |
GET | /users/{id} |
session | users.manage |
— |
UpdateUser |
PATCH | /users/{id} |
session | users.manage |
oui |
ListUserDevices |
GET | /users/{id}/devices |
session | users.manage |
— |
ListUserPasskeys |
GET | /users/{id}/passkeys |
session | users.manage |
— |
RevokeUserPasskey |
DELETE | /users/{id}/passkeys/{passkeyId} |
session | users.manage |
oui |
ListUserSessions |
GET | /users/{id}/sessions |
session | users.manage |
— |
GetVersion |
GET | /version |
aucune | — | — |
Compléments non visibles dans la table :
CreateAction: la table porteactions.run.lowcomme plancher ; le handler exigeactions.run.<criticité>du type demandé, sur le nœud et la cible précis, pluslogs.readpourservice.logs.tail, plus le step-up pourhighetcritical.GetActionOutput:actions.readetlogs.readsur le nœud.CancelAction: le demandeur, sinonactions.run.<criticité>sur le nœud.PutSettingpourorchestrator.frozen: owner seulement.BeginRegistration/FinishRegistration: le step-up ne s'applique qu'à une session (ajout d'une passkey), pas à une transaction d'invitation.- Champs privés des nœuds (adresses, numéro de série, UUID matériel, cibles NAS) :
nodes.private.read, par nœud. GET /permissionsrenvoie le catalogue des 26 permissions et les défauts par rôle.
7. Limites de débit telles qu'implémentées
En mémoire, par processus (remises à zéro au redémarrage). Dépassement : 429 rate_limited + Retry-After.
| Portée | Limite | Clé | Source |
|---|---|---|---|
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 |
| Toute requête authentifiée | 900 par minute, rafale de 300 | session | api/server.go (userLimiter) |
POST /actions |
30 par minute, rafale de 30 | utilisateur | api/ops_actions.go (actionLimiter) |
POST /agent/v1/enroll (relais) |
20 par minute, rafale de 10 | adresse IP cliente | api/agent_proxy.go |
Non limitées par adresse : registration/begin|finish appelées avec une transaction d'invitation (mode « session
ou setup ») ; elles ne sont bornées que par les 5 échecs par invitation. L'adresse cliente est prise dans
X-Forwarded-For uniquement quand le pair est un proxy de confiance (MCC_TRUSTED_PROXIES).
8. Écarts connus entre contrat et implémentation
Chaque ligne a été vérifiée dans le code au commit 45f0d03.
| # | Sujet | Contrat (openapi.yaml) |
Implémentation | Effet |
|---|---|---|---|---|
| 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é |
| 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) |
| 3 | Événement audit.appended |
seq, ts, action, actor_label, outcome requis |
{seq} |
le web ne s'en sert que comme signal |
| 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 |
| 5 | Événement resync |
reason requis |
{} |
idem |
| 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 |
| 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 |
| 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 |
| 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) |
| 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 |
| 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 |
| 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 |
| 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é |
| 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 |
| 14 | Version des services | — | make build n'estampille que control-api ; /admin/status affiche 0.1.0-dev (ingestion) et dev (orchestrateur) |
cosmétique |
Sont alignés (anciens points de INTEGRATION-TODO.md, vérifiés) : valeurs étiquetées imbriquées lues par l'API et le
moteur d'alertes, clés cpu_percent / rss_bytes de la charge de l'agent, clé fingerprint de pki.ca,
horodatages en UTC, relais vers MCC_INGEST_SIGNED_LISTEN, clé de réglage orchestrator.frozen.