cursedbelt-server 4.25.0 → 4.26.0

package/README.md

@@ -65,6 +65,14 @@ several per colo, wiped by every deploy — so a Worker's sign-in keeps its ledg
 { ledger, fallback })`, gating with `attempt` (check and charge in one step, so a concurrent burst
 cannot share one count). `src/server/auth/loginThrottleDurable.ts` has the why and the wiring.
 
+## 🔴 A master lock on a Worker: `attempts: createD1MasterLockAttempts(db)`
+
+A Worker rebuilds `MasterLock` per request, so its guess throttle must be CHARGED where every
+request can see it, before the argon2id verify — or a burst landing inside one verify is judged
+against one stale count (task 2137). Pass `attempts: createD1MasterLockAttempts(db, { snapshot })`
+(one conditional UPSERT … RETURNING on the `meta` row `master_lock:attempts`).
+`src/server/master-lock/attempts.ts` has the why.
+
 ## Standards
 
 `docs/retention.md`, `docs/activity.md`, `docs/notifications.md`, `docs/engagement.md` — the

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

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

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.25.0",
+	"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.",

package/src/server/master-lock/attempts.spec.ts

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

package/src/server/master-lock/attempts.ts

@@ -0,0 +1,141 @@
+/**
+ * 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";
+import type { D1LikeDatabase } from "../d1/types.js";
+
+/** What {@link MasterLockAttempts.charge} answers: admitted (and charged), or not (and not). */
+export type MasterLockCharge = { admitted: true; failures: number } | { admitted: false; retryAfterMs: number };
+
+export interface MasterLockAttempts {
+	/** What the ledger last knew, for the lock page's countdown. Never a decision. */
+	retryAfterMs(now: number): number;
+	/**
+	 * 🔴 CHECK AND CHARGE in one step. Admitted → one failure is already charged, and
+	 * `failures` counts it. Refused → nothing charged; `retryAfterMs` is the wait.
+	 */
+	charge(now: number): MasterLockCharge | Promise<MasterLockCharge>;
+	/** The charged attempt was not a guess (nothing could be verified): take it back. */
+	refund(): void | Promise<void>;
+	/** A correct verifier: the run is over. */
+	clear(): void | Promise<void>;
+}
+
+/** The `meta`-style row a D1 ledger keeps its count in, beside the lock's record and state. */
+export 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: string): string {
+	const cap = delayAfter(Number.MAX_SAFE_INTEGER);
+	const arms: string[] = [];
+	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: string, name: string) =>
+	`COALESCE(CASE WHEN json_valid(${column}) THEN json_extract(${column}, '$.${name}') END, 0)`;
+
+function parseCount(raw: string | null | undefined): { failures: number; lastFailureAt: number } {
+	try {
+		const parsed = JSON.parse(raw ?? "") as { failures?: unknown; lastFailureAt?: unknown };
+		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: D1LikeDatabase,
+	options: { table?: string; key?: string; snapshot?: string | null } = {},
+): MasterLockAttempts {
+	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<{ value: string }>();
+			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<{ value: string }>();
+			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/src/server/master-lock/index.ts

@@ -46,6 +46,11 @@ export {
 	type MasterLockDirectoryOptions,
 	masterLockPrincipalKey,
 } from "./principals.js";
+export {
+	MASTER_LOCK_ATTEMPTS_KEY,
+	type MasterLockAttempts,
+	createD1MasterLockAttempts,
+} from "./attempts.js";
 export {
 	FIRST_ACCOUNT_ID,
 	MasterLock,

package/src/server/master-lock/masterLock.ts

@@ -57,6 +57,7 @@ import {
 	isMasterLockKdfParams,
 	windowRemaining,
 } from "cursedbelt-core/master-lock";
+import type { MasterLockAttempts, MasterLockCharge } from "./attempts.js";
 
 /**
  * ONE master password, and therefore one TENANT of the app behind it.
@@ -179,6 +180,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;
 	/**
@@ -265,10 +273,13 @@ export class MasterLock {
 
 	private failures = 0;
 	private lastFailureAt = 0;
+	/** See {@link MasterLockOptions.attempts}. */
+	private readonly attempts: MasterLockAttempts;
 
 	constructor(options: MasterLockOptions) {
 		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;
@@ -375,7 +386,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,
 		};
@@ -464,13 +475,16 @@ export class MasterLock {
 	 */
 	async unlock(verifier: string): Promise<MasterLockUnlockResult> {
 		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: MasterLockCharge = 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: MasterLockAccount | null = 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
@@ -482,23 +496,50 @@ 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.
+	 */
+	private ownAttempts(): MasterLockAttempts {
+		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.
@@ -566,6 +607,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) };
 	}