@ouro.bot/friends 0.1.0-alpha.4

package/dist/coordination.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareCoordination = prepareCoordination;
+exports.importCoordination = importCoordination;
+// prepareCoordination (producer) + importCoordination (consumer) — the shared-work
+// assignment ledger (brick 5). Structural twins of mission-share.ts's mission
+// producer / consumer, re-aimed from a FACT (a learning / an outcome) at an
+// ASSIGNMENT (who is doing this mission).
+//
+// Coordination is a tiny, append-only set of mission-coordination messages (five
+// verbs: request / offer / accept / decline / handoff) that ride the brick-2
+// mailbox under a new `kind:"coordination"`, gated by trust (brick 1) + consent
+// (the existing grant stack, new `"coordinate"` scope), whose ONLY persisted effect
+// is one bounded sub-object on the mission a participant already shares — its
+// `coordination` (assignee + an append-only log). Store-only + transport-agnostic:
+// prepareCoordination returns an envelope, importCoordination consumes one; the
+// WIRE is the caller's job. Pure — the only node builtin is `node:crypto`.
+//
+// Through-line invariants (every one is tested in coordination.test.ts):
+//  - the mission is named by its JOIN KEY (`missionKey`), NEVER the local UUID;
+//  - the message is consent-gated (subject = the missionKey, scope = "coordinate");
+//  - imported intents NEVER touch first-party `learnings`/`notes`/`status` (they
+//    only append to `coordination.log` and, for an `accept`, set `assignee`);
+//  - the source agent's trust CAPS acceptance (a stranger peer is refused);
+//  - `status` / `participants` / `trustLevel` / `standing` are NEVER recomputed
+//    from a coordination message (non-transitive);
+//  - a `handoff` NEVER forces an `assignee` onto the receiver — only the receiver's
+//    own `accept` sets it (non-transitive handoff);
+//  - the ONE producer-side precondition: you must HOLD the assignment to hand it off;
+//  - assignee-conflict is last-writer-wins by `issuedAt` (the mailbox's total order);
+//  - an unknown mission may be SEEDED only by a friend/family introducing peer.
+const node_crypto_1 = require("node:crypto");
+const observability_1 = require("./observability");
+const consent_1 = require("./consent");
+const verifier_1 = require("./verifier");
+/** Append a log entry to a mission's coordination sub-object (creating the
+ * sub-object if absent), returning a NEW MissionCoordination (never mutates the
+ * input). The log is append-only — this only ever ADDS one step. */
+function appendLog(existing, entry) {
+    const base = existing ?? { log: [] };
+    return { ...base, log: [...base.log, entry] };
+}
+/** Whether this agent currently HOLDS the mission's assignment — the one
+ * producer-side precondition (you can only hand off what you hold). A one-line
+ * equality check, not a state machine. */
+function holdsAssignment(record, selfAgentId) {
+    return record.coordination?.assignee?.agentId === selfAgentId;
+}
+/** Apply the OUTGOING intent to the producer's own mission record as a first-party
+ * step: always append the intent to `coordination.log`; on an `accept`, also claim
+ * the assignment for self (the accepter is taking it). No other intent moves the
+ * producer's `assignee`. Mirrors how recordMission stamps first-party provenance. */
+function applyOutgoingIntent(record, input, now) {
+    const entry = {
+        intent: input.intent,
+        fromAgentId: input.selfAgentId,
+        at: now,
+        provenance: { origin: "first_party" },
+        ...(input.note !== undefined ? { note: input.note } : {}),
+    };
+    const withLog = appendLog(record.coordination, entry);
+    const coordination = input.intent === "accept"
+        ? { ...withLog, assignee: { agentId: input.selfAgentId }, assignedAt: now }
+        : withLog;
+    return { ...record, coordination, updatedAt: now };
+}
+/**
+ * Producer half of the coordination primitive. Consent-gated (subject = the
+ * mission's `missionKey`, scope = `"coordinate"`), names the mission by its join
+ * key (never the local UUID). The recipient's trust — read off this agent's own
+ * friend record for `toAgentId` — is the authorization input the policy uses. The
+ * ONLY precondition: `handoff` requires this agent to hold the assignment. Also
+ * records the outgoing intent on the local mission as a first-party log step.
+ */
+async function prepareCoordination(missions, store, grants, input, consent = consent_1.DEFAULT_CONSENT_POLICY) {
+    const record = await missions.get(input.missionId);
+    if (!record) {
+        return { ok: false, status: "not_found" };
+    }
+    // The recipient's trust is read from this agent's own knowledge of it (the
+    // a2a-agent friend record for toAgentId). An unknown recipient defaults to
+    // stranger — never trusted by default.
+    const recipientRecord = await store.findByExternalId("a2a-agent", input.toAgentId);
+    const recipientTrust = recipientRecord?.trustLevel ?? "stranger";
+    const recipient = { agentId: input.toAgentId, trustLevel: recipientTrust };
+    // The subject is the mission, keyed by its missionKey. A coordination message
+    // consents through the EXISTING grant machinery via the new identity-tier
+    // `"coordinate"` scope — so trust ≥ friend suffices under the tiered default,
+    // with ZERO change to consent-policy logic (only the scope set grew).
+    const consented = await consent.consents({
+        subjectKey: record.missionKey,
+        recipient,
+        scope: "coordinate",
+        grants,
+    });
+    if (!consented) {
+        return { ok: false, status: "no_consent" };
+    }
+    // The ONE producer-side state check: you must HOLD the assignment to hand it off.
+    if (input.intent === "handoff" && !holdsAssignment(record, input.selfAgentId)) {
+        return { ok: false, status: "not_assignee" };
+    }
+    const now = new Date().toISOString();
+    const envelope = {
+        subject: { missionKey: record.missionKey, title: record.title },
+        fromAgentId: input.selfAgentId,
+        intent: input.intent,
+        issuedAt: now,
+        ...(input.note !== undefined ? { note: input.note } : {}),
+        ...(input.intent === "handoff" && input.proposedAssignee !== undefined
+            ? { proposedAssignee: input.proposedAssignee }
+            : {}),
+        ...(input.proof !== undefined ? { proof: input.proof } : {}),
+    };
+    // Record the outgoing intent on the producer's own mission (first-party), so the
+    // sender's record reflects "I asked / I offered / I accepted".
+    const updated = applyOutgoingIntent(record, input, now);
+    await missions.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.coordination_prepared",
+        message: "prepared coordination envelope",
+        meta: { intent: input.intent, toAgentId: input.toAgentId, consentPolicy: consent.name },
+    });
+    return { ok: true, envelope };
+}
+// ── Consumer ──
+/** Trust levels a peer must hold to INTRODUCE a previously-unknown mission via a
+ * coordination message. A friend/family peer may seed a new mission; a stranger /
+ * acquaintance peer may not (mirrors the mission-share SEEDING_TRUST). */
+const SEEDING_TRUST = new Set(["family", "friend"]);
+const TRUST_RANK = { family: 4, friend: 3, acquaintance: 2, stranger: 1 };
+/** Whether an incoming intent is already in the log under the same identity-tuple
+ * `(intent, fromAgentId, issuedAt)` — the same idempotency technique
+ * mergeImportedOutcomes uses, so a replayed coordination message is a no-op on the
+ * log. `issuedAt` is matched against the entry's `at` (imports stamp `at = issuedAt`). */
+function alreadyLogged(coordination, intent, fromAgentId, issuedAt) {
+    if (!coordination)
+        return false;
+    return coordination.log.some((e) => e.intent === intent && e.fromAgentId === fromAgentId && e.at === issuedAt);
+}
+/** Apply an INCOMING coordination envelope to a mission record. Appends the intent
+ * to `coordination.log` stamped `origin:imported` + attributed (never first-party,
+ * never duplicated). Applies the assignee effect — the ONLY mutation beyond the
+ * log, and tightly bounded:
+ *   - `accept`  → set assignee = the sender (the accepter is claiming it), with
+ *     last-writer-wins by `issuedAt`: a later accept overrides an earlier one, an
+ *     earlier accept never clobbers a later holder.
+ *   - everything else (request/offer/decline/handoff) → log only; a `handoff`
+ *     NEVER sets assignee on receipt (non-transitive — only a self-accept does).
+ * NEVER recomputes status/participants/trustLevel/standing (non-transitive). */
+function applyIncomingIntent(record, envelope, fromAgentId, now) {
+    // Replay/idempotency: a message already in the log adds nothing (and can't move
+    // the assignee a second time).
+    if (alreadyLogged(record.coordination, envelope.intent, fromAgentId, envelope.issuedAt)) {
+        return { record, assigned: false };
+    }
+    const entry = {
+        intent: envelope.intent,
+        fromAgentId,
+        at: envelope.issuedAt,
+        provenance: { origin: "imported", assertedBy: { agentId: fromAgentId }, importedAt: now },
+        ...(envelope.note !== undefined ? { note: envelope.note } : {}),
+    };
+    const withLog = appendLog(record.coordination, entry);
+    if (envelope.intent === "accept") {
+        // Last-writer-wins by issuedAt: the accept with the later issuedAt is the
+        // effective assignee. An earlier-issued accept arriving after a later one does
+        // NOT clobber the later holder (both stay in the append-only log either way).
+        const currentAssignedAt = record.coordination?.assignedAt;
+        const isLater = currentAssignedAt === undefined || envelope.issuedAt >= currentAssignedAt;
+        const coordination = isLater
+            ? { ...withLog, assignee: { agentId: fromAgentId }, assignedAt: envelope.issuedAt }
+            : withLog;
+        return { record: { ...record, coordination, updatedAt: now }, assigned: isLater };
+    }
+    // request / offer / decline / handoff → log only; assignee untouched.
+    return { record: { ...record, coordination: withLog, updatedAt: now }, assigned: false };
+}
+/** Create a freshly-seeded mission for a previously-unknown key, carrying the
+ * subject's join key + title, `status:"active"`, empty first-party `learnings`. The
+ * coordination sub-object starts with an empty log (the incoming intent is applied
+ * by the caller). */
+function seedMission(envelope, now) {
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        missionKey: envelope.subject.missionKey,
+        title: envelope.subject.title,
+        status: "active",
+        participants: [],
+        outcomes: [],
+        learnings: {},
+        importedLearnings: {},
+        coordination: { log: [] },
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: 1,
+    };
+}
+/**
+ * Consumer half of the coordination primitive — the non-clobbering merge. Resolves
+ * the mission by `findByMissionKey`; appends the incoming intent to
+ * `coordination.log` stamped `origin:imported` WITHOUT touching first-party
+ * `learnings`/`notes`/`status`; applies the bounded assignee effect (only `accept`
+ * sets it; a `handoff` never forces it; conflicts are last-writer-wins by
+ * `issuedAt`); NEVER recomputes status / participants / trust / standing; the
+ * source agent's trust caps acceptance; seeds an unknown mission only when a
+ * friend/family peer introduces it.
+ */
+async function importCoordination(missions, input, options = {}) {
+    const verifier = options.verifier ?? verifier_1.DEFAULT_AGENT_VERIFIER;
+    const minTrust = options.minTrustToAccept ?? "acquaintance";
+    // Authentication (caller's seam) AND authorization (trust ladder) must BOTH pass.
+    const authenticated = verifier.verify(input.fromAgentId, input.envelope.proof);
+    const trustedEnough = TRUST_RANK[input.trustOfSource] >= TRUST_RANK[minTrust];
+    if (!authenticated || !trustedEnough) {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.coordination_refused",
+            message: "refused coordination from untrusted source",
+            meta: { fromAgentId: input.fromAgentId, trustOfSource: input.trustOfSource, authenticated },
+        });
+        return { ok: false, status: "untrusted_source" };
+    }
+    const now = new Date().toISOString();
+    const existing = await missions.findByMissionKey(input.envelope.subject.missionKey);
+    if (!existing) {
+        // Unknown mission. Only a friend/family peer may seed a new one.
+        if (!SEEDING_TRUST.has(input.trustOfSource)) {
+            return { ok: false, status: "untrusted_introduction" };
+        }
+        const seeded = seedMission(input.envelope, now);
+        const { record: withIntent, assigned } = applyIncomingIntent(seeded, input.envelope, input.fromAgentId, now);
+        await missions.put(withIntent.id, withIntent);
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.coordination_seeded",
+            message: "seeded new mission from coordination",
+            meta: { missionId: withIntent.id, fromAgentId: input.fromAgentId, intent: input.envelope.intent },
+        });
+        // A seeded mission reports `seeded` even when the intent was an accept (the
+        // record creation is the salient fact); `assigned` is reflected in the record.
+        void assigned;
+        return { ok: true, status: "seeded", record: withIntent };
+    }
+    const { record: updated, assigned } = applyIncomingIntent(existing, input.envelope, input.fromAgentId, now);
+    await missions.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.coordination_imported",
+        message: "imported coordination into existing mission",
+        meta: { missionId: updated.id, fromAgentId: input.fromAgentId, intent: input.envelope.intent, assigned },
+    });
+    return { ok: true, status: assigned ? "assigned" : "logged", record: updated };
+}

