SPB Git

Repository Public

15 entries at the root
History

Latest commit docs: legendary README — icon, logo, live spbgit badges, author 717974a

NameLast commitUpdated
agents Agent rollout script; installer sudo override; fleet enrolled (28 Macs + BHS64), M4BP36...
apps iOS app 1.0.0 (2): native iPhone/iPad app, tests on both simulators, TestFlight internal; docs
docs docs: legendary README — icon, logo, live spbgit badges, author
infra iOS app (work in progress snapshot): SwiftUI iPhone/iPad app, tests, release scripts; builds 1...
packages iOS app 1.0.0 (2): native iPhone/iPad app, tests on both simulators, TestFlight internal; docs
scripts mccctl: enroll-token and register-node; host wrapper
services Docs (architecture, security, operations, API, acceptance); fix stale job test; node.state event...
tests Integration seams fixed (command params, job capabilities, nested values in alerts); real...
tools control-api: generated strict server, central security middleware, identity handlers, SSE,...
.gitignore Apple provisioning fix; macOS 1.0.0 (1) signed and notarized
.mldignore Deploy: anchor dist exclusion so generated tokens are synced
CHANGELOG.md Docs (architecture, security, operations, API, acceptance); fix stale job test; node.state event...
Makefile Docs (architecture, security, operations, API, acceptance); fix stale job test; node.state event...
README.md docs: legendary README — icon, logo, live spbgit badges, author
VERSION Production manifest, release targets, backup upload fix
README.md View source
MacLustr Command Center logo



MacLustr Command Center icon

# 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

clustr.spboucher.ai version apps Apple plateformes licence author

Go PostgreSQL pgx go-webauthn OpenAPI kin-openapi Next.js React TypeScript TanStack Query uPlot Vitest Playwright pnpm Swift SwiftUI XcodeGen swift-openapi-runtime

commits last commit activity language languages size branches tags clones

opérations API chemins tables migrations pages web types d'action permissions ADR fichiers Go fichiers Swift fichiers TS tests Go Vitest Playwright tests Swift tests UI langues

nœud port PM2 deploy tunnel macOS iOS agents


# Sommaire


# 🎯 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.0 build 2 (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_denied ou unavailable — 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.md et INTEGRATION-TODO.md indiquent qu'aucun compte owner n'existait en production au commit 45f0d03 ; 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 (canaux mcc_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.yaml gé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.ts pose 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

text
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 :

sh
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:8730

Premier compte (lien à usage unique, à ouvrir dans le navigateur ; RP ID localhost) :

sh
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) :

sh
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-dev

Outils 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) : NavigationSplitView avec 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) et https://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

Vue d'ensemble — web

Vue d'ensemble — macOS

Vue d'ensemble — 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 / deny par utilisateur ou rôle, éventuellement limités à un nœud, un site, une étiquette ou un service ; un deny applicable l'emporte toujours ; certaines permissions ne sont accordables qu'à partir d'admin, et actions.run.critical qu'à un owner.
  • Step-up : cérémonie passkey de moins de 5 minutes pour 19 opérations d'office et pour toute action high ou critical.
  • Agent sans privilège (ADR 0007) : jamais root, aucun port en écoute, exécution sans shell, sortie expurgée, politique locale policy.json que 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), fichier FREEZE sur un nœud, révocation d'un agent.
  • Dépôt privé : docs/REAL-INFRASTRUCTURE-INVENTORY.md et docs/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

sh
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) + SHA256SUMS

# Production

É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

sh
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-api ou 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 move sans suivre docs/OPERATIONS.md §9 : les données et les secrets ne suivent pas.
  • make ci est 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)

sh
~/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
sh
# 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_TESTING dans 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 (commit ea21e9d, listes de la barre latérale et des réglages en rangées de boutons explicites). ⚠️ La §8 de docs/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

sh
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.sh traite un nœud à la fois et vérifie chacun (connection online dans mcc-agent status) avant le suivant ; une machine déjà enrôlée ne reçoit que le binaire. Variables HOST, 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-agent sur Linux ; plafond GOMEMLIMIT=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

sh
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_dump chiffré 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.key doit 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.
  • restore refuse une base qui contient déjà des tables. Aucune planification automatique de restore-test.

Arrêt d'urgence, du moins au plus radical :

  1. Geler les commandes : scripts/mccctl freeze — la télémétrie et la consultation continuent.
  2. Couper un nœud : touch ~/.mcc-agent/FREEZE sur le nœud, ou révoquer son agent.
  3. Arrêter le plan de contrôle : pm2 stop mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web.
  4. Fermer l'exposition publique : retirer la route du domaine sur la passerelle.
  5. Retirer les agents : uninstall.sh sur 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 NSTrackingArea sinon) ; .inspector n'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 de List ne 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.updated de l'ingestion, resync…), codes d'erreur d'authentification, limites de débit plus permissives que le contrat.
  • Réglages sans effet : retention.*_days et alerts.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 -race sur ingest et agent ; control-api pendant 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.md avec 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.

Clone maclustr-command-center

Anonymous clone and fetch. Pushing requires the owner's personal access token.

Snapshot of main

Files main
Menu

Theme