cursedbelt 2.8.0 → 3.0.0

package/src/server/auth/totp.ts

@@ -1,92 +0,0 @@
-import { generateSecret, generateURI, verifySync } from 'otplib';
-
-/**
- * TOTP (RFC 6238) on `otplib` — standard authenticator-app parameters (base32
- * secret, SHA-1, 6 digits, 30s step). otplib's default plugins are pure-JS
- * (`@noble/hashes` + `@scure/base`), so this runs natively on Bun with no native
- * deps. Plus single-use recovery codes hashed with argon2id (never stored plain).
- *
- * The toolkit provides the crypto; enabling/disabling 2FA, persisting the secret +
- * recovery hashes, and the login-flow ordering stay app-business (task 32).
- */
-
-export const DEFAULT_TOTP_ISSUER = 'CursedAlchemy';
-
-// One 30s step of clock-skew tolerance on each side (±1 step). otplib v13 defaults
-// to ZERO tolerance, so we set it explicitly (period = 30s).
-const DRIFT_SECONDS = 30;
-
-/** A fresh random base32 TOTP secret (20 bytes / 160 bits — the standard). */
-export function generateTotpSecret(): string {
-  return generateSecret();
-}
-
-/** The `otpauth://` URI an authenticator app scans / imports (for QR rendering). */
-export function getTotpUri(account: string, secret: string, issuer = DEFAULT_TOTP_ISSUER): string {
-  return generateURI({ issuer, label: account, secret });
-}
-
-/**
- * Verify a user-entered 6-digit code against a base32 secret, allowing ±1 step of
- * drift. Tolerates surrounding whitespace; rejects anything that isn't six digits.
- */
-export function verifyTotpCode(token: string, secret: string): boolean {
-  const clean = String(token).replace(/\s+/g, '');
-  if (!/^\d{6}$/.test(clean)) return false;
-  try {
-    return verifySync({ secret, token: clean, epochTolerance: DRIFT_SECONDS }).valid;
-  } catch {
-    return false;
-  }
-}
-
-// ── Recovery codes ──────────────────────────────────────────────────────────────
-
-// No easily-confused characters (no 0/O, 1/I/L) — readable + dictatable.
-const CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
-
-/** Strip separators + uppercase, so display formatting never affects matching. */
-const normalizeCode = (code: string): string =>
-  String(code)
-    .replace(/[^a-zA-Z0-9]/g, '')
-    .toUpperCase();
-
-const randomCode = (): string => {
-  const bytes = crypto.getRandomValues(new Uint8Array(10));
-  let s = '';
-  for (const b of bytes) s += CODE_ALPHABET[b % CODE_ALPHABET.length];
-  return `${s.slice(0, 5)}-${s.slice(5)}`; // e.g. "A1B2C-D3E4F"
-};
-
-/**
- * Generate `count` single-use recovery codes. Returns `plaintext` (shown to the user
- * exactly once) and `hashed` (argon2id PHC strings — persist these as a JSON array,
- * never the plaintext).
- */
-export async function generateRecoveryCodes(
-  count = 10,
-): Promise<{ plaintext: string[]; hashed: string[] }> {
-  const plaintext = Array.from({ length: count }, randomCode);
-  const hashed = await Promise.all(
-    plaintext.map((code) => Bun.password.hash(normalizeCode(code), { algorithm: 'argon2id' })),
-  );
-  return { plaintext, hashed };
-}
-
-/**
- * Verify a candidate recovery code against the stored argon2id hashes. Returns the
- * index of the matching hash, or -1 if none match. The caller consumes it (splice
- * that index out and persist the shortened array) so each code works exactly once.
- */
-export async function verifyRecoveryCode(input: string, hashed: string[]): Promise<number> {
-  const candidate = normalizeCode(input);
-  if (!candidate) return -1;
-  for (let i = 0; i < hashed.length; i++) {
-    try {
-      if (await Bun.password.verify(candidate, hashed[i])) return i;
-    } catch {
-      // ignore a malformed stored hash — treat as a non-match
-    }
-  }
-  return -1;
-}

package/src/server/auth/types.ts