package/dist/file-bundle.d.ts

@@ -0,0 +1,12 @@
+import { FileFriendStore } from "./store-file";
+import { FileGrantStore } from "./grant-store-file";
+import { FileMissionStore } from "./mission-store-file";
+export interface FileBundle {
+    store: FileFriendStore;
+    grants: FileGrantStore;
+    missions: FileMissionStore;
+    friendsDir: string;
+    grantsDir: string;
+    missionsDir: string;
+}
+export declare function openFileBundle(friendsDir: string): FileBundle;

package/dist/file-bundle.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openFileBundle = openFileBundle;
+// openFileBundle — one-liner wiring of a bundle's friends dir into the two file
+// stores, encapsulating the sibling `_grants/` convention. Additive ergonomics;
+// the explicit two-store construction stays exported and unchanged.
+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 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);
+    (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),
+        friendsDir,
+        grantsDir,
+        missionsDir,
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { GrantStore } from "./grant-store";
+import type { ShareGrant } from "./types";
+/** The sibling grants directory for a given friends directory: `<friendsDir>/_grants`.
+ * The collection lives UNDER the friends dir (a reserved `_`-prefixed subdir) so a
+ * single `--dir` still points the whole substrate at one place. */
+export declare function grantsDirFor(friendsDir: string): string;
+export declare class FileGrantStore implements GrantStore {
+    private readonly grantsPath;
+    constructor(grantsPath: string);
+    get(id: string): Promise<ShareGrant | null>;
+    put(id: string, grant: ShareGrant): Promise<void>;
+    delete(id: string): Promise<void>;
+    listAll(): Promise<ShareGrant[]>;
+    private normalize;
+    private readJson;
+}

