SPB Git

Repository Public

README.md 66.8 KB 985 lines markdown

1<div align="center">23<img src="docs/brand/logo.svg" alt="MacLustr Command Center logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="MacLustr Command Center icon" width="112" height="112">89# MacLustr Command Center (MCC)1011**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.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1415[![clustr.spboucher.ai](https://img.shields.io/website?url=https%3A%2F%2Fclustr.spboucher.ai%2Fapi%2Fv1%2Fhealth%2Fready&label=clustr.spboucher.ai&style=for-the-badge&up_message=en%20ligne&down_message=hors%20ligne)](https://clustr.spboucher.ai)16![version](https://img.shields.io/badge/plan%20de%20contr%C3%B4le-0.1.0-blue?style=for-the-badge)17![apps Apple](https://img.shields.io/badge/apps%20Apple-1.0.0%20%282%29-blue?style=for-the-badge&logo=apple&logoColor=white)18![plateformes](https://img.shields.io/badge/plateformes-web%20%C2%B7%20macOS%2015%2B%20%C2%B7%20iOS%2018%2B-8A2BE2?style=for-the-badge)19![licence](https://img.shields.io/badge/licence-propri%C3%A9taire-lightgrey?style=for-the-badge)20![author](https://img.shields.io/badge/author-Simon--Pierre%20Boucher-0A66C2?style=for-the-badge)2122![Go](https://img.shields.io/badge/Go-1.26-00ADD8?style=flat-square&logo=go&logoColor=white)23![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?style=flat-square&logo=postgresql&logoColor=white)24![pgx](https://img.shields.io/badge/pgx-5.13.0-336791?style=flat-square)25![go-webauthn](https://img.shields.io/badge/go--webauthn-0.18.2-3423A6?style=flat-square&logo=webauthn&logoColor=white)26![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1.0-6BA539?style=flat-square&logo=openapiinitiative&logoColor=white)27![kin-openapi](https://img.shields.io/badge/kin--openapi-0.153.0-6BA539?style=flat-square)28![Next.js](https://img.shields.io/badge/Next.js-16.4.6-000000?style=flat-square&logo=nextdotjs&logoColor=white)29![React](https://img.shields.io/badge/React-19.3.1-20232A?style=flat-square&logo=react&logoColor=white)30![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178C6?style=flat-square&logo=typescript&logoColor=white)31![TanStack Query](https://img.shields.io/badge/TanStack%20Query-5.108-FF4154?style=flat-square&logo=reactquery&logoColor=white)32![uPlot](https://img.shields.io/badge/uPlot-1.6.32-informational?style=flat-square)33![Vitest](https://img.shields.io/badge/Vitest-5.1.1-6E9F18?style=flat-square&logo=vitest&logoColor=white)34![Playwright](https://img.shields.io/badge/Playwright-1.65.1-2EAD33?style=flat-square&logo=playwright&logoColor=white)35![pnpm](https://img.shields.io/badge/pnpm-11.1.2-F69220?style=flat-square&logo=pnpm&logoColor=white)36![Swift](https://img.shields.io/badge/Swift-6.0%20%C2%B7%20concurrence%20stricte-F05138?style=flat-square&logo=swift&logoColor=white)37![SwiftUI](https://img.shields.io/badge/SwiftUI-sans%20WebView%20ni%20Catalyst-0D96F6?style=flat-square&logo=swift&logoColor=white)38![XcodeGen](https://img.shields.io/badge/XcodeGen-project.yml-1575F9?style=flat-square&logo=xcode&logoColor=white)39![swift-openapi-runtime](https://img.shields.io/badge/swift--openapi--runtime-%E2%89%A5%201.8.0-F05138?style=flat-square)4041[![commits](https://git.spboucher.ai/badge/maclustr-command-center/commits.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center/commits)42[![last commit](https://git.spboucher.ai/badge/maclustr-command-center/last-commit.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center/commits)43[![activity](https://git.spboucher.ai/badge/maclustr-command-center/activity.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center/insights)44[![language](https://git.spboucher.ai/badge/maclustr-command-center/language.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center)45[![languages](https://git.spboucher.ai/badge/maclustr-command-center/languages.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center/insights)46[![size](https://git.spboucher.ai/badge/maclustr-command-center/size.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center)47[![branches](https://git.spboucher.ai/badge/maclustr-command-center/branches.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center/branches)48[![tags](https://git.spboucher.ai/badge/maclustr-command-center/tags.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center/tags)49[![clones](https://git.spboucher.ai/badge/maclustr-command-center/clones.svg?style=flat-square)](https://git.spboucher.ai/maclustr-command-center)5051![opérations API](https://img.shields.io/badge/op%C3%A9rations%20API-132-blue?style=flat-square)52![chemins](https://img.shields.io/badge/chemins%20OpenAPI-104-blue?style=flat-square)53![tables](https://img.shields.io/badge/tables%20PostgreSQL-49-blue?style=flat-square)54![migrations](https://img.shields.io/badge/migrations-6-blue?style=flat-square)55![pages web](https://img.shields.io/badge/pages%20web-31-blue?style=flat-square)56![types d'action](https://img.shields.io/badge/types%20d'action-18-blue?style=flat-square)57![permissions](https://img.shields.io/badge/permissions-26%20%C2%B7%204%20r%C3%B4les-blue?style=flat-square)58![ADR](https://img.shields.io/badge/ADR-10-informational?style=flat-square)59![fichiers Go](https://img.shields.io/badge/Go-158%20fichiers%20%C2%B7%2076%20351%20lignes-informational?style=flat-square)60![fichiers Swift](https://img.shields.io/badge/Swift-181%20fichiers%20%C2%B7%2098%20575%20lignes-informational?style=flat-square)61![fichiers TS](https://img.shields.io/badge/TS%2FTSX-213%20fichiers%20%C2%B7%2029%20531%20lignes-informational?style=flat-square)62![tests Go](https://img.shields.io/badge/tests%20Go-201%20fonctions%20%C2%B7%2026%20paquets-brightgreen?style=flat-square)63![Vitest](https://img.shields.io/badge/Vitest-172%20tests%20%C2%B7%2023%20fichiers-brightgreen?style=flat-square)64![Playwright](https://img.shields.io/badge/Playwright-94%20tests%20%C2%B7%209%20specs-brightgreen?style=flat-square)65![tests Swift](https://img.shields.io/badge/tests%20Swift-67%20core%20%C2%B7%2054%20macOS%20%C2%B7%2054%20iOS-brightgreen?style=flat-square)66![tests UI](https://img.shields.io/badge/XCUITest-6%20macOS%20%C2%B7%2012%20%C3%97%202%20iOS-brightgreen?style=flat-square)67![langues](https://img.shields.io/badge/langues-fran%C3%A7ais%20%C2%B7%20anglais-8A2BE2?style=flat-square)6869![nœud](https://img.shields.io/badge/n%C5%93ud-M4M64c-8A2BE2?style=flat-square)70![port](https://img.shields.io/badge/ports-8800%E2%80%938805-informational?style=flat-square)71![PM2](https://img.shields.io/badge/PM2-5%20processus-2B037A?style=flat-square&logo=pm2&logoColor=white)72![deploy](https://img.shields.io/badge/deploy-mld%20%28%C3%A9pingl%C3%A9%29-orange?style=flat-square)73![tunnel](https://img.shields.io/badge/tunnel-MacLustr%20Tunnel%20%C2%B7%20Caddy%20%2B%20WireGuard-1F8B4C?style=flat-square&logo=wireguard&logoColor=white)74![macOS](https://img.shields.io/badge/macOS-ai.spboucher.clustr%20%C2%B7%20Developer%20ID-000000?style=flat-square&logo=apple&logoColor=white)75![iOS](https://img.shields.io/badge/iOS-ai.spboucher.clustr.ios%20%C2%B7%20TestFlight-000000?style=flat-square&logo=apple&logoColor=white)76![agents](https://img.shields.io/badge/agents-darwin%2Farm64%20%C2%B7%20linux%2Famd64%20%C2%B7%20linux%2Farm64-00ADD8?style=flat-square)7778</div>7980---8182## Sommaire8384- [🎯 Vue d'ensemble](#-vue-densemble)85- [👪 Famille : un dépôt, trois clients](#-famille--un-dépôt-trois-clients)86- [✨ Fonctionnalités](#-fonctionnalités)87- [🏗 Architecture](#-architecture)88- [🧱 Pile technique](#-pile-technique)89- [🗂 Carte du dépôt](#-carte-du-dépôt)90- [🚀 Démarrage rapide (développement local)](#-démarrage-rapide-développement-local)91- [🔧 Configuration](#-configuration)92- [🔌 API](#-api)93- [🖥 Écrans](#-écrans)94- [🎬 Actions typées](#-actions-typées)95- [🗄 Modèle de données](#-modèle-de-données)96- [🔐 Sécurité](#-sécurité)97- [🧪 Tests](#-tests)98- [📦 Construire et déployer](#-construire-et-déployer)99- [🍎 Applications Apple](#-applications-apple)100- [🛰 Agents](#-agents)101- [💾 Sauvegarde et arrêt d'urgence](#-sauvegarde-et-arrêt-durgence)102- [🩺 Dépannage](#-dépannage)103- [🚧 État, limites connues, reste à faire](#-état-limites-connues-reste-à-faire)104- [📚 Documentation](#-documentation)105- [👤 Auteur](#-auteur)106- [📄 Licence](#-licence)107108---109110## 🎯 Vue d'ensemble111112MacLustr Command Center (MCC) est un poste de pilotage d'infrastructure : inventaire et télémétrie rapportés par113un agent sur chaque machine, services, serveurs d'inférence, stockage, alertes et incidents, calendrier114d'entretien, jobs, et **actions typées** sur les nœuds — avec passkeys, rôles, journal d'audit chaîné et115sauvegardes chiffrées.116117- **Plan de contrôle** version `0.1.0` (2026-11-18), en production sur **https://clustr.spboucher.ai**.118- **Applications Apple** version `1.0.0` build `2` (`apps/macos/project.yml`, `apps/ios/project.yml`).119- Produit écrit à partir d'un dépôt vide ; il cohabite avec l'ancienne application « MacLustr » sans la lire ni la120  modifier ([ADR 0001](docs/DECISIONS/0001-new-product-no-reuse.md)).121- Principe d'honnêteté de l'interface : une valeur non mesurable est déclarée `unsupported`,122  `permission_denied` ou `unavailable` — jamais estimée, jamais remplacée par 0123  ([docs/METRICS-CATALOG.md](docs/METRICS-CATALOG.md)).124125Ce qui est fait, ce qui est vérifié et ce qui ne l'est pas : [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md).126127> **À savoir d'emblée** (état décrit par la documentation du dépôt, rédigée les 18 et 19 novembre 2026) :128> température et puissance ne sont pas mesurées (agent sans root) ; la livraison des notifications push n'est pas129> vérifiée de bout en bout ; `ACCEPTANCE.md` et `INTEGRATION-TODO.md` indiquent qu'aucun compte owner n'existait en130> production au commit `45f0d03` ; la suite Go, en échec sur un test à ce commit, est verte sur les 26 paquets131> depuis le commit suivant. Voir [État, limites connues, reste à faire](#-état-limites-connues-reste-à-faire).132133## 👪 Famille : un dépôt, trois clients134135Contrairement 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 :136[git.spboucher.ai/maclustr-command-center](https://git.spboucher.ai/maclustr-command-center).137138| Client | Chemin | Technologie | Identifiant | Distribution |139|---|---|---|---|---|140| 🌐 Web | [`apps/web/`](apps/web) | Next.js 16, React 19, TypeScript strict | `https://clustr.spboucher.ai` | servi derrière `control-api` (même origine) |141| 🖥 macOS | [`apps/macos/`](apps/macos/README.md) | SwiftUI, macOS 15.0+, Swift 6 | `ai.spboucher.clustr` | Developer ID + notarisation (`Scripts/release.sh`) |142| 📱 iOS / iPadOS | [`apps/ios/`](apps/ios/README.md) | SwiftUI universel, iOS 18.0+, Swift 6 | `ai.spboucher.clustr.ios` | TestFlight (fiche App Store Connect `6836652715`, « MacLustr CC ») |143| 📦 Socle Swift | [`packages/swift-core/`](packages/swift-core/README.md) | paquet `MCCCore` (macOS 15 / iOS 18) | — | consommé par les deux apps |144| 📜 Contrat | [`packages/api-contracts/`](packages/api-contracts/README.md) | OpenAPI 3.1, 132 opérations | — | génère le serveur Go, les types TS et le client Swift |145146## ✨ Fonctionnalités147148| Domaine | Ce que fait le code |149|---|---|150| **Tableau de bord** | vue d'ensemble, disponibilité par fraîcheur, capacité avec couverture, tendances, disposition par utilisateur, centre d'opérations plein écran (`/ops`) |151| **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 |152| **Services** | découverte PM2 / launchd / systemd / docker, état, historique, service « géré », URL publique |153| **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 |154| **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 |155| **Réseau** | interfaces, débits, latence et perte, topologie dessinée avec un tableau équivalent |156| **Stockage** | volumes, usage, état SMART de base, cibles NAS sondées par les agents, sauvegardes observées |157| **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 |158| **Entretien** | fenêtres, récurrence, fuseaux, mode maintenance automatique, silences, export ICS, notes |159| **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](docs/DECISIONS/0008-no-arbitrary-shell.md)) |160| **Audit** | journal en ajout seul, chaîne de hachage, consultation, vérification, export signé vérifiable hors ligne |161| **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 |162| **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`) |163| **Administration** | utilisateurs, octrois (`allow` / `deny` par ressource), agents et jetons d'enrôlement, réglages, état du backend |164| **Temps réel** | flux SSE durable, reprise par `Last-Event-ID`, resynchronisation, filtrage par permission |165| **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) |166| **Sauvegardes** | `pg_dump` chiffré AES-256-GCM en flux, relu et authentifié, copie hors hôte, test de restauration |167| **Interfaces** | français et anglais, thèmes sombre et clair, mobile, accessibilité (axe, WCAG 2.2 AA sur les écrans principaux), CSP à nonce |168169## 🏗 Architecture170171Référence complète (diagrammes C4, flux, frontières de confiance, modes dégradés, capacité) :172[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).173174```mermaid175flowchart TB176  subgraph clients["Clients"]177    browser["Navigateur"]178    apple["Apps macOS / iOS (MCCCore)"]179    agents["mcc-agent × N<br/>(sortie seulement, sans root)"]180  end181  gw["Passerelle publique<br/>MacLustr Tunnel (Caddy TLS + WireGuard)"]182  subgraph host["Nœud hôte — M4M64c"]183    api["control-api (Go) :8800<br/>REST /api/v1 · SSE · WebAuthn · AASA<br/>relais /agent/v1 · proxy web"]184    web["web (Next.js standalone) :8803"]185    ingest["telemetry-ingest (Go)<br/>:8804 requêtes signées · :8801 mTLS · :8805 santé"]186    orch["action-orchestrator (Go) :8802<br/>actions · jobs · alertes · notifications<br/>calendrier d'entretien · ménage"]187    pg[("PostgreSQL 17<br/>base mcc")]188    ctl["mccctl (CLI hors bande)"]189    bk["mcc-backup (cron 03:40)"]190  end191  backup["Second nœud<br/>(copie chiffrée des sauvegardes)"]192  browser --> gw193  apple --> gw194  agents --> gw195  gw --> api196  api -- "tout sauf /api, /agent, AASA" --> web197  api -- "/agent/v1/* (relais)" --> ingest198  api --> pg199  ingest --> pg200  orch --> pg201  ctl --> pg202  bk --> pg203  bk -- "rsync restreint" --> backup204```205206Points structurants :207208- **Un seul module Go** (`services/go.mod`, `go 1.26`) pour les six binaires : `control-api`, `telemetry-ingest`,209  `action-orchestrator`, `mccctl`, `mcc-agent`, `mcc-devlogin`.210- **Coordination par PostgreSQL uniquement** : tables durables et `LISTEN/NOTIFY` (canaux `mcc_events`,211  `mcc_commands`, `mcc_command_updates`, `mcc_actions`). Ni Redis ni file de messages212  ([ADR 0003](docs/DECISIONS/0003-postgresql-native-timeseries.md)).213- **Contrat d'abord** ([ADR 0006](docs/DECISIONS/0006-contract-first-three-clients.md)) :214  `packages/api-contracts/openapi.yaml` génère le serveur strict Go (`services/internal/api/gen.go`), la table de215  sécurité par opération (`ops_gen.go`), les types TypeScript (`apps/web/src/api/schema.d.ts`) et le client Swift216  (`packages/swift-core/Sources/MCCCore/Generated`).217- **Sécurité appliquée centralement** : `core.admit` (`services/internal/api/server.go`) enchaîne identifiants →218  limites → CSRF → permission → step-up, et refuse toute opération absente de la table générée.219- **Agents en sortie seulement** : le transport par défaut est la requête HTTPS signée (certificat + horodatage +220  nonce + signature ECDSA, fenêtre ±90 s) relayée par `control-api`221  ([ADR 0004 et son amendement](docs/DECISIONS/0004-agent-transport-mtls-lan.md)) : macOS bloque les connexions LAN222  d'un binaire lancé par launchd (constat mesuré sur le nœud pilote).223- **Web sans récupération de données côté serveur** : chaque page est une coquille rendue côté client qui n'appelle224  que `/api/v1` ; `apps/web/src/proxy.ts` pose une CSP à nonce par requête.225226### Flux d'une action (au plus une commande par action)227228```mermaid229sequenceDiagram230  participant U as Utilisateur231  participant C as control-api232  participant P as PostgreSQL233  participant O as action-orchestrator234  participant I as telemetry-ingest235  participant A as mcc-agent236  U->>C: POST /actions (Idempotency-Key)237  C->>C: permission sur la cible, step-up, confirmation, justification, pré-vérifications238  C->>P: INSERT actions (+ action_locks) + audit, NOTIFY mcc_actions239  C-->>U: 201 Action (queued ou pending_approval)240  opt criticité critical241    U->>C: POST /actions/{id}/approve (autre personne, step-up)242  end243  O->>P: prend l'action (FOR UPDATE SKIP LOCKED), refait les pré-vérifications244  O->>O: signe l'enveloppe (Ed25519, validité 90 s, nonce)245  O->>P: INSERT agent_commands (1 par action), NOTIFY mcc_commands246  A->>I: GET /agent/v1/commands?wait=25 (long-poll)247  I-->>A: SignedCommand (remise une seule fois)248  A->>A: FREEZE ? signature, destinataire, expiration, nonce, politique locale, paramètres249  A->>I: ack, events (sortie expurgée), result250  I->>P: agent_commands, action_events, NOTIFY mcc_command_updates251  O->>P: réconcilie : succeeded / failed / timed_out (+ outcome_unknown), libère le verrou252  C-->>U: SSE action.changed / action.output253```254255Propriété centrale ([ADR 0010](docs/DECISIONS/0010-at-most-once-commands.md)) : une action émet **au plus une**256commande (index unique `agent_commands_one_per_action`) et rien ne la ré-émet. Une commande jamais remise finit257`failed / agent_unreachable` ; une commande remise sans résultat finit `timed_out` avec `outcome_unknown=true` —258une issue inconnue est un état, jamais une relance.259260### L'orchestrateur261262Une boucle principale et des tâches périodiques, chacune sous un verrou consultatif PostgreSQL :263264| Tâche | Période | Paquet |265|---|---|---|266| Actions (expiration d'approbation, émission, réconciliation) | sur notification + balayage 2 s | `services/internal/orchestrator` |267| Jobs (placement, tentatives, planifications) | 2 s | `services/internal/jobs` |268| Alertes (évaluation des règles) | 15 s | `services/internal/alerts` |269| Notifications (file `alert_notifications` → APNs) | 5 s | `services/internal/notify` |270| Calendrier d'entretien (début / fin des fenêtres) | 10 s | `services/internal/maintenance` |271| Ménage | 1 h | `services/internal/orchestrator/housekeeping.go` |272273### Modes dégradés (résumé)274275| Situation | Comportement |276|---|---|277| 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) |278| 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` |279| Agent hors ligne | nœud `offline` après 120 s ; action refusée `422 agent_offline` |280| Redémarrage de l'orchestrateur | aucun état en mémoire, aucune seconde commande émise |281| Web (Next) arrêté | pages en `503 unavailable`, l'API reste disponible |282| Gel d'urgence | aucune commande émise ; `POST /actions` → `503 orchestrator_frozen` |283284## 🧱 Pile technique285286| Couche | Technologie | Version (lue dans le dépôt) | Rôle |287|---|---|---|---|288| Services et agent | Go, binaires statiques (`CGO_ENABLED=0`) | 1.26 | `control-api`, `telemetry-ingest`, `action-orchestrator`, `mccctl`, `mcc-agent` |289| Base | PostgreSQL partitionné (sans TimescaleDB) | 17 | état, séries temporelles, file d'événements, verrous |290| Pilote SQL | `jackc/pgx` | 5.13.0 | accès PostgreSQL |291| Identité | `go-webauthn/webauthn` | 0.18.2 | passkeys |292| Contrat | OpenAPI + `kin-openapi`, `oapi-codegen/runtime` | 3.1.0 · 0.153.0 · 1.9.0 | serveur strict généré |293| Encodage | `fxamacker/cbor` | 2.9.4 | CBOR |294| Web | Next.js (App Router, sortie `standalone`), React | 16.4.6 · 19.3.1 | interface |295| Web — données | `@tanstack/react-query`, `openapi-fetch`, `@tanstack/react-virtual` | 5.108 · 0.17 · 3.14 | cache, client typé, listes virtualisées |296| Web — graphiques | uPlot | 1.6.32 | séries temporelles |297| Web — langage | TypeScript strict, ESLint | 5.9.3 · 9.39 | — |298| Web — tests | Vitest, Playwright, `@axe-core/playwright`, jsdom | 5.1.1 · 1.65.1 · 4.14 · 31 | unitaires, bout en bout, accessibilité |299| Gestionnaire | pnpm | 11.1.2 | `apps/web` |300| Jetons de design | `packages/ui-tokens` (`tokens.json` → CSS, TypeScript, Swift) | — | une seule palette pour trois clients |301| Apple | Swift (mode langage 6, concurrence stricte), SwiftUI, XcodeGen | 6.0 | apps macOS 15.0+ et iOS 18.0+ |302| 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é |303| Exploitation | PM2, `mld`, MacLustr Tunnel (Caddy + WireGuard) | — | processus, placement, exposition publique |304305## 🗂 Carte du dépôt306307```308maclustr-command-center/            830 fichiers suivis309├── services/                       module Go unique (go 1.26)310│   ├── cmd/                        control-api · telemetry-ingest · action-orchestrator · mccctl · mcc-agent · mcc-devlogin311│   └── internal/                   26 paquets : api, identity, authz, audit, events, protocol, ingest, pki, agent,312│       │                           actions, orchestrator, jobs, alerts, notify, maintenance, backup, db, config,313│       │                           httpx, ids, redact, secret, signkey, svc, buildinfo, testdb314│       └── db/migrations/          0001_init … 0006_ops (schéma PostgreSQL, source de vérité avec le contrat)315├── packages/316│   ├── api-contracts/              openapi.yaml (OpenAPI 3.1, 132 opérations) + conventions317│   ├── ui-tokens/                  tokens.json + build.mjs → CSS, TypeScript, Swift318│   └── swift-core/                 paquet MCCCore : client généré, passkeys, sessions, SSE, cache hors ligne, composants319├── apps/320│   ├── web/                        Next.js 16 / React 19 ; DESIGN-SYSTEM.md ; Vitest ; e2e Playwright (9 specs)321│   ├── macos/                      app SwiftUI (project.yml XcodeGen, Sources, Tests, UITests, Scripts)322│   └── ios/                        app SwiftUI universelle iPhone + iPad (même organisation)323├── agents/                         build.sh + empaquetage launchd (macos/) et systemd (linux/)324├── infra/325│   ├── deploy/                     mld-manifest.json · rollout-agents.sh326│   └── apple/                      provision.py · asc.py · testflight.py (API App Store Connect)327├── scripts/mccctl                  lanceur de mccctl sur l'hôte, avec la configuration de production328├── tests/e2e/local-stack.sh        essai de bout en bout avec les vrais binaires329├── tools/gen-api.py                génération du code serveur depuis le contrat330├── docs/                           architecture, sécurité, exploitation, API, recette, protocole agent, ADR, captures331├── Makefile                        CI locale reproductible (make ci)332├── CHANGELOG.md · VERSION          0.1.0333└── README.md334```335336| Chemin | Contenu |337|---|---|338| `services/` | module Go unique : `cmd/control-api`, `cmd/telemetry-ingest`, `cmd/action-orchestrator`, `cmd/mccctl`, `cmd/mcc-agent`, `cmd/mcc-devlogin` ; paquets dans `internal/` |339| `services/internal/db/migrations/` | schéma PostgreSQL (source de vérité avec le contrat) |340| `packages/api-contracts/` | contrat OpenAPI 3.1 (`openapi.yaml`, 132 opérations) et ses conventions |341| `packages/ui-tokens/` | jetons de design → CSS, TypeScript, Swift |342| `packages/swift-core/`, `apps/macos/`, `apps/ios/` | clients Apple — voir [docs/APPLE-APPS.md](docs/APPLE-APPS.md) |343| `apps/web/` | application web (Next.js 16, React 19) ; [`DESIGN-SYSTEM.md`](apps/web/DESIGN-SYSTEM.md) ; tests unitaires et Playwright |344| `agents/` | construction et empaquetage de l'agent (launchd pour macOS, systemd pour Linux) |345| `infra/deploy/` | manifeste de déploiement (`mld-manifest.json`), déploiement des agents (`rollout-agents.sh`) |346| `infra/apple/` | scripts du compte Apple Developer (voir APPLE-APPS.md) |347| `scripts/mccctl` | lanceur de `mccctl` sur l'hôte, avec la configuration de production |348| `tests/e2e/local-stack.sh` | essai de bout en bout avec les vrais binaires |349| `tools/gen-api.py` | génération du code serveur depuis le contrat |350| `docs/` | documentation de référence ([ci-dessous](#-documentation)) |351352## 🚀 Démarrage rapide (développement local)353354Prérequis : Go 1.26, Node et pnpm (`apps/web/package.json` fixe `pnpm@11.1.2`), PostgreSQL 17 en écoute sur355`127.0.0.1`, Python 3 avec PyYAML (génération du code depuis le contrat).356357La référence exécutable est `tests/e2e/local-stack.sh` : il enchaîne exactement ces étapes sur une base jetable.358À la main, avec les ports par défaut de `services/internal/config/config.go` :359360```sh361createdb mcc_dev362363# Garder les secrets de développement à part : le défaut de MCC_SECRETS_DIR est ~/.config/mcc.364export MCC_ENV=dev MCC_SECRETS_DIR="$HOME/.config/mcc-dev" MCC_INGEST_ADVERTISE=http://localhost:8730365366cd services367go run ./cmd/control-api &                 # http://localhost:8730 — applique les migrations368go run ./cmd/telemetry-ingest serve &      # 8731 (mTLS), 8734 (requêtes signées), 8741 (santé)369go run ./cmd/action-orchestrator &         # 8732 (santé)370371cd ../apps/web && pnpm install && pnpm dev # 127.0.0.1:8733, à consulter via http://localhost:8730372```373374Premier compte (lien à usage unique, à ouvrir dans le navigateur ; RP ID `localhost`) :375376```sh377cd services && go run ./cmd/mccctl bootstrap-owner --handle moi --name "Moi"378```379380Agent local (le poste de développement devient un nœud, avec ses vraies métriques) :381382```sh383cd services384TOKEN=$(go run ./cmd/telemetry-ingest dev-token --alias mon-poste | tail -1)385FP=$(curl -fsS localhost:8741/healthz | python3 -c "import sys,json;print(json.load(sys.stdin)['ca_fingerprint'])")386go run ./cmd/mcc-agent enroll --endpoints http://localhost:8730 --token "$TOKEN" --ca-fingerprint "$FP" --state-dir /tmp/mcc-agent-dev387go run ./cmd/mcc-agent run --state-dir /tmp/mcc-agent-dev388```389390Outils réservés au développement (ils refusent `MCC_ENV=prod`) : `telemetry-ingest dev-token`, `dev-proxy`,391`migrate` ; `mcc-devlogin` (crée un owner avec un authentificateur logiciel et imprime un jeton d'accès pour392essayer l'API à la main).393394Régénérer le code après une modification du contrat ou des jetons : `make gen` (ne jamais modifier le code395généré à la main).396397| Port de développement | Service |398|---|---|399| 8730 | `control-api` (origine à consulter) |400| 8731 · 8734 · 8741 | `telemetry-ingest` : mTLS · requêtes signées · santé |401| 8732 | `action-orchestrator` (santé) |402| 8733 | `web` (`next dev`) |403| 8750 · 8753 | Playwright (`pnpm e2e`) |404| 8760 | backend local de l'app macOS (`packages/swift-core/Scripts/local-backend.sh`) |405| 8770–8775 | `tests/e2e/local-stack.sh` |406| 8780 · 8782 | backend local des tests iOS (`apps/ios/Scripts/local-backend.sh`) |407408## 🔧 Configuration409410Variables `MCC_*` — liste complète et défauts dans `services/internal/config/config.go`. Noms seulement ; les411valeurs de production sont dans le manifeste `infra/deploy/mld-manifest.json` et412[docs/OPERATIONS.md §1.3](docs/OPERATIONS.md).413414| Variable | Rôle |415|---|---|416| `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` |417| `MCC_DATABASE_URL` | connexion PostgreSQL |418| `MCC_SECRETS_DIR` | répertoire des secrets créés au premier démarrage (fichiers 0600) |419| `MCC_PUBLIC_ORIGIN`, `MCC_RP_ID` | origine publique et Relying Party WebAuthn |420| `MCC_API_LISTEN`, `MCC_WEB_UPSTREAM` | écoute de `control-api`, amont Next.js |421| `MCC_TRUSTED_PROXIES` | proxys dont `X-Forwarded-For` est cru (la passerelle) |422| `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 |423| `MCC_ORCHESTRATOR_LISTEN` | santé de l'orchestrateur |424| `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) |425| `MCC_FRESH_AFTER`, `MCC_OFFLINE_AFTER` | seuils de fraîcheur (`stale`, puis `offline` après 120 s) |426| `MCC_RETAIN_RAW`, `MCC_RETAIN_1M`, `MCC_RETAIN_1H` | rétention des séries (7 jours · 30 jours · 400 jours) |427| `MCC_APPLE_APP_IDS` | identifiants d'apps listés dans l'AASA (`<équipe>.ai.spboucher.clustr`, `<équipe>.ai.spboucher.clustr.ios`) |428| `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) |429| `MCC_TEST_ADMIN_URL` | tests d'intégration Go : serveur PostgreSQL des bases jetables |430| `MCC_ENV_FILE` | chemin du fichier de configuration lu par `scripts/mccctl` |431432Les **secrets ne se configurent pas** : chaque service crée le sien au premier démarrage dans `MCC_SECRETS_DIR`.433Aucun secret n'est dans le dépôt (`.gitignore` : `*.key`, `*.pem`, `*.p8`, `.env*`, `secrets/`) ni dans la table434`settings`. Le fichier `env` lu par `scripts/mccctl` ne contient que de la configuration.435436Variables de lancement **Debug uniquement** des apps Apple (absentes du binaire Release, vérifié par les scripts) :437`MCC_BASE_URL`, `MCC_PASSKEY=software`, `MCC_SECURE_STORE=keychain|file|memory`, `MCC_SETUP_TOKEN`, `MCC_OPEN_URL`.438439## 🔌 API440441Base `/api/v1`, contrat [`packages/api-contracts/openapi.yaml`](packages/api-contracts/openapi.yaml)442(OpenAPI 3.1.0, **132 opérations sur 104 chemins**). Guide, exemples complets, table des permissions et écarts443connus : [docs/API.md](docs/API.md).444445| Étiquette | Opérations | Étiquette | Opérations |446|---|---|---|---|447| Admin | 20 | Storage | 5 |448| Auth | 19 | Services | 4 |449| Alerts | 19 | Audit | 3 |450| Nodes | 11 | Dashboards | 3 |451| Maintenance | 11 | Meta (santé, version) | 3 |452| Jobs | 9 | Cluster | 2 |453| Invitations | 8 | Models | 2 |454| Actions | 8 | Network | 2 |455| Events (SSE), Activity, Search | 1 chacune | | |456457Conventions : erreurs avec code, message et identifiant de corrélation ; `limit` de 1 à 200 sur les listes ;458`Idempotency-Key` (8 à 128 caractères) ; en-tête `X-MCC-CSRF` + `Origin` pour les sessions à cookie ;459`403 step_up_required` rejoué par les clients après la cérémonie passkey.460461**Flux d'événements** (`GET /api/v1/events`, SSE) : sujets `node.state`, `node.updated`, `service.changed`,462`alert.changed`, `incident.changed`, `action.changed`, `action.output`, `job.changed`, `maintenance.changed`,463`audit.appended`, `resync` (+ trame `hello`). Conseil d'intégration tant que des écarts avec le contrat existent :464traiter chaque événement comme un **signal de rechargement** de la ressource REST concernée.465466**Limites de débit telles qu'implémentées** (en mémoire, remises à zéro au redémarrage) : 30/min par IP (rafale 15)467pour le public, 900/min par session, 30/min par utilisateur sur `POST /actions`, 20/min par IP sur l'enrôlement468d'agent. Dépassement : `429 rate_limited` + `Retry-After`.469470**Protocole agent** (`/agent/v1/*` : `enroll`, `renew`, `report`, `commands`) :471[docs/AGENT-PROTOCOL.md](docs/AGENT-PROTOCOL.md).472473## 🖥 Écrans474475### Web — 31 pages (`apps/web/src/app`)476477| Groupe | Routes |478|---|---|479| Public | `/signin`, `/setup` (invitation) |480| Vue d'ensemble | `/`, `/ops` (centre d'opérations) |481| Nœuds | `/nodes`, `/nodes/[id]`, `/nodes/compare` |482| Services, modèles, jobs | `/services`, `/services/[id]`, `/models`, `/jobs`, `/jobs/[id]` |483| Réseau, stockage | `/network`, `/storage` |484| Alertes, incidents | `/alerts`, `/alerts/[id]`, `/incidents`, `/incidents/[id]` |485| Actions, entretien | `/actions/[id]`, `/maintenance`, `/maintenance/[id]` |486| Activité, audit | `/activity`, `/audit` |487| Réglages | `/settings`, `/settings/security`, `/settings/users`, `/settings/invitations`, `/settings/grants`, `/settings/agents`, `/settings/system` |488| Développement | `/dev/ui` |489490### macOS et iOS — sections natives491492Mêmes domaines dans les trois clients : Vue d'ensemble, Nœuds, Alertes, Actions, Services, Modèles d'IA, Jobs,493Entretien, Réseau, Stockage, Activité, Audit, Réglages (+ recherche universelle).494495- **iPhone** (et fenêtre iPad compacte) : `TabView` — Vue d'ensemble, Nœuds, Alertes, Actions, Plus.496- **iPad** (largeur régulière) : `NavigationSplitView` avec toutes les sections ; liste et élément côte à côte ;497  ⌘1…⌘9, ⌘R, ⌘F, ⇧⌘N ; plusieurs fenêtres.498- **macOS** : fenêtres, barre latérale, extra de barre des menus, palette de commandes, notifications, liens499  profonds, verrou local.500- Liens : `https://clustr.spboucher.ai/setup#<jeton>` (invitation) et501  `https://clustr.spboucher.ai/open/<section>[/<uuid>]`.502503### Captures (78 fichiers)504505| Dossier | Contenu |506|---|---|507| [`docs/screenshots/web/`](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) |508| [`docs/screenshots/macos/`](docs/screenshots/macos) | 25 captures d'un build Debug contre un backend local |509| [`docs/screenshots/ios/`](docs/screenshots/ios) | 32 captures iPhone et iPad (Dynamic Type maximal, hors ligne, refus viewer…) |510511<details>512<summary>Aperçu : vue d'ensemble web, macOS et iPhone</summary>513514<p align="center">515<img src="docs/screenshots/web/01-overview.png" alt="Vue d'ensemble — web" width="720"><br><br>516<img src="docs/screenshots/macos/04-overview.png" alt="Vue d'ensemble — macOS" width="720"><br><br>517<img src="docs/screenshots/ios/overview-iphone.png" alt="Vue d'ensemble — iPhone" width="280">518</p>519520</details>521522## 🎬 Actions typées523524Catalogue de **18 types** (`services/internal/actions/catalog.go`). Aucune commande libre, aucun shell. Les525exigences découlent de la **criticité seule** :526527| Criticité | Permission | Step-up | Justification | Confirmation saisie | Seconde approbation |528|---|---|---|---|---|---|529| `low` | `actions.run.low` | — | — | — | — |530| `medium` | `actions.run.medium` | — | — | — | — |531| `high` | `actions.run.high` | oui | — | — | — |532| `critical` | `actions.run.critical` (owner) | oui | oui | oui (alias de la cible, comparé par le serveur) | oui (autre personne, `actions.approve`, step-up) |533534| Type | Criticité | Verrou | État en v1 |535|---|---|---|---|536| `inventory.refresh`, `diagnostic.run` | low | nœud | disponibles ; autorisés par défaut sur tous les agents |537| `service.health_check` | low | service | disponible ; autorisé par défaut |538| `service.logs.tail` | low | aucun | disponible ; exige aussi `logs.read` ; autorisé par défaut |539| `service.restart`, `service.start` | medium | service | disponibles ; exigent service `managed` + liste blanche locale |540| `service.stop` | high | service | idem |541| `agent.restart`, `cache.purge` | medium | nœud | disponibles ; exigent la politique locale |542| `node.maintenance.set` | medium | nœud | exécuté par le serveur (aucune commande agent) |543| `job.run` | medium | job | interne : créé seulement par `POST /jobs` |544| `job.cancel` | medium | aucun | exécuté par le serveur |545| `model.server.start`, `model.server.stop` | high | nœud | au catalogue mais **non implémentés par l'agent v1** (`422 capability_missing`) |546| `deploy.release`, `system.update.schedule` | high | service / nœud | **désactivés** (`422 action_unavailable`) |547| `system.reboot`, `system.shutdown` | critical | nœud | implémentés ; **désactivés sur chaque agent** par la politique locale |548549Chaîne de contrôles de `POST /actions`, dans l'ordre du code : limite 30/min → `Idempotency-Key` → type connu, non550interne, disponible → schéma des paramètres → permission(s) sur le nœud et la cible → step-up → rejeu idempotent →551gel d'urgence → confirmation → justification → pré-vérifications → insertion + verrou + audit dans une transaction.552Chaque refus est audité et ne laisse aucune ligne d'action. Les pré-vérifications sont **refaites par553l'orchestrateur** juste avant la signature.554555| Mécanisme | Détail |556|---|---|557| Idempotence | même clé + même corps → même action (`200`) ; même clé + corps différent → `409 idempotency_conflict` |558| Verrou | un verrou par cible ; seconde action concurrente → `409 target_locked` avec l'id du détenteur |559| Approbation | état `pending_approval`, expire après 30 min ; le demandeur ne peut ni approuver ni rejeter |560| Signature | enveloppe Ed25519, validité 90 s (120 s au plus acceptés par l'agent), nonce, destinataire |561| Anti-rejeu | nonce journalisé sur disque par l'agent avant acceptation |562| 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 |563564## 🗄 Modèle de données565566Schéma : `services/internal/db/migrations/0001_init.sql` à `0006_ops.sql` (**6 migrations, 49 `CREATE TABLE`**),567appliqué au démarrage par `control-api` et `action-orchestrator` (un fichier par transaction, verrou consultatif,568somme de contrôle : une migration déjà appliquée puis modifiée est refusée). Clés primaires en UUID v7,569horodatages lus en UTC.570571```mermaid572erDiagram573  users ||--o{ passkeys : "possède"574  users ||--o{ devices : "possède"575  devices ||--o{ sessions : "porte"576  sessions ||--o{ refresh_tokens : "rotation (natif)"577  users ||--o{ invitations : "crée"578  invitations ||--o{ invitation_transactions : "ouvre"579  nodes ||--o| agents : "1 agent actif"580  nodes ||--o| node_state : "dernier état"581  nodes ||--o{ services : "héberge"582  nodes ||--o{ inference_servers : "héberge"583  nodes ||--o{ volumes : "monte"584  nodes ||--o{ samples_raw : "mesure"585  alert_rules ||--o{ alerts : "déclenche"586  incidents ||--o{ alerts : "regroupe"587  actions ||--o| agent_commands : "au plus 1"588  actions ||--o{ action_events : "journalise"589  actions ||--o| action_locks : "verrouille"590  jobs ||--o{ actions : "1 par tentative"591  job_schedules ||--o{ jobs : "planifie"592  maintenance_windows ||--o{ maintenance_window_nodes : "vise"593```594595| Domaine | Tables | Remarques |596|---|---|---|597| Identité | `users`, `passkeys`, `webauthn_challenges`, `devices`, `sessions`, `refresh_tokens`, `invitations`, `invitation_transactions` | jetons stockés hachés (SHA-256) uniquement |598| Autorisation | `policy_grants` | `allow` / `deny` par sujet, permission, ressource |599| Audit | `audit_log` | chaîne de hachage ; déclencheurs refusant `UPDATE`, `DELETE`, `TRUNCATE` |600| 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 |601| Séries temporelles | `metric_catalog`, `samples_raw`, `samples_1m`, `samples_1h`, `rollup_state`, `rollup_dirty`, `agent_report_seqs` | partitions par plage de temps |602| Alertes | `alert_rules`, `alerts`, `incidents`, `timeline_events`, `silences`, `alert_notifications` | une alerte ouverte par empreinte |603| Entretien | `maintenance_windows`, `maintenance_window_nodes`, `maintenance_notes` | |604| Actions et jobs | `actions`, `action_locks`, `action_events`, `agent_commands`, `command_keys`, `jobs`, `job_schedules` | |605| Plateforme | `events_outbox`, `settings`, `service_heartbeats`, `user_dashboards`, `schema_migrations` | `settings` ne contient aucun secret |606607Rétention : échantillons bruts (10 s) 7 jours, agrégats 1 min 30 jours, agrégats 1 h 400 jours, `events_outbox`6081 heure, `action_events` d'actions terminées 90 jours, `audit_log` jamais purgé, 14 sauvegardes locales.609Cardinalité bornée par rapport : ≤ 400 échantillons, ≤ 8 interfaces, ≤ 12 volumes, ≤ 15 processus, ≤ 200 services.610611## 🔐 Sécurité612613Référence : [docs/SECURITY.md](docs/SECURITY.md) (modèle de menace STRIDE, passkeys, sessions, CSRF, autorisations,614sûreté des actions, confiance des agents, secrets, en-têtes, réponse aux incidents).615616- **Passkeys seulement** ([ADR 0005](docs/DECISIONS/0005-passkeys-only-identity.md)) : aucune connexion par mot de617  passe ; sessions opaques (cookie pour le web, jetons d'accès et de rafraîchissement rotatifs pour les apps618  natives) ; réutilisation d'un jeton de rafraîchissement → les deux détenteurs sont déconnectés ; récupération619  hors bande par `mccctl`.620- **4 rôles, 26 permissions** (`services/internal/authz/authz.go`) :621622| Rôle | Permissions par défaut |623|---|---|624| viewer | `cluster.read`, `nodes.read`, `services.read`, `models.read`, `jobs.read`, `alerts.read`, `maintenance.read`, `actions.read` |625| operator | viewer + `nodes.private.read`, `logs.read`, `alerts.ack`, `maintenance.write`, `jobs.submit`, `actions.run.low`, `actions.run.medium` |626| admin | operator + `nodes.write`, `alerts.manage`, `actions.run.high`, `actions.approve`, `audit.read`, `audit.export`, `users.manage`, `invitations.manage`, `agents.manage`, `settings.manage` |627| owner | les 26 permissions, dont `actions.run.critical` |628629- **Octrois** : `allow` / `deny` par utilisateur ou rôle, éventuellement limités à un nœud, un site, une étiquette630  ou un service ; un `deny` applicable l'emporte toujours ; certaines permissions ne sont accordables qu'à partir631  d'admin, et `actions.run.critical` qu'à un owner.632- **Step-up** : cérémonie passkey de moins de 5 minutes pour 19 opérations d'office et pour toute action `high` ou633  `critical`.634- **Agent sans privilège** ([ADR 0007](docs/DECISIONS/0007-unprivileged-agent.md)) : jamais root, aucun port en635  écoute, exécution sans shell, sortie expurgée, **politique locale** `policy.json` que le serveur ne peut ni lire636  ni modifier. Fichier absent → quatre commandes de lecture seulement ; fichier invalide ou inscriptible par le637  groupe ou les autres → toute commande est refusée.638- **PKI privée** : AC ECDSA P-256, certificats d'agent de 30 jours ; commandes signées par l'orchestrateur, seul639  détenteur de la clé de signature.640- **Audit** : chaîne de hachage en ajout seul, `mccctl audit-verify`, export signé vérifiable hors ligne641  (`mccctl audit-verify-export`).642- **Web** : CSP à nonce par requête, HSTS et en-têtes de sécurité, refus des requêtes inter-origines.643- **Apps natives** : session dans le trousseau (`AfterFirstUnlockThisDeviceOnly`, jamais synchronisée vers iCloud),644  App Sandbox sur macOS, aucune exception ATS en Release, verrou local facultatif (Face ID / Touch ID) qui ne645  remplace jamais la connexion ni le step-up ; une notification ne peut qu'ouvrir un écran.646- **Arrêts d'urgence** à trois niveaux indépendants : gel global (`mccctl freeze`), fichier `FREEZE` sur un nœud,647  révocation d'un agent.648- **Dépôt privé** : `docs/REAL-INFRASTRUCTURE-INVENTORY.md` et `docs/recon/` contiennent des adresses privées.649650## 🧪 Tests651652Les tests d'intégration Go créent des bases jetables `mcc_test_<aléatoire>` sur le PostgreSQL local653(`MCC_TEST_ADMIN_URL`, défaut `postgres://127.0.0.1/postgres?sslmode=disable`). **Sans PostgreSQL joignable, ils654sont ignorés, pas en échec** (`services/internal/testdb`).655656| Commande | Ce qu'elle fait |657|---|---|658| `make ci` | porte avant de pousser : `gen-check`, `fmt-check`, `vet`, `test`, `web-ci` |659| `make test` | `go test -count=1 ./...` |660| `make test-race` | idem avec le détecteur de courses |661| `make web-ci` | web : génération du client à jour, `tsc`, ESLint, Vitest |662| `cd apps/web && pnpm test` | tests unitaires web (Vitest) |663| `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` |664| `bash tests/e2e/local-stack.sh` | agent réel → relais → ingestion → API, action signée, rejeu idempotent (ports 8770–8775) |665| `cd packages/swift-core && swift test` | tests unitaires de `MCCCore` |666| `packages/swift-core/Scripts/integration-test.sh` | `MCCCore` contre un vrai `control-api` local + PostgreSQL jetable |667| `apps/macos/Scripts/test.sh unit` · `ui` | tests de logique macOS · XCUITest contre un backend local réel |668| `apps/ios/Scripts/test.sh unit` · `ui iphone` / `ipad` / `both` | catalogues + tests unitaires iOS · XCUITest sur simulateurs |669| `make hooks` | installe le crochet `pre-push` qui lance `make ci` |670| `make sbom`, `make vuln` | inventaire des dépendances ; `govulncheck` et `pnpm audit` |671672Résultats consignés dans le dépôt :673674| Suite | Compte | Source |675|---|---|---|676| Go | 201 fonctions `Test…` dans 48 fichiers, 26 paquets avec tests | compté dans `services/` |677| Vitest | 172 tests réussis, 23 fichiers | [docs/ACCEPTANCE.md §1](docs/ACCEPTANCE.md) (rejoué le 2026-11-18) |678| Playwright (Chromium, authentificateur virtuel) | 94 tests, 9 fichiers de spécifications | rapporté à la fusion, non rejoué |679| Accessibilité web (axe, WCAG 2.2 AA) | 0 violation sur les écrans principaux | rapporté |680| `tests/e2e/local-stack.sh` | 10 vérifications, `E2E OK` | rejoué |681| `MCCCore` unitaire | 67 tests dans 10 suites | [docs/APPLE-APPS.md §11.8](docs/APPLE-APPS.md) |682| macOS unitaire · UI | 54 tests · 6 scénarios XCUITest | APPLE-APPS.md §9 |683| 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 |684| 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 |685| IPA Release | 18 / 18 vérifications (`Scripts/release.sh verify`) | APPLE-APPS.md §11.8 |686687État au commit `45f0d03`, rejoué le 2026-11-18 : `go vet`, `gofmt`, `gen-check` propres ; `go test ./...` :68825 paquets sur 26 réussis, **`internal/jobs` en échec sur `TestJobRunsToSuccess`** (assertion périmée, voir689[docs/ACCEPTANCE.md §1](docs/ACCEPTANCE.md#1-état-des-suites-de-tests)) ; Vitest : 172 tests réussis ;690`local-stack.sh` : `E2E OK`. Il n'y a pas de CI hébergée.691692> Corrigé depuis : la suite Go est verte sur les 26 paquets (voir docs/ACCEPTANCE.md).693694`go test -race` a été exécuté sur orchestrator, alerts, maintenance, jobs, notify, actions, audit, api, authz,695identity et events — **pas** sur ingest ni agent.696697## 📦 Construire et déployer698699```sh700make build          # binaires darwin/arm64 du plan de contrôle dans dist/ (+ SHA256SUMS.backend)701make web-release    # serveur Next « standalone » dans dist/web (node dist/web/server.js)702make agents         # binaires de l'agent (darwin/arm64, linux/amd64, linux/arm64) + SHA256SUMS703```704705### Production706707| Élément | Valeur |708|---|---|709| URL publique | `https://clustr.spboucher.ai` |710| Nœud hôte | M4M64c (épinglé dans le manifeste : la base, l'AC des agents et les clés de signature sont locales) |711| Répertoire | `~/apps/maclustr-command-center` = clone git de ce dépôt |712| Exposition | MacLustr Tunnel (Caddy TLS + WireGuard, passerelle BHS64) ; seul le port 8800 est routé |713| Santé | `GET /api/v1/health/ready` |714| Base | PostgreSQL 17, base `mcc`, en local sur l'hôte |715| Manifeste | [`infra/deploy/mld-manifest.json`](infra/deploy/mld-manifest.json) (crochets `post_sync` : `make build`, `make web-release`) |716717| Processus PM2 | Écoute | Rôle |718|---|---|---|719| `mcc-control-api` | `0.0.0.0:8800` | API, SSE, WebAuthn, AASA, relais des agents, proxy web |720| `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 |721| `mcc-action-orchestrator` | `127.0.0.1:8802` (santé) | actions, jobs, alertes, notifications, entretien |722| `mcc-web` | `127.0.0.1:8803` | serveur Next.js standalone |723| `mcc-backup` | — (cron `40 3 * * *`) | `mccctl backup --keep 14` + copie hors hôte |724725### Mise à jour sur l'hôte726727```sh728cd ~/apps/maclustr-command-center729git pull730make build && make web-release731pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web732scripts/mccctl status733```734735- **Le serveur avant les agents** : un agent qui envoie une métrique inconnue du serveur voit son rapport refusé.736- Les migrations nouvelles s'appliquent au redémarrage de `control-api` ou de l'orchestrateur.737- Pendant le redémarrage : les agents tamponnent et rejouent ; les sessions survivent ; les clients SSE reprennent738  avec `Last-Event-ID` ; une action en vol est réconciliée, jamais ré-émise.739- **Ne pas déplacer avec `mld move`** sans suivre [docs/OPERATIONS.md §9](docs/OPERATIONS.md) : les données et les740  secrets ne suivent pas.741- `make ci` est le seul garde-fou avant de pousser : il n'y a pas de CI hébergée.742743### `mccctl` (administration hors bande, sur l'hôte)744745```sh746~/apps/maclustr-command-center/scripts/mccctl <commande> [options]747```748749Commandes : `migrate`, `bootstrap-owner`, `recovery-invite`, `audit-verify`, `audit-verify-export`, `freeze`,750`unfreeze`, `status`, `backup`, `backup-verify`, `restore`, `restore-test`, `enroll-token`, `register-node`. Les751opérations qui changent un état écrivent une entrée d'audit `actor_kind=cli`.752753Déploiement, exploitation et procédures d'urgence : [docs/OPERATIONS.md](docs/OPERATIONS.md).754755## 🍎 Applications Apple756757Référence : [docs/APPLE-APPS.md](docs/APPLE-APPS.md), [apps/macos/README.md](apps/macos/README.md),758[apps/ios/README.md](apps/ios/README.md), [packages/swift-core/README.md](packages/swift-core/README.md).759760| | macOS | iOS / iPadOS |761|---|---|---|762| Nom | MacLustr Command Center | produit `MacLustr`, affiché `MacLustr CC` |763| Bundle id (Release · Debug) | `ai.spboucher.clustr` · `ai.spboucher.clustr.debug` | `ai.spboucher.clustr.ios` · `ai.spboucher.clustr.ios.debug` |764| Cible | macOS 15.0 | iOS 18.0, universel iPhone + iPad |765| Version | 1.0.0 (2) | 1.0.0 (2) |766| 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) |767| Serveur | `https://clustr.spboucher.ai` fixe en Release | idem |768| Passkeys | système (`ASAuthorizationPlatformPublicKeyCredentialProvider`, RP `clustr.spboucher.ai`) | idem |769| Domaines associés | `webcredentials:` + `applinks:clustr.spboucher.ai` | idem |770| 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 |771| Distribution | dmg notarisé et agrafé (`Scripts/release.sh`) | TestFlight, groupe interne |772773```sh774# macOS775apps/macos/Scripts/build.sh                 # Debug → /tmp/mcc-swift/DerivedData/…776apps/macos/Scripts/test.sh unit             # ou : ui777apps/macos/Scripts/release.sh               # archive → Developer ID → notarisation + agrafage → dmg → vérification778apps/macos/Scripts/verify-release.sh dist/macos/MacLustr-Command-Center-1.0.0-1.dmg779780# iOS / iPadOS781cd apps/ios782Scripts/build.sh                            # Debug simulateur → /tmp/mcc-ios/DerivedData/…783Scripts/local-backend.sh build && Scripts/local-backend.sh start mcc_ios_test_dev784Scripts/test.sh unit && Scripts/test.sh ui both785ASC_ISSUER_ID=<émetteur> Scripts/release.sh archive   # incrémenter CURRENT_PROJECT_VERSION d'abord786Scripts/release.sh verify                              # 18 vérifications sur l'IPA787ASC_ISSUER_ID=<émetteur> Scripts/release.sh upload788ASC_ISSUER_ID=<émetteur> python3 ../../infra/apple/testflight.py [--apply]789790# Provisionnement (API App Store Connect ; ASC_KEY_ID et ASC_ISSUER_ID dans l'environnement)791python3 infra/apple/provision.py [--ios] [--check]792```793794État consigné :795796- **iOS** ([APPLE-APPS.md §11.9](docs/APPLE-APPS.md)) : builds 1 et 2 téléversés, `processingState = VALID`,797  `IN_BETA_TESTING` dans le groupe interne. **Non vérifié** : installation depuis TestFlight sur un appareil réel et798  tout ce que liste la §11.10 (passkey iCloud, liens universels depuis Mail / Messages, Face ID, trousseau, push,799  VoiceOver, multitâche iPad, réseau cellulaire).800- **macOS** : le journal git indique « macOS 1.0.0 (1) signed and notarized » (commit `14c22c7`) puis un build 2801  (commit `ea21e9d`, listes de la barre latérale et des réglages en rangées de boutons explicites). ⚠️ La §8 de802  `docs/APPLE-APPS.md`, rédigée avant, dit encore « NOT PRODUCED » : elle n'a pas été mise à jour.803- **Push** : le fournisseur APNs est implémenté et sa configuration (chemin du fichier de clé, identifiants) est804  dans le manifeste depuis le commit `3dfdbd9` ; la **livraison** n'a pas été vérifiée805  ([APPLE-APPS.md §11.4](docs/APPLE-APPS.md)).806807## 🛰 Agents808809```sh810bash agents/build.sh        # ou `make agents` → dist/mcc-agent-{darwin-arm64,linux-amd64,linux-arm64} + SHA256SUMS811812# sur l'hôte : jeton à usage unique (15 min par défaut, 1 h au plus) + empreinte de l'AC813scripts/mccctl enroll-token --alias <alias>814815# sur le Mac, avec l'utilisateur ordinaire (jamais root)816sh install.sh --binary ./mcc-agent-darwin-arm64 \817   --endpoints https://clustr.spboucher.ai \818   --token <jeton> --ca-fingerprint sha256:<hex>819```820821| Mode | Quand | Fichier | sudo |822|---|---|---|---|823| LaunchAgent (défaut) | Mac avec session graphique ouverte | `~/Library/LaunchAgents/ai.spboucher.mcc-agent.plist` | non |824| LaunchDaemon (`--daemon`) | Mac **sans** session graphique | `/Library/LaunchDaemons/ai.spboucher.mcc-agent.plist` (`UserName` = l'utilisateur ordinaire) | une fois |825| 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 |826827- Déploiement en série : `infra/deploy/rollout-agents.sh` traite un nœud à la fois et vérifie chacun828  (`connection   online` dans `mcc-agent status`) avant le suivant ; une machine déjà enrôlée ne reçoit que le829  binaire. Variables `HOST`, `GW`, `DAEMON`.830- Machine éteinte ou sans agent : `scripts/mccctl register-node --alias <alias> [--kind mac|linux|nas] …`.831- État de l'agent : `~/.mcc-agent` (0700) sur macOS, `/var/lib/mcc-agent` sur Linux ; plafond `GOMEMLIMIT=64MiB`.832- Déroulé consigné du 2026-11-18 : pilote sur m4ml puis déploiement progressif ; 28 Macs et la passerelle Linux833  rapportent (379 cœurs CPU et 1 032 Go de mémoire rapportés par les agents sur 28 Macs) ; un portable éteint834  inscrit manuellement ; politique en lecture seule partout.835- Charge mesurée de l'agent : ≈ 0 % CPU et ≈ 25 Mo de mémoire résidente sur le nœud pilote.836837## 💾 Sauvegarde et arrêt d'urgence838839```sh840scripts/mccctl backup --dir ~/mcc-backups --keep 14 --copy-to mcc-backup:backups/maclustr-command-center841scripts/mccctl backup-verify --file ~/mcc-backups/mcc-….dump.enc     # authentifie et lit le catalogue842scripts/mccctl restore-test --dir ~/mcc-backups                      # restaure la dernière dans une base temporaire843createdb mcc_restored && scripts/mccctl restore --file <fichier> --to "postgres://127.0.0.1/mcc_restored?sslmode=disable"844```845846- `pg_dump` chiffré au fil de l'eau en AES-256-GCM par blocs de 64 Kio ; la sauvegarde est **relue et847  authentifiée** avant d'être déclarée réussie ; l'échec de la copie hors hôte fait échouer la commande.848- **La clé `backup.key` doit exister ailleurs que sur l'hôte.** Sans elle, les sauvegardes sont inutilisables après849  la perte du disque ; la sauvegarde ne contient pas le répertoire des secrets.850- `restore` refuse une base qui contient déjà des tables. Aucune planification automatique de `restore-test`.851852Arrêt d'urgence, du moins au plus radical :8538541. **Geler les commandes** : `scripts/mccctl freeze` — la télémétrie et la consultation continuent.8552. **Couper un nœud** : `touch ~/.mcc-agent/FREEZE` sur le nœud, ou révoquer son agent.8563. **Arrêter le plan de contrôle** : `pm2 stop mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web`.8574. **Fermer l'exposition publique** : retirer la route du domaine sur la passerelle.8585. **Retirer les agents** : `uninstall.sh` sur chaque nœud.859860Reprise : démarrer l'ingestion, l'orchestrateur, l'API, le web ; `status` ; `audit-verify` ; `unfreeze`.861862## 🩺 Dépannage863864Table complète : [docs/OPERATIONS.md §11](docs/OPERATIONS.md).865866| Symptôme | Cause probable | Correction |867|---|---|---|868| `mccctl` : `missing ~/.config/mcc/env` | fichier de configuration absent | le créer, ou `MCC_ENV_FILE=<chemin>` |869| `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` |870| `mccctl bootstrap-owner` : `owner_exists` | un owner peut déjà se connecter | invitation normale, ou `recovery-invite` |871| `mcc-control-api` redémarre en boucle | base injoignable au démarrage, ou configuration `prod` invalide | vérifier PostgreSQL et les journaux PM2 |872| Pages en `503 unavailable`, API correcte | `mcc-web` arrêté | `pm2 restart mcc-web` ; vérifier `dist/web/server.js` (`make web-release`) |873| 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 |874| `install.sh` : « no graphical session … use --daemon » | pas de session graphique ouverte | relancer avec `--daemon` |875| 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` |876| Agent : `401 timestamp_out_of_window` ou `400 clock_skew` | horloge du nœud fausse (> 90 s) | corriger l'heure |877| Agent : `401 agent_revoked` | agent révoqué ou remplacé | nouveau jeton, ré-enrôler |878| 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` |879| 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` |880| Action : `422 capability_missing` | la politique locale du nœud n'autorise pas ce type | adapter `policy.json` sur le nœud |881| Action : `409 target_locked` | une autre action est en cours sur la cible | attendre ; `details.action_id` donne le détenteur |882| 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 |883| `503 orchestrator_frozen` | gel d'urgence actif | `scripts/mccctl unfreeze` après vérification |884| `403 step_up_required` | dernière cérémonie passkey vieille de plus de 5 min | refaire le step-up |885| `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 |886| `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 |887| 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 |888889Pièges propres aux apps Apple :890891- **Passkey système, erreur 1004** : une seconde copie enregistrée de l'identifiant de production, ou un build lancé892  depuis `~/Desktop`, fait échouer la feuille passkey. Les builds vont dans `/tmp/mcc-swift` / `/tmp/mcc-ios`, le893  build Release se lance depuis `/Applications`, et le Debug a son propre bundle id.894- **AASA avant le premier lancement** : le CDN d'Apple met le fichier en cache ; une entrée manquante fait échouer895  la passkey (1004) et ouvre les liens dans Safari. Vérifier896  `curl https://clustr.spboucher.ai/.well-known/apple-app-site-association`.897- **Contournements macOS 27.0** (à garder jusqu'à nouvel essai) : les écrans racine sont permutés ~150 ms après le898  changement d'état (crash `NSTrackingArea` sinon) ; `.inspector` n'est pas utilisé (boucle « Update Constraints ») ;899  `openWindow(id: "main")` crée toujours une fenêtre, d'où `AppModel.show` ; les listes de la barre latérale et des900  réglages sont des rangées de boutons explicites (la sélection de `List` ne répond pas au clic).901- **Énumérations fermées du client généré** : une NOUVELLE valeur envoyée par un serveur plus récent fait échouer le902  décodage de cette réponse ; les sujets d'événements, eux, sont traités avec tolérance (rechargement complet).903904## 🚧 État, limites connues, reste à faire905906Sources : [CHANGELOG.md](CHANGELOG.md), [docs/ACCEPTANCE.md §5](docs/ACCEPTANCE.md),907[docs/INTEGRATION-TODO.md](docs/INTEGRATION-TODO.md), [docs/SECURITY.md §14](docs/SECURITY.md),908[docs/API.md §8](docs/API.md).909910- **Compte owner** : aucun n'existait en production à la rédaction de ces documents (commit `45f0d03`) ; aucun911  parcours authentifié n'y était donc vérifié par une personne.912- **Écarts contrat / implémentation** (14 recensés) : charges utiles de plusieurs événements SSE (`action.output`,913  `audit.appended`, `node.updated` de l'ingestion, `resync`…), codes d'erreur d'authentification, limites de débit914  plus permissives que le contrat.915- **Réglages sans effet** : `retention.*_days` et `alerts.default_*` sont stockés mais lus par aucun service.916- **Non mesuré** : température et puissance (agent sans root) ; débit, latence et file d'attente des serveurs917  d'inférence.918- **Désactivé ou non livré** : `deploy.release`, `system.update.schedule` ; `model.server.*` non implémentés par919  l'agent ; redémarrage et extinction désactivés sur chaque agent ; terminal d'administration non livré920  ([ADR 0008](docs/DECISIONS/0008-no-arbitrary-shell.md)).921- **Non exercé** : restauration sur un autre nœud, rotation des clés (aucune rotation de l'AC sans ré-enrôlement),922  retour arrière d'une version, déplacement du plan de contrôle, renouvellement des certificats en production923  (premiers certificats émis le 2026-11-18, 30 jours).924- **Non vérifié** : Safari, Firefox et authentificateurs de plateforme réels côté web ; `go test -race` sur ingest925  et agent ; `control-api` pendant une coupure de base ; « déploiement interrompu ».926- **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é927  indépendant ; pas de HSM.928- **Documentation** : régénérer `docs/METRICS-CATALOG.md` avec la colonne Linux ; `docs/DESIGN-BRIEF.md` §1 liste929  encore les ports de développement ; `docs/APPLE-APPS.md` §8 à mettre à jour.930931## 📚 Documentation932933| Document | Sujet |934|---|---|935| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | diagrammes C4, flux, frontières de confiance, modèle de données, modes dégradés, capacité |936| [docs/SECURITY.md](docs/SECURITY.md) | modèle de menace, passkeys, sessions, autorisations, sûreté des actions, secrets, réponse aux incidents |937| [docs/OPERATIONS.md](docs/OPERATIONS.md) | installation, mise à jour, amorçage, agents, sauvegarde, supervision, dépannage, arrêt d'urgence |938| [docs/API.md](docs/API.md) | guide de l'API, flux d'événements, table des permissions, écarts contrat/implémentation |939| [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md) | matrice exigences → preuves |940| [docs/AGENT-PROTOCOL.md](docs/AGENT-PROTOCOL.md) | protocole agent ↔ ingestion |941| [docs/METRICS-CATALOG.md](docs/METRICS-CATALOG.md) | catalogue des métriques (généré) |942| [docs/DECISIONS/](docs/DECISIONS/README.md) | décisions d'architecture (ADR 0001 à 0010) |943| [docs/DESIGN-BRIEF.md](docs/DESIGN-BRIEF.md) | décisions de conception d'origine |944| [docs/REAL-INFRASTRUCTURE-INVENTORY.md](docs/REAL-INFRASTRUCTURE-INVENTORY.md) | relevé en lecture seule de l'infrastructure (phase 0) |945| [docs/MANDATE.md](docs/MANDATE.md) | résumé des contraintes du mandat |946| [docs/INTEGRATION-TODO.md](docs/INTEGRATION-TODO.md) | ce qui reste ouvert |947| [docs/APPLE-APPS.md](docs/APPLE-APPS.md) | applications macOS et iOS |948| [apps/web/DESIGN-SYSTEM.md](apps/web/DESIGN-SYSTEM.md) | système de design de l'application web |949| [CHANGELOG.md](CHANGELOG.md) | historique des versions |950951Captures d'écran : `docs/screenshots/web/`, `docs/screenshots/macos/`, `docs/screenshots/ios/`.952953<details>954<summary>Les 10 décisions d'architecture</summary>955956| ADR | Choix | Raison résumée |957|---|---|---|958| [0001](docs/DECISIONS/0001-new-product-no-reuse.md) | produit neuf, aucune reprise de l'ancien | mandat |959| [0002](docs/DECISIONS/0002-go-backend-and-agent.md) | Go pour les services et l'agent (binaire statique) | des Macs sans Homebrew ni Node ; passerelle linux/amd64 ; protocole partagé à la compilation |960| [0003](docs/DECISIONS/0003-postgresql-native-timeseries.md) | PostgreSQL partitionné, pas de TimescaleDB ni de Redis | extension absente partout ; volume modeste |961| [0004](docs/DECISIONS/0004-agent-transport-mtls-lan.md) | agents en sortie seulement ; requêtes signées via l'origine publique | confidentialité du réseau local de macOS, mesurée |962| [0005](docs/DECISIONS/0005-passkeys-only-identity.md) | passkeys seulement, sessions opaques, récupération hors bande | révocation immédiate, pas de secret partagé |963| [0006](docs/DECISIONS/0006-contract-first-three-clients.md) | OpenAPI 3.1 comme contrat unique, clients générés | une seule vérité pour trois clients |964| [0007](docs/DECISIONS/0007-unprivileged-agent.md) | agent sans root, métriques non mesurables déclarées | moindre privilège |965| [0008](docs/DECISIONS/0008-no-arbitrary-shell.md) | catalogue d'actions typées, pas de shell distant | moindre privilège |966| [0009](docs/DECISIONS/0009-hosting-and-exposure.md) | hôte unique derrière la passerelle existante | robustesse par simplicité |967| [0010](docs/DECISIONS/0010-at-most-once-commands.md) | au plus une commande par action ; issue inconnue = état | sûreté des opérations sur des machines réelles |968969</details>970971## 👤 Auteur972973<div align="center">974<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>975976**Simon-Pierre Boucher** — conception, développement, exploitation<br>977[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai978979</div>980981## 📄 Licence982983Propriétaire (`LicenseRef-Proprietary` dans le contrat). Tous droits réservés © 2026 Simon-Pierre Boucher.984Dépôt privé : `docs/REAL-INFRASTRUCTURE-INVENTORY.md` et `docs/recon/` contiennent des adresses privées.985
Files main
Menu

Theme