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

package/README.md

@@ -535,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`,
@@ -548,7 +554,10 @@ 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).
@@ -565,7 +574,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,11 @@
 {
   "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": [

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,38 @@
+import type { TrustBasis } from "./trust-explanation";
+import type { TrustLevel } from "./types";
+/** One append-only control-plane audit record. Captures a single trust mutation:
+ * WHO (`actor`), to WHOM (`targetId` / optional `targetDid`), the new `level`, the
+ * `basis` it was granted on, the `originSense` it came through, and WHEN (`ts`). */
+export interface ControlPlaneAuditRecord {
+    action: "set_trust";
+    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;

package/dist/file-bundle.d.ts

@@ -1,12 +1,17 @@
 import { FileFriendStore } from "./store-file";
 import { FileGrantStore } from "./grant-store-file";
 import { FileMissionStore } from "./mission-store-file";
+import { FileAuditSink } from "./audit";
 export interface FileBundle {
     store: FileFriendStore;
     grants: FileGrantStore;
     missions: FileMissionStore;
+    /** Control-plane audit sink (Bug B, finding 3) over the sibling `_audit/control.jsonl`,
+     * so the live MCP `set_trust` / `onboard_agent` trust seat write audit records. */
+    audit: FileAuditSink;
     friendsDir: string;
     grantsDir: string;
     missionsDir: string;
+    auditPath: string;
 }
 export declare function openFileBundle(friendsDir: string): FileBundle;

package/dist/file-bundle.js

@@ -7,17 +7,21 @@ exports.openFileBundle = openFileBundle;
 const store_file_1 = require("./store-file");
 const grant_store_file_1 = require("./grant-store-file");
 const mission_store_file_1 = require("./mission-store-file");
+const audit_1 = require("./audit");
 const observability_1 = require("./observability");
 function openFileBundle(friendsDir) {
     const grantsDir = (0, grant_store_file_1.grantsDirFor)(friendsDir);
     const missionsDir = (0, mission_store_file_1.missionsDirFor)(friendsDir);
+    const auditPath = (0, audit_1.auditPathFor)(friendsDir);
     (0, observability_1.emitNervesEvent)({ component: "friends", event: "friends.file_bundle_opened", message: "opened file bundle", meta: {} });
     return {
         store: new store_file_1.FileFriendStore(friendsDir),
         grants: new grant_store_file_1.FileGrantStore(grantsDir),
         missions: new mission_store_file_1.FileMissionStore(missionsDir),
+        audit: new audit_1.FileAuditSink(auditPath),
         friendsDir,
         grantsDir,
         missionsDir,
+        auditPath,
     };
 }

package/dist/friend-lookup.d.ts

@@ -0,0 +1,9 @@
+import type { FriendStore } from "./store";
+import type { FriendRecord } from "./types";
+/** Find the friend record whose durable identity DID equals `did`. A DUPLICATE did is
+ * an anomaly: it emits a loud `friends.duplicate_did` warning and resolves
+ * deterministically WITHOUT rewarding back-dating — a pinned/verified record wins, else
+ * the lowest record `id` (a stable, non-temporal tie-break) — see {@link preferOverBest}.
+ * Returns null when no record matches, the query did is falsy, or the store has no
+ * `listAll`. */
+export declare function findFriendByDid(store: FriendStore, did: string): Promise<FriendRecord | null>;

package/dist/friend-lookup.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findFriendByDid = findFriendByDid;
+// did-aware friend lookup (p11 Item 2 — the DID re-key).
+//
+// `did` is the durable cross-agent primary key. This pure helper finds a friend
+// record by did WITHOUT changing the FriendStore interface contract: it scans
+// `store.listAll?.()` and matches on the record's resolved identity
+// (`resolveAgentIdentity(f.agentMeta).did`, which already prefers identity.did and
+// migrates a2a.did on read). Additive — `findByExternalId` is untouched. A store
+// with no `listAll` yields null (the lookup is best-effort, never a throw).
+const observability_1 = require("./observability");
+const identity_1 = require("./identity");
+/** Whether `candidate` should replace the current best among duplicate-did records.
+ *
+ * SECURITY (finding 5, MEDIUM): the tie-break must NOT reward back-dating — the old
+ * "lowest createdAt wins" rule let an attacker mint a duplicate-did record with an
+ * earlier createdAt to silently shadow a legit one. Instead:
+ *  1) Prefer a trust-relevant signal — a record carrying a TOFU-pinned key
+ *     (`pinnedKey`) is the verified one and beats an unpinned duplicate.
+ *  2) When pinned-status is equal, break the tie by the record `id` (a stable,
+ *     non-temporal key) — back-dating `createdAt` no longer gains anything. */
+function preferOverBest(candidate, best) {
+    const candidatePinned = (0, identity_1.resolveAgentIdentity)(candidate.agentMeta).pinnedKey !== undefined;
+    const bestPinned = (0, identity_1.resolveAgentIdentity)(best.agentMeta).pinnedKey !== undefined;
+    if (candidatePinned !== bestPinned)
+        return candidatePinned; // pinned beats unpinned
+    return candidate.id < best.id; // stable, non-temporal tie-break
+}
+/** Find the friend record whose durable identity DID equals `did`. A DUPLICATE did is
+ * an anomaly: it emits a loud `friends.duplicate_did` warning and resolves
+ * deterministically WITHOUT rewarding back-dating — a pinned/verified record wins, else
+ * the lowest record `id` (a stable, non-temporal tie-break) — see {@link preferOverBest}.
+ * Returns null when no record matches, the query did is falsy, or the store has no
+ * `listAll`. */
+async function findFriendByDid(store, did) {
+    // SECURITY (finding 4, MEDIUM): a falsy did query must never match. Without this,
+    // findFriendByDid(store, undefined|"") matched the first did-less record (a did-less
+    // record resolves to `undefined`, and `undefined !== undefined` is false → match).
+    if (!did)
+        return null;
+    if (typeof store.listAll !== "function")
+        return null;
+    const all = await store.listAll();
+    let best = null;
+    let matchCount = 0;
+    for (const f of all) {
+        const resolvedDid = (0, identity_1.resolveAgentIdentity)(f.agentMeta).did;
+        // Skip records whose resolved did is falsy (absent/empty) so they can never match —
+        // belt-and-braces with resolveAgentIdentity's own empty-string guard (finding 6).
+        if (!resolvedDid || resolvedDid !== did)
+            continue;
+        matchCount += 1;
+        if (best === null || preferOverBest(f, best))
+            best = f;
+    }
+    // SECURITY (finding 5): a duplicate did is itself an anomaly — surface it loudly so a
+    // shadowing attempt is visible, rather than silently resolving it away.
+    if (matchCount > 1) {
+        (0, observability_1.emitNervesEvent)({
+            level: "warn",
+            component: "friends",
+            event: "friends.duplicate_did",
+            message: `duplicate did detected across ${matchCount} friend records — resolving to the pinned/lowest-id record (NOT lowest-createdAt); investigate possible record shadowing`,
+            meta: { did, matchCount },
+        });
+    }
+    return best;
+}

package/dist/identity.d.ts

@@ -0,0 +1,17 @@
+import type { AgentMeta } from "./types";
+/** The resolved durable identity of an agent peer — independent of which on-disk
+ * shape carried it. All fields optional: a did-less legacy record reads clean. */
+export interface ResolvedAgentIdentity {
+    did?: string;
+    pinnedKey?: string;
+    handle?: string;
+    pinnedAt?: string;
+}
+/** Read an agent's durable identity, preferring `meta.identity` and lifting the
+ * legacy `meta.a2a.did` on a miss (migrate-on-read). Returns `{}` for a did-less
+ * or absent meta. (Unit 4a stub — not implemented.) */
+export declare function resolveAgentIdentity(meta: AgentMeta | undefined): ResolvedAgentIdentity;
+/** Return a meta whose `identity.did` is backfilled from `a2a.did` when the durable
+ * home is absent (migrate-on-write); a meta already carrying `identity` is returned
+ * unchanged (no clobber). Absent meta is returned as-is. (Unit 4a stub.) */
+export declare function withMigratedIdentity(meta: AgentMeta | undefined): AgentMeta | undefined;