SPB Git

Repository Public

DESIGN-BRIEF.md 12.5 KB 150 lines markdown

1# Design brief — décisions figées (référence commune à tous les composants)23Ce document est la référence d'implémentation. `ARCHITECTURE.md`, `SECURITY.md`, `AGENT-PROTOCOL.md` en sont les4versions rédigées ; en cas de doute, **le contrat OpenAPI (`packages/api-contracts/openapi.yaml`) et le schéma SQL5(`services/internal/db/migrations/`) font foi**.67## 1. Composants et ports89| Composant | Langage | Écoute | Rôle |10|---|---|---|---|11| `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 |12| `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 |13| `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) |14| `web` | Next.js (App Router, TS strict) | `127.0.0.1:8733` | interface ; ne parle qu'à `/api/v1` en même origine |15| `mcc-agent` | Go, binaire statique | aucune écoute | collecte locale, connexion **sortante** vers l'ingestion, exécution de commandes typées |16| `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) |17| PostgreSQL 17 | — | `127.0.0.1:5432` | base `mcc` (prod), `mcc_dev`, `mcc_test` |1819Un seul module Go `services/` (`go 1.26`), binaires dans `services/cmd/<nom>`, paquets dans `services/internal/…`.20Les agents sont dans le même module (`services/cmd/mcc-agent`, `services/internal/agent/…`) pour partager le21paquet de protocole ; `agents/macos` et `agents/linux` contiennent le packaging (launchd / systemd) et la doc.22Coordination inter-services : **PostgreSQL uniquement** (tables durables + `LISTEN/NOTIFY`), pas de Redis.2324## 2. Pourquoi (critères observés, voir REAL-INFRASTRUCTURE-INVENTORY.md)2526- Go : 8 Macs n'ont ni Homebrew ni Node → l'agent doit être un binaire unique ; partager types et crypto du protocole27  entre agent et serveur évite toute divergence ; BHS64 (linux/amd64) = simple compilation croisée.28- PostgreSQL natif partitionné au lieu de TimescaleDB : l'extension n'est installée nulle part ; volume modeste29  (≈ 29 nœuds × ~25 séries × 10 s ≈ 6 M lignes/jour) ; partitions journalières + agrégats 1 min / 1 h suffisent.30- Next.js en serveur `standalone` derrière l'API Go : CSP à nonce stricte, une seule origine, cookies `__Host-`.31- Agents en mTLS direct sur le LAN (pas via Caddy, qui termine le TLS) : 12 Macs n'ont pas de tunnel.3233## 3. Identité et sessions3435- RP ID `clustr.spboucher.ai`, origine `https://clustr.spboucher.ai` ; en dev `localhost` / `http://localhost:8730`.36  Apps Apple : mêmes passkeys via Associated Domains `webcredentials:clustr.spboucher.ai`.37- WebAuthn : bibliothèque `github.com/go-webauthn/webauthn`. `userVerification=required`, `residentKey=required`38  (identifiants découvrables, connexion sans nom d'utilisateur), algorithmes ES256 (-7) et RS256 (-257),39  attestation `none` (politique documentée : pas de filtrage d'authentificateur, on vérifie UV + origine + RP ID),40  défi 32 octets à usage unique stocké côté serveur (5 min), compteur de signature vérifié (régression → refus +41  audit, sauf compteur 0 des passkeys synchronisées).42- Web : cookie `__Host-mcc_session` (opaque 32 octets, haché en base), `Secure; HttpOnly; SameSite=Strict; Path=/`.43  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`)44  **et** vérification `Origin` sur toute méthode non sûre.45- Apps natives : jeton d'accès opaque 10 min (`Authorization: Bearer`) + jeton de rafraîchissement rotatif 30 j lié à46  l'appareil ; réutilisation d'un jeton déjà tourné ⇒ révocation de la session + audit. Stockage Keychain.47- Step-up : une cérémonie passkey de moins de 5 min (`sessions.authenticated_at`) est exigée côté serveur pour toute48  action `high`/`critical`, la gestion des utilisateurs, passkeys, invitations, agents, politiques et exports d'audit.49- Invitation : jeton 32 octets (base64url), haché SHA-256, TTL 15 min par défaut (max 24 h), usage unique.50  Lien `https://clustr.spboucher.ai/setup#<jeton>` (fragment : jamais envoyé au serveur ni aux referrers ; la page fait51  `POST /invitations/exchange` puis `history.replaceState`). L'échange consomme le jeton **atomiquement** et ouvre une52  transaction de 10 min (cookie `__Host-mcc_setup`, ou jeton de transaction pour les apps). 5 échecs ⇒ invitation révoquée.53  Invitation visant un compte existant (`target_user_id`) : exige une session authentifiée **de ce compte** + step-up,54  puis confirmation explicite ; jamais de fusion implicite par `handle`.55- Amorçage et récupération : `mccctl bootstrap-owner` / `mccctl recovery-invite <handle>` exécutés en SSH sur le nœud56  hôte (hors bande), audités (`actor_kind=cli`). Aucun autre contournement.57- Rôles : owner > admin > operator > viewer, + `policy_grants` (allow/deny par permission et ressource ; deny l'emporte).5859Permissions (catalogue codé, exposé par `GET /api/v1/permissions`) :60`cluster.read`, `nodes.read`, `nodes.private.read` (IP, numéros de série), `nodes.write`, `logs.read`, `services.read`,61`models.read`, `jobs.read`, `jobs.submit`, `alerts.read`, `alerts.ack`, `alerts.manage`, `maintenance.read`,62`maintenance.write`, `actions.read`, `actions.run.low`, `actions.run.medium`, `actions.run.high`, `actions.run.critical`,63`actions.approve`, `audit.read`, `audit.export`, `users.manage`, `invitations.manage`, `agents.manage`, `settings.manage`.64Défauts : viewer = tous les `*.read` sauf `nodes.private.read`, `logs.read`, `audit.read` ; operator = viewer +65`nodes.private.read`, `logs.read`, `alerts.ack`, `maintenance.write`, `jobs.submit`, `actions.run.low|medium` ;66admin = operator + `nodes.write`, `alerts.manage`, `actions.run.high`, `actions.approve`, `audit.read`, `audit.export`,67`users.manage` (ne peut ni créer ni modifier un owner), `invitations.manage`, `agents.manage`, `settings.manage` ;68owner = tout (`actions.run.critical` inclus).6970## 4. Actions (catalogue typé — aucune commande libre)7172Chaque type : schéma JSON de paramètres, criticité, permission, `requires_step_up`, `requires_justification`,73`requires_confirmation` (le client doit renvoyer `confirm` = alias de la cible, vérifié **par le serveur**),74`requires_approval` (seconde personne ≠ demandeur, `actions.approve`), délai max, clé de verrou.7576| Type | Criticité | Verrou | Notes |77|---|---|---|---|78| `inventory.refresh` | low | node | ré-inventaire immédiat |79| `diagnostic.run` | low | node | collecte bornée (param `profile`: `basic`,`network`,`disk`) |80| `service.health_check` | low | service | |81| `service.logs.tail` | low | — | lecture bornée (≤ 500 lignes, ≤ 256 Kio), expurgée ; exige `logs.read` |82| `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 |83| `agent.restart` | medium | node | |84| `cache.purge` | medium | node | param `cache` ∈ liste blanche de l'agent (noms logiques, jamais un chemin) |85| `node.maintenance.set` | medium | node | côté serveur uniquement (pas de commande agent) |86| `job.run` / `job.cancel` | medium | job | modèles de jobs déclarés dans l'allowlist de l'agent |87| `model.server.start` / `model.server.stop` | high | node | si l'adaptateur le déclare ; estimation mémoire en pré-vérification |88| `deploy.release` | high | service | version approuvée ; **non activé en v1** (catalogue `available=false`) |89| `system.update.schedule` | high | node | **non activé en v1** |90| `system.reboot` | critical | node | step-up + justification + confirmation + approbation secondaire ; exige que l'agent ait le droit local (désactivé par défaut) |91| `system.shutdown` | critical | node | idem |9293États : `pending_approval → queued → dispatched → running → succeeded|failed|timed_out|cancelled`, `rejected`, `expired`.94Idempotence : `Idempotency-Key` obligatoire ; même clé + même corps ⇒ même action renvoyée ; même clé + corps95différent ⇒ `409 idempotency_conflict`. Un verrou par cible : seconde action concurrente ⇒ `409 target_locked`.96Pré-vérifications serveur : cible connue, agent en ligne et non révoqué, capacité déclarée par l'agent, nœud pas en97maintenance (sauf actions de maintenance), permission, step-up, confirmation, justification.98**Jamais de ré-émission automatique** d'une commande après déconnexion : une commande non acquittée expire99(`expires_at`), l'action passe `timed_out`/`failed` avec `outcome_unknown=true` si elle avait été remise.100Arrêt d'urgence : réglage `orchestrator.frozen=true` (`mccctl freeze`, ou Owner) ⇒ plus aucune commande émise ; les101agents refusent aussi toute commande si le fichier local `~/.mcc-agent/FREEZE` existe.102103## 5. Protocole agent (résumé ; détail dans AGENT-PROTOCOL.md)104105- Enrôlement : jeton à usage unique (15 min) → l'agent génère une clé ECDSA P-256 locale, envoie un CSR à106  `POST /agent/v1/enroll` (TLS serveur épinglé sur l'AC, jeton en en-tête) → certificat client 30 j (CN = id agent,107  SAN URI `mcc://agent/<id>`), AC, **clé publique Ed25519 de l'orchestrateur**. Renouvellement mTLS à mi-vie.108- `POST /agent/v1/report` (mTLS) toutes les 10 s : lot `{seq, ts, samples[], availability{}, processes?, services?,109  inventory?, inference?, volumes?, self{cpu,rss}}`. Tampon disque borné hors ligne (≤ 6 h / 20 Mo), rejoué dans l'ordre.110- `GET /agent/v1/commands?wait=25` (long-poll mTLS) → enveloppes `{id, type, params, node, issued_at, expires_at, nonce}`111  signées Ed25519 par l'orchestrateur. L'agent vérifie signature, destinataire, expiration (≤ 120 s), nonce jamais vu112  (journal local persistant), type ∈ allowlist locale (`~/.mcc-agent/policy.json`), paramètres (schéma), puis acquitte113  (`POST /agent/v1/commands/{id}/ack`), exécute avec délai et plafonds, diffuse la sortie expurgée114  (`…/events`) et termine (`…/result`). Le service d'ingestion ne peut donc pas forger de commande.115- Nom de serveur TLS fixe `ingest.mcc.internal` (SAN) : l'agent essaie une liste d'adresses, valide le certificat.116117## 6. Télémétrie118119Catalogue dans `METRICS-CATALOG.md` / table `metric_catalog`. Chaque métrique a unité, intervalle, provenance.120Toute métrique impossible à mesurer est déclarée dans `availability` (`unsupported`, `permission_denied`,121`unavailable`) — **jamais une valeur inventée ni un zéro**. Fraîcheur calculée par le serveur :122`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 j123(réglages). Limites de cardinalité : ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processus par rapport.124125## 7. Flux temps réel126127`GET /api/v1/events` (SSE). Chaque événement : `id: <seq>` (séquence monotone de `events_outbox`), `event: <topic>`,128`data: <json>`. Reprise par `Last-Event-ID` ; si la séquence demandée n'est plus retenue (> 1 h) le serveur envoie129`event: resync` et le client recharge. Battement `: ping` toutes les 15 s. Sujets : `node.state`, `node.updated`,130`alert.changed`, `incident.changed`, `action.changed`, `action.output`, `service.changed`, `job.changed`,131`maintenance.changed`, `audit.appended` (si `audit.read`). Filtrage par permission côté serveur.132133## 8. Clients134135- Contrat : OpenAPI 3.1 → types Go (`oapi-codegen`), TypeScript (`openapi-typescript` + `openapi-fetch`),136  Swift (`swift-openapi-generator`, paquet `packages/swift-core` = `MCCCore`, partagé macOS/iOS).137- Bundle ID : `ai.spboucher.clustr` (macOS), `ai.spboucher.clustr.ios` (iOS). Team `3YM54G49SN`.138- Jetons de design : `packages/ui-tokens/tokens.json` → CSS variables (web) et `Tokens.swift` (Apple), générés.139- Langues : fr (défaut) et en, partout. Thème sombre par défaut.140141## 9. Environnements142143| Env | Base | Origine | Remarque |144|---|---|---|---|145| dev | `mcc_dev` (laptop) | `http://localhost:8730` | agent local = le laptop lui-même (vraies métriques) |146| test | `mcc_test_<suffixe>` créées/détruites par les tests | — | données synthétiques **étiquetées** `environment=test`, jamais en prod |147| 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 |148149Configuration par variables d'environnement préfixées `MCC_` (voir `services/internal/config`).150
Files main
Menu

Theme