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

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

@@ -75,6 +75,48 @@ export interface ImportedLearning {
     assertedBy?: AgentAttribution;
     originallyAssertedBy?: AgentAttribution;
 }
+export interface MissionTaskSpec {
+    /** Correlation key the result-return matches (PINNED). Minted by the producer. */
+    requestId: string;
+    /** What B is being asked to do (the headline ask). */
+    summary: string;
+    /** Optional longer brief. */
+    details?: string;
+    /** Optional structured inputs. */
+    inputs?: Record<string, string>;
+}
+export interface MissionResult {
+    /** Correlates to the gap-1 task-spec's requestId (PINNED) — A only accepts a result
+     * for a requestId it actually delegated. */
+    requestId: string;
+    /** The headline deliverable — what B produced. */
+    summary: string;
+    /** Optional larger produced artifact body. */
+    artifact?: string;
+    /** Optional structured outputs. */
+    outputs?: Record<string, string>;
+    /** first_party on B's side; imported (attributed to B) on A's. */
+    provenance?: NoteProvenance;
+}
+export interface MissionResultEnvelope {
+    /** The mission, named by its join key — `missionKey` + a human title. */
+    subject: {
+        missionKey: string;
+        title: string;
+    };
+    /** The agent that produced this result (B's join-key agentId) — the attribution.
+     * NOTE (security review inc-2 finding 5, by-design): this is SELF-ASSERTED and is
+     * vestigial on import — importMissionResult attributes + enforces against the
+     * TRANSPORT-supplied `ImportMissionResultInput.fromAgentId` (the authenticated channel
+     * identity), never this envelope field, so a forged value here changes nothing. */
+    fromAgentId: string;
+    /** The delegation correlation key (matches the gap-1 task-spec's requestId). */
+    requestId: string;
+    result: MissionResult;
+    /** Opaque, verifier-specific proof slot. The TOFU verifier ignores it. */
+    proof?: string;
+    issuedAt: string;
+}
 export type CoordinationIntent = "request" | "offer" | "accept" | "decline" | "handoff";
 export declare function isCoordinationIntent(value: unknown): value is CoordinationIntent;
 export interface CoordinationLogEntry {
@@ -99,6 +141,17 @@ export interface MissionRecord {
     learnings: Record<string, MissionLearning>;
     importedLearnings?: Record<string, Record<string, ImportedLearning>>;
     coordination?: MissionCoordination;
+    delegations?: Record<string, {
+        task: MissionTaskSpec;
+        assignee?: AgentAttribution;
+        provenance: NoteProvenance;
+    }>;
+    importedDelegations?: Record<string, Record<string, {
+        task: MissionTaskSpec;
+        provenance: NoteProvenance;
+    }>>;
+    results?: Record<string, MissionResult>;
+    importedResults?: Record<string, Record<string, MissionResult>>;
     createdAt: string;
     updatedAt: string;
     schemaVersion: number;
@@ -108,6 +161,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.7",
   "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",
@@ -46,6 +46,7 @@
     "example:cross-agent-mission-memory": "npm run build && tsx examples/cross-agent-mission-memory.ts",
     "example:cross-agent-standing": "npm run build && tsx examples/cross-agent-standing.ts",
     "example:cross-agent-coordination": "npm run build && tsx examples/cross-agent-coordination.ts",
+    "example:cross-agent-delegation": "npm run build && tsx examples/cross-agent-delegation.ts",
     "example:cross-agent-a2a-relay": "npm run build && tsx examples/cross-agent-a2a-relay.ts",
     "release:bump": "node scripts/release-bump.cjs",
     "release:preflight": "node scripts/release-preflight.cjs",