cursedbelt-server 4.24.0 → 4.25.0

package/src/server/auth/loginThrottleDurable.ts

@@ -0,0 +1,291 @@
+/**
+ * The login throttle on a Cloudflare Worker: ONE Durable Object holds the ledger, every isolate
+ * asks it.
+ *
+ * ── Why this exists (2026-09-23, patterns task 2136) ─────────────────────────
+ * `createLoginThrottle` keeps its counts in memory, and its header accepts that because on the
+ * Mac "memory" is the one process an attacker cannot restart. On a Worker there is no such
+ * process. `apps/patterns`' Worker first built the throttle per REQUEST — every attempt was a
+ * first attempt, so the sign-in had no failed-login brake at all — and then per ISOLATE, which
+ * is still one ledger per colo (often several per colo), each wiped by every deploy: a guesser
+ * spread across N isolates gets N × the global allowance the header calls "the actual defense".
+ *
+ * A Durable Object is the exact shape of the fix: one instance addressed by name, requests to it
+ * serialised, so every isolate in every colo meets the same counts. It runs the SAME
+ * `createLoginThrottle` algorithm — nothing here re-decides a threshold or a delay — and persists
+ * the ledger to the object's storage after every change, so the object's own eviction (minutes
+ * idle, measured on patterns' live object) forgets nothing either.
+ *
+ * ── Why not D1 ──────────────────────────────────────────────────────────────
+ * The throttle is checked BEFORE argon2, on every attempt, and the point of checking first is
+ * that a refused attempt is cheap. A D1 read-modify-write per attempt is a query against the
+ * invocation's 1,000-query budget and, worse, not atomic across concurrent invocations: two
+ * guesses that snapshot the same count both write count+1. The object serialises for free.
+ *
+ * ── `attempt` is one operation, not two ─────────────────────────────────────
+ * `/throttle/attempt` checks and charges in one serialised step, so a burst of concurrent guesses
+ * is admitted only up to the threshold rather than all at once against one stale count. See
+ * `loginThrottle.ts`'s `attempt` section.
+ *
+ * ── When the object cannot be reached ───────────────────────────────────────
+ * {@link createRemoteLoginThrottle} takes a `fallback` — the isolate's own module-scope
+ * throttle — and MIRRORS every write into it. The object is the authority whenever it answers;
+ * when a call throws or answers non-2xx, the fallback decides and the error is logged. So an
+ * outage degrades the door to exactly the per-isolate brake it had before, never to none, and
+ * never to a 500 the owner cannot sign in past. Without a `fallback` the error propagates.
+ *
+ * ── Types are structural ────────────────────────────────────────────────────
+ * No `@cloudflare/workers-types`: an app whose `src/server` also runs under Bun cannot take Worker
+ * globals over its whole type graph (patterns measured five broken `randomBytes(n)` calls the one
+ * time it tried). The object uses the classic `fetch` interface for the same reason.
+ */
+import {
+  createLoginThrottle,
+  type AsyncLoginThrottle,
+  type LoginThrottle,
+  type LoginThrottleOptions,
+  type LoginThrottleSnapshot,
+  type ThrottleVerdict,
+} from './loginThrottle.js';
+
+/** The name every isolate addresses unless told otherwise — one object, one ledger set. */
+export const LOGIN_THROTTLE_OBJECT_NAME = 'login-throttle';
+
+/**
+ * Every operation the object answers, `[method, path]` — for an app's CPU-budget census, which
+ * must declare each path a tail can deliver. `loginThrottleDurable.spec.ts` reds if the object
+ * answers a path not listed here, or stops answering one that is.
+ */
+export const LOGIN_THROTTLE_OPERATIONS = [
+  ['POST', '/throttle/check'],
+  ['POST', '/throttle/attempt'],
+  ['POST', '/throttle/fail'],
+  ['POST', '/throttle/ok'],
+  ['POST', '/throttle/reset'],
+] as const;
+
+/**
+ * Keys persisted per ledger — the most recently seen. The in-memory table keeps its own
+ * `maxKeys` cap; this one keeps a stored value well under a Durable Object's per-value limit
+ * (128 KiB on the KV backend) at roughly 80 bytes a key. The global counter is always kept, and
+ * it is the counter a distributed guesser meets, so a key dropped here costs a courtesy layer
+ * only.
+ */
+export const PERSISTED_KEYS = 1024;
+
+/** A ledger is a short slug — the object keys its storage by it. */
+const LEDGER = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** Longer than any address or `<email>:<ip>`; a bound so a key cannot be a storage vector. */
+const MAX_KEY_CHARS = 320;
+
+/** The two members of `DurableObjectStorage` this reads — the KV API, on either backend. */
+export interface DurableStorageLike {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  put<T>(key: string, value: T): Promise<void>;
+}
+
+/** The members of `DurableObjectState` this reads. */
+export interface DurableStateLike {
+  storage: DurableStorageLike;
+  blockConcurrencyWhile?<T>(callback: () => Promise<T>): Promise<T>;
+}
+
+/** The members of a `DurableObjectNamespace` binding the client calls. */
+export interface DurableNamespaceLike {
+  idFromName(name: string): unknown;
+  get(id: unknown): { fetch(request: Request): Promise<Response> };
+}
+
+const json = (value: unknown, status = 200): Response =>
+  new Response(JSON.stringify(value ?? null), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+
+/**
+ * The Durable Object. Re-export it from the Worker's entry under the `class_name` your
+ * `wrangler.jsonc` binds, and add it in a migration (`new_sqlite_classes`):
+ *
+ *     export { LoginThrottleObject as PatternsThrottle } from "cursedbelt-server/login-throttle/durable";
+ *
+ * One object holds any number of named LEDGERS (`owner`, `probe`, …), each an independent
+ * `createLoginThrottle` persisted under `ledger:<name>`.
+ */
+export class LoginThrottleObject {
+  private readonly ledgers = new Map<string, Promise<LoginThrottle>>();
+  private readonly storage: DurableStorageLike;
+  private readonly options: LoginThrottleOptions;
+
+  /**
+   * `options` is for tests (a clock, a threshold); the runtime passes `(state, env)` only, and
+   * the throttle's own defaults are the fleet's.
+   */
+  constructor(state: DurableStateLike, _env?: unknown, options: LoginThrottleOptions = {}) {
+    this.storage = state.storage;
+    this.options = options;
+  }
+
+  /**
+   * The ledger, loaded once per object lifetime. The PROMISE is memoised, not the result, so two
+   * requests arriving while the first load is in flight share it rather than each restoring its
+   * own copy and one of them overwriting the other's charge.
+   */
+  private ledger(name: string): Promise<LoginThrottle> {
+    let loading = this.ledgers.get(name);
+    if (!loading) {
+      loading = this.storage
+        .get<LoginThrottleSnapshot>(`ledger:${name}`)
+        .then((restore) => createLoginThrottle({ ...this.options, restore: restore ?? null }));
+      // A failed load must not be cached as the ledger for the object's whole life.
+      loading.catch(() => this.ledgers.delete(name));
+      this.ledgers.set(name, loading);
+    }
+    return loading;
+  }
+
+  private persist(name: string, throttle: LoginThrottle): Promise<void> {
+    return this.storage.put(`ledger:${name}`, throttle.snapshot(PERSISTED_KEYS));
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const path = new URL(request.url).pathname;
+    if (request.method !== 'POST') return json({ error: `${request.method} ${path}: POST only` }, 405);
+    let body: { ledger?: unknown; key?: unknown };
+    try {
+      body = (await request.json()) as typeof body;
+    } catch {
+      return json({ error: 'body must be JSON {ledger, key}' }, 400);
+    }
+    const name = body?.ledger;
+    const key = body?.key;
+    if (typeof name !== 'string' || !LEDGER.test(name)) return json({ error: 'ledger must be a short slug' }, 400);
+    if (typeof key !== 'string' || key.length === 0 || key.length > MAX_KEY_CHARS) {
+      return json({ error: `key must be 1–${MAX_KEY_CHARS} characters` }, 400);
+    }
+
+    const throttle = await this.ledger(name);
+    switch (path) {
+      case '/throttle/check':
+        return json(throttle.check(key));
+      case '/throttle/attempt': {
+        const verdict = throttle.attempt(key);
+        // A refused attempt changed nothing; an admitted one was charged and must be kept.
+        if (verdict.allowed) await this.persist(name, throttle);
+        return json(verdict);
+      }
+      case '/throttle/fail': {
+        const verdict = throttle.recordFailure(key);
+        await this.persist(name, throttle);
+        return json(verdict);
+      }
+      case '/throttle/ok':
+        throttle.recordSuccess(key);
+        await this.persist(name, throttle);
+        return json({ ok: true });
+      case '/throttle/reset':
+        throttle.reset(key);
+        await this.persist(name, throttle);
+        return json({ ok: true });
+      default:
+        return json({ error: `no such throttle operation ${path}` }, 404);
+    }
+  }
+}
+
+export interface RemoteLoginThrottleOptions {
+  /** Which ledger in the object. Default `"default"`. A second ledger never spends the first's. */
+  ledger?: string;
+  /** Which object. Default {@link LOGIN_THROTTLE_OBJECT_NAME}. */
+  objectName?: string;
+  /**
+   * The isolate's own throttle, at MODULE scope — mirrored on every write and consulted only when
+   * the object cannot answer. See the header. Omitted → an unreachable object is an error.
+   */
+  fallback?: LoginThrottle;
+  /** Where an unreachable-object line goes. Default `console.error`. */
+  onError?: (line: string) => void;
+}
+
+/**
+ * The client half: an {@link AsyncLoginThrottle} whose ledger lives in the object. Cheap to build —
+ * build it per request over `env.<BINDING>`; the state is on the other side of the call.
+ */
+export function createRemoteLoginThrottle(
+  namespace: DurableNamespaceLike,
+  options: RemoteLoginThrottleOptions = {},
+): AsyncLoginThrottle {
+  const ledger = options.ledger ?? 'default';
+  if (!LEDGER.test(ledger)) throw new Error(`login throttle ledger "${ledger}" must be a short slug`);
+  const objectName = options.objectName ?? LOGIN_THROTTLE_OBJECT_NAME;
+  const fallback = options.fallback;
+  const onError = options.onError ?? ((line: string) => console.error(line));
+
+  const call = async <T>(path: string, key: string): Promise<T> => {
+    const stub = namespace.get(namespace.idFromName(objectName));
+    const response = await stub.fetch(
+      new Request(`https://login-throttle.invalid${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ ledger, key }),
+      }),
+    );
+    if (!response.ok) throw new Error(`${path} answered ${response.status}: ${await response.text()}`);
+    return (await response.json()) as T;
+  };
+
+  /** Ask the object; on failure, let the fallback answer (or rethrow when there is none). */
+  const remote = async <T>(path: string, key: string, local: (() => T) | undefined): Promise<T> => {
+    try {
+      return await call<T>(path, key);
+    } catch (error) {
+      if (!local) throw error;
+      onError(
+        `[login-throttle] the "${objectName}" object did not answer ${path} (${error instanceof Error ? error.message : String(error)}) — ` +
+          `this isolate's own ledger decides, which is per-isolate only`,
+      );
+      return local();
+    }
+  };
+
+  return {
+    check: (key) => remote<ThrottleVerdict>('/throttle/check', key, fallback && (() => fallback.check(key))),
+    async attempt(key) {
+      let mirrored = false;
+      const verdict = await remote<ThrottleVerdict>(
+        '/throttle/attempt',
+        key,
+        fallback &&
+          (() => {
+            mirrored = true;
+            return fallback.attempt(key);
+          }),
+      );
+      // The mirror: an admitted attempt the object charged is charged here too, so an outage
+      // later in this isolate's life starts from what it has seen rather than from zero.
+      if (!mirrored && verdict.allowed) fallback?.recordFailure(key);
+      return verdict;
+    },
+    async recordFailure(key) {
+      let mirrored = false;
+      const verdict = await remote<ThrottleVerdict>(
+        '/throttle/fail',
+        key,
+        fallback &&
+          (() => {
+            mirrored = true;
+            return fallback.recordFailure(key);
+          }),
+      );
+      if (!mirrored) fallback?.recordFailure(key);
+      return verdict;
+    },
+    async recordSuccess(key) {
+      fallback?.recordSuccess(key);
+      await remote<unknown>('/throttle/ok', key, fallback && (() => null));
+    },
+    async reset(key) {
+      fallback?.reset(key);
+      await remote<unknown>('/throttle/reset', key, fallback && (() => null));
+    },
+  };
+}

package/src/server/telemetryIsWorkerSafe.spec.ts

@@ -58,6 +58,20 @@ describe('🔴 cursedbelt-server/worker-argon2 — it exists to be imported by a
 		};
 		expect(pkg.exports['./worker-argon2']?.import).toBe('./dist/server/worker-argon2/index.js');
 	});
