cursedbelt-server 1.0.0

package/src/server/audit/sqliteSink.ts

@@ -0,0 +1,162 @@
+import type { Database } from 'bun:sqlite';
+import type { AuditEntryInput, AuditOperation, AuditRecord } from 'cwip/audit';
+import { runMigrations } from '../migration/runner';
+import { AUDIT_LOG_MIGRATIONS } from './migrations';
+
+interface AuditLogRow {
+  namespace: string;
+  mutation_key: string;
+  target_id: string;
+  version_key: number;
+  operation: AuditOperation;
+  tenant_id: string;
+  changed_by: string | null;
+  changed_at: string;
+  snapshot_data: string | null;
+}
+
+function rowToRecord(row: AuditLogRow): AuditRecord {
+  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: Database) {
+  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: AuditEntryInput): AuditRecord {
+      // 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((): AuditRecord => {
+        const { v: versionKey } = nextVersion.get(entry.tenantId, entry.namespace, entry.targetId) as {
+          v: number;
+        };
+        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: string, namespace: string, targetId: string): AuditRecord[] {
+      const rows = selectTimeline.all(tenantId, namespace, targetId) as AuditLogRow[];
+      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: Database,
+  tenantId: string,
+  namespace: string,
+  targetId: string,
+  at: string,
+): AuditRecord | null {
+  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) as AuditLogRow | null;
+  return row ? rowToRecord(row) : null;
+}
+
+/** Query 2: jump directly to a specific `versionKey`. */
+export function auditStateAtVersion(
+  db: Database,
+  tenantId: string,
+  namespace: string,
+  targetId: string,
+  versionKey: number,
+): AuditRecord | null {
+  const row = db
+    .prepare(
+      'SELECT * FROM audit_log WHERE tenant_id = ? AND namespace = ? AND target_id = ? AND version_key = ?',
+    )
+    .get(tenantId, namespace, targetId, versionKey) as AuditLogRow | null;
+  return row ? rowToRecord(row) : null;
+}
+
+/** Query 3: step one version back/forward from `currentVersion` (for a UI "prev/next" control). */
+export function auditStep(
+  db: Database,
+  tenantId: string,
+  namespace: string,
+  targetId: string,
+  currentVersion: number,
+  direction: 'back' | 'forward',
+): AuditRecord | null {
+  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) as AuditLogRow | null)
+      : (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) as AuditLogRow | null);
+  return row ? rowToRecord(row) : null;
+}

package/src/server/auth/cookie.spec.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { AUTH_COOKIE_NAME, clearAuthCookie, readAuthCookie, writeAuthCookie } from './cookie';
+
+const REQ = (path: string, init?: RequestInit) => new Request(`http://localhost${path}`, init);
+
+describe('auth cookie helpers', () => {
+  test('writeAuthCookie sets an httpOnly, Lax, path=/ cookie with maxAge', async () => {
+    const app = new Hono();
+    app.get('/login', (c) => {
+      writeAuthCookie(c, 'the-jwt', 900);
+      return c.text('ok');
+    });
+    const res = await app.fetch(REQ('/login'));
+    const sc = res.headers.get('set-cookie') ?? '';
+    expect(sc).toContain(`${AUTH_COOKIE_NAME}=the-jwt`);
+    expect(sc).toContain('HttpOnly');
+    expect(sc).toContain('SameSite=Lax');
+    expect(sc).toContain('Path=/');
+    expect(sc).toContain('Max-Age=900');
+  });
+
+  test('readAuthCookie reads the cookie back', async () => {
+    const app = new Hono();
+    app.get('/me', (c) => c.json({ token: readAuthCookie(c) ?? null }));
+    const res = await app.fetch(REQ('/me', { headers: { cookie: `${AUTH_COOKIE_NAME}=abc123` } }));
+    expect(await res.json()).toEqual({ token: 'abc123' });
+  });
+
+  test('readAuthCookie returns undefined when absent', async () => {
+    const app = new Hono();
+    app.get('/me', (c) => c.json({ token: readAuthCookie(c) ?? null }));
+    expect(await (await app.fetch(REQ('/me'))).json()).toEqual({ token: null });
+  });
+
+  test('clearAuthCookie expires the cookie', async () => {
+    const app = new Hono();
+    app.get('/logout', (c) => {
+      clearAuthCookie(c);
+      return c.text('ok');
+    });
+    const sc = (await app.fetch(REQ('/logout'))).headers.get('set-cookie') ?? '';
+    expect(sc).toContain(`${AUTH_COOKIE_NAME}=`);
+    expect(sc).toContain('Max-Age=0');
+  });
+});

