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

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

package/dist/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;

package/dist/identity.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgentIdentity = resolveAgentIdentity;
+exports.withMigratedIdentity = withMigratedIdentity;
+// Agent identity migrate-on-read (p11 Item 2 — the DID re-key).
+//
+// The durable identity home is `AgentMeta.identity` ({ did, pinnedKey?, handle?,
+// pinnedAt? }). Legacy records carry only the optional `a2a.did` hint (or nothing).
+// `resolveAgentIdentity` reads either, preferring the durable home and lifting
+// `a2a.did` on a miss (migrate-on-read), mirroring FileGrantStore.normalize's
+// legacy-field handling. `withMigratedIdentity` backfills `identity.did` from
+// `a2a.did` so the next `put` persists it forward (migrate-on-write), matching the
+// resolver's local-id migration + the grant subjectFriendId→subjectKey pattern.
+const observability_1 = require("./observability");
+/** 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.) */
+function resolveAgentIdentity(meta) {
+    if (!meta)
+        return {};
+    // Durable home wins (authoritative). Spread only the present optional fields so
+    // a partial identity ({ did } only) doesn't surface undefined keys. SECURITY
+    // (finding 6, LOW): an empty-string did is NOT a did — omit it so it can never be a
+    // matchable identity key (ties to findFriendByDid's falsy-did guard, finding 4).
+    //
+    // NOTE (finding 5-D): when BOTH meta.identity.did and a legacy meta.a2a.did are
+    // present and DIVERGE, the durable home silently wins here. That divergence can be a
+    // tampering signal (a record's legacy hint disagreeing with its pinned identity).
+    // We don't warn from this hot path (resolveAgentIdentity runs per-record in the
+    // findFriendByDid scan and per-audit-derivation); a divergence audit belongs in a
+    // write-time reconciliation (e.g. withMigratedIdentity / the onboard path), not here.
+    if (meta.identity) {
+        const { did, pinnedKey, handle, pinnedAt } = meta.identity;
+        return {
+            ...(did ? { did } : {}),
+            ...(pinnedKey !== undefined ? { pinnedKey } : {}),
+            ...(handle !== undefined ? { handle } : {}),
+            ...(pinnedAt !== undefined ? { pinnedAt } : {}),
+        };
+    }
+    // Migrate-on-read: lift the legacy a2a.did hint when the durable home is absent.
+    // A falsy (absent or empty-string) hint is treated as no-did.
+    if (meta.a2a?.did)
+        return { did: meta.a2a.did };
+    return {};
+}
+/** 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.) */
+function withMigratedIdentity(meta) {
+    if (!meta)
+        return undefined;
+    // Already carries the durable home → no clobber.
+    if (meta.identity)
+        return meta;
+    // Nothing to migrate from → unchanged. A falsy (absent or empty-string) a2a.did is
+    // not a real did to backfill (finding 6).
+    if (!meta.a2a?.did)
+        return meta;
+    // Backfill identity.did from the legacy a2a.did so the next put persists forward.
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.identity_migrated",
+        message: "backfilled AgentMeta.identity.did from legacy a2a.did",
+        meta: { did: meta.a2a.did },
+    });
+    return { ...meta, identity: { did: meta.a2a.did } };
+}

package/dist/index.d.ts

@@ -29,8 +29,21 @@ export { upsertGroupContextParticipants } from "./group-context";
 export { accumulateFriendTokens } from "./tokens";
 export { applyFriendNote } from "./notes";
 export { setFriendTrust } from "./trust-mutation";
+export type { SetFriendTrustContext } from "./trust-mutation";
+export { MemoryAuditSink, FileAuditSink, auditPathFor } from "./audit";
+export type { AuditSink, ControlPlaneAuditRecord } from "./audit";
 export { linkExternalId, unlinkExternalId } from "./link-identity";
 export { upsertAgentPeer } from "./agent-peer";
+export { resolveAgentIdentity, withMigratedIdentity } from "./identity";
+export type { ResolvedAgentIdentity } from "./identity";
+export { findFriendByDid } from "./friend-lookup";
+export { FileRosterStore, rostersDirFor } from "./roster-store-file";
+export type { RosterStore, AccountRoster, RosterPin } from "./roster-store";
+export { identityRosterVerifier, DEFAULT_ROSTER_VERIFIER } from "./roster-verifier";
+export type { RosterVerifier } from "./roster-verifier";
+export { MemoryRosterStore } from "./roster-store-memory";
+export { evaluateAccountMembership, verifiedCandidate, _resetRosterVerifierWarningForTest } from "./account-roster";
+export type { AccountMembershipDecision, AccountMembershipResult, EvaluateAccountMembershipInput, VerifiedCandidate, } from "./account-roster";
 export { recordRelationshipOutcome } from "./outcomes";
 export { recordMission } from "./missions";
 export type { RecordMissionInput } from "./missions";

