@ouro.bot/friends 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/a2a-client/jcs.js

@@ -0,0 +1,84 @@
+"use strict";
+// JCS — JSON Canonicalization Scheme (RFC 8785), hand-rolled.
+//
+// Why hand-rolled (not a dep): the obvious dep `canonicalize` is ESM-only, and
+// friends compiles to CommonJS with JCS called SYNCHRONOUSLY on the crypto hot
+// path (both Ed25519 signing AND the AEAD associated-data construction). A
+// dynamic `import()` (the only way CJS reaches ESM-only) would force seal/sign
+// async — unacceptable. Hand-rolling keeps JCS sync and the only new runtime dep
+// `libsodium-wrappers`. The RFC 8785 number-serialization edge cases are
+// exhaustively unit-tested (see a2a-client-jcs.test.ts).
+//
+// The canonical form (RFC 8785):
+//   • object keys sorted by UTF-16 code-unit order, recursively;
+//   • no insignificant whitespace;
+//   • arrays preserve element order;
+//   • strings serialized with JSON string escaping (which IS RFC 8785's);
+//   • numbers serialized per RFC 8785 §3.2.2 — ECMAScript `Number.prototype
+//     .toString` for finite values (integers carry no fractional part), with
+//     `-0` normalized to `0`; NaN / Infinity are rejected;
+//   • `null` → "null"; booleans literal.
+// Our envelopes carry only strings, ISO-date strings, small integers (v:1,
+// counts) and nested objects/arrays — no floats on the wire — but the number
+// path is tested anyway. `undefined` / functions / symbols are NOT valid JSON
+// values and are rejected loudly rather than silently dropped.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jcsString = jcsString;
+exports.jcsBytes = jcsBytes;
+/** Serialize a number per RFC 8785 §3.2.2. Rejects non-finite values. */
+function serializeNumber(n) {
+    if (!Number.isFinite(n)) {
+        throw new Error(`JCS: non-finite number cannot be canonicalized: ${String(n)}`);
+    }
+    // ECMAScript Number.prototype.toString is the RFC 8785 number production for
+    // finite values; it already emits integers without a fractional part and uses
+    // the shortest round-tripping form. Normalize negative zero to "0" (RFC 8785
+    // serializes -0 as 0).
+    if (Object.is(n, -0))
+        return "0";
+    return n.toString();
+}
+/** Canonicalize a single value into its JCS string fragment. */
+function canonicalize(value) {
+    if (value === null)
+        return "null";
+    const t = typeof value;
+    if (t === "string")
+        return JSON.stringify(value);
+    if (t === "boolean")
+        return value ? "true" : "false";
+    if (t === "number")
+        return serializeNumber(value);
+    if (t === "bigint") {
+        throw new Error("JCS: bigint cannot be canonicalized (not a JSON number)");
+    }
+    if (t === "undefined" || t === "function" || t === "symbol") {
+        throw new Error(`JCS: ${t} is not a valid JSON value`);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((el) => canonicalize(el)).join(",")}]`;
+    }
+    // Plain object: sort keys by UTF-16 code-unit order (the default `<` on JS
+    // strings), recurse. Keys whose value is `undefined` are omitted (matching
+    // JSON.stringify), but a value that is a function/symbol is omitted too — to
+    // stay strict we DROP only `undefined` (JSON-absent) and reject the rest.
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+        const v = obj[key];
+        if (v === undefined)
+            continue; // JSON omits undefined-valued keys
+        parts.push(`${JSON.stringify(key)}:${canonicalize(v)}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+/** The JCS canonical JSON string for `value` (RFC 8785). */
+function jcsString(value) {
+    return canonicalize(value);
+}
+/** The UTF-8 bytes of the JCS canonical JSON string — the message fed to
+ * Ed25519 signing and used as AEAD associated-data. */
+function jcsBytes(value) {
+    return new TextEncoder().encode(jcsString(value));
+}

package/dist/a2a-client/reachability.d.ts

@@ -0,0 +1,22 @@
+import type { AgentMeta } from "../types";
+export type ReachabilityPlan = {
+    rung: "direct";
+    endpointUrl: string;
+} | {
+    rung: "relay";
+    relay: {
+        url: string;
+        handle: string;
+    };
+} | {
+    rung: "mailbox";
+    mailbox: {
+        repo: string;
+        selfOutboxAgentId: string;
+    };
+} | {
+    rung: "unreachable";
+};
+/** Resolve the reachability rung for a peer from its A2A coords + (top-level)
+ * mailbox coords. Deterministic, pure. */
+export declare function resolveReachability(peerA2A: AgentMeta["a2a"] | undefined, peerMailbox: AgentMeta["mailbox"] | undefined): ReachabilityPlan;

