cursedbelt-server 1.0.0

package/src/server/sharing/migrations.ts

@@ -0,0 +1,128 @@
+/**
+ * The four tables behind the fleet's sharing model, as migrations an app runs
+ * inside its OWN database.
+ *
+ * ── 🔴 Why they live in the app's database and not in a shared one ────────────
+ * A grant answers "may this person open THIS row", and the only place that
+ * question can be answered in the same transaction as the row is read is the
+ * database holding the row. A central share service would mean every list query
+ * in every satellite is a network round trip that cannot participate in a
+ * `COUNT(*)`, and the first thing an app would do is cache the answer — at which
+ * point revocation is eventually-consistent, which is the one thing revocation
+ * must not be. So the SCHEMA is shared (this file), the data is local, and
+ * `apps/auth` remains the only registry of who exists.
+ *
+ * Names are prefixed `share_` for the same reason: these tables land in a
+ * database that already has its own, and `shares` alone is a name three apps
+ * could plausibly have wanted.
+ *
+ * ── The shape, and the two constraints that are load-bearing ────────────────
+ * `share_grants`   one row per (subject, resource). UNIQUE on exactly that, so a
+ *                  second grant is an UPDATE (a regrade) rather than a duplicate
+ *                  nobody can revoke half of.
+ * `share_groups`   a named set of people.
+ * `share_group_members`  who is in one.
+ * `share_events`   APPEND ONLY, and nothing in this package ever deletes from it.
+ *
+ * 🔴 `share_events` deliberately has **no foreign key** onto `share_grants` or
+ * `share_groups`. A trail whose rows are cascaded away when the grant is revoked
+ * can only describe access that still exists — it would erase itself at exactly
+ * the moment it becomes evidence. Revoking deletes the grant and appends an event;
+ * deleting a group deletes its membership and appends one per removal.
+ */
+import type { Database } from "bun:sqlite";
+import type { Migration } from "../migration/types";
+
+export const SHARE_GRANTS_TABLE = "share_grants";
+export const SHARE_GROUPS_TABLE = "share_groups";
+export const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
+export const SHARE_EVENTS_TABLE = "share_events";
+
+export const SHARE_MIGRATIONS: readonly Migration[] = [
+	{
+		name: "0001_share_grants",
+		up(db: Database): void {
+			db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GRANTS_TABLE} (
+					grant_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+					app         TEXT NOT NULL,
+					kind        TEXT NOT NULL,
+					resource_id TEXT NOT NULL,
+					subject_type TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
+					subject_id  TEXT NOT NULL,
+					level       TEXT NOT NULL CHECK (level IN ('read', 'write')),
+					granted_by  TEXT NOT NULL,
+					granted_at  TEXT NOT NULL,
+					note        TEXT NOT NULL DEFAULT '',
+					-- One grant per subject per resource. This is what makes raising
+					-- read to write an UPDATE the audit trail can describe, instead of
+					-- two rows where revoking one leaves access in place.
+					UNIQUE (app, kind, resource_id, subject_type, subject_id)
+				)
+			`);
+			// The hot read is the resolver's: "does this subject hold a grant on this
+			// row" — correlated per row of a list query, so it must be an index hit.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_share_grants_subject
+				 ON ${SHARE_GRANTS_TABLE} (subject_type, subject_id, app, kind, resource_id)`,
+			);
+			// …and the panel's: "who can see this record".
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_share_grants_resource
+				 ON ${SHARE_GRANTS_TABLE} (app, kind, resource_id)`,
+			);
+
+			db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GROUPS_TABLE} (
+					group_id   TEXT PRIMARY KEY,
+					name       TEXT NOT NULL,
+					created_by TEXT NOT NULL,
+					created_at TEXT NOT NULL,
+					note       TEXT NOT NULL DEFAULT ''
+				)
+			`);
+
+			db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GROUP_MEMBERS_TABLE} (
+					group_id   TEXT NOT NULL REFERENCES ${SHARE_GROUPS_TABLE} (group_id) ON DELETE CASCADE,
+					subject_id TEXT NOT NULL,
+					added_by   TEXT NOT NULL,
+					added_at   TEXT NOT NULL,
+					PRIMARY KEY (group_id, subject_id)
+				)
+			`);
+			// "Which groups is this person in" — read by every shared-row query.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_share_group_members_subject
+				 ON ${SHARE_GROUP_MEMBERS_TABLE} (subject_id)`,
+			);
+
+			db.run(`
+				CREATE TABLE IF NOT EXISTS ${SHARE_EVENTS_TABLE} (
+					event_id      INTEGER PRIMARY KEY AUTOINCREMENT,
+					at            TEXT NOT NULL,
+					action        TEXT NOT NULL,
+					app           TEXT,
+					kind          TEXT,
+					resource_id   TEXT,
+					subject_type  TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
+					subject_id    TEXT NOT NULL,
+					level         TEXT,
+					previous_level TEXT,
+					actor         TEXT NOT NULL,
+					note          TEXT NOT NULL DEFAULT ''
+				)
+			`);
+			// "Everything that ever happened to this record", newest first.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_share_events_resource
+				 ON ${SHARE_EVENTS_TABLE} (app, kind, resource_id, event_id DESC)`,
+			);
+			// "Everything this person was ever given" — the offboarding question.
+			db.run(
+				`CREATE INDEX IF NOT EXISTS idx_share_events_subject
+				 ON ${SHARE_EVENTS_TABLE} (subject_id, event_id DESC)`,
+			);
+		},
+	},
+];

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

@@ -0,0 +1,167 @@
+/**
+ * The share ROUTER's contract, over a real Hono app and a real in-memory store.
+ *
+ * White-box by STANDARDS §6a's named exception — these are permission checks, and a
+ * permissive bug here is invisible until it is a disclosure. Every case below is a
+ * property one of the five call sites this replaced depended on, and the three marked 🔴
+ * are the ones that were WRITTEN AS FAILURES first: comment out the gate, comment out the
+ * `group:` split, hand the read to a recipient, and watch each one go red.
+ */
+import { Database } from "bun:sqlite";
+import { beforeEach, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { mountShareRoutes, parseSubjectParam, subjectParam } from "./router";
+import { createShareStore, user } from "./store";
+
+let db: Database;
+let shares: ReturnType<typeof createShareStore>;
+/** Who the next request is from, and who owns the resource. */
+let asEmail: string | null;
+let owners: Record<string, string>;
+
+function app() {
+	const a = new Hono();
+	mountShareRoutes(a, {
+		base: "/api/things/:id",
+		kind: "thing",
+		shares,
+		viewerOf: () => (asEmail ? { email: asEmail } : null),
+		// The app's policy, exactly as apps/life and apps/family supply it: 404 rather
+		// than 403 for a resource the viewer may not know exists.
+		mustOwn: (c, id, viewer) =>
+			owners[id] === viewer.email ? null : c.json({ error: "not found" }, 404),
+		extra: () => ({ groups: shares.listGroups() }),
+	});
+	return a;
+}
+
+const get = (id: string) => app().request(`/api/things/${id}/shares`);
+const post = (id: string, body: unknown) =>
+	app().request(`/api/things/${id}/shares`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body),
+	});
+const del = (id: string, subject: string) =>
+	app().request(`/api/things/${id}/shares/${subject}`, { method: "DELETE" });
+
+beforeEach(() => {
+	db = new Database(":memory:");
+	db.exec("PRAGMA foreign_keys = ON");
+	shares = createShareStore({ db, app: "test" });
+	owners = { t1: "owner@example.com" };
+	asEmail = "owner@example.com";
+});
+
+describe("the subject codec", () => {
+	test("🔴 a `group:` prefix is what makes a subject a GROUP, and only the prefix", () => {
+		// The sharp edge: a path segment cannot carry a {type, id} pair, so the prefix IS
+		// the type. Drop the split and a group revoke silently removes nothing and reports
+		// success — the worst possible outcome for a permission removal.
+		expect(parseSubjectParam("group:household")).toEqual({ type: "group", id: "household" });
+		expect(parseSubjectParam("aunt@example.com")).toEqual({
+			type: "user",
+			id: "aunt@example.com",
+		});
+	});
+
+	test("it round-trips through a URL segment, including an address with a +", () => {
+		const subject = { type: "user", id: "a+b@example.com" } as const;
+		expect(parseSubjectParam(subjectParam(subject))).toEqual(subject);
+		const g = { type: "group", id: "the house" } as const;
+		expect(parseSubjectParam(subjectParam(g))).toEqual(g);
+	});
+});
+
+describe("the owner gate", () => {
+	test("🔴 it covers the READ, not only the writes", async () => {
+		// "Who else can see this" is not part of what "shared with you" grants: the roster
+		// of other grantees is itself a disclosure. Five hand-rolled copies is five chances
+		// to gate POST/DELETE and forget GET.
+		shares.grant({
+			kind: "thing",
+			id: "t1",
+			subject: user("guest@example.com"),
+			level: "read",
+			grantedBy: "owner@example.com",
+		});
+		asEmail = "guest@example.com";
+		expect((await get("t1")).status).toBe(404);
+		expect((await post("t1", { subject: { id: "x@example.com" } })).status).toBe(404);
+		expect((await del("t1", "guest@example.com")).status).toBe(404);
+		// …and the grant it could not see is still there.
+		expect(shares.listForResource({ kind: "thing", id: "t1" })).toHaveLength(1);
+	});
+
+	test("no session is 401 on every route, before ownership is even asked", async () => {
+		asEmail = null;
+		expect((await get("t1")).status).toBe(401);
+		expect((await post("t1", { subject: { id: "x@example.com" } })).status).toBe(401);
+		expect((await del("t1", "x@example.com")).status).toBe(401);
+	});
+});
+
+describe("read / grant / revoke", () => {
+	test("the read carries the store's own rows plus the app's extra", async () => {
+		shares.grant({
+			kind: "thing",
+			id: "t1",
+			subject: user("aunt@example.com"),
+			level: "write",
+			grantedBy: "owner@example.com",
+		});
+		const body = (await (await get("t1")).json()) as {
+			grants: { subject: { id: string } }[];
+			events: unknown[];
+			groups: unknown[];
+		};
+		expect(body.grants.map((g) => g.subject.id)).toEqual(["aunt@example.com"]);
+		expect(body.events).toHaveLength(1);
+		// `extra` is the seam the two apps' divergent payloads fold through.
+		expect(body.groups).toEqual([]);
+	});
+
+	test("a grant defaults to read, and an unknown level is refused rather than coerced", async () => {
+		expect((await post("t1", { subject: { id: "a@example.com" } })).status).toBe(201);
+		expect(shares.accessFor({ kind: "thing", id: "t1" }, { subjectId: "a@example.com" })).toBe(
+			"read",
+		);
+		const bad = await post("t1", { subject: { id: "b@example.com" }, level: "admin" });
+		expect(bad.status).toBe(400);
+		expect(shares.accessFor({ kind: "thing", id: "t1" }, { subjectId: "b@example.com" })).toBe(
+			"none",
+		);
+	});
+
+	test("an empty subject is a 400, never a grant to nobody", async () => {
+		expect((await post("t1", {})).status).toBe(400);
+		expect((await post("t1", { subject: { id: "   " } })).status).toBe(400);
+		expect(shares.listForResource({ kind: "thing", id: "t1" })).toHaveLength(0);
+	});
+
+	test("🔴 revoking a GROUP grant through the path actually removes it", async () => {
+		const g = shares.createGroup({
+			id: "household",
+			name: "The household",
+			createdBy: "owner@example.com",
+		});
+		shares.grant({
+			kind: "thing",
+			id: "t1",
+			subject: { type: "group", id: g.id },
+			level: "read",
+			grantedBy: "owner@example.com",
+		});
+		expect(shares.listForResource({ kind: "thing", id: "t1" })).toHaveLength(1);
+		expect((await del("t1", encodeURIComponent(`group:${g.id}`))).status).toBe(200);
+		expect(shares.listForResource({ kind: "thing", id: "t1" })).toHaveLength(0);
+	});
+
+	test("the audit trail outlives the grant it describes", async () => {
+		await post("t1", { subject: { id: "a@example.com" } });
+		await del("t1", "a@example.com");
+		const body = (await (await get("t1")).json()) as { grants: unknown[]; events: unknown[] };
+		expect(body.grants).toHaveLength(0);
+		expect(body.events).toHaveLength(2);
+	});
+});

package/src/server/sharing/router.ts

@@ -0,0 +1,194 @@
+/**
+ * `mountShareRoutes` — the three HTTP routes a shareable resource needs, once.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * The store (`./store.ts`) was already the fleet's one sharing model; the ROUTES over it
+ * were not. `apps/life` wrote them once and mounted them four times (calendars, lists,
+ * to-dos, board cards) and `apps/family` wrote a fifth copy for people — five hand-rolled
+ * copies of read/grant/revoke, each re-deciding the same three policy questions:
+ *
+ *  1. **All three routes are OWNER-only, including the READ.** "Who else can see this" is
+ *     not part of what "shared with you" grants — a recipient must never reach
+ *     `listForResource`, because the roster of other grantees is itself a disclosure.
+ *     Five copies is five chances to write the gate on POST/DELETE and forget it on GET.
+ *  2. **`group:<id>` is how a group subject travels in a URL.** A path segment cannot
+ *     carry a `{type, id}` pair, so the prefix IS the type. Getting that wrong revokes a
+ *     USER grant whose address happens to start with `group:` — or, worse, silently
+ *     revokes nothing and reports success.
+ *  3. **A grant only ever widens, and the audit trail outlives it.** Both are the store's,
+ *     and both are only true if every route actually goes through the store.
+ *
+ * A bug in any of those has to be fixable by one commit. That is the placement test in
+ * `cursedbelt/STANDARDS.md`, and it passes here.
+ *
+ * ── 🔴 The wire shape is LIFE's, and family's client changed to match ────────────────────
+ * The two apps genuinely disagreed and one had to give:
+ *
+ *   · revoke — family put the subject in the QUERY (`DELETE …/shares?subject=&type=`),
+ *     life in the PATH (`DELETE …/shares/:subject`, `group:` prefixed). The path wins.
+ *     family's own comment argued for the query on the grounds that the target should be
+ *     visible in the request line — which a path segment satisfies just as well, while
+ *     also being the shape four of the five mounts already used. Changing one client beat
+ *     changing four.
+ *   · read — family returned `{grants, events, labels}`, life `{grants, events, groups}`.
+ *     Neither extra is general: `labels` resolves addresses to names out of the family
+ *     tree *inside the viewer's space*, `groups` is life's household roster. So the
+ *     primitive owns `{grants, events}` and an app folds its own half in through
+ *     {@link ShareRouterOptions.extra}.
+ *
+ * ── What stays in the app ───────────────────────────────────────────────────────────────
+ * Ownership. `mustOwn` is the app's, because "who owns a calendar" and "who may curate a
+ * family file" are policy this module has no business knowing — and because the 404/403
+ * ORDER is policy too (family answers 404 before 403 on a person the viewer may not know
+ * exists). The hook returns the refusal it wants, or null to continue.
+ */
+import type { Context, Hono } from 'hono';
+import type { ShareEvent, ShareGrant, ShareLevel } from 'cursedbelt-core/sharing/model';
+import type { ShareStore } from './store';
+
+/** The `group:` prefix that lets a group subject travel in a path segment. Exported so a
+ *  client and a route cannot disagree about it. */
+export const GROUP_SUBJECT_PREFIX = 'group:';
+
+/** Split a URL subject segment into the store's `{type, id}` pair. */
+export function parseSubjectParam(raw: string): { type: 'user' | 'group'; id: string } {
+  const decoded = decodeURIComponent(raw);
+  return decoded.startsWith(GROUP_SUBJECT_PREFIX)
+    ? { type: 'group', id: decoded.slice(GROUP_SUBJECT_PREFIX.length) }
+    : { type: 'user', id: decoded };
+}
+
+/** The inverse — what a client puts in the path. */
+export const subjectParam = (subject: { type: 'user' | 'group'; id: string }): string =>
+  encodeURIComponent(subject.type === 'group' ? GROUP_SUBJECT_PREFIX + subject.id : subject.id);
+
+/** What every route needs about who is asking. Structural, so an app hands its own viewer
+ *  type straight in. */
+export interface ShareRouterViewer {
+  /** The fleet address; the subject id of every `user` grant. */
+  email: string;
+}
+
+export interface ShareRouterOptions<V extends ShareRouterViewer> {
+  /**
+   * The resource path, with `:id` in it — e.g. `/api/calendars/:id`. The three routes
+   * hang off `${base}/shares`; revoke adds `/:subject`.
+   */
+  base: string;
+  /** The `kind` half of the store's `(app, kind, id)` triple. */
+  kind: string;
+  /** The store. A function when it is per-request (a multi-tenant app). */
+  shares: ShareStore | ((c: Context) => ShareStore);
+  /** Who is asking. Returning null refuses every route with 401. */
+  viewerOf: (c: Context) => V | null;
+  /**
+   * 🔴 The OWNER gate, run on ALL THREE routes including the read. Return a `Response` to
+   * refuse (the app owns the status AND the 404-before-403 ordering), or null to allow.
+   * `throw`ing is fine too — an app with an error middleware can keep using it.
+   */
+  mustOwn: (c: Context, id: string, viewer: V) => Response | null | Promise<Response | null>;
+  /** Extra fields folded into the READ payload beside `{grants, events}` — family's
+   *  `labels`, life's `groups`. */
+  extra?: (c: Context, id: string, viewer: V) => Record<string, unknown>;
+  /** How many audit lines the read carries. Default 50. */
+  trailLimit?: number;
+}
+
+/** The read payload's guaranteed half. An app's `extra` is spread in beside it. */
+export interface ShareRoutesPayload {
+  grants: ShareGrant[];
+  /** Newest first, and it OUTLIVES the grants — a revoked share still has a line. */
+  events: ShareEvent[];
+}
+
+const isLevel = (v: unknown): v is ShareLevel => v === 'read' || v === 'write';
+
+/**
+ * Mount GET / POST / DELETE for one `kind` on one app.
+ *
+ * ```ts
+ * mountShareRoutes(app, {
+ *   base: '/api/calendars/:id',
+ *   kind: CALENDAR_KIND,
+ *   shares,
+ *   viewerOf,
+ *   mustOwn: (c, id, viewer) => (ownsCalendar(db, viewer, id) ? null : c.json({ error: 'not found' }, 404)),
+ *   extra: () => ({ groups: shares.listGroups() }),
+ * });
+ * ```
+ */
+export function mountShareRoutes<V extends ShareRouterViewer>(
+  // biome-ignore lint/suspicious/noExplicitAny: the caller's Hono env is theirs, and this
+  // module reads nothing off it — narrowing it would force every app to name its own Env
+  // here for no gain.
+  app: Hono<any>,
+  options: ShareRouterOptions<V>,
+): void {
+  const { base, kind, viewerOf, mustOwn, extra, trailLimit = 50 } = options;
+  const storeOf = (c: Context): ShareStore =>
+    typeof options.shares === 'function' ? options.shares(c) : options.shares;
+
+  /** The three-step preamble every route shares: identity, id, ownership. */
+  async function enter(
+    c: Context,
+  ): Promise<{ refused: Response } | { id: string; viewer: V; shares: ShareStore }> {
+    const viewer = viewerOf(c);
+    if (!viewer) return { refused: c.json({ error: 'sign in first' }, 401) };
+    const id = c.req.param('id') ?? '';
+    const refused = await mustOwn(c, id, viewer);
+    if (refused) return { refused };
+    return { id, viewer, shares: storeOf(c) };
+  }
+
+  app.get(`${base}/shares`, async (c) => {
+    const step = await enter(c);
+    if ('refused' in step) return step.refused;
+    const { id, viewer, shares } = step;
+    const payload: ShareRoutesPayload & Record<string, unknown> = {
+      // The store's own rows, straight through — the sharing panel consumes exactly
+      // these, and a DTO in the middle is a place for a field to go missing.
+      grants: shares.listForResource({ kind, id }),
+      events: shares.events({ kind, id, limit: trailLimit }),
+      ...(extra ? extra(c, id, viewer) : {}),
+    };
+    return c.json(payload);
+  });
+
+  app.post(`${base}/shares`, async (c) => {
+    const step = await enter(c);
+    if ('refused' in step) return step.refused;
+    const { id, viewer, shares } = step;
+    const body = (await c.req.json().catch(() => ({}))) as {
+      subject?: { type?: string; id?: string };
+      /** family's older spelling — an address at the top level. Accepted so the two
+       *  apps' clients could converge one at a time rather than in one commit. */
+      email?: string;
+      level?: unknown;
+      note?: unknown;
+    };
+    const subjectId = (body.subject?.id ?? body.email ?? '').trim();
+    if (!subjectId) return c.json({ error: 'who should this be shared with?' }, 400);
+    if (body.level !== undefined && !isLevel(body.level)) {
+      return c.json({ error: "level must be 'read' or 'write'" }, 400);
+    }
+    const grant = shares.grant({
+      kind,
+      id,
+      subject: { type: body.subject?.type === 'group' ? 'group' : 'user', id: subjectId },
+      level: isLevel(body.level) ? body.level : 'read',
+      grantedBy: viewer.email,
+      ...(typeof body.note === 'string' ? { note: body.note } : {}),
+    });
+    return c.json(grant, 201);
+  });
+
+  app.delete(`${base}/shares/:subject`, async (c) => {
+    const step = await enter(c);
+    if ('refused' in step) return step.refused;
+    const { id, viewer, shares } = step;
+    const raw = c.req.param('subject') ?? '';
+    if (!raw.trim()) return c.json({ error: 'which share should be removed?' }, 400);
+    shares.revoke({ kind, id, subject: parseSubjectParam(raw), revokedBy: viewer.email });
+    return c.json({ ok: true });
+  });
+}

package/src/server/sharing/sql.ts

@@ -0,0 +1,109 @@
+/**
+ * The half a consuming app needs INSIDE its own queries: a SQL boolean saying
+ * "this row is shared with the viewer".
+ *
+ * ── 🔴 Why a SQL fragment and not a list of ids ──────────────────────────────
+ * The obvious API is `sharedIds(kind, viewer): string[]`, and it is wrong for the
+ * consumers this exists to serve. `apps/family`'s rule, written in `people.ts`
+ * before this primitive existed, is that a row the viewer may not see *"must not
+ * surface as a snippet, a COUNT, or a tree node either"* — so its visibility test
+ * has to be a WHERE clause that a `COUNT(*)`, a JOIN and a recursive tree walk all
+ * inherit. Handing the app an array means the app writes `id IN (…)` itself, in
+ * every one of those places, with its own quoting; the first one somebody forgets
+ * is a disclosure, and it will be the count.
+ *
+ * So the primitive emits the clause. `sharedResourceSql` returns a correlated
+ * `EXISTS (…)` over the grant tables that can be dropped into any query where the
+ * resource's id column is in scope, including one whose only bound parameter is
+ * something else entirely.
+ *
+ * ── 🔴 …which means this module quotes literals, so it does it in ONE place ───
+ * A fragment with no bindable parameters has to inline its values. Every value
+ * that reaches SQL here goes through {@link sqlLiteral} (double every apostrophe —
+ * `o'brien@example.com` is an ordinary address) or {@link sqlColumn} (an
+ * identifier, matched against a strict pattern and REFUSED otherwise, so a column
+ * expression can never smuggle a subquery in). Both are exported and both are
+ * tested with hostile input; a consumer never quotes anything itself.
+ */
+import { levelsMeeting, normalizeSubjectId, type ShareLevel } from "cursedbelt-core/sharing/model";
+import { SHARE_GRANTS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./migrations";
+
+/**
+ * Quote a string as a SQL literal.
+ *
+ * SQLite escapes an apostrophe by doubling it, and that is the whole rule for a
+ * TEXT literal — there is no backslash escape to worry about. A NUL byte is
+ * refused rather than quoted: SQLite truncates a string at one, so a value
+ * containing it would compare equal to a shorter value and silently widen a grant.
+ */
+export function sqlLiteral(value: string): string {
+	if (value.includes("\u0000")) {
+		throw new Error("[cursedbelt-core/sharing] a SQL literal may not contain a NUL byte");
+	}
+	return `'${value.replaceAll("'", "''")}'`;
+}
+
+/** A column reference — `id`, `p.id`, `"people"."id"` is NOT accepted. Anything
+ *  that is not a bare (optionally table-qualified) identifier is refused, because
+ *  this value is interpolated and a caller passing a computed string is how an
+ *  injection reaches a fragment builder. */
+const COLUMN_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/;
+
+export function sqlColumn(column: string): string {
+	if (!COLUMN_PATTERN.test(column)) {
+		throw new Error(
+			`[cursedbelt-core/sharing] ${JSON.stringify(column)} is not a plain column reference ` +
+				"(expected `id` or `alias.id`)",
+		);
+	}
+	return column;
+}
+
+export interface SharedResourceSqlOptions {
+	/** The satellite the resource belongs to — the `app` of the `(app, kind, id)`
+	 *  triple. */
+	app: string;
+	/** The app's own word for this sort of record ("person", "budget"). */
+	kind: string;
+	/** The viewer's fleet address. An EMPTY id yields `0=1` — see below. */
+	subjectId: string;
+	/** The column holding the resource's id, in scope of the query being built. */
+	column: string;
+	/** Minimum level the grant must carry. Default `read`. */
+	atLeast?: ShareLevel;
+}
+
+/**
+ * A SQL boolean: true for a row the viewer holds a grant on, at `atLeast` or
+ * above, directly or through a group.
+ *
+ * The group half is a nested `SELECT` rather than a pre-resolved list, so a
+ * membership change takes effect on the next query with no request-scoped cache to
+ * invalidate — the failure mode of caching it is a relative who was removed from
+ * the family group this morning and can still read until something restarts.
+ *
+ * 🔴 **An empty subject id yields `0=1`, never `1=1`.** An unauthenticated or
+ * machine caller has no address, and the arithmetic of `subject_id = ''` against a
+ * table where nothing has an empty id happens to be safe today — but a single
+ * malformed row would turn that into "shared with everybody". Failing closed on the
+ * missing identity is the property, not a coincidence of the data.
+ */
+export function sharedResourceSql(options: SharedResourceSqlOptions): string {
+	const subjectId = normalizeSubjectId("user", options.subjectId);
+	if (!subjectId) return "0=1";
+	const column = sqlColumn(options.column);
+	const levels = levelsMeeting(options.atLeast ?? "read")
+		.map((level) => sqlLiteral(level))
+		.join(", ");
+	const subject = sqlLiteral(subjectId);
+	return (
+		`EXISTS (SELECT 1 FROM ${SHARE_GRANTS_TABLE} sg` +
+		` WHERE sg.app = ${sqlLiteral(options.app)}` +
+		` AND sg.kind = ${sqlLiteral(options.kind)}` +
+		` AND sg.resource_id = ${column}` +
+		` AND sg.level IN (${levels})` +
+		` AND ((sg.subject_type = 'user' AND sg.subject_id = ${subject})` +
+		` OR (sg.subject_type = 'group' AND sg.subject_id IN` +
+		` (SELECT gm.group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} gm WHERE gm.subject_id = ${subject}))))`
+	);
+}