@@ -1,146 +0,0 @@
-import type { JWTPayload } from 'jose';
-import type { CursedbeltVariables } from '../context';
-
-/**
- * Shared auth types for the cursedbelt server auth toolkit.
- *
- * cursedbelt owns the *mechanism* (sign/verify, session validity, the getOnly
- * gate, CSRF, throttling, TOTP, vault crypto). The *model* — which roles may do
- * what, the `/f`-vs-`/login` policy, what a "session" means to the product — stays
- * in the consuming app. The toolkit carries `roles`/`getOnly`/`purpose` opaquely
- * and never interprets them beyond the documented gates.
- */
-
-/** Token purposes the apps mint. `access` is the login session; the rest are
- * short-lived single-feature unlock/state tokens (held in page memory, never a
- * cookie). cursedbelt does not enforce these — {@link AppJwtPayload.purpose} is an
- * opaque string the app sets and checks (via `verifyPurposeToken`). */
-export type TokenPurpose =
-  | 'access'
-  | 'refresh'
-  | 'vault-unlock'
-  | 'pm-unlock'
-  | 'files-unlock'
-  | 'yt-oauth';
-
-/**
- * The decoded JWT payload shape the apps use. `userId`/`sessionId` tie a token to
- * its user + its row in the session store (the kill switch); `roles` + `getOnly`
- * ride along for the auth middleware to surface on `c.get('user')`.
- */
-export interface AppJwtPayload extends JWTPayload {
-  userId: string;
-  sessionId: string;
-  roles: string[];
-  /** GET-only (`/f`) session marker. Absent on tokens minted before the claim
-   * existed → treated as `false` (see {@link AuthUser.getOnly}). */
-  getOnly?: boolean;
-  /** See {@link TokenPurpose}. Absent ⇒ a plain access token. */
-  purpose?: TokenPurpose | (string & {});
-}
-
-/**
- * The authenticated principal the auth middleware sets on `c.get('user')`. This is
- * the *normalized* view (getOnly defaulted), distinct from the raw {@link AppJwtPayload}.
- */
-export interface AuthUser {
-  id: string;
-  roles: string[];
-  /** Normalized: a missing `getOnly` claim becomes `false` here. */
-  getOnly: boolean;
-  sessionId: string;
-}
-
-/** Hono `Variables` the auth middleware contributes. Composed with the base
- * {@link CursedbeltVariables} into {@link AuthEnv}. */
-export interface AuthVariables {
-  /** Set by `createAuthMiddleware` once the token + session are validated. */
-  user: AuthUser;
-}
-
-/** The Hono env an app gets once it mounts the cursedbelt auth middleware: the
- * base plumbing variables plus the authenticated `user`. `user` is typed required
- * because the gate runs before any handler that reads it; mount auth before the
- * routes that depend on it. */
-export interface AuthEnv {
-  Variables: CursedbeltVariables & AuthVariables;
-}
-
-/** A persisted login session — the in-memory + DB-backed record the auth middleware
- * checks on every request (revocation + sliding-refresh expiry). */
-export interface Session {
-  sessionId: string;
-  userId: string;
-  /** GET-only (`/f`) session. Copied onto the access token's `getOnly` claim. */
-  getOnly: boolean;
-  createdAt: string;
-  lastSeenAt: string;
-  /** Sliding deadline: a session is valid while now < refreshExpiresAt. */
-  refreshExpiresAt: string;
-  /** When the *current* access token expires (informational; the cookie/JWT is the
-   * real gate). Null until first issued. */
-  accessExpiresAt: string | null;
-  disabled: boolean;
-  disabledAt: string | null;
-  disabledBy: string | null;
-  userAgent: string | null;
-  ip: string | null;
-}
-
-/** Inputs to mint a session. The store computes `createdAt`/`lastSeenAt` and (unless
- * overridden) `refreshExpiresAt` from its configured window — callers never hand-roll
- * timestamps. */
-export interface CreateSessionInput {
-  sessionId: string;
-  userId: string;
-  getOnly?: boolean;
-  accessExpiresAt?: string | null;
-  userAgent?: string | null;
-  ip?: string | null;
-  /** Override the computed `now + refreshWindowMs` deadline. */
-  refreshExpiresAt?: string;
-}
-
-/**
- * Revocable, restart-surviving session store. The in-memory map is the hot-path
- * source of truth for token validity (no per-request DB read); the `auth_sessions`
- * table exists so the map can be rebuilt after a restart ({@link SessionStore.rehydrate}).
- * Single-server deployment — no cross-instance coherence to manage.
- */
-export interface SessionStore {
-  /** Load the table into memory on boot (prunes expired/old rows first). */
-  rehydrate(): Promise<void>;
-  /** Persist + cache a new session. */
-  create(input: CreateSessionInput): Promise<Session>;
-  /** Sync hot-path read from memory. Returns the LIVE cached object (not a copy) —
-   * treat it read-only; mutate only through the store's methods. */
-  get(sessionId: string): Session | undefined;
-  /** Is this session usable right now (present, not disabled, inside its window)? */
-  isValid(session: Session | undefined): session is Session;
-  /** Slide the refresh deadline forward on activity (and optionally record a freshly
-   * issued access-token expiry). DB write is throttled unless `accessExpiresAt` is
-   * passed (a re-issue must persist immediately so a restart reflects it). */
-  touch(sessionId: string, opts?: { accessExpiresAt?: string | null }): Promise<void>;
-  /** Revoke one session (keeps the audit row). Returns false if unknown. */
-  disable(sessionId: string, disabledBy?: string | null): Promise<boolean>;
-  /** Revoke every active session for a user; returns the affected ids (e.g. to drop
-   * matching live websockets). */
-  disableAllForUser(userId: string, disabledBy?: string | null): Promise<string[]>;
-  /** Forget a single session entirely (logout — drops the audit row too). */
-  remove(sessionId: string): Promise<void>;
-  /** Hard-delete every session for a user (memory + DB). */
-  deleteByUser(userId: string): Promise<void>;
-  /** All sessions for a user (incl. disabled audit rows), newest first — for an
-   * account/admin "your devices" view. */
-  listByUser(userId: string): Promise<Session[]>;
-  /** All cached sessions (sync; admin live list). */
-  listAll(): Session[];
-  /** Most-recent activity across a user's active sessions, or null — a cheap presence
-   * signal. */
-  getLastSeenForUser(userId: string): string | null;
-  /** Drop sessions whose last activity predates the retention window (memory + DB).
-   * Returns the count removed. */
-  prune(): Promise<number>;
-  /** Stop the optional auto-prune timer (no-op if none was started). */
-  stop(): void;
-}

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