package/dist/a2a-client/reachability.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveReachability = resolveReachability;
+/** Resolve the reachability rung for a peer from its A2A coords + (top-level)
+ * mailbox coords. Deterministic, pure. */
+function resolveReachability(peerA2A, peerMailbox) {
+    if (peerA2A?.endpointUrl) {
+        return { rung: "direct", endpointUrl: peerA2A.endpointUrl };
+    }
+    if (peerA2A?.relay) {
+        return { rung: "relay", relay: peerA2A.relay };
+    }
+    if (peerMailbox) {
+        return { rung: "mailbox", mailbox: peerMailbox };
+    }
+    return { rung: "unreachable" };
+}

package/dist/a2a-client/seal.d.ts

@@ -0,0 +1,47 @@
+import type { Sodium } from "./sodium";
+/** The opaque sealed blob the relay carries. All fields base64 (ORIGINAL
+ * variant). Nothing here reveals the sender, the payload, or the friends kind. */
+export interface SealedBlob {
+    /** Overlay version (bound into the AAD). */
+    v: number;
+    /** The sender's ephemeral X25519 public key (base64). */
+    ePk: string;
+    /** The AEAD nonce (base64, 24 bytes). */
+    n: string;
+    /** The AEAD ciphertext+tag (base64). */
+    ct: string;
+}
+export interface SealToInput {
+    sodium: Sodium;
+    /** The plaintext to seal (already the sign-then-seal plaintext bytes). */
+    plaintextBytes: Uint8Array;
+    /** The recipient's X25519 keyAgreement public key. */
+    recipientX25519Pub: Uint8Array;
+    /** The recipient's DID — bound into the AEAD AD (the re-target defense). */
+    recipientDid: string;
+    /** Overlay version (default 1). */
+    v?: number;
+}
+/** Seal `plaintextBytes` to a recipient, binding the recipient DID into the AEAD
+ * associated-data. Returns the opaque blob. */
+export declare function sealTo(input: SealToInput): SealedBlob;
+export interface OpenSealedInput {
+    sodium: Sodium;
+    blob: SealedBlob;
+    /** The recipient's X25519 keyAgreement private key. */
+    recipientX25519Priv: Uint8Array;
+    /** The recipient's X25519 keyAgreement public key (bound into the KDF). */
+    recipientX25519Pub: Uint8Array;
+    /** The recipient's own DID — reconstructed as the AEAD AD. A wrong DID (a
+     * re-targeted blob) breaks the tag. */
+    recipientDid: string;
+}
+/** Thrown by `openSealed` on any failure (bad base64, wrong key, tampered or
+ * re-targeted ciphertext → AEAD tag mismatch). The caller maps this to a typed
+ * `unseal_failed` result; it never leaks plaintext. */
+export declare class SealOpenError extends Error {
+    constructor(message: string);
+}
+/** Open a sealed blob. Throws `SealOpenError` on any failure (the AEAD tag
+ * enforces tamper + re-target resistance at the crypto layer). */
+export declare function openSealed(input: OpenSealedInput): Uint8Array;

