cursedbelt-server 4.27.0 → 4.29.0

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

@@ -0,0 +1,94 @@
+/**
+ * The store's contract with no driver attached: the input shapes both stores take, the
+ * {@link AsyncShareStore} a D1-backed store satisfies, and the two subject helpers.
+ *
+ * It lives apart from `./store.ts` so that `./d1.ts` — which runs on `workerd` — and its
+ * declaration file never reach a module that names `bun:sqlite`, not even as a type. The
+ * sync store re-exports everything here, so `cursedbelt-server/sharing` is unchanged.
+ */
+import type { ShareAccess, ShareEvent, ShareGrant, ShareGroup, ShareGroupMember, ShareLevel, ShareSubject, ShareViewer } from "cursedbelt-core/sharing/model";
+/** Shorthand for the common subject. `group(id)` is its sibling. */
+export declare const user: (id: string) => ShareSubject;
+export declare const group: (id: string) => ShareSubject;
+/** 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 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;
+}
+/** What `sharedSql` takes — the store supplies `app`. */
+export interface SharedSqlInput {
+    kind: string;
+    subjectId: string;
+    column: string;
+    atLeast?: ShareLevel;
+}
+/**
+ * The share store over an ASYNC database — `createD1ShareStore` in
+ * `cursedbelt-server/sharing/d1`.
+ *
+ * The same methods as the sync `ShareStore`, with the same names, arguments and meaning;
+ * every method that touches the database resolves instead of returning. `sharedSql` stays
+ * synchronous because it touches nothing: it emits the SAME fragment the sync store does, for
+ * an app to embed in its own D1 queries. `sharing/d1.spec.ts` checks the two stores expose
+ * exactly the same method names, so neither can grow a verb the other lacks.
+ */
+export interface AsyncShareStore {
+    /** The app this store speaks for. */
+    readonly app: string;
+    grant(input: GrantInput): Promise<ShareGrant>;
+    revoke(input: RevokeInput): Promise<ShareLevel | null>;
+    revokeResource(target: ShareTarget, revokedBy: string): Promise<number>;
+    revokeSubject(subject: ShareSubject, revokedBy: string): Promise<number>;
+    listForResource(target: ShareTarget): Promise<ShareGrant[]>;
+    listForSubject(subject: ShareSubject): Promise<ShareGrant[]>;
+    accessFor(target: ShareTarget, viewer: ShareViewer): Promise<ShareAccess>;
+    resourceIdsFor(kind: string, viewer: ShareViewer, atLeast?: ShareLevel): Promise<string[]>;
+    sharedSql(input: SharedSqlInput): string;
+    createGroup(input: {
+        id: string;
+        name: string;
+        createdBy: string;
+        note?: string;
+    }): Promise<ShareGroup>;
+    renameGroup(id: string, name: string, actor: string): Promise<void>;
+    deleteGroup(id: string, actor: string): Promise<void>;
+    listGroups(): Promise<ShareGroup[]>;
+    addGroupMember(groupId: string, subjectId: string, actor: string): Promise<void>;
+    removeGroupMember(groupId: string, subjectId: string, actor: string): Promise<void>;
+    listGroupMembers(groupId: string): Promise<ShareGroupMember[]>;
+    groupIdsFor(subjectId: string): Promise<string[]>;
+    events(query?: ShareEventQuery): Promise<ShareEvent[]>;
+}
+/**
+ * A value that may or may not be a promise — what a consumer holding EITHER store gets back
+ * from a call, and what it can always `await`.
+ */
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * Either store, as a consumer that works over both sees it: every method's result is
+ * {@link Awaitable}. `mountShareRoutes` takes this, and awaits every call — awaiting a
+ * synchronous value is a no-op, so the sync store's behaviour through it is unchanged.
+ */
+export type AwaitableShareStore = {
+    readonly [K in keyof AsyncShareStore]: AsyncShareStore[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Awaitable<R> : AsyncShareStore[K];
+};

package/dist/server/sharing/contract.js

@@ -0,0 +1,3 @@
+/** Shorthand for the common subject. `group(id)` is its sibling. */
+export const user = (id) => ({ type: "user", id });
+export const group = (id) => ({ type: "group", id });

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

@@ -0,0 +1,77 @@
+/**
+ * `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 { type ShareEvent } from "cursedbelt-core/sharing/model";
+import type { D1LikeDatabase } from "../d1/types.js";
+import type { AsyncShareStore } from "./contract.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 declare function createD1ShareStore(options: D1ShareStoreOptions): AsyncShareStore;

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 });
     });
 }