@@ -1,51 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { decryptVaultItem, deriveVaultKey, encryptVaultItem } from './vault';
-
-const SECRET = 'server-secret-used-for-vault-key-derivation';
-
-describe('vault item crypto (AES-256-GCM + HKDF)', () => {
-  test('encrypt → decrypt roundtrips the plaintext', async () => {
-    const key = await deriveVaultKey(SECRET, 'user-1');
-    const plaintext = 'sꜱh key: hunter2 🔐 — multi-byte ✓';
-    const envelope = await encryptVaultItem(key, plaintext);
-    expect(await decryptVaultItem(key, envelope)).toBe(plaintext);
-  });
-
-  test('each encryption uses a fresh IV (ciphertext differs)', async () => {
-    const key = await deriveVaultKey(SECRET, 'user-1');
-    const a = await encryptVaultItem(key, 'same');
-    const b = await encryptVaultItem(key, 'same');
-    expect(a).not.toBe(b);
-    expect(await decryptVaultItem(key, a)).toBe('same');
-    expect(await decryptVaultItem(key, b)).toBe('same');
-  });
-
-  test('the envelope starts with the version byte (1)', async () => {
-    const key = await deriveVaultKey(SECRET, 'user-1');
-    const envelope = await encryptVaultItem(key, 'x');
-    expect(new Uint8Array(Buffer.from(envelope, 'base64'))[0]).toBe(1);
-  });
-
-  test('a different user derives a different key — cross-user decrypt fails', async () => {
-    const k1 = await deriveVaultKey(SECRET, 'user-1');
-    const k2 = await deriveVaultKey(SECRET, 'user-2');
-    const envelope = await encryptVaultItem(k1, 'secret');
-    await expect(decryptVaultItem(k2, envelope)).rejects.toThrow();
-  });
-
-  test('a tampered envelope fails the GCM auth check', async () => {
-    const key = await deriveVaultKey(SECRET, 'user-1');
-    const bytes = new Uint8Array(Buffer.from(await encryptVaultItem(key, 'secret'), 'base64'));
-    bytes[bytes.length - 1] ^= 0xff; // flip a ciphertext bit
-    await expect(decryptVaultItem(key, Buffer.from(bytes).toString('base64'))).rejects.toThrow();
-  });
-
-  test('rejects an unknown version byte', async () => {
-    const key = await deriveVaultKey(SECRET, 'user-1');
-    const bytes = new Uint8Array(Buffer.from(await encryptVaultItem(key, 'secret'), 'base64'));
-    bytes[0] = 2;
-    await expect(decryptVaultItem(key, Buffer.from(bytes).toString('base64'))).rejects.toThrow(
-      /version/,
-    );
-  });
-});

