cursedbelt 2.7.0 → 3.0.0

package/src/ctgr/v0compat.ts

@@ -1,156 +0,0 @@
-/*
- * Legacy (v0) ctgr decoder — kept ONLY for the rollout window so a server running v1
- * still understands requests from not-yet-updated clients (which send no `_cv`). The
- * v0 codec was `encode→reverse→swap→base64→swap`: a trivially reversible transform,
- * never a security mechanism (the real protection is the getOnly JWT claim + the CSRF
- * guard, both unchanged). Delete this file once all clients ship v1.
- *
- * Detect v0 by the ABSENCE of `_cv` (the old client never sent it) — the safest
- * heuristic, since v1 always sets `_cv=1`. v0 carried the method only in the path
- * (`/ctgr<XX>`), so the middleware passes the path-derived method in.
- */
-import { fromBase64 } from './base64url';
-import { extractFiles } from './codec';
-import type { CtgrDecoded, CtgrMethod } from './types';
-
-const decodeBase64Utf8 = (str: string): string => new TextDecoder().decode(fromBase64(str));
-const reverseString = (str: string): string => str.split('').reverse().join('');
-const swapEnds = (str: string): string => {
-  if (str.length < 2) return str;
-  const arr = str.split('');
-  arr[0] = str[str.length - 1];
-  arr[str.length - 1] = str[0];
-  return arr.join('');
-};
-
-/** Reverse the v0 client pipeline (`encode→reverse→swap→encode→swap`) and parse JSON. */
-export function decodeV0Payload(encoded: string): unknown {
-  const json = decodeBase64Utf8(reverseString(swapEnds(decodeBase64Utf8(swapEnds(encoded)))));
-  let body = JSON.parse(json);
-  // The legacy client occasionally double-encoded the body string; unwrap it.
-  if (typeof body === 'string') body = JSON.parse(body);
-  return body;
-}
-
-function toDecoded(body: unknown, method: CtgrMethod): CtgrDecoded {
-  const { body: rest, files } = extractFiles(body);
-  return files ? { method, body: rest, files } : { method, body: rest };
-}
-
-export interface V0ChunkStoreOpts {
-  maxInFlight?: number;
-  /** Hard cap on the joined encoded string length (chars). Default ~80 MB. */
-  maxPayloadChars?: number;
-  ttlMs?: number;
-  now?: () => number;
-}
-
-interface V0Entry {
-  parts: (string | undefined)[];
-  total: number;
-  received: number;
-  chars: number;
-  method: CtgrMethod;
-  updatedAt: number;
-}
-
-/**
- * Bounded accumulator for v0 requests, mirroring the legacy `unGETifyRoute` (`p` for
- * a single payload; `cid`/`ci`/`ct`/`p` for chunked). Same `add` contract as the v1
- * {@link ChunkStore}: `false` for an intermediate chunk, {@link CtgrDecoded} when
- * complete, `Error` on malformed input.
- */
-export class V0ChunkStore {
-  private readonly entries = new Map<string, V0Entry>();
-  private readonly maxInFlight: number;
-  private readonly maxPayloadChars: number;
-  private readonly ttlMs: number;
-  private readonly now: () => number;
-
-  constructor(opts: V0ChunkStoreOpts = {}) {
-    this.maxInFlight = opts.maxInFlight ?? 200;
-    this.maxPayloadChars = opts.maxPayloadChars ?? 80 * 1024 * 1024;
-    this.ttlMs = opts.ttlMs ?? 2 * 60 * 1000;
-    this.now = opts.now ?? Date.now;
-  }
-
-  get size(): number {
-    return this.entries.size;
-  }
-
-  add(params: Record<string, string>, method: CtgrMethod): CtgrDecoded | false | Error {
-    this.evictStale();
-
-    // Single payload (or a body-less converted request: no `p`).
-    if (params.cid === undefined) {
-      if (!params.p) return { method, body: undefined };
-      try {
-        return toDecoded(decodeV0Payload(params.p), method);
-      } catch (err) {
-        return asError(err);
-      }
-    }
-
-    // Chunked payload.
-    const cid = params.cid;
-    const total = Number(params.ct);
-    const index = Number(params.ci);
-    if (
-      !Number.isInteger(total) ||
-      total <= 0 ||
-      !Number.isInteger(index) ||
-      index < 0 ||
-      index >= total
-    ) {
-      return new Error('ctgr v0: invalid chunk metadata');
-    }
-
-    let entry = this.entries.get(cid);
-    if (!entry) {
-      if (this.entries.size >= this.maxInFlight) {
-        return new Error('ctgr v0: too many in-flight payloads');
-      }
-      entry = {
-        parts: new Array(total),
-        total,
-        received: 0,
-        chars: 0,
-        method,
-        updatedAt: this.now(),
-      };
-      this.entries.set(cid, entry);
-    }
-    entry.updatedAt = this.now();
-
-    const piece = params.p ?? '';
-    if (entry.parts[index] === undefined) {
-      entry.parts[index] = piece;
-      entry.received += 1;
-      entry.chars += piece.length;
-      if (entry.chars > this.maxPayloadChars) {
-        this.entries.delete(cid);
-        return new Error('ctgr v0: payload exceeds size cap');
-      }
-    }
-
-    if (entry.received < entry.total) return false;
-
-    this.entries.delete(cid);
-    try {
-      return toDecoded(decodeV0Payload(entry.parts.join('')), method);
-    } catch (err) {
-      return asError(err);
-    }
-  }
-
-  private evictStale(): void {
-    const cutoff = this.now() - this.ttlMs;
-    for (const [cid, entry] of this.entries) {
-      if (entry.updatedAt < cutoff) this.entries.delete(cid);
-    }
-  }
-}
-
-function asError(err: unknown): Error {
-  return err instanceof Error ? err : new Error(String(err));
-}