package/dist/a2a-client/seal.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SealOpenError = void 0;
+exports.sealTo = sealTo;
+exports.openSealed = openSealed;
+// seal — the E2E sealing primitive (the "sealed-box shape" with a REAL AEAD AD).
+//
+// The relay is UNTRUSTED: it must carry ciphertext only and never be able to
+// read, tamper, or RE-TARGET a blob. Standard `crypto_box_seal` exposes no AAD,
+// so to honor the spec literally ("AEAD associated-data binds the blob to its
+// recipient") this builds the seal from `crypto_aead_xchacha20poly1305_ietf_*`
+// over an ephemeral X25519 ECDH key, with AAD = the JCS-canonical bytes of
+// `{ recipientDid, v }`. Consequence: a re-target (delivering B's blob to C) fails
+// at the AEAD TAG when C reconstructs its own DID as AAD — the strong, crypto-
+// layer defense, not a post-unseal app check.
+//
+// Construction (decision #1):
+//   sender:   ePk,eSk = X25519 keypair; shared = scalarmult(eSk, recipientX25519Pub)
+//             K = generichash(32, shared || ePk || recipientX25519Pub)   (transcript-bound)
+//             N = 24 random bytes; ct = AEAD_encrypt(plaintext, AAD={recipientDid,v}, N, K)
+//             blob = { v, ePk, n, ct } (all base64 ORIGINAL)
+//   recipient: shared' = scalarmult(recipientX25519Priv, ePk); K' = generichash(32, shared'||ePk||recipientX25519Pub)
+//             AEAD_decrypt(ct, AAD={recipientDid:self,v}, N, K') — throws on tag mismatch.
+const jcs_1 = require("./jcs");
+/** Derive the transcript-bound symmetric key from an ECDH shared secret. Binding
+ * `ePk` and the recipient pubkey into the KDF means the key is unique per
+ * (ephemeral, recipient) pair — a relay cannot swap ephemerals to attack it. */
+function deriveKey(sodium, shared, ePk, recipientPub) {
+    const transcript = new Uint8Array(shared.length + ePk.length + recipientPub.length);
+    transcript.set(shared, 0);
+    transcript.set(ePk, shared.length);
+    transcript.set(recipientPub, shared.length + ePk.length);
+    return sodium.crypto_generichash(32, transcript, null);
+}
+/** Seal `plaintextBytes` to a recipient, binding the recipient DID into the AEAD
+ * associated-data. Returns the opaque blob. */
+function sealTo(input) {
+    const { sodium, plaintextBytes, recipientX25519Pub, recipientDid } = input;
+    const v = input.v ?? 1;
+    // Ephemeral X25519 keypair (one-shot per message).
+    const eph = sodium.crypto_box_keypair();
+    const ePk = eph.publicKey;
+    const eSk = eph.privateKey;
+    const shared = sodium.crypto_scalarmult(eSk, recipientX25519Pub);
+    const key = deriveKey(sodium, shared, ePk, recipientX25519Pub);
+    const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    const ad = (0, jcs_1.jcsBytes)({ recipientDid, v });
+    const ct = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintextBytes, ad, null, nonce, key);
+    const ORIGINAL = sodium.base64_variants.ORIGINAL;
+    return {
+        v,
+        ePk: sodium.to_base64(ePk, ORIGINAL),
+        n: sodium.to_base64(nonce, ORIGINAL),
+        ct: sodium.to_base64(ct, ORIGINAL),
+    };
+}
+/** Thrown by `openSealed` on any failure (bad base64, wrong key, tampered or
+ * re-targeted ciphertext → AEAD tag mismatch). The caller maps this to a typed
+ * `unseal_failed` result; it never leaks plaintext. */
+class SealOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SealOpenError";
+    }
+}
+exports.SealOpenError = SealOpenError;
+/** Open a sealed blob. Throws `SealOpenError` on any failure (the AEAD tag
+ * enforces tamper + re-target resistance at the crypto layer). */
+function openSealed(input) {
+    const { sodium, blob, recipientX25519Priv, recipientX25519Pub, recipientDid } = input;
+    const ORIGINAL = sodium.base64_variants.ORIGINAL;
+    let ePk;
+    let nonce;
+    let ct;
+    try {
+        ePk = sodium.from_base64(blob.ePk, ORIGINAL);
+        nonce = sodium.from_base64(blob.n, ORIGINAL);
+        ct = sodium.from_base64(blob.ct, ORIGINAL);
+    }
+    catch {
+        throw new SealOpenError("seal: malformed base64 in sealed blob");
+    }
+    const shared = sodium.crypto_scalarmult(recipientX25519Priv, ePk);
+    const key = deriveKey(sodium, shared, ePk, recipientX25519Pub);
+    const ad = (0, jcs_1.jcsBytes)({ recipientDid, v: blob.v });
+    try {
+        return sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ct, ad, nonce, key);
+    }
+    catch {
+        // Tag mismatch: tampered ct/nonce, wrong ephemeral, wrong recipient key, OR a
+        // re-targeted blob (wrong recipientDid in the AAD). All collapse to one
+        // indistinguishable failure — exactly the security property we want.
+        throw new SealOpenError("seal: AEAD open failed (tampered, wrong recipient, or re-targeted)");
+    }
+}