package/src/server/auth/vault.ts

@@ -1,71 +0,0 @@
-/**
- * Vault item at-rest crypto — standard Web Crypto (HKDF-SHA256 + AES-256-GCM),
- * replacing the old hand-rolled `secretBox`/`deriveKey` scheme. Auditable, native on
- * modern Bun, zero dependencies. These primitives live in cursedbelt (not ca's
- * business layer) because ru gains a vault too.
- *
- * Keying is SERVER-SECRET–derived (per user), NOT master-password–derived: the
- * master password is a separate argon2id gate (a `Bun.password` hash — see
- * {@link ./password}), so resetting it never requires re-encrypting vault data. The
- * envelope carries a version byte so a future re-key can proceed row-by-row without
- * a flag-day migration.
- */
-
-const VERSION = 1;
-const IV_BYTES = 12; // 96-bit nonce — the AES-GCM standard
-const enc = new TextEncoder();
-const dec = new TextDecoder();
-
-/**
- * Derive a per-user AES-256-GCM vault key from the server secret via HKDF. The
- * per-user `salt` domain-separates users; `info` domain-separates this use of the
- * secret. The returned key is non-extractable (encrypt/decrypt only).
- */
-export async function deriveVaultKey(serverSecret: string, userId: string): Promise<CryptoKey> {
-  const baseKey = await crypto.subtle.importKey(
-    'raw',
-    enc.encode(serverSecret),
-    { name: 'HKDF' },
-    false,
-    ['deriveKey'],
-  );
-  return crypto.subtle.deriveKey(
-    {
-      name: 'HKDF',
-      hash: 'SHA-256',
-      salt: enc.encode(`vault:${userId}`),
-      info: enc.encode('vault-item-key'),
-    },
-    baseKey,
-    { name: 'AES-GCM', length: 256 },
-    false,
-    ['encrypt', 'decrypt'],
-  );
-}
-
-/**
- * Encrypt vault item plaintext. Returns a base64 envelope:
- *   `version(1B) || iv(12B) || ciphertext(+GCM tag)`
- * A fresh random IV per call. Store the string verbatim in `vault_items.data`.
- */
-export async function encryptVaultItem(key: CryptoKey, plaintext: string): Promise<string> {
-  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
-  const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, enc.encode(plaintext));
-  const envelope = new Uint8Array(1 + IV_BYTES + ct.byteLength);
-  envelope[0] = VERSION;
-  envelope.set(iv, 1);
-  envelope.set(new Uint8Array(ct), 1 + IV_BYTES);
-  return Buffer.from(envelope).toString('base64');
-}
-
-/** Decrypt an envelope produced by {@link encryptVaultItem}. Throws on an unknown
- * version, a truncated envelope, or a failed GCM auth (tamper/wrong key). */
-export async function decryptVaultItem(key: CryptoKey, envelope: string): Promise<string> {
-  const bytes = new Uint8Array(Buffer.from(envelope, 'base64'));
-  if (bytes.length < 1 + IV_BYTES + 16) throw new Error('vault: envelope too short');
-  if (bytes[0] !== VERSION) throw new Error(`vault: unsupported envelope version ${bytes[0]}`);
-  const iv = bytes.subarray(1, 1 + IV_BYTES);
-  const ct = bytes.subarray(1 + IV_BYTES);
-  const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ct);
-  return dec.decode(plain);
-}

package/src/server/context.ts