package/src/server/auth/cookie.ts

@@ -0,0 +1,42 @@
+import type { Context } from 'hono';
+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 = (): boolean => process.env.NODE_ENV === 'production';
+
+/** Read the httpOnly auth cookie (the access JWT), or undefined. */
+export function readAuthCookie(c: Context): string | undefined {
+  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: Context, token: string, maxAge: number): void {
+  setCookie(c, AUTH_COOKIE_NAME, token, {
+    httpOnly: true,
+    secure: isProd(),
+    sameSite: 'Lax',
+    maxAge,
+    path: '/',
+  });
+}
+
+/** Clear the auth cookie (logout). */
+export function clearAuthCookie(c: Context): void {
+  deleteCookie(c, AUTH_COOKIE_NAME, { path: '/' });
+}

package/src/server/auth/csrf.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, createCsrfMiddleware } from './csrf';
+
+const REQ = (path: string, init?: RequestInit) => new Request(`http://localhost${path}`, init);
+
+const buildApp = () => {
+  const app = new Hono();
+  app.use('*', createCsrfMiddleware());
+  app.get('/notes', (c) => c.json({ ok: true }));
+  app.post('/notes', (c) => c.json({ ok: true })); // non-ctgr mutation (internal/test)
+  app.get('/ctgrpo/notes', (c) => c.json({ ok: true })); // a ctgr GET-twin (mutation)
+  return app;
+};
+
+const csrfTokenFromSetCookie = (res: Response): string => {
+  const sc = res.headers.get('set-cookie') ?? '';
+  const m = sc.match(new RegExp(`${CSRF_COOKIE_NAME}=([^;]+)`));
+  if (!m) throw new Error('no csrf cookie set');
+  return m[1];
+};
+
+describe('createCsrfMiddleware', () => {
+  test('a GET mints the csrf_token cookie (Strict, JS-readable)', async () => {
+    const res = await buildApp().fetch(REQ('/notes'));
+    expect(res.status).toBe(200);
+    const sc = res.headers.get('set-cookie') ?? '';
+    expect(sc).toContain(`${CSRF_COOKIE_NAME}=`);
+    expect(sc).toContain('SameSite=Strict');
+    expect(sc.toLowerCase()).not.toContain('httponly');
+  });
+
+  test('a GET does NOT re-mint when the cookie is already present', async () => {
+    const res = await buildApp().fetch(
+      REQ('/notes', { headers: { cookie: `${CSRF_COOKIE_NAME}=existing` } }),
+    );
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('a ctgr request with no header → 403 envelope', async () => {
+    const res = await buildApp().fetch(
+      REQ('/ctgrpo/notes', { headers: { cookie: `${CSRF_COOKIE_NAME}=abc` } }),
+    );
+    expect(res.status).toBe(403);
+    expect((await res.json()).error.message).toBe('Invalid CSRF token');
+  });
+
+  test('a ctgr request with a mismatched header → 403', async () => {
+    const res = await buildApp().fetch(
+      REQ('/ctgrpo/notes', {
+        headers: { cookie: `${CSRF_COOKIE_NAME}=abc`, [CSRF_HEADER_NAME]: 'xyz' },
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test('a ctgr request with header === cookie passes', async () => {
+    const app = buildApp();
+    const token = csrfTokenFromSetCookie(await app.fetch(REQ('/notes')));
+    const res = await app.fetch(
+      REQ('/ctgrpo/notes', {
+        headers: { cookie: `${CSRF_COOKIE_NAME}=${token}`, [CSRF_HEADER_NAME]: token },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  test('a non-ctgr mutation is NOT CSRF-checked (internal/test traffic)', async () => {
+    const res = await buildApp().fetch(REQ('/notes', { method: 'POST' }));
+    expect(res.status).toBe(200);
+  });
+
+  test('a custom protected prefix is honored', async () => {
+    const app = new Hono();
+    app.use('*', createCsrfMiddleware({ protectedPrefix: '/api/mut' }));
+    app.post('/api/mut/x', (c) => c.json({ ok: true }));
+    const res = await app.fetch(REQ('/api/mut/x', { method: 'POST' }));
+    expect(res.status).toBe(403);
+  });
+});

package/src/server/auth/csrf.ts

@@ -0,0 +1,83 @@
+import type { MiddlewareHandler } from 'hono';
+import { getCookie, setCookie } from 'hono/cookie';
+import { ApiError, toErrorEnvelope } from '../errors';
+
+/**
+ * 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 const CSRF_COOKIE_NAME = 'csrf_token';
+export const CSRF_HEADER_NAME = 'x-csrf-token';
+
+const isProd = (): boolean => process.env.NODE_ENV === 'production';
+
+export function createCsrfMiddleware(opts: CsrfOptions = {}): MiddlewareHandler {
+  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/src/server/auth/fileTokenSigner.ts

@@ -0,0 +1,40 @@
+import { importPKCS8, SignJWT } from 'jose';
+import type { FileTokenClaims, FileTokenSigner } from '../storage/binaryServerStore';
+
+// RS256 file-token signer for binary-server tenants. binary-server holds only the tenant's
+// PUBLIC key (resolved by the token's `iss` claim) and can verify but never mint; the app holds
+// the private key and signs short-lived per-file tokens with it. This helper is mechanism only —
+// key material and issuer identity stay the app's configuration (env), never cursedbelt's.
+
+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 function createRs256FileTokenSigner(opts: Rs256FileTokenSignerOptions): FileTokenSigner {
+  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: ReturnType<typeof importPKCS8> | null = null;
+  return async (claims: FileTokenClaims): Promise<string> => {
+    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/src/server/auth/getOnly.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { getOnlyEnforcement, isGetOnlyViolation } from './getOnly';
+import type { AuthEnv, AuthUser } from './types';
+
+const REQ = (path: string, init?: RequestInit) => new Request(`http://localhost${path}`, init);
+
+describe('isGetOnlyViolation', () => {
+  test('blocks non-GET only for getOnly sessions', () => {
+    expect(isGetOnlyViolation({ getOnly: true }, 'POST')).toBe(true);
+    expect(isGetOnlyViolation({ getOnly: true }, 'DELETE')).toBe(true);
+    expect(isGetOnlyViolation({ getOnly: true }, 'GET')).toBe(false);
+    expect(isGetOnlyViolation({ getOnly: true }, 'HEAD')).toBe(false);
+    expect(isGetOnlyViolation({ getOnly: false }, 'POST')).toBe(false);
+    expect(isGetOnlyViolation({}, 'DELETE')).toBe(false);
+  });
+});
+
+const appWith = (user: AuthUser) => {
+  const app = new Hono<AuthEnv>();
+  app.use('*', async (c, next) => {
+    c.set('user', user);
+    await next();
+  });
+  app.use('*', getOnlyEnforcement());
+  app.get('/notes', (c) => c.json({ ok: true }));
+  app.post('/notes', (c) => c.json({ ok: true }));
+  app.get('/ctgrpo/notes', (c) => c.json({ ok: true })); // ctgr mutation rides a GET
+  return app;
+};
+
+describe('getOnlyEnforcement middleware', () => {
+  const getOnlyUser: AuthUser = { id: 'u1', roles: [], getOnly: true, sessionId: 's1' };
+  const normalUser: AuthUser = { id: 'u2', roles: [], getOnly: false, sessionId: 's2' };
+
+  test('getOnly session: GET passes', async () => {
+    expect((await appWith(getOnlyUser).fetch(REQ('/notes'))).status).toBe(200);
+  });
+
+  test('getOnly session: raw POST → 403 envelope', async () => {
+    const res = await appWith(getOnlyUser).fetch(REQ('/notes', { method: 'POST' }));
+    expect(res.status).toBe(403);
+    expect((await res.json()).error.message).toBe('GET-only session');
+  });
+
+  test('getOnly session: a ctgr GET-twin (transport GET) passes', async () => {
+    expect((await appWith(getOnlyUser).fetch(REQ('/ctgrpo/notes'))).status).toBe(200);
+  });
+
+  test('normal session: POST passes', async () => {
+    expect((await appWith(normalUser).fetch(REQ('/notes', { method: 'POST' }))).status).toBe(200);
+  });
+});

package/src/server/auth/getOnly.ts

@@ -0,0 +1,32 @@
+import type { MiddlewareHandler } from 'hono';
+import { ApiError, toErrorEnvelope } from '../errors';
+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 function isGetOnlyViolation(user: { getOnly?: boolean }, method: string): boolean {
+  return user.getOnly === true && method !== 'GET' && method !== 'HEAD';
+}
+
+export function getOnlyEnforcement(): MiddlewareHandler<AuthEnv> {
+  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/src/server/auth/index.ts

@@ -0,0 +1,51 @@
+// 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, 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';