package/dist/a2a-client/sealed-envelope.d.ts

@@ -0,0 +1,55 @@
+import type { SealedBlob } from "./seal";
+import type { Sodium } from "./sodium";
+/** The friends taxonomy discriminant (the re-homed mailbox `kind`). Travels
+ * SEALED, never on the DataPart `data`. */
+export type FriendsKind = "profile_share" | "mission_share" | "coordination";
+/** The on-the-wire sealed envelope: NOTHING plaintext beyond the version. */
+export interface SealedEnvelope {
+    v: number;
+    sealed: SealedBlob;
+}
+/** The signer's identity material (self). */
+export interface FromIdentity {
+    did: string;
+    keyId: string;
+    ed25519Priv: Uint8Array;
+}
+export interface SealEnvelopeInput {
+    sodium: Sodium;
+    /** The plaintext friends envelope (ProfileShare/MissionShare/Coordination). */
+    envelope: Record<string, unknown>;
+    friendsKind: FriendsKind;
+    fromIdentity: FromIdentity;
+    recipientDid: string;
+    recipientX25519Pub: Uint8Array;
+    v?: number;
+}
+/** Sign-then-seal compose. Returns the opaque SealedEnvelope. */
+export declare function sealEnvelope(input: SealEnvelopeInput): SealedEnvelope;
+/** The recipient's identity material (self). */
+export interface RecipientIdentity {
+    x25519Priv: Uint8Array;
+    x25519Pub: Uint8Array;
+}
+export type OpenSealedEnvelopeResult = {
+    ok: true;
+    envelope: Record<string, unknown>;
+    fromAgentId: string;
+    signerDid: string;
+    signerKeyId: string;
+    friendsKind: FriendsKind;
+} | {
+    ok: false;
+    error: "unseal_failed" | "malformed_plaintext" | "recipient_mismatch";
+};
+export interface OpenSealedEnvelopeInput {
+    sodium: Sodium;
+    sealedEnvelope: SealedEnvelope;
+    recipientDid: string;
+    recipientIdentity: RecipientIdentity;
+}
+/** Open a SealedEnvelope. Does NOT verify the signature (U8's adapter resolves +
+ * pins the sender DID, then runs DidVerifier — the single authentication gate).
+ * The belt-and-suspenders `recipient === recipientDid` check is the redundant
+ * second line behind the AEAD AD (which already enforced it). */
+export declare function openSealedEnvelope(input: OpenSealedEnvelopeInput): OpenSealedEnvelopeResult;

