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

package/README.md

@@ -63,11 +63,13 @@ knowledge is **structurally inviolable** and trust is **non-transitive**: an imp
 attributed, quarantined note, but it can never change who you trust. (See
 [Trust & consent model](#trust--consent-model).)
 
-### 2. Connectivity — the git-backed A2A transport
+### 2. Connectivity — the git-backed mailbox fallback
 
-How two agents actually reach each other, without a server in the middle.
+How two agents actually reach each other, without a server in the middle. (This git-mailbox is the
+demoted **offline/no-endpoint fallback** — real A2A + the friends E2E overlay is the primary path;
+see `@ouro.bot/friends/a2a-client`.)
 
-The optional `@ouro.bot/friends/a2a` sub-export is a **pure git-mailbox transport**: zero runtime
+The optional `@ouro.bot/friends/mailbox` sub-export is a **pure git-mailbox transport**: zero runtime
 dependencies, and it does **no git or network itself**. The host does every git op (clone / pull /
 add / commit / push); the library only **computes a message file's path + bytes** and
 **parses / validates / orders / dedups** the files the host hands back. Two agents authenticate as
@@ -77,6 +79,53 @@ own outbox.
 The mailbox is treated as **untrusted infrastructure**: a hostile mailbox can only **deny or
 replay** — never **escalate** — because an import never touches first-party notes or trust.
 
+### 2b. The primary transport — real A2A + an end-to-end security overlay
+
+The **`@ouro.bot/friends/a2a-client`** sub-export is the host-side adapter that makes friends agents
+speak the **real A2A (Agent2Agent) standard** — `message/send`, agent cards at a well-known URL, a
+single structured `DataPart` per envelope — and adds the **end-to-end security overlay** that keeps
+the wire safe even when a relay sits in the middle. It is the only part of the package that has a
+runtime dependency (`libsodium-wrappers`); the core stays zero-dep and transport-agnostic.
+
+A friends exchange is one A2A message whose DataPart carries a **sealed envelope**. Before it ever
+hits the wire, the envelope is:
+
+- **signed** by the sender — Ed25519 over the [RFC 8785 JCS](https://www.rfc-editor.org/rfc/rfc8785)
+  canonical bytes, carried in the envelope's reserved `proof` slot; and
+- **sealed** to the recipient — XChaCha20-Poly1305 AEAD over an ephemeral X25519 ECDH key, with the
+  **recipient's DID bound into the AEAD associated-data** so a blob cannot be re-targeted.
+
+The signature lives **inside** the ciphertext (sign-then-seal), so a relay never even learns who
+signed. Cryptographic identity is **`did:key`** (zero-infra — the agent's DID *is* its Ed25519 key,
+and the X25519 keyAgreement key is derived from it) or **`did:web`** (resolved behind an injectable
+hook). Identity is `agentId === did`, pinned trust-on-first-use, with **trust-tiered key rotation**
+(a family/friend peer may present a *signed* successor proof; acquaintances/strangers re-confirm out
+of band).
+
+**The friends relay (`ourostack/friends-relay`)** is the friends-family communication layer for any
+agent using the friends library — a relay (agents with no reachable endpoint register; it forwards
+A2A messages) plus a directory (discovery). It is built and deployed as a separate component from
+this store-only library, and it is **UNTRUSTED INFRASTRUCTURE by design**: standard A2A is TLS-only
+and terminates at the server, so a plain A2A relay would read every payload. The friends overlay
+closes exactly that gap. The relay carries **ciphertext and a routing handle and nothing else** — it
+can never **read**, **forge**, **tamper**, **re-target**, **replay-to-effect**, or **escalate**. The
+only residual it has is the ability to **deny, delay, or observe handle-level metadata**.
+
+That claim is not a promise — it is a **proof**. `examples/cross-agent-a2a-relay.ts` stands up a
+deliberately-malicious in-process relay and asserts all eight properties hold against real
+libsodium crypto:
+
+```
+npm run example:cross-agent-a2a-relay      # the malicious-relay proof: 8 hard assertions —
+                                           #   ciphertext-only, can't-forge/tamper/re-target,
+                                           #   replay-inert, moat-invariants, direct-equivalence,
+                                           #   reachability ladder (direct → relay → mailbox → none)
+```
+
+Reachability is a deterministic ladder: a directly-reachable **A2A endpoint** first, else the
+**relay**, else the **git-mailbox fallback** (§2), else **unreachable**. The *same* sealed envelope
+rides every rung — the security never depends on which path it took.
+
 ### 3. Shared memory — the mission ledger
 
 What two agents collectively *learned* doing work together.
@@ -413,7 +462,7 @@ network.
 ```sh
 npm run example:cross-agent-moat            # identity join key + consent-gated profile share,
                                             #   first-party-inviolable, trust non-transitive
-npm run example:a2a-git-mailbox             # the git-mailbox transport: path-binding, replay-safety,
+npm run example:mailbox-fallback            # the git-mailbox FALLBACK: path-binding, replay-safety,
                                             #   spoof rejection, hostile-mailbox tamper
 npm run example:cross-agent-mission-memory  # the mission ledger: shareable vs private learnings,
                                             #   first-party-wins, status non-transitive
@@ -454,7 +503,7 @@ setNervesEmitter((event) => {
 
 - **Store-only, transport-agnostic, additive.** The five layers were each built as a minimal
   primitive that does not modify the layers beneath it. The cross-agent envelopes are plain data; the
-  wire is always the caller's job (the `./a2a` mailbox is one optional, host-driven choice). A
+  wire is always the caller's job (the `./mailbox` git-mailbox is one optional, host-driven fallback). A
   CI-enforced dependency rule keeps the core from ever importing the transport.
 - **One persisted schema, additively grown.** Records are `schemaVersion: 1`; every layer added
   optional fields and sibling collections rather than changing existing meaning, so older data reads
@@ -486,7 +535,13 @@ setNervesEmitter((event) => {
 `ImportMissionShareResult`, `ImportMissionShareStatus`, `CoordinationEnvelope`,
 `PrepareCoordinationInput`, `PrepareCoordinationResult`, `PrepareCoordinationStatus`,
 `ImportCoordinationInput`, `ImportCoordinationOptions`, `ImportCoordinationResult`,
-`ImportCoordinationStatus`.
+`ImportCoordinationStatus`, `SetFriendTrustContext`, `AuditSink`, `ControlPlaneAuditRecord`,
+`ResolvedAgentIdentity`, `RosterStore`, `AccountRoster`, `RosterPin`, `RosterVerifier`,
+`AccountMembershipDecision`, `AccountMembershipResult`, `EvaluateAccountMembershipInput`,
+`FriendResolverRosterContext`. (`TrustBasis` additively gains the `"same_account"` member — the basis
+for family granted via the signed account roster — and `AgentMeta` additively gains an optional
+`identity { did, pinnedKey?, handle?, pinnedAt? }` durable-identity home; both are schemaVersion-1
+additive, and a legacy `a2a.did` migrates-on-read into `identity.did`.)
 
 **Values:** `TRUSTED_LEVELS`, `IDENTITY_SCOPES`, `isTrustedLevel`, `isIdentityProvider`,
 `isIntegration`, `isShareScope`, `isCoordinationIntent`, `FileFriendStore`, `FileGrantStore`,
@@ -499,16 +554,32 @@ setNervesEmitter((event) => {
 `trustImpliedPolicy`, `tieredPolicy`, `DEFAULT_CONSENT_POLICY`, `tofuVerifier`,
 `DEFAULT_AGENT_VERIFIER`, `prepareProfileShare`, `importProfileShare`, `prepareMissionShare`,
 `importMissionShare`, `prepareCoordination`, `importCoordination`, `grantShare`, `revokeShare`,
-`listShares`, `isGrantEffective`, `setNervesEmitter`, `emitNervesEvent`.
+`listShares`, `isGrantEffective`, `setNervesEmitter`, `emitNervesEvent`, `resolveAgentIdentity`,
+`withMigratedIdentity`, `findFriendByDid`, `MemoryAuditSink`, `FileAuditSink`, `auditPathFor`,
+`FileRosterStore`, `rostersDirFor`, `MemoryRosterStore`, `identityRosterVerifier`,
+`DEFAULT_ROSTER_VERIFIER`, `evaluateAccountMembership`.
 
 **From `@ouro.bot/friends/mcp`:** `createFriendsMcpServer`, `getToolSchemas`, `runMain` (plus the
 `McpToolSchema`, `FriendsMcpServer`, and `RunMainIo` types).
 
-**From `@ouro.bot/friends/a2a`:** `buildOutgoing`, `readIncoming`, `markSeen`, `isSeen`,
+**From `@ouro.bot/friends/mailbox`:** `buildOutgoing`, `readIncoming`, `markSeen`, `isSeen`,
 `compareReady`, `MAILBOX_VERSION` (plus the `MailboxMessage`, `BuildOutgoingInput`,
 `BuildOutgoingResult`, `IncomingFile`, `IncomingMessage`, `ReadIncomingInput`, `ReadIncomingResult`,
 `RejectedMessage`, `SeenLedger` types).
 
+**From `@ouro.bot/friends/a2a-client`** (the real-A2A adapter + the E2E overlay): `sendShare`,
+`receiveShare`, `resolveReachability`; `sealEnvelope` / `openSealedEnvelope`; `wrapInDataPart` /
+`unwrapDataPart`; `buildFriendsAgentCard`; `DidVerifier`, `evaluateRotation`, `signSuccessor`,
+`verifyCardDidBinding`, `pinOnFirstContact` / `isPinned` / `getPinned`, `MemoryPinStore`; the
+identity helpers `parseDidKey` / `keyAgreementFromDidKey` / `didKeyIdentityFromEd25519` /
+`ed25519PubToDidKey` and `didWebToUrl` / `resolveDidWeb` / `parseDidDocument`; the primitives
+`sealTo` / `openSealed`, `signEnvelope` / `verifyEnvelopeSignature`, `jcsString` / `jcsBytes`, and
+the `ready` init seam; and the account-roster Ed25519 verify `ed25519RosterVerifier` / `signRoster`
+(the crypto implementation of the core `RosterVerifier` seam — host-injected, so the core stays
+transport-free) (plus the `A2ATransport`, `DidResolution`, `SealedEnvelope`, `StructuredProof`,
+`ReachabilityPlan`, `FriendsAgentCard`, `DidKeyIdentity`, `DidDocument` types). The transports
+(direct A2A / relay / git op) are injected by the host — this module does no network or git itself.
+
 ## License
 
 [Apache-2.0](./LICENSE)

package/changelog.json

@@ -1,5 +1,17 @@
 {
   "versions": [
+    {
+      "version": "0.1.0-alpha.6",
+      "changes": [
+        "p11 increment 1 — own-fleet foundation. Bug A: cold A2A contact defaults to stranger (safe-by-default; explicit owner-initiated trustLevel still wins). Bug B: append-only control-plane audit (AuditSink + MemoryAuditSink/FileAuditSink) on every setFriendTrust, now wired into the live MCP dispatch path (set_trust + the onboard_agent trust seat) via openFileBundle's FileAuditSink, attributed to the owner-only stdio boundary. Bug C: FriendResolver is roster-aware — a key-verified member of the pinned account roster is recognized as family across OS users, without loosening the cold-A2A stranger default. DID re-key (additive, schemaVersion still 1): AgentMeta.identity durable home with a2a.did migrate-on-read; did-aware findFriendByDid. Account roster: RosterStore/FileRosterStore/MemoryRosterStore + the RosterVerifier seam (core identity-only default; a2a-client ed25519RosterVerifier Ed25519 impl) granting family via a new same_account TrustBasis only to a TOFU-pinned, key-verified roster member (changed roster key hard-fails). Security hardening of the trust primitives: the family-grant path FAILS CLOSED — the identity-only default can never grant family (only a cryptographic verifier can, gated by a grantsFamily capability), with a loud one-time warning; evaluateAccountMembership requires an unforgeable VerifiedCandidate so the did-control precondition can't be skipped; findFriendByDid rejects falsy-did queries and no longer rewards back-dating on a duplicate-did anomaly (prefers the pinned record, warns); empty-string DIDs are never matchable keys; and FileRosterStore guards accountId against path traversal. Core remains transport-free (the CI core⊥a2a-client dependency rule is unmodified)."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.5",
+      "changes": [
+        "a2a-client sub-export: real A2A + E2E sign-then-seal overlay (libsodium), did:key/did:web identity, untrusted-relay-safe; git-mailbox demoted to ./mailbox fallback"
+      ]
+    },
     {
       "version": "0.1.0-alpha.4",
       "changes": [

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

@@ -0,0 +1,39 @@
+import type { SealedBlob } from "./seal";
+/** The opaque payload carried in the A2A DataPart `data`. Nothing here reveals the
+ * sender, the content, or the friends kind. */
+export interface FriendsDataPartPayload {
+    v: number;
+    sealed: SealedBlob;
+    recipientDid: string;
+}
+/** An A2A Part (only the `data` kind is used by friends). */
+export interface A2ADataPart {
+    kind: "data";
+    data: FriendsDataPartPayload;
+}
+/** An A2A Message carrying exactly one friends DataPart. */
+export interface A2AMessage {
+    messageId: string;
+    role: "agent";
+    parts: A2ADataPart[];
+}
+/** The `SealedEnvelope` shape (re-declared minimally to avoid a cycle; the full
+ * type lives in sealed-envelope.ts). */
+interface SealedEnvelopeLike {
+    v: number;
+    sealed: SealedBlob;
+}
+export interface WrapInDataPartInput {
+    sealedEnvelope: SealedEnvelopeLike;
+    recipientDid: string;
+    v?: number;
+}
+/** Wrap a SealedEnvelope into an A2A Message with one relay-blind DataPart. No
+ * `metadata["ouro.friends/kind"]` hint (omitted by default — §3.5); no
+ * `friendsKind` on the wire. */
+export declare function wrapInDataPart(input: WrapInDataPartInput): A2AMessage;
+/** Extract + validate the single friends DataPart. Returns null on any malformed
+ * shape: wrong part count (≠1), non-data kind, or a missing/ill-typed
+ * sealed/recipientDid/v. */
+export declare function unwrapDataPart(msg: A2AMessage): FriendsDataPartPayload | null;
+export {};

package/dist/a2a-client/a2a-message.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapInDataPart = wrapInDataPart;
+exports.unwrapDataPart = unwrapDataPart;
+// A2A DataPart mapping — a friends exchange = one A2A `message/send` whose Message
+// carries ONE DataPart. The DataPart `data` is RELAY-BLIND: it carries only the
+// routing-necessary `{ v, sealed, recipientDid }`. `friendsKind` travels INSIDE the
+// sealed plaintext (see sealed-envelope.ts) — the relay never learns the friends
+// taxonomy. `recipientDid` is unavoidable (it is the AD-reconstruction target AND
+// the relay's routing handle — the relay sees the recipient regardless).
+const node_crypto_1 = require("node:crypto");
+/** Wrap a SealedEnvelope into an A2A Message with one relay-blind DataPart. No
+ * `metadata["ouro.friends/kind"]` hint (omitted by default — §3.5); no
+ * `friendsKind` on the wire. */
+function wrapInDataPart(input) {
+    const v = input.v ?? input.sealedEnvelope.v;
+    return {
+        messageId: (0, node_crypto_1.randomUUID)(),
+        role: "agent",
+        parts: [{ kind: "data", data: { v, sealed: input.sealedEnvelope.sealed, recipientDid: input.recipientDid } }],
+    };
+}
+/** Extract + validate the single friends DataPart. Returns null on any malformed
+ * shape: wrong part count (≠1), non-data kind, or a missing/ill-typed
+ * sealed/recipientDid/v. */
+function unwrapDataPart(msg) {
+    if (!msg || typeof msg !== "object")
+        return null;
+    const parts = msg.parts;
+    if (!Array.isArray(parts) || parts.length !== 1)
+        return null;
+    const part = parts[0];
+    if (!part || typeof part !== "object" || part.kind !== "data")
+        return null;
+    const data = part.data;
+    if (!data || typeof data !== "object")
+        return null;
+    if (typeof data.recipientDid !== "string")
+        return null;
+    if (typeof data.v !== "number")
+        return null;
+    if (!isSealedBlob(data.sealed))
+        return null;
+    return { v: data.v, sealed: data.sealed, recipientDid: data.recipientDid };
+}
+function isSealedBlob(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const b = value;
+    return (typeof b.v === "number" &&
+        typeof b.ePk === "string" &&
+        typeof b.n === "string" &&
+        typeof b.ct === "string");
+}

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

@@ -0,0 +1,97 @@
+import type { FriendStore } from "../store";
+import type { MissionStore } from "../mission-store";
+import type { TrustLevel } from "../types";
+import type { PinStore } from "./did-verifier";
+import type { A2AMessage } from "./a2a-message";
+import type { FriendsKind, FromIdentity, RecipientIdentity } from "./sealed-envelope";
+import type { Sodium } from "./sodium";
+/** An injectable A2A transport: deliver one A2A message to a target. Direct + relay
+ * are both "send an A2A message"; the proof's relay stub implements this maliciously.
+ */
+export interface A2ATransport {
+    send(target: {
+        rung: "direct" | "relay" | "mailbox";
+        address: string;
+    }, message: A2AMessage): Promise<void>;
+}
+/** The async DID resolve + pin step (wraps did:key / did:web + TOFU + binding). It
+ * runs BEFORE the importer so the verifier handed to the importer is pure-sync. */
+export interface DidResolution {
+    /** Resolve `did` to its pinned Ed25519 (+ optionally X25519) key material,
+     * pinning on first contact and verifying against the pin thereafter. Returns
+     * null on an unresolvable / failed-binding / failed-rotation DID. */
+    resolveAndPin(input: {
+        fromAgentId: string;
+        did: string;
+        pinStore: PinStore;
+        trustOfSource: TrustLevel;
+    }): Promise<{
+        ed25519Pub: Uint8Array;
+    } | null>;
+}
+export type SendShareResult = {
+    ok: true;
+    rung: "direct" | "relay" | "mailbox";
+    message: A2AMessage;
+} | {
+    ok: false;
+    reason: "unreachable" | "resolve_failed";
+};
+export interface SendShareInput {
+    sodium: Sodium;
+    transport: A2ATransport;
+    fromIdentity: FromIdentity;
+    /** The recipient peer's coords. */
+    toPeer: {
+        a2a?: {
+            endpointUrl?: string;
+            relay?: {
+                url: string;
+                handle: string;
+            };
+            did?: string;
+        };
+        mailbox?: {
+            repo: string;
+            selfOutboxAgentId: string;
+        };
+    };
+    recipientDid: string;
+    recipientX25519Pub: Uint8Array;
+    plaintextEnvelope: Record<string, unknown>;
+    friendsKind: FriendsKind;
+}
+/** Seal+sign a friends envelope and deliver it over the resolved rung. The SAME
+ * SealedEnvelope is built regardless of rung (direct/relay/mailbox) — only the
+ * transport target differs. */
+export declare function sendShare(input: SendShareInput): Promise<SendShareResult>;
+/** A2A TaskState mapping for an inbound share. `completed` carries the importer
+ * status; `rejected` carries the reason code. */
+export type ReceiveShareResult = {
+    state: "completed";
+    friendsKind: FriendsKind;
+    status: string;
+} | {
+    state: "rejected";
+    reason: "malformed_message" | "unseal_failed" | "recipient_mismatch" | "malformed_plaintext" | "sender_binding_mismatch" | "resolve_failed" | "replayed" | "untrusted_source" | "import_failed";
+};
+export interface SeenLedgerLike {
+    isSeen(nonce: string): boolean;
+    markSeen(nonce: string): void;
+}
+export interface ReceiveShareInput {
+    sodium: Sodium;
+    store: FriendStore;
+    missionStore: MissionStore;
+    pinStore: PinStore;
+    didResolution: DidResolution;
+    seen: SeenLedgerLike;
+    a2aMessage: A2AMessage;
+    recipientDid: string;
+    recipientIdentity: RecipientIdentity;
+    trustOfSource: TrustLevel;
+}
+/** Receive a sealed A2A message: unwrap → unseal → resolve+pin the SENDER → build a
+ * sync DidVerifier → branch on the (unsealed) friendsKind → call the UNCHANGED
+ * importer → map to A2A TaskState. Replay is deduped on the seal nonce. */
+export declare function receiveShare(input: ReceiveShareInput): Promise<ReceiveShareResult>;

package/dist/a2a-client/adapter.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendShare = sendShare;
+exports.receiveShare = receiveShare;
+// adapter — the host-side send/receive that ties everything together. Transports
+// are INJECTABLE (no real HTTP/git in this module; the host supplies them; the
+// malicious-relay proof supplies a hostile stub). The async DID resolve + pin runs
+// BEFORE the (sync) core importer, so the importer's verifier stays sync.
+const coordination_1 = require("../coordination");
+const mission_share_1 = require("../mission-share");
+const share_1 = require("../share");
+const did_verifier_1 = require("./did-verifier");
+const a2a_message_1 = require("./a2a-message");
+const reachability_1 = require("./reachability");
+const sealed_envelope_1 = require("./sealed-envelope");
+/** Seal+sign a friends envelope and deliver it over the resolved rung. The SAME
+ * SealedEnvelope is built regardless of rung (direct/relay/mailbox) — only the
+ * transport target differs. */
+async function sendShare(input) {
+    const plan = (0, reachability_1.resolveReachability)(input.toPeer.a2a, input.toPeer.mailbox);
+    if (plan.rung === "unreachable") {
+        return { ok: false, reason: "unreachable" };
+    }
+    const sealed = (0, sealed_envelope_1.sealEnvelope)({
+        sodium: input.sodium,
+        envelope: input.plaintextEnvelope,
+        friendsKind: input.friendsKind,
+        fromIdentity: input.fromIdentity,
+        recipientDid: input.recipientDid,
+        recipientX25519Pub: input.recipientX25519Pub,
+    });
+    const message = (0, a2a_message_1.wrapInDataPart)({ sealedEnvelope: sealed, recipientDid: input.recipientDid });
+    const address = plan.rung === "direct" ? plan.endpointUrl : plan.rung === "relay" ? plan.relay.handle : plan.mailbox.repo;
+    await input.transport.send({ rung: plan.rung, address }, message);
+    return { ok: true, rung: plan.rung, message };
+}
+/** Receive a sealed A2A message: unwrap → unseal → resolve+pin the SENDER → build a
+ * sync DidVerifier → branch on the (unsealed) friendsKind → call the UNCHANGED
+ * importer → map to A2A TaskState. Replay is deduped on the seal nonce. */
+async function receiveShare(input) {
+    const payload = (0, a2a_message_1.unwrapDataPart)(input.a2aMessage);
+    if (!payload)
+        return { state: "rejected", reason: "malformed_message" };
+    // Replay dedup BEFORE any state change, keyed on the seal nonce.
+    if (input.seen.isSeen(payload.sealed.n)) {
+        return { state: "rejected", reason: "replayed" };
+    }
+    const opened = (0, sealed_envelope_1.openSealedEnvelope)({
+        sodium: input.sodium,
+        sealedEnvelope: { v: payload.v, sealed: payload.sealed },
+        recipientDid: input.recipientDid,
+        recipientIdentity: input.recipientIdentity,
+    });
+    if (!opened.ok) {
+        // unseal_failed / malformed_plaintext / recipient_mismatch map 1:1.
+        return { state: "rejected", reason: opened.error };
+    }
+    // SECURITY (binding): the trustworthy sender identity is `opened.fromAgentId` —
+    // it lives INSIDE the signed envelope bytes, so it is authentic once the
+    // signature verifies. `opened.signerDid` comes from the OUTER, UNSIGNED sealed
+    // plaintext and is ADVISORY only. We pin/verify/route on the SIGNED
+    // `fromAgentId`, and require the advisory `signerDid` to match it (a divergence
+    // is a malformed/spoofed bundle). The real gate remains DidVerifier: the pinned
+    // key (keyed to `fromAgentId`) must have signed THIS envelope.
+    const senderDid = opened.fromAgentId;
+    if (senderDid.length === 0 || opened.signerDid !== senderDid) {
+        return { state: "rejected", reason: "sender_binding_mismatch" };
+    }
+    // Resolve + pin the SENDER's DID (async — BEFORE the sync importer/verifier).
+    const resolved = await input.didResolution.resolveAndPin({
+        fromAgentId: senderDid,
+        did: senderDid,
+        pinStore: input.pinStore,
+        trustOfSource: input.trustOfSource,
+    });
+    if (!resolved)
+        return { state: "rejected", reason: "resolve_failed" };
+    // Build the sync verifier bound to THIS envelope + the pinned sender key.
+    const verifier = new did_verifier_1.DidVerifier({
+        sodium: input.sodium,
+        pinnedEd25519Pub: resolved.ed25519Pub,
+        pinnedDid: senderDid,
+        envelope: opened.envelope,
+    });
+    // Mark seen now (idempotent imports + the replay guard above keep this safe).
+    input.seen.markSeen(payload.sealed.n);
+    // Branch on the unsealed friendsKind → the UNCHANGED importer. fromAgentId is the
+    // SIGNED sender DID, so the verifier's binding (proof.signerDid === fromAgentId
+    // === pinnedDid) anchors on authentic, signature-covered material.
+    const fromAgentId = senderDid;
+    const importInput = { envelope: opened.envelope, fromAgentId, trustOfSource: input.trustOfSource };
+    if (opened.friendsKind === "profile_share") {
+        const r = await (0, share_1.importProfileShare)(input.store, importInput, { verifier });
+        return mapImport(r, opened.friendsKind);
+    }
+    if (opened.friendsKind === "mission_share") {
+        const r = await (0, mission_share_1.importMissionShare)(input.missionStore, importInput, { verifier });
+        return mapImport(r, opened.friendsKind);
+    }
+    const r = await (0, coordination_1.importCoordination)(input.missionStore, importInput, { verifier });
+    return mapImport(r, opened.friendsKind);
+}
+/** Map an importer result to the A2A TaskState shape. */
+function mapImport(r, friendsKind) {
+    if (r.ok) {
+        return { state: "completed", friendsKind, status: r.status };
+    }
+    // The importer returns `untrusted_source` when the verifier fails (forge) OR the
+    // trust cap is too low (stranger) — both map to the A2A `rejected` taxonomy.
+    if (r.status === "untrusted_source") {
+        return { state: "rejected", reason: "untrusted_source" };
+    }
+    return { state: "rejected", reason: "import_failed" };
+}

package/dist/a2a-client/agent-card.d.ts

@@ -0,0 +1,50 @@
+import type { FriendsKind } from "./sealed-envelope";
+/** A single A2A skill descriptor. */
+export interface A2ASkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+}
+/** The A2A capabilities block. */
+export interface A2ACapabilities {
+    streaming: boolean;
+    pushNotifications: boolean;
+}
+/** The friends agent card (the A2A card + the friends overlay). */
+export interface FriendsAgentCard {
+    name: string;
+    description: string;
+    url: string;
+    version: string;
+    protocolVersion: string;
+    capabilities: A2ACapabilities;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: A2ASkill[];
+    /** No transport security scheme for the local proof (the E2E overlay is the
+     * real security; transport authn is host-config). */
+    securitySchemes: Record<string, never>;
+    security: never[];
+    /** The friends overlay binding: the agent's DID (== its agentId). */
+    did: string;
+    /** The friends extension: advertises the relay handle when the agent is reached
+     * via a relay. Absent when the agent has a direct endpoint. */
+    ouroRelay?: {
+        handle: string;
+    };
+}
+export interface BuildFriendsAgentCardInput {
+    name: string;
+    url: string;
+    version: string;
+    protocolVersion: string;
+    did: string;
+    description?: string;
+    relayHandle?: string;
+}
+/** Build a minimal friends agent card. The relay handle is advertised only when
+ * supplied. */
+export declare function buildFriendsAgentCard(input: BuildFriendsAgentCardInput): FriendsAgentCard;
+/** Re-export the friendsKind type for convenience (it is NOT placed on the card). */
+export type { FriendsKind };

package/dist/a2a-client/agent-card.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFriendsAgentCard = buildFriendsAgentCard;
+/** The friends-exchange skill IDs are part of the public surface; the friends
+ * KIND taxonomy is intentionally NOT exposed (only this single skill). */
+const FRIENDS_EXCHANGE_SKILL = {
+    id: "friends-exchange",
+    // Deliberately generic: the friends KIND taxonomy is never spelled out on the
+    // card (metadata-minimization — a directory/relay learns no friends internals).
+    name: "friends exchange",
+    description: "Exchange consent-gated friends envelopes over an end-to-end sign-then-seal overlay.",
+    tags: ["friends", "a2a", "e2e"],
+};
+/** Build a minimal friends agent card. The relay handle is advertised only when
+ * supplied. */
+function buildFriendsAgentCard(input) {
+    return {
+        name: input.name,
+        description: input.description ?? "A friends-using agent (A2A + the friends E2E overlay).",
+        url: input.url,
+        version: input.version,
+        protocolVersion: input.protocolVersion,
+        capabilities: { streaming: false, pushNotifications: false },
+        defaultInputModes: ["application/json"],
+        defaultOutputModes: ["application/json"],
+        skills: [FRIENDS_EXCHANGE_SKILL],
+        securitySchemes: {},
+        security: [],
+        did: input.did,
+        ...(input.relayHandle !== undefined ? { ouroRelay: { handle: input.relayHandle } } : {}),
+    };
+}

package/dist/a2a-client/did-key.d.ts

@@ -0,0 +1,38 @@
+import type { Sodium } from "./sodium";
+/** Encode bytes as base58btc (Bitcoin alphabet). */
+export declare function base58btcEncode(bytes: Uint8Array): string;
+/** Decode a base58btc string. Returns null on an invalid character. */
+export declare function base58btcDecode(str: string): Uint8Array | null;
+/** Parse a `did:key:z…` (Ed25519) into its 32-byte public key. Returns null on:
+ * wrong scheme, missing `z` multibase prefix, bad base58, wrong multicodec, or
+ * wrong key length. */
+export declare function parseDidKey(did: string): {
+    ed25519Pub: Uint8Array;
+} | null;
+/** Encode an Ed25519 public key as a `did:key:z…`. Throws on a wrong-length key
+ * (a guard — callers pass real 32-byte keys). */
+export declare function ed25519PubToDidKey(pub: Uint8Array): string;
+/** Derive the X25519 keyAgreement PUBLIC key from an Ed25519 public key. */
+export declare function keyAgreementFromDidKey(input: {
+    sodium: Sodium;
+    ed25519Pub: Uint8Array;
+}): Uint8Array;
+/** A self-contained did:key identity (signing + derived sealing keys). The keyId
+ * convention for did:key is `${did}#${zBase}` where the z-fragment repeats the
+ * did:key's multibase body (did:key is self-describing — the fragment IS the key).
+ */
+export interface DidKeyIdentity {
+    did: string;
+    ed25519Pub: Uint8Array;
+    ed25519Priv: Uint8Array;
+    x25519Pub: Uint8Array;
+    x25519Priv: Uint8Array;
+    keyId: string;
+}
+/** Build a did:key identity from an Ed25519 keypair (the signing + the derived
+ * X25519 keyAgreement keys). */
+export declare function didKeyIdentityFromEd25519(input: {
+    sodium: Sodium;
+    ed25519Pub: Uint8Array;
+    ed25519Priv: Uint8Array;
+}): DidKeyIdentity;