@ouro.bot/cli 0.1.0-alpha.70 → 0.1.0-alpha.700

package/dist/a2a/inbound-share.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.receiveInboundShare = receiveInboundShare;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/** Whether the inbound message carries a friends data part (kind:"data"). */
+function hasDataPart(message) {
+    return Array.isArray(message.parts) && message.parts.some((p) => p && p.kind === "data");
+}
+/**
+ * Bridge an inbound A2A message through friends' `receiveShare`, keying the result
+ * on the VERIFIED sender DID.
+ *
+ * Ordering (the security-critical trap — `trustOfSource` is read from the store BY
+ * the just-verified DID, never defaulted, never from the envelope):
+ *   1. `unwrapDataPart` — no friends part ⇒ `not-a-share` (caller does text path).
+ *   2. `openSealedEnvelope` (pre-unseal) — extract the SIGNED sender DID. Unseal /
+ *      recipient-mismatch failures ⇒ `rejected` (no turn). (This open does NOT
+ *      verify the signature; the real auth gate is the `DidVerifier` inside
+ *      `receiveShare`, so a forged-high-trust claim here is harmless — the forge is
+ *      rejected by the verifier regardless of the trust we read.)
+ *   3. `findFriendByDid(store, verifiedDid)` — read trust off that record; an
+ *      unknown DID ⇒ `stranger` (never a default-up).
+ *   4. `receiveShare({ ..., trustOfSource })` — re-unseal (deterministic) + resolve
+ *      & pin + run `DidVerifier` (forge fails HERE) + replay-dedup + import.
+ *   5. Map the result. `completed` ⇒ run the turn at `verifiedDid`/`trust`.
+ */
+async function receiveInboundShare(message, deps) {
+    const friendsMessage = message;
+    const payload = (0, a2a_client_1.unwrapDataPart)(friendsMessage);
+    if (!payload) {
+        // No (valid) friends part. If there was a data part at all, it was a malformed
+        // friends attempt → reject; otherwise it's a legacy text message → not-a-share.
+        if (hasDataPart(message)) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_inbound_rejected",
+                message: "rejected malformed inbound A2A data part",
+                meta: { reason: "malformed_message" },
+            });
+            return { outcome: "rejected", reason: "malformed_message" };
+        }
+        return { outcome: "not-a-share" };
+    }
+    const recipientIdentity = {
+        x25519Priv: deps.identity.x25519Priv,
+        x25519Pub: deps.identity.x25519Pub,
+    };
+    // Pre-unseal to learn the SIGNED sender DID before we can read its trust.
+    const opened = (0, a2a_client_1.openSealedEnvelope)({
+        sodium: deps.sodium,
+        sealedEnvelope: { v: payload.v, sealed: payload.sealed },
+        recipientDid: deps.identity.did,
+        recipientIdentity,
+    });
+    if (!opened.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_inbound_rejected",
+            message: "rejected inbound A2A envelope (unseal/recipient)",
+            meta: { reason: opened.error },
+        });
+        return { outcome: "rejected", reason: opened.error };
+    }
+    const verifiedDid = opened.fromAgentId;
+    // Read trust from the friend store BY the verified DID — never defaulted, never
+    // from the envelope. Unknown (or empty) DID ⇒ stranger. `findFriendByDid` itself
+    // refuses a falsy did (never matches a did-less record), so this is safe to call
+    // unconditionally.
+    const record = await (0, friends_1.findFriendByDid)(deps.store, verifiedDid);
+    const trust = record?.trustLevel ?? "stranger";
+    const result = await (0, a2a_client_1.receiveShare)({
+        sodium: deps.sodium,
+        store: deps.store,
+        missionStore: deps.missionStore,
+        pinStore: deps.pinStore,
+        didResolution: deps.didResolution,
+        seen: deps.seen,
+        a2aMessage: friendsMessage,
+        recipientDid: deps.identity.did,
+        recipientIdentity,
+        trustOfSource: trust,
+    });
+    if (result.state === "completed") {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_inbound_verified",
+            message: "verified inbound A2A share; keying turn on sender DID",
+            meta: { verifiedDid, trust, friendsKind: result.friendsKind, status: result.status },
+        });
+        return {
+            outcome: "completed",
+            verifiedDid,
+            trust,
+            friendsKind: result.friendsKind,
+            status: result.status,
+        };
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_inbound_rejected",
+        message: "rejected inbound A2A share",
+        meta: { reason: result.reason, verifiedDid, trust },
+    });
+    return { outcome: "rejected", reason: result.reason };
+}