@@ -1,37 +0,0 @@
-import type { CtgrDecoded, CtgrMethod } from '../ctgr/types';
-
-/**
- * The cursedbelt Hono environment. `createApp()` returns a `Hono<CursedbeltEnv>`
- * so every middleware and handler shares one typed `c.get`/`c.set` surface.
- *
- * Only *plumbing* variables live here — request identity that the cross-cutting
- * middleware owns. Business variables (roles, session, sharing) are added by the
- * app's own auth/feature middleware via its own env extension (task 26+).
- */
-export interface CursedbeltVariables {
-  /** Per-request correlation id. Set by {@link correlationId} on every request. */
-  correlationId: string;
-  /**
-   * Authenticated user id. cursedbelt never sets this — the app's auth middleware
-   * (task 26) populates it so the request logger can attribute metrics/events to a
-   * user. Optional because anonymous requests have none.
-   */
-  userId?: string;
-  /**
-   * The decoded original request on a `/ctgr*` GET twin. Set by the ctgr `unGETify`
-   * middleware; the downstream handler / zod validator reads the body from here.
-   */
-  ctgrDecoded?: CtgrDecoded;
-  /** The decoded original HTTP method of a ctgr-tunneled request. */
-  ctgrMethod?: CtgrMethod;
-  /**
-   * The parsed/coerced/stripped body a `zValidator(...)` route accepted. A convenience
-   * mirror of the typed `c.req.valid('json')` slot for handlers that prefer a getter.
-   * Set only on a validated route; `unknown` because the type is the route's schema.
-   */
-  validatedBody?: unknown;
-}
-
-export interface CursedbeltEnv {
-  Variables: CursedbeltVariables;
-}

package/src/server/ctgr.spec.ts

@@ -1,138 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { Hono } from 'hono';
-import { toBase64 } from '../ctgr/base64url';
-import { ChunkStore } from '../ctgr/chunkStore';
-import { encodeRequest } from '../ctgr/codec';
-import type { CursedbeltEnv } from './context';
-import { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr';
-
-const ORIGIN = 'http://localhost';
-const fetchChunk = (app: Hono<CursedbeltEnv>, url: string, init?: RequestInit) =>
-  app.fetch(new Request(ORIGIN + url, init));
-
-// Mirror the legacy client encoder so we can exercise the v0 fallback path.
-const encodeV0 = (jsonString: string): string => {
-  const encode = (s: string) => toBase64(new TextEncoder().encode(s));
-  const reverse = (s: string) => s.split('').reverse().join('');
-  const swap = (s: string) => {
-    if (s.length < 2) return s;
-    const arr = s.split('');
-    arr[0] = s[s.length - 1];
-    arr[s.length - 1] = s[0];
-    return arr.join('');
-  };
-  return swap(encode(swap(reverse(encode(jsonString)))));
-};
-
-function makeApp() {
-  const app = new Hono<CursedbeltEnv>();
-  const store = new ChunkStore();
-  app.use(CTGR_ROUTE_PATTERN, unGETify(store));
-
-  const register = buildRoutes(app);
-  // An echo handler shared by the real verb route AND its GET twin: it reads the
-  // body from the ctgr-decoded context when tunneled, else from the request.
-  register('post', '/notes', async (c) => {
-    const decoded = getCtgrDecoded(c);
-    const body = decoded ? decoded.body : await c.req.json();
-    return c.json({ ok: true, rawMethod: c.req.method, decodedMethod: decoded?.method, body });
-  });
-  register('delete', '/notes/:id', (c) => {
-    const decoded = getCtgrDecoded(c);
-    return c.json({
-      ok: true,
-      id: c.req.param('id'),
-      method: decoded?.method,
-      body: decoded?.body,
-    });
-  });
-
-  // Binary download stays a PLAIN GET — never registered via buildRoutes, so no
-  // `/ctgrde/...` twin exists to mangle its bytes through base64url.
-  app.get('/files/:id/download', (c) => c.text(`binary:${c.req.param('id')}`));
-
-  return app;
-}
-
-describe('unGETify + buildRoutes (Hono integration)', () => {
-  test('a single-chunk POST twin runs the handler with the decoded body', async () => {
-    const app = makeApp();
-    const enc = await encodeRequest('POST', '/notes', { body: 'hi' });
-    const res = await fetchChunk(app, enc.chunks[0].url);
-    expect(res.status).toBe(200);
-    expect(await res.json()).toEqual({
-      ok: true,
-      rawMethod: 'GET', // the transport is a GET — what the getOnly 403 keys off
-      decodedMethod: 'POST', // the decoded intent — what the handler/validator sees
-      body: { body: 'hi' },
-    });
-  });
-
-  test('the real verb route still works (no tunnel)', async () => {
-    const app = makeApp();
-    const res = await app.fetch(
-      new Request(`${ORIGIN}/notes`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ body: 'direct' }),
-      }),
-    );
-    expect(res.status).toBe(200);
-    const json = (await res.json()) as { rawMethod: string; body: unknown };
-    expect(json.rawMethod).toBe('POST');
-    expect(json.body).toEqual({ body: 'direct' });
-  });
-
-  test('a multi-chunk payload: intermediate chunks 202, the last drives the handler', async () => {
-    const app = makeApp();
-    // gzip disabled so the payload genuinely spans multiple chunks/requests.
-    const big = { body: 'q'.repeat(5000) };
-    const enc = await encodeRequest('POST', '/notes', big, {
-      chunkSizeBytes: 400,
-      gzipThresholdBytes: 10_000_000,
-    });
-    expect(enc.chunks.length).toBeGreaterThan(1);
-    for (const chunk of enc.chunks.slice(0, -1)) {
-      const res = await fetchChunk(app, chunk.url);
-      expect(res.status).toBe(202);
-    }
-    const final = await fetchChunk(app, enc.chunks.at(-1)!.url);
-    expect(final.status).toBe(200);
-    expect((await final.json()).body).toEqual(big);
-  });
-
-  test('a body-less DELETE twin decodes to a null body', async () => {
-    const app = makeApp();
-    const enc = await encodeRequest('DELETE', '/notes/7', undefined);
-    const res = await fetchChunk(app, enc.chunks[0].url);
-    expect(res.status).toBe(200);
-    expect(await res.json()).toMatchObject({ ok: true, id: '7', method: 'DELETE', body: null });
-  });
-
-  test('a legacy v0 request (no _cv) decodes via the compat path', async () => {
-    const app = makeApp();
-    const p = encodeV0(JSON.stringify({ body: 'legacy' }));
-    const res = await fetchChunk(app, `/ctgrpo/notes?p=${encodeURIComponent(p)}`);
-    expect(res.status).toBe(200);
-    expect((await res.json()).body).toEqual({ body: 'legacy' });
-  });
-
-  test('a corrupt tunneled payload returns a 400 error envelope', async () => {
-    const app = makeApp();
-    const enc = await encodeRequest('POST', '/notes', { body: 'hi' });
-    const tampered = enc.chunks[0].url.replace(/_sha=[0-9a-f]+/, '_sha=deadbeef');
-    const res = await fetchChunk(app, tampered);
-    expect(res.status).toBe(400);
-    expect((await res.json()).error.message).toMatch(/sha256/);
-  });
-
-  test('binary downloads stay a plain GET with NO ctgr twin', async () => {
-    const app = makeApp();
-    const direct = await fetchChunk(app, '/files/42/download');
-    expect(direct.status).toBe(200);
-    expect(await direct.text()).toBe('binary:42');
-    // No `/ctgrde/files/:id/download` route was registered → 404.
-    const twin = await fetchChunk(app, '/ctgrde/files/42/download');
-    expect(twin.status).toBe(404);
-  });
-});

