cursedbelt-server 4.26.1 → 4.28.0

package/dist/server/sharing/d1.js

@@ -0,0 +1,309 @@
+/**
+ * `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, strongerAccess, } from "cursedbelt-core/sharing/model";
+import { sharedResourceSql } from "./sql.js";
+import { eventLimit, eventsWhere, SHARE_SQL, toEvent, toGrant, } from "./statements.js";
+export { group, user } from "./contract.js";
+export { SHARE_DDL, SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, } from "./schema.js";
+/**
+ * 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) {
+    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) => {
+        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, ...values) => db.prepare(sql).bind(...values);
+    const rows = async (sql, ...values) => (await stmt(sql, ...values).all()).results;
+    /** Run a mutation's statements as ONE atomic batch, and read back the events it wrote. */
+    const commit = async (statements) => {
+        const results = await db.batch(statements);
+        const events = results
+            .flatMap((result) => result.results)
+            .filter((row) => typeof row.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) => 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, at, actor, note, ...keys) => stmt(SHARE_SQL.insertRevokeEvents(where), at, actor, note, ...keys);
+    const normalized = (subject) => ({
+        type: subject.type,
+        id: normalizeSubjectId(subject.type, subject.id),
+    });
+    return {
+        app,
+        async grant(input) {
+            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];
+            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) {
+            const subject = normalized(input.subject);
+            const at = clock();
+            const key = [app, input.kind, input.id, subject.type, subject.id];
+            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, revokedBy) {
+            const at = clock();
+            const key = [app, target.kind, target.id];
+            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, revokedBy) {
+            const normal = normalized(subject);
+            const at = clock();
+            const key = [app, normal.type, normal.id];
+            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) {
+            return (await rows(SHARE_SQL.listForResource, app, target.kind, target.id)).map(toGrant);
+        },
+        async listForSubject(subject) {
+            const normal = normalized(subject);
+            return (await rows(SHARE_SQL.listForSubject, app, normal.type, normal.id)).map(toGrant);
+        },
+        async accessFor(target, viewer) {
+            const subjectId = normalizeSubjectId("user", viewer.subjectId);
+            if (!subjectId)
+                return "none";
+            const found = await rows(SHARE_SQL.accessFor, app, target.kind, target.id, subjectId, subjectId);
+            let access = "none";
+            for (const row of found)
+                access = strongerAccess(access, row.level);
+            return access;
+        },
+        async resourceIdsFor(kind, viewer, atLeast = "read") {
+            const subjectId = normalizeSubjectId("user", viewer.subjectId);
+            if (!subjectId)
+                return [];
+            const levels = levelsMeeting(atLeast);
+            const found = await rows(SHARE_SQL.resourceIdsFor(levels.length), app, kind, ...levels, subjectId, subjectId);
+            return found.map((row) => row.resource_id);
+        },
+        sharedSql(input) {
+            return sharedResourceSql({ app, ...input });
+        },
+        // ── Groups ───────────────────────────────────────────────────────────────
+        async createGroup(input) {
+            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, name, actor) {
+            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, actor) {
+            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() {
+            return (await rows(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, subjectId, actor) {
+            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, subjectId, actor) {
+            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) {
+            const found = await rows(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) {
+            const member = normalizeSubjectId("user", subjectId);
+            if (!member)
+                return [];
+            return (await rows(SHARE_SQL.groupIdsFor, member)).map((row) => row.group_id);
+        },
+        // ── The audit trail ──────────────────────────────────────────────────────
+        async events(query = {}) {
+            const { where, params } = eventsWhere(app, {
+                ...query,
+                subject: query.subject ? normalized(query.subject) : undefined,
+            });
+            return (await rows(SHARE_SQL.events(where), ...params, eventLimit(query.limit))).map(toEvent);
+        },
+    };
+}

package/dist/server/sharing/index.d.ts

@@ -13,6 +13,7 @@ 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";
+export type { AsyncShareStore, AwaitableShareStore } from "./contract.js";
 export type { GrantInput, RevokeInput, ShareEventQuery, ShareStore, ShareStoreOptions, ShareTarget, } from "./store.js";
 export { accessMeets, describeAccess, describeShareEvent, isShareAccess, isShareLevel, isShareSubjectType, levelsMeeting, normalizeSubject, normalizeSubjectId, resolveAccess, resourceKey, sameResource, sameSubject, SHARE_ACTIONS, strongerAccess, } from "cursedbelt-core/sharing/model";
 export type { ShareAccess, ShareAction, ShareEvent, ShareGrant, ShareGroup, ShareGroupMember, ShareLevel, ShareResource, ShareSubject, ShareSubjectType, ShareViewer, } from "cursedbelt-core/sharing/model";

package/dist/server/sharing/migrations.d.ts

@@ -1,6 +1,3 @@
 import type { Migration } from "../migration/types.js";
-export declare const SHARE_GRANTS_TABLE = "share_grants";
-export declare const SHARE_GROUPS_TABLE = "share_groups";
-export declare const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
-export declare const SHARE_EVENTS_TABLE = "share_events";
+export { SHARE_DDL, SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, } from "./schema.js";
 export declare const SHARE_MIGRATIONS: readonly Migration[];

package/dist/server/sharing/migrations.js

@@ -1,79 +1,14 @@
-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";
+import { SHARE_DDL } from "./schema.js";
+// The names and the DDL live in `./schema.ts`, driver-free, so a D1 app builds its schema file
+// from the SAME statements this migration runs (`cursedbelt-server/sharing/d1` re-exports
+// them). Re-exported here so every existing import of this module keeps working.
+export { SHARE_DDL, SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE, } from "./schema.js";
 export const SHARE_MIGRATIONS = [
     {
         name: "0001_share_grants",
         up(db) {
-            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)`);
+            for (const statement of SHARE_DDL)
+                db.run(statement);
         },
     },
 ];

package/dist/server/sharing/router.d.ts

@@ -44,7 +44,7 @@
  */
 import type { Context, Hono } from 'hono';
 import type { ShareEvent, ShareGrant } from 'cursedbelt-core/sharing/model';
-import type { ShareStore } from './store.js';
+import type { AwaitableShareStore } from './contract.js';
 /** 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 declare const GROUP_SUBJECT_PREFIX = "group:";
@@ -72,8 +72,12 @@ export interface ShareRouterOptions<V extends ShareRouterViewer> {
     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);
+    /**
+     * The store — the sync `ShareStore` or the D1 `AsyncShareStore` (`./sharing/d1`); every
+     * call is awaited, and awaiting a sync store's plain value changes nothing. A function
+     * when it is per-request (a multi-tenant app, or a Worker whose D1 handle is per request).
+     */
+    shares: AwaitableShareStore | ((c: Context) => AwaitableShareStore);
     /** Who is asking. Returning null refuses every route with 401. */
     viewerOf: (c: Context) => V | null;
     /**
@@ -84,7 +88,7 @@ export interface ShareRouterOptions<V extends ShareRouterViewer> {
     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>;
+    extra?: (c: Context, id: string, viewer: V) => Record<string, unknown> | Promise<Record<string, unknown>>;
     /** How many audit lines the read carries. Default 50. */
     trailLimit?: number;
 }

package/dist/server/sharing/router.js

@@ -51,9 +51,11 @@ app, options) {
         const payload = {
             // 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) : {}),
+            // Awaited in this order — grants, trail, extra — which is the order the sync store
+            // was always read in.
+            grants: await shares.listForResource({ kind, id }),
+            events: await shares.events({ kind, id, limit: trailLimit }),
+            ...(extra ? await extra(c, id, viewer) : {}),
         };
         return c.json(payload);
     });
@@ -69,7 +71,7 @@ app, options) {
         if (body.level !== undefined && !isLevel(body.level)) {
             return c.json({ error: "level must be 'read' or 'write'" }, 400);
         }
-        const grant = shares.grant({
+        const grant = await shares.grant({
             kind,
             id,
             subject: { type: body.subject?.type === 'group' ? 'group' : 'user', id: subjectId },
@@ -87,7 +89,7 @@ app, options) {
         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 });
+        await shares.revoke({ kind, id, subject: parseSubjectParam(raw), revokedBy: viewer.email });
         return c.json({ ok: true });
     });
 }

package/dist/server/sharing/schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The sharing tables' names and DDL, with no driver attached — the ONE copy both the
+ * `bun:sqlite` migration (`./migrations.ts`) and a D1 app's `db/schema.sql` are built from.
+ *
+ * It is import-free on purpose: `./d1.ts` runs on `workerd`, and a Worker app generates its
+ * schema file from these statements rather than running DDL at request time. The migration
+ * runs exactly this list, so the two can never describe different tables. Why each table and
+ * each index exists is `./migrations.ts`'s header.
+ */
+export declare const SHARE_GRANTS_TABLE = "share_grants";
+export declare const SHARE_GROUPS_TABLE = "share_groups";
+export declare const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
+export declare const SHARE_EVENTS_TABLE = "share_events";
+/**
+ * Every statement of the `0001_share_grants` migration, in order. Idempotent (`IF NOT
+ * EXISTS` throughout), so a schema file built from it can be applied to a database that
+ * already has the tables.
+ */
+export declare const SHARE_DDL: readonly string[];

package/dist/server/sharing/schema.js

@@ -0,0 +1,88 @@
+/**
+ * The sharing tables' names and DDL, with no driver attached — the ONE copy both the
+ * `bun:sqlite` migration (`./migrations.ts`) and a D1 app's `db/schema.sql` are built from.
+ *
+ * It is import-free on purpose: `./d1.ts` runs on `workerd`, and a Worker app generates its
+ * schema file from these statements rather than running DDL at request time. The migration
+ * runs exactly this list, so the two can never describe different tables. Why each table and
+ * each index exists is `./migrations.ts`'s header.
+ */
+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";
+/**
+ * Every statement of the `0001_share_grants` migration, in order. Idempotent (`IF NOT
+ * EXISTS` throughout), so a schema file built from it can be applied to a database that
+ * already has the tables.
+ */
+export const SHARE_DDL = [
+    `
+				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.
+    `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".
+    `CREATE INDEX IF NOT EXISTS idx_share_grants_resource
+				 ON ${SHARE_GRANTS_TABLE} (app, kind, resource_id)`,
+    `
+				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 ''
+				)
+			`,
+    `
+				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.
+    `CREATE INDEX IF NOT EXISTS idx_share_group_members_subject
+				 ON ${SHARE_GROUP_MEMBERS_TABLE} (subject_id)`,
+    `
+				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.
+    `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.
+    `CREATE INDEX IF NOT EXISTS idx_share_events_subject
+				 ON ${SHARE_EVENTS_TABLE} (subject_id, event_id DESC)`,
+];

package/dist/server/sharing/sql.js

@@ -26,7 +26,7 @@
  * tested with hostile input; a consumer never quotes anything itself.
  */
 import { levelsMeeting, normalizeSubjectId } from "cursedbelt-core/sharing/model";
-import { SHARE_GRANTS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./migrations.js";
+import { SHARE_GRANTS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./schema.js";
 /**
  * Quote a string as a SQL literal.
  *