cursedbelt-server 1.0.0

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

@@ -0,0 +1,111 @@
+/**
+ * `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 } 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 declare const GROUP_SUBJECT_PREFIX = "group:";
+/** Split a URL subject segment into the store's `{type, id}` pair. */
+export declare function parseSubjectParam(raw: string): {
+    type: 'user' | 'group';
+    id: string;
+};
+/** The inverse — what a client puts in the path. */
+export declare const subjectParam: (subject: {
+    type: "user" | "group";
+    id: string;
+}) => string;
+/** 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[];
+}
+/**
+ * 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 declare function mountShareRoutes<V extends ShareRouterViewer>(app: Hono<any>, options: ShareRouterOptions<V>): void;

package/dist/server/sharing/router.js

@@ -0,0 +1,93 @@
+/** 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) {
+    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) => encodeURIComponent(subject.type === 'group' ? GROUP_SUBJECT_PREFIX + subject.id : subject.id);
+const isLevel = (v) => 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(
+// 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, options) {
+    const { base, kind, viewerOf, mustOwn, extra, trailLimit = 50 } = options;
+    const storeOf = (c) => typeof options.shares === 'function' ? options.shares(c) : options.shares;
+    /** The three-step preamble every route shares: identity, id, ownership. */
+    async function enter(c) {
+        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 = {
+            // 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(() => ({})));
+        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/dist/server/sharing/sql.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 { type ShareLevel } from "cursedbelt-core/sharing/model";
+/**
+ * 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 declare function sqlLiteral(value: string): string;
+export declare function sqlColumn(column: string): string;
+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 declare function sharedResourceSql(options: SharedResourceSqlOptions): string;

package/dist/server/sharing/sql.js

@@ -0,0 +1,88 @@
+/**
+ * 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 } 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) {
+    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) {
+    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;
+}
+/**
+ * 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) {
+    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}))))`);
+}

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

@@ -0,0 +1,173 @@
+/**
+ * The store: grants, groups, revocation and the audit trail, over `bun:sqlite`.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * ```ts
+ * const shares = createShareStore({ db, app: "family", onEvent: notify });
+ *
+ * shares.grant({ kind: "person", id, subject: user("aunt@example.com"),
+ *                level: "read", grantedBy: viewer.email });
+ * shares.accessFor({ kind: "person", id }, { subjectId: viewer.email }); // "read"
+ * shares.revoke({ kind: "person", id, subject: user("aunt@example.com"),
+ *                 revokedBy: viewer.email });
+ * ```
+ * …and inside the app's own queries, `sharedResourceSql` (see `./sql.ts`) is the
+ * WHERE clause, so a filtered row never surfaces as a count either.
+ *
+ * ── 🔴 Five properties this file exists to guarantee ────────────────────────
+ *  1. **Every mutation writes its own audit row, in the same transaction.** There
+ *     is no `recordEvent` in the public API and no way to grant without logging.
+ *     An audit trail a caller has to remember to write is a trail with holes
+ *     exactly where somebody was in a hurry.
+ *  2. **A revoked grant's history survives it.** Revocation deletes the grant row
+ *     and appends an event; nothing here deletes an event, ever.
+ *  3. **Deleting the RESOURCE is a revocation, not an orphan.** `revokeResource`
+ *     exists so an app deleting a row has one call to make. A grant left behind
+ *     for a deleted id silently becomes access to whatever later reuses that id.
+ *  4. **The notification hook cannot break a write.** `onEvent` runs AFTER the
+ *     transaction commits and its throw is swallowed with a warning: a mail server
+ *     being down must not lose the grant the owner just made.
+ *  5. **A subject is normalized once, here.** Callers pass whatever the form gave
+ *     them; `normalizeSubjectId` is applied on the way in AND on the way to a
+ *     lookup, so a grant made to `"  Ameena@Example.com "` is found by the session
+ *     that signs in as `ameena@example.com`.
+ */
+import type { Database } from "bun:sqlite";
+import { type ShareAccess, type ShareEvent, type ShareGrant, type ShareGroup, type ShareGroupMember, type ShareLevel, type ShareSubject, type 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 ShareStoreOptions {
+    db: Database;
+    /** The satellite this store speaks for. Fixed at construction so `app` cannot
+     *  be got wrong per call — the commonest way a grant becomes invisible. */
+    app: string;
+    /**
+     * Notified after every committed mutation — the notification hook ca's model
+     * had, as a seam rather than a dependency.
+     *
+     * 🔴 It stays a seam now that the other half EXISTS. `cursedbelt/server/
+     * notifications` landed the same day this did, so a consumer can wire the two
+     * in one line — `onEvent: (e) => notifications.notify({ userId: e.subject.id,
+     * … })` — and `describeShareEvent` in the vocabulary is the wording both the
+     * panel and that notification use. What must NOT happen is this store
+     * importing that one: an app is entitled to a sharing model with no bell (the
+     * grant is still audited), the subject of a GROUP grant is a group id and not
+     * a person to notify, and an app knows which of its users to address where
+     * this primitive only knows a subject id.
+     */
+    onEvent?: (event: ShareEvent) => void;
+    /** Injectable clock, for tests that assert ordering. ISO-8601 strings. */
+    now?: () => string;
+}
+export interface GrantInput extends ShareTarget {
+    subject: ShareSubject;
+    level: ShareLevel;
+    grantedBy: string;
+    note?: string;
+}
+export interface RevokeInput extends ShareTarget {
+    subject: ShareSubject;
+    revokedBy: string;
+    note?: string;
+}
+export interface ShareEventQuery {
+    kind?: string;
+    id?: string;
+    subject?: ShareSubject;
+    /** Newest first, capped. Default 200 — a panel shows a page, and an unbounded
+     *  audit read on a busy resource is the query that times out in production. */
+    limit?: number;
+}
+export type ShareStore = ReturnType<typeof createShareStore>;
+/**
+ * Open (and migrate) the sharing tables in this database, returning the store.
+ *
+ * Idempotent: safe to call once per boot per `db`, and safe to call in a database
+ * that already has the tables (the migration runner records what it applied).
+ */
+export declare function createShareStore(options: ShareStoreOptions): {
+    /** The app this store speaks for — exposed so a consumer can build its own
+     *  `sharedResourceSql` call without re-declaring the name. */
+    app: string;
+    /**
+     * Give `subject` access to a resource, or change the access they have.
+     *
+     * An unchanged re-grant is still recorded as a `grant` event: "the owner
+     * confirmed this on Tuesday" is a fact somebody reading the trail wants, and
+     * suppressing it would make an idempotent API silently unauditable.
+     */
+    grant(input: GrantInput): ShareGrant;
+    /** Take access away. Returns the level that was removed, or null when there
+     *  was nothing to remove — in which case nothing is logged, because an audit
+     *  trail full of "revoked nothing" is one nobody reads. */
+    revoke(input: RevokeInput): ShareLevel | null;
+    /**
+     * Revoke EVERY grant on one resource — what an app calls when it deletes the
+     * record. Returns how many were removed.
+     *
+     * 🔴 Not optional housekeeping. Resource ids are app-minted, and a grant left
+     * behind for a deleted id becomes access to whatever is created with that id
+     * later. `apps/family` calls this in the same transaction as deleting a
+     * person.
+     */
+    revokeResource(target: ShareTarget, revokedBy: string): number;
+    /** Revoke everything shared with one subject, across every kind — the
+     *  offboarding call. A person losing their fleet account keeps nothing. */
+    revokeSubject(subject: ShareSubject, revokedBy: string): number;
+    /** Who can see this record, strongest first then oldest — the panel's read. */
+    listForResource(target: ShareTarget): ShareGrant[];
+    /** Everything shared with one subject — "shared with you". Group grants are
+     *  NOT expanded here; use {@link resourceIdsFor} for the resolved answer. */
+    listForSubject(subject: ShareSubject): ShareGrant[];
+    /**
+     * What may this viewer do with this resource — the resolver.
+     *
+     * The strongest of their own grant and every group they are in, computed in
+     * SQL. `resolveAccess` in `cursedbelt-core/sharing` is the same rule written as a
+     * pure function, and `store.spec.ts` checks the two agree.
+     */
+    accessFor(target: ShareTarget, viewer: ShareViewer): ShareAccess;
+    /** Every resource of `kind` this viewer reaches at `atLeast` or above.
+     *  For filtering rows in the app's OWN query, prefer `sharedResourceSql`. */
+    resourceIdsFor(kind: string, viewer: ShareViewer, atLeast?: ShareLevel): string[];
+    /** The WHERE-clause half, bound to this store's app. See `./sql.ts` for why
+     *  a fragment rather than a list of ids. */
+    sharedSql(input: {
+        kind: string;
+        subjectId: string;
+        column: string;
+        atLeast?: ShareLevel;
+    }): string;
+    createGroup(input: {
+        id: string;
+        name: string;
+        createdBy: string;
+        note?: string;
+    }): ShareGroup;
+    renameGroup(id: string, name: string, actor: string): void;
+    /**
+     * Delete a group — and every grant made TO it.
+     *
+     * 🔴 The grants go with it, explicitly, each with its own revoke event. The
+     * `ON DELETE CASCADE` on membership does not reach `share_grants` (a group
+     * subject is a string, not a foreign key, because the same column holds user
+     * addresses), so a group deleted without this leaves rows nobody can see in
+     * any UI and nothing can revoke.
+     */
+    deleteGroup(id: string, actor: string): void;
+    listGroups(): ShareGroup[];
+    addGroupMember(groupId: string, subjectId: string, actor: string): void;
+    removeGroupMember(groupId: string, subjectId: string, actor: string): void;
+    listGroupMembers(groupId: string): ShareGroupMember[];
+    /** Which groups is this person in — the one place membership is resolved. */
+    groupIdsFor(subjectId: string): string[];
+    /** The trail, newest first. Filter by resource, by subject, or neither. */
+    events(query?: ShareEventQuery): ShareEvent[];
+};