package/dist/a2a-client/sealed-envelope.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sealEnvelope = sealEnvelope;
+exports.openSealedEnvelope = openSealedEnvelope;
+// SealedEnvelope — the full sign-then-seal compose (ties U2 seal + U3 sign).
+//
+// ORDER (sign-then-seal, spec §3.1): sign the plaintext envelope FIRST, put the
+// structured proof in the envelope's reserved slot, then SEAL the whole signed
+// bundle to the recipient. The signature lives INSIDE the ciphertext — the relay
+// never sees who signed. `friendsKind` also rides inside the sealed plaintext
+// (relay-blind), so the recipient unseals first, THEN branches on the kind.
+const seal_1 = require("./seal");
+const sign_1 = require("./sign");
+/** Sign-then-seal compose. Returns the opaque SealedEnvelope. */
+function sealEnvelope(input) {
+    const { sodium, envelope, friendsKind, fromIdentity, recipientDid, recipientX25519Pub } = input;
+    const v = input.v ?? 1;
+    // 1. Sign the envelope (proof excluded from the canonical bytes — see sign.ts).
+    const proof = (0, sign_1.signEnvelope)({
+        sodium,
+        envelope,
+        signerEd25519Priv: fromIdentity.ed25519Priv,
+        signerDid: fromIdentity.did,
+        signerKeyId: fromIdentity.keyId,
+    });
+    // 2. Put the structured proof in the envelope's reserved slot, so the unsealed
+    //    plaintext carries the proof the importer reads via `envelope.proof`.
+    const envelopeWithProof = { ...envelope, proof: (0, sign_1.serializeProof)(proof) };
+    // 3. Build the sealed plaintext (friendsKind + the recipient binding ride INSIDE).
+    const plaintext = {
+        envelope: envelopeWithProof,
+        signature: proof.sig,
+        signerDid: proof.signerDid,
+        signerKeyId: proof.signerKeyId,
+        recipient: recipientDid,
+        v,
+        friendsKind,
+    };
+    const plaintextBytes = new TextEncoder().encode(JSON.stringify(plaintext));
+    // 4. Seal to the recipient (the recipientDid is bound into the AEAD AD by sealTo).
+    const sealed = (0, seal_1.sealTo)({ sodium, plaintextBytes, recipientX25519Pub, recipientDid, v });
+    return { v, sealed };
+}
+/** Open a SealedEnvelope. Does NOT verify the signature (U8's adapter resolves +
+ * pins the sender DID, then runs DidVerifier — the single authentication gate).
+ * The belt-and-suspenders `recipient === recipientDid` check is the redundant
+ * second line behind the AEAD AD (which already enforced it). */
+function openSealedEnvelope(input) {
+    const { sodium, sealedEnvelope, recipientDid, recipientIdentity } = input;
+    let plaintextBytes;
+    try {
+        plaintextBytes = (0, seal_1.openSealed)({
+            sodium,
+            blob: sealedEnvelope.sealed,
+            recipientX25519Priv: recipientIdentity.x25519Priv,
+            recipientX25519Pub: recipientIdentity.x25519Pub,
+            recipientDid,
+        });
+    }
+    catch {
+        return { ok: false, error: "unseal_failed" };
+    }
+    let plaintext;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(plaintextBytes));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { ok: false, error: "malformed_plaintext" };
+        }
+        plaintext = parsed;
+    }
+    catch {
+        return { ok: false, error: "malformed_plaintext" };
+    }
+    if (!plaintext.envelope || typeof plaintext.envelope !== "object") {
+        return { ok: false, error: "malformed_plaintext" };
+    }
+    if (typeof plaintext.friendsKind !== "string" || typeof plaintext.signerDid !== "string") {
+        return { ok: false, error: "malformed_plaintext" };
+    }
+    // Belt-and-suspenders: the AEAD AD already bound the recipient, but re-assert.
+    if (plaintext.recipient !== recipientDid) {
+        return { ok: false, error: "recipient_mismatch" };
+    }
+    const envelope = plaintext.envelope;
+    const fromAgentId = typeof envelope.fromAgentId === "string" ? envelope.fromAgentId : "";
+    return {
+        ok: true,
+        envelope,
+        fromAgentId,
+        signerDid: plaintext.signerDid,
+        signerKeyId: plaintext.signerKeyId,
+        friendsKind: plaintext.friendsKind,
+    };
+}

package/dist/a2a-client/sign.d.ts

@@ -0,0 +1,42 @@
+import type { Sodium } from "./sodium";
+/** The structured proof serialized (as JSON) into the envelope's `proof?: string`
+ * slot. `alg`/`canon` are pinned so a verifier rejects anything it can't check. */
+export interface StructuredProof {
+    alg: "EdDSA";
+    /** The detached Ed25519 signature, base64 (ORIGINAL variant). */
+    sig: string;
+    /** The signer's DID (== its agentId; the binding is checked by DidVerifier). */
+    signerDid: string;
+    /** The signer's key id (the did:key fragment / DID-doc verification-method id). */
+    signerKeyId: string;
+    canon: "JCS";
+}
+export interface SignEnvelopeInput {
+    sodium: Sodium;
+    /** The plaintext envelope to sign (its `proof` field, if any, is excluded). */
+    envelope: unknown;
+    signerEd25519Priv: Uint8Array;
+    signerDid: string;
+    signerKeyId: string;
+}
+/** Sign an envelope: Ed25519 detached signature over `jcsBytes(envelope without
+ * proof)`. Returns the structured proof. */
+export declare function signEnvelope(input: SignEnvelopeInput): StructuredProof;
+export interface VerifyEnvelopeSignatureInput {
+    sodium: Sodium;
+    /** The plaintext envelope whose signature is being checked (proof excluded). */
+    envelope: unknown;
+    /** The structured proof — either the object or its JSON string form. */
+    proof: StructuredProof | string | undefined;
+    signerEd25519Pub: Uint8Array;
+}
+/** Verify an envelope's Ed25519 signature. Returns false (never throws) on a
+ * malformed proof, wrong `alg`/`canon`, missing fields, bad base64, or a bad
+ * signature. */
+export declare function verifyEnvelopeSignature(input: VerifyEnvelopeSignatureInput): boolean;
+/** Serialize a structured proof into the envelope's `proof?: string` slot. */
+export declare function serializeProof(p: StructuredProof): string;
+/** Parse a structured proof from the `proof?: string` slot. Returns null on
+ * invalid JSON or a non-object payload; field-level validation is the verifier's
+ * job (so a partially-shaped proof still surfaces as a verify failure). */
+export declare function parseProof(s: string): StructuredProof | null;

