SPB Git

Repository Public

DESIGN-BRIEF.md 12.5 KB

# Design brief — décisions figées (référence commune à tous les composants)

Ce document est la référence d'implémentation. ARCHITECTURE.md, SECURITY.md, AGENT-PROTOCOL.md en sont les versions rédigées ; en cas de doute, le contrat OpenAPI (packages/api-contracts/openapi.yaml) et le schéma SQL (services/internal/db/migrations/) font foi.

# 1. Composants et ports

Composant Langage Écoute Rôle
control-api Go 0.0.0.0:8730 (derrière Caddy/BHS64, seul port public) REST /api/v1, SSE /api/v1/events, WebAuthn, AASA, proxy inverse vers web pour tout le reste
telemetry-ingest Go 0.0.0.0:8731 TLS 1.3 mTLS (LAN + wg seulement, jamais routé par Caddy) enrôlement des agents, réception télémétrie/inventaire, remise des commandes signées, rollups, rétention
action-orchestrator Go 127.0.0.1:8732 (santé seulement) file durable d'actions, pré-vérifications, verrous, signature des commandes, délais, moteur d'alertes, ordonnanceur (jobs, fenêtres d'entretien)
web Next.js (App Router, TS strict) 127.0.0.1:8733 interface ; ne parle qu'à /api/v1 en même origine
mcc-agent Go, binaire statique aucune écoute collecte locale, connexion sortante vers l'ingestion, exécution de commandes typées
mccctl Go — CLI d'administration hors bande sur le nœud hôte (amorçage du premier Owner, récupération, sauvegarde, vérification d'audit)
PostgreSQL 17 — 127.0.0.1:5432 base mcc (prod), mcc_dev, mcc_test

Un seul module Go services/ (go 1.26), binaires dans services/cmd/<nom>, paquets dans services/internal/…. Les agents sont dans le même module (services/cmd/mcc-agent, services/internal/agent/…) pour partager le paquet de protocole ; agents/macos et agents/linux contiennent le packaging (launchd / systemd) et la doc. Coordination inter-services : PostgreSQL uniquement (tables durables + LISTEN/NOTIFY), pas de Redis.

# 2. Pourquoi (critères observés, voir REAL-INFRASTRUCTURE-INVENTORY.md)

  • Go : 8 Macs n'ont ni Homebrew ni Node → l'agent doit être un binaire unique ; partager types et crypto du protocole entre agent et serveur évite toute divergence ; BHS64 (linux/amd64) = simple compilation croisée.
  • PostgreSQL natif partitionné au lieu de TimescaleDB : l'extension n'est installée nulle part ; volume modeste (≈ 29 nœuds × ~25 séries × 10 s ≈ 6 M lignes/jour) ; partitions journalières + agrégats 1 min / 1 h suffisent.
  • Next.js en serveur standalone derrière l'API Go : CSP à nonce stricte, une seule origine, cookies __Host-.
  • Agents en mTLS direct sur le LAN (pas via Caddy, qui termine le TLS) : 12 Macs n'ont pas de tunnel.

