SPB Git

Repository Public

API.md 38.5 KB

# 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 :

json
{
  "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ête X-MCC-CSRF (valeur csrf_token renvoyée par la connexion et par GET /me) ;
  • transaction d'invitation par cookie : Origin égal à l'origine publique ;
  • jeton Bearer ou opération publique : pas de jeton CSRF ; si un Origin est 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) :

json
{
  "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)

http
POST /api/v1/auth/webauthn/authentication/begin
json
{
  "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 :

http
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") :

http
Set-Cookie: __Host-mcc_session=<opaque>; Path=/; HttpOnly; Secure; SameSite=Strict
Set-Cookie: __Host-mcc_device=<uuid>; Path=/; Max-Age=…; HttpOnly; Secure; SameSite=Strict
json
{
  "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)

http
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

http
GET /api/v1/me
json
{
  "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

http
POST /api/v1/auth/stepup/begin
X-MCC-CSRF: <csrf_token>
Origin: https://clustr.spboucher.ai

Réponse : un défi de même forme qu'en 3.1, qui n'accepte que les passkeys de l'utilisateur courant. Puis :

http
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>.

http
POST /api/v1/invitations/exchange
Content-Type: application/json

{ "token": "<jeton du fragment>", "client": { "kind": "web" } }
json
{
  "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.

http
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)

http
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

text
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 (sans id) ; head est la dernière séquence connue du serveur.
  • id est la séquence monotone de events_outbox ; data est directement la charge utile du sujet.
  • Battement : ping toutes 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 :

text
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 porte actions.run.low comme plancher ; le handler exige actions.run.<criticité> du type demandé, sur le nœud et la cible précis, plus logs.read pour service.logs.tail, plus le step-up pour high et critical.
  • GetActionOutput : actions.read et logs.read sur le nœud.
  • CancelAction : le demandeur, sinon actions.run.<criticité> sur le nœud.
  • PutSetting pour orchestrator.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 /permissions renvoie 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.

Files main
Menu

Theme