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
standalonederriè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, originehttps://clustr.spboucher.ai; en devlocalhost/http://localhost:8730. Apps Apple : mêmes passkeys via Associated Domainswebcredentials: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), attestationnone(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êteX-MCC-CSRF(jeton lié à la session, remis parGET /api/v1/me) et vérificationOriginsur 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 actionhigh/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 faitPOST /invitations/exchangepuishistory.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 parhandle. - 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 URImcc://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, paquetpackages/swift-core=MCCCore, partagé macOS/iOS). - Bundle ID :
ai.spboucher.clustr(macOS),ai.spboucher.clustr.ios(iOS). Team3YM54G49SN. - Jetons de design :
packages/ui-tokens/tokens.json→ CSS variables (web) etTokens.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).