cursedbelt-server 4.24.1 → 4.26.0

package/dist/server/master-lock/attempts.js

@@ -0,0 +1,108 @@
+/**
+ * The master lock's guess throttle, CHARGED before the verify — and, on a Worker, in D1.
+ *
+ * ── 🔴 Why this file exists (task 2137, 2026-09-23) ─────────────────────────
+ * `MasterLock.unlock` used to read its failure count, run the argon2id verify (~0.3–1.4 s on a
+ * Worker), and write the count AFTER it. Every guess that arrived during one verify was judged
+ * against the same count — so a 12-wide burst was verified whole, where the schedule allows
+ * six before the first wait. On `collections`' Worker it was worse: the count lived in a JSON
+ * blob snapshotted per request, so the twelve each wrote `failures + 1` over one another and
+ * the burst was RECORDED as one guess. The same blob holds the open unlocks, so a failed guess
+ * settling after the owner's unlock could also drop his fresh session.
+ *
+ * `charge` is the one operation that closes it: check the window AND, when it is open, charge
+ * a failure in the same step, before anything slow happens. A correct verifier then `clear`s
+ * the run; the one outcome that was not a guess at all — every stored hash unparsable — is
+ * `refund`ed. Everything else, a verify that throws included, stays charged: fail closed.
+ *
+ * Two ledgers satisfy it:
+ *  · the lock's own fields — synchronous, so atomic within one process (the Mac's daemons);
+ *  · {@link createD1MasterLockAttempts} — one conditional UPSERT … RETURNING, atomic because D1
+ *    runs one statement at a time, for a Worker whose lock is rebuilt on every request.
+ *
+ * A windowed refusal charges nothing — the delay throttles the RATE of guesses; it is not
+ * itself one (the same rule `apps/vault`'s unlock guard keeps).
+ */
+import { delayAfter, windowRemaining } from "cursedbelt-core/master-lock";
+/** The `meta`-style row a D1 ledger keeps its count in, beside the lock's record and state. */
+export 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 function masterLockDelaySql(count) {
+    const cap = delayAfter(Number.MAX_SAFE_INTEGER);
+    const arms = [];
+    for (let n = 0; delayAfter(n) < cap && n < 256; n++)
+        arms.push(`WHEN ${count} <= ${n} THEN ${delayAfter(n)}`);
+    return `(CASE ${arms.join(" ")} ELSE ${cap} END)`;
+}
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** One field of the stored JSON, 0 for a missing or unreadable row — never a throw that
+ *  would leave the owner facing a lock nothing can open. */
+const field = (column, name) => `COALESCE(CASE WHEN json_valid(${column}) THEN json_extract(${column}, '$.${name}') END, 0)`;
+function parseCount(raw) {
+    try {
+        const parsed = JSON.parse(raw ?? "");
+        const failures = Number(parsed.failures);
+        const lastFailureAt = Number(parsed.lastFailureAt);
+        return {
+            failures: Number.isFinite(failures) ? failures : 0,
+            lastFailureAt: Number.isFinite(lastFailureAt) ? lastFailureAt : 0,
+        };
+    }
+    catch {
+        return { failures: 0, lastFailureAt: 0 };
+    }
+}
+/**
+ * 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 function createD1MasterLockAttempts(db, options = {}) {
+    const table = options.table ?? "meta";
+    if (!IDENTIFIER.test(table))
+        throw new Error(`master lock attempts: "${table}" is not a table name`);
+    const key = options.key ?? MASTER_LOCK_ATTEMPTS_KEY;
+    let known = parseCount(options.snapshot);
+    const value = `${table}.value`;
+    return {
+        retryAfterMs: (now) => windowRemaining(known.failures, known.lastFailureAt, now),
+        async charge(now) {
+            // ONE statement: the row is created at 1, or incremented only WHERE the window its own
+            // count implies has passed. A refused guess matches no row, so RETURNING is empty.
+            const charged = await db
+                .prepare(`INSERT INTO ${table} (key, value) VALUES (?1, json_object('failures', 1, 'lastFailureAt', ?2))
+					 ON CONFLICT(key) DO UPDATE SET value = json_object(
+					   'failures', ${field(value, "failures")} + 1, 'lastFailureAt', ?2)
+					 WHERE ${field(value, "lastFailureAt")} + ${masterLockDelaySql(field(value, "failures"))} <= ?2
+					 RETURNING value`)
+                .bind(key, now)
+                .first();
+            if (charged) {
+                known = parseCount(charged.value);
+                return { admitted: true, failures: known.failures };
+            }
+            const row = await db.prepare(`SELECT value FROM ${table} WHERE key = ?`).bind(key).first();
+            known = parseCount(row?.value);
+            return { admitted: false, retryAfterMs: Math.max(1, windowRemaining(known.failures, known.lastFailureAt, now)) };
+        },
+        async refund() {
+            await db
+                .prepare(`UPDATE ${table} SET value = json_object(
+					   'failures', MAX(${field("value", "failures")} - 1, 0), 'lastFailureAt', ${field("value", "lastFailureAt")})
+					 WHERE key = ?`)
+                .bind(key)
+                .run();
+            known = { ...known, failures: Math.max(0, known.failures - 1) };
+        },
+        async clear() {
+            await db.prepare(`DELETE FROM ${table} WHERE key = ?`).bind(key).run();
+            known = { failures: 0, lastFailureAt: 0 };
+        },
+    };
+}

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

@@ -24,6 +24,7 @@ export { MASTER_LOCK_ACCOUNTS_PAGE_PATHS, MASTER_LOCK_ACCOUNTS_SCRIPT, MASTER_LO
 export { MASTER_LOCK_CSP, type MasterLockGuard, type MasterLockGuardOptions, createMasterLockGuard, } from "./guard.js";
 export { LOCK_SCRIPT, LOCK_STYLE, MASTER_LOCK_DERIVE_SOURCE, type LockPageOptions, lockPageHtml, } from "./lockPage.js";
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, type MasterLockDirectoryOptions, masterLockPrincipalKey, } from "./principals.js";
+export { MASTER_LOCK_ATTEMPTS_KEY, type MasterLockAttempts, createD1MasterLockAttempts, } from "./attempts.js";
 export { FIRST_ACCOUNT_ID, MasterLock, type MasterLockAccount, type MasterLockAddAccountResult, type MasterLockEnrollResult, type MasterLockOptions, type MasterLockRecord, type MasterLockStore, type MasterLockUnlockResult, readRecord, } from "./masterLock.js";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, type MintMasterLockSeedOptions, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed.js";
 export { MASTER_LOCK_SETTING_KEY, MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store.js";

package/dist/server/master-lock/index.js

@@ -24,6 +24,7 @@ export { MASTER_LOCK_ACCOUNTS_PAGE_PATHS, MASTER_LOCK_ACCOUNTS_SCRIPT, MASTER_LO
 export { MASTER_LOCK_CSP, createMasterLockGuard, } from "./guard.js";
 export { LOCK_SCRIPT, LOCK_STYLE, MASTER_LOCK_DERIVE_SOURCE, lockPageHtml, } from "./lockPage.js";
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, masterLockPrincipalKey, } from "./principals.js";
+export { MASTER_LOCK_ATTEMPTS_KEY, createD1MasterLockAttempts, } from "./attempts.js";
 export { FIRST_ACCOUNT_ID, MasterLock, readRecord, } from "./masterLock.js";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed.js";
 export { MASTER_LOCK_SETTING_KEY, MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store.js";

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

@@ -1,4 +1,5 @@
 import { type MasterLockAccountSummary, type MasterLockKdfParams, type MasterLockStatus } from "cursedbelt-core/master-lock";
+import type { MasterLockAttempts } from "./attempts.js";
 /**
  * ONE master password, and therefore one TENANT of the app behind it.
  *
@@ -115,6 +116,13 @@ export interface MasterLockOptions {
      * the store has nothing.
      */
     seedJson?: string | null;