package/src/server/ctgr.ts

@@ -1,108 +0,0 @@
-/*
- * ctgr Hono transport — the server half of the GET-tunnel: the `unGETify` middleware
- * that decodes a `/ctgr<XX>` twin's query params back into the original request, and
- * the `buildRoutes` registrar that wires the real verb route and its GET twin from one
- * call. The codec re-exports from `cursedbelt/server`; the browser side is `cursedbelt/client`.
- *
- * Protection is unchanged and lives elsewhere by design: the getOnly-claim 403 keys
- * off the RAW request method (always GET on a twin) in the auth middleware, and the
- * CSRF double-submit guard fires on every `/ctgr*` path. unGETify ONLY decodes.
- */
-import type { Context, Hono, MiddlewareHandler } from 'hono';
-import type { H } from 'hono/types';
-import type { ChunkStore } from '../ctgr/chunkStore';
-import {
-  ABBREV_TO_METHOD,
-  type CtgrAbbrev,
-  type CtgrDecoded,
-  type CtgrMethod,
-  METHOD_TO_ABBREV,
-} from '../ctgr/types';
-import { V0ChunkStore } from '../ctgr/v0compat';
-import type { CursedbeltEnv } from './context';
-import { ApiError, toErrorEnvelope } from './errors';
-
-/**
- * The path pattern that matches EVERY ctgr GET twin (`/ctgr<XX>...`) and nothing
- * else — mount the decode + CSRF + getOnly middleware on this. NOTE: Hono's router
- * does not treat `/ctgr*` as a prefix wildcard (a bare-suffix `*` only matches a
- * single following segment), so a named param with a `ctgr.+` regex is the correct,
- * portable matcher (`.` spans `/`, so it covers multi-segment paths like
- * `/ctgrpa/api/v1/lists/123`). Reuse this everywhere a `/ctgr*` mount is meant.
- */
-export const CTGR_ROUTE_PATTERN = '/:ctgrTwin{ctgr.+}';
-
-/**
- * Mount on {@link CTGR_ROUTE_PATTERN} (before the twin routes). A single chunk decodes
- * inline; a multi-chunk payload accumulates in the injected {@link ChunkStore}
- * (intermediate chunk → 202). The decoded request + method are stashed on the context for the
- * downstream handler / validator (`c.get('ctgrDecoded')`). Legacy `_cv`-absent
- * requests fall back to the v0 decoder for the rollout window.
- */
-export function unGETify(store: ChunkStore): MiddlewareHandler<CursedbeltEnv> {
-  const legacy = new V0ChunkStore();
-  return async (c, next) => {
-    const params = Object.fromEntries(new URL(c.req.url).searchParams);
-    const pathMethod = ABBREV_TO_METHOD[c.req.path.slice(5, 7) as CtgrAbbrev];
-    if (!pathMethod) {
-      return c.json(toErrorEnvelope(new ApiError(400, 'ctgr: unknown method twin', { code: 'unknown_method' })), 400);
-    }
-
-    const result =
-      params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
-
-    if (result === false) return c.json({ acknowledged: true }, 202);
-    if (result instanceof Error)
-      return c.json(toErrorEnvelope(new ApiError(400, result.message, { code: 'ctgr_decode_failed' })), 400);
-
-    c.set('ctgrDecoded', result);
-    c.set('ctgrMethod', result.method);
-    await next();
-  };
-}
-
-/** Read the ctgr-decoded request a `/ctgr*` twin stashed, if this was a tunneled call. */
-export function getCtgrDecoded(c: Context<CursedbeltEnv>): CtgrDecoded | undefined {
-  return c.get('ctgrDecoded');
-}
-
-/** The internal dispatch shape of `app.on` — Hono's overload soup can't resolve a
- *  runtime-length handler spread, so we assert the (method, path, ...handlers) shape
- *  it accepts at runtime while keeping the public {@link buildRoutes} API type-safe. */
-type RouteDispatch = (
-  method: string,
-  path: string,
-  ...handlers: MiddlewareHandler<CursedbeltEnv>[]
-) => unknown;
-
-/**
- * Twin registrar: one call registers the real verb route AND its `/ctgr<XX>` GET twin
- * (same handlers; the global `/ctgr*` {@link unGETify} middleware decodes the body
- * first). Binary/download routes MUST NOT go through this — register those as a plain
- * `app.get(path, handler)` so their bytes never ride the base64url tunnel and get
- * mangled.
- */
-export function buildRoutes(app: Hono<CursedbeltEnv>) {
-  const on = app.on.bind(app) as RouteDispatch;
-  return function register(
-    method: CtgrMethod | Lowercase<CtgrMethod>,
-    path: string,
-    /*
-     * `H`, not `MiddlewareHandler`. These are ROUTE handlers: Hono's
-     * `MiddlewareHandler` must return `Promise<Response | void>`, so declaring it
-     * here forced every caller to be `async` for no reason — a plain
-     * `(c) => c.json(…)` did not typecheck against a registrar whose whole job is
-     * registering exactly that. `H` is Hono's own union of both kinds and is what
-     * `app.on` accepts.
-     */
-    ...handlers: H<CursedbeltEnv>[]
-  ): void {
-    const upper = method.toUpperCase() as CtgrMethod;
-    const abbrev = METHOD_TO_ABBREV[upper];
-    if (!abbrev) throw new Error(`buildRoutes: "${method}" is not a ctgr-tunnelable method`);
-
-    // The real verb route + its GET twin, from one call.
-    on(upper, path, ...handlers);
-    on('GET', `/ctgr${abbrev}${path}`, ...handlers);
-  };
-}