cursedbelt-server 4.24.1 → 4.25.0

package/README.md

@@ -57,6 +57,14 @@ 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.
+
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.24.1",
+	"version": "4.25.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -173,6 +173,12 @@
 			"source": "./src/server/auth/loginThrottle.ts",
 			"import": "./dist/server/auth/loginThrottle.js"
 		},
+		"./login-throttle/durable": {
+			"types": "./dist/server/auth/loginThrottleDurable.d.ts",
+			"bun": "./src/server/auth/loginThrottleDurable.ts",
+			"source": "./src/server/auth/loginThrottleDurable.ts",
+			"import": "./dist/server/auth/loginThrottleDurable.js"
+		},
 		"./maps-budget": {
 			"types": "./dist/server/maps-budget/mapsBudget.d.ts",
 			"bun": "./src/server/maps-budget/mapsBudget.ts",

package/src/leafSubpathsImportNothing.spec.ts

@@ -124,6 +124,16 @@ const LEAVES = [
     /** The failed-login backoff. Every app with a login door; shipped as 2.5.1. */
     evaluates: 'createLoginThrottle',
   },
+  {
+    subpath: './login-throttle/durable',
+    /**
+     * The throttle's Durable Object and its client — a Worker's ledger shared by every isolate
+     * (4.25.0, patterns task 2136). It runs on `workerd`, so it may import nothing but the
+     * throttle it serves; its types for the object's state and namespace are structural.
+     */
+    evaluates: 'createRemoteLoginThrottle',
+    siblings: ['src/server/auth/loginThrottle.ts'],
+  },
   {
     subpath: './binary-store',
     /**

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

@@ -211,3 +211,85 @@ describe('createLoginThrottle', () => {
     expect(t.size).toBe(1);
   });
 });
+
+describe('attempt — check and charge in one step', () => {
+  it('🔴 a burst of concurrent attempts is admitted only up to the threshold', async () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 3, globalThreshold: 1000 });
+    // Every attempt is admitted BEFORE any verify finishes — the shape of K concurrent guesses
+    // each waiting on argon2id. With check-then-recordFailure all ten would pass one stale count.
+    const verdicts = Array.from({ length: 10 }, () => t.attempt('ip'));
+    // Threshold 3 → charges 1–3 free, the 4th arms the delay but is itself admitted (the same
+    // "one extra" the threshold option documents), the 5th onward are refused.
+    expect(verdicts.filter((v) => v.allowed).length).toBe(4);
+    expect(verdicts[4]).toEqual({ allowed: false, scope: 'ip', retryAfterSeconds: 1 });
+  });
+
+  it('a success after an attempt clears the charge', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 1, globalThreshold: 1 });
+    expect(t.attempt('ip').allowed).toBe(true);
+    t.recordSuccess('ip');
+    expect(t.attempt('ip').allowed).toBe(true);
+    t.recordSuccess('ip');
+    expect(t.check('ip')).toEqual({ allowed: true });
+    expect(t.size).toBe(0);
+  });
+
+  it('a refused attempt is not itself charged', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 0, baseDelayMs: 1_000, globalThreshold: 1000 });
+    expect(t.attempt('ip').allowed).toBe(true); // charged: failure 1 → 1 s delay
+    for (let i = 0; i < 5; i++) expect(t.attempt('ip').allowed).toBe(false);
+    c.advance(1_000);
+    // Still failure 1's delay that just elapsed — not 2^5 s from five refused attempts.
+    expect(t.attempt('ip').allowed).toBe(true);
+  });
+});
+
+describe('snapshot / restore', () => {
+  it('a throttle restored from a snapshot enforces what the original had seen', () => {
+    const c = clock();
+    const first = createLoginThrottle({ now: c.now, threshold: 2, globalThreshold: 1000 });
+    for (let i = 0; i < 3; i++) first.recordFailure('Attacker');
+    expect(first.check('attacker').allowed).toBe(false);
+    const snap = JSON.parse(JSON.stringify(first.snapshot()));
+    const second = createLoginThrottle({ now: c.now, threshold: 2, globalThreshold: 1000, restore: snap });
+    expect(second.check('attacker').allowed).toBe(false);
+    expect(second.check('someone-else').allowed).toBe(true);
+    // The count carries on rather than restarting.
+    c.advance(10_000);
+    const next = second.recordFailure('attacker');
+    expect(next.allowed).toBe(false);
+    if (!next.allowed) expect(next.retryAfterSeconds).toBe(2);
+  });
+
+  it('keeps the global counter, and only the most recent keys under a limit', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, globalThreshold: 3 });
+    for (let i = 0; i < 5; i++) {
+      c.advance(1);
+      t.recordFailure(`ip-${i}`);
+    }
+    const snap = t.snapshot(2);
+    expect(snap.entries.map(([k]) => k)).toEqual(['ip-4', 'ip-3']);
+    expect(snap.global.failures).toBe(5);
+    const restored = createLoginThrottle({ now: c.now, globalThreshold: 3, restore: snap });
+    const v = restored.check('a-new-ip');
+    expect(v.allowed).toBe(false);
+    if (!v.allowed) expect(v.scope).toBe('global');
+  });
+
+  it('an unreadable snapshot starts empty rather than throwing', () => {
+    const bad = [
+      { v: 2, global: { failures: 99, lockedUntil: 9e15, lastSeen: 0 }, entries: [] },
+      { v: 1, global: { failures: 'x' }, entries: [['k', { failures: null }], 'junk'] },
+      { v: 1, global: null, entries: null },
+    ];
+    for (const restore of bad) {
+      const t = createLoginThrottle({ restore: restore as never });
+      expect(t.check('k')).toEqual({ allowed: true });
+      expect(t.size).toBe(0);
+    }
+  });
+});

package/src/server/auth/loginThrottle.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.
  */
@@ -74,6 +93,28 @@ 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 =
@@ -83,6 +124,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. */
@@ -91,8 +139,26 @@ 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.
@@ -142,12 +208,16 @@ export function clientKeyOfContext(req: Request, env: unknown): string {
   return clientKeyOf(req, address);
 }
 
-interface Attempt {
-  failures: number;
-  /** When the current lockout ends; 0 when not locked. */
-  lockedUntil: number;
-  lastSeen: number;
-}
+type Attempt = LoginThrottleEntry;
+
+/** A persisted entry is trusted only as far as its three numbers are finite. */
+const readEntry = (raw: unknown): Attempt | null => {
+  const e = raw as Partial<Attempt> | null | undefined;
+  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 as number, lockedUntil: lockedUntil as number, lastSeen: lastSeen as number };
+};
 
 /**
  * Keys are compared case- and whitespace-insensitively.
@@ -172,6 +242,18 @@ export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginTh
 
   const attempts = new Map<string, Attempt>();
   const global: Attempt = { 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: number, limit: number, cap: number): number => {
@@ -215,11 +297,19 @@ export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginTh
     return { allowed: true };
   };
 
-  return {
+  const api: LoginThrottle = {
     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();
@@ -257,5 +347,16 @@ export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginTh
     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/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));
+    },
+  };
+}