package/dist/a2a/mission-result-wire.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapMissionResultDataPart = wrapMissionResultDataPart;
+exports.isMissionResultDataPart = isMissionResultDataPart;
+exports.receiveInboundMissionResult = receiveInboundMissionResult;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * THE HARNESS-OWNED RESULT WIRE.
+ *
+ * A mission RESULT is NOT a `FriendsKind` (`FriendsKind` = profile_share |
+ * mission_share | coordination) — `prepareMissionResult`/`importMissionResult` are
+ * transport-agnostic + store-only, and the result does NOT ride `sendShare`/
+ * `receiveShare`. So the HARNESS owns the wire: the result envelope is sealed (reusing
+ * the sign-then-seal crypto) and wrapped in a DataPart carrying a distinct `ouroKind:
+ * "mission_result"` discriminator. The inbound bridge recognizes that tag and routes
+ * it to `importMissionResult` — NEVER to `receiveShare`, which would mis-route a
+ * non-`FriendsKind` envelope. This is "a DataPart variant + an inbound route branch"
+ * (the carrier is the friends `unwrapDataPart` shape + one extra tag field — no
+ * structural change beyond that).
+ *
+ * SECURITY — the wire AUTHENTICATES the sender exactly like the share path
+ * (`receiveShare` in friends' `adapter.ts`). `openSealedEnvelope` does AEAD
+ * decryption ONLY — it does NOT verify the signature (its docstring names the
+ * adapter's `DidVerifier` as "the single authentication gate"). The decrypted
+ * `envelope.fromAgentId` is therefore attacker-controlled plaintext: the recipient's
+ * X25519 pubkey is public (derived from the published DID), so any party can SEAL a
+ * forged result to us. Authentication is the ONLY barrier. Before trusting the
+ * claimed sender we therefore replicate `receiveShare`'s gate:
+ *   1. binding check — `opened.signerDid === opened.fromAgentId` (and non-empty),
+ *   2. resolve + pin the sender DID (TOFU pin + signed-rotation evaluation),
+ *   3. hand `importMissionResult` a REAL `DidVerifier` bound to the pinned key, so
+ *      `verifier.verify(fromAgentId, proof)` runs the Ed25519 signature check against
+ *      the pinned key — NOT the no-op `tofuVerifier` the importer defaults to.
+ * Replay is deduped on the seal nonce (durable `SeenLedger`), matching the share path.
+ */
+const OURO_RESULT_KIND = "mission_result";
+/** Wrap a sealed result envelope into the harness-owned `mission_result` DataPart. */
+function wrapMissionResultDataPart(input) {
+    return {
+        messageId: `result-${Math.random().toString(36).slice(2)}`,
+        role: "agent",
+        parts: [{
+                kind: "data",
+                data: {
+                    v: input.sealedEnvelope.v,
+                    sealed: input.sealedEnvelope.sealed,
+                    recipientDid: input.recipientDid,
+                    ouroKind: OURO_RESULT_KIND,
+                },
+            }],
+    };
+}
+/** Whether an inbound message carries the harness-owned `mission_result` DataPart. */
+function isMissionResultDataPart(message) {
+    if (!Array.isArray(message.parts))
+        return false;
+    return message.parts.some((p) => p && p.kind === "data" && typeof p.data === "object" && p.data !== null
+        && p.data.ouroKind === OURO_RESULT_KIND);
+}
+/** Extract the sealed envelope from a `mission_result` DataPart, or null. */
+function unwrapMissionResultDataPart(message) {
+    if (!Array.isArray(message.parts) || message.parts.length !== 1)
+        return null;
+    const part = message.parts[0];
+    if (!part || part.kind !== "data" || !part.data)
+        return null;
+    const data = part.data;
+    if (data.ouroKind !== OURO_RESULT_KIND)
+        return null;
+    if (typeof data.v !== "number" || typeof data.recipientDid !== "string" || !data.sealed)
+        return null;
+    return { sealed: { v: data.v, sealed: data.sealed }, recipientDid: data.recipientDid };
+}
+/**
+ * Route an inbound `mission_result` DataPart to `importMissionResult`, AUTHENTICATING
+ * the sender exactly like `receiveShare` does for every other inbound kind.
+ *
+ * Ordering (mirrors the share bridge's trust trap + authentication gate):
+ *   1. recognize + unwrap the harness `mission_result` carrier (else `not-a-result`).
+ *   2. replay dedup on the seal nonce (durable `SeenLedger`) — before any state change.
+ *   3. `openSealedEnvelope` → AEAD-decrypt only (unseal/recipient failures → reject).
+ *   4. binding check — reject unless `opened.signerDid === opened.fromAgentId` (and
+ *      non-empty): the advisory `signerDid` (outer, unsigned) must match the claimed
+ *      sender. A divergence is a forged/spoofed bundle (`sender_binding_mismatch`).
+ *   5. `resolveAndPin` the sender DID (TOFU pin / signed-rotation) → the pinned key
+ *      (unresolvable/failed-binding/failed-rotation → `resolve_failed`).
+ *   6. build a `DidVerifier` bound to THIS envelope + the pinned key, mark the nonce
+ *      seen, then call `importMissionResult({ envelope, fromAgentId: <signed DID>,
+ *      trustOfSource }, { verifier })`. The verifier runs the REAL signature check
+ *      against the pinned key — a result signed with a key that is not the pinned key
+ *      for the claimed DID is rejected (`untrusted_source`). Every authorization gate
+ *      (no_mission / no_delegation / assignee_mismatch, fail-closed on a legacy
+ *      assignee-less delegation) is still enforced by the importer.
+ */
+async function receiveInboundMissionResult(message, deps) {
+    const payload = unwrapMissionResultDataPart(message);
+    if (!payload)
+        return { outcome: "not-a-result" };
+    // Replay dedup BEFORE any state change, keyed on the seal nonce (matches receiveShare).
+    if (deps.seen.isSeen(payload.sealed.sealed.n)) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (replayed seal nonce)",
+            meta: { reason: "replayed" },
+        });
+        return { outcome: "rejected", reason: "replayed" };
+    }
+    const recipientIdentity = { x25519Priv: deps.identity.x25519Priv, x25519Pub: deps.identity.x25519Pub };
+    const opened = (0, a2a_client_1.openSealedEnvelope)({
+        sodium: deps.sodium,
+        sealedEnvelope: payload.sealed,
+        recipientDid: deps.identity.did,
+        recipientIdentity,
+    });
+    if (!opened.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (unseal/recipient)",
+            meta: { reason: opened.error },
+        });
+        return { outcome: "rejected", reason: opened.error };
+    }
+    // SECURITY (binding): the trustworthy sender identity is the SIGNED `fromAgentId`.
+    // `openSealedEnvelope` does NOT verify the signature, so `fromAgentId` is untrusted
+    // until the DidVerifier confirms the pinned key signed THIS envelope. The advisory
+    // `signerDid` (from the outer, unsigned sealed plaintext) must match the claimed
+    // sender; a divergence is a forged/spoofed bundle (e.g. an attacker signing with its
+    // OWN key while claiming a victim's DID). Reject before resolving or importing.
+    const senderDid = opened.fromAgentId;
+    if (senderDid.length === 0 || opened.signerDid !== senderDid) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (sender binding mismatch — forged sender)",
+            meta: { reason: "sender_binding_mismatch", claimedDid: senderDid, signerDid: opened.signerDid },
+        });
+        return { outcome: "rejected", reason: "sender_binding_mismatch" };
+    }
+    // Read trust from the friend store BY the verified DID — never defaulted, never from
+    // the envelope. Unknown (or empty) DID ⇒ stranger.
+    const record = await (0, friends_1.findFriendByDid)(deps.store, senderDid);
+    const trust = record?.trustLevel ?? "stranger";
+    // Resolve + pin the SENDER's DID (async — BEFORE the sync verifier/importer).
+    const resolved = await deps.didResolution.resolveAndPin({
+        fromAgentId: senderDid,
+        did: senderDid,
+        pinStore: deps.pinStore,
+        trustOfSource: trust,
+    });
+    if (!resolved) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (sender DID resolve/pin failed)",
+            meta: { reason: "resolve_failed", verifiedDid: senderDid, trust },
+        });
+        return { outcome: "rejected", reason: "resolve_failed" };
+    }
+    // Build the sync verifier bound to THIS envelope + the pinned sender key. This is the
+    // single authentication gate (the importer would otherwise default to the no-op TOFU
+    // verifier). `verify` confirms the agentId===did binding AND the Ed25519 signature
+    // over the envelope against the pinned key.
+    const verifier = new a2a_client_1.DidVerifier({
+        sodium: deps.sodium,
+        pinnedEd25519Pub: resolved.ed25519Pub,
+        pinnedDid: senderDid,
+        envelope: opened.envelope,
+    });
+    // Mark seen now (idempotent imports + the replay guard above keep this safe).
+    deps.seen.markSeen(payload.sealed.sealed.n);
+    const result = await (0, friends_1.importMissionResult)(deps.missionStore, {
+        envelope: opened.envelope,
+        fromAgentId: senderDid,
+        trustOfSource: trust,
+    }, { verifier });
+    if (result.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_imported",
+            message: "imported inbound mission_result (authenticated, quarantined, attributed)",
+            meta: { verifiedDid: senderDid, trust, status: result.status },
+        });
+        return { outcome: "imported", verifiedDid: senderDid };
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_result_rejected",
+        message: "rejected inbound mission_result (import gate)",
+        meta: { reason: result.status, verifiedDid: senderDid, trust },
+    });
+    return { outcome: "rejected", reason: result.status };
+}