+    /**
+     * Where the guess throttle is CHARGED. Omitted, it is this instance's own count — atomic
+     * within one process, which is all the Mac's daemons are. 🔴 Required wherever the lock is
+     * rebuilt per request (a Worker): pass `createD1MasterLockAttempts`, or K guesses landing
+     * inside one argon2id verify are judged against one stale count (task 2137, `./attempts.ts`).
+     */
+    attempts?: MasterLockAttempts;
     /** Injected clock. The tests drive it; production omits it. */
     now?: () => number;
     /**
@@ -201,6 +209,8 @@ export declare class MasterLock {
     private expiryTimer;
     private failures;
     private lastFailureAt;
+    /** See {@link MasterLockOptions.attempts}. */
+    private readonly attempts;
     constructor(options: MasterLockOptions);
     /** Is any master password set at all? An app with `false` here admits nobody, and
      *  offers the choose-a-password form instead. */
@@ -302,6 +312,11 @@ export declare class MasterLock {
      * conclusion for its per-file keys in 2026-08-14; this is that reasoning, kept.)
      */
     unlock(verifier: string): Promise<MasterLockUnlockResult>;
+    /**
+     * The default ledger: this instance's own fields, persisted with the live state. `charge`
+     * has no `await` between its check and its increment, so within one process it is atomic.
+     */
+    private ownAttempts;
     /**
      * Mint a token for one account and start its idle clock. The one place a session is
      * created, so `unlock` and `enroll` cannot disagree about what an unlock is.

package/dist/server/master-lock/masterLock.js

@@ -93,9 +93,12 @@ export class MasterLock {
     expiryTimer = null;
     failures = 0;
     lastFailureAt = 0;
+    /** See {@link MasterLockOptions.attempts}. */
+    attempts;
     constructor(options) {
         this.store = options.store;
         this.stateStore = options.state ?? null;
+        this.attempts = options.attempts ?? this.ownAttempts();
         this.loadState();
         this.now = options.now ?? Date.now;
         this.onLockedChange = options.onLockedChange;
@@ -199,7 +202,7 @@ export class MasterLock {
             kdf: this.kdf,
             idleMs: this.idleMs,
             remainingMs: this.remainingMs,
-            retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, this.now()),
+            retryAfterMs: this.attempts.retryAfterMs(this.now()),
             accountId: account?.id ?? null,
             accountLabel: account?.label ?? null,
         };
