cursedbelt-server 4.26.1 → 4.28.0

package/src/server/sharing/d1.spec.ts

@@ -0,0 +1,242 @@
+/**
+ * The D1 share store is the sync store, asynchronously — the SAME results for the same calls,
+ * and the SAME rows in the SAME four tables, so a database moved from the Mac to D1 keeps
+ * meaning what it meant (task 393, `apps/family`).
+ *
+ * The parity scenario runs one script of calls through both stores, each over its own fresh
+ * database with the same clock, and compares every call's result and then every table. It
+ * runs twice: over `createLocalD1` (the local driver) and over `createRemoteD1` on the
+ * divergence-simulating fake binding, which refuses `undefined`/`boolean` binds exactly as
+ * D1 does — a store that bound either would pass locally and fail here.
+ */
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { createFakeD1Binding } from "../d1/fakeD1.js";
+import { createLocalD1 } from "../d1/local.js";
+import { createRemoteD1 } from "../d1/remote.js";
+import type { D1LikeDatabase } from "../d1/types.js";
+import { runMigrations } from "../migration/runner.js";
+import { type AsyncShareStore, createD1ShareStore, group, SHARE_DDL, user } from "./d1.js";
+import { SHARE_MIGRATIONS } from "./migrations.js";
+import { mountShareRoutes } from "./router.js";
+import { createShareStore, type ShareStore } from "./store.js";
+
+const APP = "family";
+const OWNER = "owner@example.com";
+
+/** A monotonic clock, one second per call, identical for both stores. */
+const clock = () => {
+	let ticks = 0;
+	return () => new Date(Date.UTC(2026, 8, 24, 0, 0, ticks++)).toISOString();
+};
+
+const d1Database = (): Database => {
+	const sqlite = new Database(":memory:");
+	sqlite.exec("PRAGMA foreign_keys = ON"); // D1 enforces foreign keys; so does this.
+	for (const statement of SHARE_DDL) sqlite.run(statement);
+	return sqlite;
+};
+
+const DRIVERS: Record<string, (sqlite: Database) => D1LikeDatabase> = {
+	local: (sqlite) => createLocalD1(sqlite),
+	"remote (fake D1 binding)": (sqlite) => createRemoteD1(createFakeD1Binding(sqlite)),
+};
+
+const syncStore = (): { sqlite: Database; store: ShareStore } => {
+	const sqlite = new Database(":memory:");
+	sqlite.exec("PRAGMA foreign_keys = ON");
+	return { sqlite, store: createShareStore({ db: sqlite, app: APP, now: clock() }) };
+};
+
+const asyncStore = (driver: (sqlite: Database) => D1LikeDatabase) => {
+	const sqlite = d1Database();
+	return { sqlite, store: createD1ShareStore({ db: driver(sqlite), app: APP, now: clock() }) };
+};
+
+const dump = (db: Database) => ({
+	grants: db.query("SELECT * FROM share_grants ORDER BY grant_id").all(),
+	groups: db.query("SELECT * FROM share_groups ORDER BY group_id").all(),
+	members: db.query("SELECT * FROM share_group_members ORDER BY group_id, subject_id").all(),
+	events: db.query("SELECT * FROM share_events ORDER BY event_id").all(),
+});
+
+/**
+ * One script, both stores. Grants are made in an order chosen so the sync store's multi-row
+ * revokes read their grants in grant order, which is the D1 store's DEFINED order — the sync
+ * store's is whatever index its SELECT picks (for `revokeSubject`, kind then resource id).
+ * That is the one documented difference; see the header of `./d1.ts`.
+ */
+const SCENARIO: ReadonlyArray<(s: ShareStore | AsyncShareStore) => unknown> = [
+	(s) => s.createGroup({ id: " cousins ", name: "The cousins", createdBy: OWNER, note: "both sides" }),
+	(s) => s.addGroupMember("cousins", " Cousin@Example.com ", OWNER),
+	(s) => s.addGroupMember("cousins", "aunt@example.com", OWNER),
+	(s) => s.grant({ kind: "person", id: "p1", subject: group("cousins"), level: "read", grantedBy: OWNER }),
+	(s) => s.grant({ kind: "person", id: "p1", subject: user("  Aunt@Example.com "), level: "read", grantedBy: OWNER, note: "she asked" }),
+	(s) => s.grant({ kind: "person", id: "p1", subject: user("aunt@example.com"), level: "write", grantedBy: OWNER }),
+	(s) => s.grant({ kind: "person", id: "p1", subject: user("aunt@example.com"), level: "write", grantedBy: OWNER }),
+	(s) => s.grant({ kind: "person", id: "p2", subject: user("uncle@example.com"), level: "read", grantedBy: OWNER }),
+	(s) => s.grant({ kind: "budget", id: "b1", subject: user("aunt@example.com"), level: "write", grantedBy: OWNER }),
+	(s) => s.grant({ kind: "person", id: "p3", subject: user("aunt@example.com"), level: "read", grantedBy: OWNER }),
+	(s) => s.accessFor({ kind: "person", id: "p1" }, { subjectId: "AUNT@example.com" }),
+	(s) => s.accessFor({ kind: "person", id: "p1" }, { subjectId: "cousin@example.com" }),
+	(s) => s.accessFor({ kind: "person", id: "p2" }, { subjectId: "cousin@example.com" }),
+	(s) => s.accessFor({ kind: "person", id: "p1" }, { subjectId: "" }),
+	(s) => s.resourceIdsFor("person", { subjectId: "aunt@example.com" }),
+	(s) => s.resourceIdsFor("person", { subjectId: "aunt@example.com" }, "write"),
+	(s) => s.resourceIdsFor("person", { subjectId: "cousin@example.com" }),
+	(s) => s.resourceIdsFor("person", { subjectId: "  " }),
+	(s) => s.listForResource({ kind: "person", id: "p1" }),
+	(s) => s.listForSubject(user("AUNT@example.com")),
+	(s) => s.listGroups(),
+	(s) => s.listGroupMembers(" cousins "),
+	(s) => s.groupIdsFor("cousin@example.com"),
+	(s) => s.groupIdsFor(""),
+	(s) => s.revoke({ kind: "person", id: "p2", subject: user("uncle@example.com"), revokedBy: OWNER, note: "moved" }),
+	(s) => s.revoke({ kind: "person", id: "p2", subject: user("uncle@example.com"), revokedBy: OWNER }),
+	(s) => s.revokeResource({ kind: "person", id: "p1" }, OWNER),
+	(s) => s.revokeResource({ kind: "person", id: "nothing" }, OWNER),
+	(s) => s.grant({ kind: "person", id: "p4", subject: group("cousins"), level: "write", grantedBy: OWNER }),
+	(s) => s.renameGroup("cousins", "Cousins, all of them", OWNER),
+	(s) => s.removeGroupMember("cousins", "aunt@example.com", OWNER),
+	(s) => s.revokeSubject(user("aunt@example.com"), OWNER),
+	(s) => s.revokeSubject(user("nobody@example.com"), OWNER),
+	(s) => s.deleteGroup("cousins", OWNER),
+	(s) => s.events(),
+	(s) => s.events({ kind: "person", id: "p1", limit: 3 }),
+	(s) => s.events({ subject: user(" AUNT@example.com ") }),
+	(s) => s.events({ limit: 0 }),
+	(s) => s.sharedSql({ kind: "person", subjectId: "o'brien@example.com", column: "p.id", atLeast: "write" }),
+];
+
+describe("cursedbelt-server/sharing/d1", () => {
+	for (const [name, driver] of Object.entries(DRIVERS)) {
+		test(`🔴 parity over the ${name} driver: every result and every row match the sync store`, async () => {
+			const sync = syncStore();
+			const d1 = asyncStore(driver);
+			for (const [index, step] of SCENARIO.entries()) {
+				const expected = step(sync.store);
+				const actual = await step(d1.store);
+				expect({ step: index, result: actual }).toEqual({ step: index, result: expected });
+			}
+			expect(dump(d1.sqlite)).toEqual(dump(sync.sqlite));
+			// Not vacuous: the trail holds every kind of event the scenario exercised.
+			const actions = new Set(dump(d1.sqlite).events.map((e) => (e as { action: string }).action));
+			expect([...actions].sort()).toEqual(
+				["grant", "group.create", "group.delete", "group.join", "group.leave", "group.rename", "regrade", "revoke"].sort(),
+			);
+		});
+	}
+
+	test("exposes exactly the sync store's methods, and `sharedSql` stays synchronous", () => {
+		const sync = syncStore().store;
+		const d1 = asyncStore(DRIVERS.local as (s: Database) => D1LikeDatabase).store;
+		expect(Object.keys(d1).sort()).toEqual(Object.keys(sync).sort());
+		const input = { kind: "person", subjectId: "aunt@example.com", column: "id" };
+		expect(typeof d1.sharedSql(input)).toBe("string");
+		expect(d1.sharedSql(input)).toBe(sync.sharedSql(input));
+	});
+
+	test("SHARE_DDL builds exactly the tables and indexes the sync migration does", () => {
+		const shape = (db: Database) =>
+			db
+				.query("SELECT type, name, sql FROM sqlite_master WHERE name LIKE '%share%' AND sql IS NOT NULL ORDER BY name")
+				.all();
+		const migrated = new Database(":memory:");
+		runMigrations(migrated, SHARE_MIGRATIONS);
+		expect(shape(d1Database())).toEqual(shape(migrated));
+		expect(shape(migrated).length).toBe(9);
+	});
+
+	test("🔴 runs no DDL: on a database without the tables it creates nothing and fails loudly", async () => {
+		const sqlite = new Database(":memory:");
+		const shares = createD1ShareStore({ db: createLocalD1(sqlite), app: APP });
+		expect(sqlite.query("SELECT COUNT(*) AS n FROM sqlite_master").get()).toEqual({ n: 0 });
+		await expect(shares.listGroups()).rejects.toThrow(/no such table/);
+	});
+
+	test("🔴 a mutation is atomic: when the grant write fails, its audit row is not left behind", async () => {
+		const { sqlite, store } = asyncStore(DRIVERS.local as (s: Database) => D1LikeDatabase);
+		// The event insert runs FIRST and accepts any level; the grant's CHECK refuses this one.
+		// Only a real batch leaves neither row — a loop of awaits would leave the event.
+		await expect(
+			store.grant({
+				kind: "person",
+				id: "p1",
+				subject: user("aunt@example.com"),
+				level: "admin" as unknown as "read",
+				grantedBy: OWNER,
+			}),
+		).rejects.toThrow(/CHECK constraint/);
+		expect(dump(sqlite)).toEqual({ grants: [], groups: [], members: [], events: [] });
+	});
+
+	test("validation rejects, and writes nothing", async () => {
+		const { sqlite, store } = asyncStore(DRIVERS.local as (s: Database) => D1LikeDatabase);
+		await expect(
+			store.grant({ kind: "person", id: "p1", subject: user("   "), level: "read", grantedBy: OWNER }),
+		).rejects.toThrow(/needs a subject/);
+		await expect(
+			store.grant({ kind: "person", id: "", subject: user("a@example.com"), level: "read", grantedBy: OWNER }),
+		).rejects.toThrow(/needs a resource id/);
+		await expect(store.createGroup({ id: " ", name: "x", createdBy: OWNER })).rejects.toThrow(/needs an id/);
+		await expect(store.addGroupMember("g", " ", OWNER)).rejects.toThrow(/needs an address/);
+		expect(dump(sqlite)).toEqual({ grants: [], groups: [], members: [], events: [] });
+		expect(() => createD1ShareStore({ db: createLocalD1(sqlite), app: " " })).toThrow(/needs an `app`/);
+	});
+
+	test("the hook hears every committed mutation, and neither a throw nor a rejection loses the write", async () => {
+		const sqlite = d1Database();
+		const heard: string[] = [];
+		let mode: "ok" | "throw" | "reject" = "ok";
+		const store = createD1ShareStore({
+			db: createLocalD1(sqlite),
+			app: APP,
+			onEvent: (event) => {
+				heard.push(`${event.action}:${event.subject.id}`);
+				if (mode === "throw") throw new Error("the mail server is down");
+				if (mode === "reject") return Promise.reject(new Error("the mail server is still down"));
+			},
+		});
+		await store.grant({ kind: "person", id: "p1", subject: user("a@example.com"), level: "read", grantedBy: OWNER });
+		mode = "throw";
+		await store.grant({ kind: "person", id: "p1", subject: user("b@example.com"), level: "write", grantedBy: OWNER });
+		mode = "reject";
+		expect(await store.revokeResource({ kind: "person", id: "p1" }, OWNER)).toBe(2);
+		expect(heard).toEqual(["grant:a@example.com", "grant:b@example.com", "revoke:a@example.com", "revoke:b@example.com"]);
+		expect(await store.events({ kind: "person", id: "p1" })).toHaveLength(4);
+		expect(await store.listForResource({ kind: "person", id: "p1" })).toEqual([]);
+	});
+
+	test("mountShareRoutes serves the D1 store — read, grant, revoke by group path", async () => {
+		const { store } = asyncStore(DRIVERS.local as (s: Database) => D1LikeDatabase);
+		const app = new Hono();
+		mountShareRoutes(app, {
+			base: "/api/people/:id",
+			kind: "person",
+			shares: store,
+			viewerOf: () => ({ email: OWNER }),
+			mustOwn: () => null,
+			extra: async (_c, id) => ({ labels: { [id]: "Grandma" } }),
+		});
+		const post = await app.request("/api/people/p1/shares", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ subject: { type: "group", id: "cousins" }, level: "write" }),
+		});
+		expect(post.status).toBe(201);
+		expect(await post.json()).toMatchObject({ subject: { type: "group", id: "cousins" }, level: "write" });
+		const read = (await (await app.request("/api/people/p1/shares")).json()) as {
+			grants: unknown[];
+			events: unknown[];
+			labels: Record<string, string>;
+		};
+		expect(read.grants).toHaveLength(1);
+		expect(read.events).toHaveLength(1);
+		expect(read.labels).toEqual({ p1: "Grandma" });
+		const del = await app.request("/api/people/p1/shares/group%3Acousins", { method: "DELETE" });
+		expect(await del.json()).toEqual({ ok: true });
+		expect(await store.listForResource({ kind: "person", id: "p1" })).toEqual([]);
+		expect((await store.events({ kind: "person", id: "p1" }))[0]?.action).toBe("revoke");
+	});
+});

