Repository Public
1# Exploitation — MacLustr Command Center23État décrit : commit `45f0d03`, déploiement du 2026-11-18 sur le nœud hôte M4M64c. Les faits **[prod]** ont été4observés par le responsable du déploiement ; ils ne sont pas vérifiables depuis ce dépôt. Les procédures marquées5**(non exercée)** sont déduites du code et n'ont jamais été déroulées en conditions réelles.67Documents liés : [ARCHITECTURE.md](ARCHITECTURE.md) · [SECURITY.md](SECURITY.md) · [AGENT-PROTOCOL.md](AGENT-PROTOCOL.md) ·8[API.md](API.md) · ADR [0009](DECISIONS/0009-hosting-and-exposure.md).910## 0. Repères1112| Élément | Valeur en production **[prod]** |13|---|---|14| URL publique | `https://clustr.spboucher.ai` |15| Nœud hôte | M4M64c (Mac Studio M4 Max) |16| Répertoire | `~/apps/maclustr-command-center` = clone git de `gitsrv:srv/git/maclustr-command-center.git` |17| Processus PM2 | `mcc-control-api` (0.0.0.0:8800), `mcc-telemetry-ingest` (127.0.0.1:8801 mTLS, 8804 requêtes signées, 8805 santé), `mcc-action-orchestrator` (127.0.0.1:8802), `mcc-web` (127.0.0.1:8803), `mcc-backup` (cron `40 3 * * *`) |18| Base | PostgreSQL 17, base `mcc`, `postgres://127.0.0.1/mcc?sslmode=disable` |19| Secrets | `~/.config/mcc/` (AC des agents, clés de signature, clé CSRF, clé de sauvegarde) |20| Configuration de `mccctl` | `~/.config/mcc/env` (aucun secret) |21| Sauvegardes | `~/mcc-backups` sur l'hôte + copie sur M3U96b (`backups/maclustr-command-center`) |22| Manifeste de déploiement | `infra/deploy/mld-manifest.json` |2324`mccctl` s'exécute **sur l'hôte**, par SSH, avec le lanceur qui charge la configuration :2526```sh27~/apps/maclustr-command-center/scripts/mccctl <commande> [options]28```2930Commandes (`services/cmd/mccctl/`) : `migrate`, `bootstrap-owner`, `recovery-invite`, `audit-verify`,31`audit-verify-export`, `freeze`, `unfreeze`, `status`, `backup`, `backup-verify`, `restore`, `restore-test`,32`enroll-token`, `register-node`. Les opérations qui changent un état écrivent une entrée d'audit `actor_kind=cli`.3334## 1. Installation à partir de zéro3536### 1.1 Prérequis de l'hôte3738D'après `infra/deploy/mld-manifest.json` (`requires`) et le `Makefile` :3940- macOS sur Apple Silicon (les binaires sont construits pour `darwin/arm64`), toujours allumé, session ouverte ;41- Homebrew avec `go` (1.26, voir `services/go.mod`), `node`, `pnpm`, `pm2`, `postgresql@17` ;42- ports libres 8800 à 8805 ; ≈ 3 Go de mémoire disponibles ;43- une route publique `https://clustr.spboucher.ai` → `hôte:8800` sur la passerelle, avec prise en charge des44 connexions longues (SSE, long-poll des agents) ; le DNS du domaine pointe sur la passerelle ;45- l'adresse de la passerelle vue par l'hôte dans `MCC_TRUSTED_PROXIES` (production : `10.67.0.1,127.0.0.1`), sinon46 toutes les requêtes semblent venir de la même adresse et partagent les limites de débit par IP.4748### 1.2 Base de données4950```sh51createdb mcc # PostgreSQL local, écoute en loopback52```5354Les migrations (`services/internal/db/migrations/`) sont appliquées automatiquement au démarrage de `control-api`55et d'`action-orchestrator`, ou explicitement par `scripts/mccctl migrate`. Une migration déjà appliquée puis56modifiée est refusée (somme de contrôle).5758### 1.3 Configuration5960Variables `MCC_*` (liste complète et défauts : `services/internal/config/config.go`). Valeurs de production,61identiques pour les trois services et `mcc-backup` dans le manifeste :6263```sh64MCC_ENV=prod65MCC_DATABASE_URL=postgres://127.0.0.1/mcc?sslmode=disable66MCC_SECRETS_DIR=$HOME/.config/mcc67MCC_PUBLIC_ORIGIN=https://clustr.spboucher.ai68MCC_RP_ID=clustr.spboucher.ai69MCC_API_LISTEN=0.0.0.0:880070MCC_TRUSTED_PROXIES=10.67.0.1,127.0.0.171MCC_WEB_UPSTREAM=http://127.0.0.1:880372MCC_INGEST_LISTEN=127.0.0.1:880173MCC_ORCHESTRATOR_LISTEN=127.0.0.1:880274MCC_INGEST_SIGNED_LISTEN=127.0.0.1:880475MCC_INGEST_HEALTH_LISTEN=127.0.0.1:880576MCC_INGEST_ADVERTISE=https://clustr.spboucher.ai77MCC_APPLE_APP_IDS=3YM54G49SN.ai.spboucher.clustr,3YM54G49SN.ai.spboucher.clustr.ios78TZ=UTC79```8081Le même contenu (sans secret) va dans `~/.config/mcc/env` pour `scripts/mccctl`. En `prod`, le démarrage échoue si82l'origine n'est pas en `https` ou si `MCC_RP_ID` vaut `localhost` (`config.validate`).8384Les secrets ne se configurent pas : chaque service crée le sien au premier démarrage dans `MCC_SECRETS_DIR`85(fichiers 0600). Inventaire : [SECURITY.md §11](SECURITY.md#11-inventaire-des-secrets).8687### 1.4 Construction et démarrage8889```sh90cd ~/apps/maclustr-command-center91make build # dist/control-api, telemetry-ingest, action-orchestrator, mccctl + SHA256SUMS.backend92make web-release # serveur Next « standalone » assemblé dans dist/web (node dist/web/server.js)93```9495En production ces deux cibles sont les crochets `post_sync` du manifeste : le produit a été placé et démarré avec96l'outil de déploiement existant du cluster, `mld`, à partir de `infra/deploy/mld-manifest.json`. La syntaxe de `mld`97appartient à cet outil et n'est pas documentée dans ce dépôt. Sans `mld`, il faut créer les cinq processus PM298décrits dans le manifeste (`processes[]` : `script`, `args`, `cwd`, `env`, `autorestart`, `max_memory_restart`,99`cron_restart`) et la route publique vers le port 8800.100101Ordre conseillé au premier démarrage : `mcc-telemetry-ingest` (crée l'AC et la publie dans `settings['pki.ca']`,102ce dont `mccctl enroll-token` a besoin), `mcc-action-orchestrator` (crée la clé de commande, inscrit les règles103d'alerte intégrées), `mcc-control-api`, `mcc-web`.104105### 1.5 Vérification106107```sh108curl -fsS https://clustr.spboucher.ai/api/v1/health/ready # {"status":"ok"} ; 503 si la base ne répond pas109curl -fsS https://clustr.spboucher.ai/api/v1/version110curl -fsS https://clustr.spboucher.ai/.well-known/apple-app-site-association111curl -fsS http://127.0.0.1:8805/healthz # ingestion (sur l'hôte) ; donne ca_fingerprint112curl -fsS http://127.0.0.1:8802/health/ready # orchestrateur (sur l'hôte)113scripts/mccctl status114```115116Observé le 2026-11-18 **[prod]** : santé, version et AASA publics ; HSTS et en-têtes de sécurité ; CSP à nonce sur117les pages ; options WebAuthn avec `rpId=clustr.spboucher.ai` et `userVerification=required` ; POST inter-origine118refusé (403) ; requête non signée vers `/agent/v1/report` refusée (401).119120## 2. Mise à jour et retour arrière121122### 2.1 Mise à jour123124Sur l'hôte (le répertoire déployé est un clone git) :125126```sh127cd ~/apps/maclustr-command-center128git pull129make build && make web-release130pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web131scripts/mccctl status132```133134À savoir :135136- **Le serveur avant les agents.** Un agent qui envoie une métrique inconnue du serveur voit son rapport refusé137 ([AGENT-PROTOCOL.md §12](AGENT-PROTOCOL.md)). Mettre à jour le plan de contrôle, puis les agents.138- Les migrations nouvelles s'appliquent au redémarrage de `control-api` ou de l'orchestrateur.139- Pendant le redémarrage : les agents tamponnent et rejouent ; les sessions survivent (elles sont en base) ; les140 clients SSE reprennent avec `Last-Event-ID` ; une action en vol est réconciliée, jamais ré-émise.141- Les limites de débit et le cache de nonces de l'ingestion sont en mémoire et repartent de zéro.142- `make ci` (voir [README](../README.md)) est le seul garde-fou avant de pousser : il n'y a pas de CI hébergée.143144### 2.2 Retour arrière **(non exercé)**145146```sh147git checkout <commit précédent>148make build && make web-release149pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web150```151152Il n'existe **pas de migrations descendantes**. Si la version à annuler a ajouté une migration, l'ancien binaire153tournera sur un schéma plus récent : ce cas n'a pas été testé. La voie sûre est alors de restaurer la sauvegarde154précédant la mise à jour (§7.3), en acceptant de perdre les données écrites depuis.155156## 3. Premier owner et récupération de compte157158### 3.1 Amorçage du premier owner159160```sh161scripts/mccctl bootstrap-owner --handle <identifiant> --name "<Nom affiché>" [--ttl 15m]162```163164La commande imprime **une seule fois** un lien `https://clustr.spboucher.ai/setup#<jeton>` (usage unique, 15 min165par défaut, 24 h au plus). L'ouvrir **sur l'appareil qui portera la passkey**, créer la passkey : le compte owner166est créé et la session ouverte. La commande est refusée dès qu'un owner capable de se connecter existe167(`owner_exists`). Ne pas coller le lien dans une messagerie ou un ticket.168169État au moment de la rédaction : **cette étape n'a pas encore été faite en production** ; c'est au propriétaire de170l'exécuter avec sa propre passkey. Conseil : ajouter aussitôt une seconde passkey (Réglages → Sécurité), car la171perte de la seule passkey impose la procédure de récupération.172173### 3.2 Comptes suivants174175Depuis l'interface (Réglages → Invitations) ou `POST /invitations` (`invitations.manage` + step-up). Un admin ne176peut pas inviter un owner.177178### 3.3 Récupération d'un compte (passkeys perdues)179180```sh181scripts/mccctl recovery-invite --handle <identifiant> [--ttl 15m]182```183184Ouvrir le lien sur le nouvel appareil et créer une passkey. Effets (`FinishSetupRegistration`) : **toutes** les185anciennes passkeys et sessions du compte sont révoquées ; le rôle est inchangé. Une seule invitation de186récupération peut être ouverte par compte (`409 recovery_pending` sinon). C'est le seul contournement prévu ; il187suppose l'accès SSH à l'hôte.188189## 4. Agents190191Binaires : `bash agents/build.sh` (ou `make agents`) produit `dist/mcc-agent-darwin-arm64`,192`dist/mcc-agent-linux-amd64`, `dist/mcc-agent-linux-arm64` et `dist/SHA256SUMS`.193194### 4.1 Enrôlement d'un Mac195196```sh197# sur l'hôte : jeton à usage unique (15 min par défaut, 1 h au plus) + empreinte de l'AC198scripts/mccctl enroll-token --alias <alias>199200# sur le Mac, avec l'utilisateur ordinaire (jamais root)201sh install.sh --binary ./mcc-agent-darwin-arm64 \202 --endpoints https://clustr.spboucher.ai \203 --token <jeton> --ca-fingerprint sha256:<hex>204```205206`agents/macos/install.sh` installe le binaire dans `~/.mcc-agent/bin/`, enrôle l'agent s'il ne l'est pas, pose207`~/Library/LaunchAgents/ai.spboucher.mcc-agent.plist` et démarre le service. Il ne touche qu'au libellé208`ai.spboucher.mcc-agent`. Relancé sur une machine déjà enrôlée, il conserve l'identité.209210| Mode | Quand | Fichier | sudo |211|---|---|---|---|212| LaunchAgent (défaut) | Mac avec session graphique ouverte | `~/Library/LaunchAgents/ai.spboucher.mcc-agent.plist` | non |213| LaunchDaemon (`--daemon`) | Mac **sans** session graphique | `/Library/LaunchDaemons/ai.spboucher.mcc-agent.plist`, avec `UserName` = l'utilisateur ordinaire | une fois, pour installer le fichier |214215Dans les deux modes l'agent tourne sous l'utilisateur ordinaire. Pour un `--daemon` non interactif :216`SUDO="sudo -A"` avec `SUDO_ASKPASS`. En production **[prod]** : LaunchAgent partout, sauf M2U64 et m4md217(pas de session graphique) installés en LaunchDaemon.218219**Point de terminaison.** Utiliser l'URL publique. Un binaire lancé par launchd ne peut pas joindre le LAN sous220macOS (confidentialité du réseau local, mesurée sur m4ml — [ADR 0004, amendement](DECISIONS/0004-agent-transport-mtls-lan.md)) ;221une adresse `host:port` (mTLS direct) ne fonctionne donc pas pour un agent géré par launchd sur ces machines.222223### 4.2 Déploiement en série224225```sh226bash agents/build.sh227DAEMON="M2U64 m4md" infra/deploy/rollout-agents.sh <alias> <alias>@<ip-lan> …228```229230`infra/deploy/rollout-agents.sh` traite un nœud à la fois et vérifie chacun (`connection online` dans231`mcc-agent status`) avant le suivant. `<alias>@<ip-lan>` passe par la passerelle SSH du cluster ; dans ce cas le232script exige que le marqueur `~/.maclustr-node` de la machine soit égal à l'alias (une adresse n'est jamais prise233pour une identité). Variables : `HOST` (hôte du plan de contrôle, défaut `M4M64c`), `GW` (défaut `M1M32`),234`DAEMON` (alias installés en LaunchDaemon, défaut `M2U64`). Une machine déjà enrôlée ne reçoit que le binaire.235236Déroulé du 2026-11-18 **[prod]** : pilote sur m4ml, puis déploiement progressif ; 28 Macs et la passerelle Linux237BHS64 rapportent. Totaux rapportés par les agents : 379 cœurs CPU et 1 032 Go de mémoire sur 28 Macs, identiques au238relevé en lecture seule de la phase 0 (`REAL-INFRASTRUCTURE-INVENTORY.md`).239240### 4.3 Machine éteinte ou sans agent241242```sh243scripts/mccctl register-node --alias <alias> [--kind mac|linux|nas] [--site …] [--role …] [--tags a,b]244```245246Le nœud apparaît hors ligne, sans fait matériel, jusqu'à ce qu'un agent s'enrôle sous le même alias. M4BP36247(portable éteint) a été inscrit ainsi **[prod]**.248249### 4.4 Linux (systemd)250251```sh252scripts/mccctl enroll-token --alias <alias> --kind linux # sur l'hôte253sudo ./install.sh --binary ./mcc-agent-linux-amd64 \254 --endpoints https://clustr.spboucher.ai --token <jeton> --ca-fingerprint sha256:<hex>255```256257`agents/linux/install.sh` crée l'utilisateur système `mcc-agent`, installe `/usr/local/bin/mcc-agent`, l'état dans258`/var/lib/mcc-agent` (0700) et l'unité `agents/linux/mcc-agent.service` (`NoNewPrivileges`, `ProtectSystem=strict`,259`ProtectHome=yes`, `MemoryMax=256M`, `CPUQuota=50%`, seule capacité `CAP_NET_RAW` pour le ping). En service sur260BHS64 **[prod]**.261262### 4.5 État, journaux, mise à jour263264```sh265~/.mcc-agent/bin/mcc-agent status [--json] # Linux : sudo -u mcc-agent mcc-agent status --state-dir /var/lib/mcc-agent266~/.mcc-agent/bin/mcc-agent policy check267~/.mcc-agent/bin/mcc-agent version268tail -f ~/Library/Logs/mcc-agent/mcc-agent.log # Linux : journalctl -u mcc-agent269```270271Mise à jour : relancer `install.sh --binary <nouveau binaire>` (remplacement atomique, identité conservée, service272relancé), ou `rollout-agents.sh`. Le certificat (30 jours) se renouvelle seul à mi-vie ; la règle d'alerte273« Agent certificate expiring » se déclenche à moins de 7 jours.274275### 4.6 Révocation et désinstallation276277| Opération | Commande |278|---|---|279| Révoquer (serveur) | Réglages → Agents, ou `POST /agents/{id}/revoke` (`agents.manage` + step-up). Effet en quelques secondes (`401 agent_revoked`) |280| Révoquer sans compte **(non exercé)** | il n'existe pas de commande `mccctl` de révocation ; en dernier recours, sur l'hôte : `update agents set revoked_at = now(), revoked_reason = '<motif>' where id = '<id>'` — **non audité** |281| Désinstaller un Mac | `sh agents/macos/uninstall.sh` (garde l'identité) ou `--purge` (efface `~/.mcc-agent` et les journaux) |282| Désinstaller Linux | `sudo ./uninstall.sh [--purge]` |283| Ré-enrôler | nouveau jeton ; l'enrôlement révoque l'agent actif précédent du nœud (`re-enrolled`). Par l'API, il faut d'abord révoquer l'agent existant (`409` sinon) |284| Retirer un nœud | `DELETE /nodes/{id}` (`nodes.write` + step-up) ; un nœud retiré ne peut plus être enrôlé (`409 node_retired`) |285286Après un `--purge`, révoquer aussi l'agent côté serveur.287288## 5. Politique locale et interrupteur d'arrêt de l'agent289290Fichier `<état>/policy.json` (`~/.mcc-agent/policy.json` ; Linux : `/var/lib/mcc-agent/policy.json`), propriété du291propriétaire du nœud. Le serveur ne peut ni le lire ni le modifier.292293| État du fichier | Effet |294|---|---|295| absent | quatre commandes de lecture : `inventory.refresh`, `diagnostic.run`, `service.health_check`, `service.logs.tail` |296| présent et valide | exactement ce qu'il autorise |297| invalide, ou inscriptible par le groupe ou les autres | **toute commande est refusée** |298299Exemple validé avec `mcc-agent policy check` (adapter les chemins ; un cache dont le chemin n'existe pas est signalé300« NOT USABLE ») :301302```json303{304 "allow": ["inventory.refresh", "diagnostic.run", "service.health_check", "service.logs.tail",305 "service.restart", "cache.purge", "job.run", "job.cancel"],306 "services": {"pm2": ["my-app", "my-app-*"], "launchd": ["com.example.worker"]},307 "cache_roots": ["/Users/me/Library/Caches/my-app"],308 "caches": {"thumbnails": "/Users/me/Library/Caches/my-app/thumbnails"},309 "jobs": {310 "report": {311 "argv": ["/usr/bin/du", "-sk", "{path}"],312 "params": {"path": {"type": "enum", "values": ["/Users/me/data", "/Users/me/logs"]}},313 "timeout_s": 120314 }315 },316 "allow_reboot": false,317 "allow_shutdown": false318}319```320321```sh322chmod 600 ~/.mcc-agent/policy.json && ~/.mcc-agent/bin/mcc-agent policy check323```324325Les types autorisés sont déclarés au serveur comme capacités (un modèle de job devient `job.run:<nom>`) ; une action326dont la capacité manque est refusée avant tout envoi (`422 capability_missing`). `system.reboot` et327`system.shutdown` exigent en plus `allow_reboot` / `allow_shutdown` **et** un `sudo -n` fonctionnel.328Référence : [AGENT-PROTOCOL.md §8](AGENT-PROTOCOL.md), `services/internal/agent/policy/policy.go`.329330En production **[prod]** : aucun fichier de politique n'est déployé — tous les agents sont en lecture seule ;331redémarrage et extinction sont désactivés partout.332333**Interrupteur d'arrêt local** :334335```sh336touch ~/.mcc-agent/FREEZE # l'agent refuse toute commande (raison « frozen ») ; la télémétrie continue337rm ~/.mcc-agent/FREEZE # retour à la normale338```339340## 6. Supervision du produit lui-même341342| Source | Ce qu'elle montre |343|---|---|344| `GET /api/v1/health/live`, `/health/ready` | vie de `control-api` ; `ready` répond 503 si la base ne répond pas en 2 s. C'est le `health_path` du manifeste |345| `GET /api/v1/admin/status` (`settings.manage`) ; écran Réglages → Système | base (latence), battement de l'ingestion et de l'orchestrateur, agents connectés, dernier rapport reçu, clients SSE, gel, dernière sauvegarde observée |346| `scripts/mccctl status` | utilisateurs, owners, sessions, nœuds, agents, battements de chaque service |347| Table `service_heartbeats` | un battement toutes les 10 s par service ; `/admin/status` déclare un composant `degraded` au-delà de 30 s et `down` au-delà de 120 s ; absence totale de battement = `unknown` |348| `http://127.0.0.1:8805/healthz` | ingestion : base, AC, agents connectés |349| `http://127.0.0.1:8802/health/ready` | orchestrateur : dernière passe, gel, état APNs, dernière exécution de chaque tâche périodique |350| Journaux PM2, `~/.pm2/logs/mcc-*` | JSON structuré, une ligne par requête avec `correlation_id`. `control-api` et l'orchestrateur écrivent sur la sortie standard (`…-out.log`), l'ingestion sur la sortie d'erreur (`…-error.log`) |351| Écran Stockage → Sauvegardes | résultat enregistré de chaque `mccctl backup` et `restore-test` (table `backups`) |352| Journal d'audit | `scripts/mccctl audit-verify` ; écran Audit |353354Règles d'alerte intégrées (12, `services/internal/alerts/rules.go`) : nœud hors ligne, disque > 90 % et > 97 %,355pression mémoire (avertissement, critique), swap > 80 %, CPU saturé, service géré en erreur, certificat d'agent356proche de l'expiration, perte de paquets vers la passerelle, rafale de requêtes refusées, connexion d'un357owner/admin depuis un nouvel appareil. Alertes réelles levées juste après le déploiement **[prod]** : disque à35899,6 % sur M4M64b (critique), disque à 92 % sur M3U96b, swap > 80 % en attente sur M3U96a.359360Ce qui n'existe pas : aucune supervision externe du plan de contrôle (si l'hôte tombe, rien ne prévient) et aucune361notification push (APNs inactif). Les versions affichées pour l'ingestion et l'orchestrateur ne sont pas362estampillées par `make build` (`0.1.0-dev` et `dev`) ; se fier à `GET /api/v1/version` et au commit du clone.363364## 7. Sauvegarde et restauration365366Source : `services/internal/backup/`, `services/cmd/mccctl/backup.go`.367368### 7.1 Sauvegarde369370```sh371scripts/mccctl backup --dir ~/mcc-backups --keep 14 --copy-to mcc-backup:backups/maclustr-command-center372```373374- `pg_dump` (format personnalisé) chiffré au fil de l'eau en AES-256-GCM par blocs de 64 Kio, clé375 `~/.config/mcc/backup.key`. Le fichier `mcc-*.dump.enc` n'apparaît sous son nom final qu'une fois complet.376- La sauvegarde est **relue et authentifiée** avant d'être déclarée réussie.377- `--copy-to` : copie `rsync` vers un second nœud ; l'échec de la copie fait échouer la commande.378- Le résultat est enregistré dans la table `backups` ; les fichiers locaux au-delà de `--keep` sont supprimés.379- Planification : processus PM2 `mcc-backup`, `cron_restart: 40 3 * * *`, `autorestart: false`.380381En production **[prod]** : première sauvegarde chiffrée créée, vérifiée et copiée sur M3U96b ; l'alias SSH382`mcc-backup` utilise une clé dédiée restreinte, côté M3U96b, par une commande forcée au dépôt rsync dans un seul383répertoire.384385**La clé `backup.key` doit exister ailleurs que sur l'hôte** (gestionnaire de mots de passe ou autre machine).386Sans elle, les sauvegardes sont inutilisables après la perte du disque ; la sauvegarde ne contient pas387`~/.config/mcc`.388389### 7.2 Vérification et test de restauration390391```sh392scripts/mccctl backup-verify --file ~/mcc-backups/mcc-….dump.enc # authentifie et lit le catalogue393scripts/mccctl restore-test --dir ~/mcc-backups # dernière sauvegarde394```395396`restore-test` restaure dans une base temporaire `mcc_restore_test_<suffixe>` sur le même serveur, vérifie la chaîne397d'audit restaurée et la présence du schéma, affiche les comptes (migrations, utilisateurs, nœuds, lignes d'audit),398enregistre le résultat, puis supprime la base temporaire. La base de production n'est que lue. Il ne compare pas399ligne à ligne avec la base vivante. Exécuté avec succès sur l'hôte **[prod]**.400401Aucune planification automatique de `restore-test` n'existe : à lancer à la main, périodiquement.402403### 7.3 Restauration404405```sh406createdb mcc_restored407scripts/mccctl restore --file <fichier> --to "postgres://127.0.0.1/mcc_restored?sslmode=disable"408```409410`restore` refuse une base qui contient déjà des tables, puis affiche les comptes et vérifie la chaîne d'audit.411Pour remettre en service : arrêter les quatre processus, restaurer dans une base `mcc` vide (renommer l'ancienne),412redémarrer. Les agents rejouent leur tampon (6 h au plus) ; ce qui a été écrit entre la sauvegarde et l'incident413est perdu, sauf la télémétrie encore tamponnée.414415## 8. Rotation des clés416417Aucune rotation n'est outillée ni n'a été exercée. Procédures déduites du code ; tableau des clés :418[SECURITY.md §11](SECURITY.md#11-inventaire-des-secrets).419420| Clé | Procédure **(non exercée)** |421|---|---|422| `csrf.key` | `pm2 stop mcc-control-api` ; déplacer le fichier ; `pm2 start`. Sans effet sur les sessions |423| `audit-signing.key` | noter d'abord `export_public_key` (`GET /audit/verify`) pour les exports existants ; déplacer le fichier ; redémarrer `mcc-control-api` |424| `command-signing.key` | `scripts/mccctl freeze` ; `pm2 stop mcc-action-orchestrator` ; déplacer le fichier ; `pm2 start` (nouvelle clé créée et inscrite dans `command_keys`) ; marquer l'ancienne : `update command_keys set retired_at = now() where key_id = '<ancien>'` ; `unfreeze`. Chaque agent apprend la nouvelle clé par un renouvellement de certificat, déclenché quand il reçoit une commande portant un identifiant de clé inconnu — **la première commande après rotation peut donc être refusée** |425| `backup.key` | déplacer le fichier ; la prochaine sauvegarde en crée une nouvelle (à copier hors hôte). Garder l'ancienne tant que d'anciennes sauvegardes existent |426| AC des agents (`agent-ca.key`, `agent-ca.crt`) | pas de rotation sans interruption : arrêter l'ingestion, déplacer les deux fichiers, redémarrer (nouvelle AC publiée), puis **ré-enrôler chaque agent** (`uninstall.sh --purge`, nouveau jeton, `install.sh`). L'AC est valide 10 ans |427| Certificats d'agents | automatique (30 jours, renouvelés à mi-vie par l'agent) |428| Clé SSH de copie des sauvegardes | remplacer la clé sur l'hôte et l'entrée `authorized_keys` restreinte sur le second nœud |429430## 9. Déplacer le plan de contrôle vers un autre nœud431432**(non exercé).** Le manifeste épingle l'app (`placement.pin: M4M64c`) parce que **ni la base ni les secrets ne433suivent** un déplacement fait par l'outil de déploiement. Ce qui doit suivre :434435| Élément | Pourquoi | Comment |436|---|---|---|437| Base `mcc` | tout l'état : comptes, passkeys, sessions, nœuds, agents, audit, séries | sauvegarde fraîche puis `restore` sur le nouveau nœud |438| `~/.config/mcc/agent-ca.key` + `.crt` | sans la même AC, **tous les agents doivent être ré-enrôlés** | copie sécurisée du répertoire entier |439| `~/.config/mcc/command-signing.key` | sinon nouvelle clé, que les agents doivent réapprendre | idem |440| `~/.config/mcc/audit-signing.key` | vérification des exports déjà produits | idem |441| `~/.config/mcc/backup.key` | nécessaire pour restaurer et pour continuer les sauvegardes | idem (et copie hors hôte) |442| `~/.config/mcc/csrf.key` | facultatif (les clients relisent leur jeton) | idem |443| `~/.config/mcc/env` | configuration de `mccctl` | idem |444| Clé SSH et alias `mcc-backup` | copie hors hôte des sauvegardes | à recréer |445| Route publique et `MCC_TRUSTED_PROXIES` | le domaine doit viser le nouveau `nœud:8800` | passerelle / outil de déploiement ; mettre à jour `placement.pin` dans le manifeste |446447Séquence proposée :4484491. `scripts/mccctl freeze` ; arrêter les quatre processus sur l'ancien nœud (les agents commencent à tamponner :450 fenêtre de 6 h).4512. `scripts/mccctl backup --dir ~/mcc-backups` puis `backup-verify`.4523. Copier le fichier de sauvegarde et `~/.config/mcc/` (mode 0700/0600) vers le nouveau nœud.4534. Nouveau nœud : prérequis (§1.1), `createdb mcc`, `scripts/mccctl restore --file … --to …/mcc`.4545. Construire, démarrer, basculer la route publique.4556. `scripts/mccctl status`, `audit-verify`, puis `unfreeze`.456457Les agents n'ont rien à changer : ils parlent à `https://clustr.spboucher.ai` et vérifient la même AC. Les sessions458des utilisateurs restent valides (elles sont dans la base restaurée, et l'origine ne change pas).459460## 10. Environnements de développement et de test461462Voir le [README](../README.md) : pile locale, `make ci`, test de bout en bout `tests/e2e/local-stack.sh`, suite463Playwright (`apps/web/e2e/run.mjs`). Les outils `telemetry-ingest dev-token`, `dev-proxy`, `migrate` et464`mcc-devlogin` refusent de s'exécuter quand `MCC_ENV=prod`.465466## 11. Dépannage467468| Symptôme | Cause probable | Correction |469|---|---|---|470| `mccctl` : `missing ~/.config/mcc/env` | fichier de configuration absent | le créer (§1.3) ou `MCC_ENV_FILE=<chemin>` |471| `mccctl enroll-token` : « the agent CA is not published yet » | l'ingestion n'a jamais démarré avec la base | démarrer `mcc-telemetry-ingest`, vérifier `:8805/healthz` |472| `mccctl bootstrap-owner` : `owner_exists` | un owner peut déjà se connecter | invitation normale, ou `recovery-invite` |473| `mcc-control-api` redémarre en boucle | base injoignable au démarrage (il n'attend pas), ou configuration `prod` invalide (origine non https, `MCC_RP_ID=localhost`) | vérifier PostgreSQL et `~/.pm2/logs/mcc-control-api-*.log` |474| Pages en `503 unavailable`, API correcte | `mcc-web` arrêté | `pm2 restart mcc-web` ; vérifier que `dist/web/server.js` existe (`make web-release`) |475| Tous les nœuds `stale` puis `offline` | ingestion arrêtée, ou chemin public coupé | `pm2 logs mcc-telemetry-ingest` ; les agents rejouent jusqu'à 6 h |476| Un nœud `offline` | machine éteinte ou en veille, agent arrêté, agent révoqué | sur le nœud : `mcc-agent status`, journal de l'agent |477| `install.sh` : « no graphical session … use --daemon » | pas de session graphique ouverte | relancer avec `--daemon` |478| Agent : `connect: no route to host` vers une adresse LAN | confidentialité du réseau local de macOS (binaire lancé par launchd) | utiliser `--endpoints https://clustr.spboucher.ai` |479| Agent : `401 timestamp_out_of_window` ou `400 clock_skew` | horloge du nœud fausse (> 90 s) | corriger l'heure |480| Agent : `401 agent_revoked` | agent révoqué ou remplacé par un ré-enrôlement | nouveau jeton, ré-enrôler |481| Enrôlement : `409 alias_in_use` | l'alias appartient à un autre matériel | choisir un autre alias, ou retirer l'ancien nœud |482| Enrôlement : `429` | plus de 6 tentatives/min depuis la même adresse | attendre (`Retry-After`) |483| Toute commande refusée par un agent | `policy.json` invalide ou trop permissif en droits de fichier ; fichier `FREEZE` présent | `mcc-agent policy check` ; `chmod 600` ; supprimer `FREEZE` |484| Action : `422 capability_missing` | la politique locale du nœud n'autorise pas ce type | adapter `policy.json` sur le nœud (§5) |485| Action : `422 agent_offline` | agent non vu depuis plus de 120 s | voir « un nœud offline » |486| Action : `409 target_locked` | une autre action est en cours sur la cible | attendre ; `details.action_id` donne le détenteur |487| Action `timed_out`, `outcome_unknown` | commande remise, résultat jamais reçu | vérifier l'état réel sur le nœud **avant** de relancer |488| `503 orchestrator_frozen` | gel d'urgence actif | `scripts/mccctl unfreeze` après vérification |489| Actions qui restent `queued` | orchestrateur arrêté, ou gel | `/admin/status`, `pm2 restart mcc-action-orchestrator` |490| `403 step_up_required` | dernière cérémonie passkey vieille de plus de 5 min | refaire le step-up (l'interface le propose) |491| `403 csrf_failed` | en-tête `X-MCC-CSRF` ou `Origin` absent ; accès par une autre origine que `MCC_PUBLIC_ORIGIN` | relire `GET /me` ; utiliser l'URL publique |492| `429` sur la page de connexion | plus de 30 requêtes publiques/min depuis la même adresse (ou `MCC_TRUSTED_PROXIES` incomplet : tout le monde partage l'adresse de la passerelle) | attendre ; corriger la liste des proxys |493| Sauvegarde : « off-host copy … failed » | alias SSH `mcc-backup` ou second nœud indisponible | la sauvegarde locale existe ; rétablir la copie |494| Restauration : `authentication failed` | mauvaise `backup.key`, ou fichier altéré | retrouver la clé d'origine |495| `/admin/status` : sauvegarde `unknown` | aucun `mccctl backup` enregistré | lancer une sauvegarde |496| Réglage de rétention modifié sans effet | l'ingestion lit `MCC_RETAIN_*` au démarrage, pas le réglage | changer la variable et redémarrer l'ingestion |497498## 12. Arrêt d'urgence499500Du moins au plus radical :5015021. **Geler les commandes** : `scripts/mccctl freeze`. La télémétrie et la consultation continuent.5032. **Couper un nœud** : `touch ~/.mcc-agent/FREEZE` sur le nœud, ou révoquer son agent.5043. **Arrêter le plan de contrôle** : `pm2 stop mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web`.505 L'interface et l'API ne répondent plus ; les agents tamponnent ; aucune commande ne peut partir.5064. **Fermer l'exposition publique** : retirer la route du domaine sur la passerelle (outil de déploiement).5075. **Retirer les agents** : `uninstall.sh` sur chaque nœud (ils n'écoutent sur aucun port ; arrêtés, ils ne font508 plus rien).509510Reprise : démarrer l'ingestion, l'orchestrateur, l'API, le web ; `status` ; `audit-verify` ; `unfreeze`.511L'ancien produit n'est pas concerné par ces opérations (ADR 0001).512