cursedbelt-server 1.0.0

package/dist/server/audit/migrations.js

@@ -0,0 +1,79 @@
+// ONE shared append-only table backs every namespace's audit trail — not a
+// shadow table per business table. cursedshell's `defineService` mutations
+// are dispatched against host-injected Store interfaces (`NotesStore`,
+// `AliasStore`, …), never raw SQL the host's DB owns, so there is no single
+// business table a `CREATE TRIGGER` could attach to. `(namespace, target_id)`
+// plays the role a per-table shadow table would: history for cursedshell's
+// `todo` plugin and an app's own `todo` table can coexist without collision.
+export const AUDIT_LOG_MIGRATIONS = [
+    {
+        name: '0001_audit_log',
+        up(db) {
+            db.run(`
+        CREATE TABLE IF NOT EXISTS audit_log (
+          audit_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+          namespace    TEXT NOT NULL,
+          mutation_key TEXT NOT NULL,
+          target_id    TEXT NOT NULL,
+          version_key  INTEGER NOT NULL,
+          operation    TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+          tenant_id    TEXT NOT NULL,
+          changed_by   TEXT,
+          changed_at   TEXT NOT NULL,
+          snapshot_data TEXT,
+          UNIQUE(tenant_id, namespace, target_id, version_key)
+        )
+      `);
+            // Time-travel + timeline() reads key on (tenant_id, namespace, target_id);
+            // changed_at additionally covers the "state as of a timestamp" query.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_audit_log_lookup ON audit_log(tenant_id, namespace, target_id, changed_at)`);
+        },
+    },
+    {
+        // 05 §A1, the repair half. `0001` above was corrected in place so a fresh
+        // database is right from the start — but `CREATE TABLE IF NOT EXISTS` means
+        // an EXISTING `audit_log` keeps the old `UNIQUE(namespace, target_id,
+        // version_key)`, which is cross-tenant: two tenants whose ids collide
+        // (`target_id` is namespace-scoped, not minted per tenant — a plugin's
+        // `todo` row "5" is "5" for everybody) contend for the same version
+        // sequence, and one tenant's write fails against a row it cannot read.
+        //
+        // A table-level UNIQUE cannot be altered in SQLite, so this rebuilds. It is
+        // ordered AFTER `0001` and guarded on the old constraint actually being
+        // present, so on a fresh database it is a no-op rather than a needless copy
+        // of the whole audit trail.
+        name: '0002_tenant_scoped_version',
+        up(db) {
+            const schema = db
+                .query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'audit_log'")
+                .get()?.sql;
+            if (!schema || !/UNIQUE\s*\(\s*namespace/i.test(schema))
+                return;
+            db.run(`
+        CREATE TABLE audit_log_0002 (
+          audit_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+          namespace    TEXT NOT NULL,
+          mutation_key TEXT NOT NULL,
+          target_id    TEXT NOT NULL,
+          version_key  INTEGER NOT NULL,
+          operation    TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+          tenant_id    TEXT NOT NULL,
+          changed_by   TEXT,
+          changed_at   TEXT NOT NULL,
+          snapshot_data TEXT,
+          UNIQUE(tenant_id, namespace, target_id, version_key)
+        )
+      `);
+            db.run(`
+        INSERT INTO audit_log_0002
+          (audit_id, namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_by, changed_at, snapshot_data)
+        SELECT audit_id, namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_by, changed_at, snapshot_data
+          FROM audit_log
+      `);
+            db.run('DROP TABLE audit_log');
+            db.run('ALTER TABLE audit_log_0002 RENAME TO audit_log');
+            // The rename does not carry the index — it was dropped with the old table.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_audit_log_lookup ON audit_log(tenant_id, namespace, target_id, changed_at)`);
+        },
+    },
+];

package/dist/server/audit/sqliteSink.d.ts

@@ -0,0 +1,36 @@
+import type { Database } from 'bun:sqlite';
+import type { AuditEntryInput, AuditRecord } from 'cwip/audit';
+/**
+ * The persistent audit sink: one shared `audit_log` table (see `./migrations`),
+ * versioned per `(namespace, targetId)`. Runs its migration on first
+ * construction (idempotent — safe to call once per boot per `db`).
+ *
+ *   const sink = createSqliteAuditSink(db);
+ *   const router = buildServerRouter(runtime, config, { verifyToken, audit: { sink } });
+ *
+ * Deliberately NOT annotated `: AuditSink` — see `cwip/audit`'s
+ * `createMemoryAuditSink` for why (this sink is fully synchronous under the
+ * hood; the interface's async-capable signature would erase that at every
+ * call site). Structurally assignable to `AuditSink` wherever one is expected.
+ */
+export declare function createSqliteAuditSink(db: Database): {
+    record(entry: AuditEntryInput): AuditRecord;
+    timeline(tenantId: string, namespace: string, targetId: string): AuditRecord[];
+};
+/**
+ * Every read below takes `tenantId` FIRST and as a required argument (05 §A1).
+ *
+ * `audit_log` is ONE shared table across every namespace and every tenant, and
+ * its lookup key `(namespace, targetId)` is a business key a plugin chose — not a
+ * minted id. So a read that omits the tenant is not merely broad: it returns
+ * another tenant's snapshot for the same row number, which is the whole audit
+ * trail's contents. Making the parameter optional (defaulting to "all tenants")
+ * would put that one keystroke away, so it is required and positioned where a
+ * mistaken call fails to typecheck rather than silently widening.
+ */
+/** Query 1: the record's state as of a given moment (last version at or before `at`). */
+export declare function auditStateAt(db: Database, tenantId: string, namespace: string, targetId: string, at: string): AuditRecord | null;
+/** Query 2: jump directly to a specific `versionKey`. */
+export declare function auditStateAtVersion(db: Database, tenantId: string, namespace: string, targetId: string, versionKey: number): AuditRecord | null;
+/** Query 3: step one version back/forward from `currentVersion` (for a UI "prev/next" control). */
+export declare function auditStep(db: Database, tenantId: string, namespace: string, targetId: string, currentVersion: number, direction: 'back' | 'forward'): AuditRecord | null;

package/dist/server/audit/sqliteSink.js

@@ -0,0 +1,95 @@
+import { runMigrations } from '../migration/runner';
+import { AUDIT_LOG_MIGRATIONS } from './migrations';
+function rowToRecord(row) {
+    return {
+        namespace: row.namespace,
+        mutationKey: row.mutation_key,
+        targetId: row.target_id,
+        versionKey: row.version_key,
+        operation: row.operation,
+        tenantId: row.tenant_id,
+        changedBy: row.changed_by ?? undefined,
+        changedAt: row.changed_at,
+        snapshot: row.snapshot_data == null ? null : JSON.parse(row.snapshot_data),
+    };
+}
+/**
+ * The persistent audit sink: one shared `audit_log` table (see `./migrations`),
+ * versioned per `(namespace, targetId)`. Runs its migration on first
+ * construction (idempotent — safe to call once per boot per `db`).
+ *
+ *   const sink = createSqliteAuditSink(db);
+ *   const router = buildServerRouter(runtime, config, { verifyToken, audit: { sink } });
+ *
+ * Deliberately NOT annotated `: AuditSink` — see `cwip/audit`'s
+ * `createMemoryAuditSink` for why (this sink is fully synchronous under the
+ * hood; the interface's async-capable signature would erase that at every
+ * call site). Structurally assignable to `AuditSink` wherever one is expected.
+ */
+export function createSqliteAuditSink(db) {
+    runMigrations(db, AUDIT_LOG_MIGRATIONS);
+    // Scoped by tenant (05 §A1). `targetId` is a namespace-local business key, not
+    // a minted global id — a plugin's `todo` row "5" is "5" for every tenant — so
+    // an unscoped MAX() hands tenant B a version number tenant A already used, and
+    // the UNIQUE then refuses B's write over a row B may not read.
+    const nextVersion = db.prepare('SELECT COALESCE(MAX(version_key), 0) + 1 AS v FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ?');
+    const insert = db.prepare(`
+    INSERT INTO audit_log
+      (namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_by, changed_at, snapshot_data)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const selectTimeline = db.prepare('SELECT * FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ? ORDER BY version_key ASC');
+    return {
+        record(entry) {
+            // No `await` between the read and the write below — bun:sqlite's calls are
+            // synchronous, so nothing else can interleave and race the version number.
+            const record = db.transaction(() => {
+                const { v: versionKey } = nextVersion.get(entry.tenantId, entry.namespace, entry.targetId);
+                const changedAt = entry.changedAt ?? new Date().toISOString();
+                insert.run(entry.namespace, entry.mutationKey, entry.targetId, versionKey, entry.operation, entry.tenantId, entry.changedBy ?? null, changedAt, entry.snapshot == null ? null : JSON.stringify(entry.snapshot));
+                return { ...entry, versionKey, changedAt };
+            })();
+            return record;
+        },
+        timeline(tenantId, namespace, targetId) {
+            const rows = selectTimeline.all(tenantId, namespace, targetId);
+            return rows.map(rowToRecord);
+        },
+    };
+}
+/**
+ * Every read below takes `tenantId` FIRST and as a required argument (05 §A1).
+ *
+ * `audit_log` is ONE shared table across every namespace and every tenant, and
+ * its lookup key `(namespace, targetId)` is a business key a plugin chose — not a
+ * minted id. So a read that omits the tenant is not merely broad: it returns
+ * another tenant's snapshot for the same row number, which is the whole audit
+ * trail's contents. Making the parameter optional (defaulting to "all tenants")
+ * would put that one keystroke away, so it is required and positioned where a
+ * mistaken call fails to typecheck rather than silently widening.
+ */
+/** Query 1: the record's state as of a given moment (last version at or before `at`). */
+export function auditStateAt(db, tenantId, namespace, targetId, at) {
+    const row = db
+        .prepare('SELECT * FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ? AND changed_at <= ? ORDER BY version_key DESC LIMIT 1')
+        .get(tenantId, namespace, targetId, at);
+    return row ? rowToRecord(row) : null;
+}
+/** Query 2: jump directly to a specific `versionKey`. */
+export function auditStateAtVersion(db, tenantId, namespace, targetId, versionKey) {
+    const row = db
+        .prepare('SELECT * FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ? AND version_key = ?')
+        .get(tenantId, namespace, targetId, versionKey);
+    return row ? rowToRecord(row) : null;
+}
+/** Query 3: step one version back/forward from `currentVersion` (for a UI "prev/next" control). */
+export function auditStep(db, tenantId, namespace, targetId, currentVersion, direction) {
+    const row = direction === 'back'
+        ? db
+            .prepare('SELECT * FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ? AND version_key < ? ORDER BY version_key DESC LIMIT 1')
+            .get(tenantId, namespace, targetId, currentVersion)
+        : db
+            .prepare('SELECT * FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ? AND version_key > ? ORDER BY version_key ASC LIMIT 1')
+            .get(tenantId, namespace, targetId, currentVersion);
+    return row ? rowToRecord(row) : null;
+}

package/dist/server/audit/sqliteSink.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/audit/sqliteSink.test.js

@@ -0,0 +1,180 @@
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { auditStateAt, auditStateAtVersion, auditStep, createSqliteAuditSink } from './sqliteSink';
+let db;
+beforeEach(() => {
+    db = new Database(':memory:');
+});
+describe('createSqliteAuditSink', () => {
+    it('assigns sequential version keys per (namespace, targetId) and persists snapshots', async () => {
+        const sink = createSqliteAuditSink(db);
+        const v1 = await sink.record({
+            namespace: 'todo',
+            mutationKey: 'add',
+            targetId: '5',
+            operation: 'insert',
+            snapshot: { id: '5', title: 'a' },
+            tenantId: 't1',
+            changedBy: 'u1',
+        });
+        const v2 = await sink.record({
+            namespace: 'todo',
+            mutationKey: 'update',
+            targetId: '5',
+            operation: 'update',
+            snapshot: { id: '5', title: 'b' },
+            tenantId: 't1',
+        });
+        expect(v1.versionKey).toBe(1);
+        expect(v2.versionKey).toBe(2);
+        expect(v1.snapshot).toEqual({ id: '5', title: 'a' });
+    });
+    it('stores a null snapshot for delete tombstones', async () => {
+        const sink = createSqliteAuditSink(db);
+        const deleted = await sink.record({
+            namespace: 'todo',
+            mutationKey: 'remove',
+            targetId: '5',
+            operation: 'delete',
+            snapshot: null,
+            tenantId: 't1',
+        });
+        expect(deleted.snapshot).toBeNull();
+    });
+    it('is idempotent to construct twice against the same db (migration re-run is a no-op)', () => {
+        createSqliteAuditSink(db);
+        expect(() => createSqliteAuditSink(db)).not.toThrow();
+    });
+    it('timeline() returns full history oldest-first', async () => {
+        const sink = createSqliteAuditSink(db);
+        await sink.record({
+            namespace: 'todo',
+            mutationKey: 'add',
+            targetId: '5',
+            operation: 'insert',
+            snapshot: { title: 'a' },
+            tenantId: 't1',
+        });
+        await sink.record({
+            namespace: 'todo',
+            mutationKey: 'remove',
+            targetId: '5',
+            operation: 'delete',
+            snapshot: null,
+            tenantId: 't1',
+        });
+        const timeline = await sink.timeline('t1', 'todo', '5');
+        expect(timeline.map((r) => r.operation)).toEqual(['insert', 'delete']);
+    });
+    // 05 §A1. `targetId` is a namespace-local business key, not a minted id, so
+    // two tenants routinely mutate "5". Before the tenant joined the UNIQUE and
+    // the MAX() that feeds it, tenant B's first write took version 2 — or was
+    // refused outright by tenant A's row — and B's timeline read A's history.
+    it('versions and reads per TENANT, not just per (namespace, targetId)', async () => {
+        const sink = createSqliteAuditSink(db);
+        const entry = (tenantId, title) => ({
+            namespace: 'todo',
+            mutationKey: 'add',
+            targetId: '5',
+            operation: 'insert',
+            snapshot: { title },
+            tenantId,
+        });
+        const first = await sink.record(entry('t1', 'a'));
+        const second = await sink.record(entry('t2', 'b'));
+        expect(first.versionKey).toBe(1);
+        expect(second.versionKey).toBe(1);
+        expect((await sink.timeline('t2', 'todo', '5')).map((r) => r.snapshot)).toEqual([{ title: 'b' }]);
+        expect(auditStateAtVersion(db, 't1', 'todo', '5', 1)?.snapshot).toEqual({ title: 'a' });
+    });
+    // The repair half: a database created before this landing carries
+    // `UNIQUE(namespace, target_id, version_key)` and `CREATE TABLE IF NOT EXISTS`
+    // would never correct it, so `0002` rebuilds — preserving the rows.
+    it('rebuilds a pre-existing audit_log that carries the cross-tenant UNIQUE', () => {
+        db.run(`
+      CREATE TABLE audit_log (
+        audit_id     INTEGER PRIMARY KEY AUTOINCREMENT,
+        namespace    TEXT NOT NULL,
+        mutation_key TEXT NOT NULL,
+        target_id    TEXT NOT NULL,
+        version_key  INTEGER NOT NULL,
+        operation    TEXT NOT NULL CHECK (operation IN ('insert', 'update', 'delete')),
+        tenant_id    TEXT NOT NULL,
+        changed_by   TEXT,
+        changed_at   TEXT NOT NULL,
+        snapshot_data TEXT,
+        UNIQUE(namespace, target_id, version_key)
+      )
+    `);
+        db.run(`INSERT INTO audit_log (namespace, mutation_key, target_id, version_key, operation, tenant_id, changed_at, snapshot_data)
+       VALUES ('todo', 'add', '5', 1, 'insert', 't1', '2026-01-01T00:00:00.000Z', '{"title":"kept"}')`);
+        const sink = createSqliteAuditSink(db);
+        const schema = db.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'audit_log'").get().sql;
+        expect(schema).toContain('UNIQUE(tenant_id, namespace, target_id, version_key)');
+        // The history survived the rebuild …
+        expect(auditStateAtVersion(db, 't1', 'todo', '5', 1)?.snapshot).toEqual({ title: 'kept' });
+        // … and the constraint the rebuild exists for now holds.
+        const other = sink.record({
+            namespace: 'todo',
+            mutationKey: 'add',
+            targetId: '5',
+            operation: 'insert',
+            snapshot: { title: 'theirs' },
+            tenantId: 't2',
+        });
+        expect(other.versionKey).toBe(1);
+    });
+});
+describe('time-travel queries', () => {
+    const seed = async () => {
+        const sink = createSqliteAuditSink(db);
+        await sink.record({
+            namespace: 'todo',
+            mutationKey: 'add',
+            targetId: '5',
+            operation: 'insert',
+            snapshot: { title: 'v1' },
+            tenantId: 't1',
+            changedAt: '2026-01-01T00:00:00.000Z',
+        });
+        await sink.record({
+            namespace: 'todo',
+            mutationKey: 'update',
+            targetId: '5',
+            operation: 'update',
+            snapshot: { title: 'v2' },
+            tenantId: 't1',
+            changedAt: '2026-01-02T00:00:00.000Z',
+        });
+        await sink.record({
+            namespace: 'todo',
+            mutationKey: 'update',
+            targetId: '5',
+            operation: 'update',
+            snapshot: { title: 'v3' },
+            tenantId: 't1',
+            changedAt: '2026-01-03T00:00:00.000Z',
+        });
+    };
+    it('auditStateAt returns the last version at or before the given time', async () => {
+        await seed();
+        const state = auditStateAt(db, 't1', 'todo', '5', '2026-01-02T12:00:00.000Z');
+        expect(state?.snapshot).toEqual({ title: 'v2' });
+    });
+    it('auditStateAt returns null before any history exists', async () => {
+        await seed();
+        expect(auditStateAt(db, 't1', 'todo', '5', '2025-12-31T00:00:00.000Z')).toBeNull();
+    });
+    it('auditStateAtVersion jumps directly to a version', async () => {
+        await seed();
+        expect(auditStateAtVersion(db, 't1', 'todo', '5', 1)?.snapshot).toEqual({ title: 'v1' });
+        expect(auditStateAtVersion(db, 't1', 'todo', '5', 99)).toBeNull();
+    });
+    it('auditStep walks back and forward one version', async () => {
+        await seed();
+        expect(auditStep(db, 't1', 'todo', '5', 2, 'back')?.versionKey).toBe(1);
+        expect(auditStep(db, 't1', 'todo', '5', 2, 'forward')?.versionKey).toBe(3);
+        expect(auditStep(db, 't1', 'todo', '5', 1, 'back')).toBeNull();
+        expect(auditStep(db, 't1', 'todo', '5', 3, 'forward')).toBeNull();
+    });
+});

package/dist/server/auth/cookie.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from 'hono';
+/**
+ * Cookie helpers on `hono/cookie` (replacing `cookie-parser` + Express
+ * `res.cookie`). Two cookies, two deliberately-different `sameSite` postures:
+ *
+ *  - `access_token` — httpOnly, **`sameSite: Lax`** so it rides top-level
+ *    navigations (a returning user lands authenticated). The JWT is the auth
+ *    credential; JS must never read it.
+ *  - `csrf_token` — JS-readable (the SPA echoes it in a header), **`sameSite:
+ *    Strict`** so it is NOT attached to cross-site requests. The two MUST stay
+ *    separate cookies (see {@link ./csrf}).
+ */
+export declare const AUTH_COOKIE_NAME = "access_token";
+/** Read the httpOnly auth cookie (the access JWT), or undefined. */
+export declare function readAuthCookie(c: Context): string | undefined;
+/**
+ * Write the auth cookie. `maxAge` is seconds (cookie spec) — pass the access
+ * token's lifetime. httpOnly + `sameSite: Lax`, secure in production.
+ */
+export declare function writeAuthCookie(c: Context, token: string, maxAge: number): void;
+/** Clear the auth cookie (logout). */
+export declare function clearAuthCookie(c: Context): void;

package/dist/server/auth/cookie.js

@@ -0,0 +1,35 @@
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
+/**
+ * Cookie helpers on `hono/cookie` (replacing `cookie-parser` + Express
+ * `res.cookie`). Two cookies, two deliberately-different `sameSite` postures:
+ *
+ *  - `access_token` — httpOnly, **`sameSite: Lax`** so it rides top-level
+ *    navigations (a returning user lands authenticated). The JWT is the auth
+ *    credential; JS must never read it.
+ *  - `csrf_token` — JS-readable (the SPA echoes it in a header), **`sameSite:
+ *    Strict`** so it is NOT attached to cross-site requests. The two MUST stay
+ *    separate cookies (see {@link ./csrf}).
+ */
+export const AUTH_COOKIE_NAME = 'access_token';
+const isProd = () => process.env.NODE_ENV === 'production';
+/** Read the httpOnly auth cookie (the access JWT), or undefined. */
+export function readAuthCookie(c) {
+    return getCookie(c, AUTH_COOKIE_NAME);
+}
+/**
+ * Write the auth cookie. `maxAge` is seconds (cookie spec) — pass the access
+ * token's lifetime. httpOnly + `sameSite: Lax`, secure in production.
+ */
+export function writeAuthCookie(c, token, maxAge) {
+    setCookie(c, AUTH_COOKIE_NAME, token, {
+        httpOnly: true,
+        secure: isProd(),
+        sameSite: 'Lax',
+        maxAge,
+        path: '/',
+    });
+}
+/** Clear the auth cookie (logout). */
+export function clearAuthCookie(c) {
+    deleteCookie(c, AUTH_COOKIE_NAME, { path: '/' });
+}

package/dist/server/auth/csrf.d.ts

@@ -0,0 +1,42 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Double-submit CSRF guard for the cookie-auth + ctgr GET-tunnel model.
+ *
+ * Because mutations tunnel through a GET (the ctgr twin) and the auth cookie is
+ * `sameSite: Lax`, a cross-site top-level navigation could otherwise trigger a
+ * state change. We defend with a JS-readable, `sameSite: Strict` `csrf_token`
+ * cookie that the SPA echoes back in the `x-csrf-token` header. A cross-origin page
+ * can neither read the victim's cookie nor (Strict) cause it to be sent on a
+ * cross-site request, so it cannot forge the header.
+ *
+ * Behavior:
+ *  - Safe verbs (GET/HEAD) OUTSIDE the protected prefix: mint the `csrf_token`
+ *    cookie if absent (so a returning user has it on first paint), then continue.
+ *    Genuine reads are never CSRF-checked.
+ *  - ANY request whose path starts with the protected prefix (default `/ctgr`),
+ *    regardless of HTTP method: require `header === cookie`, else 403. Every ctgr
+ *    request is a tunneled mutation — and the twin rides a *GET* — so the check must
+ *    fire even on GET here, or the exact attack CSRF defends against (a cross-site
+ *    navigation/`<img>` to a `/ctgr*` mutation) slips through. Enforcing on the
+ *    prefix (not the verb) keeps the guarantee independent of where task-25's
+ *    `unGETify` sits in the chain. (Invariant #2: ctgr protection may never weaken.)
+ *  - Mutating verbs OUTSIDE the prefix are NOT checked here (in production all
+ *    mutations come through ctgr; direct verbs are internal/test traffic).
+ *
+ * MOUNT GLOBALLY — `app.use('*', createCsrfMiddleware())`. It matches the prefix with
+ * a plain `path.startsWith`, so it is immune to Hono's `/ctgr*`-doesn't-match wildcard
+ * gotcha; do NOT mount it on `CTGR_ROUTE_PATTERN` (that pattern is for the `unGETify`
+ * decode mount) — a prefix-only mount would never run on normal reads and so would
+ * never mint the `csrf_token` cookie.
+ */
+export interface CsrfOptions {
+    /** Path prefix whose requests are CSRF-checked. Default `/ctgr`. */
+    protectedPrefix?: string;
+    /** Cookie name. Default `csrf_token`. */
+    cookieName?: string;
+    /** Request header the SPA echoes the token in. Default `x-csrf-token`. */
+    headerName?: string;
+}
+export declare const CSRF_COOKIE_NAME = "csrf_token";
+export declare const CSRF_HEADER_NAME = "x-csrf-token";
+export declare function createCsrfMiddleware(opts?: CsrfOptions): MiddlewareHandler;

package/dist/server/auth/csrf.js

@@ -0,0 +1,36 @@
+import { getCookie, setCookie } from 'hono/cookie';
+import { ApiError, toErrorEnvelope } from '../errors';
+export const CSRF_COOKIE_NAME = 'csrf_token';
+export const CSRF_HEADER_NAME = 'x-csrf-token';
+const isProd = () => process.env.NODE_ENV === 'production';
+export function createCsrfMiddleware(opts = {}) {
+    const prefix = opts.protectedPrefix ?? '/ctgr';
+    const cookieName = opts.cookieName ?? CSRF_COOKIE_NAME;
+    const headerName = opts.headerName ?? CSRF_HEADER_NAME;
+    return async (c, next) => {
+        const method = c.req.method;
+        const isProtected = c.req.path.startsWith(prefix);
+        // Genuine reads (outside the ctgr tunnel): mint the cookie, never enforce.
+        if (!isProtected && (method === 'GET' || method === 'HEAD')) {
+            if (!getCookie(c, cookieName)) {
+                setCookie(c, cookieName, crypto.randomUUID(), {
+                    httpOnly: false, // the SPA must read it to echo it back
+                    secure: isProd(),
+                    sameSite: 'Strict',
+                    path: '/',
+                });
+            }
+            return next();
+        }
+        // Every ctgr request is a tunneled mutation (the twin is a GET) — enforce here
+        // regardless of verb. Non-ctgr mutating verbs fall through unchecked.
+        if (isProtected) {
+            const header = c.req.header(headerName);
+            const cookie = getCookie(c, cookieName);
+            if (!header || header !== cookie) {
+                return c.json(toErrorEnvelope(new ApiError(403, 'Invalid CSRF token')), 403);
+            }
+        }
+        return next();
+    };
+}

package/dist/server/auth/fileTokenSigner.d.ts

@@ -0,0 +1,10 @@
+import type { FileTokenSigner } from '../storage/binaryServerStore';
+export type Rs256FileTokenSignerOptions = {
+    /** PKCS8 PEM private key. `\n` escape sequences are accepted (env-var friendly). */
+    privateKeyPem: string;
+    /** The `iss` claim — must match the issuer the tenant was registered with. */
+    issuer: string;
+    /** Token lifetime in seconds (default 6h — long enough for a paused, resumed video). */
+    ttlSeconds?: number;
+};
+export declare function createRs256FileTokenSigner(opts: Rs256FileTokenSignerOptions): FileTokenSigner;

package/dist/server/auth/fileTokenSigner.js

@@ -0,0 +1,22 @@
+import { importPKCS8, SignJWT } from 'jose';
+export function createRs256FileTokenSigner(opts) {
+    const ttl = opts.ttlSeconds ?? 6 * 60 * 60;
+    const pem = opts.privateKeyPem.includes('-----')
+        ? opts.privateKeyPem.replace(/\\n/g, '\n')
+        : Buffer.from(opts.privateKeyPem, 'base64').toString('utf8');
+    // Lazy: a bad key must surface as a sign-time error, not an unhandled
+    // rejection parked on a module-scope promise from construction time.
+    let keyPromise = null;
+    return async (claims) => {
+        keyPromise ??= importPKCS8(pem, 'RS256');
+        const key = await keyPromise;
+        // Drop undefined values — jose serializes them as null otherwise.
+        const payload = Object.fromEntries(Object.entries(claims).filter(([, v]) => v !== undefined));
+        return new SignJWT(payload)
+            .setProtectedHeader({ alg: 'RS256' })
+            .setIssuer(opts.issuer)
+            .setIssuedAt()
+            .setExpirationTime(`${ttl}s`)
+            .sign(key);
+    };
+}

package/dist/server/auth/getOnly.d.ts

@@ -0,0 +1,20 @@
+import type { MiddlewareHandler } from 'hono';
+import type { AuthEnv } from './types';
+/**
+ * `getOnly` enforcement — the server-side half of the `/f` GET-only session
+ * guarantee. A getOnly session (the obfuscated `/f` login) may read freely and may
+ * mutate ONLY through the ctgr GET-twins (which are GETs at the transport level);
+ * any raw non-GET/HEAD verb from such a session is rejected with 403.
+ *
+ * Mount GLOBALLY (`app.use('*', getOnlyEnforcement())`) AFTER `createAuthMiddleware`
+ * — it reads the `user` the auth middleware sets and gates purely on the HTTP verb,
+ * so it needs no ctgr path pattern (it must see EVERY mutating request, not only
+ * `/ctgr*`). A non-getOnly session — or an unauthenticated request that never reached
+ * here — passes through untouched.
+ */
+/** Pure predicate: does this principal+method combination violate the GET-only
+ * rule? Exposed for direct unit testing and reuse outside the middleware. */
+export declare function isGetOnlyViolation(user: {
+    getOnly?: boolean;
+}, method: string): boolean;
+export declare function getOnlyEnforcement(): MiddlewareHandler<AuthEnv>;

package/dist/server/auth/getOnly.js

@@ -0,0 +1,27 @@
+import { ApiError, toErrorEnvelope } from '../errors';
+/**
+ * `getOnly` enforcement — the server-side half of the `/f` GET-only session
+ * guarantee. A getOnly session (the obfuscated `/f` login) may read freely and may
+ * mutate ONLY through the ctgr GET-twins (which are GETs at the transport level);
+ * any raw non-GET/HEAD verb from such a session is rejected with 403.
+ *
+ * Mount GLOBALLY (`app.use('*', getOnlyEnforcement())`) AFTER `createAuthMiddleware`
+ * — it reads the `user` the auth middleware sets and gates purely on the HTTP verb,
+ * so it needs no ctgr path pattern (it must see EVERY mutating request, not only
+ * `/ctgr*`). A non-getOnly session — or an unauthenticated request that never reached
+ * here — passes through untouched.
+ */
+/** Pure predicate: does this principal+method combination violate the GET-only
+ * rule? Exposed for direct unit testing and reuse outside the middleware. */
+export function isGetOnlyViolation(user, method) {
+    return user.getOnly === true && method !== 'GET' && method !== 'HEAD';
+}
+export function getOnlyEnforcement() {
+    return async (c, next) => {
+        const user = c.get('user');
+        if (user && isGetOnlyViolation(user, c.req.method)) {
+            return c.json(toErrorEnvelope(new ApiError(403, 'GET-only session')), 403);
+        }
+        return next();
+    };
+}

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

@@ -0,0 +1,12 @@
+export { AUTH_COOKIE_NAME, clearAuthCookie, readAuthCookie, writeAuthCookie, } from './cookie';
+export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type CsrfOptions, createCsrfMiddleware } from './csrf';
+export { createRs256FileTokenSigner, type Rs256FileTokenSignerOptions, } from './fileTokenSigner';
+export { getOnlyEnforcement, isGetOnlyViolation } from './getOnly';
+export { signToken, verifyPurposeToken, verifyToken } from './jwt';
+export { clientKeyOf, clientKeyOfContext, createLoginThrottle, type LoginThrottle, type LoginThrottleOptions, type ThrottleVerdict, } from './loginThrottle';
+export { createAuthMiddleware } from './middleware';
+export { hashPassword, needsRehash, verifyPassword } from './password';
+export { createSessionStore, type SessionStoreOptions, } from './sessionStore';
+export { DEFAULT_TOTP_ISSUER, generateRecoveryCodes, generateTotpSecret, getTotpUri, verifyRecoveryCode, verifyTotpCode, } from './totp';
+export type { AppJwtPayload, AuthEnv, AuthUser, AuthVariables, CreateSessionInput, Session, SessionStore, TokenPurpose, } from './types';
+export { decryptVaultItem, deriveVaultKey, encryptVaultItem } from './vault';

package/dist/server/auth/index.js

@@ -0,0 +1,15 @@
+// cursedbelt server auth toolkit (task 26) — jose JWT, cookies, CSRF, the getOnly
+// gate, a Kysely-backed session store, login throttle, argon2id passwords, TOTP, and
+// Web-Crypto vault item crypto. The *mechanism* lives here; the *model* (roles,
+// sharing, the `/f`-vs-`/login` policy, session semantics) stays in the apps.
+export { AUTH_COOKIE_NAME, clearAuthCookie, readAuthCookie, writeAuthCookie, } from './cookie';
+export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, createCsrfMiddleware } from './csrf';
+export { createRs256FileTokenSigner, } from './fileTokenSigner';
+export { getOnlyEnforcement, isGetOnlyViolation } from './getOnly';
+export { signToken, verifyPurposeToken, verifyToken } from './jwt';
+export { clientKeyOf, clientKeyOfContext, createLoginThrottle, } from './loginThrottle';
+export { createAuthMiddleware } from './middleware';
+export { hashPassword, needsRehash, verifyPassword } from './password';
+export { createSessionStore, } from './sessionStore';
+export { DEFAULT_TOTP_ISSUER, generateRecoveryCodes, generateTotpSecret, getTotpUri, verifyRecoveryCode, verifyTotpCode, } from './totp';
+export { decryptVaultItem, deriveVaultKey, encryptVaultItem } from './vault';