package/src/server/sharing/d1.ts

@@ -0,0 +1,430 @@
+/**
+ * `cursedbelt-server/sharing/d1` — the fleet's sharing model over D1, for an app a Worker serves.
+ *
+ * ── Why it exists ───────────────────────────────────────────────────────────
+ * `./store.ts` is synchronous `bun:sqlite`, and a Worker has neither. `apps/family`'s port to
+ * a Worker + D1 (task 393) needs the SAME grants, revokes, groups and audit trail, in the SAME
+ * four tables, so a database moved from the Mac to D1 keeps meaning what it meant. This is that
+ * store, beside the sync one — which stays exactly as it was, because `auth` and `station` are
+ * still Bun servers.
+ *
+ * ── What is the same, and what is not ─────────────────────────────────────
+ * Same methods, names, arguments, validation and results as `ShareStore`; every method that
+ * touches the database resolves instead of returning. `sharedSql` is still synchronous and
+ * emits the identical fragment, for an app to embed in its own D1 queries. The SQL is the
+ * sync store's own (`./statements.ts`), and `./d1.spec.ts` runs both stores through one
+ * scenario and compares every call's result and every table's rows.
+ *
+ * The four properties of `./store.ts`'s header hold, by different means:
+ *  1. **Every mutation writes its audit row in the same transaction.** D1 has no interactive
+ *     transaction, so each mutation is ONE `db.batch([...])` — atomic on D1, a real
+ *     transaction locally. Where the sync store reads the grant and then decides what to log,
+ *     this store logs FROM the grant row inside that batch (`INSERT … SELECT … RETURNING`),
+ *     so there is no window between the read and the write for another request to use.
+ *  2. **A revoked grant's history survives it** — the event insert runs before the delete.
+ *  3. **`revokeResource` is one call** — two statements, one batch, however many grants.
+ *  4. **The hook cannot break a write.** `onEvent` runs after the batch commits; a throw — or
+ *     a rejected promise, which a Worker's hook may well return — is caught and warned.
+ *
+ * Differences a caller can observe, each deliberate:
+ *   · A multi-grant revoke (`revokeResource`, `revokeSubject`, `deleteGroup`) writes its
+ *     events oldest-grant-first (`ORDER BY grant_id`); the sync store writes them in whatever
+ *     order its SELECT happened to return. Same events, a defined order.
+ *   · `onEvent` may return a promise, and the store AWAITS it before resolving — a Worker that
+ *     returned before the hook settled could have it cut off with the isolate.
+ *   · Validation failures REJECT rather than throw synchronously (they are async methods).
+ *   · 🔴 No DDL runs here, ever. The sync store migrates on construction; on D1 the schema is
+ *     the app's `db/schema.sql`, built from {@link SHARE_DDL} (the exact statements the sync
+ *     migration runs), and applied by `wrangler d1 migrations`. A request-time `CREATE TABLE`
+ *     is a write per invocation against the 1,000-query budget, for nothing.
+ *
+ * 🔴 Worker-safe: nothing reachable from here at runtime imports `bun:*`
+ * (`../telemetryIsWorkerSafe.spec.ts` walks it). Do not import `./store.js` or
+ * `./migrations.js` here — `./schema.js`, `./statements.js` and `./contract.js` are the
+ * driver-free halves they were split into.
+ *
+ * ```ts
+ * import { createD1ShareStore } from "cursedbelt-server/sharing/d1";
+ *
+ * const shares = createD1ShareStore({ db: createRemoteD1(env.DB), app: "family", onEvent });
+ * await shares.grant({ kind: "person", id, subject: user(email), level: "read", grantedBy });
+ * const where = shares.sharedSql({ kind: "person", subjectId: viewer.email, column: "p.id" });
+ * ```
+ */
+import {
+	levelsMeeting,
+	normalizeSubjectId,
+	type ShareAccess,
+	type ShareEvent,
+	type ShareGrant,
+	type ShareGroup,
+	type ShareGroupMember,
+	type ShareLevel,
+	type ShareResource,
+	type ShareSubject,
+	type ShareViewer,
+	strongerAccess,
+} from "cursedbelt-core/sharing/model";
+import type { D1LikeBindable, D1LikeDatabase, D1LikeStatement } from "../d1/types.js";
+import type { AsyncShareStore, GrantInput, RevokeInput, ShareEventQuery, ShareTarget } from "./contract.js";
+import { sharedResourceSql } from "./sql.js";
+import {
+	type EventRow,
+	eventLimit,
+	eventsWhere,
+	type GrantRow,
+	type GroupMemberRow,
+	type GroupRow,
+	SHARE_SQL,
+	toEvent,
+	toGrant,
+} from "./statements.js";
+
+export { group, user } from "./contract.js";
+export type {
+	AsyncShareStore,
+	Awaitable,
+	AwaitableShareStore,
+	GrantInput,
+	RevokeInput,
+	SharedSqlInput,
+	ShareEventQuery,
+	ShareTarget,
+} from "./contract.js";
+export {
+	SHARE_DDL,
+	SHARE_EVENTS_TABLE,
+	SHARE_GRANTS_TABLE,
+	SHARE_GROUPS_TABLE,
+	SHARE_GROUP_MEMBERS_TABLE,
+} from "./schema.js";
+
+export interface D1ShareStoreOptions {
+	/** The app's D1 handle — `createRemoteD1(env.DB)` on a Worker, `createLocalD1(sqlite)` in a test. */
+	db: D1LikeDatabase;
+	/** The satellite this store speaks for. Fixed at construction, as in the sync store. */
+	app: string;
+	/**
+	 * Notified after every committed mutation, as in the sync store. May return a promise; the
+	 * store awaits it, and neither a throw nor a rejection can undo the write.
+	 */
+	onEvent?: (event: ShareEvent) => void | Promise<void>;
+	/** Injectable clock, for tests that assert ordering. ISO-8601 strings. */
+	now?: () => string;
+}
+
+/**
+ * The share store over D1. Runs no DDL — see the header; the tables come from
+ * {@link SHARE_DDL} in the app's schema.
+ */
+export function createD1ShareStore(options: D1ShareStoreOptions): AsyncShareStore {
+	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`");
+
+	const emit = async (events: readonly ShareEvent[]): Promise<void> => {
+		const hook = options.onEvent;
+		if (!hook) return;
+		for (const event of events) {
+			try {
+				await hook(event);
+			} catch (error) {
+				console.warn(`[cursedbelt-core/sharing] a share-event listener threw: ${String(error)}`);
+			}
+		}
+	};
+
+	const stmt = (sql: string, ...values: D1LikeBindable[]): D1LikeStatement => db.prepare(sql).bind(...values);
+	const rows = async <T>(sql: string, ...values: D1LikeBindable[]): Promise<T[]> =>
+		(await stmt(sql, ...values).all<T>()).results;
+
+	/** Run a mutation's statements as ONE atomic batch, and read back the events it wrote. */
+	const commit = async (statements: D1LikeStatement[]): Promise<ShareEvent[]> => {
+		const results = await db.batch<EventRow>(statements);
+		const events = results
+			.flatMap((result) => result.results)
+			.filter((row): row is EventRow => typeof (row as Partial<EventRow>).event_id === "number")
+			.sort((a, b) => a.event_id - b.event_id)
+			.map(toEvent);
+		await emit(events);
+		return events;
+	};
+
+	/** A plain event insert, for the mutations whose audit row does not depend on a read. */
+	const eventInsert = (input: {
+		action: ShareEvent["action"];
+		resource: ShareResource | null;
+		subject: ShareSubject;
+		level: ShareLevel | null;
+		actor: string;
+		note?: string;
+		at: string;
+	}): D1LikeStatement =>
+		stmt(
+			`${SHARE_SQL.insertEvent} RETURNING *`,
+			input.at,
+			input.action,
+			input.resource?.app ?? null,
+			input.resource?.kind ?? null,
+			input.resource?.id ?? null,
+			input.subject.type,
+			input.subject.id,
+			input.level,
+			null,
+			input.actor,
+			input.note ?? "",
+		);
+
+	const revokeEvents = (where: string, at: string, actor: string, note: string, ...keys: D1LikeBindable[]) =>
+		stmt(SHARE_SQL.insertRevokeEvents(where), at, actor, note, ...keys);
+
+	const normalized = (subject: ShareSubject): ShareSubject => ({
+		type: subject.type,
+		id: normalizeSubjectId(subject.type, subject.id),
+	});
+
+	return {
+		app,
+
+		async grant(input: GrantInput): Promise<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 note = input.note ?? "";
+			const key = [app, input.kind, input.id, subject.type, subject.id] as const;
+			await commit([
+				// The event FIRST: it reads the grant as it stood, to tell a grant from a regrade.
+				stmt(
+					SHARE_SQL.insertGrantEvent,
+					at,
+					input.level,
+					...key,
+					input.level,
+					input.level,
+					input.grantedBy,
+					note,
+					...key,
+				),
+				stmt(SHARE_SQL.upsertGrant, ...key, input.level, input.grantedBy, at, note),
+			]);
+			return {
+				resource: { app, kind: input.kind, id: input.id },
+				subject,
+				level: input.level,
+				grantedBy: input.grantedBy,
+				grantedAt: at,
+				note,
+			};
+		},
+
+		async revoke(input: RevokeInput): Promise<ShareLevel | null> {
+			const subject = normalized(input.subject);
+			const at = clock();
+			const key = [app, input.kind, input.id, subject.type, subject.id] as const;
+			const [event] = await commit([
+				revokeEvents(SHARE_SQL.oneGrant, at, input.revokedBy, input.note ?? "", ...key),
+				stmt(SHARE_SQL.deleteGrant, ...key),
+			]);
+			// No grant, no event — "revoked nothing" is not logged, exactly as in the sync store.
+			return event?.level ?? null;
+		},
+
+		async revokeResource(target: ShareTarget, revokedBy: string): Promise<number> {
+			const at = clock();
+			const key = [app, target.kind, target.id] as const;
+			const events = await commit([
+				revokeEvents(SHARE_SQL.resourceGrants, at, revokedBy, "the record was deleted", ...key),
+				stmt(SHARE_SQL.deleteResourceGrants, ...key),
+			]);
+			return events.length;
+		},
+
+		async revokeSubject(subject: ShareSubject, revokedBy: string): Promise<number> {
+			const normal = normalized(subject);
+			const at = clock();
+			const key = [app, normal.type, normal.id] as const;
+			const events = await commit([
+				revokeEvents(SHARE_SQL.subjectGrants, at, revokedBy, "every share with this subject was revoked", ...key),
+				stmt(SHARE_SQL.deleteSubjectGrants, ...key),
+			]);
+			return events.length;
+		},
+
+		async listForResource(target: ShareTarget): Promise<ShareGrant[]> {
+			return (await rows<GrantRow>(SHARE_SQL.listForResource, app, target.kind, target.id)).map(toGrant);
+		},
+
+		async listForSubject(subject: ShareSubject): Promise<ShareGrant[]> {
+			const normal = normalized(subject);
+			return (await rows<GrantRow>(SHARE_SQL.listForSubject, app, normal.type, normal.id)).map(toGrant);
+		},
+
+		async accessFor(target: ShareTarget, viewer: ShareViewer): Promise<ShareAccess> {
+			const subjectId = normalizeSubjectId("user", viewer.subjectId);
+			if (!subjectId) return "none";
+			const found = await rows<{ level: ShareLevel }>(
+				SHARE_SQL.accessFor,
+				app,
+				target.kind,
+				target.id,
+				subjectId,
+				subjectId,
+			);
+			let access: ShareAccess = "none";
+			for (const row of found) access = strongerAccess(access, row.level);
+			return access;
+		},
+
+		async resourceIdsFor(kind: string, viewer: ShareViewer, atLeast: ShareLevel = "read"): Promise<string[]> {
+			const subjectId = normalizeSubjectId("user", viewer.subjectId);
+			if (!subjectId) return [];
+			const levels = levelsMeeting(atLeast);
+			const found = await rows<{ resource_id: string }>(
+				SHARE_SQL.resourceIdsFor(levels.length),
+				app,
+				kind,
+				...levels,
+				subjectId,
+				subjectId,
+			);
+			return found.map((row) => row.resource_id);
+		},
+
+		sharedSql(input: { kind: string; subjectId: string; column: string; atLeast?: ShareLevel }): string {
+			return sharedResourceSql({ app, ...input });
+		},
+
+		// ── Groups ───────────────────────────────────────────────────────────────
+
+		async createGroup(input: { id: string; name: string; createdBy: string; note?: string }): Promise<ShareGroup> {
+			const id = normalizeSubjectId("group", input.id);
+			if (!id) throw new Error("[cursedbelt-core/sharing] a group needs an id");
+			const at = clock();
+			await commit([
+				stmt(SHARE_SQL.upsertGroup, id, input.name, input.createdBy, at, input.note ?? ""),
+				eventInsert({
+					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 ?? "" };
+		},
+
+		async renameGroup(id: string, name: string, actor: string): Promise<void> {
+			const groupId = normalizeSubjectId("group", id);
+			const at = clock();
+			await commit([
+				stmt(SHARE_SQL.renameGroup, name, groupId),
+				eventInsert({
+					action: "group.rename",
+					resource: null,
+					subject: { type: "group", id: groupId },
+					level: null,
+					actor,
+					note: name,
+					at,
+				}),
+			]);
+		},
+
+		/** Deletes the group AND every grant made to it, each with its own revoke event — see
+		 *  the sync store's `deleteGroup` for why that is not optional. */
+		async deleteGroup(id: string, actor: string): Promise<void> {
+			const groupId = normalizeSubjectId("group", id);
+			const at = clock();
+			await commit([
+				revokeEvents(SHARE_SQL.groupGrants, at, actor, "the group was deleted", app, groupId),
+				stmt(SHARE_SQL.deleteGroupGrants, app, groupId),
+				stmt(SHARE_SQL.deleteGroup, groupId),
+				eventInsert({
+					action: "group.delete",
+					resource: null,
+					subject: { type: "group", id: groupId },
+					level: null,
+					actor,
+					note: "",
+					at,
+				}),
+			]);
+		},
+
+		async listGroups(): Promise<ShareGroup[]> {
+			return (await rows<GroupRow>(SHARE_SQL.listGroups)).map((row) => ({
+				id: row.group_id,
+				name: row.name,
+				createdBy: row.created_by,
+				createdAt: row.created_at,
+				note: row.note,
+			}));
+		},
+
+		async addGroupMember(groupId: string, subjectId: string, actor: string): Promise<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();
+			await commit([
+				stmt(SHARE_SQL.insertMember, id, member, actor, at),
+				eventInsert({
+					action: "group.join",
+					resource: null,
+					subject: { type: "group", id },
+					level: null,
+					actor,
+					note: member,
+					at,
+				}),
+			]);
+		},
+
+		async removeGroupMember(groupId: string, subjectId: string, actor: string): Promise<void> {
+			const id = normalizeSubjectId("group", groupId);
+			const member = normalizeSubjectId("user", subjectId);
+			const at = clock();
+			await commit([
+				stmt(SHARE_SQL.deleteMember, id, member),
+				eventInsert({
+					action: "group.leave",
+					resource: null,
+					subject: { type: "group", id },
+					level: null,
+					actor,
+					note: member,
+					at,
+				}),
+			]);
+		},
+
+		async listGroupMembers(groupId: string): Promise<ShareGroupMember[]> {
+			const found = await rows<GroupMemberRow>(SHARE_SQL.listMembers, normalizeSubjectId("group", groupId));
+			return found.map((row) => ({
+				groupId: row.group_id,
+				subjectId: row.subject_id,
+				addedBy: row.added_by,
+				addedAt: row.added_at,
+			}));
+		},
+
+		async groupIdsFor(subjectId: string): Promise<string[]> {
+			const member = normalizeSubjectId("user", subjectId);
+			if (!member) return [];
+			return (await rows<{ group_id: string }>(SHARE_SQL.groupIdsFor, member)).map((row) => row.group_id);
+		},
+
+		// ── The audit trail ──────────────────────────────────────────────────────
+
+		async events(query: ShareEventQuery = {}): Promise<ShareEvent[]> {
+			const { where, params } = eventsWhere(app, {
+				...query,
+				subject: query.subject ? normalized(query.subject) : undefined,
+			});
+			return (await rows<EventRow>(SHARE_SQL.events(where), ...params, eventLimit(query.limit))).map(toEvent);
+		},
+	};
+}

package/src/server/sharing/index.ts

@@ -23,6 +23,9 @@ export type { ShareRouterOptions, ShareRouterViewer, ShareRoutesPayload } from "
 export { sharedResourceSql, sqlColumn, sqlLiteral } from "./sql.js";
 export type { SharedResourceSqlOptions } from "./sql.js";
 export { createShareStore, group, user } from "./store.js";
+// The D1 store itself is `cursedbelt-server/sharing/d1` — never re-exported here, so this
+// barrel stays what it was. Its TYPES are here, because `mountShareRoutes` takes either store.
+export type { AsyncShareStore, AwaitableShareStore } from "./contract.js";
 export type {
 	GrantInput,
 	RevokeInput,