# 3. Identité et sessions

  • RP ID clustr.spboucher.ai, origine https://clustr.spboucher.ai ; en dev localhost / http://localhost:8730. Apps Apple : mêmes passkeys via Associated Domains webcredentials:clustr.spboucher.ai.
  • WebAuthn : bibliothèque github.com/go-webauthn/webauthn. userVerification=required, residentKey=required (identifiants découvrables, connexion sans nom d'utilisateur), algorithmes ES256 (-7) et RS256 (-257), attestation none (politique documentée : pas de filtrage d'authentificateur, on vérifie UV + origine + RP ID), défi 32 octets à usage unique stocké côté serveur (5 min), compteur de signature vérifié (régression → refus + audit, sauf compteur 0 des passkeys synchronisées).
  • Web : cookie __Host-mcc_session (opaque 32 octets, haché en base), Secure; HttpOnly; SameSite=Strict; Path=/. Inactivité 30 min, durée absolue 12 h. CSRF : en-tête X-MCC-CSRF (jeton lié à la session, remis par GET /api/v1/me) et vérification Origin sur toute méthode non sûre.
  • Apps natives : jeton d'accès opaque 10 min (Authorization: Bearer) + jeton de rafraîchissement rotatif 30 j lié à l'appareil ; réutilisation d'un jeton déjà tourné ⇒ révocation de la session + audit. Stockage Keychain.
  • Step-up : une cérémonie passkey de moins de 5 min (sessions.authenticated_at) est exigée côté serveur pour toute action high/critical, la gestion des utilisateurs, passkeys, invitations, agents, politiques et exports d'audit.
  • Invitation : jeton 32 octets (base64url), haché SHA-256, TTL 15 min par défaut (max 24 h), usage unique. Lien https://clustr.spboucher.ai/setup#<jeton> (fragment : jamais envoyé au serveur ni aux referrers ; la page fait POST /invitations/exchange puis history.replaceState). L'échange consomme le jeton atomiquement et ouvre une transaction de 10 min (cookie __Host-mcc_setup, ou jeton de transaction pour les apps). 5 échecs ⇒ invitation révoquée. Invitation visant un compte existant (target_user_id) : exige une session authentifiée de ce compte + step-up, puis confirmation explicite ; jamais de fusion implicite par handle.
  • Amorçage et récupération : mccctl bootstrap-owner / mccctl recovery-invite <handle> exécutés en SSH sur le nœud hôte (hors bande), audités (actor_kind=cli). Aucun autre contournement.
  • Rôles : owner > admin > operator > viewer, + policy_grants (allow/deny par permission et ressource ; deny l'emporte).

Permissions (catalogue codé, exposé par GET /api/v1/permissions) : cluster.read, nodes.read, nodes.private.read (IP, numéros de série), nodes.write, logs.read, services.read, models.read, jobs.read, jobs.submit, alerts.read, alerts.ack, alerts.manage, maintenance.read, maintenance.write, actions.read, actions.run.low, actions.run.medium, actions.run.high, actions.run.critical, actions.approve, audit.read, audit.export, users.manage, invitations.manage, agents.manage, settings.manage. Défauts : viewer = tous les *.read sauf nodes.private.read, logs.read, audit.read ; operator = viewer + nodes.private.read, logs.read, alerts.ack, maintenance.write, jobs.submit, actions.run.low|medium ; admin = operator + nodes.write, alerts.manage, actions.run.high, actions.approve, audit.read, audit.export, users.manage (ne peut ni créer ni modifier un owner), invitations.manage, agents.manage, settings.manage ; owner = tout (actions.run.critical inclus).

# 4. Actions (catalogue typé — aucune commande libre)

Chaque type : schéma JSON de paramètres, criticité, permission, requires_step_up, requires_justification, requires_confirmation (le client doit renvoyer confirm = alias de la cible, vérifié par le serveur), requires_approval (seconde personne ≠ demandeur, actions.approve), délai max, clé de verrou.

Type Criticité Verrou Notes
inventory.refresh low node ré-inventaire immédiat
diagnostic.run low node collecte bornée (param profile: basic,network,disk)
service.health_check low service
service.logs.tail low — lecture bornée (≤ 500 lignes, ≤ 256 Kio), expurgée ; exige logs.read
service.restart / service.start / service.stop medium / medium / high service uniquement services managed=true côté serveur et présents dans l'allowlist locale de l'agent
agent.restart medium node
cache.purge medium node param cache ∈ liste blanche de l'agent (noms logiques, jamais un chemin)
node.maintenance.set medium node côté serveur uniquement (pas de commande agent)
job.run / job.cancel medium job modèles de jobs déclarés dans l'allowlist de l'agent
model.server.start / model.server.stop high node si l'adaptateur le déclare ; estimation mémoire en pré-vérification
deploy.release high service version approuvée ; non activé en v1 (catalogue available=false)
system.update.schedule high node non activé en v1
system.reboot critical node step-up + justification + confirmation + approbation secondaire ; exige que l'agent ait le droit local (désactivé par défaut)
system.shutdown critical node idem

États : pending_approval → queued → dispatched → running → succeeded|failed|timed_out|cancelled, rejected, expired. Idempotence : Idempotency-Key obligatoire ; même clé + même corps ⇒ même action renvoyée ; même clé + corps différent ⇒ 409 idempotency_conflict. Un verrou par cible : seconde action concurrente ⇒ 409 target_locked. Pré-vérifications serveur : cible connue, agent en ligne et non révoqué, capacité déclarée par l'agent, nœud pas en maintenance (sauf actions de maintenance), permission, step-up, confirmation, justification. Jamais de ré-émission automatique d'une commande après déconnexion : une commande non acquittée expire (expires_at), l'action passe timed_out/failed avec outcome_unknown=true si elle avait été remise. Arrêt d'urgence : réglage orchestrator.frozen=true (mccctl freeze, ou Owner) ⇒ plus aucune commande émise ; les agents refusent aussi toute commande si le fichier local ~/.mcc-agent/FREEZE existe.

# 5. Protocole agent (résumé ; détail dans AGENT-PROTOCOL.md)

  • Enrôlement : jeton à usage unique (15 min) → l'agent génère une clé ECDSA P-256 locale, envoie un CSR à POST /agent/v1/enroll (TLS serveur épinglé sur l'AC, jeton en en-tête) → certificat client 30 j (CN = id agent, SAN URI mcc://agent/<id>), AC, clé publique Ed25519 de l'orchestrateur. Renouvellement mTLS à mi-vie.
  • POST /agent/v1/report (mTLS) toutes les 10 s : lot {seq, ts, samples[], availability{}, processes?, services?, inventory?, inference?, volumes?, self{cpu,rss}}. Tampon disque borné hors ligne (≤ 6 h / 20 Mo), rejoué dans l'ordre.
  • GET /agent/v1/commands?wait=25 (long-poll mTLS) → enveloppes {id, type, params, node, issued_at, expires_at, nonce} signées Ed25519 par l'orchestrateur. L'agent vérifie signature, destinataire, expiration (≤ 120 s), nonce jamais vu (journal local persistant), type ∈ allowlist locale (~/.mcc-agent/policy.json), paramètres (schéma), puis acquitte (POST /agent/v1/commands/{id}/ack), exécute avec délai et plafonds, diffuse la sortie expurgée (…/events) et termine (…/result). Le service d'ingestion ne peut donc pas forger de commande.
  • Nom de serveur TLS fixe ingest.mcc.internal (SAN) : l'agent essaie une liste d'adresses, valide le certificat.

# 6. Télémétrie

Catalogue dans METRICS-CATALOG.md / table metric_catalog. Chaque métrique a unité, intervalle, provenance. Toute métrique impossible à mesurer est déclarée dans availability (unsupported, permission_denied, unavailable) — jamais une valeur inventée ni un zéro. Fraîcheur calculée par le serveur : fresh (< 30 s), stale (30 s – 120 s), offline (> 120 s ou jamais vu). Rétention : brut 7 j, 1 min 30 j, 1 h 400 j (réglages). Limites de cardinalité : ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processus par rapport.

# 7. Flux temps réel

GET /api/v1/events (SSE). Chaque événement : id: <seq> (séquence monotone de events_outbox), event: <topic>, data: <json>. Reprise par Last-Event-ID ; si la séquence demandée n'est plus retenue (> 1 h) le serveur envoie event: resync et le client recharge. Battement : ping toutes les 15 s. Sujets : node.state, node.updated, alert.changed, incident.changed, action.changed, action.output, service.changed, job.changed, maintenance.changed, audit.appended (si audit.read). Filtrage par permission côté serveur.

# 8. Clients

  • Contrat : OpenAPI 3.1 → types Go (oapi-codegen), TypeScript (openapi-typescript + openapi-fetch), Swift (swift-openapi-generator, paquet packages/swift-core = MCCCore, partagé macOS/iOS).
  • Bundle ID : ai.spboucher.clustr (macOS), ai.spboucher.clustr.ios (iOS). Team 3YM54G49SN.
  • Jetons de design : packages/ui-tokens/tokens.json → CSS variables (web) et Tokens.swift (Apple), générés.
  • Langues : fr (défaut) et en, partout. Thème sombre par défaut.

# 9. Environnements

Env Base Origine Remarque
dev mcc_dev (laptop) http://localhost:8730 agent local = le laptop lui-même (vraies métriques)
test mcc_test_<suffixe> créées/détruites par les tests — données synthétiques étiquetées environment=test, jamais en prod
prod mcc (nœud hôte) https://clustr.spboucher.ai secrets dans ~/.config/mcc/ (0600) sur le nœud, jamais dans le dépôt

Configuration par variables d'environnement préfixées MCC_ (voir services/internal/config).

Files main
Menu

Theme