cursedbelt-server 4.24.1 → 4.26.0

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

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'bun:test';
+import { createLoginThrottle } from './loginThrottle.js';
+import {
+  createRemoteLoginThrottle,
+  type DurableNamespaceLike,
+  type DurableStorageLike,
+  LOGIN_THROTTLE_OPERATIONS,
+  LoginThrottleObject,
+} from './loginThrottleDurable.js';
+
+/** A Durable Object's storage, as a Map that survives the object — which is what storage is for. */
+const memoryStorage = (): DurableStorageLike & { data: Map<string, unknown> } => {
+  const data = new Map<string, unknown>();
+  return {
+    data,
+    // Structured clone, as the runtime does — an object that kept a live reference would pass
+    // a persistence test without persisting anything.
+    get: async <T>(key: string) => (data.has(key) ? (structuredClone(data.get(key)) as T) : undefined),
+    put: async (key, value) => {
+      data.set(key, structuredClone(value));
+    },
+  };
+};
+
+const clock = (start = 5_000_000) => {
+  let t = start;
+  return { now: () => t, advance: (ms: number) => (t += ms) };
+};
+
+/** A namespace whose ONE object can be swapped — `evict()` is the platform recycling it. */
+const namespaceOver = (storage: DurableStorageLike, now: () => number) => {
+  let object = new LoginThrottleObject({ storage }, {}, { now, threshold: 2, globalThreshold: 4 });
+  const ns: DurableNamespaceLike & { evict(): void; calls: number } = {
+    calls: 0,
+    idFromName: (name) => name,
+    get: () => ({
+      fetch: (request: Request) => {
+        ns.calls += 1;
+        return object.fetch(request);
+      },
+    }),
+    evict() {
+      object = new LoginThrottleObject({ storage }, {}, { now, threshold: 2, globalThreshold: 4 });
+    },
+  };
+  return ns;
+};
+
+describe('LoginThrottleObject + createRemoteLoginThrottle', () => {
+  it('🔴 two isolates share ONE ledger — failures in one lock the other', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    // Two isolates: each builds its own client (per request, as a Worker does) over one binding.
+    const isolateA = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    const isolateB = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    for (let i = 0; i < 3; i++) await isolateA.recordFailure('203.0.113.9');
+    const seenByB = await isolateB.check('203.0.113.9');
+    expect(seenByB.allowed).toBe(false);
+    // …and the per-isolate version of the same thing does not, which is the bug this replaces.
+    const perIsolateA = createLoginThrottle({ now: c.now, threshold: 2 });
+    const perIsolateB = createLoginThrottle({ now: c.now, threshold: 2 });
+    for (let i = 0; i < 3; i++) perIsolateA.recordFailure('203.0.113.9');
+    expect(perIsolateB.check('203.0.113.9').allowed).toBe(true);
+  });
+
+  it('🔴 the ledger survives the object being evicted and rebuilt over the same storage', async () => {
+    const c = clock();
+    const storage = memoryStorage();
+    const ns = namespaceOver(storage, c.now);
+    const t = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    for (let i = 0; i < 3; i++) await t.recordFailure('192.0.2.44');
+    ns.evict();
+    expect((await t.check('192.0.2.44')).allowed).toBe(false);
+    // The global counter too: a fifth failure from anywhere arms the global delay (threshold 4).
+    await t.recordFailure('198.51.100.1');
+    ns.evict();
+    await t.recordFailure('198.51.100.2');
+    ns.evict();
+    const v = await t.check('a-fresh-address');
+    expect(v.allowed).toBe(false);
+    if (!v.allowed) expect(v.scope).toBe('global');
+  });
+
+  it('lockout after N failures, and a success clears it everywhere', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    const t = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    // threshold 2: attempts 1–3 admitted (the third arms), the fourth refused.
+    const verdicts = [];
+    for (let i = 0; i < 4; i++) verdicts.push(await t.attempt('ip'));
+    expect(verdicts.map((v) => v.allowed)).toEqual([true, true, true, false]);
+    c.advance(60_000);
+    expect((await t.attempt('ip')).allowed).toBe(true);
+    await t.recordSuccess('ip');
+    expect(await createRemoteLoginThrottle(ns, { ledger: 'owner' }).check('ip')).toEqual({ allowed: true });
+  });
+
+  it('🔴 a concurrent burst is admitted only up to the threshold, not all at once', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    const verdicts = await Promise.all(
+      Array.from({ length: 12 }, () => createRemoteLoginThrottle(ns, { ledger: 'owner' }).attempt('burst')),
+    );
+    expect(verdicts.filter((v) => v.allowed).length).toBe(3);
+  });
+
+  it('ledgers are independent — the probe never spends the owner', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    const probe = createRemoteLoginThrottle(ns, { ledger: 'probe' });
+    const owner = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    for (let i = 0; i < 20; i++) await probe.recordFailure('home');
+    expect((await probe.check('home')).allowed).toBe(false);
+    expect(await owner.attempt('home')).toEqual({ allowed: true });
+  });
+
+  it('an unreachable object degrades to the fallback, which was mirrored all along', async () => {
+    const c = clock();
+    const storage = memoryStorage();
+    const ns = namespaceOver(storage, c.now);
+    const fallback = createLoginThrottle({ now: c.now, threshold: 2, globalThreshold: 4 });
+    const lines: string[] = [];
+    const t = createRemoteLoginThrottle(ns, { ledger: 'owner', fallback, onError: (l) => lines.push(l) });
+    for (let i = 0; i < 3; i++) await t.attempt('ip');
+    // The object goes away. The fallback has seen all three charges, so it refuses the fourth
+    // instead of starting from zero.
+    const broken: DurableNamespaceLike = {
+      idFromName: (n) => n,
+      get: () => ({ fetch: async () => new Response('overloaded', { status: 503 }) }),
+    };
+    const degraded = createRemoteLoginThrottle(broken, { ledger: 'owner', fallback, onError: (l) => lines.push(l) });
+    expect((await degraded.attempt('ip')).allowed).toBe(false);
+    expect(lines.length).toBe(1);
+    expect(lines[0]).toContain('503');
+    // Without a fallback the error is the caller's, never a silent allow.
+    await expect(createRemoteLoginThrottle(broken).check('ip')).rejects.toThrow('503');
+  });
+
+  it('answers exactly LOGIN_THROTTLE_OPERATIONS, and refuses malformed input', async () => {
+    const object = new LoginThrottleObject({ storage: memoryStorage() });
+    const post = (path: string, body: unknown) =>
+      object.fetch(new Request(`https://x.invalid${path}`, { method: 'POST', body: JSON.stringify(body) }));
+    for (const [, path] of LOGIN_THROTTLE_OPERATIONS) {
+      expect([path, (await post(path, { ledger: 'owner', key: 'k' })).status]).toEqual([path, 200]);
+    }
+    expect((await post('/throttle/nope', { ledger: 'owner', key: 'k' })).status).toBe(404);
+    expect((await post('/throttle/check', { ledger: 'Not A Slug', key: 'k' })).status).toBe(400);
+    expect((await post('/throttle/check', { ledger: 'owner', key: 'x'.repeat(321) })).status).toBe(400);
+    expect((await post('/throttle/check', { ledger: 'owner' })).status).toBe(400);
+    expect((await object.fetch(new Request('https://x.invalid/throttle/check'))).status).toBe(405);
+  });
+
+  it('persists a bounded ledger, however many keys it has seen', async () => {
+    const storage = memoryStorage();
+    const object = new LoginThrottleObject({ storage }, {}, { globalThreshold: 1e9, maxKeys: 5000 });
+    const t = createRemoteLoginThrottle(
+      { idFromName: (n) => n, get: () => ({ fetch: (r) => object.fetch(r) }) },
+      { ledger: 'owner' },
+    );
+    for (let i = 0; i < 1100; i++) await t.recordFailure(`10.0.${Math.floor(i / 250)}.${i % 250}`);
+    const saved = storage.data.get('ledger:owner') as { entries: unknown[] };
+    expect(saved.entries.length).toBe(1024);
+    expect(JSON.stringify(saved).length).toBeLessThan(128 * 1024);
+  });
+});

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/master-lock/attempts.spec.ts