package/dist/grant-store-file.js

@@ -0,0 +1,136 @@
+"use strict";
+// FileGrantStore — filesystem adapter for GrantStore.
+// Stores each ShareGrant as one JSON file in a sibling `_grants/` collection next
+// to the friends directory. Mirrors FileFriendStore's structure (mkdir on
+// construct, one file per record, guarded reads) so the two stores feel uniform.
+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.FileGrantStore = void 0;
+exports.grantsDirFor = grantsDirFor;
+const fs = __importStar(require("fs"));
+const fsPromises = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const observability_1 = require("./observability");
+const types_1 = require("./types");
+/** The sibling grants directory for a given friends directory: `<friendsDir>/_grants`.
+ * The collection lives UNDER the friends dir (a reserved `_`-prefixed subdir) so a
+ * single `--dir` still points the whole substrate at one place. */
+function grantsDirFor(friendsDir) {
+    return path.join(friendsDir, "_grants");
+}
+class FileGrantStore {
+    grantsPath;
+    constructor(grantsPath) {
+        this.grantsPath = grantsPath;
+        fs.mkdirSync(grantsPath, { recursive: true });
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.grant_store_init",
+            message: "file grant store initialized",
+            meta: {},
+        });
+    }
+    async get(id) {
+        const grant = await this.readJson(path.join(this.grantsPath, `${id}.json`));
+        return grant ? this.normalize(grant) : null;
+    }
+    async put(id, grant) {
+        await fsPromises.writeFile(path.join(this.grantsPath, `${id}.json`), JSON.stringify(this.normalize(grant), null, 2), "utf-8");
+    }
+    async delete(id) {
+        try {
+            await fsPromises.unlink(path.join(this.grantsPath, `${id}.json`));
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return;
+            throw err;
+        }
+    }
+    async listAll() {
+        let entries;
+        try {
+            entries = await fsPromises.readdir(this.grantsPath);
+        }
+        catch {
+            /* v8 ignore next -- defensive: dir is mkdir'd in the constructor, so readdir
+               only throws if it's deleted mid-run; unreachable through the API @preserve */
+            return [];
+        }
+        const grants = [];
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const raw = await this.readJson(path.join(this.grantsPath, entry));
+            if (!raw)
+                continue;
+            grants.push(this.normalize(raw));
+        }
+        return grants;
+    }
+    normalize(raw) {
+        return {
+            id: raw.id,
+            // Fork D compat seam (a): on-disk schemaVersion-1 grants carry the legacy
+            // `subjectFriendId`; newer ones carry `subjectKey`. Read both, persist
+            // forward as `subjectKey` so the legacy field migrates on the next write.
+            subjectKey: raw.subjectKey ?? raw.subjectFriendId ?? "",
+            recipientAgentId: raw.recipientAgentId,
+            scope: (0, types_1.isShareScope)(raw.scope) ? raw.scope : "identity",
+            grantedAt: typeof raw.grantedAt === "string" ? raw.grantedAt : new Date().toISOString(),
+            ...(typeof raw.expiresAt === "string" ? { expiresAt: raw.expiresAt } : {}),
+            ...(typeof raw.revokedAt === "string" ? { revokedAt: raw.revokedAt } : {}),
+        };
+    }
+    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.FileGrantStore = FileGrantStore;