package/src/leafSubpathsImportNothing.spec.ts

@@ -1,358 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { readdirSync, rmSync, statSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import pkg from '../package.json';
-
-/**
- * A LEAF subpath's whole promise is what it does NOT pull in. Nothing in this repo
- * measured that until now (2026-09-15), so the promise was kept by hand — and it was
- * broken twice in two days, in the same shape, one level apart.
- *
- * ## The measurement this exists because of
- *
- * `apps/collections/src/kit/binaryStore.ts` needed exactly one thing from here:
- *
- *     import type { FileTokenClaims } from "cursedbelt/server/storage";
- *
- * A TYPE — TypeScript erases it, so the app should have paid nothing at runtime. What it
- * actually paid was:
- *
- *     error: Cannot find package 'otplib' from
- *       …/node_modules/cursedbelt/src/server/auth/totp.ts
- *
- * …and four unrelated route suites died before anything was measured. `server/storage`'s
- * index is a barrel; the barrel reached `streamToken.ts`, which imported the `../auth`
- * INDEX for two jose functions, and that index reaches `totp.ts` → `otplib`, an optional
- * peer. (`sessionStore.ts` takes its Kysely db as a TYPE, so the `kysely` half of the same
- * trap arrives through the `./server` barrel's `db/kysely.ts` instead — measured, not
- * assumed: bundling `./server/storage` externals before this change listed `otplib` and
- * `hono/cookie`, never `kysely`.) The app declared `otplib` as a direct dependency to get
- * its route suites back — a one-time-password library installed to satisfy a claim shape.
- *
- * That is the exact shape 2.5.1 shipped `./server/login-throttle` to fix, one level
- * deeper, and the rule written down after it ("never import the `cursedbelt/server`
- * barrel for one primitive") could not catch it, because `./server/storage` IS a leaf by
- * that rule's standard and has a barrel of its own. A rule that only a human can apply
- * gets re-broken by the next module that looks like a leaf. So: a check.
- *
- * ## What it does
- *
- * Assembles a throwaway consumer under `$TMPDIR` — a `node_modules/cursedbelt` holding
- * this package's REAL package.json (so the real `exports` map is what resolves) and
- * nothing else but the leaf source files themselves — then spawns bun in it and imports
- * each leaf by its PUBLIC specifier. No peers are installed, no other file of this package
- * is even on disk, so any import that survives transpilation fails the import and this
- * spec with it. `import type` is erased and costs nothing, which is the whole point:
- * `verbatimModuleSyntax` is on, so a type import that is not written `import type` is
- * already a typecheck error, and source and `dist` therefore carry the same module graph.
- *
- * ## 🔴 The trap that makes the naive version of this check a lie
- *
- * Bun AUTO-INSTALLS a missing bare import out of `~/.bun/install/cache` when the walk up
- * from the importing file finds NO `node_modules` at all. Measured while building this, in
- * a scratch directory holding two files and nothing else: `import { authenticator } from
- * 'otplib'` resolved — from
- * `~/.bun/install/cache/otplib@13.5.0@@@1/dist/index.js` — and the only error was a missing
- * named export. An "empty fixture" therefore proves NOTHING about what a leaf drags: every
- * peer in the cache answers.
- *
- * Two things hold the line, and the second is the one that matters:
- *
- *  1. `bunfig.toml` with `[install] auto = "disable"` in the fixture root. Note what this
- *     is and is not: with a `node_modules/` present (as here) bun does not auto-install
- *     anyway — removing the line and re-running left the negative control failing exactly
- *     as before. It is the second lock, for the day this fixture is refactored into one
- *     that has no `node_modules` and the trap silently comes back.
- *  2. The NEGATIVE CONTROL: a file importing `otplib` and nothing else is copied in beside
- *     the leaves, and this spec fails if importing it SUCCEEDS. Whatever makes peers
- *     resolvable — auto-install, a `node_modules` above the scratch root, a future bun
- *     default — the control sees it and reds, instead of letting every assertion below
- *     pass vacuously.
- *
- * ## 🔴 Verified failing, 2026-09-15, before it was trusted — every branch
- *
- *   · `import 'otplib'` added to `src/server/storage/types.ts`
- *       → "cursedbelt/server/storage/types must import nothing at runtime … Cannot find
- *          package 'otplib' imported from …/node_modules/cursedbelt/src/server/storage/types.ts"
- *   · the same, but `import { createStreamTokenService } from './streamToken'` — a
- *     relative import of a module inside this package
- *       → red too: "Cannot find module './streamToken'". A leaf may not reach sideways
- *         either, which is why ONLY the leaf files are copied into the fixture.
- *   · `./server/storage/types` re-pointed at `src/server/storage/index.ts`, the barrel it
- *     was split out of
- *       → red: "Cannot find module './videoDerivativeKeys'". A barrel cannot pass this.
- *   · the negative control re-pointed at `loginThrottle.ts`, which imports nothing, so the
- *     fixture stopped demonstrating that peers are unreachable
- *       → red on the control itself: "the fixture resolved 'otplib' … Every assertion below
- *         is vacuous until that is fixed". The vacuity guard fires.
- *   · `src/server/private-media/unlock.ts` put back to `import … from '../auth'` — the
- *     second, two-hop edge, which grep for `../auth` inside `src/server/storage` cannot see
- *       → red: "importing cursedbelt/server/storage statically pulls these OPTIONAL peers
- *         … + otplib". This is the branch that found that edge in the first place.
- */
-
-const REPO = fileURLToPath(new URL('..', import.meta.url));
-
-/**
- * Every subpath that promises to cost a consumer NOTHING at runtime. A leaf earns its
- * place here by being the answer to "I want one type / one primitive out of a module
- * whose index is heavy" — the entry names the runtime symbol proving the module really
- * evaluated, so an accidentally-empty module can never pass this vacuously.
- *
- * The file is read from `exports`, never hard-coded: re-target the subpath and the check
- * follows it to the new file rather than going quietly green against the old one.
- */
-const LEAVES = [
-  {
-    subpath: './server/storage/types',
-    /** Claim/config shapes + the keyspace helpers. apps/collections wants `FileTokenClaims`. */
-    evaluates: 'fsSourceKey',
-  },
-  {
-    subpath: './server/login-throttle',
-    /** The failed-login backoff. Every app with a login door; shipped as 2.5.1. */
-    evaluates: 'createLoginThrottle',
-  },
-] as const;
-
-/**
- * Imports `otplib` and nothing else, so its failure message is unambiguous. It is the
- * proof that the fixture has no peers — not an assertion about `totp.ts` itself.
- */
-const CONTROL = 'src/server/auth/totp.ts';
-
-type Outcome = { ok: true; keys: string[] } | { ok: false; error: string };
-
-const exportsMap = pkg.exports as Record<string, { bun?: string } | string>;
-
-/** `./src/server/storage/types.ts` → `src/server/storage/types.ts`. */
-const sourceOf = (subpath: string): string => {
-  const entry = exportsMap[subpath];
-  const bun = typeof entry === 'object' && entry !== null ? entry.bun : undefined;
-  if (typeof bun !== 'string') {
-    throw new Error(`package.json exports has no \`bun\` target for "${subpath}"`);
-  }
-  return bun.replace(/^\.\//, '');
-};
-
-/**
- * 🔴 The fixture must sit OUTSIDE this repo, and where it lands is not a detail.
- *
- * `scripts/testTmpRoot.ts` redirects `$TMPDIR` per process, and when `$FORGE_STATE`
- * is unset — a bare checkout with no generation around it — its fallback is
- * deliberately repo-local: `<repo>/.agent.noindex/tmp/<pid>`. For every other suite
- * that is exactly right. For this one it is fatal: bun resolves a bare import by
- * walking node_modules UP to the filesystem root, so a fixture under the repo finds
- * `<repo>/node_modules/otplib` and every peer this check exists to prove unreachable
- * becomes reachable.
- *
- * Measured 2026-09-15: with `$FORGE_STATE` set the negative control failed correctly;
- * with it unset the SAME control resolved `otplib` out of this repo's own
- * `node_modules` and the guard fired — *"the fixture resolved 'otplib' … Every
- * assertion below is vacuous until that is fixed"*. So `bun run verify` was green
- * under the runner and red in a plain shell, for a reason that has nothing to do with
- * the code under test. The control did its job; the fixture's address was the bug.
- *
- * Resolution here is therefore explicit rather than inherited. The redirected root is
- * used when it lies outside the repo (the normal case — the runner always sets
- * `$FORGE_STATE`, and the preload's sweep then cleans up after a killed run). When it
- * does not, this hops to `$HOME`, which `resolveTestTmpRoot` refuses for the general
- * default and which this check genuinely requires: an isolated root is the whole
- * measurement. Stale siblings are swept by mtime, the same way the preload does it,
- * so the hop cannot accumulate.
- */
-const REPO_PREFIX = `${REPO.replace(/\/$/, '')}/`;
-
-const fixtureRoot = (): string => {
-  const redirected = process.env.TMPDIR;
-  if (redirected !== undefined && !`${redirected}/`.startsWith(REPO_PREFIX)) {
-    return `${redirected}/leaf-subpath-fixture`;
-  }
-  const home = process.env.HOME?.trim();
-  if (home === undefined || home === '') {
-    throw new Error(
-      'no isolated root available for the leaf fixture ($TMPDIR is inside this repo and $HOME is unset) — ' +
-        'a check that cannot isolate itself is not a passing check',
-    );
-  }
-  const outside = `${home}/.cursedbelt-leaf-fixture.noindex`;
-  try {
-    const cutoff = Date.now() - 6 * 60 * 60 * 1000;
-    for (const entry of readdirSync(outside)) {
-      const path = `${outside}/${entry}`;
-      try {
-        if (statSync(path).mtimeMs < cutoff) rmSync(path, { recursive: true, force: true });
-      } catch {
-        // racing another run's sweep is fine — whoever wins, it goes
-      }
-    }
-  } catch {
-    // no root yet: Bun.write creates it below
-  }
-  return `${outside}/${process.pid}/leaf-subpath-fixture`;
-};
-
-const run = async (): Promise<Record<string, Outcome>> => {
-  const root = fixtureRoot();
-  const pkgDir = `${root}/node_modules/cursedbelt`;
-
-  // The second lock against bun's auto-install (see the header). The negative control is the
-  // first one, and the one that would catch this line being wrong.
-  await Bun.write(`${root}/bunfig.toml`, '[install]\nauto = "disable"\n');
-  // The REAL manifest: the export map under test, resolved exactly as a consumer resolves it.
-  await Bun.write(`${pkgDir}/package.json`, Bun.file(`${REPO}/package.json`));
-
-  const targets: Array<{ name: string; specifier: string }> = [];
-  for (const leaf of LEAVES) {
-    const source = sourceOf(leaf.subpath);
-    // 🔴 Bun.file/Bun.write, NOT node:fs — this repo's test preload virtualizes node:fs, so a
-    // copy made through it can land in a mock the spawned child cannot see. Same trap as
-    // publishShape.spec.ts.
-    await Bun.write(`${pkgDir}/${source}`, Bun.file(`${REPO}/${source}`));
-    targets.push({ name: leaf.subpath, specifier: `cursedbelt/${leaf.subpath.slice(2)}` });
-  }
-  await Bun.write(`${pkgDir}/${CONTROL}`, Bun.file(`${REPO}/${CONTROL}`));
-  // By PATH, not by subpath: the control is deliberately not exported, and an
-  // ERR_PACKAGE_PATH_NOT_EXPORTED would prove nothing about peer resolution.
-  targets.push({ name: 'control', specifier: `./node_modules/cursedbelt/${CONTROL}` });
-
-  await Bun.write(
-    `${root}/entry.ts`,
-    `const targets = ${JSON.stringify(targets)};
-const out = {};
-for (const t of targets) {
-  try {
-    const mod = await import(t.specifier);
-    out[t.name] = { ok: true, keys: Object.keys(mod) };
-  } catch (error) {
-    out[t.name] = { ok: false, error: String((error && error.message) || error) };
-  }
-}
-console.log(JSON.stringify(out));
-`,
-  );
-
-  const child = Bun.spawnSync(['bun', 'run', 'entry.ts'], {
-    cwd: root,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  });
-  const stdout = child.stdout.toString().trim();
-  if (child.exitCode !== 0 || stdout === '') {
-    throw new Error(
-      `the fixture could not run at all (exit ${child.exitCode}) — that is a broken check, not a passing one:\n${child.stderr.toString()}`,
-    );
-  }
-  return JSON.parse(stdout) as Record<string, Outcome>;
-};
-
-/**
- * The other half, and the one that caught the SECOND edge. A leaf can be clean while the
- * barrel it was split out of still drags an optional peer, and a barrel is what most apps
- * import — `music`, `family` and `roms` all take `cursedbelt/server/storage` whole.
- *
- * Measured by bundling the subpath's relative graph with every bare import left external
- * and reading what remains. The subpaths listed must reach NO optional peer with a STATIC
- * import: a static one is paid at import time by every consumer, which is the crash the
- * task above is about; a `await import('sharp')` inside the function that needs it is
- * exactly the right shape and stays legal here.
- *
- * Limitation, stated rather than hidden: the externals are read out of the bundle's import
- * statements textually, so an import bun emits across several lines would be missed. That
- * makes this half a floor, not a ceiling — the runtime fixture above is the strict one.
- */
-const NO_STATIC_OPTIONAL_PEERS = [
-  {
-    subpath: './server/storage',
-    /** Its `streamToken.ts` and (two hops out) `private-media/unlock.ts` both imported the
-     *  `../auth` index for two jose functions, so `otplib` was static in here until 2.6.0. */
-    entry: 'src/server/storage/index.ts',
-  },
-] as const;
-
-const OPTIONAL_PEERS = new Set(
-  Object.entries(
-    (pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> })
-      .peerDependenciesMeta ?? {},
-  )
-    .filter(([, meta]) => meta?.optional === true)
-    .map(([name]) => name),
-);
-
-/** `import x from "pkg"`, `import "pkg"`, `export … from "pkg"` — one line each, as bun emits. */
-const STATIC_SPECIFIER = /^(?:import|export)\s[^\n]*?["']([^"'\n]+)["'];?$|^import\s*["']([^"'\n]+)["'];?$/gm;
-
-const staticOptionalPeersOf = (entry: string): string[] => {
-  const build = Bun.spawnSync(
-    ['bun', 'build', entry, '--target=bun', '--packages=external'],
-    { cwd: REPO, stdout: 'pipe', stderr: 'pipe' },
-  );
-  const bundle = build.stdout.toString();
-  if (build.exitCode !== 0 || bundle.trim() === '') {
-    throw new Error(
-      `could not bundle ${entry} (exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
-    );
-  }
-  const found = new Set<string>();
-  for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
-    const specifier = match[1] ?? match[2];
-    if (specifier === undefined || specifier.startsWith('.')) continue;
-    // `@scope/name/deep` → `@scope/name`, `pkg/deep` → `pkg`.
-    const parts = specifier.split('/');
-    const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
-    if (name !== undefined && OPTIONAL_PEERS.has(name)) found.add(name);
-  }
-  return [...found].sort();
-};
-
-const outcomes = await run();
-
-describe('leaf subpaths import nothing at runtime', () => {
-  it('has a fixture with no peers installed (negative control)', () => {
-    const control = outcomes.control;
-    expect(control, 'the control never ran — the fixture is not measuring anything').toBeDefined();
-    expect(
-      control?.ok === false,
-      `the fixture resolved 'otplib' — bun auto-installed it out of ~/.bun/install/cache, or a node_modules above the fixture answered. Every assertion below is vacuous until that is fixed; do not delete this test to make it pass.`,
-    ).toBe(true);
-    expect(
-      control?.ok === false ? control.error : '',
-      'the control failed for the wrong reason — it must fail on the missing PACKAGE',
-    ).toContain("Cannot find package 'otplib'");
-  });
-
-  for (const leaf of LEAVES) {
-    it(`cursedbelt/${leaf.subpath.slice(2)} imports clean`, () => {
-      const outcome = outcomes[leaf.subpath];
-      expect(outcome, `${leaf.subpath} was never imported by the fixture`).toBeDefined();
-      expect(
-        outcome?.ok === true ? '' : outcome?.ok === false ? outcome.error : 'missing',
-        `cursedbelt/${leaf.subpath.slice(2)} must import NOTHING at runtime — that is the entire reason the subpath exists. Move whatever it now reaches behind \`import type\`, or split the leaf again; do not add the dependency to a consumer.`,
-      ).toBe('');
-      // Non-vacuity: a module that resolved but exported nothing would otherwise pass.
-      expect(
-        outcome?.ok === true ? outcome.keys : [],
-        `${leaf.subpath} resolved but does not export ${leaf.evaluates} — the check is pointing at the wrong file`,
-      ).toContain(leaf.evaluates);
-    });
-  }
-});
-
-describe('barrels reach no optional peer statically', () => {
-  it('knows which peers are optional', () => {
-    // Guards the assertions below: an empty set makes every one of them pass vacuously.
-    expect(OPTIONAL_PEERS.size, 'peerDependenciesMeta lists no optional peer').toBeGreaterThan(10);
-    expect([...OPTIONAL_PEERS], 'otplib is the peer this whole spec was written for').toContain(
-      'otplib',
-    );
-  });
-
-  for (const target of NO_STATIC_OPTIONAL_PEERS) {
-    it(`cursedbelt/${target.subpath.slice(2)} costs a consumer no optional peer to import`, () => {
-      expect(
-        staticOptionalPeersOf(target.entry),
-        `importing cursedbelt/${target.subpath.slice(2)} statically pulls these OPTIONAL peers, so every consumer must install them for code it may never call. Either import the leaf module that has what you need instead of a sibling INDEX (that is how 'otplib' got in here twice), or make the dependency lazy: \`const { x } = await import('pkg')\` inside the function that needs it.`,
-      ).toEqual([]);
-    });
-  }
-});