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

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/trust-explanation.d.ts

@@ -1,5 +1,5 @@
 import type { Channel, FriendRecord, TrustLevel } from "./types";
-export type TrustBasis = "direct" | "shared_group" | "unknown";
+export type TrustBasis = "direct" | "shared_group" | "unknown" | "same_account";
 export interface TrustExplanation {
     level: TrustLevel;
     basis: TrustBasis;
@@ -13,4 +13,10 @@ export declare function describeTrustContext(input: {
     friend: FriendRecord;
     channel: Channel;
     isGroupChat?: boolean;
+    /** When the relationship is `family` AND this hint is `"same_account"`, the
+     * explanation attributes the family trust to the signed account roster
+     * (`basis: "same_account"`) instead of the generic `direct`. Ignored for any
+     * non-family level. Absent ⇒ existing behavior byte-for-byte. (Unit 3a stub:
+     * accepted but not yet honored — implemented GREEN in Unit 3b.) */
+    basisHint?: TrustBasis;
 }): TrustExplanation;

package/dist/trust-explanation.js

@@ -11,14 +11,17 @@ function resolveLevel(friend) {
 function describeTrustContext(input) {
     const level = resolveLevel(input.friend);
     const relatedGroupId = findRelatedGroupId(input.friend);
-    const explanation = level === "family" || level === "friend"
+    // The same-account variant only applies where the relationship is actually
+    // account-derived family: level === "family" AND the caller hints same_account
+    // (the roster path seats it). It keeps the family tier's permits/constraints but
+    // attributes the trust to the signed account roster, not generic direct trust.
+    const isSameAccountFamily = level === "family" && input.basisHint === "same_account";
+    const explanation = isSameAccountFamily
         ? {
             level,
-            basis: "direct",
-            summary: level === "family"
-                ? "direct family trust"
-                : "direct trusted relationship",
-            why: "this relationship is directly trusted rather than inferred through a shared group or cold first contact.",
+            basis: "same_account",
+            summary: "same-account family (signed account roster)",
+            why: "this agent is recognized as the same owner's agent via the signed account roster, not through a shared group or cold first contact.",
             permits: [
                 "local operations when appropriate",
                 "proactive follow-through",
@@ -26,39 +29,54 @@ function describeTrustContext(input) {
             ],
             constraints: [],
         }
-        : level === "acquaintance"
+        : level === "family" || level === "friend"
             ? {
                 level,
-                basis: "shared_group",
-                summary: relatedGroupId
-                    ? "known through the shared project group"
-                    : "known through a shared group context",
-                why: relatedGroupId
-                    ? `this trust comes from the shared group context ${relatedGroupId}, not from direct endorsement.`
-                    : "this trust comes from shared group context rather than direct endorsement.",
+                basis: "direct",
+                summary: level === "family"
+                    ? "direct family trust"
+                    : "direct trusted relationship",
+                why: "this relationship is directly trusted rather than inferred through a shared group or cold first contact.",
                 permits: [
-                    "group-safe coordination",
-                    "normal conversation inside the shared context",
+                    "local operations when appropriate",
+                    "proactive follow-through",
+                    "full collaborative problem solving",
                 ],
-                constraints: [
-                    "guarded local actions",
-                    "do not assume broad private authority",
-                ],
-                relatedGroupId,
+                constraints: [],
             }
-            : {
-                level,
-                basis: "unknown",
-                summary: "truly unknown first-contact context",
-                why: "this person is not known through direct trust or a shared group context.",
-                permits: [
-                    "safe first-contact orientation only",
-                ],
-                constraints: [
-                    "first contact does not reach the full model on open channels",
-                    "no local or privileged actions",
-                ],
-            };
+            : level === "acquaintance"
+                ? {
+                    level,
+                    basis: "shared_group",
+                    summary: relatedGroupId
+                        ? "known through the shared project group"
+                        : "known through a shared group context",
+                    why: relatedGroupId
+                        ? `this trust comes from the shared group context ${relatedGroupId}, not from direct endorsement.`
+                        : "this trust comes from shared group context rather than direct endorsement.",
+                    permits: [
+                        "group-safe coordination",
+                        "normal conversation inside the shared context",
+                    ],
+                    constraints: [
+                        "guarded local actions",
+                        "do not assume broad private authority",
+                    ],
+                    relatedGroupId,
+                }
+                : {
+                    level,
+                    basis: "unknown",
+                    summary: "truly unknown first-contact context",
+                    why: "this person is not known through direct trust or a shared group context.",
+                    permits: [
+                        "safe first-contact orientation only",
+                    ],
+                    constraints: [
+                        "first contact does not reach the full model on open channels",
+                        "no local or privileged actions",
+                    ],
+                };
     (0, observability_1.emitNervesEvent)({
         component: "friends",
         event: "friends.trust_explained",

package/dist/trust-mutation.d.ts

@@ -1,4 +1,16 @@
 import type { FriendStore } from "./store";
 import type { TrustLevel } from "./types";
 import type { FriendOpResult } from "./results";
-export declare function setFriendTrust(store: FriendStore, friendId: string, level: TrustLevel): Promise<FriendOpResult>;
+import type { AuditSink } from "./audit";
+import type { TrustBasis } from "./trust-explanation";
+/** Optional control-plane context for a trust mutation (Bug B). When a `sink` is
+ * supplied, a successful mutation appends one append-only control-plane audit
+ * record carrying WHO (`actor`), the `basis` and `originSense`, and WHEN. All
+ * fields are optional so the existing 3-arg callers are unaffected. */
+export interface SetFriendTrustContext {
+    actor?: string;
+    originSense?: string;
+    basis?: TrustBasis;
+    sink?: AuditSink;
+}
+export declare function setFriendTrust(store: FriendStore, friendId: string, level: TrustLevel, ctx?: SetFriendTrustContext): Promise<FriendOpResult>;

package/dist/trust-mutation.js

@@ -7,7 +7,8 @@ exports.setFriendTrust = setFriendTrust;
 // `trustLevel` and `role` to the same level (so the record's coarse role tracks
 // its trust). A missing friend is a normal `not_found` result, never a throw.
 const observability_1 = require("./observability");
-async function setFriendTrust(store, friendId, level) {
+const identity_1 = require("./identity");
+async function setFriendTrust(store, friendId, level, ctx) {
     (0, observability_1.emitNervesEvent)({
         component: "friends",
         event: "friends.trust_set",
@@ -16,14 +17,42 @@ async function setFriendTrust(store, friendId, level) {
     });
     const current = await store.get(friendId);
     if (!current) {
+        // not_found is an early return BEFORE any mutation — and so writes NO audit
+        // record. The control-plane log captures actual standing changes only.
         return { ok: false, status: "not_found", message: "friend record not found" };
     }
+    const updatedAt = new Date().toISOString();
     const updated = {
         ...current,
         trustLevel: level,
         role: level,
-        updatedAt: new Date().toISOString(),
+        updatedAt,
     };
     await store.put(friendId, updated);
+    // Bug B — append one control-plane audit record on the successful mutation. The
+    // `targetDid` is the record's durable identity DID (identity.did, falling back to
+    // the migrated a2a.did via resolveAgentIdentity). `actor` defaults to the literal
+    // "unknown" when the caller threads no context. No sink ⇒ a clean no-op.
+    //
+    // NOTE (finding 6-B): the append runs AFTER store.put, so it is best-effort with
+    // respect to the mutation — if the sink append throws/crashes, the trust change is
+    // already persisted but the audit line may be missing. We keep this ordering on
+    // purpose (the mutation is the source of truth; the audit is an observability log,
+    // not a 2-phase-commit participant). A throwing sink rejects this call so the caller
+    // still sees the failure; it does not roll back the already-applied mutation.
+    if (ctx?.sink) {
+        const targetDid = (0, identity_1.resolveAgentIdentity)(current.agentMeta).did;
+        const record = {
+            action: "set_trust",
+            targetId: friendId,
+            ...(targetDid !== undefined ? { targetDid } : {}),
+            level,
+            ...(ctx.basis !== undefined ? { basis: ctx.basis } : {}),
+            actor: ctx.actor ?? "unknown",
+            ...(ctx.originSense !== undefined ? { originSense: ctx.originSense } : {}),
+            ts: updatedAt,
+        };
+        await ctx.sink.append(record);
+    }
     return { ok: true, status: "updated", record: updated };
 }

package/dist/types.d.ts

@@ -108,6 +108,17 @@ export interface AgentMeta {
     familiarity: number;
     sharedMissions: string[];
     outcomes: RelationshipOutcome[];
+    /** The durable identity home (p11 Item 2 — the DID re-key). `did` is the
+     * cross-agent primary key; `pinnedKey` is its TOFU-pinned Ed25519 public key.
+     * Additive + optional: legacy records carry only `a2a.did` (or nothing) and
+     * migrate-on-read into this shape via `resolveAgentIdentity`. schemaVersion
+     * stays 1. */
+    identity?: {
+        did: string;
+        pinnedKey?: string;
+        handle?: string;
+        pinnedAt?: string;
+    };
     a2a?: {
         cardUrl?: string;
         endpointUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/friends",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "The who's-who / identity / relationship substrate for agents — trust ladder (family/friend/acquaintance/stranger), multi-party and multi-agent, consumed via the FriendStore interface + FriendResolver.",
   "license": "Apache-2.0",
   "main": "dist/index.js",