package/dist/grant-store.d.ts

@@ -0,0 +1,7 @@
+import type { ShareGrant } from "./types";
+export interface GrantStore {
+    get(id: string): Promise<ShareGrant | null>;
+    put(id: string, grant: ShareGrant): Promise<void>;
+    delete(id: string): Promise<void>;
+    listAll(): Promise<ShareGrant[]>;
+}

package/dist/grant-store.js

@@ -0,0 +1,8 @@
+"use strict";
+// Grant store abstraction.
+// Consent state (ShareGrant records) persists through GrantStore — a sibling to
+// FriendStore, mirroring its shape. Grants are many-to-many (one subject ↔ many
+// recipients ↔ many scopes) with their own lifecycle, so they live in their own
+// collection rather than on the friend record. No grant module imports `fs`
+// directly except the FileGrantStore adapter.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/grants.d.ts

@@ -0,0 +1,39 @@
+import type { GrantStore } from "./grant-store";
+import type { ShareGrant, ShareScope } from "./types";
+/** Whether a grant currently consents: not revoked, and not past its expiry as
+ * of `now`. The single source of truth for "effective", shared by the consent
+ * policies and the audit listing. */
+export declare function isGrantEffective(grant: ShareGrant, now?: Date): boolean;
+export interface GrantShareInput {
+    /** The subject whose data may be shared — a friend UUID, or a missionKey
+     * (Fork D: opaque subject key). */
+    subjectKey: string;
+    recipientAgentId: string;
+    scope: ShareScope;
+    /** Optional ISO expiry; absent ⇒ the grant never expires. */
+    expiresAt?: string;
+}
+/** Mint an explicit share grant. Returns the persisted ShareGrant. */
+export declare function grantShare(grants: GrantStore, input: GrantShareInput): Promise<ShareGrant>;
+export interface RevokeShareResult {
+    ok: boolean;
+    status: "revoked" | "not_found" | "noop";
+    grant?: ShareGrant;
+}
+/** Revoke a grant by id. Tombstones it (sets `revokedAt`) rather than deleting,
+ * so the audit trail survives. Re-revoking an already-revoked grant is a noop. */
+export declare function revokeShare(grants: GrantStore, grantId: string): Promise<RevokeShareResult>;
+export interface ListSharesFilter {
+    /** Filter to one subject (a friend UUID, or a missionKey). */
+    subjectKey?: string;
+    recipientAgentId?: string;
+    /** When true, only grants that currently consent (effective) are returned. */
+    effectiveOnly?: boolean;
+}
+export interface ListedShare extends ShareGrant {
+    /** Whether this grant currently consents (not revoked, not expired). */
+    effective: boolean;
+}
+/** List grants with their effective state, optionally filtered by subject /
+ * recipient / effectiveness. The inspect-and-revoke surface. */
+export declare function listShares(grants: GrantStore, filter?: ListSharesFilter): Promise<ListedShare[]>;