package/dist/index.js

@@ -6,8 +6,8 @@
 // multi-agent (a2a peer) aware, consumed through the FriendStore interface +
 // FriendResolver.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.revokeShare = exports.grantShare = exports.importCoordination = exports.prepareCoordination = exports.importMissionShare = exports.prepareMissionShare = exports.importProfileShare = exports.prepareProfileShare = exports.DEFAULT_AGENT_VERIFIER = exports.tofuVerifier = exports.DEFAULT_CONSENT_POLICY = exports.tieredPolicy = exports.trustImpliedPolicy = exports.strictPolicy = exports.resolveRoom = exports.whoami = exports.recordMission = exports.recordRelationshipOutcome = exports.upsertAgentPeer = exports.unlinkExternalId = exports.linkExternalId = exports.setFriendTrust = exports.applyFriendNote = exports.accumulateFriendTokens = exports.upsertGroupContextParticipants = exports.DEFAULT_STANDING_RULE = exports.explainStanding = exports.assessStanding = exports.describeTrustContext = exports.getAlwaysOnSenseNames = exports.isRemoteChannel = exports.channelToFacing = exports.getChannelCapabilities = exports._setMachineOwnerUsernameForTest = exports.isLocalMachineOwnerIdentity = exports.machineOwnerUsername = exports.FriendResolver = exports.openFileBundle = exports.missionsDirFor = exports.FileMissionStore = exports.grantsDirFor = exports.FileGrantStore = exports.FileFriendStore = exports.isCoordinationIntent = exports.isShareScope = exports.isIntegration = exports.isIdentityProvider = exports.isTrustedLevel = exports.IDENTITY_SCOPES = exports.TRUSTED_LEVELS = void 0;
-exports.setNervesEmitter = exports.emitNervesEvent = exports.isGrantEffective = exports.listShares = void 0;
+exports.resolveRoom = exports.whoami = exports.recordMission = exports.recordRelationshipOutcome = exports._resetRosterVerifierWarningForTest = exports.verifiedCandidate = exports.evaluateAccountMembership = exports.MemoryRosterStore = exports.DEFAULT_ROSTER_VERIFIER = exports.identityRosterVerifier = exports.rostersDirFor = exports.FileRosterStore = exports.findFriendByDid = exports.withMigratedIdentity = exports.resolveAgentIdentity = exports.upsertAgentPeer = exports.unlinkExternalId = exports.linkExternalId = exports.auditPathFor = exports.FileAuditSink = exports.MemoryAuditSink = exports.setFriendTrust = exports.applyFriendNote = exports.accumulateFriendTokens = exports.upsertGroupContextParticipants = exports.DEFAULT_STANDING_RULE = exports.explainStanding = exports.assessStanding = exports.describeTrustContext = exports.getAlwaysOnSenseNames = exports.isRemoteChannel = exports.channelToFacing = exports.getChannelCapabilities = exports._setMachineOwnerUsernameForTest = exports.isLocalMachineOwnerIdentity = exports.machineOwnerUsername = exports.FriendResolver = exports.openFileBundle = exports.missionsDirFor = exports.FileMissionStore = exports.grantsDirFor = exports.FileGrantStore = exports.FileFriendStore = exports.isCoordinationIntent = exports.isShareScope = exports.isIntegration = exports.isIdentityProvider = exports.isTrustedLevel = exports.IDENTITY_SCOPES = exports.TRUSTED_LEVELS = void 0;
+exports.setNervesEmitter = exports.emitNervesEvent = exports.isGrantEffective = exports.listShares = exports.revokeShare = exports.grantShare = exports.importCoordination = exports.prepareCoordination = exports.importMissionShare = exports.prepareMissionShare = exports.importProfileShare = exports.prepareProfileShare = exports.DEFAULT_AGENT_VERIFIER = exports.tofuVerifier = exports.DEFAULT_CONSENT_POLICY = exports.tieredPolicy = exports.trustImpliedPolicy = exports.strictPolicy = void 0;
 // -- Values --
 var types_1 = require("./types");
 Object.defineProperty(exports, "TRUSTED_LEVELS", { enumerable: true, get: function () { return types_1.TRUSTED_LEVELS; } });
