cursedbelt-server 1.0.0

package/src/server/sharing/store.ts

@@ -0,0 +1,737 @@
+/**
+ * The store: grants, groups, revocation and the audit trail, over `bun:sqlite`.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * ```ts
+ * const shares = createShareStore({ db, app: "family", onEvent: notify });
+ *
+ * shares.grant({ kind: "person", id, subject: user("aunt@example.com"),
+ *                level: "read", grantedBy: viewer.email });
+ * shares.accessFor({ kind: "person", id }, { subjectId: viewer.email }); // "read"
+ * shares.revoke({ kind: "person", id, subject: user("aunt@example.com"),
+ *                 revokedBy: viewer.email });
+ * ```
+ * …and inside the app's own queries, `sharedResourceSql` (see `./sql.ts`) is the
+ * WHERE clause, so a filtered row never surfaces as a count either.
+ *
+ * ── 🔴 Five properties this file exists to guarantee ────────────────────────
+ *  1. **Every mutation writes its own audit row, in the same transaction.** There
+ *     is no `recordEvent` in the public API and no way to grant without logging.
+ *     An audit trail a caller has to remember to write is a trail with holes
+ *     exactly where somebody was in a hurry.
+ *  2. **A revoked grant's history survives it.** Revocation deletes the grant row
+ *     and appends an event; nothing here deletes an event, ever.
+ *  3. **Deleting the RESOURCE is a revocation, not an orphan.** `revokeResource`
+ *     exists so an app deleting a row has one call to make. A grant left behind
+ *     for a deleted id silently becomes access to whatever later reuses that id.
+ *  4. **The notification hook cannot break a write.** `onEvent` runs AFTER the
+ *     transaction commits and its throw is swallowed with a warning: a mail server
+ *     being down must not lose the grant the owner just made.
+ *  5. **A subject is normalized once, here.** Callers pass whatever the form gave
+ *     them; `normalizeSubjectId` is applied on the way in AND on the way to a
+ *     lookup, so a grant made to `"  Ameena@Example.com "` is found by the session
+ *     that signs in as `ameena@example.com`.
+ */
+import type { Database } from "bun:sqlite";
+import {
+	type ShareAccess,
+	type ShareAction,
+	type ShareEvent,
+	type ShareGrant,
+	type ShareGroup,
+	type ShareGroupMember,
+	type ShareLevel,
+	type ShareResource,
+	type ShareSubject,
+	type ShareViewer,
+	levelsMeeting,
+	normalizeSubjectId,
+	strongerAccess,
+} from "cursedbelt-core/sharing/model";
+import { runMigrations } from "../migration/runner";
+import {
+	SHARE_EVENTS_TABLE,
+	SHARE_GRANTS_TABLE,
+	SHARE_GROUPS_TABLE,
+	SHARE_GROUP_MEMBERS_TABLE,
+	SHARE_MIGRATIONS,
+} from "./migrations";
+import { sharedResourceSql } from "./sql";
+
+/** Shorthand for the common subject. `group(id)` is its sibling. */
+export const user = (id: string): ShareSubject => ({ type: "user", id });
+export const group = (id: string): ShareSubject => ({ type: "group", id });
+
+/** A resource within the store's own app — the `app` half is supplied by the
+ *  store, so a caller cannot mistakenly write a grant into another app's rows. */
+export interface ShareTarget {
+	kind: string;
+	id: string;
+}
+
+export interface ShareStoreOptions {
+	db: Database;
+	/** The satellite this store speaks for. Fixed at construction so `app` cannot
+	 *  be got wrong per call — the commonest way a grant becomes invisible. */
+	app: string;
+	/**
+	 * Notified after every committed mutation — the notification hook ca's model
+	 * had, as a seam rather than a dependency.
+	 *
+	 * 🔴 It stays a seam now that the other half EXISTS. `cursedbelt/server/
+	 * notifications` landed the same day this did, so a consumer can wire the two
+	 * in one line — `onEvent: (e) => notifications.notify({ userId: e.subject.id,
+	 * … })` — and `describeShareEvent` in the vocabulary is the wording both the
+	 * panel and that notification use. What must NOT happen is this store
+	 * importing that one: an app is entitled to a sharing model with no bell (the
+	 * grant is still audited), the subject of a GROUP grant is a group id and not
+	 * a person to notify, and an app knows which of its users to address where
+	 * this primitive only knows a subject id.
+	 */
+	onEvent?: (event: ShareEvent) => void;
+	/** Injectable clock, for tests that assert ordering. ISO-8601 strings. */
+	now?: () => string;
+}
+
+interface GrantRow {
+	app: string;
+	kind: string;
+	resource_id: string;
+	subject_type: "user" | "group";
+	subject_id: string;
+	level: ShareLevel;
+	granted_by: string;
+	granted_at: string;
+	note: string;
+}
+
+interface EventRow {
+	event_id: number;
+	at: string;
+	action: ShareAction;
+	app: string | null;
+	kind: string | null;
+	resource_id: string | null;
+	subject_type: "user" | "group";
+	subject_id: string;
+	level: ShareLevel | null;
+	previous_level: ShareLevel | null;
+	actor: string;
+	note: string;
+}
+
+const toGrant = (row: GrantRow): ShareGrant => ({
+	resource: { app: row.app, kind: row.kind, id: row.resource_id },
+	subject: { type: row.subject_type, id: row.subject_id },
+	level: row.level,
+	grantedBy: row.granted_by,
+	grantedAt: row.granted_at,
+	note: row.note,
+});
+
+const toEvent = (row: EventRow): ShareEvent => ({
+	id: row.event_id,
+	at: row.at,
+	action: row.action,
+	resource:
+		row.app === null || row.kind === null || row.resource_id === null
+			? null
+			: { app: row.app, kind: row.kind, id: row.resource_id },
+	subject: { type: row.subject_type, id: row.subject_id },
+	level: row.level,
+	previousLevel: row.previous_level,
+	actor: row.actor,
+	note: row.note,
+});
+
+export interface GrantInput extends ShareTarget {
+	subject: ShareSubject;
+	level: ShareLevel;
+	grantedBy: string;
+	note?: string;
+}
+
+export interface RevokeInput extends ShareTarget {
+	subject: ShareSubject;
+	revokedBy: string;
+	note?: string;
+}
+
+export interface ShareEventQuery {
+	kind?: string;
+	id?: string;
+	subject?: ShareSubject;
+	/** Newest first, capped. Default 200 — a panel shows a page, and an unbounded
+	 *  audit read on a busy resource is the query that times out in production. */
+	limit?: number;
+}
+
+export type ShareStore = ReturnType<typeof createShareStore>;
+
+/**
+ * Open (and migrate) the sharing tables in this database, returning the store.
+ *
+ * Idempotent: safe to call once per boot per `db`, and safe to call in a database
+ * that already has the tables (the migration runner records what it applied).
+ */
+export function createShareStore(options: ShareStoreOptions) {
+	const { db, app } = options;
+	const clock = options.now ?? (() => new Date().toISOString());
+	if (!app.trim()) throw new Error("[cursedbelt-core/sharing] a share store needs an `app`");
+	runMigrations(db, SHARE_MIGRATIONS);
+
+	/** Collected inside a transaction, delivered after it commits — see property 4
+	 *  in the file header. */
+	const emit = (events: readonly ShareEvent[]): void => {
+		const hook = options.onEvent;
+		if (!hook) return;
+		for (const event of events) {
+			try {
+				hook(event);
+			} catch (error) {
+				console.warn(`[cursedbelt-core/sharing] a share-event listener threw: ${String(error)}`);
+			}
+		}
+	};
+
+	const recordEvent = (input: {
+		action: ShareAction;
+		resource: ShareResource | null;
+		subject: ShareSubject;
+		level: ShareLevel | null;
+		previousLevel?: ShareLevel | null;
+		actor: string;
+		note?: string;
+		at: string;
+	}): ShareEvent => {
+		db.query(
+			`INSERT INTO ${SHARE_EVENTS_TABLE}
+			   (at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			input.at,
+			input.action,
+			input.resource?.app ?? null,
+			input.resource?.kind ?? null,
+			input.resource?.id ?? null,
+			input.subject.type,
+			input.subject.id,
+			input.level,
+			input.previousLevel ?? null,
+			input.actor,
+			input.note ?? "",
+		);
+		const id = (db.query("SELECT last_insert_rowid() AS id").get() as { id: number }).id;
+		return {
+			id,
+			at: input.at,
+			action: input.action,
+			resource: input.resource,
+			subject: input.subject,
+			level: input.level,
+			previousLevel: input.previousLevel ?? null,
+			actor: input.actor,
+			note: input.note ?? "",
+		};
+	};
+
+	const normalized = (subject: ShareSubject): ShareSubject => ({
+		type: subject.type,
+		id: normalizeSubjectId(subject.type, subject.id),
+	});
+
+	const readGrant = (target: ShareTarget, subject: ShareSubject): ShareGrant | null => {
+		const row = db
+			.query(
+				`SELECT * FROM ${SHARE_GRANTS_TABLE}
+				 WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?`,
+			)
+			.get(app, target.kind, target.id, subject.type, subject.id) as GrantRow | null;
+		return row ? toGrant(row) : null;
+	};
+
+	return {
+		/** The app this store speaks for — exposed so a consumer can build its own
+		 *  `sharedResourceSql` call without re-declaring the name. */
+		app,
+
+		/**
+		 * Give `subject` access to a resource, or change the access they have.
+		 *
+		 * An unchanged re-grant is still recorded as a `grant` event: "the owner
+		 * confirmed this on Tuesday" is a fact somebody reading the trail wants, and
+		 * suppressing it would make an idempotent API silently unauditable.
+		 */
+		grant(input: GrantInput): ShareGrant {
+			const subject = normalized(input.subject);
+			if (!subject.id) throw new Error("[cursedbelt-core/sharing] a grant needs a subject");
+			if (!input.id) throw new Error("[cursedbelt-core/sharing] a grant needs a resource id");
+			const at = clock();
+			const events: ShareEvent[] = [];
+			const grant = db.transaction((): ShareGrant => {
+				const existing = readGrant(input, subject);
+				db.query(
+					`INSERT INTO ${SHARE_GRANTS_TABLE}
+					   (app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note)
+					 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+					 ON CONFLICT (app, kind, resource_id, subject_type, subject_id)
+					 DO UPDATE SET level = excluded.level, granted_by = excluded.granted_by,
+					               granted_at = excluded.granted_at, note = excluded.note`,
+				).run(
+					app,
+					input.kind,
+					input.id,
+					subject.type,
+					subject.id,
+					input.level,
+					input.grantedBy,
+					at,
+					input.note ?? "",
+				);
+				const resource: ShareResource = { app, kind: input.kind, id: input.id };
+				events.push(
+					recordEvent({
+						action: existing && existing.level !== input.level ? "regrade" : "grant",
+						resource,
+						subject,
+						level: input.level,
+						previousLevel: existing && existing.level !== input.level ? existing.level : null,
+						actor: input.grantedBy,
+						note: input.note,
+						at,
+					}),
+				);
+				return {
+					resource,
+					subject,
+					level: input.level,
+					grantedBy: input.grantedBy,
+					grantedAt: at,
+					note: input.note ?? "",
+				};
+			})();
+			emit(events);
+			return grant;
+		},
+
+		/** Take access away. Returns the level that was removed, or null when there
+		 *  was nothing to remove — in which case nothing is logged, because an audit
+		 *  trail full of "revoked nothing" is one nobody reads. */
+		revoke(input: RevokeInput): ShareLevel | null {
+			const subject = normalized(input.subject);
+			const at = clock();
+			const events: ShareEvent[] = [];
+			const removed = db.transaction((): ShareLevel | null => {
+				const existing = readGrant(input, subject);
+				if (!existing) return null;
+				db.query(
+					`DELETE FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?`,
+				).run(app, input.kind, input.id, subject.type, subject.id);
+				events.push(
+					recordEvent({
+						action: "revoke",
+						resource: { app, kind: input.kind, id: input.id },
+						subject,
+						level: existing.level,
+						actor: input.revokedBy,
+						note: input.note,
+						at,
+					}),
+				);
+				return existing.level;
+			})();
+			emit(events);
+			return removed;
+		},
+
+		/**
+		 * Revoke EVERY grant on one resource — what an app calls when it deletes the
+		 * record. Returns how many were removed.
+		 *
+		 * 🔴 Not optional housekeeping. Resource ids are app-minted, and a grant left
+		 * behind for a deleted id becomes access to whatever is created with that id
+		 * later. `apps/family` calls this in the same transaction as deleting a
+		 * person.
+		 */
+		revokeResource(target: ShareTarget, revokedBy: string): number {
+			const at = clock();
+			const events: ShareEvent[] = [];
+			const count = db.transaction((): number => {
+				const rows = db
+					.query(`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND kind = ? AND resource_id = ?`)
+					.all(app, target.kind, target.id) as GrantRow[];
+				if (rows.length === 0) return 0;
+				db.query(
+					`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND kind = ? AND resource_id = ?`,
+				).run(app, target.kind, target.id);
+				for (const row of rows) {
+					events.push(
+						recordEvent({
+							action: "revoke",
+							resource: { app, kind: row.kind, id: row.resource_id },
+							subject: { type: row.subject_type, id: row.subject_id },
+							level: row.level,
+							actor: revokedBy,
+							note: "the record was deleted",
+							at,
+						}),
+					);
+				}
+				return rows.length;
+			})();
+			emit(events);
+			return count;
+		},
+
+		/** Revoke everything shared with one subject, across every kind — the
+		 *  offboarding call. A person losing their fleet account keeps nothing. */
+		revokeSubject(subject: ShareSubject, revokedBy: string): number {
+			const normal = normalized(subject);
+			const at = clock();
+			const events: ShareEvent[] = [];
+			const count = db.transaction((): number => {
+				const rows = db
+					.query(
+						`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = ? AND subject_id = ?`,
+					)
+					.all(app, normal.type, normal.id) as GrantRow[];
+				if (rows.length === 0) return 0;
+				db.query(
+					`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = ? AND subject_id = ?`,
+				).run(app, normal.type, normal.id);
+				for (const row of rows) {
+					events.push(
+						recordEvent({
+							action: "revoke",
+							resource: { app, kind: row.kind, id: row.resource_id },
+							subject: normal,
+							level: row.level,
+							actor: revokedBy,
+							note: "every share with this subject was revoked",
+							at,
+						}),
+					);
+				}
+				return rows.length;
+			})();
+			emit(events);
+			return count;
+		},
+
+		/** Who can see this record, strongest first then oldest — the panel's read. */
+		listForResource(target: ShareTarget): ShareGrant[] {
+			const rows = db
+				.query(
+					`SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND resource_id = ?
+					 -- Strongest first, then oldest. Spelled as a CASE rather than an
+					 -- ORDER BY on level, which happens to work only because 'write'
+					 -- sorts after 'read' and would silently mis-order a third level.
+					 ORDER BY CASE level WHEN 'write' THEN 0 ELSE 1 END, granted_at ASC`,
+				)
+				.all(app, target.kind, target.id) as GrantRow[];
+			return rows.map(toGrant);
+		},
+
+		/** Everything shared with one subject — "shared with you". Group grants are
+		 *  NOT expanded here; use {@link resourceIdsFor} for the resolved answer. */
+		listForSubject(subject: ShareSubject): ShareGrant[] {
+			const normal = normalized(subject);
+			const rows = db
+				.query(
+					`SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND subject_type = ? AND subject_id = ?
+					 ORDER BY granted_at DESC`,
+				)
+				.all(app, normal.type, normal.id) as GrantRow[];
+			return rows.map(toGrant);
+		},
+
+		/**
+		 * What may this viewer do with this resource — the resolver.
+		 *
+		 * The strongest of their own grant and every group they are in, computed in
+		 * SQL. `resolveAccess` in `cursedbelt-core/sharing` is the same rule written as a
+		 * pure function, and `store.spec.ts` checks the two agree.
+		 */
+		accessFor(target: ShareTarget, viewer: ShareViewer): ShareAccess {
+			const subjectId = normalizeSubjectId("user", viewer.subjectId);
+			if (!subjectId) return "none";
+			const rows = db
+				.query(
+					`SELECT level FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND resource_id = ?
+					   AND ( (subject_type = 'user' AND subject_id = ?)
+					      OR (subject_type = 'group' AND subject_id IN
+					          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )`,
+				)
+				.all(app, target.kind, target.id, subjectId, subjectId) as { level: ShareLevel }[];
+			let access: ShareAccess = "none";
+			for (const row of rows) access = strongerAccess(access, row.level);
+			return access;
+		},
+
+		/** Every resource of `kind` this viewer reaches at `atLeast` or above.
+		 *  For filtering rows in the app's OWN query, prefer `sharedResourceSql`. */
+		resourceIdsFor(kind: string, viewer: ShareViewer, atLeast: ShareLevel = "read"): string[] {
+			const subjectId = normalizeSubjectId("user", viewer.subjectId);
+			if (!subjectId) return [];
+			const levels = levelsMeeting(atLeast);
+			const rows = db
+				.query(
+					`SELECT DISTINCT resource_id FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND level IN (${levels.map(() => "?").join(", ")})
+					   AND ( (subject_type = 'user' AND subject_id = ?)
+					      OR (subject_type = 'group' AND subject_id IN
+					          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )
+					 ORDER BY resource_id`,
+				)
+				.all(app, kind, ...levels, subjectId, subjectId) as { resource_id: string }[];
+			return rows.map((row) => row.resource_id);
+		},
+
+		/** The WHERE-clause half, bound to this store's app. See `./sql.ts` for why
+		 *  a fragment rather than a list of ids. */
+		sharedSql(input: { kind: string; subjectId: string; column: string; atLeast?: ShareLevel }): string {
+			return sharedResourceSql({ app, ...input });
+		},
+
+		// ── Groups ───────────────────────────────────────────────────────────────
+
+		createGroup(input: { id: string; name: string; createdBy: string; note?: string }): ShareGroup {
+			const id = normalizeSubjectId("group", input.id);
+			if (!id) throw new Error("[cursedbelt-core/sharing] a group needs an id");
+			const at = clock();
+			const events: ShareEvent[] = [];
+			const created = db.transaction((): ShareGroup => {
+				db.query(
+					`INSERT INTO ${SHARE_GROUPS_TABLE} (group_id, name, created_by, created_at, note)
+					 VALUES (?, ?, ?, ?, ?)
+					 ON CONFLICT (group_id) DO UPDATE SET name = excluded.name, note = excluded.note`,
+				).run(id, input.name, input.createdBy, at, input.note ?? "");
+				events.push(
+					recordEvent({
+						action: "group.create",
+						resource: null,
+						subject: { type: "group", id },
+						level: null,
+						actor: input.createdBy,
+						note: input.name,
+						at,
+					}),
+				);
+				return {
+					id,
+					name: input.name,
+					createdBy: input.createdBy,
+					createdAt: at,
+					note: input.note ?? "",
+				};
+			})();
+			emit(events);
+			return created;
+		},
+
+		renameGroup(id: string, name: string, actor: string): void {
+			const groupId = normalizeSubjectId("group", id);
+			const at = clock();
+			const events: ShareEvent[] = [];
+			db.transaction(() => {
+				db.query(`UPDATE ${SHARE_GROUPS_TABLE} SET name = ? WHERE group_id = ?`).run(name, groupId);
+				events.push(
+					recordEvent({
+						action: "group.rename",
+						resource: null,
+						subject: { type: "group", id: groupId },
+						level: null,
+						actor,
+						note: name,
+						at,
+					}),
+				);
+			})();
+			emit(events);
+		},
+
+		/**
+		 * Delete a group — and every grant made TO it.
+		 *
+		 * 🔴 The grants go with it, explicitly, each with its own revoke event. The
+		 * `ON DELETE CASCADE` on membership does not reach `share_grants` (a group
+		 * subject is a string, not a foreign key, because the same column holds user
+		 * addresses), so a group deleted without this leaves rows nobody can see in
+		 * any UI and nothing can revoke.
+		 */
+		deleteGroup(id: string, actor: string): void {
+			const groupId = normalizeSubjectId("group", id);
+			const at = clock();
+			const events: ShareEvent[] = [];
+			db.transaction(() => {
+				const grants = db
+					.query(
+						`SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = 'group' AND subject_id = ?`,
+					)
+					.all(app, groupId) as GrantRow[];
+				db.query(
+					`DELETE FROM ${SHARE_GRANTS_TABLE} WHERE app = ? AND subject_type = 'group' AND subject_id = ?`,
+				).run(app, groupId);
+				for (const row of grants) {
+					events.push(
+						recordEvent({
+							action: "revoke",
+							resource: { app, kind: row.kind, id: row.resource_id },
+							subject: { type: "group", id: groupId },
+							level: row.level,
+							actor,
+							note: "the group was deleted",
+							at,
+						}),
+					);
+				}
+				db.query(`DELETE FROM ${SHARE_GROUPS_TABLE} WHERE group_id = ?`).run(groupId);
+				events.push(
+					recordEvent({
+						action: "group.delete",
+						resource: null,
+						subject: { type: "group", id: groupId },
+						level: null,
+						actor,
+						note: "",
+						at,
+					}),
+				);
+			})();
+			emit(events);
+		},
+
+		listGroups(): ShareGroup[] {
+			const rows = db
+				.query(`SELECT * FROM ${SHARE_GROUPS_TABLE} ORDER BY name`)
+				.all() as {
+				group_id: string;
+				name: string;
+				created_by: string;
+				created_at: string;
+				note: string;
+			}[];
+			return rows.map((row) => ({
+				id: row.group_id,
+				name: row.name,
+				createdBy: row.created_by,
+				createdAt: row.created_at,
+				note: row.note,
+			}));
+		},
+
+		addGroupMember(groupId: string, subjectId: string, actor: string): void {
+			const id = normalizeSubjectId("group", groupId);
+			const member = normalizeSubjectId("user", subjectId);
+			if (!member) throw new Error("[cursedbelt-core/sharing] a group member needs an address");
+			const at = clock();
+			const events: ShareEvent[] = [];
+			db.transaction(() => {
+				db.query(
+					`INSERT INTO ${SHARE_GROUP_MEMBERS_TABLE} (group_id, subject_id, added_by, added_at)
+					 VALUES (?, ?, ?, ?) ON CONFLICT (group_id, subject_id) DO NOTHING`,
+				).run(id, member, actor, at);
+				events.push(
+					recordEvent({
+						action: "group.join",
+						resource: null,
+						subject: { type: "group", id },
+						level: null,
+						actor,
+						note: member,
+						at,
+					}),
+				);
+			})();
+			emit(events);
+		},
+
+		removeGroupMember(groupId: string, subjectId: string, actor: string): void {
+			const id = normalizeSubjectId("group", groupId);
+			const member = normalizeSubjectId("user", subjectId);
+			const at = clock();
+			const events: ShareEvent[] = [];
+			db.transaction(() => {
+				db.query(
+					`DELETE FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? AND subject_id = ?`,
+				).run(id, member);
+				events.push(
+					recordEvent({
+						action: "group.leave",
+						resource: null,
+						subject: { type: "group", id },
+						level: null,
+						actor,
+						note: member,
+						at,
+					}),
+				);
+			})();
+			emit(events);
+		},
+
+		listGroupMembers(groupId: string): ShareGroupMember[] {
+			const rows = db
+				.query(
+					`SELECT * FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? ORDER BY subject_id`,
+				)
+				.all(normalizeSubjectId("group", groupId)) as {
+				group_id: string;
+				subject_id: string;
+				added_by: string;
+				added_at: string;
+			}[];
+			return rows.map((row) => ({
+				groupId: row.group_id,
+				subjectId: row.subject_id,
+				addedBy: row.added_by,
+				addedAt: row.added_at,
+			}));
+		},
+
+		/** Which groups is this person in — the one place membership is resolved. */
+		groupIdsFor(subjectId: string): string[] {
+			const member = normalizeSubjectId("user", subjectId);
+			if (!member) return [];
+			const rows = db
+				.query(
+					`SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ? ORDER BY group_id`,
+				)
+				.all(member) as { group_id: string }[];
+			return rows.map((row) => row.group_id);
+		},
+
+		// ── The audit trail ──────────────────────────────────────────────────────
+
+		/** The trail, newest first. Filter by resource, by subject, or neither. */
+		events(query: ShareEventQuery = {}): ShareEvent[] {
+			const clauses = ["app IS NULL OR app = ?"];
+			const params: (string | number)[] = [app];
+			if (query.kind !== undefined) {
+				clauses.push("kind = ?");
+				params.push(query.kind);
+			}
+			if (query.id !== undefined) {
+				clauses.push("resource_id = ?");
+				params.push(query.id);
+			}
+			if (query.subject) {
+				const normal = normalized(query.subject);
+				clauses.push("subject_type = ? AND subject_id = ?");
+				params.push(normal.type, normal.id);
+			}
+			const where = clauses.map((clause) => `(${clause})`).join(" AND ");
+			const limit = Math.max(1, Math.min(query.limit ?? 200, 1000));
+			const rows = db
+				.query(
+					`SELECT * FROM ${SHARE_EVENTS_TABLE} WHERE ${where} ORDER BY event_id DESC LIMIT ?`,
+				)
+				.all(...params, limit) as EventRow[];
+			return rows.map(toEvent);
+		},
+	};
+}