cursedbelt-core 2.1.1 → 2.3.0

package/src/core/offline/shellWorker.ts

@@ -0,0 +1,346 @@
+/**
+ * The app-shell service worker, once, for every app that serves its shell offline
+ * (task 2073, 2026-09-22).
+ *
+ * `apps/roms` wrote this by hand as plain JS in `public/sw.js`, with a TypeScript
+ * twin in `src/offline/swRouting.ts` held in step by a comment saying "keep the two
+ * in step". `apps/music` needed the same worker, and a third hand copy is how a fix
+ * lands in one app and not the others. This module is the one body; an app's
+ * `src/sw.ts` passes a config and adds whatever is genuinely its own (background
+ * sync, an outbox, a digest-keyed media cache) as further listeners beside it.
+ *
+ * What it does, and it is deliberately all it does:
+ *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
+ *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
+ *                 then `clients.claim()`.
+ *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *                 network-first, falling back offline to the exact URL, then the same
+ *                 path ignoring the query, then the shell. Everything else is left on
+ *                 the network: `respondWith` is never called for it.
+ *
+ * 🔴 `/api/` is NEVER cached and NEVER served from a cache. It is auth-gated, and a
+ * browser whose session has since been revoked must not read yesterday's copy of a
+ * private response out of its own cache. That is not a default a config can switch
+ * off: `apiPrefixes` ADDS prefixes to `/api/`, it cannot remove it, a precache entry
+ * under an API prefix is refused when the worker is installed, and `shouldCache`
+ * refuses to store an `api` route even if a caller asks.
+ *
+ * 🔴 `noShellFallback` exists because of the 2026-08-12 frame incident in roms. A game
+ * boots by loading `/emulator-frame.html` into a sandboxed iframe — a NAVIGATION, so it
+ * went network-first, and offline with nothing cached under that path the fallback
+ * handed it the APP SHELL. The iframe rendered a second copy of the library where the
+ * game should be: no canvas, no error, no clue. Any document that is not the shell (an
+ * iframe, a popup, a print view) must be listed there, and must be in `precache` if it
+ * is meant to work offline at all — an offline miss on it then REJECTS, which is the
+ * honest answer, rather than resolving the wrong document.
+ *
+ * Imports nothing at runtime (`leafSubpathsImportNothing.spec.ts` holds it to that):
+ * it is bundled into a service worker, where every byte ships on every install.
+ * `scope` is typed structurally so this compiles without the WebWorker lib, is testable
+ * with a fake, and still accepts the real `self` — `shellWorker.webworker.spec.ts`
+ * typechecks exactly that against `lib.webworker.d.ts`.
+ */
+
+/** Where a request goes. */
+export type ShellRoute =
+  /** A document navigation — network-first, cached-document fallback offline. */
+  | 'navigate'
+  /** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first. */
+  | 'asset'
+  /** An auth-gated API call — never cached, never answered from a cache. */
+  | 'api'
+  /** Everything else (non-GET, cross-origin, `passthroughPrefixes`) — untouched. */
+  | 'passthrough';
+
+/** The facts about a request that classification reads — nothing else. */
+export interface RequestFacts {
+  method: string;
+  /** Same origin as the worker (`new URL(request.url).origin === location.origin`). */
+  sameOrigin: boolean;
+  /** URL pathname, no query. */
+  pathname: string;
+  /** `request.mode === 'navigate'`. */
+  isNavigate: boolean;
+}
+
+export interface ShellWorkerConfig {
+  /**
+   * Every cache this worker owns is named `<cachePrefix><version>`, and `activate`
+   * deletes every OTHER cache starting with `cachePrefix`. So the prefix must be one
+   * nothing else in the app shares — `roms-shell-`, not `roms-`, or the app's own
+   * digest-keyed caches go with it.
+   */
+  cachePrefix: string;
+  /** Bump to evict the previous shell on the next activate. */
+  version: string;
+  /**
+   * Same-origin paths fetched into the cache at install. `shellPath` is always
+   * precached whether listed or not — a shell fallback with no shell is no fallback.
+   */
+  precache: readonly string[];
+  /**
+   * Extra API prefixes. `/api/` is ALWAYS one of them and cannot be removed — see the
+   * header. Default: `['/api/']`.
+   */
+  apiPrefixes?: readonly string[];
+  /**
+   * Same-origin prefixes the worker must leave alone even for GET assets — e.g. roms'
+   * `/_nes-roms/`, whose bytes the app caches itself under a content digest.
+   */
+  passthroughPrefixes?: readonly string[];
+  /**
+   * Exact pathnames that must NEVER be answered with the shell offline (roms'
+   * `/emulator-frame.html`). An offline miss on one rejects instead. See the header.
+   */
+  noShellFallback?: readonly string[];
+  /** Which same-origin pathnames count as static assets. Default: `DEFAULT_ASSET_EXT`. */
+  assetExtensions?: RegExp;
+  /** The app shell's path, the navigation fallback. Default: `'/'`. */
+  shellPath?: string;
+}
+
+/** A config with every default applied and every refusal already checked. */
+export interface ResolvedShellWorkerConfig {
+  cachePrefix: string;
+  version: string;
+  cacheName: string;
+  precache: readonly string[];
+  apiPrefixes: readonly string[];
+  passthroughPrefixes: readonly string[];
+  noShellFallback: readonly string[];
+  assetExtensions: RegExp;
+  shellPath: string;
+}
+
+/** roms' `ASSET_EXT`, verbatim. */
+export const DEFAULT_ASSET_EXT = /\.(?:js|mjs|css|wasm|woff2?|ttf|png|jpe?g|webp|svg|ico|json)$/i;
+
+/** Always an API prefix, whatever the config says. */
+export const ALWAYS_API_PREFIX = '/api/';
+
+const apiPrefixesOf = (config: Pick<ShellWorkerConfig, 'apiPrefixes'>): readonly string[] => {
+  const extra = config.apiPrefixes ?? [];
+  return extra.includes(ALWAYS_API_PREFIX) ? extra : [ALWAYS_API_PREFIX, ...extra];
+};
+
+const startsWithAny = (pathname: string, prefixes: readonly string[]): boolean =>
+  prefixes.some((prefix) => pathname.startsWith(prefix));
+
+/**
+ * Classify a request. Order matters and is roms' order: non-GET and cross-origin
+ * first, then the API (so an API path that happens to end in `.json` is still `api`),
+ * then the app's own passthrough prefixes, then navigation, then assets.
+ */
+export function classifyRequest(
+  facts: RequestFacts,
+  config: Pick<ShellWorkerConfig, 'apiPrefixes' | 'passthroughPrefixes' | 'assetExtensions'> = {},
+): ShellRoute {
+  if (facts.method !== 'GET') return 'passthrough';
+  if (!facts.sameOrigin) return 'passthrough';
+  if (startsWithAny(facts.pathname, apiPrefixesOf(config))) return 'api';
+  if (startsWithAny(facts.pathname, config.passthroughPrefixes ?? [])) return 'passthrough';
+  if (facts.isNavigate) return 'navigate';
+  if ((config.assetExtensions ?? DEFAULT_ASSET_EXT).test(facts.pathname)) return 'asset';
+  return 'passthrough';
+}
+
+/** Whether a response on this route may be written to the cache. Never `api`. */
+export function shouldCache(route: ShellRoute): boolean {
+  return route === 'asset' || route === 'navigate';
+}
+
+/** May an offline miss on this navigation be answered with the shell? */
+export function mayFallBackToShell(pathname: string, config: Pick<ShellWorkerConfig, 'noShellFallback'> = {}): boolean {
+  return !(config.noShellFallback ?? []).includes(pathname);
+}
+
+/**
+ * Apply defaults and refuse the configs that would break a promise in the header.
+ * `installShellWorker` calls this; it is exported so an app's own test can prove its
+ * config is accepted without standing up a worker.
+ */
+export function resolveShellWorkerConfig(config: ShellWorkerConfig): ResolvedShellWorkerConfig {
+  if (config.cachePrefix.trim() === '') {
+    // An empty prefix makes EVERY cache on the origin "an old version of ours", and
+    // activate would delete the app's other caches with it.
+    throw new Error('shell worker: cachePrefix must not be empty — activate deletes every cache it prefixes');
+  }
+  if (config.version.trim() === '') throw new Error('shell worker: version must not be empty');
+  const shellPath = config.shellPath ?? '/';
+  const apiPrefixes = apiPrefixesOf(config);
+  const precache = config.precache.includes(shellPath) ? [...config.precache] : [shellPath, ...config.precache];
+  for (const path of precache) {
+    if (!path.startsWith('/')) {
+      throw new Error(`shell worker: precache entry "${path}" must be a same-origin path starting with "/"`);
+    }
+    if (startsWithAny(path, apiPrefixes)) {
+      throw new Error(`shell worker: precache entry "${path}" is under an API prefix — the API is never cached`);
+    }
+  }
+  if (config.noShellFallback?.includes(shellPath)) {
+    throw new Error(`shell worker: the shell path "${shellPath}" cannot also be in noShellFallback`);
+  }
+  return {
+    cachePrefix: config.cachePrefix,
+    version: config.version,
+    cacheName: `${config.cachePrefix}${config.version}`,
+    precache,
+    apiPrefixes,
+    passthroughPrefixes: config.passthroughPrefixes ?? [],
+    noShellFallback: config.noShellFallback ?? [],
+    assetExtensions: config.assetExtensions ?? DEFAULT_ASSET_EXT,
+    shellPath,
+  };
+}
+
+// ── The structural slice of ServiceWorkerGlobalScope this worker touches ──────────
+// Method syntax throughout, on purpose: TypeScript checks method parameters
+// bivariantly, which is what lets the real `self` (whose `Request`/`Response` are
+// far wider than these) satisfy them.
+
+export interface ShellWorkerRequest {
+  readonly url: string;
+  readonly method: string;
+  readonly mode: string;
+}
+
+/**
+ * The structural mirror of `RequestInfo | URL` — a request, a string, or a URL-like —
+ * which is what the real `fetch`, `Cache` and `CacheStorage` accept. It has to be the
+ * whole union: with `ShellWorkerRequest` alone the real `self` is refused, because a
+ * `URL` is not a request in either direction (measured by the webworker spec).
+ */
+export type ShellWorkerRequestInfo = ShellWorkerRequest | string | { readonly href: string };
+
+export interface ShellWorkerResponse {
+  readonly ok: boolean;
+  clone(): ShellWorkerResponse;
+}
+
+export interface ShellWorkerCache {
+  addAll(requests: string[]): Promise<void>;
+  put(request: ShellWorkerRequestInfo, response: ShellWorkerResponse): Promise<void>;
+}
+
+export interface ShellWorkerCacheStorage {
+  open(cacheName: string): Promise<ShellWorkerCache>;
+  keys(): Promise<string[]>;
+  delete(cacheName: string): Promise<boolean>;
+  match(request: ShellWorkerRequestInfo, options?: { ignoreSearch?: boolean }): Promise<ShellWorkerResponse | undefined>;
+}
+
+export interface ShellExtendableEvent {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+export interface ShellFetchEvent extends ShellExtendableEvent {
+  readonly request: ShellWorkerRequest;
+  respondWith(response: Promise<ShellWorkerResponse>): void;
+}
+
+export interface ShellWorkerScope {
+  addEventListener(type: 'install', listener: (event: ShellExtendableEvent) => void): void;
+  addEventListener(type: 'activate', listener: (event: ShellExtendableEvent) => void): void;
+  addEventListener(type: 'fetch', listener: (event: ShellFetchEvent) => void): void;
+  readonly caches: ShellWorkerCacheStorage;
+  readonly clients: { claim(): Promise<void> };
+  readonly location: { readonly origin: string };
+  fetch(request: ShellWorkerRequestInfo): Promise<ShellWorkerResponse>;
+  skipWaiting(): Promise<void>;
+}
+
+/**
+ * Wire `install`, `activate` and `fetch` onto `scope` (the worker's `self`).
+ * Returns the resolved config, so an app can read `cacheName` for its own use.
+ */
+export function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerConfig): ResolvedShellWorkerConfig {
+  const resolved = resolveShellWorkerConfig(config);
+  const { caches } = scope;
+
+  // Written after the response is handed back, like roms' `cache.put` — but kept
+  // alive with `waitUntil` so the worker is not stopped mid-write, and swallowed on
+  // failure: a full quota must not turn a good network response into an error.
+  const store = (event: ShellFetchEvent, route: ShellRoute, response: ShellWorkerResponse): void => {
+    if (!shouldCache(route) || !response.ok) return;
+    const copy = response.clone();
+    event.waitUntil(
+      caches
+        .open(resolved.cacheName)
+        .then((cache) => cache.put(event.request, copy))
+        .catch(() => undefined),
+    );
+  };
+
+  const cacheFirst = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
+    const cached = await caches.match(event.request);
+    if (cached) return cached;
+    const response = await scope.fetch(event.request);
+    store(event, 'asset', response);
+    return response;
+  };
+
+  const networkFirst = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
+    const { request } = event;
+    try {
+      const response = await scope.fetch(request);
+      store(event, 'navigate', response);
+      return response;
+    } catch (error) {
+      // Offline. The exact URL first, then the same path ignoring the query — roms'
+      // frame is `/emulator-frame.html?system=nes`, and one cached copy answers for
+      // every console.
+      const cached = (await caches.match(request)) ?? (await caches.match(request, { ignoreSearch: true }));
+      if (cached) return cached;
+      if (mayFallBackToShell(new URL(request.url).pathname, resolved)) {
+        const shell = await caches.match(resolved.shellPath);
+        if (shell) return shell;
+      }
+      // Nothing honest to serve: reject, and the browser shows its own offline page
+      // rather than a document that is not the one asked for.
+      throw error;
+    }
+  };
+
+  scope.addEventListener('install', (event) => {
+    event.waitUntil(
+      caches
+        .open(resolved.cacheName)
+        .then((cache) => cache.addAll([...resolved.precache]))
+        .then(() => scope.skipWaiting()),
+    );
+  });
+
+  scope.addEventListener('activate', (event) => {
+    event.waitUntil(
+      caches
+        .keys()
+        .then((keys) =>
+          Promise.all(
+            keys
+              .filter((key) => key.startsWith(resolved.cachePrefix) && key !== resolved.cacheName)
+              .map((key) => caches.delete(key)),
+          ),
+        )
+        .then(() => scope.clients.claim()),
+    );
+  });
+
+  scope.addEventListener('fetch', (event) => {
+    const url = new URL(event.request.url);
+    const route = classifyRequest(
+      {
+        method: event.request.method,
+        sameOrigin: url.origin === scope.location.origin,
+        pathname: url.pathname,
+        isNavigate: event.request.mode === 'navigate',
+      },
+      resolved,
+    );
+    if (route === 'asset') event.respondWith(cacheFirst(event));
+    else if (route === 'navigate') event.respondWith(networkFirst(event));
+    // `api` and `passthrough`: no respondWith, so the browser goes to the network as
+    // if this worker did not exist. Never a cache read, never a cache write.
+  });
+
+  return resolved;
+}

