brainclaw 1.20.4 → 1.22.0

package/dist/core/federation-hpke.js

@@ -0,0 +1,213 @@
+/**
+ * HPKE mode base — DHKEM(X25519, HKDF-SHA256) / HKDF-SHA256 / ChaCha20-Poly1305.
+ * Suite v1 du RFC fédération §3.1, conforme à la RFC 9180.
+ *
+ * ── POURQUOI CE CODE EXISTE PLUTÔT QU'UNE DÉPENDANCE ──────────────────────────
+ * Node n'expose pas HPKE. Le projet tient à zéro dépendance d'exécution hors
+ * commander/yaml/zod, et ajouter une bibliothèque de crypto pour un usage aussi restreint
+ * — mode base, une suite, chiffrement à un coup — élargirait la surface d'audit bien
+ * au-delà du besoin.
+ *
+ * CE QUI EST IMPLÉMENTÉ, ET CE QUI NE L'EST PAS. Uniquement le MODE BASE (`mode = 0x00`)
+ * en un seul coup. Ni PSK, ni authentification de l'expéditeur, ni API à secret exporté,
+ * ni chiffrements multiples sur un même contexte. L'authenticité de l'émetteur ne repose
+ * PAS sur HPKE ici : elle vient de la signature Ed25519 d'origine, portée dans
+ * l'enveloppe et vérifiée par tout lecteur (RFC §3.1). Confondre les deux serait une
+ * erreur d'architecture — HPKE en mode base ne dit rien de QUI a chiffré.
+ *
+ * TOUTES LES CONSTANTES SONT CELLES DE LA RFC 9180 et sont vérifiées contre le vecteur de
+ * test A.2 dans tests/unit/federation-hpke.test.ts. Un « ça a l'air juste » sur du code
+ * cryptographique ne vaut rien : soit le vecteur officiel passe, soit l'implémentation
+ * est fausse.
+ */
+import crypto from 'node:crypto';
+// Identifiants d'algorithmes (RFC 9180 §7). Encodés en 16 bits gros-boutiste dans suite_id.
+const KEM_ID = 0x0020; // DHKEM(X25519, HKDF-SHA256)
+const KDF_ID = 0x0001; // HKDF-SHA256
+const AEAD_ID = 0x0003; // ChaCha20-Poly1305
+const NH = 32; // taille de sortie de SHA-256
+const NK = 32; // taille de clé ChaCha20-Poly1305
+const NN = 12; // taille de nonce ChaCha20-Poly1305
+const MODE_BASE = 0x00;
+export const HPKE_SUITE = 'HPKE-v1/X25519-HKDF-SHA256-CHACHA20POLY1305';
+function concat(...parts) {
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+function u16(n) {
+    return new Uint8Array([(n >> 8) & 0xff, n & 0xff]);
+}
+function ascii(s) {
+    return new TextEncoder().encode(s);
+}
+/** RFC 9180 §4 : suite_id du KEM, distinct de celui du contexte HPKE. */
+function kemSuiteId() {
+    return concat(ascii('KEM'), u16(KEM_ID));
+}
+/**
+ * RFC 9180 §5.1 : suite_id du contexte, couvrant KEM, KDF et AEAD.
+ *
+ * `aeadId` est paramétrable UNIQUEMENT pour la validation par vecteurs. La RFC ne publie
+ * en clair dans son corps que l'appendice A.1 (AES-128-GCM) ; pouvoir instancier le
+ * schedule sous cet identifiant permet de vérifier toute la machinerie
+ * labeled_extract/labeled_expand contre des valeurs officielles, plutôt que de se
+ * contenter d'un aller-retour interne qui passerait tout aussi bien avec deux erreurs
+ * symétriques. La suite de production reste figée à ChaCha20-Poly1305.
+ */
+function hpkeSuiteId(aeadId = AEAD_ID) {
+    return concat(ascii('HPKE'), u16(KEM_ID), u16(KDF_ID), u16(aeadId));
+}
+function labeledExtract(suiteId, salt, label, ikm) {
+    // labeled_ikm = "HPKE-v1" || suite_id || label || ikm  (RFC 9180 §4)
+    const labeledIkm = concat(ascii('HPKE-v1'), suiteId, ascii(label), ikm);
+    return new Uint8Array(crypto.createHmac('sha256', Buffer.from(salt)).update(Buffer.from(labeledIkm)).digest());
+}
+function labeledExpand(suiteId, prk, label, info, length) {
+    const labeledInfo = concat(u16(length), ascii('HPKE-v1'), suiteId, ascii(label), info);
+    // HKDF-Expand (RFC 5869) : T(i) = HMAC(prk, T(i-1) || info || i)
+    const out = new Uint8Array(length);
+    let t = new Uint8Array(0);
+    let off = 0;
+    for (let i = 1; off < length; i++) {
+        t = new Uint8Array(crypto.createHmac('sha256', Buffer.from(prk))
+            .update(Buffer.from(concat(t, labeledInfo, new Uint8Array([i]))))
+            .digest());
+        const take = Math.min(t.length, length - off);
+        out.set(t.subarray(0, take), off);
+        off += take;
+    }
+    return out;
+}
+function extractAndExpand(dh, kemContext) {
+    const suiteId = kemSuiteId();
+    const eaePrk = labeledExtract(suiteId, new Uint8Array(0), 'eae_prk', dh);
+    return labeledExpand(suiteId, eaePrk, 'shared_secret', kemContext, NH);
+}
+// ── Conversions de clés X25519 ────────────────────────────────────────────────
+/**
+ * Octets bruts (32) d'une clé publique X25519 depuis son PEM SPKI.
+ *
+ * L'en-tête SPKI d'une X25519 fait exactement 12 octets et est constant pour cet
+ * algorithme ; les 32 derniers octets sont la clé. On prend la FIN du DER plutôt qu'un
+ * décalage fixe depuis le début : le préfixe pourrait varier d'un encodeur à l'autre,
+ * la longueur de la clé, non.
+ */
+export function rawPublicKey(pem) {
+    const der = crypto.createPublicKey(pem).export({ type: 'spki', format: 'der' });
+    return new Uint8Array(der.subarray(der.length - 32));
+}
+function publicKeyFromRaw(raw) {
+    // Préfixe SPKI de X25519 : SEQUENCE { SEQUENCE { OID 1.3.101.110 }, BIT STRING }
+    const prefix = Buffer.from('302a300506032b656e032100', 'hex');
+    return crypto.createPublicKey({
+        key: Buffer.concat([prefix, Buffer.from(raw)]),
+        format: 'der',
+        type: 'spki',
+    });
+}
+// ── KEM : encapsulation / décapsulation ───────────────────────────────────────
+function encapsulate(recipientPublicPem) {
+    const ephemeral = crypto.generateKeyPairSync('x25519');
+    const recipientKey = crypto.createPublicKey(recipientPublicPem);
+    const dh = new Uint8Array(crypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipientKey }));
+    const enc = new Uint8Array(ephemeral.publicKey.export({ type: 'spki', format: 'der' }).subarray(-32));
+    const pkRm = rawPublicKey(recipientPublicPem);
+    // kem_context = enc || pkRm — l'ordre est normatif ; l'inverser produit un secret
+    // différent des deux côtés et un échec de déchiffrement sans explication.
+    return { sharedSecret: extractAndExpand(dh, concat(enc, pkRm)), enc };
+}
+function decapsulate(enc, recipientPrivateKey) {
+    const ephemeralPublic = publicKeyFromRaw(enc);
+    const dh = new Uint8Array(crypto.diffieHellman({ privateKey: recipientPrivateKey, publicKey: ephemeralPublic }));
+    const pkRm = new Uint8Array(crypto.createPublicKey(recipientPrivateKey).export({ type: 'spki', format: 'der' }).subarray(-32));
+    return extractAndExpand(dh, concat(enc, pkRm));
+}
+// ── Contexte HPKE ─────────────────────────────────────────────────────────────
+function keySchedule(sharedSecret, info, suite = { aeadId: AEAD_ID, nk: NK, nn: NN }) {
+    const suiteId = hpkeSuiteId(suite.aeadId);
+    // En mode base, psk et psk_id sont vides — mais leurs hachages entrent QUAND MÊME dans
+    // le contexte. Les omettre donnerait un contexte différent de toute autre
+    // implémentation conforme.
+    const pskIdHash = labeledExtract(suiteId, new Uint8Array(0), 'psk_id_hash', new Uint8Array(0));
+    const infoHash = labeledExtract(suiteId, new Uint8Array(0), 'info_hash', info);
+    const keyScheduleContext = concat(new Uint8Array([MODE_BASE]), pskIdHash, infoHash);
+    const secret = labeledExtract(suiteId, sharedSecret, 'secret', new Uint8Array(0));
+    return {
+        key: labeledExpand(suiteId, secret, 'key', keyScheduleContext, suite.nk),
+        baseNonce: labeledExpand(suiteId, secret, 'base_nonce', keyScheduleContext, suite.nn),
+        keyScheduleContext,
+        secret,
+    };
+}
+/**
+ * Scelle un texte clair pour un destinataire, lié à un AAD.
+ *
+ * L'AAD est passé en OCTETS DÉJÀ CANONIQUES, jamais en objet : la canonicalisation
+ * appartient à l'appelant, qui doit produire exactement les mêmes octets à la
+ * vérification. L'accepter en objet ici inviterait deux canonicalisations différentes.
+ *
+ * `seq` vaut 0 : un contexte n'est utilisé que pour UN chiffrement. Le RFC interdit toute
+ * répétition du couple de contexte de nonce, et la garantie la plus simple est qu'un
+ * contexte ne serve jamais deux fois — chaque appel génère une clé éphémère neuve.
+ */
+export function seal(params) {
+    const { sharedSecret, enc } = encapsulate(params.recipientPublicKeyPem);
+    const { key, baseNonce } = keySchedule(sharedSecret, params.info ?? new Uint8Array(0));
+    const cipher = crypto.createCipheriv('chacha20-poly1305', Buffer.from(key), Buffer.from(baseNonce), {
+        authTagLength: 16,
+    });
+    cipher.setAAD(Buffer.from(params.aadCanonicalBytes), { plaintextLength: params.plaintext.length });
+    const body = Buffer.concat([cipher.update(Buffer.from(params.plaintext)), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return {
+        alg: HPKE_SUITE,
+        enc: Buffer.from(enc).toString('base64url'),
+        nonce: Buffer.from(baseNonce).toString('base64url'),
+        ciphertext: Buffer.concat([body, tag]).toString('base64url'),
+    };
+}
+/**
+ * Ouvre un blob scellé. Échoue FERMÉ au moindre octet d'AAD différent.
+ *
+ * Toute erreur est convertie en `undefined` plutôt qu'en exception détaillée : distinguer
+ * « mauvaise clé » de « AAD divergent » de « tag invalide » donnerait à un attaquant un
+ * oracle sur la cause de l'échec. L'appelant apprend seulement que ça n'ouvre pas.
+ */
+export function open(params) {
+    try {
+        if (params.sealed.alg !== HPKE_SUITE)
+            return undefined;
+        const enc = new Uint8Array(Buffer.from(params.sealed.enc, 'base64url'));
+        const sharedSecret = decapsulate(enc, params.recipientPrivateKey);
+        const { key, baseNonce } = keySchedule(sharedSecret, params.info ?? new Uint8Array(0));
+        // Le nonce annoncé DOIT être celui dérivé du schedule. Accepter un nonce arbitraire
+        // laisserait un émetteur en réutiliser un — la faute la plus grave possible sur un
+        // AEAD à nonce, qui trahit le clair de deux messages d'un simple XOR.
+        const announced = Buffer.from(params.sealed.nonce, 'base64url');
+        if (!announced.equals(Buffer.from(baseNonce)))
+            return undefined;
+        const raw = Buffer.from(params.sealed.ciphertext, 'base64url');
+        if (raw.length < 16)
+            return undefined;
+        const body = raw.subarray(0, raw.length - 16);
+        const tag = raw.subarray(raw.length - 16);
+        const decipher = crypto.createDecipheriv('chacha20-poly1305', Buffer.from(key), Buffer.from(baseNonce), {
+            authTagLength: 16,
+        });
+        decipher.setAAD(Buffer.from(params.aadCanonicalBytes), { plaintextLength: body.length });
+        decipher.setAuthTag(tag);
+        return new Uint8Array(Buffer.concat([decipher.update(body), decipher.final()]));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Exposé pour les vecteurs de test RFC 9180 ; hors de ce cadre, utiliser `seal`/`open`. */
+export const __testing = { labeledExtract, labeledExpand, keySchedule, kemSuiteId, hpkeSuiteId, extractAndExpand };
+//# sourceMappingURL=federation-hpke.js.map

package/dist/core/federation-inbound.js

@@ -0,0 +1,187 @@
+/**
+ * Vérification à la réception — fédération v2 (pln#651 étape 6, RFC §6).
+ *
+ * ── LE TROU QUE CE MODULE FERME ───────────────────────────────────────────────
+ * Avant lui, `pullSignalsFromCloud` faisait un simple `as { messages: … }` sans AUCUNE
+ * vérification, puis `materializeFederationSignal` écrivait dans la mémoire locale via
+ * saveCandidate et saveRuntimeNote. La signature Ed25519 existante était TRANSPORT
+ * uniquement, edge→cloud, dans des en-têtes : elle n'était pas persistée dans l'enveloppe
+ * et ne disait rien de l'origine du contenu.
+ *
+ * Conséquence : un cloud malveillant ne lisait pas la roadmap — elle est chiffrée — mais
+ * pouvait INJECTER des candidates et des runtime_notes dans la mémoire de chaque agent
+ * enrôlé. Soit un canal d'injection de prompt vers toute la flotte. Trois critiques sur
+ * quatre l'ont classé bloquant, par trois angles distincts.
+ *
+ * Chiffrer les LECTURES en laissant les ÉCRITURES forgeables par l'opérateur qu'on
+ * prétend neutraliser est le défaut structurel fermé ici.
+ *
+ * ── CE QUE LE CLOUD PEUT ENCORE FAIRE, ET QU'IL FAUT DIRE ─────────────────────
+ * Il peut RETARDER ou OMETTRE une enveloppe. Aucune cryptographie ne l'en empêche : un
+ * relais qui ne relaie pas est indétectable de l'intérieur. Ce qu'il ne peut plus faire,
+ * c'est injecter, rejouer une ancienne révision comme courante, ou réordonner des
+ * métadonnées sans être vu.
+ */
+import crypto from 'node:crypto';
+import { canonicalJson } from './federation-canonical.js';
+import { open as hpkeOpen } from './federation-hpke.js';
+import { FederationEnvelopeSchema, originSigningInput, } from './federation-projection.js';
+import { acceptsRevision, recordRevision } from './federation-state.js';
+function reject(reason, detail) {
+    return { ok: false, reason, detail };
+}
+/**
+ * Vérifie la signature d'origine sur les octets canoniques complets.
+ *
+ * Toute exception — PEM illisible, signature mal encodée, mauvaise longueur — rend
+ * `false` sans distinction. Laisser remonter l'erreur, ou différencier les causes,
+ * donnerait un oracle sur la RAISON du refus ; du point de vue de l'appelant il n'y a
+ * qu'un seul fait utile : ces octets ne sont pas signés par cette clé.
+ */
+function verifyOriginSignature(env, signerPem) {
+    try {
+        return crypto.verify(null, originSigningInput(env.meta, env.sealed, env.key_epoch), crypto.createPublicKey(signerPem), Buffer.from(env.origin_sig.value, 'base64url'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Vérifie une enveloppe entrante. AUCUNE écriture locale n'a lieu ici — la fonction est
+ * pure vis-à-vis du disque et rend un verdict.
+ *
+ * L'ORDRE DES CONTRÔLES EST UN CONTRAT (RFC §6) : parse strict → résolution du signataire
+ * → signature → AAD → révocation → déchiffrement → cohérence du clair → anti-rejeu →
+ * dédoublonnage. Déchiffrer AVANT d'avoir vérifié la signature exposerait le déchiffreur
+ * à un ciphertext choisi par l'attaquant ; vérifier l'anti-rejeu avant la signature
+ * laisserait un cloud faire avancer la barrière avec des révisions forgées, condamnant
+ * les révisions légitimes qui suivent.
+ */
+export function verifyInbound(params) {
+    // (1) Parse STRICT. Une clé inconnue est refusée, pas retirée en silence : c'est le
+    // pendant entrant du filet 2 du projecteur.
+    const parsed = FederationEnvelopeSchema.safeParse(params.raw);
+    if (!parsed.success) {
+        return reject('schema_invalid', parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '));
+    }
+    const env = parsed.data;
+    // (2) Résoudre le signataire DANS LE ROSTER ATTESTÉ.
+    const signerPem = params.roster.keys.get(env.origin_sig.key_id);
+    if (!signerPem) {
+        return reject('unknown_signer', `key_id '${env.origin_sig.key_id}' absent du roster attesté.`);
+    }
+    // Révoqué et inconnu sont distingués : un opérateur doit pouvoir voir qu'un membre
+    // révoqué continue d'émettre, ce qu'un « inconnu » générique masquerait.
+    if (params.roster.revoked?.has(env.origin_sig.key_id)) {
+        return reject('revoked_signer', `key_id '${env.origin_sig.key_id}' révoqué.`);
+    }
+    // (3) Signature sur les octets canoniques COMPLETS : meta, sealed (alg, enc, nonce,
+    // ciphertext) et key_epoch. Couvrir meta est ce qui rend le réordonnancement de
+    // priorité, de dépendances ou de statut détectable — le Cloud peut lire ces champs,
+    // il ne peut pas les changer.
+    if (!verifyOriginSignature(env, signerPem)) {
+        return reject('bad_signature', "la signature d'origine ne couvre pas ces octets.");
+    }
+    // (4) L'AAD doit DÉCRIRE l'objet annoncé. Sans ce contrôle, une enveloppe légitime pour
+    // l'objet A, correctement signée, pourrait être présentée comme concernant l'objet B :
+    // la signature resterait valide puisqu'elle couvre meta, mais meta lui-même mentirait
+    // sur sa cohérence interne.
+    const aad = env.meta.aad;
+    if (aad.object_id !== env.meta.id_opaque
+        || aad.base_rev !== env.meta.base_rev
+        || aad.object_type !== env.meta.kind
+        || aad.cloud_project_id !== params.state.cloud_project_id) {
+        return reject('aad_mismatch', "l'AAD ne décrit pas l'objet annoncé par meta.");
+    }
+    // (5) Déchiffrement. Échoue FERMÉ : `hpkeOpen` ne distingue pas les causes, pour ne pas
+    // offrir d'oracle sur la raison de l'échec.
+    if (!params.epochPrivateKey) {
+        return reject('undecryptable', `aucune clé détenue pour l'epoch ${env.key_epoch}.`);
+    }
+    const plaintext = hpkeOpen({
+        recipientPrivateKey: params.epochPrivateKey,
+        sealed: env.sealed,
+        aadCanonicalBytes: new TextEncoder().encode(canonicalJson(aad)),
+    });
+    if (!plaintext) {
+        return reject('undecryptable', 'AEAD refusé (clé, AAD ou tag).');
+    }
+    let content;
+    try {
+        content = JSON.parse(new TextDecoder().decode(plaintext));
+    }
+    catch {
+        return reject('payload_type_mismatch', 'le clair déchiffré n\'est pas du JSON.');
+    }
+    if (content === null || typeof content !== 'object') {
+        return reject('payload_type_mismatch', 'le clair déchiffré n\'est pas un objet.');
+    }
+    // (6) ANTI-REJEU. L'AEAD détecte l'ALTÉRATION, pas le REJEU d'un ciphertext valide et
+    // ancien. Sans high-water mark, un cloud peut resservir un état antérieur comme s'il
+    // était courant, et rien dans la cryptographie ne s'y oppose.
+    //
+    // Le dédoublonnage est vérifié AVANT le rejeu : une enveloppe DÉJÀ matérialisée a
+    // légitimement une révision égale au high-water mark. La confondre avec un rejeu
+    // rendrait tout retour d'un retry indistinguable d'une attaque.
+    const idempotencyKey = env.meta.transport.idempotency_key;
+    if (params.seenIdempotencyKeys?.has(idempotencyKey)) {
+        return reject('duplicate', `opération déjà matérialisée (${idempotencyKey}).`);
+    }
+    if (!acceptsRevision(params.state, env.meta.id_opaque, env.meta.base_rev)) {
+        const seen = params.state.sync.high_water[env.meta.id_opaque];
+        return reject('replay_or_rollback', `révision ${env.meta.base_rev} refusée pour ${env.meta.id_opaque} : high-water mark à ${seen}.`);
+    }
+    return {
+        ok: true,
+        envelope: env,
+        content,
+        kind: env.meta.kind,
+        idempotencyKey,
+        nextState: recordRevision(params.state, env.meta.id_opaque, env.meta.base_rev),
+    };
+}
+/**
+ * Vérifie un lot d'enveloppes et rend le verdict de chacune.
+ *
+ * L'ÉTAT AVANCE AU FIL DU LOT, et l'ordre compte : deux révisions du même objet dans un
+ * même lot doivent être appliquées dans l'ordre croissant, sinon la seconde est refusée
+ * comme rollback — ce qui est le comportement voulu. Un lot est traité comme une suite
+ * d'opérations, jamais comme un ensemble à réordonner selon ce que le Cloud propose.
+ *
+ * Le dédoublonnage accumule les clés vues DANS le lot en plus de celles déjà connues :
+ * un cloud qui livrerait deux fois la même opération dans un seul lot serait sinon
+ * accepté deux fois.
+ */
+export function verifyInboundBatch(params) {
+    const seen = new Set(params.seenIdempotencyKeys ?? []);
+    let state = params.state;
+    const results = [];
+    let accepted = 0;
+    for (const raw of params.envelopes) {
+        // L'epoch est lu sur l'enveloppe AVANT vérification, uniquement pour choisir une clé.
+        // Ce n'est pas une décision de confiance : une valeur mensongère mène simplement à
+        // une clé qui n'ouvrira pas, donc à un refus.
+        const epoch = typeof raw?.key_epoch === 'number'
+            ? raw.key_epoch
+            : undefined;
+        const result = verifyInbound({
+            raw,
+            roster: params.roster,
+            state,
+            epochPrivateKey: epoch === undefined ? undefined : params.epochKeys.get(epoch),
+            seenIdempotencyKeys: seen,
+        });
+        results.push(result);
+        if (result.ok) {
+            // L'état n'avance QUE sur acceptation. Une enveloppe refusée ne doit laisser aucune
+            // trace : ni barrière avancée, ni clé d'idempotence enregistrée. Sinon un cloud
+            // hostile empoisonnerait l'état avec des enveloppes invalides et condamnerait les
+            // révisions légitimes qui suivent.
+            state = result.nextState;
+            seen.add(result.idempotencyKey);
+            accepted++;
+        }
+    }
+    return { results, nextState: state, accepted, rejected: results.length - accepted };
+}
+//# sourceMappingURL=federation-inbound.js.map

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);