brainclaw 1.20.4 → 1.22.0

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

package/dist/core/federation-projection.js

@@ -0,0 +1,336 @@
+/**
+ * Le projecteur et ses trois filets — fédération v2 (pln#651 étape 5, RFC §4).
+ *
+ * C'est ici que la table de classification devient EXÉCUTABLE. Trois classes, et
+ * « non classé » n'en est pas une quatrième : c'est un refus.
+ *
+ * ── POURQUOI TROIS FILETS ET NON UN SEUL ──────────────────────────────────────
+ * Établi par quatre critiques sur quatre pendant l'idéation, chacune par un angle
+ * différent :
+ *   (i)   Zod fait `.strip()` PAR DÉFAUT — un champ nouveau passe la validation en
+ *         silence, sans jamais lever ;
+ *   (ii)  un test couvre la SORTIE, pas la CONSTRUCTION — N projecteurs, un seul testé,
+ *         et les N-1 autres fuient (application littérale de trp#5a8fb7d9) ;
+ *   (iii) `{...entity, ciphertext}` compile parfaitement et déverse tout.
+ *
+ * Et le typage seul ne borne RIEN. `pushToCloud(payload: { id: string })` suivi d'un
+ * `JSON.stringify` sérialise chaque clé présente à L'EXÉCUTION : le typage structurel de
+ * TypeScript est une BORNE INFÉRIEURE sur ce que l'objet contient, jamais une borne
+ * supérieure. C'est la raison pour laquelle le filet 2 existe malgré le filet 1.
+ *
+ * FILET 1 — un builder nominal, marque de type non fabricable ailleurs, sélection
+ *           explicite champ par champ, JAMAIS de spread.
+ * FILET 2 — un parse `.strict()` à UN SEUL point de sortie que tout push traverse.
+ * FILET 3 — fixture golden byte-exacte + test de complétude sur l'inventaire.
+ *
+ * ── CE QUI RESTE VISIBLE, ÉCRIT ET NON MASQUÉ ─────────────────────────────────
+ * « Lane 3 » cache le libellé, pas le GRAPHE. Le nombre de lanes, la forme du graphe de
+ * dépendances et la cardinalité restent lisibles par le Cloud. C'est assumé : le board
+ * aveugle rend une structure, et une structure est une information. Le prétendre
+ * autrement serait mentir sur la garantie.
+ */
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { canonicalJson, canonicalSha256, b64url } from './federation-canonical.js';
+import { seal, HPKE_SUITE } from './federation-hpke.js';
+export const ENVELOPE_SCHEMA = 'brainclaw.federation-envelope/v1';
+export const AAD_PROTOCOL = 'brainclaw/federation/v1';
+/**
+ * Types d'entités PROJETABLES. Une famille absente de cette liste n'est pas « à faire
+ * plus tard » : son schéma entier est interdit de sortie (RFC §4.3). L'ajout d'une
+ * famille est un acte délibéré qui passe par la table de classification.
+ */
+export const FEDERATED_KINDS = [
+    'constraint', 'decision', 'trap', 'handoff', 'plan', 'plan_step', 'sequence',
+    'claim', 'candidate', 'runtime_note', 'inbox_message', 'assignment',
+    'agent_run', 'action_required', 'ai_task', 'runtime_event', 'lane_result',
+];
+// ── Champs INTERDITS DE SORTIR (RFC §4.2, classe 3) ──────────────────────────
+/**
+ * Ces noms ne doivent apparaître NI dans meta NI dans sealed. Leur présence fait échouer
+ * la projection — un refus, pas une troncature.
+ *
+ * POURQUOI UNE LISTE DE NOMS ICI ALORS QUE J'AI ÉCRIT AILLEURS QU'UNE LISTE DE NOMS NE
+ * SUFFIT PAS : elle ne suffit effectivement pas SEULE, et n'est pas seule. Le filet 1
+ * empêche déjà tout champ non explicitement sélectionné d'entrer dans meta, et le filet 2
+ * refuse toute clé inconnue à la sortie. Cette liste est un TROISIÈME contrôle qui vise
+ * le SCELLÉ — la seule partie que les deux autres filets ne peuvent pas inspecter,
+ * puisqu'ils la traitent comme opaque. Sans elle, `worktree_path` chiffré partirait quand
+ * même : chiffré n'est pas « autorisé à sortir ».
+ */
+export const FORBIDDEN_LEAF_NAMES = new Set([
+    'host_id', 'session_id', 'worktree_path', 'project_path', 'storage_dir', 'related_paths',
+    'command', 'shell', 'pid', 'provider_run_id', 'base_sha', 'cwd',
+    'api_key', 'apiKey', 'secret', 'token', 'password', 'private_key', 'privateKey',
+    'env', 'environment',
+]);
+/** Motifs de VALEURS trahissant un chemin local, quel que soit le nom du champ. */
+const LOCAL_PATH_PATTERNS = [
+    /^[A-Za-z]:[\\/]/, // C:\... ou C:/...
+    /^\/(?:home|Users|root)\//, // /home/x, /Users/x, /root/x
+    /\.brainclaw[\\/]worktrees/,
+];
+export class ProjectionRefused extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'ProjectionRefused';
+    }
+}
+/**
+ * Parcours RÉCURSIF refusant tout champ interdit, par son nom ou par la forme de sa
+ * valeur.
+ *
+ * Appliqué au CLAIR AVANT scellement, donc y compris à ce qui partira chiffré. Le RFC est
+ * explicite : la classe interdite est « absente de meta ET de sealed ». Un chemin de
+ * worktree chiffré reste une donnée qui a quitté l'hôte, et le jour où la clé fuit, elle
+ * a fui aussi. Le chiffrement protège le contenu ; il ne rend pas licite de l'envoyer.
+ */
+export function assertNoForbiddenLeaf(value, path = '$') {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'string') {
+        for (const pattern of LOCAL_PATH_PATTERNS) {
+            if (pattern.test(value)) {
+                throw new ProjectionRefused(`Chemin local détecté en ${path} — interdit de sortir, même scellé (RFC §4.2).`, path);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => assertNoForbiddenLeaf(v, `${path}[${i}]`));
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [key, v] of Object.entries(value)) {
+            if (FORBIDDEN_LEAF_NAMES.has(key)) {
+                throw new ProjectionRefused(`Champ interdit '${key}' en ${path} — absent de meta ET de sealed (RFC §4.2).`, `${path}.${key}`);
+            }
+            assertNoForbiddenLeaf(v, `${path}.${key}`);
+        }
+    }
+}
+// ── FILET 2 : le schéma strict du point de sortie unique ─────────────────────
+/**
+ * `.strict()` PARTOUT, et c'est le point.
+ *
+ * Zod `.strip()` — le défaut — accepterait un objet porteur d'une clé inconnue et la
+ * retirerait SILENCIEUSEMENT du résultat. Le push passerait, et personne n'apprendrait
+ * qu'un champ non classé a été ajouté au projecteur. `.strict()` LÈVE, ce qui transforme
+ * l'oubli de classification en échec de CI plutôt qu'en fuite discrète.
+ */
+const CanonicalAadSchema = z.object({
+    protocol: z.literal(AAD_PROTOCOL),
+    cloud_project_id: z.string().min(1),
+    object_id: z.string().min(1),
+    base_rev: z.number().int().nonnegative(),
+    object_type: z.enum(FEDERATED_KINDS),
+    schema: z.literal(ENVELOPE_SCHEMA),
+}).strict();
+const PublicMetaSchema = z.object({
+    id_opaque: z.string().uuid(),
+    kind: z.enum(FEDERATED_KINDS),
+    status: z.object({
+        object: z.string().min(1),
+        sync: z.enum(['pending', 'synced', 'conflict']).optional(),
+    }).strict(),
+    priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
+    rank: z.number().int().optional(),
+    deps: z.array(z.object({ from: z.string().uuid(), to: z.string().uuid() }).strict()),
+    // Jour UTC, JAMAIS l'heure. Une heure précise trahit le rythme de travail d'une
+    // personne ; le jour ne dit que la cadence, ce que le RFC assume explicitement.
+    timestamp_bucket_jour: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    base_rev: z.number().int().nonnegative(),
+    aad: CanonicalAadSchema,
+    // Ne contient NI nom NI empreinte de destinataire : la référence de paquet de clés
+    // aurait divulgué le roster, canal de fuite que l'idéation avait manqué.
+    wrap_hint: z.string().min(1),
+    transport: z.object({
+        operation_id: z.string().min(1),
+        content_hash: z.string().min(1),
+        idempotency_key: z.string().min(1),
+    }).strict(),
+}).strict();
+const SealedSchema = z.object({
+    alg: z.literal(HPKE_SUITE),
+    enc: z.string().min(1),
+    nonce: z.string().min(1),
+    ciphertext: z.string().min(1),
+}).strict();
+export const FederationEnvelopeSchema = z.object({
+    schema: z.literal(ENVELOPE_SCHEMA),
+    meta: PublicMetaSchema,
+    sealed: SealedSchema,
+    key_epoch: z.number().int().nonnegative(),
+    origin_sig: z.object({
+        alg: z.literal('Ed25519'),
+        key_id: z.string().min(1),
+        value: z.string().min(1),
+    }).strict(),
+}).strict();
+/** Jour UTC. La troncature est faite ICI pour qu'aucun appelant ne puisse l'oublier. */
+function dayBucket(when) {
+    const d = typeof when === 'string' ? new Date(when) : when;
+    if (Number.isNaN(d.getTime()))
+        throw new ProjectionRefused('Date invalide pour le bucket jour.', '$.occurredAt');
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Construit la projection publique — SÉLECTION EXPLICITE, CHAMP PAR CHAMP.
+ *
+ * Aucun spread nulle part dans cette fonction, et c'est délibéré : `{...input}` suffirait
+ * à déverser tout ce que l'appelant a mis dans l'objet. Chaque champ de meta est nommé
+ * ici ou n'existe pas. Ajouter un champ à `PublicMetaSchema` sans l'ajouter ici produit
+ * une erreur de compilation, et l'inverse un échec de parse `.strict()`.
+ *
+ * `priority` et `rank` ne sont posés QUE s'ils existent : l'absence d'un champ optionnel
+ * est SIGNIFICATIVE (RFC §3). Inventer `priority: 'medium'` pour un objet qui n'en porte
+ * pas créerait une fuite par normalisation — le Cloud croirait à une priorité choisie.
+ */
+export function toPublicProjection(input) {
+    const aad = {
+        protocol: AAD_PROTOCOL,
+        cloud_project_id: input.cloudProjectId,
+        object_id: input.idOpaque,
+        base_rev: input.baseRev,
+        object_type: input.kind,
+        schema: ENVELOPE_SCHEMA,
+    };
+    const meta = {
+        id_opaque: input.idOpaque,
+        kind: input.kind,
+        status: input.syncState
+            ? { object: input.statusObject, sync: input.syncState }
+            : { object: input.statusObject },
+        deps: (input.deps ?? []).map((d) => ({ from: d.from, to: d.to })),
+        timestamp_bucket_jour: dayBucket(input.occurredAt),
+        base_rev: input.baseRev,
+        aad,
+        wrap_hint: input.wrapHint,
+        transport: {
+            operation_id: input.operationId,
+            // Dérivés du CIPHERTEXT, jamais du clair (RFC §3.2). En v1, content_hash portait
+            // sur le corps sémantique en clair : le Cloud pouvait alors confirmer une
+            // devinette sur un contenu à faible entropie en comparant des hachages.
+            content_hash: canonicalSha256(input.sealed),
+            idempotency_key: '',
+        },
+    };
+    if (input.priority !== undefined)
+        meta.priority = input.priority;
+    if (input.rank !== undefined)
+        meta.rank = input.rank;
+    return meta;
+}
+/**
+ * LE SEUL point par lequel une enveloppe peut être produite.
+ *
+ * L'ordre des opérations est un contrat, pas un détail :
+ *   1. refus des champs interdits sur le CLAIR (avant qu'ils ne deviennent illisibles) ;
+ *   2. AAD canonique, lié au projet, à l'objet, à la révision et au type ;
+ *   3. scellement HPKE avec cet AAD exact ;
+ *   4. projection publique par le filet 1 ;
+ *   5. dérivés de transport calculés sur le CIPHERTEXT ;
+ *   6. signature d'origine sur meta ‖ sealed ‖ key_epoch ;
+ *   7. parse `.strict()` — le filet 2 — qui refuse toute clé inconnue.
+ *
+ * Inverser 1 et 3 laisserait passer un champ interdit dans le blob chiffré.
+ */
+export function buildEnvelope(params) {
+    // (1) Le contrôle porte sur le clair, y compris ce qui sera scellé.
+    assertNoForbiddenLeaf(params.content, '$.content');
+    // (2) AAD comme STRUCTURE canonique et non concaténation ambiguë : « a|b » et « a|b »
+    // issus de découpages différents produisent la même chaîne, donc deux contextes
+    // distincts indiscernables.
+    const aad = {
+        protocol: AAD_PROTOCOL,
+        cloud_project_id: params.cloudProjectId,
+        object_id: params.idOpaque,
+        base_rev: params.baseRev,
+        object_type: params.kind,
+        schema: ENVELOPE_SCHEMA,
+    };
+    const aadBytes = new TextEncoder().encode(canonicalJson(aad));
+    // (3)
+    const sealed = seal({
+        recipientPublicKeyPem: params.recipientPublicKeyPem,
+        plaintext: new TextEncoder().encode(canonicalJson(params.content)),
+        aadCanonicalBytes: aadBytes,
+    });
+    // (4)
+    const meta = toPublicProjection({
+        kind: params.kind,
+        idOpaque: params.idOpaque,
+        cloudProjectId: params.cloudProjectId,
+        baseRev: params.baseRev,
+        statusObject: params.statusObject,
+        syncState: params.syncState,
+        priority: params.priority,
+        rank: params.rank,
+        deps: params.deps,
+        occurredAt: params.occurredAt,
+        wrapHint: params.wrapHint,
+        operationId: params.operationId,
+        sealed,
+    });
+    // (5) idempotency_key = SHA-256(canonical(sealed) || operation_id || origin_sig.key_id).
+    // CLEFÉE par l'identité du signataire : deux agents qui pousseraient le même contenu
+    // n'auraient pas la même clé, donc le Cloud ne peut pas déduire qu'ils poussent la
+    // même chose.
+    meta.transport.idempotency_key = b64url(new Uint8Array(crypto.createHash('sha256')
+        .update(canonicalJson(sealed), 'utf-8')
+        .update(params.operationId, 'utf-8')
+        .update(params.originKeyId, 'utf-8')
+        .digest()));
+    // (6) L'entrée couvre alg, enc, nonce ET ciphertext, plus key_epoch — pas seulement
+    // « meta || ciphertext ». Le raccourci ne couvrirait pas les paramètres permettant
+    // d'INTERPRÉTER le ciphertext, qu'un Cloud pourrait alors modifier sans casser la
+    // signature.
+    const signingInput = Buffer.concat([
+        Buffer.from('brainclaw/federation-envelope/v1\0', 'utf-8'),
+        Buffer.from(canonicalJson(meta), 'utf-8'),
+        Buffer.from(canonicalJson(sealed), 'utf-8'),
+        Buffer.from(canonicalJson(params.keyEpoch), 'utf-8'),
+    ]);
+    const signature = crypto.sign(null, signingInput, crypto.createPrivateKey(params.originPrivateKeyPem));
+    const envelope = {
+        schema: ENVELOPE_SCHEMA,
+        meta,
+        sealed,
+        key_epoch: params.keyEpoch,
+        origin_sig: { alg: 'Ed25519', key_id: params.originKeyId, value: signature.toString('base64url') },
+    };
+    // (7) FILET 2 — fail-closed. Une clé inconnue lève ici plutôt que de partir sur le fil.
+    return FederationEnvelopeSchema.parse(envelope);
+}
+/**
+ * Octets exacts sur lesquels porte la signature d'origine.
+ *
+ * Exporté pour que le VÉRIFICATEUR les reconstruise avec la même fonction que
+ * l'émetteur. Deux reconstructions indépendantes est précisément le défaut qui a rendu
+ * l'attestation d'appairage insatisfiable côté Cloud : le vérificateur fabriquait un
+ * champ que le signataire ne pouvait pas connaître.
+ */
+export function originSigningInput(meta, sealed, keyEpoch) {
+    return Buffer.concat([
+        Buffer.from('brainclaw/federation-envelope/v1\0', 'utf-8'),
+        Buffer.from(canonicalJson(meta), 'utf-8'),
+        Buffer.from(canonicalJson(sealed), 'utf-8'),
+        Buffer.from(canonicalJson(keyEpoch), 'utf-8'),
+    ]);
+}
+// ── Ids opaques ──────────────────────────────────────────────────────────────
+/**
+ * Ids RE-ROULÉS en UUID v4, mapping local↔cloud gardé LOCAL.
+ *
+ * Pourquoi ne pas simplement hacher l'id local : un hachage est déterministe, donc le
+ * même objet exporté vers deux projets Cloud produirait le même identifiant, et un
+ * observateur corrélerait les deux projets. Un UUID aléatoire par projet coupe cette
+ * corrélation — c'est le sens de « stable dans un projet Cloud, pas cross-projet »
+ * (RFC §4.1).
+ */
+export function newOpaqueId() {
+    return crypto.randomUUID();
+}
+//# sourceMappingURL=federation-projection.js.map