cursedbelt-server 4.24.1 → 4.26.0

package/README.md

@@ -57,6 +57,22 @@ the Worker's `fetch` gives `Bun.password` to the auth code, backed by `argon2id`
 files as static imports that wrangler bundles from `node_modules`. No wrangler rule and no local
 `.wasm` declaration are needed. `src/server/worker-argon2/argon2.ts` has the measurements.
 
+## 🔴 A login throttle on a Worker: `cursedbelt-server/login-throttle/durable`
+
+`createLoginThrottle()` remembers in memory, and a Worker's memory is one isolate — per colo,
+several per colo, wiped by every deploy — so a Worker's sign-in keeps its ledger in the
+`LoginThrottleObject` Durable Object and asks it through `createRemoteLoginThrottle(env.<BINDING>,
+{ ledger, fallback })`, gating with `attempt` (check and charge in one step, so a concurrent burst
+cannot share one count). `src/server/auth/loginThrottleDurable.ts` has the why and the wiring.
+
+## 🔴 A master lock on a Worker: `attempts: createD1MasterLockAttempts(db)`
+
+A Worker rebuilds `MasterLock` per request, so its guess throttle must be CHARGED where every
+request can see it, before the argon2id verify — or a burst landing inside one verify is judged
+against one stale count (task 2137). Pass `attempts: createD1MasterLockAttempts(db, { snapshot })`
+(one conditional UPSERT … RETURNING on the `meta` row `master_lock:attempts`).
+`src/server/master-lock/attempts.ts` has the why.
+
 ## Standards
 
 `docs/retention.md`, `docs/activity.md`, `docs/notifications.md`, `docs/engagement.md` — the

package/dist/server/auth/loginThrottle.d.ts

@@ -45,6 +45,25 @@
  * global counter keeps working after eviction, which is precisely the case where it
  * matters most.
  *
