cursedbelt-server 4.24.1 → 4.26.0

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) };
 	}