package/dist/a2a/onboarding.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onboardA2APeer = onboardA2APeer;
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const friends_1 = require("@ouro.bot/friends");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const client_1 = require("./client");
+function storeFor(options) {
+    if (options.store)
+        return options.store;
+    /* v8 ignore next -- default bundle root fallback is owned by identity path tests; CLI and onboarding tests inject explicit roots @preserve */
+    return new friends_1.FileFriendStore(path.join(options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${options.agentName}.ouro`, "friends"));
+}
+/** The normalized card URL (legacy URL-keyed identity for did-less cards). */
+function urlAgentId(cardUrl) {
+    const parsed = new URL(cardUrl);
+    parsed.hash = "";
+    return parsed.toString();
+}
+/** The trimmed `did:key` a card serves, or undefined when the card is did-less. */
+function cardDid(card) {
+    const did = card.did;
+    return typeof did === "string" && did.trim() ? did.trim() : undefined;
+}
+async function onboardA2APeer(options) {
+    // HTTP/URL glue stays harness-side: fetch the agent card, resolve its JSON-RPC
+    // endpoint, and derive the stable agentId. The record-shaping (mint/update the
+    // agent-peer friend) is delegated to @ouro.bot/friends' upsertAgentPeer.
+    const card = await (0, client_1.fetchA2AAgentCard)(options.cardUrl, options.fetchImpl);
+    const store = storeFor(options);
+    /* v8 ignore next -- fetchA2AAgentCard validates a usable endpoint or legacy url before returning a card @preserve */
+    const endpointUrl = (0, client_1.endpointForCard)(card) ?? options.cardUrl;
+    const protocolVersion = card.supportedInterfaces?.find((entry) => entry.url === endpointUrl)?.protocolVersion
+        ?? card.protocolVersion;
+    const name = options.name ?? card.name;
+    // THE FOOTGUN FIX: a DID-bearing card keys the record on its VERIFIED did:key
+    // (so an inbound sealed envelope — keyed on the signed DID — resolves to THIS
+    // record, not a stranger). A did-less (legacy) card keeps the URL-keyed identity
+    // unchanged (backward compatible). For did:key the binding is self-contained
+    // (`card.did === did`, `didDoc: null`); we ALSO require the served did:key to be a
+    // well-formed, parseable Ed25519 key (a malformed did:key could never key/verify
+    // an inbound envelope, so onboarding it would silently break the resolve later). A
+    // card whose DID is unparseable or fails the binding is REFUSED (no record
+    // written) — never TOFU-trust a mis-bound or malformed card.
+    const did = cardDid(card);
+    if (did) {
+        const parsed = (0, a2a_client_1.parseDidKey)(did);
+        const bound = parsed !== null && (0, a2a_client_1.verifyCardDidBinding)({ card: { did, url: options.cardUrl }, did, didDoc: null });
+        if (!bound) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "friends",
+                event: "friends.a2a_card_binding_rejected",
+                message: "refused A2A onboarding: card↔DID binding failed",
+                meta: { agentName: options.agentName, cardUrl: options.cardUrl, did, parseable: parsed !== null },
+            });
+            throw new Error(`A2A card↔DID binding failed for ${did}`);
+        }
+    }
+    // DID-keyed when present (externalId === did, a2a.did === did), else URL-keyed.
+    const externalId = did ?? urlAgentId(options.cardUrl);
+    const record = await (0, friends_1.upsertAgentPeer)(store, {
+        name,
+        agentId: externalId,
+        ...(options.trustLevel ? { trustLevel: options.trustLevel } : {}),
+        a2a: {
+            cardUrl: options.cardUrl,
+            endpointUrl,
+            agentId: externalId,
+            protocolVersion,
+            ...(did ? { did } : {}),
+        },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.a2a_peer_onboarded",
+        message: "onboarded A2A peer into friend model",
+        meta: { agentName: options.agentName, friendId: record.id, peerName: record.name, trustLevel: record.trustLevel, ...(did ? { did } : {}) },
+    });
+    return record;
+}

package/dist/a2a/pin-store.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileA2APinStore = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const runtime_1 = require("../nerves/runtime");
+function pinFileName(fromAgentId) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(fromAgentId).digest("hex")}.json`;
+}
+class FileA2APinStore {
+    dir;
+    cache = new Map();
+    constructor(agentRoot) {
+        this.dir = path.join(agentRoot, "state", "a2a", "pins");
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.loadExisting();
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_store_init",
+            message: "initialized durable A2A pin store",
+            meta: { dir: this.dir, pins: this.cache.size },
+        });
+    }
+    get size() {
+        return this.cache.size;
+    }
+    get(fromAgentId) {
+        if (!fromAgentId)
+            return undefined;
+        const pinned = this.cache.get(fromAgentId);
+        if (!pinned)
+            return undefined;
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_hit",
+            message: "A2A pin hit",
+            meta: { fromAgentId, did: pinned.did },
+        });
+        return pinned;
+    }
+    set(fromAgentId, pinned) {
+        // An empty-string DID is never a matchable key (security: it can never index a
+        // pin). Stay inert rather than writing an unkeyed pin file.
+        if (!fromAgentId)
+            return;
+        const existed = this.cache.has(fromAgentId);
+        // Faithfully persist the pinned identity's DID (which may differ from
+        // fromAgentId after a rotation), not fromAgentId itself.
+        const stored = {
+            fromAgentId,
+            did: pinned.did,
+            pinnedKey: (0, a2a_client_1.base58btcEncode)(pinned.ed25519Pub),
+        };
+        fs.writeFileSync(path.join(this.dir, pinFileName(fromAgentId)), `${JSON.stringify(stored, null, 2)}\n`, "utf-8");
+        this.cache.set(fromAgentId, { did: pinned.did, ed25519Pub: pinned.ed25519Pub });
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_set",
+            message: "set durable A2A pin",
+            meta: { fromAgentId, did: pinned.did, rotated: existed },
+        });
+    }
+    /** Reload every persisted pin from disk into the in-memory cache (the restart
+     * replay). Corrupt/undecodable files are skipped so one bad file can never
+     * wedge the store. */
+    loadExisting() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.dir);
+        }
+        catch {
+            /* v8 ignore next -- the constructor mkdirSync's the dir before this runs; unreadable dir is unreachable in practice @preserve */
+            return;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            let stored;
+            try {
+                stored = JSON.parse(fs.readFileSync(path.join(this.dir, name), "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            // `fromAgentId` is the cache key; fall back to `did` for any pre-rotation
+            // file written before the key/did split (back-compat).
+            const key = stored.fromAgentId ?? stored.did;
+            if (!key || !stored.did || !stored.pinnedKey)
+                continue;
+            const ed25519Pub = (0, a2a_client_1.base58btcDecode)(stored.pinnedKey);
+            if (!ed25519Pub)
+                continue;
+            this.cache.set(key, { did: stored.did, ed25519Pub });
+        }
+    }
+}
+exports.FileA2APinStore = FileA2APinStore;

package/dist/a2a/seen-ledger.js

@@ -0,0 +1,120 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileA2ASeenLedger = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+function nonceFileName(nonce) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(nonce).digest("hex")}.json`;
+}
+class FileA2ASeenLedger {
+    dir;
+    cache = new Set();
+    constructor(agentRoot) {
+        this.dir = path.join(agentRoot, "state", "a2a", "seen");
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.loadExisting();
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_seen_ledger_init",
+            message: "initialized durable A2A seen ledger",
+            meta: { dir: this.dir, seen: this.cache.size },
+        });
+    }
+    get size() {
+        return this.cache.size;
+    }
+    isSeen(nonce) {
+        if (!nonce)
+            return false;
+        const seen = this.cache.has(nonce);
+        if (seen) {
+            // A nonce we already processed is arriving again — for a seal nonce this is
+            // a replay. Loud security signal.
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_replay_rejected",
+                message: "A2A replay rejected (nonce already seen)",
+                meta: { nonceHash: nonceFileName(nonce).slice(0, 16) },
+            });
+        }
+        return seen;
+    }
+    markSeen(nonce) {
+        // An empty-string nonce is never a matchable key — stay inert.
+        if (!nonce)
+            return;
+        if (this.cache.has(nonce))
+            return;
+        fs.writeFileSync(path.join(this.dir, nonceFileName(nonce)), `${JSON.stringify({ nonce, markedAt: new Date().toISOString() }, null, 2)}\n`, "utf-8");
+        this.cache.add(nonce);
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_seen_marked",
+            message: "marked A2A seal nonce as seen (first sight)",
+            meta: { nonceHash: nonceFileName(nonce).slice(0, 16) },
+        });
+    }
+    /** Reload every persisted nonce from disk into the in-memory set (the restart
+     * replay defense). Corrupt/unreadable artifacts are skipped so one bad file can
+     * never reopen the replay window for the rest. */
+    loadExisting() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.dir);
+        }
+        catch {
+            /* v8 ignore next -- the constructor mkdirSync's the dir before this runs; unreadable dir is unreachable in practice @preserve */
+            return;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            let record;
+            try {
+                record = JSON.parse(fs.readFileSync(path.join(this.dir, name), "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            if (typeof record.nonce === "string" && record.nonce.length > 0) {
+                this.cache.add(record.nonce);
+            }
+        }
+    }
+}
+exports.FileA2ASeenLedger = FileA2ASeenLedger;