brainclaw 1.20.4 → 1.22.0

package/dist/core/context-diff.js

@@ -1,8 +1,7 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import { readAuditLog } from './audit.js';
 import { listCandidates } from './candidates.js';
-import { resolveEntityDir } from './io.js';
+import { entityRecordPaths } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import { buildNotificationSummary, hasEventCursor, readUnseenEvents, seedCursorToEnd } from './event-log.js';
 import { SessionSnapshotSchema } from './schema.js';
@@ -28,17 +27,35 @@ export function resolveContextDiffSince(options) {
     // everyone's diff baseline.
     return {};
 }
+/**
+ * THE LAST BY-ID SITE THAT COULD ACTUALLY FIRE, and the only one with live two-layout
+ * data in the field: this store holds 173 sessions in the legacy layout next to 1019
+ * canonical ones (dec#153-T2's dual write). `resolveEntityDir(..., 'read')` answers a
+ * DIRECTORY question with a `hasContent` heuristic, so one canonical file made every
+ * legacy record invisible — the same malformed abstraction pln#649 removed from the
+ * entity locator and the by-id loaders, still here because nothing routed sessions.
+ *
+ * The consequence was a SILENT WRONG ANSWER, which is why this one was worth fixing
+ * while the sibling sites were not: an invisible snapshot falls through to the audit-log
+ * scan, and if that misses too `resolveContextDiffSince` returns no `since`, so
+ * `buildContextDiff` returns undefined and the caller is told "no changes" over a window
+ * where there were changes. An agent cannot tell that apart from a quiet period.
+ *
+ * Uses the shared primitive rather than a fourth hand-rolled pair of paths (io.ts).
+ */
 function loadSessionSnapshot(sessionId, cwd) {
-    const snapshotPath = path.join(resolveEntityDir('sessions', cwd ?? process.cwd(), 'read'), `${sessionId}.json`);
-    if (!fs.existsSync(snapshotPath)) {
-        return undefined;
-    }
-    try {
-        return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
-    }
-    catch {
-        return undefined;
+    for (const snapshotPath of entityRecordPaths('sessions', sessionId, cwd ?? process.cwd())) {
+        if (!fs.existsSync(snapshotPath))
+            continue;
+        try {
+            return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
+        }
+        catch {
+            // An unparseable record in one layout must not mask a good one in the other.
+            continue;
+        }
     }
+    return undefined;
 }
 export function buildContextDiff(options = {}) {
     const resolved = resolveContextDiffSince(options);

package/dist/core/coordination.js

@@ -300,9 +300,7 @@ function buildIncomingSignalsSummary(cwd) {
     try {
         const fedSignals = pullSignalsFromLinkedProjects(cwd);
         for (const sig of fedSignals) {
-            const payloadPreview = typeof sig.payload === 'string'
-                ? sig.payload.slice(0, 120)
-                : JSON.stringify(sig.payload).slice(0, 120);
+            const payloadPreview = JSON.stringify(sig.payload).slice(0, 120);
             incomingSignals.push({
                 id: sig.id,
                 entity_type: sig.type,

package/dist/core/entity-locator.js

@@ -0,0 +1,404 @@
+/**
+ * pln#649 step 2 (dec#153) — locate the store that OWNS an entity, by id.
+ *
+ * THE PROBLEM THIS SOLVES. dec#153 made the entity the routing authority: for any
+ * work unit, `owner_project` is fixed at creation and every read/mutation must
+ * reach THAT store, regardless of pid, cwd, session or the shared global pointer.
+ * Step 1 persisted the owner *inside* the record — but to read that field you must
+ * first find the file, which is the very thing ambient resolution gets wrong. This
+ * module breaks that circle: it finds the record by probing a BOUNDED candidate
+ * set, so a worker holding only an `assignment_id` can be routed correctly without
+ * anything ambient being trusted.
+ *
+ * WHY A PROBE AND NOT AN INDEX. The plan allowed an index; the code does not need
+ * one, and an index would be strictly worse here:
+ *   - the candidate set is already enumerable and small (the store itself, the
+ *     workspace's nested children, declared cross-project links) — one `existsSync`
+ *     each, and the current store is probed FIRST so the overwhelmingly common
+ *     single-project case costs exactly one stat;
+ *   - an index is a second source of truth that can go stale, be half-written, or
+ *     disagree with the filesystem — and the whole point of dec#153 is to stop
+ *     trusting a derived answer over the record itself;
+ *   - `resolveEntityDir` is store-LOCAL (io.ts:79-107 — it joins memoryDir(cwd)
+ *     and falls back only to a legacy path inside the SAME store), so each probe
+ *     is properly isolated and cannot leak a parent store's hit.
+ * If enumeration ever becomes expensive (hundreds of projects), a cache belongs in
+ * FRONT of this function, not instead of it.
+ *
+ * AMBIGUITY IS A RESULT, NOT AN ERROR. Two stores holding the same id is exactly
+ * the divergence T3 must refuse on (step 4), so it is reported as `ambiguous` with
+ * every match rather than silently resolved by first-wins. Callers decide; this
+ * module never picks a winner it cannot justify.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from './config.js';
+import { resolveCrossProjectLinks } from './cross-project.js';
+import { entityRecordPaths, MEMORY_DIR } from './io.js';
+import { resolvePrimaryStore, resolveWorkspaceRoot } from './store-resolution.js';
+import { scanNestedBrainclawProjectsDetailed, summarizeWorkspaceProjects } from './workspace-projects.js';
+/**
+ * Depth ceiling for nested-store scans.
+ *
+ * Review P1-2 offered two remedies for the false `not_found` at depth 7: raise the
+ * ceiling, or report incompleteness. I tried raising it to 12 and MEASURED the
+ * result — a test whose resolved workspace root was a large shared directory took
+ * 130 SECONDS in enumeration alone. Trading a false `not_found` for a pathological
+ * walk on a routing path is the worse defect, and it validated this review's own
+ * warning about hidden enumeration cost. So the ceiling stays at the underlying
+ * default and the enumeration REPORTS when it stopped early (`incomplete`), which
+ * lets a caller distinguish "not there" from "I could not look that far".
+ */
+export const DEFAULT_SCAN_DEPTH = 6;
+/** Directory key in ENTITY_DIR_MAP for each mapped entity kind. */
+function subdirFor(entity) {
+    return entity === 'assignment' ? 'assignments'
+        : entity === 'claim' ? 'claims'
+            : entity === 'agent_run' ? 'runs'
+                : 'plans';
+}
+/**
+ * EVERY file path a record with this id could occupy in one store.
+ *
+ * Deliberately NOT `resolveEntityDir(..., 'read')` any more (review P1-1, which the
+ * reviewer reproduced): that helper picks the canonical directory as soon as it
+ * contains ANY file (`hasContent`), which answers "where do records generally
+ * live" — not "where is THIS record". A store mid-migration holding
+ * `coordination/assignments/asgn_new.json` plus a legacy `assignments/asgn_old.json`
+ * made `asgn_old` unroutable: the canonical dir had content, so the legacy path was
+ * never looked at. Choosing a directory is the wrong primitive for a per-file
+ * question, so both layouts are probed by FILE and the caller sees one hit.
+ */
+/**
+ * The identifier shape `JsonStore` enforces before building a record path
+ * (json-store.ts:78). Duplicated HERE rather than trusted from the caller (review
+ * P2-6): this module joins an id into a filesystem path, so an id containing `..`
+ * or a separator would escape the store it is supposed to be probing. Callers on
+ * the MCP surface validate too and return a clean input_error — this is the
+ * backstop that makes the escape impossible rather than merely unlikely.
+ */
+export function isLocatableId(id) {
+    return /^[A-Za-z0-9_-]+$/.test(id);
+}
+function recordPaths(entity, id, storeCwd) {
+    if (entity === 'loop') {
+        // Loops are not in ENTITY_DIR_MAP — their threads live under loops/threads.
+        return [path.join(storeCwd, MEMORY_DIR, 'loops', 'threads', `${id}.json`)];
+    }
+    // Shared primitive (io.ts): this module had a hand-made copy, and so did two
+    // loaders. One export, four consumers — a fourth review would otherwise have
+    // found the same defect one layer further down.
+    return entityRecordPaths(subdirFor(entity), id, storeCwd);
+}
+/**
+ * One candidate, all its possible layouts. A store that is mid-write,
+ * permission-denied or otherwise unreadable counts as a miss rather than an
+ * exception: routing must not depend on the health of a project the caller has
+ * nothing to do with.
+ */
+function recordExists(entity, id, storeCwd) {
+    for (const candidate of recordPaths(entity, id, storeCwd)) {
+        try {
+            if (fs.existsSync(candidate))
+                return true;
+        }
+        catch { /* unreadable — treat as a miss and keep looking */ }
+    }
+    return false;
+}
+/**
+ * Canonical identity of a store path, for deduplication (review P2-3, reproduced).
+ * `path.resolve` is LEXICAL: a Windows directory junction — or a symlink, or a
+ * case-different spelling — declared as a cross-project link survived as a SECOND
+ * candidate pointing at the same physical store, and the same record was then found
+ * twice and reported `ambiguous`. That is a false positive that blocks a healthy
+ * mutation, i.e. the exact opposite of what the ambiguity contract is for.
+ *
+ * Falls back to the lexical form when the path cannot be realpath'd (missing or
+ * unreadable): a candidate we cannot canonicalise must still be probed, not dropped.
+ */
+function canonicalKey(abs) {
+    try {
+        const real = fs.realpathSync.native(abs);
+        // Windows paths are case-insensitive; lower-casing the KEY only (never the
+        // stored path) makes `C:\Repo` and `c:\repo` one candidate without changing
+        // what is reported back to the caller.
+        return process.platform === 'win32' ? real.toLowerCase() : real;
+    }
+    catch {
+        return process.platform === 'win32' ? abs.toLowerCase() : abs;
+    }
+}
+function describe(storeCwd) {
+    try {
+        const config = loadConfig(storeCwd);
+        return { cwd: storeCwd, project_id: config.project_id, project_name: config.project_name };
+    }
+    catch {
+        // A store we can enumerate but not read config for is still a valid location.
+        return { cwd: storeCwd };
+    }
+}
+/**
+ * Candidate stores, in probe order: the caller's own store first (so the common
+ * single-project case stops after one stat), then the workspace's children, then
+ * declared cross-project links. Deduplicated by resolved absolute path.
+ *
+ * Enumeration mirrors the loop project-resolution gate (loops/project-resolution.ts)
+ * on purpose — two different candidate sets for "which projects exist here" is how
+ * routing surfaces drift apart.
+ */
+export function enumerateCandidateStores(cwd, options = {}) {
+    return enumerateCandidates(cwd, options).stores;
+}
+/**
+ * Per-process memo of the CANDIDATE LIST — never of the probes.
+ *
+ * This module's own header said "a cache belongs in FRONT of this function" and
+ * nobody wrote it, which a Fable audit ranked as the second live risk of the whole
+ * routing change: `enumerateCandidates` re-walks the workspace tree on EVERY routed
+ * mutation, and a worker emits repeated PROGRESS calls for the length of a run.
+ * Measured by a reviewer on Windows: p50 3.36 ms vs 0.23 ms for a direct load (~15x
+ * per call) — and a depth-12 experiment of mine spent 130 SECONDS in enumeration
+ * alone, which is the shape of the tail.
+ *
+ * WHAT IS AND IS NOT CACHED, deliberately. Only "which stores exist here" is memoised
+ * — a filesystem-topology answer that changes when someone creates a project. The
+ * PROBES (does this store hold this id?) are never cached: that is the state a
+ * mutation is about to change, and a stale answer there would route a write to the
+ * wrong store, which is the entire class dec#153 exists to kill.
+ *
+ * ASSUMED TRADE-OFF: for up to TTL milliseconds after a store is created, it is not a
+ * candidate. Consequences are bounded and safe in both directions — a `not_found`
+ * carries `enumeration_incomplete`, and an ambiguity that appears late is caught on
+ * the next call. The TTL is deliberately short: long enough to collapse a burst of
+ * calls from one operation, far too short to matter to a human.
+ */
+const ENUMERATION_MEMO_TTL_MS = 2_000;
+const enumerationMemo = new Map();
+/**
+ * Drop the memo. Called by tests, and by `runInit` — because a store that has just come
+ * into existence is exactly what a cached candidate list cannot know about.
+ *
+ * This comment used to name that second caller before it existed (Fable audit: intent
+ * described as code). Now it does.
+ */
+export function clearEnumerationMemo() {
+    enumerationMemo.clear();
+}
+export function enumerateCandidates(cwd, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_SCAN_DEPTH;
+    // Keyed on the canonical cwd AND the depth, so two callers asking different
+    // questions cannot read each other's answer.
+    const memoKey = `${canonicalKey(path.resolve(cwd))}::${maxDepth}`;
+    if (!options.noMemo) {
+        const hit = enumerationMemo.get(memoKey);
+        if (hit && Date.now() - hit.at < ENUMERATION_MEMO_TTL_MS) {
+            // Copy the array so a caller mutating its result cannot corrupt the memo.
+            return { stores: [...hit.value.stores], incomplete: hit.value.incomplete };
+        }
+    }
+    const computed = enumerateCandidatesUncached(cwd, maxDepth);
+    if (!options.noMemo)
+        enumerationMemo.set(memoKey, { at: Date.now(), value: computed });
+    return { stores: [...computed.stores], incomplete: computed.incomplete };
+}
+function enumerateCandidatesUncached(cwd, maxDepth) {
+    const seen = new Set();
+    const ordered = [];
+    let incomplete = false;
+    const add = (candidate) => {
+        if (!candidate)
+            return;
+        const abs = path.resolve(candidate);
+        // Only real stores are candidates — an unreadable path costs nothing later.
+        if (!fs.existsSync(path.join(abs, MEMORY_DIR, 'config.yaml')))
+            return;
+        // Dedup on the CANONICAL path so a junction/symlink/case alias of a store
+        // already in the list cannot become a second candidate (review P2-3).
+        const key = canonicalKey(abs);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        ordered.push(abs);
+    };
+    /**
+     * ONE nested scan per root, with truncation reported BY THE WALK.
+     *
+     * An earlier version inferred it from the deepest RESULT — a store found at the
+     * ceiling depth meant deeper ones might exist. Review P1-1 reproduced why that is
+     * wrong: with a store at `root/d1/…/d7` and nothing in `d1…d6`, the walk cut the
+     * branch without returning anything near the ceiling, so the heuristic reported
+     * completeness while the target sat just below the cut — and the handler emitted a
+     * CONFIDENT `not_found`. Truncation is a property of the traversal, not of what it
+     * happened to find, so the scanner now says it (still one scan, no extra I/O).
+     */
+    const addNested = (root) => {
+        const scan = scanNestedBrainclawProjectsDetailed(root, maxDepth);
+        for (const project of scan.projects)
+            add(project.path);
+        if (scan.truncated)
+            incomplete = true;
+    };
+    const here = path.resolve(cwd);
+    add(here);
+    let config;
+    try {
+        config = loadConfig(here);
+    }
+    catch {
+        // Uninitialised store: `here` was already rejected by `add`, and there is
+        // nothing to enumerate from. Returning what we have keeps callers simple.
+        return { stores: ordered, incomplete };
+    }
+    if (config.project_mode === 'multi-project') {
+        for (const project of summarizeWorkspaceProjects(here, config).discovered_projects) {
+            // `config`-sourced entries are declared namespaces without a path of their own.
+            if (project.source !== 'config')
+                add(project.path);
+        }
+    }
+    // A workspace root can host nested project stores; so can the workspace root
+    // ABOVE us, which is how a child project reaches its siblings.
+    const wsRoot = resolveWorkspaceRoot(here);
+    if (wsRoot) {
+        add(wsRoot);
+        addNested(wsRoot);
+    }
+    else if (resolvePrimaryStore(here)?.role === 'workspace') {
+        addNested(here);
+    }
+    // A cross-project link can point at a WORKSPACE, whose own children are then
+    // reachable by the linked side (review P1-2, reproduced: A → linked B → B/apps/C
+    // returned candidates [A, B] and not_found for a record living in C). Adding the
+    // link root alone was an arbitrary stop one level short of what the product can
+    // reach, so nested stores under each link are enumerated too.
+    for (const link of resolveCrossProjectLinks(here)) {
+        add(link.absolutePath);
+        addNested(link.absolutePath);
+    }
+    return { stores: ordered, incomplete };
+}
+/**
+ * Find the store holding `id`. Never throws for a missing store or unreadable
+ * config — a locator that fails loudly on an unrelated broken sibling would make
+ * routing depend on the health of projects the caller has nothing to do with.
+ */
+/**
+ * The owner project id shared by EVERY match, or undefined when the records do not
+ * agree on one — which includes all the ways they can fail to answer:
+ *
+ *   - a record with no `project_id` (legacy, created before step 1 persisted it):
+ *     step 1 decided a missing owner must NOT trigger new behaviour, so one absent
+ *     field makes the whole set undecided rather than letting the others vote;
+ *   - records naming DIFFERENT owners — a genuine divergence, the case the hard
+ *     refusal exists for;
+ *   - a record that cannot be read or parsed. NEVER throws: this module refuses to
+ *     make routing depend on the health of a project the caller has nothing to do
+ *     with, and an unreadable record must degrade to `ambiguous`, not to a crash.
+ */
+function sharedRecordOwner(entity, id, matches) {
+    let owner;
+    for (const match of matches) {
+        let recordOwner;
+        for (const candidate of recordPaths(entity, id, match.cwd)) {
+            if (!fs.existsSync(candidate))
+                continue;
+            try {
+                const raw = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+                const value = raw?.project_id;
+                if (typeof value === 'string' && value.trim())
+                    recordOwner = value;
+            }
+            catch { /* unreadable → undecided, handled below */ }
+            break;
+        }
+        if (!recordOwner)
+            return undefined;
+        if (owner === undefined)
+            owner = recordOwner;
+        else if (owner !== recordOwner)
+            return undefined;
+    }
+    return owner;
+}
+export function locateEntity(entity, id, cwd, options = {}) {
+    // An unusable id never touches the filesystem: no path is built, nothing is
+    // probed. Reported as not_found rather than thrown so an MCP handler can turn it
+    // into a clean input_error without a crash, while an internal caller that forgot
+    // to validate still cannot escape a store.
+    if (!isLocatableId(id)) {
+        return { status: 'not_found', matches: [], probed: [], enumeration_incomplete: false };
+    }
+    const enumeration = options.candidates
+        ? { stores: options.candidates, incomplete: false }
+        : enumerateCandidates(cwd, { maxDepth: options.maxDepth });
+    const matches = [];
+    const probed = [];
+    // Alias-aware dedup lives HERE, not only in enumeration: a caller-supplied
+    // candidate list can contain two spellings of one physical store just as easily
+    // (found while pinning review P2-3 — the enumeration-only dedup left this path
+    // open). Probing an alias twice would report a single record as `ambiguous`.
+    const probedKeys = new Set();
+    for (const candidate of enumeration.stores) {
+        const key = canonicalKey(path.resolve(candidate));
+        if (probedKeys.has(key))
+            continue;
+        probedKeys.add(key);
+        probed.push(candidate);
+        if (recordExists(entity, id, candidate))
+            matches.push(describe(candidate));
+    }
+    const incomplete = enumeration.incomplete;
+    if (matches.length === 1) {
+        return { status: 'found', location: matches[0], matches, probed, enumeration_incomplete: incomplete };
+    }
+    if (matches.length > 1) {
+        // ── dec#155's robustness guard: ≥2 matches carrying the SAME owner route to the
+        // owner instead of refusing. Written from that sentence, not from this code.
+        //
+        // This does NOT weaken the ambiguity contract, and the distinction is the whole
+        // point of the module header: "never picks a winner it cannot justify". Here the
+        // RECORD names its owner, so the winner is justified BY THE DATA — it is not a
+        // first-wins tie-break. Every path where the data does not justify a winner
+        // stays `ambiguous`, which is what the two entity-routed surfaces refuse on.
+        //
+        // It uses the field step 1 persisted (`project_id` on assignment / agent_run /
+        // claim) and that this function has ignored ever since, and it exists to avoid
+        // REFUSING a healthy mutation when an alias or a mirror surfaces one record
+        // twice — a false refusal is the exact opposite of what the contract is for.
+        //
+        // Paid only on the ambiguous path: one read per match, in a branch that is
+        // already the rare case. The single-store hit still costs what it cost.
+        //
+        // ONE COUNTEREXAMPLE WAS RAISED AND IS EMPTY TODAY — recorded because it will not
+        // stay empty by itself. `bclaw_move` deliberately leaves a recoverable duplicate
+        // if it crashes between writing the target and removing the source, and it copies
+        // the record VERBATIM (relocate.ts) — so the residue would be two copies naming
+        // the SAME owner, which this guard would route instead of surfacing, freezing the
+        // repair signal. It cannot happen now: `plan` is the only entity both relocatable
+        // and locatable, and plan records carry NO `project_id` (checked against real
+        // records on disk, not just the schema), so `sharedRecordOwner` returns undefined
+        // and the residue stays `ambiguous`. THE DAY PLANS GAIN AN OWNER, relocate must
+        // rewrite `project_id` on the moved copy first — then the residue carries
+        // divergent owners and stays loudly ambiguous, which is the better companion fix
+        // anyway. (Fable audit; the counterexample was sound reasoning about a field the
+        // entity does not have.)
+        const owner = sharedRecordOwner(entity, id, matches);
+        if (owner) {
+            const owned = matches.filter((m) => m.project_id === owner);
+            // Exactly one match must BE the owner store. Zero means the owner is not among
+            // the stores holding the record (so routing there would name a store that does
+            // not have it); more than one means two stores claim the same project id, which
+            // is itself a divergence and not something to resolve here.
+            if (owned.length === 1) {
+                return { status: 'found', location: owned[0], matches, probed, enumeration_incomplete: incomplete };
+            }
+        }
+        return { status: 'ambiguous', matches, probed, enumeration_incomplete: incomplete };
+    }
+    return { status: 'not_found', matches, probed, enumeration_incomplete: incomplete };
+}
+//# sourceMappingURL=entity-locator.js.map

package/dist/core/federation-attestation.js

@@ -0,0 +1,96 @@
+/**
+ * Contrat d'attestation de clé, côté CLIENT (pln#651 étape 4, RFC §5.2).
+ *
+ * ── CE FICHIER A UN JUMEAU, ET C'EST DÉLIBÉRÉ ─────────────────────────────────
+ * Le même contrat existe côté Cloud dans `brainclaw-cloud/src/lib/attestation.ts`.
+ * Les deux DOIVENT produire octet pour octet la même chaîne : le CLI signe, le Worker
+ * vérifie. Ils ne peuvent pas partager un module — deux dépôts, deux runtimes (Node ici,
+ * Workers là-bas) — donc la duplication est assumée et le gel de la forme est verrouillé
+ * DES DEUX CÔTÉS par un test sur le littéral exact.
+ *
+ * Ce n'est pas une précaution théorique. La première livraison côté Cloud reconstruisait
+ * `created_at` avec l'horloge du serveur au moment de l'approbation : la signature portait
+ * sur d'autres octets que ceux vérifiés, et AUCUN appairage ne pouvait aboutir. Le défaut
+ * a survécu à un typecheck vert parce que rien n'exerçait les deux côtés ensemble.
+ *
+ * RÈGLE QUI EN DÉCOULE, valable au-delà de ce fichier : tout champ couvert par une
+ * signature doit venir du signataire, ou d'une valeur qu'il connaît déjà. Un champ que le
+ * vérificateur fabrique lui-même ne peut pas être signé.
+ */
+import crypto from 'node:crypto';
+/**
+ * Payload canonique de l'attestation.
+ *
+ * LA FORME EST GELÉE. Changer l'ordre des clés ou ajouter un champ invalide toutes les
+ * attestations déjà émises — ce qui est voulu, mais doit être un acte délibéré, jamais
+ * l'effet de bord d'une refactorisation. Le test de gel existe pour cela.
+ */
+export function attestationPayload(input) {
+    return JSON.stringify({
+        v: 1,
+        kind: 'brainclaw.federation.v2.key_attestation',
+        enrollment_id: input.enrollment_id,
+        project_id: input.project_id,
+        agent_id: input.agent_id,
+        key_type: input.key_type,
+        key_purpose: input.key_purpose,
+        key_fingerprint: input.key_fingerprint,
+        key_epoch: input.key_epoch,
+        created_at: input.created_at,
+    });
+}
+/**
+ * Empreinte canonique d'un PEM — MÊME RÈGLE que `fingerprintPublicKeyPem` d'agent-registry
+ * et que `fingerprintPem` côté Cloud.
+ *
+ * Le retrait des CR et le trim ne sont pas cosmétiques : le même PEM traversant un champ
+ * JSON ou un éditeur Windows ressort avec un CRLF ou un saut de ligne final. Sans
+ * canonicalisation, deux représentations de LA MÊME clé donnent deux empreintes
+ * différentes — et la comparaison locale↔distante, qui EST la preuve d'identité de la
+ * clé, échouerait sur une différence invisible à l'œil.
+ */
+export function fingerprintPem(pem) {
+    return crypto.createHash('sha256').update(pem.replace(/\r/g, '').trim()).digest('hex');
+}
+/**
+ * Signe des octets avec une clé privée Ed25519 au format PEM, en base64.
+ *
+ * Ed25519 ne prend pas d'algorithme de hachage séparé — d'où le `null` en premier
+ * argument, qui n'est pas un oubli : passer un digest ici lèverait.
+ */
+export function signEd25519(privateKeyPem, message) {
+    const key = crypto.createPrivateKey(privateKeyPem);
+    return crypto.sign(null, Buffer.from(message), key).toString('base64');
+}
+/**
+ * Construit et signe l'attestation liant la clé de chiffrement X25519 de l'appareil à son
+ * identité Ed25519.
+ *
+ * C'EST LA PIÈCE QUI EMPÊCHE LE MEMBRE FANTÔME. Sans elle, le Cloud — qui orchestre
+ * l'appairage — pourrait insérer sa propre clé dans la liste d'enveloppement : un
+ * chiffrement de bout en bout dont l'échange de clés serait arbitré par la partie même
+ * qu'il prétend neutraliser.
+ *
+ * Retourne aussi l'horodatage, que l'appelant DOIT transmettre au serveur : sans lui, le
+ * vérificateur ne peut pas reconstruire les octets signés.
+ */
+export function buildKeyAttestation(params) {
+    const keyFingerprint = fingerprintPem(params.encryptionPublicKeyPem);
+    const payload = attestationPayload({
+        enrollment_id: params.enrollmentId,
+        project_id: params.projectId,
+        agent_id: params.agentId,
+        key_type: 'encryption',
+        key_purpose: 'envelope',
+        key_fingerprint: keyFingerprint,
+        key_epoch: params.keyEpoch ?? 1,
+        created_at: params.createdAt,
+    });
+    return {
+        payload,
+        signature: signEd25519(params.identityPrivateKeyPem, new TextEncoder().encode(payload)),
+        created_at: params.createdAt,
+        key_fingerprint: keyFingerprint,
+    };
+}
+//# sourceMappingURL=federation-attestation.js.map

package/dist/core/federation-canonical.js

@@ -0,0 +1,95 @@
+/**
+ * Sérialisation canonique — fédération v2 (pln#651 étape 5, RFC §3.1).
+ *
+ * ── POURQUOI « CANONIQUE » ET PAS SIMPLEMENT `JSON.stringify` ─────────────────
+ * Ces octets sont hachés, chiffrés et signés par UN programme, puis vérifiés par UN
+ * AUTRE. Une différence d'un seul octet — un espace, un ordre de clés, un `1e3` au lieu
+ * de `1000` — fait échouer la vérification sans qu'aucun message ne dise laquelle des
+ * deux implémentations a tort.
+ *
+ * `JSON.stringify` sur un OBJET n'est déterministe que si l'ordre d'insertion l'est. Il
+ * ne l'est pas quand l'objet vient d'un `JSON.parse`, d'un spread ou d'un tri différent.
+ * D'où un sérialiseur explicite qui trie par point de code, comme l'exige le RFC.
+ *
+ * Le RFC dit aussi : « Core et Cloud partagent les vecteurs de test ; ils ne
+ * réimplémentent pas chacun une quasi-canonicalisation. » Les vecteurs vivent dans les
+ * tests des deux dépôts, sur les mêmes chaînes littérales.
+ */
+import crypto from 'node:crypto';
+/**
+ * Trie par POINT DE CODE et non par `localeCompare`.
+ *
+ * `Array.prototype.sort()` sans comparateur trie déjà par unité de code UTF-16, ce qui
+ * diffère du point de code pour les caractères hors du plan multilingue de base. Un
+ * emoji dans un nom de clé suffirait à faire diverger deux implémentations qui croient
+ * toutes deux « trier les clés ». On compare donc explicitement les points de code.
+ */
+function compareCodePoints(a, b) {
+    const ai = Array.from(a);
+    const bi = Array.from(b);
+    const n = Math.min(ai.length, bi.length);
+    for (let i = 0; i < n; i++) {
+        const ca = ai[i].codePointAt(0);
+        const cb = bi[i].codePointAt(0);
+        if (ca !== cb)
+            return ca - cb;
+    }
+    return ai.length - bi.length;
+}
+/**
+ * JSON canonique : clés triées, aucune espace, chaînes NFC, entiers finis sans notation
+ * exponentielle.
+ *
+ * REFUSE plutôt que d'inventer une représentation pour ce que JSON ne porte pas
+ * fidèlement : `undefined`, `NaN`, `Infinity`, fonctions, symboles, `BigInt`. Les
+ * sérialiser en `null` — ce que fait `JSON.stringify` pour certains — produirait deux
+ * objets différents avec les mêmes octets, donc une signature valide pour un contenu
+ * qu'on n'a pas signé.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new Error(`Canonicalisation impossible : nombre non fini (${String(value)}).`);
+            }
+            // `String(1e21)` rend "1e+21". Le RFC interdit la notation exponentielle, et un
+            // vérificateur qui lirait "1e+21" produirait d'autres octets que celui qui écrit
+            // "1000000000000000000000". Refuser est plus sûr qu'une conversion approximative.
+            if (Number.isInteger(value) && Math.abs(value) >= 1e21) {
+                throw new Error(`Canonicalisation impossible : entier hors de la plage sérialisable sans exposant (${value}).`);
+            }
+            return JSON.stringify(value);
+        case 'string':
+            // NFC : « é » composé et « e + accent » combinés sont visuellement identiques et
+            // produisent des octets différents. Sans normalisation, un titre saisi sur macOS
+            // (NFD par défaut) et le même titre saisi sur Windows ne se vérifieraient pas.
+            return JSON.stringify(value.normalize('NFC'));
+        case 'object': {
+            if (Array.isArray(value)) {
+                return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+            }
+            const obj = value;
+            const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort(compareCodePoints);
+            return `{${keys.map((k) => `${JSON.stringify(k.normalize('NFC'))}:${canonicalJson(obj[k])}`).join(',')}}`;
+        }
+        default:
+            throw new Error(`Canonicalisation impossible : type '${typeof value}' non sérialisable en JSON.`);
+    }
+}
+/** base64url sans padding — la seule forme admise par le RFC pour les champs binaires. */
+export function b64url(bytes) {
+    return Buffer.from(bytes).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export function b64urlDecode(s) {
+    const padded = s.replace(/-/g, '+').replace(/_/g, '/');
+    return new Uint8Array(Buffer.from(padded + '='.repeat((4 - (padded.length % 4)) % 4), 'base64'));
+}
+/** SHA-256 des octets canoniques d'une valeur, rendu en base64url (RFC §3.2). */
+export function canonicalSha256(value) {
+    return b64url(new Uint8Array(crypto.createHash('sha256').update(canonicalJson(value), 'utf-8').digest()));
+}
+//# sourceMappingURL=federation-canonical.js.map