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

package/dist/mcp/dispatch.d.ts

@@ -1,14 +1,25 @@
 import type { FriendStore } from "../store";
 import type { GrantStore } from "../grant-store";
 import type { MissionStore } from "../mission-store";
+import type { AuditSink } from "../audit";
 type Args = Record<string, unknown>;
 export interface DispatchResult {
     result: unknown;
     isError: boolean;
 }
+/** WHO/WHENCE context stamped onto a control-plane audit record (finding 3). The MCP
+ * server passes the local owner/sense it was constructed with. */
+export interface ControlPlaneContext {
+    actor?: string;
+    originSense?: string;
+}
+/** Whether wiring an AuditSink should also stamp a record for an `onboard_agent` trust
+ * seat: only when the owner explicitly set a trustLevel (a deliberate trust decision).
+ * A cold contact with no trustLevel lands at the safe `stranger` default (Bug A) and is
+ * NOT an owner trust mutation, so it is not audited. */
 export declare function coerceBool(v: unknown): boolean;
 export declare function coerceInt(v: unknown): number | undefined;
 export declare function coerceString(v: unknown): string;
 export declare function coerceOptionalString(v: unknown): string | undefined;
-export declare function dispatchTool(store: FriendStore, name: string, args: Args, grants?: GrantStore, missions?: MissionStore): Promise<DispatchResult>;
+export declare function dispatchTool(store: FriendStore, name: string, args: Args, grants?: GrantStore, missions?: MissionStore, audit?: AuditSink, controlContext?: ControlPlaneContext): Promise<DispatchResult>;
 export {};

package/dist/mcp/dispatch.js

@@ -11,6 +11,7 @@ exports.dispatchTool = dispatchTool;
 // the library fns. `dispatchTool` is a flat tool → library-fn map (D9/D10) with
 // NO domain logic of its own — every behavior lives in the friends library.
 const observability_1 = require("../observability");
+const identity_1 = require("../identity");
 const types_1 = require("../types");
 const resolver_1 = require("../resolver");
 const trust_explanation_1 = require("../trust-explanation");
@@ -31,6 +32,17 @@ const missions_1 = require("../missions");
 const mission_share_1 = require("../mission-share");
 const coordination_1 = require("../coordination");
 const types_2 = require("../types");
+/** SECURITY (finding 3-A): the friends MCP server speaks JSON-RPC over **stdio**, and
+ * stdio is an owner-only channel — the local user who launched the process is the only
+ * actor. So when no explicit controlContext is wired, audited mutations are attributed
+ * to the stdio owner boundary rather than the generic "unknown". A network/multi-tenant
+ * transport MUST pass its own authenticated actor instead of relying on these. */
+const STDIO_OWNER_ACTOR = "owner:stdio";
+const STDIO_ORIGIN_SENSE = "stdio";
+/** Whether wiring an AuditSink should also stamp a record for an `onboard_agent` trust
+ * seat: only when the owner explicitly set a trustLevel (a deliberate trust decision).
+ * A cold contact with no trustLevel lands at the safe `stranger` default (Bug A) and is
+ * NOT an owner trust mutation, so it is not audited. */
 function coerceBool(v) {
     return v === true || v === "true";
 }
@@ -69,13 +81,18 @@ const NO_GRANT_STORE = { ok: false, status: "unsupported", message: "no grant st
  * embedding). The mission ledger needs mission persistence, so report it cleanly
  * rather than guessing. */
 const NO_MISSION_STORE = { ok: false, status: "unsupported", message: "no mission store configured (mission tools require one)" };
