brainclaw 1.21.0 → 1.22.0

package/dist/core/federation-keyring.js

@@ -0,0 +1,241 @@
+/**
+ * Fédération v2 — identité d'APPAREIL et trousseau multi-epoch (pln#651 étape 3).
+ *
+ * Création propre, AUCUNE migration (dec#156) : ce module ne lit ni `cloud_sync` ni
+ * `BRAINCLAW_CLOUD_*` pour reconstruire un état. Le chemin v1 a été démoli en étape 2.
+ *
+ * ── POURQUOI DEUX PAIRES DE CLÉS ET NON UNE ────────────────────────────────────
+ * L'appareil porte DEUX clés distinctes, et aucune ne se dérive de l'autre :
+ *
+ *   Ed25519 (~/.brainclaw/keys/<agentId>.ed25519.pem, agent-registry.ts)
+ *     → QUI PARLE. Signature d'origine des enveloppes, preuve de possession
+ *       pendant l'appairage. C'est l'identité que le Cloud a déjà enregistrée.
+ *
+ *   X25519 (~/.brainclaw/keys/<deviceId>.x25519.pem, ce module)
+ *     → QUI PEUT LIRE. Destinataire des enveloppements HPKE qui remettent les
+ *       clés privées d'epoch.
+ *
+ * Les dériver l'une de l'autre est tentant (une seule clé à sauvegarder) et faux :
+ * cela lierait la capacité de LECTURE à la capacité de SIGNATURE, alors que le RFC
+ * §5.1 en fait une propriété d'architecture — « écrire sans lire ». Un émetteur qui
+ * ne doit pas lire reçoit la clé publique de projet et son accès de signature, rien
+ * d'autre. Avec des clés dérivées, révoquer la lecture révoquerait l'écriture, et
+ * la compromission de l'une livrerait l'autre.
+ *
+ * ── PLAFOND DE SÉCURITÉ, ÉCRIT ICI PARCE QUE C'EST ICI QU'ON LIT LA CLÉ ────────
+ * `~/.brainclaw/keys/` est un répertoire du système de fichiers, lisible par TOUT
+ * processus tournant sous le même UID. Sur Windows le mode 0600 de `fs.chmod` est
+ * largement ignoré. Donc : la sécurité du chiffrement de bout en bout côté Cloud
+ * NE DÉPASSE PAS celle du disque local. Un malware ayant l'UID de l'utilisateur lit
+ * les clés d'epoch et déchiffre tout ce que l'appareil pouvait déchiffrer.
+ *
+ * Ce n'est pas un défaut à corriger dans ce step : TPM, enclave sécurisée et HSM
+ * sont explicitement une v2 ultérieure (RFC §5.1). C'est un plafond à ÉNONCER, pour
+ * qu'on ne vende pas au-delà de ce que la construction tient.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MEMORY_DIR } from './io.js';
+import { nowISO } from './ids.js';
+import { logger } from './logger.js';
+/** Empreinte canonique d'une clé publique PEM — même règle que Ed25519 (agent-registry.ts). */
+export function fingerprintKeyPem(publicKeyPem) {
+    return crypto.createHash('sha256').update(publicKeyPem.replace(/\r/g, '').trim()).digest('hex');
+}
+// ── Emplacements ──────────────────────────────────────────────────────────────
+/** Racine neutre des secrets : ~/.brainclaw/ — JAMAIS le store de workspace. */
+function keysRoot(home = os.homedir()) {
+    return path.join(home, MEMORY_DIR, 'keys');
+}
+/**
+ * Clé privée X25519 de l'appareil.
+ *
+ * Voisine de la clé Ed25519 par CHOIX : un seul répertoire à protéger, à sauvegarder
+ * et à effacer. Le suffixe distingue les deux algorithmes de façon lisible sans avoir
+ * à ouvrir le fichier.
+ */
+export function deviceKeyPath(deviceId, home = os.homedir()) {
+    return path.join(keysRoot(home), `${deviceId}.x25519.pem`);
+}
+/**
+ * Clés privées d'epoch, cloisonnées PAR PROJET CLOUD.
+ *
+ * Le cloisonnement n'est pas cosmétique : `disconnect` d'un projet doit pouvoir
+ * effacer ses clés sans toucher à celles d'un autre projet auquel la même machine
+ * est appairée. Un trousseau à plat rendrait cette suppression sélective fragile.
+ */
+export function epochKeyPath(cloudProjectId, epoch, home = os.homedir()) {
+    return path.join(keysRoot(home), 'epochs', cloudProjectId, `epoch-${epoch}.x25519.pem`);
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/**
+ * Écrit un secret sur disque en RESTREIGNANT les permissions AVANT d'écrire les
+ * octets, pas après.
+ *
+ * `writeFileSync(p, data)` puis `chmodSync(p, 0o600)` laisse une fenêtre où le
+ * fichier existe en 0644 avec la clé dedans. Le mode passé à l'ouverture ferme
+ * cette fenêtre. Sur Windows le mode est largement ignoré — d'où le plafond
+ * documenté en tête de module ; ce n'est pas une raison de l'omettre sur POSIX,
+ * où il est effectif.
+ */
+function writeSecretFile(filepath, contents) {
+    ensureDir(path.dirname(filepath));
+    fs.writeFileSync(filepath, contents, { encoding: 'utf-8', mode: 0o600 });
+}
+/**
+ * Retourne la clé X25519 de l'appareil, en la créant au premier appel.
+ *
+ * NE FAIT JAMAIS TOURNER une clé existante — même contrat que `ensureAgentSigningKey`
+ * pour Ed25519, et pour la même raison en plus grave : une rotation silencieuse
+ * casserait l'attestation déjà approuvée par un humain côté Cloud, et rendrait
+ * ILLISIBLES toutes les enveloppes d'epoch déjà remises à l'ancienne clé. Une clé de
+ * signature perdue empêche d'écrire ; une clé de déchiffrement perdue perd des données.
+ */
+export function ensureDeviceKey(deviceId, home = os.homedir()) {
+    const filepath = deviceKeyPath(deviceId, home);
+    if (fs.existsSync(filepath)) {
+        const privateKey = crypto.createPrivateKey(fs.readFileSync(filepath, 'utf-8'));
+        const publicKeyPem = crypto
+            // @types/node 26 a retiré la surcharge KeyObject de createPublicKey (régression :
+            // Node accepte une clé privée pour en dériver la publique, comme documenté).
+            // Même contournement que agent-registry.ts ; comportement d'exécution inchangé.
+            .createPublicKey(privateKey)
+            .export({ type: 'spki', format: 'pem' })
+            .toString();
+        return {
+            device_id: deviceId,
+            public_key_pem: publicKeyPem,
+            fingerprint: fingerprintKeyPem(publicKeyPem),
+            created_at: fs.statSync(filepath).birthtime.toISOString(),
+        };
+    }
+    const generated = crypto.generateKeyPairSync('x25519');
+    const privateKeyPem = generated.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+    const publicKeyPem = generated.publicKey.export({ type: 'spki', format: 'pem' }).toString();
+    writeSecretFile(filepath, privateKeyPem);
+    return {
+        device_id: deviceId,
+        public_key_pem: publicKeyPem,
+        fingerprint: fingerprintKeyPem(publicKeyPem),
+        created_at: nowISO(),
+    };
+}
+/**
+ * Charge la clé privée X25519 de l'appareil, ou `undefined` si absente.
+ *
+ * Ne CRÉE rien : un appelant qui a besoin de déchiffrer et ne trouve pas la clé doit
+ * traiter cela comme un échec explicite, pas voir une clé fraîche se matérialiser et
+ * échouer plus tard, plus loin, sur un déchiffrement incompréhensible.
+ */
+export function loadDevicePrivateKey(deviceId, home = os.homedir()) {
+    const filepath = deviceKeyPath(deviceId, home);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    return crypto.createPrivateKey(fs.readFileSync(filepath, 'utf-8'));
+}
+/**
+ * Enregistre la clé privée d'un epoch, remise par une enveloppe HPKE après approbation.
+ *
+ * REFUSE D'ÉCRASER un epoch déjà détenu. Deux clés différentes pour un même numéro
+ * d'epoch signifie que quelque chose s'est mal passé en amont — le Cloud a resservi un
+ * autre roster, ou deux appairages se marchent dessus. Écraser rendrait silencieusement
+ * illisible tout ce qui a été scellé sous la première ; l'erreur est le bon comportement.
+ * Ré-enregistrer la MÊME clé est en revanche idempotent : une reprise d'appairage
+ * interrompu ne doit pas échouer (le step 4 exige une reprise sûre).
+ */
+export function storeEpochPrivateKey(cloudProjectId, epoch, privateKeyPem, home = os.homedir()) {
+    const filepath = epochKeyPath(cloudProjectId, epoch, home);
+    if (fs.existsSync(filepath)) {
+        const existing = fs.readFileSync(filepath, 'utf-8').replace(/\r/g, '').trim();
+        if (existing === privateKeyPem.replace(/\r/g, '').trim())
+            return;
+        throw new Error(`Refus d'écraser la clé de l'epoch ${epoch} du projet ${cloudProjectId} : ` +
+            `une clé DIFFÉRENTE est déjà détenue. Écraser rendrait illisible tout ce qui a été ` +
+            `scellé sous la clé actuelle. Vérifier le roster côté cloud avant de forcer.`);
+    }
+    // Valider AVANT d'écrire : un PEM corrompu stocké se découvrirait au premier
+    // déchiffrement, longtemps après, sans lien évident avec l'appairage qui l'a produit.
+    const key = crypto.createPrivateKey(privateKeyPem);
+    if (key.asymmetricKeyType !== 'x25519') {
+        throw new Error(`Clé d'epoch invalide : attendu x25519, reçu ${key.asymmetricKeyType ?? 'inconnu'}`);
+    }
+    writeSecretFile(filepath, privateKeyPem);
+}
+/** Charge la clé privée d'un epoch, ou `undefined` si cet epoch n'est pas détenu. */
+export function loadEpochPrivateKey(cloudProjectId, epoch, home = os.homedir()) {
+    const filepath = epochKeyPath(cloudProjectId, epoch, home);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    try {
+        return crypto.createPrivateKey(fs.readFileSync(filepath, 'utf-8'));
+    }
+    catch (err) {
+        // Une clé illisible n'est PAS équivalente à une clé absente : la première est une
+        // corruption à signaler, la seconde un état normal. On journalise et on renvoie
+        // undefined pour que l'appelant refuse le déchiffrement — jamais un fallback muet.
+        logger.warn(`Clé d'epoch ${epoch} illisible pour ${cloudProjectId}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Énumère les epochs dont la clé privée est détenue localement — le trousseau réel,
+ * lu SUR DISQUE et non déduit de l'état de connexion.
+ *
+ * La distinction compte : l'état de connexion dit ce que l'appareil CROIT détenir,
+ * le disque dit ce qu'il détient VRAIMENT. `federation-state.ts` réconcilie les deux
+ * plutôt que de faire confiance au JSON, parce qu'une restauration partielle de
+ * sauvegarde produit exactement ce désaccord.
+ */
+export function heldEpochs(cloudProjectId, home = os.homedir()) {
+    const dir = path.dirname(epochKeyPath(cloudProjectId, 0, home));
+    if (!fs.existsSync(dir))
+        return [];
+    const epochs = [];
+    for (const entry of fs.readdirSync(dir)) {
+        const match = /^epoch-(\d+)\.x25519\.pem$/.exec(entry);
+        if (match)
+            epochs.push(Number(match[1]));
+    }
+    return epochs.sort((a, b) => a - b);
+}
+/**
+ * Efface les clés d'epoch d'un projet — appelé par `cloud disconnect`.
+ *
+ * CE QUE ÇA NE FAIT PAS, et que la commande appelante doit dire à l'humain : cela
+ * n'efface pas les blobs déjà tirés et déchiffrés localement, ni ce qu'un autre
+ * appareil détient. `disconnect` retire une autorisation locale ; il ne réécrit pas
+ * le passé (RFC §5.2). Retourne le nombre de clés supprimées.
+ */
+export function forgetProjectEpochs(cloudProjectId, home = os.homedir()) {
+    const dir = path.dirname(epochKeyPath(cloudProjectId, 0, home));
+    if (!fs.existsSync(dir))
+        return 0;
+    let removed = 0;
+    for (const entry of fs.readdirSync(dir)) {
+        if (!/^epoch-\d+\.x25519\.pem$/.test(entry))
+            continue;
+        fs.rmSync(path.join(dir, entry), { force: true });
+        removed++;
+    }
+    try {
+        fs.rmdirSync(dir);
+    }
+    catch { /* non vide ou déjà parti : sans conséquence */ }
+    return removed;
+}
+/** Clé publique d'un epoch détenu, dérivée de la privée — utile pour afficher son empreinte. */
+export function epochPublicKey(cloudProjectId, epoch, home = os.homedir()) {
+    const priv = loadEpochPrivateKey(cloudProjectId, epoch, home);
+    if (!priv)
+        return undefined;
+    const pem = crypto
+        .createPublicKey(priv)
+        .export({ type: 'spki', format: 'pem' })
+        .toString();
+    return { public_key_pem: pem, fingerprint: fingerprintKeyPem(pem) };
+}
+//# sourceMappingURL=federation-keyring.js.map

package/dist/core/federation-message.js

@@ -13,17 +13,17 @@ export const FederationMessageSchema = z.object({
         agent_name: z.string(),
         agent_id: z.string().optional(),
         host_id: z.string().optional(),
-    }),
+    }).strict(),
     to: z.object({
         project_name: z.string(),
         project_path: z.string(),
         agent_name: z.string().optional(),
-    }),
-    type: z.enum(['signal', 'handoff', 'candidate', 'runtime_note', 'board_snapshot']),
-    payload: z.unknown(),
+    }).strict(),
+    type: z.enum(['handoff', 'candidate', 'runtime_note']),
+    payload: z.record(z.string(), z.unknown()),
     created_at: z.string(),
     causal_parent: z.string().optional(),
-});
+}).strict();
 function computeIdempotencyKey(msg) {
     const data = JSON.stringify({ from: msg.from, to: msg.to, type: msg.type, payload: msg.payload });
     return crypto.createHash('sha256').update(data).digest('hex').slice(0, 16);

package/dist/core/federation-outbox-v2.js

@@ -0,0 +1,125 @@
+/**
+ * Fédération v2 — outbox locale (pln#651 étape 3).
+ *
+ * Création propre : l'outbox v1 (`federation-outbox.ts`) a été SUPPRIMÉE en étape 2 avec
+ * ses 112 enveloppes en attente, dont 50 portaient un `worktree_path` absolu et 48 le nom
+ * d'hôte de la machine (dec#156-d). Rien n'est repris d'elle — ni format, ni contenu.
+ *
+ * ── CE QUE CETTE OUTBOX SAIT, ET CE QU'ELLE NE SAIT PAS ───────────────────────
+ * Elle stocke des enveloppes DÉJÀ SCELLÉES et suit leur état. Elle ne construit pas
+ * l'enveloppe, ne chiffre pas, ne classe pas les champs : c'est l'étape 5 (le projecteur
+ * et ses trois filets). La séparation est délibérée — une file d'attente qui saurait
+ * aussi fabriquer son contenu serait un second chemin de sérialisation, donc un second
+ * endroit où un champ non classé peut fuir.
+ *
+ * Conséquence testable : ce module n'accepte QUE la partie `sealed` opaque et des
+ * métadonnées de transport. Il n'a aucun accès au clair, donc il ne peut pas le divulguer.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryDir, writeFileAtomic } from './io.js';
+import { nowISO } from './ids.js';
+import { logger } from './logger.js';
+/** Les trois répertoires SONT les trois états — l'état est le chemin, pas un champ. */
+const STATE_DIRS = {
+    pending: 'outbox',
+    synced: 'sent',
+    conflict: 'conflict',
+};
+export const OUTBOX_ENTRY_SCHEMA = 'brainclaw.federation-outbox-entry/v2';
+function stateDir(state, cwd) {
+    return path.join(memoryDir(cwd), 'coordination', 'federation', STATE_DIRS[state]);
+}
+function entryPath(state, idempotencyKey, cwd) {
+    return path.join(stateDir(state, cwd), `${idempotencyKey}.json`);
+}
+/**
+ * Met une enveloppe scellée en file d'attente.
+ *
+ * IDEMPOTENT PAR CONSTRUCTION : la clé d'idempotence est le NOM DU FICHIER, donc un
+ * double enqueue de la même opération ne peut pas produire deux entrées. C'est ce que
+ * `materializeFederationSignal` ne faisait pas — il frappait un nouvel id et un nouveau
+ * created_at à chaque passage, rendant le dédoublonnage absent par construction (étape 6).
+ *
+ * Une entrée déjà `synced` n'est pas remise en attente : la retransmission d'une opération
+ * confirmée est exactement le rejeu contre lequel l'étape 6 protège à la réception ; il
+ * n'y a pas de raison de l'émettre depuis ici.
+ */
+export function enqueue(entry, cwd = process.cwd()) {
+    for (const state of ['synced', 'pending', 'conflict']) {
+        if (fs.existsSync(entryPath(state, entry.idempotency_key, cwd)))
+            return false;
+    }
+    const now = nowISO();
+    const full = { schema: OUTBOX_ENTRY_SCHEMA, ...entry, attempts: 0, created_at: now, updated_at: now };
+    const filepath = entryPath('pending', entry.idempotency_key, cwd);
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    writeFileAtomic(filepath, `${JSON.stringify(full, null, 2)}\n`);
+    return true;
+}
+/**
+ * Déplace une entrée d'un état vers un autre.
+ *
+ * Le déplacement est un `rename` : une entrée ne peut pas exister dans deux états à la
+ * fois, même si le processus meurt au milieu. Une copie-puis-suppression laisserait une
+ * fenêtre où l'opération est comptée deux fois — et les compteurs de `status` mentiraient
+ * précisément pendant l'incident où on les consulte.
+ */
+export function transition(idempotencyKey, from, to, cwd = process.cwd(), mutate) {
+    const src = entryPath(from, idempotencyKey, cwd);
+    if (!fs.existsSync(src))
+        return false;
+    const dest = entryPath(to, idempotencyKey, cwd);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (mutate) {
+        try {
+            const entry = JSON.parse(fs.readFileSync(src, 'utf-8'));
+            const next = mutate({ ...entry, updated_at: nowISO() });
+            writeFileAtomic(dest, `${JSON.stringify(next, null, 2)}\n`);
+            fs.rmSync(src, { force: true });
+            return true;
+        }
+        catch (err) {
+            logger.warn(`Entrée d'outbox illisible (${idempotencyKey}) : ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    fs.renameSync(src, dest);
+    return true;
+}
+/** Entrées d'un état donné, triées par date de création. */
+export function list(state, cwd = process.cwd()) {
+    const dir = stateDir(state, cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            entries.push(JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8')));
+        }
+        catch {
+            // Une entrée corrompue est ignorée à la lecture mais reste sur disque : la
+            // supprimer ici effacerait la seule trace d'une opération peut-être jamais émise.
+            logger.warn(`Entrée d'outbox ignorée (illisible) : ${name}`);
+        }
+    }
+    return entries.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+/**
+ * Compte les trois états EN LES LISANT SUR DISQUE.
+ *
+ * Les compteurs de `connection.json` sont un cache d'affichage ; ceci est la vérité. Le
+ * critère de sortie de l'étape 3 dit « observables par une commande » — observer un
+ * compteur qu'on a soi-même incrémenté n'observe rien, c'est se relire. En cas d'écart,
+ * c'est ce comptage qui gagne.
+ */
+export function counters(cwd = process.cwd()) {
+    return {
+        pending: list('pending', cwd).length,
+        synced: list('synced', cwd).length,
+        conflict: list('conflict', cwd).length,
+    };
+}
+//# sourceMappingURL=federation-outbox-v2.js.map

package/dist/core/federation-pairing.js

@@ -0,0 +1,213 @@
+/**
+ * Cérémonie d'appairage — fédération v2 (pln#651 étape 4, RFC §5.2).
+ *
+ * C'est le chantier qui a motivé toute la recherche : l'enrôlement v1 était lourd et
+ * fastidieux, et surtout il n'était pas sûr — présenter un PEM suffisait à activer un
+ * agent. Ici, rejoindre un projet est une CÉRÉMONIE DE CLÉS.
+ *
+ * ── POURQUOI L'APPAIRAGE ET LA DISTRIBUTION DE CLÉS SONT UN SEUL CHANTIER ─────
+ * On pourrait croire qu'un « enrôlement simple » d'abord, le chiffrement ensuite, serait
+ * plus rapide. Ce serait faux deux fois. D'abord parce que la clé de chiffrement de
+ * l'appareil doit être ATTESTÉE par son identité Ed25519 — sans quoi le Cloud, qui
+ * orchestre l'appairage, peut insérer sa propre clé dans la liste d'enveloppement.
+ * Ensuite parce que livrer les deux séparément produirait DEUX flux d'enrôlement et
+ * imposerait de réenrôler tout le monde au moment de la bascule.
+ *
+ * ── INTERDIT DANS LE CHEMIN NOMINAL (dec#8) ──────────────────────────────────
+ * Aucune clé d'API, aucun PEM, aucun agent_id, aucune variable d'environnement à copier
+ * à la main. L'humain manipule UN code d'invitation et compare DEUX empreintes. Tout le
+ * reste est dérivé localement ou négocié par le protocole.
+ *
+ * La clé d'API manuelle reste un mécanisme de compatibilité documenté, HORS de ce
+ * parcours — et sa seule présence n'active plus rien (c'est le défaut v1 fermé en vague 1).
+ */
+import crypto from 'node:crypto';
+import { nowISO } from './ids.js';
+import { loadAgentSigningKey, ensureAgentSigningKey } from './agent-registry.js';
+import { buildKeyAttestation, fingerprintPem } from './federation-attestation.js';
+import { ensureDeviceKey, } from './federation-keyring.js';
+import { createConnectionState, loadConnectionState, saveConnectionState, newDeviceId, } from './federation-state.js';
+export class PairingError extends Error {
+    stage;
+    status;
+    constructor(message, stage, status) {
+        super(message);
+        this.stage = stage;
+        this.status = status;
+        this.name = 'PairingError';
+    }
+}
+/**
+ * Phases 1 à 3 du parcours : réclamer l'invitation, prouver la possession de l'identité,
+ * attester la clé de chiffrement. Le tout SANS que l'humain ne copie autre chose que le
+ * code d'invitation.
+ *
+ * REPRENABLE PAR CONSTRUCTION. Chaque phase est un appel distinct dont le résultat est
+ * écrit avant la suivante, et la clé d'appareil n'est jamais régénérée si elle existe
+ * (`ensureDeviceKey`). Une interruption laisse un enrollment en attente côté cloud, qui
+ * expire proprement — jamais un orphelin non réclamable.
+ */
+export async function beginPairing(params) {
+    const cwd = params.cwd ?? process.cwd();
+    // (1) L'IDENTITÉ D'ABORD. `ensureAgentSigningKey` ne fait PAS tourner une clé
+    // existante : une rotation silencieuse invaliderait l'empreinte déjà approuvée côté
+    // cloud, et l'agent se retrouverait rejeté sans comprendre pourquoi.
+    ensureAgentSigningKey(params.agentId);
+    const identity = loadAgentSigningKey(params.agentId);
+    if (!identity) {
+        throw new PairingError(`Aucune clé d'identité Ed25519 pour l'agent '${params.agentId}'. La cérémonie ne peut pas commencer sans identité.`, 'identity');
+    }
+    // (2) RÉCLAMER L'INVITATION. Le code n'est jamais stocké — ni ici, ni côté cloud, qui
+    // n'en garde que le SHA-256.
+    const claimed = await params.transport.post('/api/v1/enrollments/claim', {
+        invite_code: params.inviteCode,
+        identity_public_key_pem: identity.publicKeyPem,
+        agent_id: params.agentId,
+    });
+    if (claimed.status !== 200 && claimed.status !== 201) {
+        throw new PairingError(describeError(claimed.body, "l'invitation n'a pas pu être réclamée"), 'claim', claimed.status);
+    }
+    const enrollmentId = asString(claimed.body['enrollment_id']);
+    const cloudProjectId = asString(claimed.body['project_id']);
+    const challenge = asString(claimed.body['pop_challenge']);
+    if (!enrollmentId || !cloudProjectId || !challenge) {
+        throw new PairingError('Réponse de claim incomplète (enrollment_id, project_id ou pop_challenge manquant).', 'claim');
+    }
+    // Le cloud renvoie l'empreinte qu'il a calculée. On la RECALCULE localement et on
+    // compare : un désaccord signifie que la clé enregistrée n'est pas celle qu'on croit
+    // avoir envoyée, ce qui invaliderait toute la chaîne d'attestation qui suit.
+    const remoteIdentityFp = asString(claimed.body['identity_key_fingerprint']);
+    const localIdentityFp = fingerprintPem(identity.publicKeyPem);
+    if (remoteIdentityFp && remoteIdentityFp !== localIdentityFp) {
+        throw new PairingError(`Empreinte d'identité divergente : le cloud a enregistré ${remoteIdentityFp}, cet appareil détient ${localIdentityFp}. ` +
+            `Interrompre — la clé enregistrée n'est pas celle de cet appareil.`, 'claim');
+    }
+    // (3) LA CLÉ DE CHIFFREMENT DE L'APPAREIL. Distincte de l'identité, jamais dérivée
+    // d'elle (RFC §5.1) — c'est ce qui rend « écrire sans lire » possible.
+    const deviceId = params.deviceId ?? newDeviceId();
+    const device = ensureDeviceKey(deviceId);
+    // (4) PREUVE DE POSSESSION + ATTESTATION, EN UN SEUL ACTE. Les deux signatures sont
+    // produites par la MÊME clé d'identité : c'est ce lien qui interdit à quiconque
+    // d'attester une clé de chiffrement sans détenir l'identité approuvée.
+    const challengeSignature = crypto
+        .sign(null, Buffer.from(new TextEncoder().encode(challenge)), crypto.createPrivateKey(identity.privateKeyPem))
+        .toString('base64');
+    const attestation = buildKeyAttestation({
+        enrollmentId,
+        projectId: cloudProjectId,
+        agentId: params.agentId,
+        encryptionPublicKeyPem: device.public_key_pem,
+        identityPrivateKeyPem: identity.privateKeyPem,
+        // L'horodatage vient d'ICI et voyage avec la signature. Le serveur ne le fabrique
+        // pas : il ne pourrait pas, l'appareil ayant signé avant qu'il ne l'apprenne.
+        createdAt: nowISO(),
+    });
+    const proved = await params.transport.post(`/api/v1/enrollments/${enrollmentId}/prove`, {
+        invite_code: params.inviteCode,
+        challenge_signature: challengeSignature,
+        encryption_public_key_pem: device.public_key_pem,
+        attestation_signature: attestation.signature,
+        attestation_created_at: attestation.created_at,
+        key_type: 'encryption',
+        key_purpose: 'envelope',
+    });
+    if (proved.status !== 200) {
+        throw new PairingError(describeError(proved.body, "la preuve de possession a été refusée"), 'prove', proved.status);
+    }
+    // (5) ÉTAT LOCAL en 'pending'. Créer l'état ne vaut pas approbation — le passage à
+    // 'active' appartient à la confirmation humaine, phase suivante.
+    const deviceRecord = {
+        device_id: deviceId,
+        x25519_fingerprint: device.fingerprint,
+        attested_by_ed25519: localIdentityFp,
+        enrolled_at: nowISO(),
+        // Le premier appareil est marqué récupération : sans cela, un projet mono-appareil
+        // n'atteindrait jamais le quorum de RFC §5.3 et ne pourrait rien émettre. Le second
+        // porteur reste exigé — `recoveryReadiness` continue de refuser tant qu'il manque.
+        recovery: true,
+    };
+    const state = createConnectionState({
+        cloudProjectId,
+        device: deviceRecord,
+        workspacePath: cwd,
+        enrollmentId,
+    });
+    saveConnectionState(state, cwd);
+    return {
+        enrollment_id: enrollmentId,
+        cloud_project_id: cloudProjectId,
+        device,
+        fingerprints: { identity: localIdentityFp, encryption: device.fingerprint },
+        state,
+    };
+}
+/**
+ * Interroge l'état d'un enrollment en attente d'approbation.
+ *
+ * NE MATÉRIALISE RIEN. Le premier pull réel est en lecture seule et non destructif
+ * (RFC §5.2 phase 4) ; cette fonction ne fait que lire un état de cérémonie.
+ */
+export async function checkPairingApproval(params) {
+    const res = await params.transport.get(`/api/v1/enrollments/${params.enrollmentId}`);
+    if (res.status !== 200) {
+        throw new PairingError(describeError(res.body, "l'état de l'enrôlement n'a pas pu être lu"), 'poll', res.status);
+    }
+    const enrollment = (res.body['enrollment'] ?? res.body);
+    const state = asString(enrollment['state']) ?? 'unknown';
+    return { state, role: asString(enrollment['invited_role']), approved: state === 'active' };
+}
+/**
+ * Bascule l'état local en 'active' une fois l'approbation obtenue.
+ *
+ * SÉPARÉ DU SONDAGE VOLONTAIREMENT : lire l'état distant et modifier l'état local sont
+ * deux actes. Les fusionner ferait qu'une lecture de statut mute le workspace — un effet
+ * de bord invisible dans une commande qu'on croit inoffensive.
+ */
+export function completePairing(params) {
+    const cwd = params.cwd ?? process.cwd();
+    const state = loadConnectionState(cwd);
+    if (!state) {
+        throw new PairingError("Aucun état d'appairage local — relancer `brainclaw cloud connect`.", 'complete');
+    }
+    const next = {
+        ...state,
+        enrollment: { ...state.enrollment, stage: 'active', role: params.role ?? state.enrollment.role, updated_at: nowISO() },
+    };
+    saveConnectionState(next, cwd);
+    return next;
+}
+/**
+ * Ce qu'un `disconnect` fait — et surtout ce qu'il NE FAIT PAS.
+ *
+ * Il retire l'autorisation LOCALE et demande la révocation distante. Il ne prétend pas
+ * effacer les blobs déjà tirés ni les clés déjà lues par d'autres appareils (RFC §5.2).
+ * Le dire est le contrat ; le taire laisserait croire à un effacement rétroactif que la
+ * cryptographie ne permet pas.
+ */
+export async function requestRevocation(params) {
+    try {
+        const res = await params.transport.post(`/api/v1/enrollments/${params.enrollmentId}/revoke`, {
+            reason: params.reason ?? 'disconnect local',
+        });
+        return { revoked: res.status === 200, detail: asString(res.body['error']) };
+    }
+    catch (err) {
+        // Un cloud injoignable ne doit PAS empêcher de se déconnecter localement : sinon un
+        // appareil perdu resterait autorisé faute de réseau. On rend l'échec, l'appelant
+        // efface quand même le local et le dit à l'humain.
+        return { revoked: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+// ── Aides ─────────────────────────────────────────────────────────────────────
+function asString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** Remonte le message du serveur quand il y en a un, plutôt qu'un libellé générique. */
+function describeError(body, fallback) {
+    const err = asString(body['error']);
+    const code = asString(body['code']);
+    if (err)
+        return code ? `${err} (${code})` : err;
+    return fallback;
+}
+//# sourceMappingURL=federation-pairing.js.map