package/src/core/offline/shellWorker.webworker.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'bun:test';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `ShellWorkerScope` is structural so the module typechecks without the WebWorker lib
+ * and can be tested with a fake. The promise that makes that worth anything is the
+ * other half: an app's `src/sw.ts` passes the REAL `self` and it must compile. Nothing
+ * in this repo's own tsconfig can see that (it carries lib DOM, not WebWorker), so this
+ * spec typechecks a two-file fixture against `lib.webworker.d.ts` with no DOM at all:
+ *
+ *  - `sw.ts`       passes a `ServiceWorkerGlobalScope` — must be clean;
+ *  - `control.ts`  passes a scope with no `caches` — must be RED, or tsc was not
+ *                  checking anything and the clean result above is vacuous.
+ *
+ * It also proves `shellWorker.ts` itself compiles with no DOM lib, which is the lib a
+ * service-worker build has.
+ */
+const REPO = fileURLToPath(new URL('../../..', import.meta.url));
+const SOURCE = fileURLToPath(new URL('./shellWorker.ts', import.meta.url));
+
+const typecheck = async (): Promise<string> => {
+  const root = `${process.env.TMPDIR ?? '/tmp'}/shell-worker-webworker-${process.pid}`;
+  // Bun.write, NOT node:fs — this repo's test preload virtualizes node:fs, and the
+  // spawned tsc would read a directory the mock never wrote.
+  await Bun.write(
+    `${root}/tsconfig.json`,
+    JSON.stringify({
+      compilerOptions: {
+        target: 'ESNext',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
+        lib: ['ESNext', 'WebWorker'],
+        types: [],
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        allowImportingTsExtensions: true,
+      },
+      files: ['sw.ts', 'control.ts'],
+    }),
+  );
+  await Bun.write(
+    `${root}/sw.ts`,
+    `import { installShellWorker } from ${JSON.stringify(SOURCE)};
+declare const sw: ServiceWorkerGlobalScope;
+installShellWorker(sw, { cachePrefix: 'app-shell-', version: 'v1', precache: ['/'] });
+`,
+  );
+  await Bun.write(
+    `${root}/control.ts`,
+    `import { installShellWorker } from ${JSON.stringify(SOURCE)};
+declare const sw: ServiceWorkerGlobalScope;
+const { caches: _dropped, ...noCaches } = sw;
+installShellWorker(noCaches, { cachePrefix: 'app-shell-', version: 'v1', precache: ['/'] });
+`,
+  );
+  const child = Bun.spawnSync([process.execPath, `${REPO}/node_modules/typescript/bin/tsc`, '-p', root], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  return `${child.stdout.toString()}${child.stderr.toString()}`;
+};
+
+const output = await typecheck();
+const errorsIn = (file: string): string[] =>
+  output.split('\n').filter((line) => line.includes(`${file}(`) && line.includes('error TS'));
+
+describe('shell worker against lib.webworker', () => {
+  it('rejects a scope with no caches (negative control — tsc really checked)', () => {
+    const control = errorsIn('control.ts');
+    expect(control.length, `tsc output:\n${output}`).toBeGreaterThan(0);
+    // Red for the RIGHT reason — the missing member, not a broken fixture.
+    expect(output, `tsc output:\n${output}`).toContain("Property 'caches' is missing");
+  });
+
+  it('accepts the real ServiceWorkerGlobalScope, and the module compiles without DOM', () => {
+    expect(errorsIn('sw.ts'), `tsc output:\n${output}`).toEqual([]);
+    expect(errorsIn('shellWorker.ts'), `tsc output:\n${output}`).toEqual([]);
+  });
+});

package/src/core/passwordPolicy.spec.ts

@@ -0,0 +1,19 @@
+/**
+ * The floor may be RAISED by an app and never lowered — the asymmetry is the whole policy.
+ */
+import { describe, expect, it } from 'bun:test';
+import { DEFAULT_MIN_PASSWORD_BYTES, resolveMinPasswordBytes } from './passwordPolicy';
+
+describe('resolveMinPasswordBytes', () => {
+  it('is the shared default when an app asks for nothing', () => {
+    expect(resolveMinPasswordBytes()).toBe(DEFAULT_MIN_PASSWORD_BYTES);
+    expect(DEFAULT_MIN_PASSWORD_BYTES).toBe(9);
+  });
+  it('lets an app raise it, visibly, at its own call site', () => {
+    expect(resolveMinPasswordBytes(14)).toBe(14);
+  });
+  it('🔴 refuses to go BELOW the default, and refuses a non-integer', () => {
+    expect(() => resolveMinPasswordBytes(8)).toThrow(/may only be RAISED/);
+    expect(() => resolveMinPasswordBytes(9.5)).toThrow(/must be an integer/);
+  });
+});

package/src/core/passwordPolicy.ts

@@ -0,0 +1,63 @@
+/**
+ * The one place a satellite's owner-password floor is decided.
+ *
+ * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
+ * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
+ * a paragraph in each explaining itself against the others. A floor is a
+ * POLICY, and a policy copied three times is three policies.
+ *
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
+ * owner wants for an ordinary satellite: long enough that it is not a PIN, short
+ * enough that it does not push the owner toward writing it down or reusing one.
+ * Argon2id — what every caller hashes with — is what actually carries the cost
+ * of a guess here; these apps have exactly ONE principal and no enumerable user
+ * list, so the marginal value of characters 10–14 is small and the friction is
+ * not.
+ *
+ * ── `cursedbelt-core/password-policy`, since 2.3.0 (task 321) ────────────────
+ * The floor that exists so it cannot drift was itself copied — `src/kit/passwordPolicy.ts`
+ * in `auth`, `patterns` and `vault`. It is here, in the isomorphic tier, because `vault`
+ * enforces it in the BROWSER (`src/crypto/vaultCipher.ts`) as well as on the server, and a
+ * floor checked in two runtimes must be one import in both. It imports nothing.
+ *
+ * ── Raising it is an APP's decision, and it is the only direction ───────────
+ * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
+ * go below the default**. An app that genuinely runs at higher stakes says so
+ * at its own call site, in one visible argument, with a comment saying why.
+ * No app overrides it today — the retired orch companion app did (14, as the single
+ * internet-facing door into the host that runs `claude` in every repo) until
+ * the owner dropped it to the shared floor on 2026-07-26.
+ *
+ * The asymmetry is the whole point: a shared default can be raised locally
+ * where the risk is local, but nothing can quietly lower the floor for
+ * everyone — which is exactly the mistake a bare exported constant invites.
+ */
+
+/**
+ * The floor, in BYTES as typed (not codepoints — callers measure the raw bytes
+ * they read, so a multi-byte character counts as more than one, which is the
+ * conservative direction).
+ */
+export const DEFAULT_MIN_PASSWORD_BYTES = 9;
+
+/**
+ * The floor this app enforces: the default, or a higher one it asks for.
+ *
+ * Throws on an override below the default rather than silently clamping. A
+ * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * how a security floor becomes folklore.
+ */
+export function resolveMinPasswordBytes(override?: number): number {
+	if (override === undefined) return DEFAULT_MIN_PASSWORD_BYTES;
+	if (!Number.isInteger(override)) {
+		throw new Error(`minPasswordBytes must be an integer, got ${override}`);
+	}
+	if (override < DEFAULT_MIN_PASSWORD_BYTES) {
+		throw new Error(
+			`minPasswordBytes may only be RAISED above the shared default of ` +
+				`${DEFAULT_MIN_PASSWORD_BYTES}; refusing ${override}`,
+		);
+	}
+	return override;
+}

package/src/leafSubpathsImportNothing.spec.ts

@@ -108,6 +108,16 @@ const LEAVES = [
     /** Wire-format types + the method⇄abbreviation maps. Trivially isomorphic on purpose. */
     evaluates: 'METHOD_TO_ABBREV',
   },
+  {
+    subpath: './offline/shell-worker',
+    /** Bundled into an app's service worker, where every byte ships on every install. */
+    evaluates: 'installShellWorker',
+  },
+  {
+    subpath: './password-policy',
+    /** The owner-password floor (2.3.0, task 321) — enforced in a browser bundle as well as a server. */
+    evaluates: 'resolveMinPasswordBytes',
+  },
 ] as const;
 
 /**