-async function dispatchTool(store, name, args, grants, missions) {
+async function dispatchTool(store, name, args, grants, missions, audit, controlContext) {
     (0, observability_1.emitNervesEvent)({
         component: "clients",
         event: "clients.mcp_dispatch",
         message: "dispatching friends mcp tool",
         meta: { tool: name },
     });
+    // SECURITY (finding 3 / 3-A): resolve the WHO/WHENCE for an audited mutation. With
+    // no explicit context, attribute to the stdio owner boundary (the only actor on an
+    // owner-only stdio channel) rather than the generic "unknown".
+    const auditActor = controlContext?.actor ?? STDIO_OWNER_ACTOR;
+    const auditOriginSense = controlContext?.originSense ?? STDIO_ORIGIN_SENSE;
     switch (name) {
         case "resolve_party": {
             const provider = coerceString(args.provider);
@@ -188,7 +205,14 @@ async function dispatchTool(store, name, args, grants, missions) {
             return { result: results, isError: false };
         }
         case "set_trust": {
-            const result = await (0, trust_mutation_1.setFriendTrust)(store, coerceString(args.friendId), coerceString(args.trustLevel));
+            // SECURITY (finding 3): thread the audit sink + owner/sense context so the LIVE
+            // trust mutation actually writes a control-plane record. With no sink wired,
+            // setFriendTrust treats the ctx as a no-op (back-compat).
+            const result = await (0, trust_mutation_1.setFriendTrust)(store, coerceString(args.friendId), coerceString(args.trustLevel), {
+                ...(audit ? { sink: audit } : {}),
+                actor: auditActor,
+                originSense: auditOriginSense,
+            });
             return { result, isError: result.ok === false };
         }
         case "link_identity": {
@@ -207,14 +231,32 @@ async function dispatchTool(store, name, args, grants, missions) {
             return { result, isError: result.ok === false };
         }
         case "onboard_agent": {
+            const explicitTrustLevel = coerceOptionalString(args.trustLevel);
             const record = await (0, agent_peer_1.upsertAgentPeer)(store, {
                 name: coerceString(args.name),
                 agentId: coerceString(args.agentId),
-                trustLevel: coerceOptionalString(args.trustLevel),
+                trustLevel: explicitTrustLevel,
                 a2a: parseMaybeJson(args.a2a),
                 mailbox: parseMaybeJson(args.mailbox),
                 bundleName: coerceOptionalString(args.bundleName),
             });
+            // SECURITY (finding 3): an owner-initiated trust SEAT (an explicit trustLevel) is
+            // a control-plane trust mutation, so audit it through the wired sink. A cold
+            // contact with no trustLevel falls to the safe `stranger` default (Bug A) — not
+            // an owner trust decision — so it is left unaudited.
+            if (audit && explicitTrustLevel !== undefined) {
+                const targetDid = (0, identity_1.resolveAgentIdentity)(record.agentMeta).did;
+                const auditRecord = {
+                    action: "set_trust",
+                    targetId: record.id,
+                    ...(targetDid !== undefined ? { targetDid } : {}),
+                    level: explicitTrustLevel,
+                    actor: auditActor,
+                    originSense: auditOriginSense,
+                    ts: record.updatedAt,
+                };
+                await audit.append(auditRecord);
+            }
             return { result: record, isError: false };
         }
         case "whoami": {

package/dist/mcp/run-main.js

@@ -35,11 +35,14 @@ function runMain(argv, env, io) {
         message: "friends mcp run-main",
         meta: { source },
     });
-    // The consent-grant + mission collections are sibling `_grants/` + `_missions/`
-    // dirs under the friends dir, so the single `--dir` wires the whole substrate
-    // (friends + consent + missions). `openFileBundle` encapsulates that convention.
-    const { store, grants, missions } = (0, file_bundle_1.openFileBundle)(dir);
-    const server = (0, server_1.createFriendsMcpServer)({ store, grants, missions, stdin: io.stdin, stdout: io.stdout });
+    // The consent-grant + mission + audit collections are sibling `_grants/`,
+    // `_missions/`, `_audit/` dirs under the friends dir, so the single `--dir` wires the
+    // whole substrate. `openFileBundle` encapsulates that convention.
+    const { store, grants, missions, audit } = (0, file_bundle_1.openFileBundle)(dir);
+    // SECURITY (finding 3 / 3-A): thread the FileAuditSink into the live server so trust
+    // mutations are audited. The `friends-mcp` bin speaks owner-only stdio, so the
+    // default actor/originSense (the stdio owner boundary) is the correct attribution.
+    const server = (0, server_1.createFriendsMcpServer)({ store, grants, missions, audit, stdin: io.stdin, stdout: io.stdout });
     server.start();
     return server;
 }

package/dist/mcp/schemas.js

@@ -187,7 +187,7 @@ function getToolSchemas() {
                 properties: {
                     name: { type: "string", description: "the peer agent's name" },
                     agentId: { type: "string", description: "the a2a agent id" },
-                    trustLevel: { type: "string", description: "trust level (default acquaintance)" },
+                    trustLevel: { type: "string", description: "trust level (default stranger (cold contact))" },
                     a2a: { type: "object", description: "a2a coordinates { cardUrl?, endpointUrl?, protocolVersion? }" },
                     mailbox: { type: "object", description: "optional A2A git-mailbox coords { repo, selfOutboxAgentId }" },
                     bundleName: { type: "string", description: "optional bundle name" },

package/dist/mcp/server.d.ts

@@ -1,6 +1,8 @@
 import type { FriendStore } from "../store";
 import type { GrantStore } from "../grant-store";
 import type { MissionStore } from "../mission-store";
+import type { AuditSink } from "../audit";
+import type { ControlPlaneContext } from "./dispatch";
 export interface FriendsMcpServerOptions {
     store: FriendStore;
     /** Optional consent-grant store. When omitted, the consent/share tools
@@ -11,6 +13,13 @@ export interface FriendsMcpServerOptions {
      * (record_mission / get_mission / list_missions / share_mission /
      * import_mission) report `unsupported`; everything else works without it. */
     missions?: MissionStore;
+    /** Optional control-plane audit sink (Bug B, finding 3). When wired, the LIVE
+     * trust mutations (`set_trust`, and an explicit-trust-seat `onboard_agent`) append
+     * an append-only audit record. When omitted, those mutations are unaudited. */
+    audit?: AuditSink;
+    /** Optional WHO/WHENCE context for audited mutations. Defaults to the stdio
+     * owner-only boundary (finding 3-A) when omitted. */
+    controlContext?: ControlPlaneContext;
     stdin: NodeJS.ReadableStream;
     stdout: NodeJS.WritableStream;
 }

package/dist/mcp/server.js

@@ -13,7 +13,7 @@ const observability_1 = require("../observability");
 const schemas_1 = require("./schemas");
 const dispatch_1 = require("./dispatch");
 function createFriendsMcpServer(options) {
-    const { store, grants, missions, stdin, stdout } = options;
+    const { store, grants, missions, audit, controlContext, stdin, stdout } = options;
     let buffer = "";
     let running = false;
     let useContentLengthFraming = true;
@@ -145,7 +145,7 @@ function createFriendsMcpServer(options) {
         const toolName = params.name ?? "";
         const toolArgs = params.arguments ?? {};
         try {
-            const { result, isError } = await (0, dispatch_1.dispatchTool)(store, toolName, toolArgs, grants, missions);
+            const { result, isError } = await (0, dispatch_1.dispatchTool)(store, toolName, toolArgs, grants, missions, audit, controlContext);
             writeResponse({
                 jsonrpc: "2.0",
                 id: request.id,

package/dist/resolver.d.ts

@@ -1,5 +1,29 @@
 import type { FriendStore } from "./store";
 import type { IdentityProvider, ResolvedContext } from "./types";
+import type { RosterStore } from "./roster-store";
+import type { RosterVerifier } from "./roster-verifier";
+/** Optional roster context for a cold-contact resolution (Bug C). When supplied AND
+ * the candidate's `did` is a key-verified member of the pinned account roster, the
+ * resolver seats `family` (attributable to `same_account`) even when the peer is on
+ * a different OS user. Constructor-injected (not a `resolve()` arg) so existing
+ * `new FriendResolver(store, params)` call sites stay source-compatible. The
+ * resolver stays core-clean: the Ed25519 `verifier` arrives via the seam — never an
+ * a2a-client import. */
+export interface FriendResolverRosterContext {
+    store: RosterStore;
+    accountId: string;
+    /** The peer's did. PRECONDITION (finding 2): the host has already authenticated
+     * that the peer controls this did (the a2a-client sealed-envelope gate runs
+     * `DidVerifier` before resolution). The resolver wraps it in a `VerifiedCandidate`
+     * on the caller's behalf — so only seed this from a verified inbound identity, never
+     * an unauthenticated, peer-claimed string. */
+    candidateDid: string;
+    /** PRECONDITION (finding 1): to actually seat family, this MUST be a cryptographic
+     * verifier (`ed25519RosterVerifier`, `grantsFamily: true`). With it absent (the
+     * identity-only default), `evaluateAccountMembership` fails closed and the resolver
+     * keeps the cold-A2A `stranger` default — never family. */
+    verifier?: RosterVerifier;
+}
 export interface FriendResolverParams {
     provider: IdentityProvider;
     externalId: string;
@@ -22,7 +46,14 @@ export declare function isLocalMachineOwnerIdentity(provider: string, externalId
 export declare class FriendResolver {
     private readonly store;
     private readonly params;
-    constructor(store: FriendStore, params: FriendResolverParams);
+    private readonly roster?;
+    constructor(store: FriendStore, params: FriendResolverParams, roster?: FriendResolverRosterContext);
     resolve(): Promise<ResolvedContext>;
     private resolveOrCreate;
+    /** Bug C — whether the candidate is family via a key-verified account roster.
+     * Reads the pinned roster + roster key from the injected RosterStore and reuses
+     * `evaluateAccountMembership`. Returns false (no family) when no roster context is
+     * wired, the roster/pin is absent, or membership is anything but
+     * `family_same_account` (unverified / not-member / key-mismatch all stay false). */
+    private evaluateRosterFamily;
 }

package/dist/resolver.js

@@ -11,6 +11,7 @@ const crypto_1 = require("crypto");
 const os_1 = require("os");
 const channel_1 = require("./channel");
 const observability_1 = require("./observability");
+const account_roster_1 = require("./account-roster");
 const CURRENT_SCHEMA_VERSION = 1;
 // Test seam: when set (including to null), overrides OS detection of the
 // machine-owner username so resolver tests are deterministic.
@@ -46,9 +47,11 @@ function isLocalMachineOwnerIdentity(provider, externalId, ownerUsername) {
 class FriendResolver {
     store;
     params;
-    constructor(store, params) {
+    roster;
+    constructor(store, params, roster) {
         this.store = store;
         this.params = params;
+        this.roster = roster;
     }
     async resolve() {
         const friend = await this.resolveOrCreate();
@@ -123,6 +126,13 @@ class FriendResolver {
         }
         const isFirstImprint = !hasAnyFriends;
         const isA2AAgent = this.params.provider === "a2a-agent";
+        // Bug C — roster-awareness. When a roster context is injected AND the candidate's
+        // did is a key-verified member of the pinned account roster, seat `family` (even
+        // on a different OS user). Reuses `evaluateAccountMembership` against the pinned
+        // roster fetched from the injected RosterStore. Absent/unverifiable roster ⇒ the
+        // OS-owner + cold-A2A default below is unchanged. The resolver never imports
+        // a2a-client — the Ed25519 verifier arrives via the injected seam.
+        const isRosterFamily = await this.evaluateRosterFamily();
         // The local friend that names the OS user running the daemon is the machine
         // owner (family) — they own the agent + its bundle. Usually this friend already
         // exists as a family/primary hatch imprint; this covers the un-imprinted boss
@@ -146,8 +156,11 @@ class FriendResolver {
         const friend = {
             id: (0, crypto_1.randomUUID)(),
             name: this.params.displayName,
-            role: isA2AAgent ? "agent-peer" : isFirstImprint ? "primary" : isLocalMachineOwner ? "family" : "stranger",
-            trustLevel: isA2AAgent ? "stranger" : (isFirstImprint || isLocalMachineOwner) ? "family" : "stranger",
+            // Bug C: a key-verified roster member is family (role + trustLevel), overriding
+            // the cold-A2A `agent-peer`/`stranger` default. Otherwise the matrix is
+            // unchanged: a2a ⇒ agent-peer/stranger; first imprint or machine owner ⇒ family.
+            role: isRosterFamily ? "family" : isA2AAgent ? "agent-peer" : isFirstImprint ? "primary" : isLocalMachineOwner ? "family" : "stranger",
+            trustLevel: isRosterFamily ? "family" : isA2AAgent ? "stranger" : (isFirstImprint || isLocalMachineOwner) ? "family" : "stranger",
             connections: [],
             externalIds: [externalId],
             tenantMemberships,
@@ -183,5 +196,39 @@ class FriendResolver {
         }
         return friend;
     }
+    /** Bug C — whether the candidate is family via a key-verified account roster.
+     * Reads the pinned roster + roster key from the injected RosterStore and reuses
+     * `evaluateAccountMembership`. Returns false (no family) when no roster context is
+     * wired, the roster/pin is absent, or membership is anything but
+     * `family_same_account` (unverified / not-member / key-mismatch all stay false). */
+    async evaluateRosterFamily() {
+        const ctx = this.roster;
+        if (!ctx)
+            return false;
+        const roster = await ctx.store.getRoster(ctx.accountId);
+        const pin = await ctx.store.getPin(ctx.accountId);
+        // The resolver grants family only against an ALREADY-pinned roster key (the pin
+        // is established during explicit onboarding, never silently at resolve time).
+        if (!roster || !pin)
+            return false;
+        const result = await (0, account_roster_1.evaluateAccountMembership)({
+            roster,
+            // The host authenticated the peer's control of this did upstream (see the
+            // FriendResolverRosterContext.candidateDid precondition); wrap it as verified.
+            candidate: (0, account_roster_1.verifiedCandidate)(ctx.candidateDid),
+            rosterKey: pin.rosterKey,
+            store: ctx.store,
+            ...(ctx.verifier !== undefined ? { verifier: ctx.verifier } : {}),
+        });
+        if (result.decision !== "family_same_account")
+            return false;
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.family_via_roster",
+            message: "seated family via the account roster (same_account)",
+            meta: { accountId: ctx.accountId, candidateDid: ctx.candidateDid },
+        });
+        return true;
+    }
 }
 exports.FriendResolver = FriendResolver;

package/dist/roster-store-file.d.ts

@@ -0,0 +1,16 @@
+import type { AccountRoster, RosterPin, RosterStore } from "./roster-store";
+/** The sibling rosters directory for a given friends directory:
+ * `<friendsDir>/_rosters`. A reserved `_`-prefixed subdir (like `_grants`) so one
+ * `--dir` still points the whole substrate at one place. */
+export declare function rostersDirFor(friendsDir: string): string;
+export declare class FileRosterStore implements RosterStore {
+    private readonly rostersPath;
+    constructor(rostersPath: string);
+    getRoster(accountId: string): Promise<AccountRoster | null>;
+    putRoster(roster: AccountRoster): Promise<void>;
+    getPin(accountId: string): Promise<RosterPin | null>;
+    putPin(pin: RosterPin): Promise<void>;
+    /** Read + parse a JSON file, returning null on a missing file, invalid JSON, or a
+     * non-object payload (guarded; mirrors FileGrantStore.readJson). */
+    private readJson;
+}

package/dist/roster-store-file.js

@@ -0,0 +1,125 @@
+"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.FileRosterStore = void 0;
+exports.rostersDirFor = rostersDirFor;
+// FileRosterStore — filesystem adapter for RosterStore.
+//
+// Stores the account roster and its pinned key as JSON files in a sibling
+// `_rosters/` collection next to the friends directory (one `<accountId>.roster.json`
+// and one `<accountId>.pin.json` per account). Mirrors FileGrantStore's structure
+// (mkdir on construct, one file per record, guarded reads) so the stores feel
+// uniform.
+const fs = __importStar(require("fs"));
+const fsPromises = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const observability_1 = require("./observability");
+/** The sibling rosters directory for a given friends directory:
+ * `<friendsDir>/_rosters`. A reserved `_`-prefixed subdir (like `_grants`) so one
+ * `--dir` still points the whole substrate at one place. */
+function rostersDirFor(friendsDir) {
+    return path.join(friendsDir, "_rosters");
+}
+/** SECURITY (finding 8, LOW): the accountId is interpolated into the
+ * `<accountId>.roster.json` / `.pin.json` filename, so a wire-influenced value like
+ * "../evil" could otherwise escape the `_rosters/` dir. Enforce a strict allowlist
+ * (alphanumerics, dot, underscore, hyphen — no path separators) AND a basename
+ * identity (no normalization surprises), rejecting `.`/`..` and the empty string.
+ * Throws on anything unsafe so a bad accountId can never reach the filesystem. */
+const SAFE_ACCOUNT_ID = /^[A-Za-z0-9._-]+$/;
+function assertSafeAccountId(accountId) {
+    // Basename identity is the primary traversal guard: any value carrying a path
+    // separator (`/` on POSIX, `/` or `\` on Windows) basenames to something else and is
+    // rejected. The charset allowlist then rejects the remaining unsafe-but-separatorless
+    // bytes (spaces, shell metachars, control chars, the empty string — `+` needs ≥1
+    // char). The explicit `.`/`..` reject closes the two in-charset relative-dir refs.
+    if (path.basename(accountId) !== accountId) {
+        throw new Error(`unsafe accountId ${JSON.stringify(accountId)}: must not contain a path separator`);
+    }
+    if (!SAFE_ACCOUNT_ID.test(accountId) || accountId === "." || accountId === "..") {
+        throw new Error(`unsafe accountId ${JSON.stringify(accountId)}: must match ${SAFE_ACCOUNT_ID} (not "." or "..")`);
+    }
+}
+class FileRosterStore {
+    rostersPath;
+    constructor(rostersPath) {
+        this.rostersPath = rostersPath;
+        fs.mkdirSync(rostersPath, { recursive: true });
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.roster_store_init",
+            message: "file roster store initialized",
+            meta: {},
+        });
+    }
+    async getRoster(accountId) {
+        assertSafeAccountId(accountId);
+        const raw = await this.readJson(path.join(this.rostersPath, `${accountId}.roster.json`));
+        return raw;
+    }
+    async putRoster(roster) {
+        assertSafeAccountId(roster.accountId);
+        await fsPromises.writeFile(path.join(this.rostersPath, `${roster.accountId}.roster.json`), JSON.stringify(roster, null, 2), "utf-8");
+    }
+    async getPin(accountId) {
+        assertSafeAccountId(accountId);
+        const raw = await this.readJson(path.join(this.rostersPath, `${accountId}.pin.json`));
+        return raw;
+    }
+    async putPin(pin) {
+        assertSafeAccountId(pin.accountId);
+        await fsPromises.writeFile(path.join(this.rostersPath, `${pin.accountId}.pin.json`), JSON.stringify(pin, null, 2), "utf-8");
+    }
+    /** Read + parse a JSON file, returning null on a missing file, invalid JSON, or a
+     * non-object payload (guarded; mirrors FileGrantStore.readJson). */
+    async readJson(filePath) {
+        try {
+            const raw = await fsPromises.readFile(filePath, "utf-8");
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                    return null;
+                return parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.FileRosterStore = FileRosterStore;

package/dist/roster-store-memory.d.ts

@@ -0,0 +1,9 @@
+import type { AccountRoster, RosterPin, RosterStore } from "./roster-store";
+export declare class MemoryRosterStore implements RosterStore {
+    private readonly rosters;
+    private readonly pins;
+    getRoster(accountId: string): Promise<AccountRoster | null>;
+    putRoster(roster: AccountRoster): Promise<void>;
+    getPin(accountId: string): Promise<RosterPin | null>;
+    putPin(pin: RosterPin): Promise<void>;
+}

package/dist/roster-store-memory.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRosterStore = void 0;
+class MemoryRosterStore {
+    rosters = new Map();
+    pins = new Map();
+    async getRoster(accountId) {
+        return this.rosters.get(accountId) ?? null;
+    }
+    async putRoster(roster) {
+        this.rosters.set(roster.accountId, roster);
+    }
+    async getPin(accountId) {
+        return this.pins.get(accountId) ?? null;
+    }
+    async putPin(pin) {
+        this.pins.set(pin.accountId, pin);
+    }
+}
+exports.MemoryRosterStore = MemoryRosterStore;

package/dist/roster-store.d.ts

@@ -0,0 +1,29 @@
+/** The signed account roster as it lives on the wire / on disk. `members` lists the
+ * owner's agents by `{ handle, did }`; `epoch` is the monotonic roster version; the
+ * Ed25519 `sig` is over `jcsBytes({ accountId, members, epoch })` (the roster minus
+ * `sig`), exactly how `verifyEnvelopeSignature` signs the proof-stripped envelope. */
+export interface AccountRoster {
+    accountId: string;
+    members: {
+        handle: string;
+        did: string;
+    }[];
+    epoch: number;
+    sig: string;
+}
+/** The TOFU-pinned roster signing key for an account (first-contact pin; a changed
+ * key HARD-FAILS rather than silently re-pinning). `rosterKey` is the base64
+ * Ed25519 public key the roster `sig` must verify under. */
+export interface RosterPin {
+    accountId: string;
+    rosterKey: string;
+    pinnedAt: string;
+}
+/** Domain-specific store for the account roster + its pinned signing key. One
+ * roster and one pin per accountId. */
+export interface RosterStore {
+    getRoster(accountId: string): Promise<AccountRoster | null>;
+    putRoster(roster: AccountRoster): Promise<void>;
+    getPin(accountId: string): Promise<RosterPin | null>;
+    putPin(pin: RosterPin): Promise<void>;
+}

package/dist/roster-store.js

@@ -0,0 +1,9 @@
+"use strict";
+// Roster store abstraction (p11 Item 3 — the account roster).
+//
+// The pinned account roster + its TOFU roster-key pin persist through RosterStore —
+// a sibling to GrantStore/MissionStore, mirroring their shape. The core stays
+// storage-agnostic; backends stay pluggable. No roster module imports `fs` directly
+// except the FileRosterStore adapter. This file is a PURE INTERFACE (no logic) and
+// is coverage-excluded in vitest.config.ts, mirroring src/store.ts.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/roster-verifier.d.ts

@@ -0,0 +1,23 @@
+import type { AccountRoster } from "./roster-store";
+export interface RosterVerifier {
+    /** Whether `roster` is authentic under the pinned `rosterKey`. The identity-only
+     * default returns true for any well-formed roster (ignores the sig); an Ed25519
+     * impl verifies the detached sig over the canonical roster bytes. */
+    verify(roster: AccountRoster, rosterKey: string): boolean;
+    /** SECURITY (finding 1, HIGH): whether this verifier is strong enough to back a
+     * FAMILY grant. The identity-only default ignores the sig, so it MUST NOT grant
+     * family — only a real cryptographic verifier (the a2a-client `ed25519RosterVerifier`)
+     * sets this true. `evaluateAccountMembership` fails closed (→ `unverified`, never
+     * `family_same_account`) when the active verifier is not family-granting. Optional
+     * + defaulting-to-false so a custom verifier is non-granting unless it opts in. */
+    grantsFamily?: boolean;
+}
+/** Identity-only roster verifier: accept any well-formed roster, ignore the sig.
+ * The day-one default for NON-GRANT identity checks; it deliberately omits
+ * `grantsFamily` (defaults to false) so the family-granting path
+ * (`evaluateAccountMembership`) fails closed under it — a garbage-signed roster can
+ * never yield a family grant without a real cryptographic verifier injected. Mirrors
+ * `tofuVerifier`. */
+export declare const identityRosterVerifier: RosterVerifier;
+/** The default verifier used when no crypto verifier is injected. */
+export declare const DEFAULT_ROSTER_VERIFIER: RosterVerifier;

package/dist/roster-verifier.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ROSTER_VERIFIER = exports.identityRosterVerifier = void 0;
+// RosterVerifier — the pluggable account-roster authentication seam (Q1; mirrors
+// AgentVerifier exactly). The core declares the INTERFACE + an identity-only
+// default that does NO crypto; the a2a-client side provides the real Ed25519
+// implementation (`ed25519RosterVerifier`), which the host injects — the same split
+// that keeps `DidVerifier` out of the core. THIS MODULE MUST NOT import
+// src/a2a-client/ or libsodium (the no-restricted-imports lint enforces it).
+//
+// The canonical-bytes contract both sides agree on: the roster `sig` is an Ed25519
+// detached signature over `jcsBytes({ accountId, members, epoch })` — the roster
+// MINUS its `sig` field — exactly how `verifyEnvelopeSignature` signs the
+// proof-stripped envelope. The identity default ignores the sig (TOFU-equivalent);
+// the crypto impl checks it.
+const observability_1 = require("./observability");
+/** A roster is well-formed when it has the structural shape the membership check
+ * relies on: a string accountId, an array of `{handle, did}` members, a numeric
+ * epoch, and a string sig. (The identity verifier accepts any well-formed roster
+ * without checking the sig — TOFU-equivalent, mirroring `tofuVerifier`.) */
+function isWellFormedRoster(roster) {
+    return (typeof roster.accountId === "string" &&
+        Array.isArray(roster.members) &&
+        roster.members.every((m) => typeof m.handle === "string" && typeof m.did === "string") &&
+        typeof roster.epoch === "number" &&
+        typeof roster.sig === "string");
+}
+/** Identity-only roster verifier: accept any well-formed roster, ignore the sig.
+ * The day-one default for NON-GRANT identity checks; it deliberately omits
+ * `grantsFamily` (defaults to false) so the family-granting path
+ * (`evaluateAccountMembership`) fails closed under it — a garbage-signed roster can
+ * never yield a family grant without a real cryptographic verifier injected. Mirrors
+ * `tofuVerifier`. */
+exports.identityRosterVerifier = {
+    verify(roster) {
+        const ok = isWellFormedRoster(roster);
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.roster_verified",
+            message: "verified account roster (tofu)",
+            meta: { accountId: roster.accountId, epoch: roster.epoch, ok },
+        });
+        return ok;
+    },
+};
+/** The default verifier used when no crypto verifier is injected. */
+exports.DEFAULT_ROSTER_VERIFIER = exports.identityRosterVerifier;

package/dist/store-file.d.ts

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