brainclaw 1.22.0 → 1.24.0

package/dist/core/federation-pull.js

@@ -0,0 +1,375 @@
+/**
+ * Fédération v2 — pull : le cloud livre un delta, ce module vérifie puis
+ * matérialise seulement le clair accepté. Le cloud reste un relais, jamais la
+ * source de vérité locale.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { verifyInboundBatch } from './federation-inbound.js';
+import { loadEpochPrivateKey } from './federation-keyring.js';
+import { localIdForOpaque, rememberOpaqueId } from './federation-opaque-ids.js';
+import { addStep, createPlan, updatePlan, updateStep } from './operations/plan.js';
+import { memoryDir, writeFileAtomic } from './io.js';
+import { nowISO } from './ids.js';
+import { loadConnectionState, recordRevision, saveConnectionState } from './federation-state.js';
+const INBOUND_SCHEMA = 'brainclaw.federation-inbound-pull/v1';
+const INBOUND_FILE = 'inbound-pull.json';
+/**
+ * Limite transitoire, volontairement rendue à l'UI : le roster signé de dec#159
+ * n'existe pas encore. Tirer les attestations du cloud demande donc au relais qui
+ * surveiller ; la signature protège le contenu, pas cette sélection de clés.
+ */
+export const CLOUD_ROSTER_LIMITATION = 'Roster provisoire : attestations tirées du cloud, pas encore un roster signé (dec#159 §5). Le relais peut influencer qui est accepté comme signataire.';
+function journalPath(cwd) {
+    return path.join(memoryDir(cwd), 'coordination', 'federation', INBOUND_FILE);
+}
+function loadJournal(cwd) {
+    const file = journalPath(cwd);
+    if (!fs.existsSync(file))
+        return { schema: INBOUND_SCHEMA, seen: [], pending: {} };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed.schema !== INBOUND_SCHEMA || !Array.isArray(parsed.seen) || !parsed.pending || typeof parsed.pending !== 'object') {
+            return { schema: INBOUND_SCHEMA, seen: [], pending: {} };
+        }
+        return {
+            schema: INBOUND_SCHEMA,
+            seen: parsed.seen.filter((key) => typeof key === 'string'),
+            pending: parsed.pending,
+        };
+    }
+    catch {
+        // Un journal local corrompu n'est jamais une preuve qu'un message a été appliqué.
+        return { schema: INBOUND_SCHEMA, seen: [], pending: {} };
+    }
+}
+function saveJournal(journal, cwd) {
+    const file = journalPath(cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(journal, null, 2)}\n`);
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function rawKey(raw) {
+    // Déduplication de stockage uniquement — jamais une décision d'authenticité.
+    return crypto.createHash('sha256').update(JSON.stringify(raw)).digest('hex');
+}
+/**
+ * Le cloud rend une LIGNE À PLAT dont un champ, `envelope_json`, porte l'enveloppe signée
+ * verbatim (dec#162). C'est ELLE que le vérificateur doit parser — la ligne plate n'a ni
+ * la forme imbriquée de FederationEnvelopeSchema ni la signature d'AUTEUR. Sans
+ * `envelope_json` (enveloppe poussée avant dec#162), on laisse passer l'objet tel quel :
+ * il échouera en `schema_invalid`, ce qui est le verdict juste — non vérifiable.
+ */
+function toEnvelope(item) {
+    const record = asRecord(item);
+    if (record && typeof record['envelope_json'] === 'string') {
+        try {
+            return JSON.parse(record['envelope_json']);
+        }
+        catch {
+            return item;
+        }
+    }
+    return item;
+}
+function responseArray(value, fields) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    for (const field of fields)
+        if (Array.isArray(record[field]))
+            return record[field];
+    return undefined;
+}
+function parseDelta(body) {
+    if (Array.isArray(body))
+        return { envelopes: body };
+    const root = asRecord(body);
+    if (!root)
+        throw new Error('Delta cloud invalide : objet JSON attendu.');
+    const source = asRecord(root['data']) ?? asRecord(root['delta']) ?? root;
+    const envelopes = responseArray(source, ['envelopes', 'items', 'results']);
+    if (!envelopes)
+        throw new Error('Delta cloud invalide : tableau envelopes attendu.');
+    const cursor = source['next_seq'] ?? source['next_cursor'] ?? source['nextCursor'] ?? source['cursor'];
+    return { envelopes, cursor: typeof cursor === 'string' || typeof cursor === 'number' ? String(cursor) : undefined };
+}
+/** Lit les attestations cloud. Ce n'est PAS un roster signé : voir la constante exportée. */
+function parseCloudRoster(body) {
+    const root = asRecord(body);
+    if (!root)
+        throw new Error('Roster cloud invalide : objet JSON attendu.');
+    const source = asRecord(root['data']) ?? root;
+    const keys = new Map();
+    const revoked = new Set();
+    const compact = asRecord(source['keys']);
+    if (compact) {
+        for (const [id, pem] of Object.entries(compact))
+            if (typeof pem === 'string')
+                keys.set(id, pem);
+    }
+    for (const value of responseArray(source, ['attestations', 'members', 'roster', 'items']) ?? []) {
+        const row = asRecord(value);
+        if (!row)
+            continue;
+        const id = row['key_id'] ?? row['identity_fingerprint'] ?? row['signer_fingerprint'];
+        const pem = row['identity_public_key_pem'] ?? row['ed25519_public_key_pem'] ?? row['public_key_pem'];
+        if (typeof id !== 'string' || typeof pem !== 'string')
+            continue;
+        keys.set(id, pem);
+        if (row['revoked'] === true || row['revoked_at'])
+            revoked.add(id);
+    }
+    return { keys, revoked };
+}
+function headers(apiKey) {
+    return apiKey ? { accept: 'application/json', authorization: `Bearer ${apiKey}` } : { accept: 'application/json' };
+}
+async function readJson(res, label) {
+    if (!res.ok)
+        throw new Error(`${label} refusé par le cloud (HTTP ${res.status}) : ${(await res.text()).slice(0, 200)}`);
+    try {
+        return await res.json();
+    }
+    catch {
+        throw new Error(`${label} invalide : JSON attendu.`);
+    }
+}
+function problem(raw, reason) {
+    const env = asRecord(raw);
+    const meta = asRecord(env?.['meta']);
+    const transport = asRecord(meta?.['transport']);
+    return {
+        idempotency_key: typeof transport?.['idempotency_key'] === 'string' ? transport['idempotency_key'] : undefined,
+        key_epoch: typeof env?.['key_epoch'] === 'number' ? env['key_epoch'] : undefined,
+        reason,
+    };
+}
+function contentOf(value) {
+    const content = asRecord(value);
+    if (!content || typeof content['text'] !== 'string')
+        throw new Error('clair vérifié non matérialisable : text est attendu.');
+    return content;
+}
+function tagsOf(content) {
+    return Array.isArray(content['tags']) && content['tags'].every((tag) => typeof tag === 'string')
+        ? content['tags']
+        : undefined;
+}
+function priorityOf(value) {
+    return value === 'low' || value === 'medium' || value === 'high' || value === 'critical' ? value : undefined;
+}
+class DeferredMaterialization extends Error {
+}
+/**
+ * Passe par les opérations métier (donc leur pipeline de mutation/verrous), jamais par
+ * l'écriture d'un JSON d'entité. L'opaque est mappé seulement APRES la mutation réussie.
+ */
+function materialize(accepted, state, cwd) {
+    const opaque = accepted.envelope.meta.id_opaque;
+    const existing = localIdForOpaque(state.cloud_project_id, opaque, cwd);
+    const content = contentOf(accepted.content);
+    const priority = priorityOf(accepted.envelope.meta.priority);
+    const tags = tagsOf(content);
+    if (accepted.kind === 'plan') {
+        if (existing) {
+            updatePlan({
+                id: existing,
+                status: accepted.envelope.meta.status.object,
+                priority,
+                patch: { text: content['text'], tags },
+            }, cwd);
+            return;
+        }
+        const created = createPlan({
+            text: content['text'],
+            author: 'federation',
+            type: typeof content['type'] === 'string' ? content['type'] : undefined,
+            priority,
+            tags,
+        }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'plan_step') {
+        const parentOpaque = accepted.envelope.meta.deps.find((dependency) => dependency.from === opaque)?.to;
+        const parent = parentOpaque ? localIdForOpaque(state.cloud_project_id, parentOpaque, cwd) : undefined;
+        if (!parent)
+            throw new DeferredMaterialization('étape reçue avant son plan parent ; conservée pour relecture.');
+        if (existing) {
+            updateStep({ stepId: existing, planId: parent, text: content['text'], status: accepted.envelope.meta.status.object }, cwd);
+            return;
+        }
+        const created = addStep({
+            planId: parent,
+            text: content['text'],
+            assignee: typeof content['assignee'] === 'string' ? content['assignee'] : undefined,
+        }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.stepId, opaque, cwd);
+        return;
+    }
+    // Les familles sans mutation canonique correspondante sont différées. Les accepter dans
+    // high_water les ferait disparaître du feed sans jamais atteindre le magasin local.
+    throw new DeferredMaterialization(`kind '${accepted.kind}' sans mutation canonique de réception.`);
+}
+/**
+ * GET du delta + attestations, vérification du lot et matérialisation. Une absence de clé
+ * d'epoch est le seul échec conservé explicitement comme « illisible » : l'enveloppe reste
+ * dans le journal entrant et sera repassée à verifyInboundBatch après remise de la clé.
+ */
+export async function pullFederationDelta(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const current = loadConnectionState(cwd);
+    if (!current || current.enrollment.stage !== 'active') {
+        throw new Error("Aucun appairage actif : un pull n'est autorisé qu'après approbation locale.");
+    }
+    const base = options.url.replace(/\/+$/, '');
+    if (!base)
+        throw new Error('Adresse du cloud absente : aucune origine ne sera devinée.');
+    const root = `${base}/api/v1/projects/${encodeURIComponent(current.cloud_project_id)}`;
+    const query = new URLSearchParams();
+    // Contrat réel de handleListEnvelopes : since_seq est un curseur exclusif et
+    // include_sealed est indispensable au déchiffrement local.
+    if (current.sync.feed_cursor)
+        query.set('since_seq', current.sync.feed_cursor);
+    query.set('include_sealed', 'true');
+    if (options.limit !== undefined)
+        query.set('limit', String(options.limit));
+    const deltaUrl = `${root}/projection/envelopes${query.size ? `?${query}` : ''}`;
+    const doFetch = options.fetchImpl ?? fetch;
+    const delta = parseDelta(await readJson(await doFetch(deltaUrl, { headers: headers(options.apiKey) }), 'Delta'));
+    // ROSTER PROVISOIRE : le commentaire et le résultat nomment la limite dec#159.
+    // Une erreur de roster est fatale AVANT le lot : remplacer la liste par une liste vide
+    // ferait passer les refus unknown_signer pour des échecs ordinaires et masquerait la
+    // vraie borne de confiance.
+    let roster;
+    try {
+        // `/projection/roster` (dec#162) : joignable par la clé d'API de l'agent et rendant
+        // {empreinte -> PEM Ed25519}. `/attestations` ne convenait pas — withUserAuth (une clé
+        // d'agent y est refusée) et sans le PEM public dont dépend la vérification de signature.
+        roster = parseCloudRoster(await readJson(await doFetch(`${root}/projection/roster`, { headers: headers(options.apiKey) }), 'Roster'));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`${CLOUD_ROSTER_LIMITATION} Roster indisponible : ${detail}`, { cause: err });
+    }
+    const journal = loadJournal(cwd);
+    const pending = { ...journal.pending };
+    const combined = new Map();
+    // Les entrées en attente sont DÉJÀ des enveloppes (parsées au tour précédent) ; le delta
+    // frais arrive à plat et doit être déballé de `envelope_json` avant toute vérification.
+    for (const [key, entry] of Object.entries(pending))
+        combined.set(key, entry.raw);
+    for (const item of delta.envelopes) {
+        const envelope = toEnvelope(item);
+        combined.set(rawKey(envelope), envelope);
+    }
+    const entries = [...combined.entries()];
+    if (entries.length > 0 && roster.keys.size === 0) {
+        throw new Error(`${CLOUD_ROSTER_LIMITATION} Le endpoint n'a fourni aucune clé Ed25519 publiquement vérifiable ; aucun clair ne sera matérialisé.`);
+    }
+    // ── RÉCEPTION DES REMISES DE CLÉS, AVANT DE CHOISIR LES CLÉS D'EPOCH (pln#658) ──
+    //
+    // L'ORDRE EST LE POINT : une clé reçue MAINTENANT rend lisibles, DANS LE MÊME PULL, les
+    // enveloppes conservées comme « illisibles, epoch absent ». Recevoir après aurait obligé
+    // à un second pull pour que la remise produise son effet — et l'opérateur aurait vu un
+    // « 0 matérialisé » juste après avoir reçu ses clés.
+    //
+    // Le roster des custodians est celui des identités attestées actives (dec#163 §2 : tout
+    // détenteur actif peut remettre). Un échec de réception n'interrompt PAS le pull : les
+    // enveloppes déjà lisibles doivent arriver même si la remise de clés échoue.
+    const grantOutcome = { stored: [], rejected: [] };
+    try {
+        const { receiveEpochGrants } = await import('./federation-grant-transport.js');
+        const received = await receiveEpochGrants({
+            cwd,
+            url: base,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetchImpl,
+            recipientDeviceId: current.device.device_id,
+            activeCustodians: roster.keys,
+        });
+        grantOutcome.stored = received.stored;
+        grantOutcome.rejected = received.rejected;
+    }
+    catch (err) {
+        grantOutcome.rejected.push({
+            reason: 'unavailable',
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const epochKeys = new Map();
+    for (const [, raw] of entries) {
+        const epoch = asRecord(raw)?.['key_epoch'];
+        if (typeof epoch === 'number' && !epochKeys.has(epoch)) {
+            const key = options.epochKeyFor
+                ? options.epochKeyFor(current.cloud_project_id, epoch)
+                : loadEpochPrivateKey(current.cloud_project_id, epoch);
+            if (key)
+                epochKeys.set(epoch, key);
+        }
+    }
+    const batch = verifyInboundBatch({
+        envelopes: entries.map(([, raw]) => raw), roster, state: current, epochKeys,
+        seenIdempotencyKeys: new Set(journal.seen),
+    });
+    const result = {
+        received: delta.envelopes.length, verified: batch.accepted, materialized: 0,
+        unreadable_epoch_absent: [], rejected: [], deferred: [], retained: 0,
+        feed_cursor: delta.cursor, roster_limitation: CLOUD_ROSTER_LIMITATION,
+        epoch_keys_received: grantOutcome.stored,
+        epoch_keys_rejected: grantOutcome.rejected,
+    };
+    let next = current;
+    const seen = new Set(journal.seen);
+    for (const [index, verdict] of batch.results.entries()) {
+        const [key, raw] = entries[index];
+        if (!verdict.ok) {
+            const item = problem(raw, verdict.detail);
+            if (verdict.reason === 'undecryptable' && item.key_epoch !== undefined && !epochKeys.has(item.key_epoch)) {
+                pending[key] = { raw, key_epoch: item.key_epoch, received_at: pending[key]?.received_at ?? nowISO() };
+                result.unreadable_epoch_absent.push({ ...item, reason: `reçue, illisible : epoch ${item.key_epoch} absent ; conservée pour relecture après remise de clé.` });
+            }
+            else {
+                delete pending[key];
+                result.rejected.push({ ...item, reason: `${verdict.reason}: ${verdict.detail}` });
+            }
+            continue;
+        }
+        try {
+            materialize(verdict, next, cwd);
+            delete pending[key];
+            seen.add(verdict.idempotencyKey);
+            next = recordRevision(next, verdict.envelope.meta.id_opaque, verdict.envelope.meta.base_rev);
+            result.materialized++;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            pending[key] = { raw, key_epoch: verdict.envelope.key_epoch, received_at: pending[key]?.received_at ?? nowISO() };
+            if (err instanceof DeferredMaterialization)
+                result.deferred.push(problem(raw, reason));
+            else
+                result.rejected.push(problem(raw, `matérialisation: ${reason} (conservée pour reprise)`));
+        }
+    }
+    // Le curseur n'est qu'une optimisation ; la barrière anti-rejeu persistée dans sync
+    // porte la sûreté. Le journal est écrit avant l'état/cursor afin que les epochs absents
+    // restent relisibles même si le cloud ne les retourne plus dans le prochain delta.
+    saveJournal({ schema: INBOUND_SCHEMA, seen: [...seen], pending }, cwd);
+    saveConnectionState({
+        ...next,
+        sync: {
+            ...next.sync,
+            feed_cursor: delta.cursor ?? next.sync.feed_cursor,
+            last_pull_at: nowISO(),
+        },
+    }, cwd);
+    result.retained = Object.keys(pending).length;
+    return result;
+}
+//# sourceMappingURL=federation-pull.js.map

package/dist/core/federation-push.js

@@ -0,0 +1,274 @@
+/**
+ * Fédération v2 — TRANSPORT : drainer l'outbox vers le cloud.
+ *
+ * ── POURQUOI CE MODULE EST SÉPARÉ DE L'ÉMISSION ───────────────────────────────
+ * `federation-emit.ts` scelle et met en file ; celui-ci envoie. La séparation n'est pas
+ * cosmétique : une file qui saurait aussi parler au réseau serait un SECOND chemin par
+ * lequel un objet pourrait sortir sans passer par les trois filets du projecteur. Ici, tout
+ * ce qui part a déjà été scellé — ce module ne voit que des `sealed` opaques et ne peut donc
+ * pas divulguer de clair, même par erreur de programmation.
+ *
+ * ── CE QU'IL FAIT DE L'ÉCHEC ──────────────────────────────────────────────────
+ * Une entrée qui échoue RESTE en attente, avec son erreur enregistrée. Elle n'est ni
+ * supprimée ni déplacée en `conflict` : un échec réseau n'est pas un conflit de révision, et
+ * les confondre ferait disparaître de la file une opération jamais émise.
+ *
+ * Seul un 409 fait passer en `conflict` — c'est le cas où le cloud dit « ta base_rev est
+ * périmée », donc un désaccord d'état qu'un renvoi ne résoudra pas.
+ */
+import crypto from 'node:crypto';
+import { list, transition } from './federation-outbox-v2.js';
+import { loadConnectionState } from './federation-state.js';
+import { loadAgentSigningKey } from './agent-registry.js';
+import { logger } from './logger.js';
+/**
+ * Met une entrée d'outbox à la forme que le cloud attend RÉELLEMENT.
+ *
+ * ── POURQUOI CETTE FONCTION EXISTE, ET CE QU'ELLE A COÛTÉ ────────────────────
+ * La première version envoyait `{ envelope, key_epoch, base_rev }` — la forme que je
+ * SUPPOSAIS. Le cloud attend des champs À PLAT : id, entity_kind, entity_id, rev,
+ * sealed_b64, content_hash, meta, et quatre champs d'origine. Mon test de bout en bout
+ * n'a rien vu : il utilisait un `fetch` simulé, donc il validait mon hypothèse de l'API
+ * contre elle-même.
+ *
+ * C'est la même leçon que d'habitude, à un endroit nouveau : un contrat inter-services ne
+ * se vérifie que contre le service, jamais contre l'idée qu'on s'en fait.
+ *
+ * `sealed` est encodé en base64 d'un JSON canonique : le cloud le stocke sans jamais
+ * l'ouvrir — il n'en a pas la clé.
+ */
+/** En-têtes communs : type, idempotence, et porteur si le déploiement l'exige. */
+function authHeaders(idempotencyKey, apiKey) {
+    const headers = {
+        'content-type': 'application/json',
+        // La clé d'idempotence voyage AUSSI en en-tête : le cloud doit pouvoir dédoublonner
+        // sans ouvrir le corps, qu'il ne peut de toute façon pas lire.
+        'idempotency-key': idempotencyKey,
+    };
+    if (apiKey)
+        headers['authorization'] = `Bearer ${apiKey}`;
+    return headers;
+}
+/**
+ * Charge SIGNÉE DU TRANSPORT — reconstruite exactement comme le cloud la reconstruit.
+ *
+ * L'ordre des clés compte : le cloud fait `JSON.stringify` sur cet objet littéral, sans
+ * tri. Une clé déplacée produit une chaîne différente, donc un condensé différent, donc un
+ * refus SIG_PAYLOAD_HASH_MISMATCH que rien dans le message n'expliquerait.
+ */
+function transportPayload(wire, baseRev) {
+    return JSON.stringify({
+        v: 1,
+        kind: 'brainclaw.federation.v2.envelope',
+        envelope_id: wire['id'],
+        project_id: wire['__project_id'],
+        entity_kind: wire['entity_kind'],
+        entity_id: wire['entity_id'],
+        rev: wire['rev'],
+        base_rev: baseRev,
+        content_hash: wire['content_hash'],
+        key_epoch: wire['key_epoch'],
+        is_tombstone: false,
+    });
+}
+/**
+ * Signe la charge de transport et renseigne les trois champs qui en dépendent.
+ *
+ * ── POURQUOI LE TRANSPORT SIGNE, ALORS QUE L'ENVELOPPE EST DÉJÀ SIGNÉE ───────
+ * Ce sont DEUX garanties distinctes. La signature d'enveloppe (RFC) lie meta ‖ sealed ‖
+ * key_epoch : elle dit « ce contenu vient de cet auteur ». La signature de transport lie
+ * envelope_id, rev, base_rev et content_hash : elle dit « cette opération-ci s'applique à
+ * CETTE révision », ce que la première ne peut pas dire — ces champs n'existent pas encore
+ * au moment de sceller.
+ *
+ * ── ET C'EST CE QUI DÉBLOQUE LE RECALAGE SUR 409 ────────────────────────────
+ * J'avais d'abord jugé les deux contrats incompatibles (dec#160 §6), parce que `base_rev`
+ * peut changer au réessai et invaliderait une signature calculée à l'émission. Faire signer
+ * le TRANSPORT lève l'objection : il resigne simplement avec la nouvelle valeur.
+ *
+ * Cette clé Ed25519 SIGNE, elle ne déchiffre rien : la propriété « ce module ne peut pas
+ * divulguer de clair » tient toujours.
+ */
+function signTransport(wire, baseRev, identityPem) {
+    const payload = Buffer.from(transportPayload(wire, baseRev), 'utf-8');
+    const signature = crypto.sign(null, payload, crypto.createPrivateKey(identityPem));
+    const body = { ...wire, base_rev: baseRev };
+    delete body['__project_id'];
+    return {
+        ...body,
+        origin_sig: signature.toString('base64'),
+        origin_sig_payload_hash: crypto.createHash('sha256').update(payload).digest('hex'),
+    };
+}
+function toWireBody(entry) {
+    const env = entry.sealed;
+    const meta = env.meta;
+    const transport = (meta['transport'] ?? {});
+    // ── L'EMPREINTE PORTE SUR CE QUI EST RÉELLEMENT ENVOYÉ ──────────────────────
+    //
+    // Le cloud recalcule SHA-256 sur les octets DÉCODÉS de `sealed_b64`, en hexadécimal, et
+    // refuse tout écart (CONTENT_HASH_MISMATCH). Le `content_hash` du core est calculé
+    // autrement — base64url sur une autre sérialisation — donc le réutiliser tel quel
+    // échouait systématiquement.
+    //
+    // Le calculer ICI, sur les octets exacts qu'on encode, rend l'accord vrai PAR
+    // CONSTRUCTION plutôt que par coïncidence de conventions. Deux sérialisations qui
+    // doivent produire le même condensé sont un pari ; hacher ce qu'on envoie n'en est pas un.
+    const sealedBytes = Buffer.from(JSON.stringify(env.sealed), 'utf-8');
+    const contentHashHex = crypto.createHash('sha256').update(sealedBytes).digest('hex');
+    return {
+        id: String(transport['idempotency_key'] ?? entry.idempotency_key),
+        entity_kind: meta['kind'],
+        entity_id: meta['id_opaque'],
+        rev: String(meta['base_rev'] ?? entry.base_rev ?? 0),
+        // Aucune tête connue au premier envoi : le cloud l'annonce dans son 409 et l'appelant
+        // se recale une fois. Suivre cette tête localement dupliquerait un état dont le cloud
+        // est déjà l'autorité.
+        base_rev: null,
+        sealed_b64: sealedBytes.toString('base64'),
+        key_epoch: env.key_epoch,
+        content_hash: contentHashHex,
+        idempotency_key: String(transport['idempotency_key'] ?? entry.idempotency_key),
+        // `key_id` de l'enveloppe EST l'empreinte du signataire (cf. federation-emit).
+        // L'agent d'origine voyage à part : le cloud vérifie l'un ET l'autre.
+        origin_agent_id: entry.origin_agent_id ?? env.origin_sig.key_id,
+        // Renseignés par `signTransport` : ils dépendent de `base_rev`, connu seulement ici.
+        origin_sig: '',
+        origin_sig_payload_hash: '',
+        origin_signer_fingerprint: env.origin_sig.key_id,
+        meta,
+        // ── L'ENVELOPPE SIGNÉE, VERBATIM (dec#162) ──────────────────────────────────
+        //
+        // La signature de TRANSPORT ci-dessus prouve « cette opération s'applique à cette
+        // révision » ; elle ne prouve RIEN sur l'auteur du contenu. La signature d'AUTEUR
+        // (origin_sig sur meta‖sealed‖key_epoch, cf. buildEnvelope) est la seule qui le fasse —
+        // et `toWireBody` l'écrasait jusqu'ici en réutilisant le champ `origin_sig` pour le
+        // transport. Un lecteur (pull) ne pouvait donc pas vérifier qui a écrit l'enveloppe.
+        //
+        // On transporte l'enveloppe complète SANS LA TOUCHER. Le cloud la stocke telle quelle et
+        // la rend au pull ; le vérificateur y retrouve `origin_sig.value` d'auteur et
+        // recanonicalise meta/sealed lui-même (federation-inbound). Aucune donnée NOUVELLE ne
+        // fuit : `meta` partait déjà en clair au relais (ligne ci-dessus) — on ne fait que
+        // PERSISTER ce qui transitait déjà. Le champ n'entre pas dans la signature de transport :
+        // son intégrité est portée par la signature d'auteur qu'il contient.
+        envelope_json: JSON.stringify(entry.sealed),
+    };
+}
+/**
+ * Envoie les enveloppes en attente.
+ *
+ * REFUSE plutôt que de deviner : sans appairage actif, sans URL, la fonction lève. Pousser
+ * vers une adresse devinée enverrait des enveloppes chiffrées à un tiers — inintelligibles
+ * pour lui, mais c'est une fuite de métadonnées et de trafic, pas un non-événement.
+ */
+export async function pushPending(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const doFetch = options.fetchImpl ?? fetch;
+    const result = { attempted: 0, sent: 0, conflicts: 0, failed: 0, errors: [] };
+    const state = loadConnectionState(cwd);
+    if (!state || state.enrollment.stage !== 'active') {
+        throw new Error('Aucun appairage actif : rien n\'est envoyé tant que l\'appairage n\'est pas confirmé localement.');
+    }
+    // MANQUE MESURÉ (2026-08-09) : `FederationConnectionState` ne persiste AUCUNE adresse de
+    // cloud — ni à la racine, ni dans `sync`. L'appairage prend `--url` puis l'oublie. Chaque
+    // commande doit donc la repasser. C'est un défaut d'ergonomie à corriger côté appairage,
+    // pas ici : deviner une adresse enverrait le trafic d'un projet à un tiers — illisible
+    // pour lui, mais une fuite de métadonnées et de trafic n'est pas un non-événement.
+    const base = (options.url ?? '').replace(/\/+$/, '');
+    if (!base) {
+        throw new Error('Adresse du cloud inconnue : passez --url. Elle n\'est pas conservée par l\'appairage ' +
+            '(état de connexion sans champ d\'URL), et aucune adresse n\'est devinée.');
+    }
+    // L'identité SIGNATAIRE du transport : celle de l'agent qui a produit les enveloppes.
+    // Elle est portée par l'entrée d'outbox, donc le transport n'a pas à deviner qui signe.
+    const agentId = options.agentId ?? list('pending', cwd)[0]?.origin_agent_id;
+    const identity = agentId ? loadAgentSigningKey(agentId) : undefined;
+    if (!identity) {
+        throw new Error('Identité de signature introuvable : le cloud vérifie une signature de TRANSPORT ' +
+            'liant envelope_id, rev et base_rev. Sans elle, chaque envoi est refusé en 422.');
+    }
+    const identityPem = identity.privateKeyPem;
+    const pending = list('pending', cwd);
+    const batch = options.limit ? pending.slice(0, options.limit) : pending;
+    result.attempted = batch.length;
+    if (options.dryRun)
+        return result;
+    const endpoint = `${base}/api/v1/projects/${state.cloud_project_id}/projection/envelopes`;
+    for (const entry of batch) {
+        try {
+            const wire = { ...toWireBody(entry), __project_id: state.cloud_project_id };
+            let signed = signTransport(wire, null, identityPem);
+            let res = await doFetch(endpoint, {
+                method: 'POST',
+                headers: authHeaders(entry.idempotency_key, options.apiKey),
+                body: JSON.stringify(signed),
+            });
+            // ── RECALAGE SUR 409, UNE SEULE FOIS ──────────────────────────────────
+            //
+            // Le cloud applique une concurrence optimiste : `base_rev` doit désigner la tête
+            // courante. Un émetteur qui n'a jamais poussé ne CONNAÎT pas cette tête — et la
+            // suivre localement dupliquerait un état dont le cloud est déjà l'autorité.
+            //
+            // Le refus la contient (`expected_base_rev`) : on renvoie donc une fois avec la
+            // valeur annoncée. UNE SEULE, délibérément : boucler transformerait un désaccord
+            // réel en écrasement silencieux du travail d'un autre appareil.
+            if (res.status === 409) {
+                const detail = (await res.clone().json().catch(() => ({})));
+                const expected = detail['expected_base_rev'] ?? detail['expected'];
+                if (typeof expected === 'string' || typeof expected === 'number') {
+                    // On RESIGNE avec la nouvelle base_rev : c'est précisément ce que la signature
+                    // au niveau du transport rend possible, et qu'une signature figée à l'émission
+                    // interdisait.
+                    signed = signTransport(wire, String(expected), identityPem);
+                    res = await doFetch(endpoint, {
+                        method: 'POST',
+                        headers: authHeaders(entry.idempotency_key, options.apiKey),
+                        body: JSON.stringify(signed),
+                    });
+                }
+            }
+            if (res.ok || res.status === 202) {
+                transition(entry.idempotency_key, 'pending', 'synced', cwd);
+                result.sent += 1;
+                continue;
+            }
+            if (res.status === 409) {
+                // Désaccord de révision : un renvoi à l'identique échouera pareil. L'entrée passe
+                // en `conflict` pour être VUE, pas retentée en boucle.
+                transition(entry.idempotency_key, 'pending', 'conflict', cwd, (e) => ({
+                    ...e,
+                    last_error: `409 conflit de révision (base_rev=${entry.base_rev})`,
+                }));
+                result.conflicts += 1;
+                result.errors.push({ idempotency_key: entry.idempotency_key, status: 409, reason: 'conflit de révision' });
+                continue;
+            }
+            const body = await res.text();
+            result.failed += 1;
+            result.errors.push({
+                idempotency_key: entry.idempotency_key,
+                status: res.status,
+                reason: body.slice(0, 200),
+            });
+            // RESTE en attente : un refus temporaire ne doit pas faire disparaître l'opération.
+            transition(entry.idempotency_key, 'pending', 'pending', cwd, (e) => ({
+                ...e,
+                attempts: e.attempts + 1,
+                last_error: `HTTP ${res.status}`,
+            }));
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            result.failed += 1;
+            result.errors.push({ idempotency_key: entry.idempotency_key, reason });
+            transition(entry.idempotency_key, 'pending', 'pending', cwd, (e) => ({
+                ...e,
+                attempts: e.attempts + 1,
+                last_error: reason,
+            }));
+            logger.warn(`Envoi échoué (${entry.idempotency_key}) : ${reason}`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=federation-push.js.map