package/dist/a2a-client/sign.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signEnvelope = signEnvelope;
+exports.verifyEnvelopeSignature = verifyEnvelopeSignature;
+exports.serializeProof = serializeProof;
+exports.parseProof = parseProof;
+// sign — Ed25519 detached signing/verification over JCS-canonical envelope bytes,
+// and the structured proof that rides in the envelope's reserved `proof?: string`
+// slot (decision #3; the envelope-level `proof` TYPE is unchanged so CORE needs no
+// edit).
+//
+// CRITICAL: the signature is computed over the envelope with its `proof` field
+// EXCLUDED — you cannot sign over the proof you are producing, and the verifier
+// must recompute the identical canonical bytes. Both sides strip `proof` before
+// `jcsBytes`.
+const jcs_1 = require("./jcs");
+/** Strip the `proof` field so signing/verifying both canonicalize the same bytes.
+ * Returns a shallow copy without `proof` (the rest of the envelope is unchanged). */
+function envelopeWithoutProof(envelope) {
+    if (!envelope || typeof envelope !== "object" || Array.isArray(envelope))
+        return envelope;
+    const { proof: _proof, ...rest } = envelope;
+    return rest;
+}
+/** Sign an envelope: Ed25519 detached signature over `jcsBytes(envelope without
+ * proof)`. Returns the structured proof. */
+function signEnvelope(input) {
+    const { sodium, envelope, signerEd25519Priv, signerDid, signerKeyId } = input;
+    const msg = (0, jcs_1.jcsBytes)(envelopeWithoutProof(envelope));
+    const sig = sodium.crypto_sign_detached(msg, signerEd25519Priv);
+    return {
+        alg: "EdDSA",
+        sig: sodium.to_base64(sig, sodium.base64_variants.ORIGINAL),
+        signerDid,
+        signerKeyId,
+        canon: "JCS",
+    };
+}
+/** Verify an envelope's Ed25519 signature. Returns false (never throws) on a
+ * malformed proof, wrong `alg`/`canon`, missing fields, bad base64, or a bad
+ * signature. */
+function verifyEnvelopeSignature(input) {
+    const { sodium, envelope, signerEd25519Pub } = input;
+    const proof = typeof input.proof === "string" ? parseProof(input.proof) : input.proof;
+    if (!proof)
+        return false;
+    if (proof.alg !== "EdDSA" || proof.canon !== "JCS")
+        return false;
+    if (typeof proof.sig !== "string" || typeof proof.signerDid !== "string" || typeof proof.signerKeyId !== "string") {
+        return false;
+    }
+    let sigBytes;
+    try {
+        sigBytes = sodium.from_base64(proof.sig, sodium.base64_variants.ORIGINAL);
+    }
+    catch {
+        return false;
+    }
+    const msg = (0, jcs_1.jcsBytes)(envelopeWithoutProof(envelope));
+    try {
+        return sodium.crypto_sign_verify_detached(sigBytes, msg, signerEd25519Pub);
+    }
+    catch {
+        // A wrong-length signature can throw inside libsodium — treat as a failed
+        // verification, never an uncaught error.
+        return false;
+    }
+}
+/** Serialize a structured proof into the envelope's `proof?: string` slot. */
+function serializeProof(p) {
+    return JSON.stringify(p);
+}
+/** Parse a structured proof from the `proof?: string` slot. Returns null on
+ * invalid JSON or a non-object payload; field-level validation is the verifier's
+ * job (so a partially-shaped proof still surfaces as a verify failure). */
+function parseProof(s) {
+    let parsed;
+    try {
+        parsed = JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    return parsed;
+}

package/dist/a2a-client/sodium.d.ts

@@ -0,0 +1,5 @@
+import _sodium from "libsodium-wrappers";
+/** The libsodium-wrappers instance type. */
+export type Sodium = typeof _sodium;
+/** Await the WASM init (idempotent) and return the ready libsodium instance. */
+export declare function ready(): Promise<Sodium>;

package/dist/a2a-client/sodium.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ready = ready;
+// sodium — the single libsodium init seam for the a2a-client.
+//
+// libsodium-wrappers is WASM with async init; nothing crypto-bearing may run
+// before `await _sodium.ready`. Every entry point that touches a primitive funnels
+// through `ready()` so the WASM is initialized exactly once. Downstream code takes
+// the resolved `Sodium` instance as a parameter (it never re-imports the module),
+// which keeps the crypto functions pure and synchronous past this seam.
+const libsodium_wrappers_1 = __importDefault(require("libsodium-wrappers"));
+/** Await the WASM init (idempotent) and return the ready libsodium instance. */
+async function ready() {
+    await libsodium_wrappers_1.default.ready;
+    return libsodium_wrappers_1.default;
+}

package/dist/agent-peer.js

@@ -36,9 +36,13 @@ async function upsertAgentPeer(store, input) {
         trustLevel,
         kind: "agent",
         agentMeta: {
+            // `...baseMeta` already carries any existing top-level `mailbox`; an explicit
+            // `input.mailbox` overrides it below. Mailbox is top-level on AgentMeta since
+            // the phase-8 demote (was nested under `a2a` in alpha.4).
             ...baseMeta,
             bundleName: baseMeta.bundleName || bundleName || name,
-            a2a: { ...(a2a ?? {}), agentId, ...(input.mailbox ? { mailbox: input.mailbox } : {}) },
+            a2a: { ...(a2a ?? {}), agentId },
+            ...(input.mailbox ? { mailbox: input.mailbox } : {}),
         },
         externalIds: [
             ...(existing?.externalIds.filter((id) => !(id.provider === "a2a-agent" && id.externalId === agentId)) ?? []),

package/dist/{a2a → mailbox}/index.js

@@ -6,7 +6,13 @@ exports.compareReady = compareReady;
 exports.readIncoming = readIncoming;
 exports.isSeen = isSeen;
 exports.markSeen = markSeen;
-// src/a2a — the pure git-mailbox format/routing/dedup library (brick two).
+// src/mailbox — the pure git-mailbox format/routing/dedup library (the demoted
+// offline/no-endpoint FALLBACK transport, NOT the primary A2A path).
+//
+// Real A2A (`message/send` + the friends E2E sign-then-seal overlay — see
+// src/a2a-client/) is the PRIMARY cross-agent transport. This git-mailbox
+// survives only as a clearly-labelled fallback for peers with no reachable
+// endpoint and no relay; a host opts into it explicitly.
 //
 // A consumer agent and a producer agent that authenticate as two DISTINCT git
 // identities share a dedicated PRIVATE mailbox repo. This module computes the
@@ -17,8 +23,9 @@ exports.markSeen = markSeen;
 //   • NO fs / net / http / child_process / process.env / git anywhere — the wire
 //     (clone / pull / add / commit / push) is entirely the caller's job.
 // Type-only imports of `ProfileShareEnvelope` (../share) + `MissionShareEnvelope`
-// (../mission-share) carry no runtime edge. Both are CORE modules, so the a2a→core
-// import direction is eslint-legal (a2a may import core; the reverse is forbidden).
+// (../mission-share) carry no runtime edge. Both are CORE modules, so the
+// mailbox→core import direction is eslint-legal (mailbox may import core; the
+// reverse is forbidden).
 //
 // Security model (the git-native TOFU): addressing lives in the PATH, and a
 // single-writer-per-outbox-dir layout means a forged sender can't write into

package/dist/store-file.d.ts

@@ -12,9 +12,13 @@ export declare class FileFriendStore implements FriendStore {
     private normalize;
     private normalizeAgentMeta;
     private normalizeA2AMeta;
-    /** Preserve an additive a2a.mailbox coord only when both fields are strings;
-     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). */
+    /** Preserve the top-level mailbox coord only when both fields are strings;
+     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). Also used to
+     * migrate a legacy nested `a2a.mailbox`. */
     private normalizeMailbox;
+    /** Preserve an additive a2a.relay coord only when both fields are strings;
+     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). */
+    private normalizeRelay;
     private readJson;
     private writeJson;
     private removeFile;