@@ -284,13 +287,16 @@ export class MasterLock {
      */
     async unlock(verifier) {
         const now = this.now();
-        const retryAfterMs = windowRemaining(this.failures, this.lastFailureAt, now);
         const record = this.record;
+        // 🔴 CHARGED before anything slow happens — see `./attempts.ts`. A guess that lands while
+        // another is inside its argon2id verify sees that one already counted.
+        const charge = await this.attempts.charge(now);
         // The equalizing verify happens first and unconditionally. `verifier` may be empty
         // or absurd; `verify` neither throws on that nor tells us anything, which is the point.
+        // A throw anywhere past the charge leaves it charged: the attempt fails closed.
         let opened = null;
         let unparsable = 0;
-        if (retryAfterMs === 0 && record) {
+        if (charge.admitted && record) {
             for (const account of record.accounts) {
                 const genuine = await verifyArgon(verifier, account.verifierHash);
                 // `null` is a hash this build cannot parse. It is NOT a wrong password, and
@@ -303,20 +309,47 @@ export class MasterLock {
             }
         }
         await equalize(verifier);
-        if (retryAfterMs > 0)
-            return { ok: false, retryAfterMs };
+        if (!charge.admitted)
+            return { ok: false, retryAfterMs: charge.retryAfterMs };
         if (!opened) {
             if (unparsable > 0 && unparsable === (record?.accounts.length ?? 0)) {
+                // Nothing was verified, so nothing was guessed: the charge goes back.
+                await this.attempts.refund();
                 this.log("🔴 master lock: every stored verifier hash is unparsable — nothing can unlock");
                 return { ok: false, retryAfterMs: 0 };
             }
-            this.failures += 1;
-            this.lastFailureAt = now;
-            this.saveState();
-            return { ok: false, retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, now) };
+            return { ok: false, retryAfterMs: windowRemaining(charge.failures, now, now) };
         }
+        await this.attempts.clear();
         return { ok: true, ...this.open(opened.id, now) };
     }
+    /**
+     * The default ledger: this instance's own fields, persisted with the live state. `charge`
+     * has no `await` between its check and its increment, so within one process it is atomic.
+     */
+    ownAttempts() {
+        return {
+            retryAfterMs: (now) => windowRemaining(this.failures, this.lastFailureAt, now),
+            charge: (now) => {
+                const wait = windowRemaining(this.failures, this.lastFailureAt, now);
+                if (wait > 0)
+                    return { admitted: false, retryAfterMs: wait };
+                this.failures += 1;
+                this.lastFailureAt = now;
+                this.saveState();
+                return { admitted: true, failures: this.failures };
+            },
+            refund: () => {
+                this.failures = Math.max(0, this.failures - 1);
+                this.saveState();
+            },
+            clear: () => {
+                this.failures = 0;
+                this.lastFailureAt = 0;
+                this.saveState();
+            },
+        };
+    }
     /**
      * Mint a token for one account and start its idle clock. The one place a session is
      * created, so `unlock` and `enroll` cannot disagree about what an unlock is.
@@ -380,6 +413,7 @@ export class MasterLock {
             createdAt: now,
         };
         this.write({ kdf: input.kdf, idleMs: clampIdleMs(this.record?.idleMs), accounts: [account] });
+        await this.attempts.clear();
         this.log("master lock: a first master password was chosen");
         return { ok: true, ...this.open(account.id, now) };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.24.1",
+	"version": "4.26.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;
 }