package/dist/grants.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGrantEffective = isGrantEffective;
+exports.grantShare = grantShare;
+exports.revokeShare = revokeShare;
+exports.listShares = listShares;
+// Consent-grant lifecycle — grantShare / revokeShare / listShares.
+//
+// The audit + revoke surface over a GrantStore (the GDPR / right-to-be-forgotten
+// seam). `grantShare` mints an explicit ShareGrant; `revokeShare` tombstones one
+// (sets `revokedAt` rather than deleting, so the audit trail survives);
+// `listShares` returns grants with their effective state for inspection. The
+// consent policies in `consent.ts` read these grants to decide whether a share is
+// permitted — this module owns their CRUD, not the permission decision.
+const node_crypto_1 = require("node:crypto");
+const observability_1 = require("./observability");
+/** Whether a grant currently consents: not revoked, and not past its expiry as
+ * of `now`. The single source of truth for "effective", shared by the consent
+ * policies and the audit listing. */
+function isGrantEffective(grant, now = new Date()) {
+    if (grant.revokedAt)
+        return false;
+    if (grant.expiresAt && Date.parse(grant.expiresAt) <= now.getTime())
+        return false;
+    return true;
+}
+/** Mint an explicit share grant. Returns the persisted ShareGrant. */
+async function grantShare(grants, input) {
+    const now = new Date().toISOString();
+    const grant = {
+        id: (0, node_crypto_1.randomUUID)(),
+        subjectKey: input.subjectKey,
+        recipientAgentId: input.recipientAgentId,
+        scope: input.scope,
+        grantedAt: now,
+        ...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
+    };
+    await grants.put(grant.id, grant);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.share_granted",
+        message: "granted profile share",
+        meta: { subjectKey: input.subjectKey, recipientAgentId: input.recipientAgentId, scope: input.scope },
+    });
+    return grant;
+}
+/** Revoke a grant by id. Tombstones it (sets `revokedAt`) rather than deleting,
+ * so the audit trail survives. Re-revoking an already-revoked grant is a noop. */
+async function revokeShare(grants, grantId) {
+    const grant = await grants.get(grantId);
+    if (!grant) {
+        return { ok: false, status: "not_found" };
+    }
+    if (grant.revokedAt) {
+        return { ok: true, status: "noop", grant };
+    }
+    const revoked = { ...grant, revokedAt: new Date().toISOString() };
+    await grants.put(revoked.id, revoked);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.share_revoked",
+        message: "revoked profile share",
+        meta: { grantId },
+    });
+    return { ok: true, status: "revoked", grant: revoked };
+}
+/** List grants with their effective state, optionally filtered by subject /
+ * recipient / effectiveness. The inspect-and-revoke surface. */
+async function listShares(grants, filter = {}) {
+    const all = await grants.listAll();
+    const now = new Date();
+    const listed = all
+        .filter((g) => filter.subjectKey === undefined || g.subjectKey === filter.subjectKey)
+        .filter((g) => filter.recipientAgentId === undefined || g.recipientAgentId === filter.recipientAgentId)
+        .map((g) => ({ ...g, effective: isGrantEffective(g, now) }))
+        .filter((g) => filter.effectiveOnly !== true || g.effective);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.shares_listed",
+        message: "listed profile shares",
+        meta: { count: listed.length },
+    });
+    return listed;
+}

package/dist/group-context.d.ts

@@ -0,0 +1,21 @@
+import type { FriendStore } from "./store";
+import type { TrustLevel } from "./types";
+export interface GroupContextParticipant {
+    provider: "imessage-handle" | "aad" | "teams-conversation";
+    externalId: string;
+    displayName?: string;
+}
+export interface GroupContextUpsertResult {
+    friendId: string;
+    name: string;
+    trustLevel: TrustLevel;
+    created: boolean;
+    updated: boolean;
+    addedGroupExternalId: boolean;
+}
+export declare function upsertGroupContextParticipants(input: {
+    store: FriendStore;
+    participants: GroupContextParticipant[];
+    groupExternalId: string;
+    now?: () => string;
+}): Promise<GroupContextUpsertResult[]>;