@@ -52,11 +52,40 @@ var notes_1 = require("./notes");
 Object.defineProperty(exports, "applyFriendNote", { enumerable: true, get: function () { return notes_1.applyFriendNote; } });
 var trust_mutation_1 = require("./trust-mutation");
 Object.defineProperty(exports, "setFriendTrust", { enumerable: true, get: function () { return trust_mutation_1.setFriendTrust; } });
+// -- Control-plane audit (Bug B): append-only record of trust mutations --
+var audit_1 = require("./audit");
+Object.defineProperty(exports, "MemoryAuditSink", { enumerable: true, get: function () { return audit_1.MemoryAuditSink; } });
+Object.defineProperty(exports, "FileAuditSink", { enumerable: true, get: function () { return audit_1.FileAuditSink; } });
+Object.defineProperty(exports, "auditPathFor", { enumerable: true, get: function () { return audit_1.auditPathFor; } });
 var link_identity_1 = require("./link-identity");
 Object.defineProperty(exports, "linkExternalId", { enumerable: true, get: function () { return link_identity_1.linkExternalId; } });
 Object.defineProperty(exports, "unlinkExternalId", { enumerable: true, get: function () { return link_identity_1.unlinkExternalId; } });
 var agent_peer_1 = require("./agent-peer");
 Object.defineProperty(exports, "upsertAgentPeer", { enumerable: true, get: function () { return agent_peer_1.upsertAgentPeer; } });
+// -- Agent identity (p11 Item 2 — DID re-key): durable home + migrate-on-read --
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "resolveAgentIdentity", { enumerable: true, get: function () { return identity_1.resolveAgentIdentity; } });
+Object.defineProperty(exports, "withMigratedIdentity", { enumerable: true, get: function () { return identity_1.withMigratedIdentity; } });
+// did-aware friend lookup (the durable cross-agent primary key is the DID).
+var friend_lookup_1 = require("./friend-lookup");
+Object.defineProperty(exports, "findFriendByDid", { enumerable: true, get: function () { return friend_lookup_1.findFriendByDid; } });
+// -- Account roster (p11 Item 3): pinned roster + TOFU roster-key storage seam --
+var roster_store_file_1 = require("./roster-store-file");
+Object.defineProperty(exports, "FileRosterStore", { enumerable: true, get: function () { return roster_store_file_1.FileRosterStore; } });
+Object.defineProperty(exports, "rostersDirFor", { enumerable: true, get: function () { return roster_store_file_1.rostersDirFor; } });
+// -- RosterVerifier seam (Q1): core declares the interface + identity-only default;
+// the a2a-client provides the Ed25519 impl (host-injected). Core stays crypto-free.
+var roster_verifier_1 = require("./roster-verifier");
+Object.defineProperty(exports, "identityRosterVerifier", { enumerable: true, get: function () { return roster_verifier_1.identityRosterVerifier; } });
+Object.defineProperty(exports, "DEFAULT_ROSTER_VERIFIER", { enumerable: true, get: function () { return roster_verifier_1.DEFAULT_ROSTER_VERIFIER; } });
+var roster_store_memory_1 = require("./roster-store-memory");
+Object.defineProperty(exports, "MemoryRosterStore", { enumerable: true, get: function () { return roster_store_memory_1.MemoryRosterStore; } });
+// -- Account-roster membership (Item 3 payoff): family via same_account for a
+// key-verified, TOFU-pinned roster member; changed roster key hard-fails. --
+var account_roster_1 = require("./account-roster");
+Object.defineProperty(exports, "evaluateAccountMembership", { enumerable: true, get: function () { return account_roster_1.evaluateAccountMembership; } });
+Object.defineProperty(exports, "verifiedCandidate", { enumerable: true, get: function () { return account_roster_1.verifiedCandidate; } });
+Object.defineProperty(exports, "_resetRosterVerifierWarningForTest", { enumerable: true, get: function () { return account_roster_1._resetRosterVerifierWarningForTest; } });
 var outcomes_1 = require("./outcomes");
 Object.defineProperty(exports, "recordRelationshipOutcome", { enumerable: true, get: function () { return outcomes_1.recordRelationshipOutcome; } });
 var missions_1 = require("./missions");

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

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