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

package/README.md

@@ -39,12 +39,12 @@ narrow:
 - **Bring your own storage.** The library never decides *where* or *how* your data lives — you
   pass a path (or a connection string) and, if you want, your own storage backend.
 
-It is built as **five additive capability layers**. Each is a minimal primitive on the one before
+It is built as **six additive capability layers**. Each is a minimal primitive on the one before
 it; none is a workflow engine; removing any layer leaves the ones beneath it unchanged.
 
 ---
 
-## What it does — the five capabilities
+## What it does — the six capabilities
 
 ### 1. Identity + the cross-agent moat
 
@@ -158,9 +158,29 @@ an assignee onto anyone (the receiver's own `accept` confirms it — non-transit
 advisory metadata rather than a granted capability, and conflicts resolve last-writer-wins by
 timestamp. No queue, no DAG, no workflow DSL.
 
+### 6. Own-fleet delegation — link your own agents, then delegate work end-to-end
+
+The control-plane thread: the owner can **link two of their own agents** and have one **delegate a
+task** to the other, get it done, and **receive the result back** — over the same consent-gated,
+trust-capped, first-party-inviolable machinery.
+
+`connect_to` is a first-class **management-sense** capability — the owner introduces a peer into an
+agent's fleet, but **only from a trusted control surface**: a `local` (owner-only) sense commits
+inline; an `open` sense never does (it downgrades to a confirm-prompt); a `closed` sense is gated by
+a **signed account-roster membership check** (same-account `family` via `same_account`), never a
+blanket allow. The link is recorded as an `action:"connect"` control-plane audit. A bare name with
+no resolvable handle is answered honestly (`needs_handle_or_introduction`) rather than invented.
+
+Delegation then rides the layers already here: a **task-spec** travels on a coordination `request`
+(correlated by a minted `requestId`), and the **result-return** (`send_result` / `import_result`)
+carries the actual produced **deliverable** back — attributed to the doer, correlated to the original
+delegation, landing **quarantined** in a separate namespace on import. A result for work you never
+delegated is rejected (`no_delegation`); a stranger's result is refused at the trust cap; first-party
+knowledge is never touched. It is a deliverable channel, **not a remote-exec grant**.
+
 > The stack, in one line: agents **recognize** each other (1), **reach** each other (2),
-> **remember** shared work (3), **assess** each other (4), and **negotiate** who does what (5) —
-> each a minimal primitive on the last.
+> **remember** shared work (3), **assess** each other (4), **negotiate** who does what (5), and the
+> owner **links their own agents to delegate end-to-end** (6) — each a minimal primitive on the last.
 
 ---
 
@@ -252,7 +272,7 @@ You can also `npm pack` then
 Content-Length and newline-delimited JSON — auto-detected from the first message, so it works with
 harnesses on either convention.
 
-#### The tool surface — 29 tools
+#### The tool surface — 32 tools
 
 A thin 1:1 mapping over the library (no domain logic in the server):
 
@@ -269,6 +289,7 @@ A thin 1:1 mapping over the library (no domain logic in the server):
 | `link_identity` | Link an external identity, merging any orphan record that holds it. |
 | `unlink_identity` | Remove an external identity from a friend. |
 | `onboard_agent` | Upsert an agent-peer record from resolved coordinates (no HTTP fetch). |
+| `connect_to` | **Control plane** — the owner links one of their OWN agents into the fleet (introduce a peer by agentId/did/name at a trust level, default `family`). Authority-gated to a management sense (`local` commits; an `open` sense downgrades to a confirm-prompt; `closed` is gated by a roster/membership check); a bare name with no resolvable handle/DID returns `needs_handle_or_introduction` (never fabricates). Writes an `action:"connect"` control-plane audit. |
 | `whoami` | Resolve the machine owner and which record represents the self. |
 | `channel_caps` | Return a channel's capabilities. |
 | `resolve_room` | Resolve a room (a group's external id) into its members, each with trust context and `knownVia`. |
@@ -287,13 +308,17 @@ A thin 1:1 mapping over the library (no domain logic in the server):
 | `coordinate` | **Producer** — prepare a coordination message (`request` / `offer` / `accept` / `decline` / `handoff`) that negotiates **who** does a mission. |
 | `import_coordination` | **Consumer** — import a coordination message (appends to the mission's coordination log; only a self-`accept` sets the assignee; a `handoff` never forces one). |
 | `get_coordination` | Read a mission's coordination state — its current assignee + the append-only negotiation log. |
+| `send_result` | **Producer** — return B's DELIVERABLE for a delegation, attributed to B + correlated to A's task-spec by `requestId`, named by the mission's `missionKey` (consent-gated via the `coordinate` scope). |
+| `import_result` | **Consumer** — import a result-return; lands B's deliverable quarantined + attributed under `importedResults`, trust-capped; a result whose `requestId` matches no prior first-party delegation is rejected (`no_delegation`); never recomputes status. |
 
 The consent tools (`share_profile` / `import_profile` / `grant_share` / `revoke_share` /
-`list_shares`) need a **grant store**; the mission and coordination tools need a **mission store**.
-The `friends-mcp` binary wires both automatically at sibling `_grants/` and `_missions/` directories
-under `--dir`. An embedded server gets them by passing `grants` / `missions` to
-`createFriendsMcpServer`. Without the relevant store, those tools report
-`{ ok: false, status: "unsupported" }` and everything else works store-only.
+`list_shares`) need a **grant store**; the mission, coordination, and result-return tools
+(`send_result` consumes both) need a **mission store**. The `friends-mcp` binary wires both
+automatically at sibling `_grants/` and `_missions/` directories under `--dir` (plus the
+`_audit/` control-plane log `connect_to` / `set_trust` write through). An embedded server gets
+them by passing `grants` / `missions` / `audit` to `createFriendsMcpServer`. Without the
+relevant store, those tools report `{ ok: false, status: "unsupported" }` and everything else
+works store-only.
 
 The server module is consumed in code from the `@ouro.bot/friends/mcp` subpath, exporting
 `createFriendsMcpServer`, `getToolSchemas`, and `runMain`.
@@ -470,6 +495,10 @@ npm run example:cross-agent-standing        # earned standing: first-party-only,
                                             #   inert on trust
 npm run example:cross-agent-coordination    # the five coordination verbs end-to-end: assignment,
                                             #   non-transitive handoff, last-writer-wins, seeding gate
+npm run example:cross-agent-delegation      # own-fleet delegation: two of the owner's agents,
+                                            #   same-account family (signed roster), connect_to link,
+                                            #   A delegates → B performs → B returns the result → A
+                                            #   imports it — every invariant hard-asserted
 ```
 
 Read them as the honest spec of what the package promises: if a guarantee weren't real, the
@@ -501,7 +530,7 @@ setNervesEmitter((event) => {
 
 ## Design notes & status
 
-- **Store-only, transport-agnostic, additive.** The five layers were each built as a minimal
+- **Store-only, transport-agnostic, additive.** The six 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 `./mailbox` git-mailbox is one optional, host-driven fallback). A
   CI-enforced dependency rule keeps the core from ever importing the transport.
@@ -510,8 +539,9 @@ setNervesEmitter((event) => {
   clean.
 - **Not a workflow engine.** Each layer deliberately refuses the larger machine it brushes against:
   the mission ledger is not a knowledge base, standing is not a reputation engine, coordination is not
-  a scheduler. The discipline is the point.
-- **Alpha.** The surface is feature-complete across the five layers but pre-1.0 — expect additive
+  a scheduler, and the delegation channel is a deliverable return — not a remote-exec grant. The
+  discipline is the point.
+- **Alpha.** The surface is feature-complete across the six layers but pre-1.0 — expect additive
   changes, and pin a version. Feedback and issues are welcome.
 
 ### Public API
@@ -535,7 +565,20 @@ 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`, `ConnectPeer`, `ConnectAgentsInput`, `ConnectAgentsDeps`,
+`ConnectResult`, `ConnectStatus`, `AuthorizeConnectInput`, `ConnectAuthorization`, `MissionTaskSpec`,
+`MissionResult`, `MissionResultEnvelope`, `PrepareMissionResultInput`, `PrepareMissionResultResult`,
+`PrepareMissionResultStatus`, `ImportMissionResultInput`, `ImportMissionResultOptions`,
+`ImportMissionResultResult`, `ImportMissionResultStatus`. (`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`.
+`MissionRecord` additively gains the own-fleet delegation namespaces `delegations` / `importedDelegations`
+(gap-1) and `results` / `importedResults` (gap-2), and `ControlPlaneAuditRecord.action` widens additively
+to `"set_trust" | "connect"`.)
 
 **Values:** `TRUSTED_LEVELS`, `IDENTITY_SCOPES`, `isTrustedLevel`, `isIdentityProvider`,
 `isIntegration`, `isShareScope`, `isCoordinationIntent`, `FileFriendStore`, `FileGrantStore`,
@@ -548,7 +591,11 @@ 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`, `connectAgents`, `authorizeConnect`,
+`prepareMissionResult`, `importMissionResult`.
 
 **From `@ouro.bot/friends/mcp`:** `createFriendsMcpServer`, `getToolSchemas`, `runMain` (plus the
 `McpToolSchema`, `FriendsMcpServer`, and `RunMainIo` types).
@@ -565,7 +612,9 @@ setNervesEmitter((event) => {
 identity helpers `parseDidKey` / `keyAgreementFromDidKey` / `didKeyIdentityFromEd25519` /
 `ed25519PubToDidKey` and `didWebToUrl` / `resolveDidWeb` / `parseDidDocument`; the primitives
 `sealTo` / `openSealed`, `signEnvelope` / `verifyEnvelopeSignature`, `jcsString` / `jcsBytes`, and
-the `ready` init seam (plus the `A2ATransport`, `DidResolution`, `SealedEnvelope`, `StructuredProof`,
+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.
 

package/changelog.json

@@ -1,5 +1,17 @@
 {
   "versions": [
+    {
+      "version": "0.1.0-alpha.7",
+      "changes": [
+        "p11 increment 2 — own-fleet delegation: connect_to control plane + the LOCAL delegate->perform->return proof (task-spec + result-return). Brick 8 (greenfield): connectAgents + a NEW management-sense authority predicate (authorizeConnect) — the owner links one of their own agents into the fleet, gated to a management sense (local commits inline; an open sense downgrades to a confirm-prompt; closed is gated by a signed account-roster membership check, NEVER a blanket allow), with disambiguation honesty (a bare name with no resolvable handle/DID returns needs_handle_or_introduction, never fabricated). connect_to is a library fn + an MCP tool, writes an action:\"connect\" control-plane audit (ControlPlaneAuditRecord.action widens additively to \"set_trust\" | \"connect\"), and the MCP boundary maps the stdio origin to a local management senseType (a network transport passes its real senseType + a pre-computed roster membership). gap-1 (the task-spec): CoordinationEnvelope gains an optional task? (MissionTaskSpec with a minted requestId) on the delegation request — recorded first-party under MissionRecord.delegations[requestId], imported quarantined under importedDelegations[agentId][requestId] (trust-capped, non-transitive, first-party-inviolable). gap-2 (the result-return): a NEW prepareMissionResult/importMissionResult envelope (twin of mission-share, NOT a reuse) carries B's actual DELIVERABLE back to A — attributed to B, correlated by missionKey + requestId, consent-gated via the existing \"coordinate\" scope (no new ShareScope); on import it lands quarantined + attributed under importedResults, rejects a result whose requestId matches no prior first-party delegation (no_delegation — correlation honesty), rejects a result whose source is not the agent the work was delegated TO (assignee_mismatch — assignee honesty; the delegation now persists its assignee and the import enforces source === assignee, failing closed on a legacy assignee-less record), never seeds a mission (no_mission), is trust-capped (untrusted_source before correlation), non-transitive, idempotent on replay. The mailbox kind union widens additively to carry kind:\"mission_result\". 3 new MCP tools (connect_to, send_result, import_result) — 29 -> 32; the coordinate tool now threads the task-spec. FileMissionStore.normalize round-trips the four new additive MissionRecord namespaces (delegations/importedDelegations/results/importedResults). A LOCAL hermetic proof (examples/cross-agent-delegation.ts): two own-fleet agents on separate stores, recognized as same-account family via a signed roster (real ed25519) on both sides, linked by the owner via connect_to, then A delegates a task -> B performs it -> B returns the deliverable -> A imports it — every invariant hard-asserted (missionKey-not-UUID, first-party-inviolable, non-transitive, trust cap, orphan-reject, trusted-non-assignee-reject, replay-inert, no third-party leak); exit 0, with a negative control that bites. Security review (inc-2): finding 1 (MEDIUM, cross-delegation result injection) FIXED as above — a trusted peer that is not the assignee can no longer inject a forged result for a requestId delegated to a different agent; findings 2-3 (LOW, dormant networking pre-conditions) DOCUMENTED at the connect_to authority gate + introduce-default site (before any non-local/networked controlContext is wired, the connect commit must add target-side roster verification and validate the caller-supplied trustLevel against the authority decision); findings 4-5 (existence oracle, vestigial envelope.fromAgentId) accepted by-design (finding 5 noted at its site). Core stays transport-free (the core⊥a2a-client + mailbox⊥mcp CI rules unmodified); 100% coverage maintained."
+      ]
+    },
+    {
+      "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": [

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

@@ -19,5 +19,6 @@ export { buildFriendsAgentCard } from "./agent-card";
 export type { A2ACapabilities, A2ASkill, FriendsAgentCard } from "./agent-card";
 export { resolveReachability } from "./reachability";
 export type { ReachabilityPlan } from "./reachability";
+export { ed25519RosterVerifier, signRoster } from "./roster-verify";
 export { receiveShare, sendShare } from "./adapter";
 export type { A2ATransport, DidResolution, ReceiveShareInput, ReceiveShareResult, SeenLedgerLike, SendShareInput, SendShareResult, } from "./adapter";

package/dist/a2a-client/index.js

@@ -10,7 +10,7 @@
 // recipient DID bound into the AEAD AD), so a relay carries CIPHERTEXT ONLY — it
 // can never read, forge, tamper, re-target, replay-to-effect, or escalate.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendShare = exports.receiveShare = exports.resolveReachability = exports.buildFriendsAgentCard = exports.wrapInDataPart = exports.unwrapDataPart = exports.sealEnvelope = exports.openSealedEnvelope = exports.verifyCardDidBinding = exports.signSuccessor = exports.pinOnFirstContact = exports.MemoryPinStore = exports.isPinned = exports.getPinned = exports.evaluateRotation = exports.DidVerifier = exports.resolveDidWeb = exports.parseDidDocument = exports.didWebToUrl = exports.parseDidKey = exports.keyAgreementFromDidKey = exports.ed25519PubToDidKey = exports.didKeyIdentityFromEd25519 = exports.base58btcEncode = exports.base58btcDecode = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.serializeProof = exports.parseProof = exports.SealOpenError = exports.sealTo = exports.openSealed = exports.jcsString = exports.jcsBytes = exports.ready = void 0;
+exports.sendShare = exports.receiveShare = exports.signRoster = exports.ed25519RosterVerifier = exports.resolveReachability = exports.buildFriendsAgentCard = exports.wrapInDataPart = exports.unwrapDataPart = exports.sealEnvelope = exports.openSealedEnvelope = exports.verifyCardDidBinding = exports.signSuccessor = exports.pinOnFirstContact = exports.MemoryPinStore = exports.isPinned = exports.getPinned = exports.evaluateRotation = exports.DidVerifier = exports.resolveDidWeb = exports.parseDidDocument = exports.didWebToUrl = exports.parseDidKey = exports.keyAgreementFromDidKey = exports.ed25519PubToDidKey = exports.didKeyIdentityFromEd25519 = exports.base58btcEncode = exports.base58btcDecode = exports.verifyEnvelopeSignature = exports.signEnvelope = exports.serializeProof = exports.parseProof = exports.SealOpenError = exports.sealTo = exports.openSealed = exports.jcsString = exports.jcsBytes = exports.ready = void 0;
 // ── init seam ──
 var sodium_1 = require("./sodium");
 Object.defineProperty(exports, "ready", { enumerable: true, get: function () { return sodium_1.ready; } });
@@ -66,6 +66,10 @@ Object.defineProperty(exports, "buildFriendsAgentCard", { enumerable: true, get:
 // ── reachability ladder ──
 var reachability_1 = require("./reachability");
 Object.defineProperty(exports, "resolveReachability", { enumerable: true, get: function () { return reachability_1.resolveReachability; } });
+// ── account-roster Ed25519 verify (the RosterVerifier seam's crypto impl) ──
+var roster_verify_1 = require("./roster-verify");
+Object.defineProperty(exports, "ed25519RosterVerifier", { enumerable: true, get: function () { return roster_verify_1.ed25519RosterVerifier; } });
+Object.defineProperty(exports, "signRoster", { enumerable: true, get: function () { return roster_verify_1.signRoster; } });
 // ── send / receive adapter ──
 var adapter_1 = require("./adapter");
 Object.defineProperty(exports, "receiveShare", { enumerable: true, get: function () { return adapter_1.receiveShare; } });

package/dist/a2a-client/roster-verify.d.ts

@@ -0,0 +1,15 @@
+import type { Sodium } from "./sodium";
+import type { RosterVerifier } from "../roster-verifier";
+import type { AccountRoster } from "../roster-store";
+/** A RosterVerifier that checks the roster's Ed25519 signature against the base64
+ * `rosterKey`. Returns false (never throws) on a malformed key/sig or a bad
+ * signature. (Unit 7a stub — verify not implemented.) */
+export declare function ed25519RosterVerifier(sodium: Sodium): RosterVerifier;
+/** Test/host helper: produce a valid roster `sig` by signing `rosterSigningBytes`
+ * with the account's Ed25519 private key (mirrors `signSuccessor`/`signEnvelope`).
+ * Returns the base64 (ORIGINAL) detached signature. */
+export declare function signRoster(input: {
+    sodium: Sodium;
+    accountKeyPriv: Uint8Array;
+    roster: Omit<AccountRoster, "sig">;
+}): string;

package/dist/a2a-client/roster-verify.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ed25519RosterVerifier = ed25519RosterVerifier;
+exports.signRoster = signRoster;
+// ed25519RosterVerifier — the RosterVerifier seam's REAL crypto implementation
+// (a2a-client side; MAY import libsodium/jcs/sign). Mirrors how DidVerifier
+// implements the AgentVerifier seam. The host injects this so the core stays
+// transport-free.
+//
+// Contract (shared with src/roster-verifier.ts): the roster `sig` is an Ed25519
+// detached signature over `jcsBytes({ accountId, members, epoch })` — the roster
+// MINUS `sig` — exactly how `verifyEnvelopeSignature` signs the proof-stripped
+// envelope. `rosterKey` is the base64 (ORIGINAL) Ed25519 public key.
+const jcs_1 = require("./jcs");
+/** The canonical bytes the roster `sig` is computed over: the roster minus its
+ * `sig` field, JCS-canonicalized. Both signer and verifier MUST produce these
+ * identical bytes. */
+function rosterSigningBytes(roster) {
+    return (0, jcs_1.jcsBytes)({ accountId: roster.accountId, members: roster.members, epoch: roster.epoch });
+}
+/** A RosterVerifier that checks the roster's Ed25519 signature against the base64
+ * `rosterKey`. Returns false (never throws) on a malformed key/sig or a bad
+ * signature. (Unit 7a stub — verify not implemented.) */
+function ed25519RosterVerifier(sodium) {
+    return {
+        // SECURITY (finding 1): the REAL cryptographic verifier — the only RosterVerifier
+        // strong enough to back a family grant. `evaluateAccountMembership` checks this
+        // flag and fails closed (→ unverified) under any verifier that lacks it.
+        grantsFamily: true,
+        verify(roster, rosterKey) {
+            let pub;
+            let sig;
+            try {
+                pub = sodium.from_base64(rosterKey, sodium.base64_variants.ORIGINAL);
+                sig = sodium.from_base64(roster.sig, sodium.base64_variants.ORIGINAL);
+            }
+            catch {
+                // Malformed base64 in the key or sig → a failed verification, never a throw.
+                return false;
+            }
+            const msg = rosterSigningBytes(roster);
+            try {
+                return sodium.crypto_sign_verify_detached(sig, msg, pub);
+            }
+            catch {
+                // A wrong-length key/sig can throw inside libsodium — treat as a failed
+                // verification, never an uncaught error (mirrors verifyEnvelopeSignature).
+                return false;
+            }
+        },
+    };
+}
+/** Test/host helper: produce a valid roster `sig` by signing `rosterSigningBytes`
+ * with the account's Ed25519 private key (mirrors `signSuccessor`/`signEnvelope`).
+ * Returns the base64 (ORIGINAL) detached signature. */
+function signRoster(input) {
+    const { sodium, accountKeyPriv, roster } = input;
+    const msg = (0, jcs_1.jcsBytes)({ accountId: roster.accountId, members: roster.members, epoch: roster.epoch });
+    const sig = sodium.crypto_sign_detached(msg, accountKeyPriv);
+    return sodium.to_base64(sig, sodium.base64_variants.ORIGINAL);
+}

package/dist/account-roster.d.ts

@@ -0,0 +1,52 @@
+import type { AccountRoster, RosterStore } from "./roster-store";
+import type { RosterVerifier } from "./roster-verifier";
+export type AccountMembershipDecision = "family_same_account" | "not_member" | "unverified" | "roster_key_mismatch";
+/** SECURITY (finding 2, HIGH): an opaque "the caller has verified this peer controls
+ * this did" token. `evaluateAccountMembership` grants family ONLY for a value of this
+ * type, and the ONLY way to produce one is `verifiedCandidate(did)` — so the
+ * candidate-DID precondition is impossible to forget at a call site (a bare string
+ * does not type-check). The private brand makes it unforgeable from a plain object. */
+export interface VerifiedCandidate {
+    readonly did: string;
+    /** Private brand — prevents `{ did }` from structurally satisfying the type. */
+    readonly [VERIFIED_BRAND]: true;
+}
+declare const VERIFIED_BRAND: unique symbol;
+/** Mint a {@link VerifiedCandidate}. CALLING THIS IS AN ASSERTION: the caller has
+ * already proven (via a DID/pinned-key handshake — e.g. the a2a-client sealed-envelope
+ * gate that runs `DidVerifier` before this) that the peer controls `did`. Never call
+ * it on an attacker-supplied did that has not been authenticated. */
+export declare function verifiedCandidate(did: string): VerifiedCandidate;
+export interface EvaluateAccountMembershipInput {
+    roster: AccountRoster;
+    /** SECURITY (finding 2): the verified candidate — only mintable via
+     * `verifiedCandidate(did)` after the caller has authenticated the peer's control of
+     * the did. The roster membership + sig checks are NOT a proof of did-control on
+     * their own; this token supplies that missing precondition. */
+    candidate: VerifiedCandidate;
+    rosterKey: string;
+    store: RosterStore;
+    verifier?: RosterVerifier;
+}
+export interface AccountMembershipResult {
+    decision: AccountMembershipDecision;
+    reason?: string;
+}
+/** Test seam: reset the one-time-warning latch so a test can assert the loud warning
+ * fires (and de-dupes) deterministically, independent of test order. */
+export declare function _resetRosterVerifierWarningForTest(): void;
+/** Decide whether the VERIFIED `candidate` is family-via-same-account under `roster`.
+ *
+ * Preconditions (all enforced, not merely documented):
+ *  - The caller has authenticated that the peer controls `candidate.did` (carried by
+ *    the unforgeable {@link VerifiedCandidate} — finding 2). Membership + sig are NOT
+ *    a substitute for did-control.
+ *  - A real cryptographic `verifier` (`grantsFamily: true`) is injected. The
+ *    identity-only default fails closed: it can verify identity for non-grant checks
+ *    but can NEVER produce a `family_same_account` grant (finding 1).
+ *
+ * Flow: TOFU-pin the roster key on first contact; a changed key hard-fails; the
+ * verifier must accept the roster; the verifier must be family-granting; the
+ * candidate's did must be in the roster. Any miss yields a non-family decision. */
+export declare function evaluateAccountMembership(input: EvaluateAccountMembershipInput): Promise<AccountMembershipResult>;
+export {};

package/dist/account-roster.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifiedCandidate = verifiedCandidate;
+exports._resetRosterVerifierWarningForTest = _resetRosterVerifierWarningForTest;
+exports.evaluateAccountMembership = evaluateAccountMembership;
+// evaluateAccountMembership — the Increment-1 payoff (Item 3). Grants `family` via
+// TrustBasis "same_account" ONLY to a peer whose `did` is in the pinned roster AND
+// whose roster verifies under the TOFU-pinned roster key. A changed roster key
+// HARD-FAILS (no silent re-pin).
+//
+// CORE module: it uses the INJECTED RosterVerifier + RosterStore seams and does NO
+// direct crypto (no a2a-client / libsodium import) — the Ed25519 verifier is
+// injected by the host/test. The lint enforces the dependency direction.
+const observability_1 = require("./observability");
+const roster_verifier_1 = require("./roster-verifier");
+/** Mint a {@link VerifiedCandidate}. CALLING THIS IS AN ASSERTION: the caller has
+ * already proven (via a DID/pinned-key handshake — e.g. the a2a-client sealed-envelope
+ * gate that runs `DidVerifier` before this) that the peer controls `did`. Never call
+ * it on an attacker-supplied did that has not been authenticated. */
+function verifiedCandidate(did) {
+    return { did };
+}
+/** One-time loud-warning latch: we warn at most once per process when a family grant
+ * is refused purely because the active verifier is not cryptographic (finding 1). */
+let warnedNonCryptographicVerifier = false;
+/** Test seam: reset the one-time-warning latch so a test can assert the loud warning
+ * fires (and de-dupes) deterministically, independent of test order. */
+function _resetRosterVerifierWarningForTest() {
+    warnedNonCryptographicVerifier = false;
+}
+/** Decide whether the VERIFIED `candidate` is family-via-same-account under `roster`.
+ *
+ * Preconditions (all enforced, not merely documented):
+ *  - The caller has authenticated that the peer controls `candidate.did` (carried by
+ *    the unforgeable {@link VerifiedCandidate} — finding 2). Membership + sig are NOT
+ *    a substitute for did-control.
+ *  - A real cryptographic `verifier` (`grantsFamily: true`) is injected. The
+ *    identity-only default fails closed: it can verify identity for non-grant checks
+ *    but can NEVER produce a `family_same_account` grant (finding 1).
+ *
+ * Flow: TOFU-pin the roster key on first contact; a changed key hard-fails; the
+ * verifier must accept the roster; the verifier must be family-granting; the
+ * candidate's did must be in the roster. Any miss yields a non-family decision. */
+async function evaluateAccountMembership(input) {
+    const { roster, candidate, rosterKey, store } = input;
+    const accountId = roster.accountId;
+    // 1) Roster-key pin (TOFU). First contact pins the key; an EXISTING pin for a
+    // DIFFERENT key HARD-FAILS (no silent re-pin); a matching pin proceeds.
+    const existingPin = await store.getPin(accountId);
+    if (!existingPin) {
+        await store.putPin({ accountId, rosterKey, pinnedAt: new Date().toISOString() });
+    }
+    else if (existingPin.rosterKey !== rosterKey) {
+        const result = {
+            decision: "roster_key_mismatch",
+            reason: "presented roster key does not match the pinned key",
+        };
+        emit(result.decision, accountId);
+        return result;
+    }
+    // 2) Authenticity: the injected verifier (or the identity default) must accept
+    // the roster under the pinned/presented key.
+    const verifier = input.verifier ?? roster_verifier_1.DEFAULT_ROSTER_VERIFIER;
+    if (!verifier.verify(roster, rosterKey)) {
+        const result = { decision: "unverified", reason: "roster signature did not verify" };
+        emit(result.decision, accountId);
+        return result;
+    }
+    // 2b) SECURITY (finding 1, HIGH): FAIL CLOSED on the family-granting path. The
+    // identity-only default accepts any well-formed roster (it ignores the sig), so it
+    // MUST NOT be allowed to grant family — only a real cryptographic verifier
+    // (`grantsFamily: true`) can. Without one, the strongest tier is unreachable: a
+    // would-be member is `unverified`, never `family_same_account`. Warn LOUDLY once.
+    if (verifier.grantsFamily !== true) {
+        if (!warnedNonCryptographicVerifier) {
+            warnedNonCryptographicVerifier = true;
+            (0, observability_1.emitNervesEvent)({
+                level: "warn",
+                component: "friends",
+                event: "friends.roster_verifier_not_cryptographic",
+                message: "REFUSING to grant family_same_account: no cryptographic RosterVerifier injected (the identity-only default cannot back a family grant). Inject ed25519RosterVerifier to enable same-account family.",
+                meta: { accountId },
+            });
+        }
+        const result = {
+            decision: "unverified",
+            reason: "no cryptographic roster verifier injected — family grant withheld (fail-closed)",
+        };
+        emit(result.decision, accountId);
+        return result;
+    }
+    // 3) Membership: the candidate's did must be in the verified roster.
+    const isMember = roster.members.some((m) => m.did === candidate.did);
+    const result = isMember
+        ? { decision: "family_same_account" }
+        : { decision: "not_member", reason: "candidate did is not in the roster" };
+    emit(result.decision, accountId);
+    return result;
+}
+/** Emit the membership-evaluated nerves event. */
+function emit(decision, accountId) {
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.account_membership_evaluated",
+        message: "evaluated account-roster membership",
+        meta: { accountId, decision },
+    });
+}

package/dist/agent-peer.js

@@ -13,7 +13,11 @@ async function upsertAgentPeer(store, input) {
     const { name, agentId, a2a, bundleName } = input;
     const existing = await store.findByExternalId("a2a-agent", agentId);
     const now = new Date().toISOString();
-    const trustLevel = input.trustLevel ?? existing?.trustLevel ?? "acquaintance";
+    // Bug A — cold contact is safe-by-default: a brand-new peer with no explicit
+    // trustLevel and no existing record lands at `stranger`, not `acquaintance`. An
+    // owner-initiated onboard that passes an explicit `trustLevel`, and an existing
+    // record's level, both still win (they precede this fallback).
+    const trustLevel = input.trustLevel ?? existing?.trustLevel ?? "stranger";
     const baseMeta = existing?.agentMeta ?? {
         bundleName: bundleName ?? name,
         familiarity: 0,

package/dist/audit.d.ts

@@ -0,0 +1,42 @@
+import type { TrustBasis } from "./trust-explanation";
+import type { TrustLevel } from "./types";
+/** One append-only control-plane audit record. Captures a single control-plane
+ * mutation: WHO (`actor`), to WHOM (`targetId` / optional `targetDid`), the resulting
+ * `level`, the `basis` it was granted on, the `originSense` it came through, and WHEN
+ * (`ts`). The `action` discriminates the mutation kind: `"set_trust"` (a trust-level
+ * change — the `setFriendTrust` mutation + the `onboard_agent` trust seat) or
+ * `"connect"` (an owner linking one of their own agents into the fleet via `connect_to`
+ * — p11 inc2; additive, the JSONL append is value-agnostic so only the type widened). */
+export interface ControlPlaneAuditRecord {
+    action: "set_trust" | "connect";
+    targetId: string;
+    targetDid?: string;
+    level: TrustLevel;
+    basis?: TrustBasis;
+    actor: string;
+    originSense?: string;
+    ts: string;
+}
+/** The append-only sink a control-plane mutation writes through. The host
+ * implements it (in-memory in tests, a file/JSONL adapter in production). */
+export interface AuditSink {
+    append(record: ControlPlaneAuditRecord): Promise<void> | void;
+}
+/** In-memory append-only sink — test/host convenience, mirroring MemoryPinStore.
+ * `list()` exposes the records in append order; there is no overwrite. */
+export declare class MemoryAuditSink implements AuditSink {
+    private readonly records;
+    append(record: ControlPlaneAuditRecord): void;
+    list(): ControlPlaneAuditRecord[];
+}
+/** The append-only control-plane log file for a given friends directory:
+ * `<friendsDir>/_audit/control.jsonl`. A reserved `_`-prefixed sibling (like
+ * `_grants/`) so one `--dir` covers it; JSONL so appends never rewrite history. */
+export declare function auditPathFor(friendsDir: string): string;
+/** Filesystem AuditSink — appends each record as one JSON line to
+ * `_audit/control.jsonl`. mkdir-on-construct, mirroring FileGrantStore. */
+export declare class FileAuditSink implements AuditSink {
+    private readonly filePath;
+    constructor(filePath: string);
+    append(record: ControlPlaneAuditRecord): Promise<void>;
+}

package/dist/audit.js

@@ -0,0 +1,86 @@
+"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.FileAuditSink = exports.MemoryAuditSink = void 0;
+exports.auditPathFor = auditPathFor;
+// Control-plane audit (Bug B) — an append-only record of every trust mutation.
+//
+// The control plane is "who changed a peer's standing, from where, and why". The
+// package must stay storage-agnostic (and 100%-coverable), so the audit is an
+// injectable SINK — not a hard-wired `fs` write — mirroring the observability
+// seam and the GrantStore/FileGrantStore split. `setFriendTrust` writes one record
+// on a successful mutation; the host wires a `FileAuditSink` (or its own) to
+// persist it. With no sink injected, the mutation is unchanged (no-op audit).
+const fs = __importStar(require("fs"));
+const fsPromises = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const observability_1 = require("./observability");
+/** In-memory append-only sink — test/host convenience, mirroring MemoryPinStore.
+ * `list()` exposes the records in append order; there is no overwrite. */
+class MemoryAuditSink {
+    records = [];
+    append(record) {
+        this.records.push(record);
+    }
+    list() {
+        return [...this.records];
+    }
+}
+exports.MemoryAuditSink = MemoryAuditSink;
+/** The append-only control-plane log file for a given friends directory:
+ * `<friendsDir>/_audit/control.jsonl`. A reserved `_`-prefixed sibling (like
+ * `_grants/`) so one `--dir` covers it; JSONL so appends never rewrite history. */
+function auditPathFor(friendsDir) {
+    return path.join(friendsDir, "_audit", "control.jsonl");
+}
+/** Filesystem AuditSink — appends each record as one JSON line to
+ * `_audit/control.jsonl`. mkdir-on-construct, mirroring FileGrantStore. */
+class FileAuditSink {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.audit_sink_init",
+            message: "file audit sink initialized",
+            meta: {},
+        });
+    }
+    async append(record) {
+        await fsPromises.appendFile(this.filePath, JSON.stringify(record) + "\n", "utf-8");
+    }
+}
+exports.FileAuditSink = FileAuditSink;