+ * 🔴 **"Per-process" is one ISOLATE on a Cloudflare Worker, and that is not a process.**
+ * Cloudflare runs an isolate per colo (often several), discards them without warning and
+ * builds a fresh one on every deploy, so a module-scope throttle there is global to one
+ * isolate only: a guesser reaching N isolates gets N × `globalThreshold` free failures,
+ * and one built per REQUEST has no memory at all (patterns' Worker until 2026-09-23). A
+ * Worker keeps its ledger in a Durable Object instead — `./loginThrottleDurable.ts`
+ * (`cursedbelt-server/login-throttle/durable`), which serves THIS algorithm from one
+ * named object and persists it, so every isolate and every colo meets the same counts.
+ *
+ * ── `attempt`, not `check` then `recordFailure` ─────────────────────────────
+ * `check` → verify → `recordFailure` has a gap exactly as long as the verify: argon2id,
+ * hundreds of ms. Every request that arrives inside it reads the same count, so K
+ * concurrent guesses are all admitted and the counter learns of them afterwards — the
+ * throttle limits guesses per BURST, and the burst is as wide as the attacker's
+ * concurrency. `attempt` closes the gap: it checks and, when admitted, charges a
+ * failure in the same synchronous step, so the (threshold+1)th concurrent request is
+ * refused. A success then clears the charge (`recordSuccess`), and a failure needs no
+ * second call. The Durable Object serves `attempt` as one operation for the same reason.
+ *
  * Pair with the coarse per-IP `createRateLimiter` (`../middleware/rateLimit`); this is
  * the strict per-identity layer.
  */
@@ -73,6 +92,26 @@ export interface LoginThrottleOptions {
     windowMs?: number;
     /** Hard cap on tracked keys, so the table cannot be a memory vector. Default 4096. */
     maxKeys?: number;
+    /**
+     * Start from a persisted {@link LoginThrottle.snapshot} rather than empty — how a Durable
+     * Object (`./loginThrottleDurable.ts`) survives its own eviction. An unreadable snapshot
+     * (wrong version, wrong shape) starts EMPTY for the keys and is ignored, never thrown on.
+     */
+    restore?: LoginThrottleSnapshot | null;
+}
+/** One key's (or the global counter's) ledger line — the unit {@link LoginThrottleSnapshot} holds. */
+export interface LoginThrottleEntry {
+    failures: number;
+    /** When the current lockout ends; 0 when not locked. */
+    lockedUntil: number;
+    lastSeen: number;
+}
+/** A throttle's whole state as plain data, for a store that outlives the throttle. */
+export interface LoginThrottleSnapshot {
+    v: 1;
+    global: LoginThrottleEntry;
+    /** Most recently seen first, `[normalizedKey, entry]`. */
+    entries: Array<[string, LoginThrottleEntry]>;
 }
 export type ThrottleVerdict = {
     allowed: true;
@@ -84,6 +123,13 @@ export type ThrottleVerdict = {
 export interface LoginThrottle {
     /** May this key attempt a login right now? */
     check(key: string): ThrottleVerdict;
+    /**
+     * `check`, and when allowed, charge a failure in the SAME step — so concurrent attempts
+     * cannot all be admitted against one count. Follow an allowed attempt with
+     * `recordSuccess` when the credential was right; a wrong one needs no further call.
+     * See the header's `attempt` section.
+     */
+    attempt(key: string): ThrottleVerdict;
     /** Record a failed attempt. Returns the verdict the NEXT attempt would get. */
     recordFailure(key: string): ThrottleVerdict;
     /** Record a success — clears this key and the global counter. */
@@ -92,7 +138,23 @@ export interface LoginThrottle {
     reset(key: string): void;
     /** Tracked-key count, for the bounded-growth test. */
     readonly size: number;
+    /** The state as plain data — the `limit` most recently seen keys (default all) and the global counter. */
+    snapshot(limit?: number): LoginThrottleSnapshot;
+}
+/**
+ * The same ledger across a round trip — `createRemoteLoginThrottle` in
+ * `./loginThrottleDurable.ts`. A door that awaits every call takes either shape:
+ * {@link LoginThrottleLike}.
+ */
+export interface AsyncLoginThrottle {
+    check(key: string): Promise<ThrottleVerdict>;
+    attempt(key: string): Promise<ThrottleVerdict>;
+    recordFailure(key: string): Promise<ThrottleVerdict>;
+    recordSuccess(key: string): Promise<void>;
+    reset(key: string): Promise<void>;
 }
+/** What a sign-in handler should accept: the in-process throttle or the Durable Object's. */
+export type LoginThrottleLike = LoginThrottle | AsyncLoginThrottle;
 /**
  * The client address to key on — the LAST `X-Forwarded-For` entry (what our proxy
  * saw), falling back to `X-Real-IP`, the socket peer, and finally a shared constant.

package/dist/server/auth/loginThrottle.js

@@ -45,6 +45,25 @@
  * global counter keeps working after eviction, which is precisely the case where it
  * matters most.
  *
+ * 🔴 **"Per-process" is one ISOLATE on a Cloudflare Worker, and that is not a process.**
+ * Cloudflare runs an isolate per colo (often several), discards them without warning and
+ * builds a fresh one on every deploy, so a module-scope throttle there is global to one
+ * isolate only: a guesser reaching N isolates gets N × `globalThreshold` free failures,
+ * and one built per REQUEST has no memory at all (patterns' Worker until 2026-09-23). A
+ * Worker keeps its ledger in a Durable Object instead — `./loginThrottleDurable.ts`
+ * (`cursedbelt-server/login-throttle/durable`), which serves THIS algorithm from one
+ * named object and persists it, so every isolate and every colo meets the same counts.
+ *
+ * ── `attempt`, not `check` then `recordFailure` ─────────────────────────────
+ * `check` → verify → `recordFailure` has a gap exactly as long as the verify: argon2id,
+ * hundreds of ms. Every request that arrives inside it reads the same count, so K
+ * concurrent guesses are all admitted and the counter learns of them afterwards — the
+ * throttle limits guesses per BURST, and the burst is as wide as the attacker's
+ * concurrency. `attempt` closes the gap: it checks and, when admitted, charges a
+ * failure in the same synchronous step, so the (threshold+1)th concurrent request is
+ * refused. A success then clears the charge (`recordSuccess`), and a failure needs no
+ * second call. The Durable Object serves `attempt` as one operation for the same reason.
+ *
  * Pair with the coarse per-IP `createRateLimiter` (`../middleware/rateLimit`); this is
  * the strict per-identity layer.
  */
@@ -98,6 +117,16 @@ export function clientKeyOfContext(req, env) {
     }
     return clientKeyOf(req, address);
 }
+/** A persisted entry is trusted only as far as its three numbers are finite. */
+const readEntry = (raw) => {
+    const e = raw;
+    if (!e || typeof e !== 'object')
+        return null;
+    const { failures, lockedUntil, lastSeen } = e;
+    if (![failures, lockedUntil, lastSeen].every((n) => typeof n === 'number' && Number.isFinite(n)))
+        return null;
+    return { failures: failures, lockedUntil: lockedUntil, lastSeen: lastSeen };
+};
 /**
  * Keys are compared case- and whitespace-insensitively.
  *
@@ -119,6 +148,21 @@ export function createLoginThrottle(options = {}) {
     const maxKeys = options.maxKeys ?? 4096;
     const attempts = new Map();
     const global = { failures: 0, lockedUntil: 0, lastSeen: 0 };
+    const restored = options.restore;
+    if (restored && restored.v === 1) {
+        const g = readEntry(restored.global);
+        if (g)
+            Object.assign(global, g);
+        // Oldest first, so the Map's insertion order matches what it would have been live.
+        const entries = Array.isArray(restored.entries) ? [...restored.entries].reverse() : [];
+        for (const pair of entries) {
+            if (!Array.isArray(pair) || typeof pair[0] !== 'string')
+                continue;
+            const entry = readEntry(pair[1]);
+            if (entry)
+                attempts.set(normalizeKey(pair[0]), entry);
+        }
+    }
     /** Delay for the nth failure past a threshold: base·2^(n-1), capped. */
     const delayFor = (failures, limit, cap) => {
         const past = failures - limit;
@@ -162,10 +206,18 @@ export function createLoginThrottle(options = {}) {
         }
         return { allowed: true };
     };
-    return {
+    const api = {
         check(key) {
             return verdict(key, now());
         },
+        attempt(key) {
+            const gate = verdict(key, now());
+            if (!gate.allowed)
+                return gate;
+            // Charged BEFORE the caller verifies anything — see the header's `attempt` section.
+            api.recordFailure(key);
+            return gate;
+        },
         recordFailure(rawKey) {
             const key = normalizeKey(rawKey);
             const nowMs = now();
@@ -200,5 +252,15 @@ export function createLoginThrottle(options = {}) {
         get size() {
             return attempts.size;
         },
+        snapshot(limit) {
+            const byRecency = [...attempts.entries()].sort((a, b) => b[1].lastSeen - a[1].lastSeen);
+            const kept = limit === undefined ? byRecency : byRecency.slice(0, Math.max(0, limit));
+            return {
+                v: 1,
+                global: { ...global },
+                entries: kept.map(([key, entry]) => [key, { ...entry }]),
+            };
+        },
     };
+    return api;
 }

package/dist/server/auth/loginThrottleDurable.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { type AsyncLoginThrottle, type LoginThrottle, type LoginThrottleOptions } from './loginThrottle.js';
+/** The name every isolate addresses unless told otherwise — one object, one ledger set. */
+export declare 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 declare const LOGIN_THROTTLE_OPERATIONS: readonly [readonly ["POST", "/throttle/check"], readonly ["POST", "/throttle/attempt"], readonly ["POST", "/throttle/fail"], readonly ["POST", "/throttle/ok"], readonly ["POST", "/throttle/reset"]];
+/**
+ * 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 declare const PERSISTED_KEYS = 1024;
+/** 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>;
+    };
+}
+/**
+ * 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 declare class LoginThrottleObject {
+    private readonly ledgers;
+    private readonly storage;
+    private readonly options;
+    /**
+     * `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);
+    /**
+     * 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;
+    private persist;
+    fetch(request: Request): Promise<Response>;
+}
+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 declare function createRemoteLoginThrottle(namespace: DurableNamespaceLike, options?: RemoteLoginThrottleOptions): AsyncLoginThrottle;

package/dist/server/auth/loginThrottleDurable.js

@@ -0,0 +1,231 @@
+/**
+ * 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, } 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'],
+];
+/**
+ * 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;
+const json = (value, status = 200) => 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 {
+    ledgers = new Map();
+    storage;
+    options;
+    /**
+     * `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, _env, options = {}) {
+        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.
+     */
+    ledger(name) {
+        let loading = this.ledgers.get(name);
+        if (!loading) {
+            loading = this.storage
+                .get(`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;
+    }
+    persist(name, throttle) {
+        return this.storage.put(`ledger:${name}`, throttle.snapshot(PERSISTED_KEYS));
+    }
+    async fetch(request) {
+        const path = new URL(request.url).pathname;
+        if (request.method !== 'POST')
+            return json({ error: `${request.method} ${path}: POST only` }, 405);
+        let body;
+        try {
+            body = (await request.json());
+        }
+        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);
+        }
+    }
+}
+/**
+ * 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, options = {}) {
+    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) => console.error(line));
+    const call = async (path, key) => {
+        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());
+    };
+    /** Ask the object; on failure, let the fallback answer (or rethrow when there is none). */
+    const remote = async (path, key, local) => {
+        try {
+            return await call(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('/throttle/check', key, fallback && (() => fallback.check(key))),
+        async attempt(key) {
+            let mirrored = false;
+            const verdict = await remote('/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('/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('/throttle/ok', key, fallback && (() => null));
+        },
+        async reset(key) {
+            fallback?.reset(key);
+            await remote('/throttle/reset', key, fallback && (() => null));
+        },
+    };
+}

package/dist/server/master-lock/attempts.d.ts

@@ -0,0 +1,42 @@
+import type { D1LikeDatabase } from "../d1/types.js";
+/** What {@link MasterLockAttempts.charge} answers: admitted (and charged), or not (and not). */
+export type MasterLockCharge = {
+    admitted: true;
+    failures: number;
+} | {
+    admitted: false;
+    retryAfterMs: number;
+};
+export interface MasterLockAttempts {
+    /** What the ledger last knew, for the lock page's countdown. Never a decision. */
+    retryAfterMs(now: number): number;
+    /**
+     * 🔴 CHECK AND CHARGE in one step. Admitted → one failure is already charged, and
+     * `failures` counts it. Refused → nothing charged; `retryAfterMs` is the wait.
+     */
+    charge(now: number): MasterLockCharge | Promise<MasterLockCharge>;
+    /** The charged attempt was not a guess (nothing could be verified): take it back. */
+    refund(): void | Promise<void>;
+    /** A correct verifier: the run is over. */
+    clear(): void | Promise<void>;
+}
+/** The `meta`-style row a D1 ledger keeps its count in, beside the lock's record and state. */
+export declare const MASTER_LOCK_ATTEMPTS_KEY = "master_lock:attempts";
+/**
+ * `delayAfter` as a SQL `CASE` over a failure-count expression — GENERATED from the function,
+ * so the statement that admits a guess and the schedule the specs pin cannot disagree.
+ */
+export declare function masterLockDelaySql(count: string): string;
+/**
+ * The ledger over a D1 key/value table (`key TEXT PRIMARY KEY, value TEXT`) — `meta` by default,
+ * the table a Worker port already keeps the lock's record in, so it needs no migration.
+ *
+ * Its writes are AWAITED, never queued on a per-invocation collector: a charge that lands after
+ * the verify is the bug this exists to close. `snapshot` is the row as the request's own snapshot
+ * read it, for {@link MasterLockAttempts.retryAfterMs}; every decision reads D1 itself.
+ */
+export declare function createD1MasterLockAttempts(db: D1LikeDatabase, options?: {
+    table?: string;
+    key?: string;
+    snapshot?: string | null;
+}): MasterLockAttempts;