MacLustr Command Center (MCC)
Poste de pilotage d'une infrastructure de machines Apple Silicon (et d'une passerelle Linux) : un agent sans root sur chaque machine, un plan de contrôle Go + PostgreSQL, une application web, une application macOS et une application iOS / iPadOS natives — toutes branchées sur le même contrat OpenAPI.
Author: Simon-Pierre Boucher
Sommaire
- 🎯 Vue d'ensemble
- 👪 Famille : un dépôt, trois clients
- ✨ Fonctionnalités
- 🏗 Architecture
- 🧱 Pile technique
- 🗂 Carte du dépôt
- 🚀 Démarrage rapide (développement local)
- 🔧 Configuration
- 🔌 API
- 🖥 Écrans
- 🎬 Actions typées
- 🗄 Modèle de données
- 🔐 Sécurité
- 🧪 Tests
- 📦 Construire et déployer
- 🍎 Applications Apple
- 🛰 Agents
- 💾 Sauvegarde et arrêt d'urgence
- 🩺 Dépannage
- 🚧 État, limites connues, reste à faire
- 📚 Documentation
- 👤 Auteur
- 📄 Licence
🎯 Vue d'ensemble
MacLustr Command Center (MCC) est un poste de pilotage d'infrastructure : inventaire et télémétrie rapportés par un agent sur chaque machine, services, serveurs d'inférence, stockage, alertes et incidents, calendrier d'entretien, jobs, et actions typées sur les nœuds — avec passkeys, rôles, journal d'audit chaîné et sauvegardes chiffrées.
- Plan de contrôle version
0.1.0(2026-11-18), en production sur https://clustr.spboucher.ai. - Applications Apple version
1.0.0build2(apps/macos/project.yml,apps/ios/project.yml). - Produit écrit à partir d'un dépôt vide ; il cohabite avec l'ancienne application « MacLustr » sans la lire ni la modifier (ADR 0001).
- Principe d'honnêteté de l'interface : une valeur non mesurable est déclarée
unsupported,permission_deniedouunavailable— jamais estimée, jamais remplacée par 0 (docs/METRICS-CATALOG.md).
Ce qui est fait, ce qui est vérifié et ce qui ne l'est pas : docs/ACCEPTANCE.md.
À savoir d'emblée (état décrit par la documentation du dépôt, rédigée les 18 et 19 novembre 2026) : température et puissance ne sont pas mesurées (agent sans root) ; la livraison des notifications push n'est pas vérifiée de bout en bout ;
ACCEPTANCE.mdetINTEGRATION-TODO.mdindiquent qu'aucun compte owner n'existait en production au commit45f0d03; la suite Go, en échec sur un test à ce commit, est verte sur les 26 paquets depuis le commit suivant. Voir État, limites connues, reste à faire.
👪 Famille : un dépôt, trois clients
Contrairement aux autres familles de spbgit (un dépôt web + un dépôt Apple), tout vit ici dans le même dépôt : git.spboucher.ai/maclustr-command-center.
| Client | Chemin | Technologie | Identifiant | Distribution |
|---|---|---|---|---|
| 🌐 Web | apps/web/ |
Next.js 16, React 19, TypeScript strict | https://clustr.spboucher.ai |
servi derrière control-api (même origine) |
| 🖥 macOS | apps/macos/ |
SwiftUI, macOS 15.0+, Swift 6 | ai.spboucher.clustr |
Developer ID + notarisation (Scripts/release.sh) |
| 📱 iOS / iPadOS | apps/ios/ |
SwiftUI universel, iOS 18.0+, Swift 6 | ai.spboucher.clustr.ios |
TestFlight (fiche App Store Connect 6836652715, « MacLustr CC ») |
| 📦 Socle Swift | packages/swift-core/ |
paquet MCCCore (macOS 15 / iOS 18) |
— | consommé par les deux apps |
| 📜 Contrat | packages/api-contracts/ |
OpenAPI 3.1, 132 opérations | — | génère le serveur Go, les types TS et le client Swift |
✨ Fonctionnalités
| Domaine | Ce que fait le code |
|---|---|
| Tableau de bord | vue d'ensemble, disponibilité par fraîcheur, capacité avec couverture, tendances, disposition par utilisateur, centre d'opérations plein écran (/ops) |
| Inventaire | nœuds, matériel réel, niveaux de performance CPU nommés, métriques et séries, processus, historique de santé, comparaison de nœuds, inscription manuelle, retrait |
| Services | découverte PM2 / launchd / systemd / docker, état, historique, service « géré », URL publique |
| Modèles d'IA | serveurs d'inférence observés (santé, modèle, port) ; les métriques de requêtes non instrumentées sont affichées comme telles, avec la raison |
| Jobs | modèles déclarés par l'agent, placement sur l'état réel des nœuds, tentatives bornées avec recul, dépendances, planifications, annulation |
| Réseau | interfaces, débits, latence et perte, topologie dessinée avec un tableau équivalent |
| Stockage | volumes, usage, état SMART de base, cibles NAS sondées par les agents, sauvegardes observées |
| Alertes et incidents | règles (seuil, absence, état de service), 12 règles intégrées, hystérésis, silences, suppression en maintenance, acquittement, commentaires, incidents, chronologie, rejeu sur l'historique |
| Entretien | fenêtres, récurrence, fuseaux, mode maintenance automatique, silences, export ICS, notes |
| Actions typées | catalogue de 18 types, confirmation, justification, seconde approbation, idempotence, verrous par cible, signature Ed25519, sortie expurgée, annulation — aucun shell distant (ADR 0008) |
| Audit | journal en ajout seul, chaîne de hachage, consultation, vérification, export signé vérifiable hors ligne |
| Identité | passkeys seulement (WebAuthn, vérification de l'utilisateur obligatoire, identifiants découvrables), connexion sans nom d'utilisateur, step-up, sessions web (cookie) et natives (jetons rotatifs), appareils, 4 rôles |
| Invitations | usage unique, durée courte, jeton dans le fragment d'URL, profil, liaison à un compte existant, récupération hors bande (mccctl recovery-invite) |
| Administration | utilisateurs, octrois (allow / deny par ressource), agents et jetons d'enrôlement, réglages, état du backend |
| Temps réel | flux SSE durable, reprise par Last-Event-ID, resynchronisation, filtrage par permission |
| Agents | sans root, sans port en écoute, enrôlement par jeton à usage unique, tampon hors ligne (6 h / 20 Mio), renouvellement de certificat, révocation ; macOS (launchd) et Linux (systemd) |
| Sauvegardes | pg_dump chiffré AES-256-GCM en flux, relu et authentifié, copie hors hôte, test de restauration |
| Interfaces | français et anglais, thèmes sombre et clair, mobile, accessibilité (axe, WCAG 2.2 AA sur les écrans principaux), CSP à nonce |
🏗 Architecture
Référence complète (diagrammes C4, flux, frontières de confiance, modes dégradés, capacité) : docs/ARCHITECTURE.md.
flowchart TB
subgraph clients["Clients"]
browser["Navigateur"]
apple["Apps macOS / iOS (MCCCore)"]
agents["mcc-agent × N<br/>(sortie seulement, sans root)"]
end
gw["Passerelle publique<br/>MacLustr Tunnel (Caddy TLS + WireGuard)"]
subgraph host["Nœud hôte — M4M64c"]
api["control-api (Go) :8800<br/>REST /api/v1 · SSE · WebAuthn · AASA<br/>relais /agent/v1 · proxy web"]
web["web (Next.js standalone) :8803"]
ingest["telemetry-ingest (Go)<br/>:8804 requêtes signées · :8801 mTLS · :8805 santé"]
orch["action-orchestrator (Go) :8802<br/>actions · jobs · alertes · notifications<br/>calendrier d'entretien · ménage"]
pg[("PostgreSQL 17<br/>base mcc")]
ctl["mccctl (CLI hors bande)"]
bk["mcc-backup (cron 03:40)"]
end
backup["Second nœud<br/>(copie chiffrée des sauvegardes)"]
browser --> gw
apple --> gw
agents --> gw
gw --> api
api -- "tout sauf /api, /agent, AASA" --> web
api -- "/agent/v1/* (relais)" --> ingest
api --> pg
ingest --> pg
orch --> pg
ctl --> pg
bk --> pg
bk -- "rsync restreint" --> backup
Points structurants :
- Un seul module Go (
services/go.mod,go 1.26) pour les six binaires :control-api,telemetry-ingest,action-orchestrator,mccctl,mcc-agent,mcc-devlogin. - Coordination par PostgreSQL uniquement : tables durables et
LISTEN/NOTIFY(canauxmcc_events,mcc_commands,mcc_command_updates,mcc_actions). Ni Redis ni file de messages (ADR 0003). - Contrat d'abord (ADR 0006) :
packages/api-contracts/openapi.yamlgénère le serveur strict Go (services/internal/api/gen.go), la table de sécurité par opération (ops_gen.go), les types TypeScript (apps/web/src/api/schema.d.ts) et le client Swift (packages/swift-core/Sources/MCCCore/Generated). - Sécurité appliquée centralement :
core.admit(services/internal/api/server.go) enchaîne identifiants → limites → CSRF → permission → step-up, et refuse toute opération absente de la table générée. - Agents en sortie seulement : le transport par défaut est la requête HTTPS signée (certificat + horodatage +
nonce + signature ECDSA, fenêtre ±90 s) relayée par
control-api(ADR 0004 et son amendement) : macOS bloque les connexions LAN d'un binaire lancé par launchd (constat mesuré sur le nœud pilote). - Web sans récupération de données côté serveur : chaque page est une coquille rendue côté client qui n'appelle
que
/api/v1;apps/web/src/proxy.tspose une CSP à nonce par requête.
Flux d'une action (au plus une commande par action)
sequenceDiagram
participant U as Utilisateur
participant C as control-api
participant P as PostgreSQL
participant O as action-orchestrator
participant I as telemetry-ingest
participant A as mcc-agent
U->>C: POST /actions (Idempotency-Key)
C->>C: permission sur la cible, step-up, confirmation, justification, pré-vérifications
C->>P: INSERT actions (+ action_locks) + audit, NOTIFY mcc_actions
C-->>U: 201 Action (queued ou pending_approval)
opt criticité critical
U->>C: POST /actions/{id}/approve (autre personne, step-up)
end
O->>P: prend l'action (FOR UPDATE SKIP LOCKED), refait les pré-vérifications
O->>O: signe l'enveloppe (Ed25519, validité 90 s, nonce)
O->>P: INSERT agent_commands (1 par action), NOTIFY mcc_commands
A->>I: GET /agent/v1/commands?wait=25 (long-poll)
I-->>A: SignedCommand (remise une seule fois)
A->>A: FREEZE ? signature, destinataire, expiration, nonce, politique locale, paramètres
A->>I: ack, events (sortie expurgée), result
I->>P: agent_commands, action_events, NOTIFY mcc_command_updates
O->>P: réconcilie : succeeded / failed / timed_out (+ outcome_unknown), libère le verrou
C-->>U: SSE action.changed / action.output
Propriété centrale (ADR 0010) : une action émet au plus une
commande (index unique agent_commands_one_per_action) et rien ne la ré-émet. Une commande jamais remise finit
failed / agent_unreachable ; une commande remise sans résultat finit timed_out avec outcome_unknown=true —
une issue inconnue est un état, jamais une relance.
L'orchestrateur
Une boucle principale et des tâches périodiques, chacune sous un verrou consultatif PostgreSQL :
| Tâche | Période | Paquet |
|---|---|---|
| Actions (expiration d'approbation, émission, réconciliation) | sur notification + balayage 2 s | services/internal/orchestrator |
| Jobs (placement, tentatives, planifications) | 2 s | services/internal/jobs |
| Alertes (évaluation des règles) | 15 s | services/internal/alerts |
Notifications (file alert_notifications → APNs) |
5 s | services/internal/notify |
| Calendrier d'entretien (début / fin des fenêtres) | 10 s | services/internal/maintenance |
| Ménage | 1 h | services/internal/orchestrator/housekeeping.go |
Modes dégradés (résumé)
| Situation | Comportement |
|---|---|
| Base indisponible | ingestion : 503 + Retry-After, les agents tamponnent ; orchestrateur : reprend avec recul puis réconcilie ; control-api : /health/ready → 503, SSE fermé (au démarrage il n'attend pas la base, PM2 le relance) |
| Ingestion arrêtée ou chemin public coupé | les agents tamponnent 6 h / 20 Mio puis rejouent sans doublon ; les nœuds passent stale puis offline |
| Agent hors ligne | nœud offline après 120 s ; action refusée 422 agent_offline |
| Redémarrage de l'orchestrateur | aucun état en mémoire, aucune seconde commande émise |
| Web (Next) arrêté | pages en 503 unavailable, l'API reste disponible |
| Gel d'urgence | aucune commande émise ; POST /actions → 503 orchestrator_frozen |
🧱 Pile technique
| Couche | Technologie | Version (lue dans le dépôt) | Rôle |
|---|---|---|---|
| Services et agent | Go, binaires statiques (CGO_ENABLED=0) |
1.26 | control-api, telemetry-ingest, action-orchestrator, mccctl, mcc-agent |
| Base | PostgreSQL partitionné (sans TimescaleDB) | 17 | état, séries temporelles, file d'événements, verrous |
| Pilote SQL | jackc/pgx |
5.13.0 | accès PostgreSQL |
| Identité | go-webauthn/webauthn |
0.18.2 | passkeys |
| Contrat | OpenAPI + kin-openapi, oapi-codegen/runtime |
3.1.0 · 0.153.0 · 1.9.0 | serveur strict généré |
| Encodage | fxamacker/cbor |
2.9.4 | CBOR |
| Web | Next.js (App Router, sortie standalone), React |
16.4.6 · 19.3.1 | interface |
| Web — données | @tanstack/react-query, openapi-fetch, @tanstack/react-virtual |
5.108 · 0.17 · 3.14 | cache, client typé, listes virtualisées |
| Web — graphiques | uPlot | 1.6.32 | séries temporelles |
| Web — langage | TypeScript strict, ESLint | 5.9.3 · 9.39 | — |
| Web — tests | Vitest, Playwright, @axe-core/playwright, jsdom |
5.1.1 · 1.65.1 · 4.14 · 31 | unitaires, bout en bout, accessibilité |
| Gestionnaire | pnpm | 11.1.2 | apps/web |
| Jetons de design | packages/ui-tokens (tokens.json → CSS, TypeScript, Swift) |
— | une seule palette pour trois clients |
| Apple | Swift (mode langage 6, concurrence stricte), SwiftUI, XcodeGen | 6.0 | apps macOS 15.0+ et iOS 18.0+ |
| Apple — client | swift-openapi-runtime, swift-openapi-urlsession, swift-http-types |
≥ 1.8.0 · ≥ 1.1.0 · ≥ 1.3.0 | client généré, committé |
| Exploitation | PM2, mld, MacLustr Tunnel (Caddy + WireGuard) |
— | processus, placement, exposition publique |
🗂 Carte du dépôt
maclustr-command-center/ 830 fichiers suivis
├── services/ module Go unique (go 1.26)
│ ├── cmd/ control-api · telemetry-ingest · action-orchestrator · mccctl · mcc-agent · mcc-devlogin
│ └── internal/ 26 paquets : api, identity, authz, audit, events, protocol, ingest, pki, agent,
│ │ actions, orchestrator, jobs, alerts, notify, maintenance, backup, db, config,
│ │ httpx, ids, redact, secret, signkey, svc, buildinfo, testdb
│ └── db/migrations/ 0001_init … 0006_ops (schéma PostgreSQL, source de vérité avec le contrat)
├── packages/
│ ├── api-contracts/ openapi.yaml (OpenAPI 3.1, 132 opérations) + conventions
│ ├── ui-tokens/ tokens.json + build.mjs → CSS, TypeScript, Swift
│ └── swift-core/ paquet MCCCore : client généré, passkeys, sessions, SSE, cache hors ligne, composants
├── apps/
│ ├── web/ Next.js 16 / React 19 ; DESIGN-SYSTEM.md ; Vitest ; e2e Playwright (9 specs)
│ ├── macos/ app SwiftUI (project.yml XcodeGen, Sources, Tests, UITests, Scripts)
│ └── ios/ app SwiftUI universelle iPhone + iPad (même organisation)
├── agents/ build.sh + empaquetage launchd (macos/) et systemd (linux/)
├── infra/
│ ├── deploy/ mld-manifest.json · rollout-agents.sh
│ └── apple/ provision.py · asc.py · testflight.py (API App Store Connect)
├── scripts/mccctl lanceur de mccctl sur l'hôte, avec la configuration de production
├── tests/e2e/local-stack.sh essai de bout en bout avec les vrais binaires
├── tools/gen-api.py génération du code serveur depuis le contrat
├── docs/ architecture, sécurité, exploitation, API, recette, protocole agent, ADR, captures
├── Makefile CI locale reproductible (make ci)
├── CHANGELOG.md · VERSION 0.1.0
└── README.md| Chemin | Contenu |
|---|---|
services/ |
module Go unique : cmd/control-api, cmd/telemetry-ingest, cmd/action-orchestrator, cmd/mccctl, cmd/mcc-agent, cmd/mcc-devlogin ; paquets dans internal/ |
services/internal/db/migrations/ |
schéma PostgreSQL (source de vérité avec le contrat) |
packages/api-contracts/ |
contrat OpenAPI 3.1 (openapi.yaml, 132 opérations) et ses conventions |
packages/ui-tokens/ |
jetons de design → CSS, TypeScript, Swift |
packages/swift-core/, apps/macos/, apps/ios/ |
clients Apple — voir docs/APPLE-APPS.md |
apps/web/ |
application web (Next.js 16, React 19) ; DESIGN-SYSTEM.md ; tests unitaires et Playwright |
agents/ |
construction et empaquetage de l'agent (launchd pour macOS, systemd pour Linux) |
infra/deploy/ |
manifeste de déploiement (mld-manifest.json), déploiement des agents (rollout-agents.sh) |
infra/apple/ |
scripts du compte Apple Developer (voir APPLE-APPS.md) |
scripts/mccctl |
lanceur de mccctl sur l'hôte, avec la configuration de production |
tests/e2e/local-stack.sh |
essai de bout en bout avec les vrais binaires |
tools/gen-api.py |
génération du code serveur depuis le contrat |
docs/ |
documentation de référence (ci-dessous) |
🚀 Démarrage rapide (développement local)
Prérequis : Go 1.26, Node et pnpm (apps/web/package.json fixe pnpm@11.1.2), PostgreSQL 17 en écoute sur
127.0.0.1, Python 3 avec PyYAML (génération du code depuis le contrat).
La référence exécutable est tests/e2e/local-stack.sh : il enchaîne exactement ces étapes sur une base jetable.
À la main, avec les ports par défaut de services/internal/config/config.go :
createdb mcc_dev
# Garder les secrets de développement à part : le défaut de MCC_SECRETS_DIR est ~/.config/mcc.
export MCC_ENV=dev MCC_SECRETS_DIR="$HOME/.config/mcc-dev" MCC_INGEST_ADVERTISE=http://localhost:8730
cd services
go run ./cmd/control-api & # http://localhost:8730 — applique les migrations
go run ./cmd/telemetry-ingest serve & # 8731 (mTLS), 8734 (requêtes signées), 8741 (santé)
go run ./cmd/action-orchestrator & # 8732 (santé)
cd ../apps/web && pnpm install && pnpm dev # 127.0.0.1:8733, à consulter via http://localhost:8730Premier compte (lien à usage unique, à ouvrir dans le navigateur ; RP ID localhost) :
cd services && go run ./cmd/mccctl bootstrap-owner --handle moi --name "Moi"Agent local (le poste de développement devient un nœud, avec ses vraies métriques) :
cd services
TOKEN=$(go run ./cmd/telemetry-ingest dev-token --alias mon-poste | tail -1)
FP=$(curl -fsS localhost:8741/healthz | python3 -c "import sys,json;print(json.load(sys.stdin)['ca_fingerprint'])")
go run ./cmd/mcc-agent enroll --endpoints http://localhost:8730 --token "$TOKEN" --ca-fingerprint "$FP" --state-dir /tmp/mcc-agent-dev
go run ./cmd/mcc-agent run --state-dir /tmp/mcc-agent-devOutils réservés au développement (ils refusent MCC_ENV=prod) : telemetry-ingest dev-token, dev-proxy,
migrate ; mcc-devlogin (crée un owner avec un authentificateur logiciel et imprime un jeton d'accès pour
essayer l'API à la main).
Régénérer le code après une modification du contrat ou des jetons : make gen (ne jamais modifier le code
généré à la main).
| Port de développement | Service |
|---|---|
| 8730 | control-api (origine à consulter) |
| 8731 · 8734 · 8741 | telemetry-ingest : mTLS · requêtes signées · santé |
| 8732 | action-orchestrator (santé) |
| 8733 | web (next dev) |
| 8750 · 8753 | Playwright (pnpm e2e) |
| 8760 | backend local de l'app macOS (packages/swift-core/Scripts/local-backend.sh) |
| 8770–8775 | tests/e2e/local-stack.sh |
| 8780 · 8782 | backend local des tests iOS (apps/ios/Scripts/local-backend.sh) |
🔧 Configuration
Variables MCC_* — liste complète et défauts dans services/internal/config/config.go. Noms seulement ; les
valeurs de production sont dans le manifeste infra/deploy/mld-manifest.json et
docs/OPERATIONS.md §1.3.
| Variable | Rôle |
|---|---|
MCC_ENV |
dev ou prod ; en prod le démarrage échoue si l'origine n'est pas en https ou si MCC_RP_ID vaut localhost |
MCC_DATABASE_URL |
connexion PostgreSQL |
MCC_SECRETS_DIR |
répertoire des secrets créés au premier démarrage (fichiers 0600) |
MCC_PUBLIC_ORIGIN, MCC_RP_ID |
origine publique et Relying Party WebAuthn |
MCC_API_LISTEN, MCC_WEB_UPSTREAM |
écoute de control-api, amont Next.js |
MCC_TRUSTED_PROXIES |
proxys dont X-Forwarded-For est cru (la passerelle) |
MCC_INGEST_LISTEN, MCC_INGEST_SIGNED_LISTEN, MCC_INGEST_HEALTH_LISTEN, MCC_INGEST_ADVERTISE, MCC_INGEST_SERVER_NAME |
écoutes et adresse annoncée de l'ingestion |
MCC_ORCHESTRATOR_LISTEN |
santé de l'orchestrateur |
MCC_ACCESS_TTL, MCC_REFRESH_TTL, MCC_SESSION_IDLE, MCC_SESSION_ABSOLUTE, MCC_STEPUP_WINDOW |
durées des jetons, des sessions et de la fenêtre de step-up (5 minutes) |
MCC_FRESH_AFTER, MCC_OFFLINE_AFTER |
seuils de fraîcheur (stale, puis offline après 120 s) |
MCC_RETAIN_RAW, MCC_RETAIN_1M, MCC_RETAIN_1H |
rétention des séries (7 jours · 30 jours · 400 jours) |
MCC_APPLE_APP_IDS |
identifiants d'apps listés dans l'AASA (<équipe>.ai.spboucher.clustr, <équipe>.ai.spboucher.clustr.ios) |
MCC_APNS_KEY_FILE, MCC_APNS_KEY_ID, MCC_APNS_TEAM_ID, MCC_APNS_TOPIC_IOS, MCC_APNS_TOPIC_MACOS |
fournisseur APNs (la clé elle-même reste dans le répertoire des secrets de l'hôte) |
MCC_TEST_ADMIN_URL |
tests d'intégration Go : serveur PostgreSQL des bases jetables |
MCC_ENV_FILE |
chemin du fichier de configuration lu par scripts/mccctl |
Les secrets ne se configurent pas : chaque service crée le sien au premier démarrage dans MCC_SECRETS_DIR.
Aucun secret n'est dans le dépôt (.gitignore : *.key, *.pem, *.p8, .env*, secrets/) ni dans la table
settings. Le fichier env lu par scripts/mccctl ne contient que de la configuration.
Variables de lancement Debug uniquement des apps Apple (absentes du binaire Release, vérifié par les scripts) :
MCC_BASE_URL, MCC_PASSKEY=software, MCC_SECURE_STORE=keychain|file|memory, MCC_SETUP_TOKEN, MCC_OPEN_URL.
🔌 API
Base /api/v1, contrat packages/api-contracts/openapi.yaml
(OpenAPI 3.1.0, 132 opérations sur 104 chemins). Guide, exemples complets, table des permissions et écarts
connus : docs/API.md.
| Étiquette | Opérations | Étiquette | Opérations |
|---|---|---|---|
| Admin | 20 | Storage | 5 |
| Auth | 19 | Services | 4 |
| Alerts | 19 | Audit | 3 |
| Nodes | 11 | Dashboards | 3 |
| Maintenance | 11 | Meta (santé, version) | 3 |
| Jobs | 9 | Cluster | 2 |
| Invitations | 8 | Models | 2 |
| Actions | 8 | Network | 2 |
| Events (SSE), Activity, Search | 1 chacune |
Conventions : erreurs avec code, message et identifiant de corrélation ; limit de 1 à 200 sur les listes ;
Idempotency-Key (8 à 128 caractères) ; en-tête X-MCC-CSRF + Origin pour les sessions à cookie ;
403 step_up_required rejoué par les clients après la cérémonie passkey.
Flux d'événements (GET /api/v1/events, SSE) : sujets node.state, node.updated, service.changed,
alert.changed, incident.changed, action.changed, action.output, job.changed, maintenance.changed,
audit.appended, resync (+ trame hello). Conseil d'intégration tant que des écarts avec le contrat existent :
traiter chaque événement comme un signal de rechargement de la ressource REST concernée.
Limites de débit telles qu'implémentées (en mémoire, remises à zéro au redémarrage) : 30/min par IP (rafale 15)
pour le public, 900/min par session, 30/min par utilisateur sur POST /actions, 20/min par IP sur l'enrôlement
d'agent. Dépassement : 429 rate_limited + Retry-After.
Protocole agent (/agent/v1/* : enroll, renew, report, commands) :
docs/AGENT-PROTOCOL.md.
🖥 Écrans
Web — 31 pages (apps/web/src/app)
| Groupe | Routes |
|---|---|
| Public | /signin, /setup (invitation) |
| Vue d'ensemble | /, /ops (centre d'opérations) |
| Nœuds | /nodes, /nodes/[id], /nodes/compare |
| Services, modèles, jobs | /services, /services/[id], /models, /jobs, /jobs/[id] |
| Réseau, stockage | /network, /storage |
| Alertes, incidents | /alerts, /alerts/[id], /incidents, /incidents/[id] |
| Actions, entretien | /actions/[id], /maintenance, /maintenance/[id] |
| Activité, audit | /activity, /audit |
| Réglages | /settings, /settings/security, /settings/users, /settings/invitations, /settings/grants, /settings/agents, /settings/system |
| Développement | /dev/ui |
macOS et iOS — sections natives
Mêmes domaines dans les trois clients : Vue d'ensemble, Nœuds, Alertes, Actions, Services, Modèles d'IA, Jobs, Entretien, Réseau, Stockage, Activité, Audit, Réglages (+ recherche universelle).
- iPhone (et fenêtre iPad compacte) :
TabView— Vue d'ensemble, Nœuds, Alertes, Actions, Plus. - iPad (largeur régulière) :
NavigationSplitViewavec toutes les sections ; liste et élément côte à côte ; ⌘1…⌘9, ⌘R, ⌘F, ⇧⌘N ; plusieurs fenêtres. - macOS : fenêtres, barre latérale, extra de barre des menus, palette de commandes, notifications, liens profonds, verrou local.
- Liens :
https://clustr.spboucher.ai/setup#<jeton>(invitation) ethttps://clustr.spboucher.ai/open/<section>[/<uuid>].
Captures (78 fichiers)
| Dossier | Contenu |
|---|---|
docs/screenshots/web/ |
21 captures (connexion, vue d'ensemble, nœuds, services, modèles, jobs, réseau, stockage, alertes, entretien, activité, audit, réglages, centre d'opérations, mobile) |
docs/screenshots/macos/ |
25 captures d'un build Debug contre un backend local |
docs/screenshots/ios/ |
32 captures iPhone et iPad (Dynamic Type maximal, hors ligne, refus viewer…) |
Aperçu : vue d'ensemble web, macOS et iPhone


🎬 Actions typées
Catalogue de 18 types (services/internal/actions/catalog.go). Aucune commande libre, aucun shell. Les
exigences découlent de la criticité seule :
| Criticité | Permission | Step-up | Justification | Confirmation saisie | Seconde approbation |
|---|---|---|---|---|---|
low |
actions.run.low |
— | — | — | — |
medium |
actions.run.medium |
— | — | — | — |
high |
actions.run.high |
oui | — | — | — |
critical |
actions.run.critical (owner) |
oui | oui | oui (alias de la cible, comparé par le serveur) | oui (autre personne, actions.approve, step-up) |
| Type | Criticité | Verrou | État en v1 |
|---|---|---|---|
inventory.refresh, diagnostic.run |
low | nœud | disponibles ; autorisés par défaut sur tous les agents |
service.health_check |
low | service | disponible ; autorisé par défaut |
service.logs.tail |
low | aucun | disponible ; exige aussi logs.read ; autorisé par défaut |
service.restart, service.start |
medium | service | disponibles ; exigent service managed + liste blanche locale |
service.stop |
high | service | idem |
agent.restart, cache.purge |
medium | nœud | disponibles ; exigent la politique locale |
node.maintenance.set |
medium | nœud | exécuté par le serveur (aucune commande agent) |
job.run |
medium | job | interne : créé seulement par POST /jobs |
job.cancel |
medium | aucun | exécuté par le serveur |
model.server.start, model.server.stop |
high | nœud | au catalogue mais non implémentés par l'agent v1 (422 capability_missing) |
deploy.release, system.update.schedule |
high | service / nœud | désactivés (422 action_unavailable) |
system.reboot, system.shutdown |
critical | nœud | implémentés ; désactivés sur chaque agent par la politique locale |
Chaîne de contrôles de POST /actions, dans l'ordre du code : limite 30/min → Idempotency-Key → type connu, non
interne, disponible → schéma des paramètres → permission(s) sur le nœud et la cible → step-up → rejeu idempotent →
gel d'urgence → confirmation → justification → pré-vérifications → insertion + verrou + audit dans une transaction.
Chaque refus est audité et ne laisse aucune ligne d'action. Les pré-vérifications sont refaites par
l'orchestrateur juste avant la signature.
| Mécanisme | Détail |
|---|---|
| Idempotence | même clé + même corps → même action (200) ; même clé + corps différent → 409 idempotency_conflict |
| Verrou | un verrou par cible ; seconde action concurrente → 409 target_locked avec l'id du détenteur |
| Approbation | état pending_approval, expire après 30 min ; le demandeur ne peut ni approuver ni rejeter |
| Signature | enveloppe Ed25519, validité 90 s (120 s au plus acceptés par l'agent), nonce, destinataire |
| Anti-rejeu | nonce journalisé sur disque par l'agent avant acceptation |
| Bornes d'exécution | délai par type, 2 commandes simultanées au plus par agent et une par cible, sortie plafonnée et expurgée |
🗄 Modèle de données
Schéma : services/internal/db/migrations/0001_init.sql à 0006_ops.sql (6 migrations, 49 CREATE TABLE),
appliqué au démarrage par control-api et action-orchestrator (un fichier par transaction, verrou consultatif,
somme de contrôle : une migration déjà appliquée puis modifiée est refusée). Clés primaires en UUID v7,
horodatages lus en UTC.
erDiagram
users ||--o{ passkeys : "possède"
users ||--o{ devices : "possède"
devices ||--o{ sessions : "porte"
sessions ||--o{ refresh_tokens : "rotation (natif)"
users ||--o{ invitations : "crée"
invitations ||--o{ invitation_transactions : "ouvre"
nodes ||--o| agents : "1 agent actif"
nodes ||--o| node_state : "dernier état"
nodes ||--o{ services : "héberge"
nodes ||--o{ inference_servers : "héberge"
nodes ||--o{ volumes : "monte"
nodes ||--o{ samples_raw : "mesure"
alert_rules ||--o{ alerts : "déclenche"
incidents ||--o{ alerts : "regroupe"
actions ||--o| agent_commands : "au plus 1"
actions ||--o{ action_events : "journalise"
actions ||--o| action_locks : "verrouille"
jobs ||--o{ actions : "1 par tentative"
job_schedules ||--o{ jobs : "planifie"
maintenance_windows ||--o{ maintenance_window_nodes : "vise"
| Domaine | Tables | Remarques |
|---|---|---|
| Identité | users, passkeys, webauthn_challenges, devices, sessions, refresh_tokens, invitations, invitation_transactions |
jetons stockés hachés (SHA-256) uniquement |
| Autorisation | policy_grants |
allow / deny par sujet, permission, ressource |
| Audit | audit_log |
chaîne de hachage ; déclencheurs refusant UPDATE, DELETE, TRUNCATE |
| Inventaire | nodes, agents, agent_enrollment_tokens, node_state, services, service_events, inference_servers, volumes, nas_targets, nas_observations, backups |
un seul agent actif par nœud |
| Séries temporelles | metric_catalog, samples_raw, samples_1m, samples_1h, rollup_state, rollup_dirty, agent_report_seqs |
partitions par plage de temps |
| Alertes | alert_rules, alerts, incidents, timeline_events, silences, alert_notifications |
une alerte ouverte par empreinte |
| Entretien | maintenance_windows, maintenance_window_nodes, maintenance_notes |
|
| Actions et jobs | actions, action_locks, action_events, agent_commands, command_keys, jobs, job_schedules |
|
| Plateforme | events_outbox, settings, service_heartbeats, user_dashboards, schema_migrations |
settings ne contient aucun secret |
Rétention : échantillons bruts (10 s) 7 jours, agrégats 1 min 30 jours, agrégats 1 h 400 jours, events_outbox
1 heure, action_events d'actions terminées 90 jours, audit_log jamais purgé, 14 sauvegardes locales.
Cardinalité bornée par rapport : ≤ 400 échantillons, ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processus, ≤ 200 services.
🔐 Sécurité
Référence : docs/SECURITY.md (modèle de menace STRIDE, passkeys, sessions, CSRF, autorisations, sûreté des actions, confiance des agents, secrets, en-têtes, réponse aux incidents).
- Passkeys seulement (ADR 0005) : aucune connexion par mot de
passe ; sessions opaques (cookie pour le web, jetons d'accès et de rafraîchissement rotatifs pour les apps
natives) ; réutilisation d'un jeton de rafraîchissement → les deux détenteurs sont déconnectés ; récupération
hors bande par
mccctl. - 4 rôles, 26 permissions (
services/internal/authz/authz.go) :
| Rôle | Permissions par défaut |
|---|---|
| viewer | cluster.read, nodes.read, services.read, models.read, jobs.read, alerts.read, maintenance.read, actions.read |
| operator | viewer + nodes.private.read, logs.read, alerts.ack, maintenance.write, jobs.submit, actions.run.low, actions.run.medium |
| admin | operator + nodes.write, alerts.manage, actions.run.high, actions.approve, audit.read, audit.export, users.manage, invitations.manage, agents.manage, settings.manage |
| owner | les 26 permissions, dont actions.run.critical |
- Octrois :
allow/denypar utilisateur ou rôle, éventuellement limités à un nœud, un site, une étiquette ou un service ; undenyapplicable l'emporte toujours ; certaines permissions ne sont accordables qu'à partir d'admin, etactions.run.criticalqu'à un owner. - Step-up : cérémonie passkey de moins de 5 minutes pour 19 opérations d'office et pour toute action
highoucritical. - Agent sans privilège (ADR 0007) : jamais root, aucun port en
écoute, exécution sans shell, sortie expurgée, politique locale
policy.jsonque le serveur ne peut ni lire ni modifier. Fichier absent → quatre commandes de lecture seulement ; fichier invalide ou inscriptible par le groupe ou les autres → toute commande est refusée. - PKI privée : AC ECDSA P-256, certificats d'agent de 30 jours ; commandes signées par l'orchestrateur, seul détenteur de la clé de signature.
- Audit : chaîne de hachage en ajout seul,
mccctl audit-verify, export signé vérifiable hors ligne (mccctl audit-verify-export). - Web : CSP à nonce par requête, HSTS et en-têtes de sécurité, refus des requêtes inter-origines.
- Apps natives : session dans le trousseau (
AfterFirstUnlockThisDeviceOnly, jamais synchronisée vers iCloud), App Sandbox sur macOS, aucune exception ATS en Release, verrou local facultatif (Face ID / Touch ID) qui ne remplace jamais la connexion ni le step-up ; une notification ne peut qu'ouvrir un écran. - Arrêts d'urgence à trois niveaux indépendants : gel global (
mccctl freeze), fichierFREEZEsur un nœud, révocation d'un agent. - Dépôt privé :
docs/REAL-INFRASTRUCTURE-INVENTORY.mdetdocs/recon/contiennent des adresses privées.
🧪 Tests
Les tests d'intégration Go créent des bases jetables mcc_test_<aléatoire> sur le PostgreSQL local
(MCC_TEST_ADMIN_URL, défaut postgres://127.0.0.1/postgres?sslmode=disable). Sans PostgreSQL joignable, ils
sont ignorés, pas en échec (services/internal/testdb).
| Commande | Ce qu'elle fait |
|---|---|
make ci |
porte avant de pousser : gen-check, fmt-check, vet, test, web-ci |
make test |
go test -count=1 ./... |
make test-race |
idem avec le détecteur de courses |
make web-ci |
web : génération du client à jour, tsc, ESLint, Vitest |
cd apps/web && pnpm test |
tests unitaires web (Vitest) |
cd apps/web && pnpm e2e |
Playwright contre le vrai control-api et une base jetable (ports 8750/8753) ; MCC_E2E_SKIP_BUILD=1, MCC_E2E_SCREENSHOTS=1 |
bash tests/e2e/local-stack.sh |
agent réel → relais → ingestion → API, action signée, rejeu idempotent (ports 8770–8775) |
cd packages/swift-core && swift test |
tests unitaires de MCCCore |
packages/swift-core/Scripts/integration-test.sh |
MCCCore contre un vrai control-api local + PostgreSQL jetable |
apps/macos/Scripts/test.sh unit · ui |
tests de logique macOS · XCUITest contre un backend local réel |
apps/ios/Scripts/test.sh unit · ui iphone / ipad / both |
catalogues + tests unitaires iOS · XCUITest sur simulateurs |
make hooks |
installe le crochet pre-push qui lance make ci |
make sbom, make vuln |
inventaire des dépendances ; govulncheck et pnpm audit |
Résultats consignés dans le dépôt :
| Suite | Compte | Source |
|---|---|---|
| Go | 201 fonctions Test… dans 48 fichiers, 26 paquets avec tests |
compté dans services/ |
| Vitest | 172 tests réussis, 23 fichiers | docs/ACCEPTANCE.md §1 (rejoué le 2026-11-18) |
| Playwright (Chromium, authentificateur virtuel) | 94 tests, 9 fichiers de spécifications | rapporté à la fusion, non rejoué |
| Accessibilité web (axe, WCAG 2.2 AA) | 0 violation sur les écrans principaux | rapporté |
tests/e2e/local-stack.sh |
10 vérifications, E2E OK |
rejoué |
MCCCore unitaire |
67 tests dans 10 suites | docs/APPLE-APPS.md §11.8 |
| macOS unitaire · UI | 54 tests · 6 scénarios XCUITest | APPLE-APPS.md §9 |
| iOS unitaire · UI | 54 tests dans 7 suites · 12 scénarios × 2 simulateurs (iPhone 17 Pro, iPad Pro 13 pouces) | APPLE-APPS.md §11.8 |
| Catalogues de chaînes | macOS : 1 416 clés fr/en complètes ; iOS : 1 054 clés fr/en complètes | APPLE-APPS.md |
| IPA Release | 18 / 18 vérifications (Scripts/release.sh verify) |
APPLE-APPS.md §11.8 |
État au commit 45f0d03, rejoué le 2026-11-18 : go vet, gofmt, gen-check propres ; go test ./... :
25 paquets sur 26 réussis, internal/jobs en échec sur TestJobRunsToSuccess (assertion périmée, voir
docs/ACCEPTANCE.md §1) ; Vitest : 172 tests réussis ;
local-stack.sh : E2E OK. Il n'y a pas de CI hébergée.
Corrigé depuis : la suite Go est verte sur les 26 paquets (voir docs/ACCEPTANCE.md).
go test -race a été exécuté sur orchestrator, alerts, maintenance, jobs, notify, actions, audit, api, authz,
identity et events — pas sur ingest ni agent.
📦 Construire et déployer
make build # binaires darwin/arm64 du plan de contrôle dans dist/ (+ SHA256SUMS.backend)
make web-release # serveur Next « standalone » dans dist/web (node dist/web/server.js)
make agents # binaires de l'agent (darwin/arm64, linux/amd64, linux/arm64) + SHA256SUMSProduction
| Élément | Valeur |
|---|---|
| URL publique | https://clustr.spboucher.ai |
| Nœud hôte | M4M64c (épinglé dans le manifeste : la base, l'AC des agents et les clés de signature sont locales) |
| Répertoire | ~/apps/maclustr-command-center = clone git de ce dépôt |
| Exposition | MacLustr Tunnel (Caddy TLS + WireGuard, passerelle BHS64) ; seul le port 8800 est routé |
| Santé | GET /api/v1/health/ready |
| Base | PostgreSQL 17, base mcc, en local sur l'hôte |
| Manifeste | infra/deploy/mld-manifest.json (crochets post_sync : make build, make web-release) |
| Processus PM2 | Écoute | Rôle |
|---|---|---|
mcc-control-api |
0.0.0.0:8800 |
API, SSE, WebAuthn, AASA, relais des agents, proxy web |
mcc-telemetry-ingest |
127.0.0.1:8801 (mTLS), :8804 (requêtes signées), :8805 (santé) |
enrôlement, rapports, transport des commandes, agrégats, rétention |
mcc-action-orchestrator |
127.0.0.1:8802 (santé) |
actions, jobs, alertes, notifications, entretien |
mcc-web |
127.0.0.1:8803 |
serveur Next.js standalone |
mcc-backup |
— (cron 40 3 * * *) |
mccctl backup --keep 14 + copie hors hôte |
Mise à jour sur l'hôte
cd ~/apps/maclustr-command-center
git pull
make build && make web-release
pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web
scripts/mccctl status- Le serveur avant les agents : un agent qui envoie une métrique inconnue du serveur voit son rapport refusé.
- Les migrations nouvelles s'appliquent au redémarrage de
control-apiou de l'orchestrateur. - Pendant le redémarrage : les agents tamponnent et rejouent ; les sessions survivent ; les clients SSE reprennent
avec
Last-Event-ID; une action en vol est réconciliée, jamais ré-émise. - Ne pas déplacer avec
mld movesans suivre docs/OPERATIONS.md §9 : les données et les secrets ne suivent pas. make ciest le seul garde-fou avant de pousser : il n'y a pas de CI hébergée.
mccctl (administration hors bande, sur l'hôte)
~/apps/maclustr-command-center/scripts/mccctl <commande> [options]Commandes : migrate, bootstrap-owner, recovery-invite, audit-verify, audit-verify-export, freeze,
unfreeze, status, backup, backup-verify, restore, restore-test, enroll-token, register-node. Les
opérations qui changent un état écrivent une entrée d'audit actor_kind=cli.
Déploiement, exploitation et procédures d'urgence : docs/OPERATIONS.md.
🍎 Applications Apple
Référence : docs/APPLE-APPS.md, apps/macos/README.md, apps/ios/README.md, packages/swift-core/README.md.
| macOS | iOS / iPadOS | |
|---|---|---|
| Nom | MacLustr Command Center | produit MacLustr, affiché MacLustr CC |
| Bundle id (Release · Debug) | ai.spboucher.clustr · ai.spboucher.clustr.debug |
ai.spboucher.clustr.ios · ai.spboucher.clustr.ios.debug |
| Cible | macOS 15.0 | iOS 18.0, universel iPhone + iPad |
| Version | 1.0.0 (2) | 1.0.0 (2) |
| Langage | Swift 6, concurrence stricte ; SwiftUI (AppKit pour l'ancre passkey, les panneaux d'enregistrement, le presse-papiers) | Swift 6 ; SwiftUI seulement (UIKit pour le délégué APNs et l'ancre passkey) |
| Serveur | https://clustr.spboucher.ai fixe en Release |
idem |
| Passkeys | système (ASAuthorizationPlatformPublicKeyCredentialProvider, RP clustr.spboucher.ai) |
idem |
| Domaines associés | webcredentials: + applinks:clustr.spboucher.ai |
idem |
| Signature | Developer ID Application + profil « MCC macOS Developer ID », notarisation (profil de trousseau MacLustr-Notarize) |
signature automatique Xcode authentifiée par la clé API ; export App Store |
| Distribution | dmg notarisé et agrafé (Scripts/release.sh) |
TestFlight, groupe interne |
# macOS
apps/macos/Scripts/build.sh # Debug → /tmp/mcc-swift/DerivedData/…
apps/macos/Scripts/test.sh unit # ou : ui
apps/macos/Scripts/release.sh # archive → Developer ID → notarisation + agrafage → dmg → vérification
apps/macos/Scripts/verify-release.sh dist/macos/MacLustr-Command-Center-1.0.0-1.dmg
# iOS / iPadOS
cd apps/ios
Scripts/build.sh # Debug simulateur → /tmp/mcc-ios/DerivedData/…
Scripts/local-backend.sh build && Scripts/local-backend.sh start mcc_ios_test_dev
Scripts/test.sh unit && Scripts/test.sh ui both
ASC_ISSUER_ID=<émetteur> Scripts/release.sh archive # incrémenter CURRENT_PROJECT_VERSION d'abord
Scripts/release.sh verify # 18 vérifications sur l'IPA
ASC_ISSUER_ID=<émetteur> Scripts/release.sh upload
ASC_ISSUER_ID=<émetteur> python3 ../../infra/apple/testflight.py [--apply]
# Provisionnement (API App Store Connect ; ASC_KEY_ID et ASC_ISSUER_ID dans l'environnement)
python3 infra/apple/provision.py [--ios] [--check]État consigné :
- iOS (APPLE-APPS.md §11.9) : builds 1 et 2 téléversés,
processingState = VALID,IN_BETA_TESTINGdans le groupe interne. Non vérifié : installation depuis TestFlight sur un appareil réel et tout ce que liste la §11.10 (passkey iCloud, liens universels depuis Mail / Messages, Face ID, trousseau, push, VoiceOver, multitâche iPad, réseau cellulaire). - macOS : le journal git indique « macOS 1.0.0 (1) signed and notarized » (commit
14c22c7) puis un build 2 (commitea21e9d, listes de la barre latérale et des réglages en rangées de boutons explicites). ⚠️ La §8 dedocs/APPLE-APPS.md, rédigée avant, dit encore « NOT PRODUCED » : elle n'a pas été mise à jour. - Push : le fournisseur APNs est implémenté et sa configuration (chemin du fichier de clé, identifiants) est
dans le manifeste depuis le commit
3dfdbd9; la livraison n'a pas été vérifiée (APPLE-APPS.md §11.4).
🛰 Agents
bash agents/build.sh # ou `make agents` → dist/mcc-agent-{darwin-arm64,linux-amd64,linux-arm64} + SHA256SUMS
# sur l'hôte : jeton à usage unique (15 min par défaut, 1 h au plus) + empreinte de l'AC
scripts/mccctl enroll-token --alias <alias>
# sur le Mac, avec l'utilisateur ordinaire (jamais root)
sh install.sh --binary ./mcc-agent-darwin-arm64 \
--endpoints https://clustr.spboucher.ai \
--token <jeton> --ca-fingerprint sha256:<hex>| Mode | Quand | Fichier | sudo |
|---|---|---|---|
| LaunchAgent (défaut) | Mac avec session graphique ouverte | ~/Library/LaunchAgents/ai.spboucher.mcc-agent.plist |
non |
LaunchDaemon (--daemon) |
Mac sans session graphique | /Library/LaunchDaemons/ai.spboucher.mcc-agent.plist (UserName = l'utilisateur ordinaire) |
une fois |
systemd (Linux, agents/linux/install.sh) |
serveur Linux | unité mcc-agent.service : utilisateur système mcc-agent, NoNewPrivileges, ProtectSystem=strict, MemoryMax=256M, CPUQuota=50%, seule capacité CAP_NET_RAW |
oui |
- Déploiement en série :
infra/deploy/rollout-agents.shtraite un nœud à la fois et vérifie chacun (connection onlinedansmcc-agent status) avant le suivant ; une machine déjà enrôlée ne reçoit que le binaire. VariablesHOST,GW,DAEMON. - Machine éteinte ou sans agent :
scripts/mccctl register-node --alias <alias> [--kind mac|linux|nas] …. - État de l'agent :
~/.mcc-agent(0700) sur macOS,/var/lib/mcc-agentsur Linux ; plafondGOMEMLIMIT=64MiB. - Déroulé consigné du 2026-11-18 : pilote sur m4ml puis déploiement progressif ; 28 Macs et la passerelle Linux rapportent (379 cœurs CPU et 1 032 Go de mémoire rapportés par les agents sur 28 Macs) ; un portable éteint inscrit manuellement ; politique en lecture seule partout.
- Charge mesurée de l'agent : ≈ 0 % CPU et ≈ 25 Mo de mémoire résidente sur le nœud pilote.
💾 Sauvegarde et arrêt d'urgence
scripts/mccctl backup --dir ~/mcc-backups --keep 14 --copy-to mcc-backup:backups/maclustr-command-center
scripts/mccctl backup-verify --file ~/mcc-backups/mcc-….dump.enc # authentifie et lit le catalogue
scripts/mccctl restore-test --dir ~/mcc-backups # restaure la dernière dans une base temporaire
createdb mcc_restored && scripts/mccctl restore --file <fichier> --to "postgres://127.0.0.1/mcc_restored?sslmode=disable"pg_dumpchiffré au fil de l'eau en AES-256-GCM par blocs de 64 Kio ; la sauvegarde est relue et authentifiée avant d'être déclarée réussie ; l'échec de la copie hors hôte fait échouer la commande.- La clé
backup.keydoit exister ailleurs que sur l'hôte. Sans elle, les sauvegardes sont inutilisables après la perte du disque ; la sauvegarde ne contient pas le répertoire des secrets. restorerefuse une base qui contient déjà des tables. Aucune planification automatique derestore-test.
Arrêt d'urgence, du moins au plus radical :
- Geler les commandes :
scripts/mccctl freeze— la télémétrie et la consultation continuent. - Couper un nœud :
touch ~/.mcc-agent/FREEZEsur le nœud, ou révoquer son agent. - Arrêter le plan de contrôle :
pm2 stop mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web. - Fermer l'exposition publique : retirer la route du domaine sur la passerelle.
- Retirer les agents :
uninstall.shsur chaque nœud.
Reprise : démarrer l'ingestion, l'orchestrateur, l'API, le web ; status ; audit-verify ; unfreeze.
🩺 Dépannage
Table complète : docs/OPERATIONS.md §11.
| Symptôme | Cause probable | Correction |
|---|---|---|
mccctl : missing ~/.config/mcc/env |
fichier de configuration absent | le créer, ou MCC_ENV_FILE=<chemin> |
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 |
mccctl bootstrap-owner : owner_exists |
un owner peut déjà se connecter | invitation normale, ou recovery-invite |
mcc-control-api redémarre en boucle |
base injoignable au démarrage, ou configuration prod invalide |
vérifier PostgreSQL et les journaux PM2 |
Pages en 503 unavailable, API correcte |
mcc-web arrêté |
pm2 restart mcc-web ; vérifier dist/web/server.js (make web-release) |
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 |
install.sh : « no graphical session … use --daemon » |
pas de session graphique ouverte | relancer avec --daemon |
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 |
Agent : 401 timestamp_out_of_window ou 400 clock_skew |
horloge du nœud fausse (> 90 s) | corriger l'heure |
Agent : 401 agent_revoked |
agent révoqué ou remplacé | nouveau jeton, ré-enrôler |
Enrôlement : 409 alias_in_use · 429 |
alias pris par un autre matériel · trop de tentatives | autre alias ou retrait de l'ancien nœud · attendre Retry-After |
| Toute commande refusée par un agent | policy.json invalide ou trop permissif ; fichier FREEZE présent |
mcc-agent policy check ; chmod 600 ; supprimer FREEZE |
Action : 422 capability_missing |
la politique locale du nœud n'autorise pas ce type | adapter policy.json sur le nœud |
Action : 409 target_locked |
une autre action est en cours sur la cible | attendre ; details.action_id donne le détenteur |
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 |
503 orchestrator_frozen |
gel d'urgence actif | scripts/mccctl unfreeze après vérification |
403 step_up_required |
dernière cérémonie passkey vieille de plus de 5 min | refaire le step-up |
403 csrf_failed |
en-tête X-MCC-CSRF ou Origin absent ; autre origine que MCC_PUBLIC_ORIGIN |
relire GET /me ; utiliser l'URL publique |
429 sur la page de connexion |
plus de 30 requêtes publiques/min par adresse (ou MCC_TRUSTED_PROXIES incomplet) |
attendre ; corriger la liste des proxys |
| 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 |
Pièges propres aux apps Apple :
- Passkey système, erreur 1004 : une seconde copie enregistrée de l'identifiant de production, ou un build lancé
depuis
~/Desktop, fait échouer la feuille passkey. Les builds vont dans/tmp/mcc-swift//tmp/mcc-ios, le build Release se lance depuis/Applications, et le Debug a son propre bundle id. - AASA avant le premier lancement : le CDN d'Apple met le fichier en cache ; une entrée manquante fait échouer
la passkey (1004) et ouvre les liens dans Safari. Vérifier
curl https://clustr.spboucher.ai/.well-known/apple-app-site-association. - Contournements macOS 27.0 (à garder jusqu'à nouvel essai) : les écrans racine sont permutés ~150 ms après le
changement d'état (crash
NSTrackingAreasinon) ;.inspectorn'est pas utilisé (boucle « Update Constraints ») ;openWindow(id: "main")crée toujours une fenêtre, d'oùAppModel.show; les listes de la barre latérale et des réglages sont des rangées de boutons explicites (la sélection deListne répond pas au clic). - Énumérations fermées du client généré : une NOUVELLE valeur envoyée par un serveur plus récent fait échouer le décodage de cette réponse ; les sujets d'événements, eux, sont traités avec tolérance (rechargement complet).
🚧 État, limites connues, reste à faire
Sources : CHANGELOG.md, docs/ACCEPTANCE.md §5, docs/INTEGRATION-TODO.md, docs/SECURITY.md §14, docs/API.md §8.
- Compte owner : aucun n'existait en production à la rédaction de ces documents (commit
45f0d03) ; aucun parcours authentifié n'y était donc vérifié par une personne. - Écarts contrat / implémentation (14 recensés) : charges utiles de plusieurs événements SSE (
action.output,audit.appended,node.updatedde l'ingestion,resync…), codes d'erreur d'authentification, limites de débit plus permissives que le contrat. - Réglages sans effet :
retention.*_daysetalerts.default_*sont stockés mais lus par aucun service. - Non mesuré : température et puissance (agent sans root) ; débit, latence et file d'attente des serveurs d'inférence.
- Désactivé ou non livré :
deploy.release,system.update.schedule;model.server.*non implémentés par l'agent ; redémarrage et extinction désactivés sur chaque agent ; terminal d'administration non livré (ADR 0008). - Non exercé : restauration sur un autre nœud, rotation des clés (aucune rotation de l'AC sans ré-enrôlement), retour arrière d'une version, déplacement du plan de contrôle, renouvellement des certificats en production (premiers certificats émis le 2026-11-18, 30 jours).
- Non vérifié : Safari, Firefox et authentificateurs de plateforme réels côté web ;
go test -racesur ingest et agent ;control-apipendant une coupure de base ; « déploiement interrompu ». - Structurel : pas de réplication de la base (une base, un hôte) ; pas de CI hébergée ; pas d'audit de sécurité indépendant ; pas de HSM.
- Documentation : régénérer
docs/METRICS-CATALOG.mdavec la colonne Linux ;docs/DESIGN-BRIEF.md§1 liste encore les ports de développement ;docs/APPLE-APPS.md§8 à mettre à jour.
📚 Documentation
| Document | Sujet |
|---|---|
| docs/ARCHITECTURE.md | diagrammes C4, flux, frontières de confiance, modèle de données, modes dégradés, capacité |
| docs/SECURITY.md | modèle de menace, passkeys, sessions, autorisations, sûreté des actions, secrets, réponse aux incidents |
| docs/OPERATIONS.md | installation, mise à jour, amorçage, agents, sauvegarde, supervision, dépannage, arrêt d'urgence |
| docs/API.md | guide de l'API, flux d'événements, table des permissions, écarts contrat/implémentation |
| docs/ACCEPTANCE.md | matrice exigences → preuves |
| docs/AGENT-PROTOCOL.md | protocole agent ↔ ingestion |
| docs/METRICS-CATALOG.md | catalogue des métriques (généré) |
| docs/DECISIONS/ | décisions d'architecture (ADR 0001 à 0010) |
| docs/DESIGN-BRIEF.md | décisions de conception d'origine |
| docs/REAL-INFRASTRUCTURE-INVENTORY.md | relevé en lecture seule de l'infrastructure (phase 0) |
| docs/MANDATE.md | résumé des contraintes du mandat |
| docs/INTEGRATION-TODO.md | ce qui reste ouvert |
| docs/APPLE-APPS.md | applications macOS et iOS |
| apps/web/DESIGN-SYSTEM.md | système de design de l'application web |
| CHANGELOG.md | historique des versions |
Captures d'écran : docs/screenshots/web/, docs/screenshots/macos/, docs/screenshots/ios/.
Les 10 décisions d'architecture
| ADR | Choix | Raison résumée |
|---|---|---|
| 0001 | produit neuf, aucune reprise de l'ancien | mandat |
| 0002 | Go pour les services et l'agent (binaire statique) | des Macs sans Homebrew ni Node ; passerelle linux/amd64 ; protocole partagé à la compilation |
| 0003 | PostgreSQL partitionné, pas de TimescaleDB ni de Redis | extension absente partout ; volume modeste |
| 0004 | agents en sortie seulement ; requêtes signées via l'origine publique | confidentialité du réseau local de macOS, mesurée |
| 0005 | passkeys seulement, sessions opaques, récupération hors bande | révocation immédiate, pas de secret partagé |
| 0006 | OpenAPI 3.1 comme contrat unique, clients générés | une seule vérité pour trois clients |
| 0007 | agent sans root, métriques non mesurables déclarées | moindre privilège |
| 0008 | catalogue d'actions typées, pas de shell distant | moindre privilège |
| 0009 | hôte unique derrière la passerelle existante | robustesse par simplicité |
| 0010 | au plus une commande par action ; issue inconnue = état | sûreté des opérations sur des machines réelles |
👤 Auteur
Simon-Pierre Boucher — conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai
📄 Licence
Propriétaire (LicenseRef-Proprietary dans le contrat). Tous droits réservés © 2026 Simon-Pierre Boucher.
Dépôt privé : docs/REAL-INFRASTRUCTURE-INVENTORY.md et docs/recon/ contiennent des adresses privées.