@@ -0,0 +1,159 @@
+/**
+ * 🔴 The guess throttle is CHARGED before the verify (task 2137) — a burst of guesses landing
+ * inside one argon2id verify is not judged against one stale count.
+ *
+ * Proved two ways, because the lock has two ledgers: its own fields (one process — the Mac's
+ * daemons, where a burst is K concurrent `unlock` calls on one instance) and a D1 row (a Worker,
+ * where every request builds its own lock over a snapshot and only D1 is shared). Both were run
+ * against the pre-fix `MasterLock` and failed: 12 of 12 verified, and on the per-request shape
+ * the burst was recorded as ONE failure.
+ */
+import { Database } from "bun:sqlite";
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { type MasterLockKdfParams, delayAfter, deriveMasterLockVerifier } from "cursedbelt-core/master-lock";
+import { createRemoteD1 } from "../d1/remote.js";
+import { createFakeD1Binding } from "../d1/fakeD1.js";
+import type { D1LikeDatabase } from "../d1/types.js";
+import { MASTER_LOCK_ATTEMPTS_KEY, createD1MasterLockAttempts, masterLockDelaySql } from "./attempts.js";
+import { MasterLock } from "./masterLock.js";
+import { createMemoryMasterLockStore } from "./store.js";
+
+const KDF: MasterLockKdfParams = { v: 1, alg: "PBKDF2-SHA256", iter: 1, salt: "AAECAwQFBgcICQoLDA0ODw" };
+const BURST = 12;
+/** Five free, and the sixth is evaluated before the first wait — the same as one at a time. */
+const ADMITTED = 6;
+
+let VERIFIER = "";
+let HASH = "";
+let SEED = "";
+beforeAll(async () => {
+	VERIFIER = await deriveMasterLockVerifier("the owner's master password", KDF);
+	HASH = await Bun.password.hash(VERIFIER, { algorithm: "argon2id", memoryCost: 4096, timeCost: 1 });
+	SEED = JSON.stringify({ kdf: KDF, verifierHash: HASH });
+});
+
+/** How many verifies reached the REAL hash — a guess that was evaluated, not refused. */
+const realVerify = Bun.password.verify;
+let evaluated = 0;
+function countEvaluations(): void {
+	evaluated = 0;
+	Bun.password.verify = ((candidate: string, hash: string) => {
+		if (hash === HASH) evaluated += 1;
+		return realVerify(candidate, hash);
+	}) as typeof Bun.password.verify;
+}
+afterEach(() => {
+	Bun.password.verify = realVerify;
+});
+
+function d1(): { db: D1LikeDatabase; sqlite: Database } {
+	const sqlite = new Database(":memory:");
+	sqlite.exec("CREATE TABLE meta ( key TEXT PRIMARY KEY, value TEXT NOT NULL )");
+	return { db: createRemoteD1(createFakeD1Binding(sqlite)), sqlite };
+}
+const stored = (sqlite: Database) =>
+	JSON.parse(
+		(sqlite.query("SELECT value FROM meta WHERE key = ?").get(MASTER_LOCK_ATTEMPTS_KEY) as { value: string } | null)?.value ?? "{}",
+	) as { failures?: number; lastFailureAt?: number };
+
+describe("🔴 a concurrent burst of wrong verifiers", () => {
+	test("one process, one instance: 12 at once → 6 evaluated, the rest refused", async () => {
+		const lock = new MasterLock({ store: createMemoryMasterLockStore(null), seedJson: SEED, now: () => 1_000_000 });
+		countEvaluations();
+		const answers = await Promise.all(Array.from({ length: BURST }, () => lock.unlock("a wrong guess")));
+		expect(answers.every((a) => !a.ok)).toBe(true);
+		expect(evaluated).toBe(ADMITTED);
+		expect(lock.status().retryAfterMs).toBe(delayAfter(ADMITTED));
+	});
+
+	test("a Worker: a fresh lock per request over one D1 → 6 evaluated, and all 6 are RECORDED", async () => {
+		const { db, sqlite } = d1();
+		const store = createMemoryMasterLockStore(null);
+		const state = createMemoryMasterLockStore(null);
+		const now = 1_000_000;
+		const request = () => new MasterLock({ store, state, seedJson: SEED, now: () => now, attempts: createD1MasterLockAttempts(db) });
+		countEvaluations();
+		const answers = await Promise.all(Array.from({ length: BURST }, () => request().unlock("a wrong guess")));
+		expect(answers.every((a) => !a.ok)).toBe(true);
+		expect(evaluated).toBe(ADMITTED);
+		// Recorded = evaluated: never the lost update that counted a burst as one guess.
+		expect(stored(sqlite)).toEqual({ failures: ADMITTED, lastFailureAt: now });
+		// A failed guess no longer rewrites the live state, so it cannot drop an open unlock.
+		expect(state.read()).toBeNull();
+	});
+
+	test("after the window, the owner's ONE correct attempt opens it and ends the run", async () => {
+		const { db, sqlite } = d1();
+		const store = createMemoryMasterLockStore(null);
+		const state = createMemoryMasterLockStore(null);
+		let now = 1_000_000;
+		const request = () => new MasterLock({ store, state, seedJson: SEED, now: () => now, attempts: createD1MasterLockAttempts(db) });
+		await Promise.all(Array.from({ length: BURST }, () => request().unlock("a wrong guess")));
+		// Inside the window the right verifier is refused too — and charges nothing.
+		const early = await request().unlock(VERIFIER);
+		expect(early).toEqual({ ok: false, retryAfterMs: delayAfter(ADMITTED) });
+		expect(stored(sqlite).failures).toBe(ADMITTED);
+		now += delayAfter(ADMITTED);
+		const opened = await request().unlock(VERIFIER);
+		expect(opened.ok).toBe(true);
+		expect(stored(sqlite)).toEqual({});
+		if (opened.ok) expect(request().presents(new Request("http://x/", { headers: { "x-master-lock": opened.token } }))).toBe(true);
+	});
+});
+
+describe("the D1 ledger", () => {
+	test("the SQL schedule IS delayAfter — every count from 0 past the cap", () => {
+		const sqlite = new Database(":memory:");
+		for (let n = 0; n <= 40; n++) {
+			const row = sqlite.query(`SELECT ${masterLockDelaySql("?1")} AS d`).get(n) as { d: number };
+			expect(`${n} → ${row.d}`).toBe(`${n} → ${delayAfter(n)}`);
+		}
+	});
+
+	test("a charge is refused inside the window, admitted after it, and only admitted ones count", async () => {
+		const { db } = d1();
+		const ledger = createD1MasterLockAttempts(db);
+		for (let i = 1; i <= ADMITTED; i++) expect(await ledger.charge(10_000)).toEqual({ admitted: true, failures: i });
+		expect(await ledger.charge(10_000)).toEqual({ admitted: false, retryAfterMs: delayAfter(ADMITTED) });
+		expect(await ledger.charge(10_000 + delayAfter(ADMITTED) - 1)).toEqual({ admitted: false, retryAfterMs: 1 });
+		expect(await ledger.charge(10_000 + delayAfter(ADMITTED))).toEqual({ admitted: true, failures: ADMITTED + 1 });
+	});
+
+	test("refund takes one back; clear ends the run; a snapshot feeds the countdown only", async () => {
+		const { db, sqlite } = d1();
+		const ledger = createD1MasterLockAttempts(db);
+		await ledger.charge(5);
+		await ledger.charge(5);
+		await ledger.refund();
+		expect(stored(sqlite)).toEqual({ failures: 1, lastFailureAt: 5 });
+		await ledger.clear();
+		expect(stored(sqlite)).toEqual({});
+		const snap = JSON.stringify({ failures: ADMITTED, lastFailureAt: 100 });
+		expect(createD1MasterLockAttempts(db, { snapshot: snap }).retryAfterMs(100)).toBe(delayAfter(ADMITTED));
+	});
+
+	test("an unreadable row reads as no failures — never a lock nothing can open", async () => {
+		const { db, sqlite } = d1();
+		sqlite.run("INSERT INTO meta (key, value) VALUES (?, 'not json')", [MASTER_LOCK_ATTEMPTS_KEY]);
+		expect(await createD1MasterLockAttempts(db).charge(1)).toEqual({ admitted: true, failures: 1 });
+	});
+
+	test("🔴 a ledger that cannot charge refuses the unlock — nothing is verified uncharged", async () => {
+		const failing = {
+			retryAfterMs: () => 0,
+			charge: async () => {
+				throw new Error("D1 unavailable");
+			},
+			refund: () => {},
+			clear: () => {},
+		};
+		const lock = new MasterLock({ store: createMemoryMasterLockStore(null), seedJson: SEED, attempts: failing });
+		countEvaluations();
+		await expect(lock.unlock(VERIFIER)).rejects.toThrow("D1 unavailable");
+		expect(evaluated).toBe(0);
+	});
+
+	test("a table name that is not an identifier is refused", () => {
+		expect(() => createD1MasterLockAttempts(d1().db, { table: "meta; DROP TABLE meta" })).toThrow("not a table name");
+	});
+});