+
+	test('Node is refused by name — its WebAssembly ESM integration cannot load the static `.wasm` imports', async () => {
+		// 4.24.0 published with no `node` condition and failed proveInstall: node read the `.wasm`
+		// as an ES module and died on `Cannot find package 'env'`. wrangler never activates `node`
+		// (a dry-run bundle of the probe Worker carries both `.wasm` modules), so this costs a Worker nothing.
+		const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as {
+			exports: Record<string, Record<string, string>>;
+		};
+		const conditions = Object.keys(pkg.exports['./worker-argon2'] ?? {});
+		expect(pkg.exports['./worker-argon2']?.node).toBe('./dist/server/worker-argon2/_nodeRefuses.js');
+		expect(conditions.indexOf('node')).toBeLessThan(conditions.indexOf('import'));
+		expect(conditions.indexOf('bun')).toBeLessThan(conditions.indexOf('node'));
+		await expect(import('./worker-argon2/_nodeRefuses.ts')).rejects.toThrow('not Node');
+	});
 });
 
 describe('cursedbelt-server/telemetry', () => {

package/src/server/worker-argon2/_nodeRefuses.ts

@@ -0,0 +1,16 @@
+// Loaded only under Node — the `node` condition of `cursedbelt-server/worker-argon2`.
+//
+// This subpath's two `.wasm` files are STATIC imports, which is the one shape workerd will run
+// (`./argon2.ts`). Node 24 reads the same import through its WebAssembly ESM integration and
+// instantiates the module itself, resolving its imports from a package called `env` — so the
+// real module fails under Node with `ERR_MODULE_NOT_FOUND: Cannot find package 'env'`, deep in
+// `argon2id/dist/no-simd.wasm` (measured by tools/proveInstall.ts publishing 4.24.0, 2026-09-23).
+// Nothing in this generation runs it on Node: a Worker gets it through wrangler (`workerd`
+// resolves `import`), a Mac server through Bun (`bun`), and a Mac server already HAS
+// `Bun.password`. So Node gets this sentence instead. Same shape as `../_bunOnly.ts`.
+throw new Error(
+	"cursedbelt-server/worker-argon2 runs on workerd (through wrangler) and Bun — not Node, which cannot load its static `.wasm` imports. " +
+		"A Node server should hash with a native argon2 (`@node-rs/argon2`).",
+);
+
+export {};