cursedbelt-server 1.0.0

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

@@ -0,0 +1,313 @@
+/**
+ * The lock page — the ONLY thing a locked app serves.
+ *
+ * ── Why it is authored here as strings ──────────────────────────────────────
+ * It has to render before any of the app exists: no bundle, no framework, no design system,
+ * no fonts, nothing fetched from anywhere. That is the requirement — *"a user logged in as
+ * me cannot see anything about the site, not even text or images, nothing at all"* — and the
+ * honest way to meet it is for the locked response to have nothing of the app in it.
+ *
+ * ── Why the CSS and JS are separate routes, not inline ──────────────────────
+ * `apps/vault`'s CSP wall forbids inline script, and any app adopting this lock deserves to
+ * keep a wall that strict. Two same-origin files cost one round trip each and let the page
+ * ship under `script-src 'self'` with no nonce plumbing.
+ *
+ * ── 🔴 The derivation in `LOCK_SCRIPT` is a HAND COPY of `deriveMasterLockVerifier` ──────
+ * It cannot import it: this file is served to a browser as plain text, outside every build.
+ * A copy that drifts derives a verifier that can never match, and the symptom would be "my
+ * correct password is refused" — the same shape of bug that cost `apps/collections` a day.
+ * So `lockPage.spec.ts` EVALUATES the script's function out of this source and asserts it
+ * agrees with the TypeScript one on a fixed vector. Change one, the spec fails until you
+ * change the other.
+ */
+import { MASTER_LOCK_PATHS } from "cursedbelt-core/master-lock";
+
+/** Everything the page needs to know about the app it is standing in front of. */
+export interface LockPageOptions {
+	/** What to call this app — "Collections", "binary-server inspector". */
+	appLabel: string;
+	/** Shown under the title. Defaults to the sentence that explains the second wall. */
+	note?: string;
+	/**
+	 * Render the CHOOSE-a-password form rather than the type-it form.
+	 *
+	 * Set by the guard from `lock.awaitingEnrollment`, i.e. per-person mode with no record
+	 * for this account yet. It is a rendering hint and nothing more — the server refuses
+	 * `POST /__lock/enroll` on its own record's state, so a page asking to enroll cannot
+	 * make enrollment legal.
+	 */
+	enroll?: boolean;
+}
+
+const escapeHtml = (value: string): string =>
+	value.replace(
+		/[&<>"']/g,
+		(ch) =>
+			({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch] ?? ch,
+	);
+
+/**
+ * The document. Deliberately says the app's NAME and nothing else about it — whoever is
+ * looking already reached the origin, so the hostname told them that much, and a page that
+ * would not say which app it is cannot tell the owner which password to type.
+ */
+export function lockPageHtml(options: LockPageOptions): string {
+	const label = escapeHtml(options.appLabel);
+	const enroll = options.enroll === true;
+	const note = escapeHtml(
+		options.note ??
+			(enroll
+				? "You are signed in, but this site needs a master password of your own. " +
+					"Choose one now. Nobody else can see it and nobody else can reset it — " +
+					"if you forget it, it cannot be recovered."
+				: "This site is locked. Signing in is not enough — enter the master password to continue."),
+	);
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Locked · ${label}</title>
+<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🔒</text></svg>">
+<link rel="stylesheet" href="${MASTER_LOCK_PATHS.style}">
+</head>
+<body data-mode="${enroll ? "enroll" : "unlock"}">
+<main class="card" aria-labelledby="ml-title">
+  <div class="glyph" aria-hidden="true">${enroll ? "🔑" : "🔒"}</div>
+  <h1 id="ml-title">${label}</h1>
+  <p class="note">${note}</p>
+  <form id="ml-form" autocomplete="off">
+    <label class="field">
+      <span>${enroll ? "New master password" : "Master password"}</span>
+      <input id="ml-input" type="password" name="master-password"
+             autocomplete="${enroll ? "new-password" : "current-password"}"
+             autofocus required spellcheck="false" enterkeyhint="${enroll ? "next" : "go"}"${
+               enroll ? ' minlength="10"' : ""
+             }>
+    </label>${
+      enroll
+        ? `
+    <label class="field">
+      <span>Confirm master password</span>
+      <input id="ml-confirm" type="password" name="confirm-master-password"
+             autocomplete="new-password" required spellcheck="false" enterkeyhint="go"
+             minlength="10">
+    </label>`
+        : ""
+    }
+    <button id="ml-submit" type="submit">${enroll ? "Set master password" : "Unlock"}</button>
+  </form>
+  <p id="ml-status" class="status" role="status" aria-live="polite"></p>
+</main>
+<script type="module" src="${MASTER_LOCK_PATHS.script}"></script>
+</body>
+</html>
+`;
+}
+
+/** The stylesheet. Follows the viewer's theme and commits to nothing else. */
+export const LOCK_STYLE = `:root{color-scheme:light dark;
+  --ml-bg:#f4f5f7;--ml-card:#ffffff;--ml-text:#14171c;--ml-muted:#69707c;--ml-border:#d9dde3;
+  --ml-accent:#1f6feb;--ml-accent-text:#ffffff;--ml-danger:#b42318;
+  --ml-shadow:0 18px 48px rgba(16,18,22,.14)}
+@media (prefers-color-scheme:dark){:root{
+  --ml-bg:#0d0f13;--ml-card:#171a20;--ml-text:#e7eaef;--ml-muted:#8b93a1;--ml-border:#2b3039;
+  --ml-accent:#4f8cf7;--ml-accent-text:#0b0d11;--ml-danger:#f97066;
+  --ml-shadow:0 18px 48px rgba(0,0,0,.55)}}
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px;
+  background:var(--ml-bg);color:var(--ml-text);
+  font:15px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+.card{width:100%;max-width:23rem;background:var(--ml-card);border:1px solid var(--ml-border);
+  border-radius:16px;padding:28px 26px 24px;box-shadow:var(--ml-shadow);text-align:center}
+.glyph{font-size:30px;line-height:1;margin-bottom:10px}
+h1{margin:0 0 6px;font-size:18px;font-weight:650;letter-spacing:-.01em}
+.note{margin:0 0 20px;font-size:13px;color:var(--ml-muted)}
+.field{display:block;text-align:left;margin-bottom:14px}
+.field span{display:block;font-size:12px;font-weight:600;color:var(--ml-muted);margin-bottom:6px}
+input{width:100%;height:40px;padding:0 12px;border:1px solid var(--ml-border);border-radius:9px;
+  background:var(--ml-bg);color:inherit;font:inherit}
+input:focus{outline:2px solid var(--ml-accent);outline-offset:1px;border-color:transparent}
+button{width:100%;height:40px;border:0;border-radius:9px;background:var(--ml-accent);
+  color:var(--ml-accent-text);font:inherit;font-weight:600;cursor:pointer}
+button[disabled]{opacity:.6;cursor:progress}
+.status{margin:14px 0 0;min-height:1.2em;font-size:12.5px;color:var(--ml-muted)}
+.status[data-tone="error"]{color:var(--ml-danger)}
+`;
+
+/**
+ * The page's script.
+ *
+ * Derives in the browser and sends only the verifier — the password itself never crosses
+ * the network, which is what makes "saved nowhere" true rather than aspirational.
+ *
+ * 600,000 PBKDF2 rounds take a beat on a phone, so the button says so; a page that looks
+ * frozen gets clicked again, and every extra click is another 600k rounds.
+ */
+export const LOCK_SCRIPT = `const paths = ${JSON.stringify(MASTER_LOCK_PATHS)};
+
+const form = document.getElementById("ml-form");
+const input = document.getElementById("ml-input");
+const confirmInput = document.getElementById("ml-confirm");
+const submit = document.getElementById("ml-submit");
+const status = document.getElementById("ml-status");
+
+function say(message, tone) {
+  status.textContent = message;
+  if (tone) status.setAttribute("data-tone", tone);
+  else status.removeAttribute("data-tone");
+}
+
+// ── derivation ───────────────────────────────────────────────────────────────
+// 🔴 Byte-identical to deriveMasterLockVerifier in cursedbelt-core/master-lock. Pinned by
+// lockPage.spec.ts, which evaluates THIS function and compares. Do not "tidy" it apart.
+function unb64u(text) {
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function b64u(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\\+/g, "-").replace(/\\//g, "_").replace(/=+$/, "");
+}
+async function pbkdf2(material, salt, iterations) {
+  const key = await crypto.subtle.importKey("raw", material, "PBKDF2", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits(
+    { name: "PBKDF2", salt: salt, iterations: iterations, hash: "SHA-256" }, key, 256);
+  return new Uint8Array(bits);
+}
+async function deriveVerifier(password, kdf) {
+  const salt = unb64u(kdf.salt);
+  const bytes = new TextEncoder().encode(password);
+  const kek = await pbkdf2(bytes, salt, kdf.iter);
+  const joined = new Uint8Array(kek.length + bytes.length);
+  joined.set(kek, 0);
+  joined.set(bytes, kek.length);
+  return b64u(await pbkdf2(joined, salt, 1));
+}
+globalThis.__masterLockDerive = deriveVerifier;
+
+// ── the page ─────────────────────────────────────────────────────────────────
+// 🔴 Everything below this line touches \`document\` beyond \`getElementById\`, and
+// lockPage.spec.ts cuts the source at the marker above to evaluate the derivation with a
+// stub. Keep page state here, not in the prelude, or that test throws instead of running.
+//
+// Rendered by the server from THIS principal's own record. The server re-decides it on
+// every POST, so this only chooses which form to submit — it cannot grant anything.
+const enrolling = document.body.dataset.mode === "enroll";
+
+/** The shortest password worth calling one. Matched by the input's own minlength, and
+ *  checked here too because a pasted value can beat the constraint on some engines. */
+const MIN_LENGTH = 10;
+
+let kdf = null;
+let busy = false;
+
+async function loadStatus() {
+  try {
+    const res = await fetch(paths.status, { credentials: "same-origin" });
+    if (!res.ok) return;
+    const body = await res.json();
+    kdf = body.kdf;
+    if (body.enrollable) { /* the choose-a-password form is already rendered */ }
+    else if (!body.configured) say("No master password is set for this app.", "error");
+    else if (body.retryAfterMs > 0) countdown(body.retryAfterMs);
+    else if (!body.locked) location.reload();
+  } catch { /* offline: the submit below reports it */ }
+}
+
+let timer = null;
+function countdown(ms) {
+  if (timer) clearInterval(timer);
+  let left = Math.ceil(ms / 1000);
+  const tick = () => {
+    if (left <= 0) { clearInterval(timer); timer = null; say(""); submit.disabled = false; return; }
+    say("Too many attempts. Try again in " + left + "s.", "error");
+    left -= 1;
+  };
+  submit.disabled = true;
+  tick();
+  timer = setInterval(tick, 1000);
+}
+
+/** Fresh params for a password nobody has chosen before. Byte-identical to
+ *  newMasterLockKdfParams — pinned by lockPage.spec.ts alongside the derivation. */
+function newKdf() {
+  const salt = new Uint8Array(16);
+  crypto.getRandomValues(salt);
+  return { v: 1, alg: "PBKDF2-SHA256", iter: 600000, salt: b64u(salt) };
+}
+
+async function doEnroll(password) {
+  const params = newKdf();
+  const verifier = await deriveVerifier(password, params);
+  const res = await fetch(paths.enroll, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ kdf: params, verifier: verifier }),
+  });
+  if (res.ok) { say("Master password set."); location.reload(); return true; }
+  // The server collapses every enrollment refusal into one, so this cannot say more
+  // than "reload and see" without inventing a distinction the server refused to draw.
+  say("This site could not accept that right now. Reload and try again.", "error");
+  return false;
+}
+
+async function doUnlock(password) {
+  const verifier = await deriveVerifier(password, kdf);
+  const res = await fetch(paths.unlock, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ verifier: verifier }),
+  });
+  if (res.ok) { say("Unlocked."); location.reload(); return true; }
+  const body = await res.json().catch(() => ({}));
+  input.value = "";
+  input.focus();
+  if (body && body.retryAfterMs > 0) { countdown(body.retryAfterMs); return false; }
+  say("That is not the master password.", "error");
+  return false;
+}
+
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  if (busy || submit.disabled) return;
+  const password = input.value;
+  if (!password) return;
+  if (enrolling) {
+    if (password.length < MIN_LENGTH) {
+      say("Use at least " + MIN_LENGTH + " characters.", "error");
+      return;
+    }
+    if (confirmInput && confirmInput.value !== password) {
+      say("Those two do not match.", "error");
+      confirmInput.value = "";
+      confirmInput.focus();
+      return;
+    }
+  } else if (!kdf) {
+    await loadStatus();
+    if (!kdf) { say("Cannot reach this site right now.", "error"); return; }
+  }
+  busy = true;
+  submit.disabled = true;
+  say(enrolling ? "Setting…" : "Checking…");
+  try {
+    const done = enrolling ? await doEnroll(password) : await doUnlock(password);
+    if (!done) submit.disabled = false;
+  } catch {
+    say("Cannot reach this site right now.", "error");
+    submit.disabled = false;
+  } finally {
+    busy = false;
+  }
+});
+
+loadStatus();
+`;

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

@@ -0,0 +1,338 @@
+/**
+ * The engine: seeding, the idle clock, the throttle, rotation.
+ *
+ * Real argon2id runs on every unlock here (that is the thing being tested), so this leans on
+ * the repo's per-test budget rather than trying to be fast.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+	DEFAULT_IDLE_MS,
+	MAX_IDLE_MS,
+	MIN_IDLE_MS,
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+	newMasterLockKdfParams,
+} from "cursedbelt-core/master-lock";
+import { MasterLock, readRecord } from "./masterLock";
+import { createMemoryMasterLockStore } from "./store";
+
+const KDF: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 1, // 600k rounds x N tests is minutes; the ROUND COUNT is pinned in kdf.spec.ts
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+const PASSWORD = "the owner's vault master password";
+
+let VERIFIER = "";
+let SEED = "";
+
+beforeEach(async () => {
+	if (VERIFIER) return;
+	VERIFIER = await deriveMasterLockVerifier(PASSWORD, KDF);
+	SEED = JSON.stringify({
+		kdf: KDF,
+		verifierHash: await Bun.password.hash(VERIFIER, { algorithm: "argon2id" }),
+	});
+});
+
+/** A lock with a fake clock the test drives. */
+function build(options: { seed?: string | null; stored?: string | null; now?: () => number } = {}) {
+	const store = createMemoryMasterLockStore(options.stored ?? null);
+	const locked: boolean[] = [];
+	const lock = new MasterLock({
+		store,
+		seedJson: options.seed === undefined ? SEED : options.seed,
+		...(options.now ? { now: options.now } : {}),
+		onLockedChange: (value) => locked.push(value),
+	});
+	return { lock, store, locked };
+}
+
+const req = (token?: string): Request =>
+	new Request("http://x/", token ? { headers: { cookie: `master_lock=${token}` } } : undefined);
+
+describe("seeding", () => {
+	test("adopts MASTER_LOCK_SEED when the store is empty, and persists it", () => {
+		const { lock, store } = build();
+		expect(lock.configured).toBe(true);
+		expect(store.read()).toBeTruthy();
+		expect(readRecord(store.read())?.kdf.salt).toBe(KDF.salt);
+	});
+
+	test("a STORED record wins over the seed — a rotation is permanent", async () => {
+		const otherKdf = newMasterLockKdfParams();
+		const stored = JSON.stringify({
+			kdf: otherKdf,
+			verifierHash: await Bun.password.hash("whatever", { algorithm: "argon2id" }),
+			idleMs: 90_000,
+		});
+		const { lock } = build({ stored });
+		expect(lock.kdf?.salt).toBe(otherKdf.salt);
+		expect(lock.idleMs).toBe(90_000);
+	});
+
+	test("an unusable seed leaves the lock unconfigured rather than half-armed", () => {
+		const { lock } = build({ seed: '{"kdf":{"v":1},"verifierHash":"nope"}' });
+		expect(lock.configured).toBe(false);
+	});
+
+	test("🔴 an UNCONFIGURED app reads as unlocked — a lock nobody can open is not protection", () => {
+		const { lock } = build({ seed: null });
+		expect(lock.configured).toBe(false);
+		expect(lock.unlocked).toBe(true);
+	});
+
+	test("a seed whose hash arrived shell-quoted is repaired, not refused", async () => {
+		const hash = await Bun.password.hash(VERIFIER, { algorithm: "argon2id" });
+		const { lock } = build({ seed: JSON.stringify({ kdf: KDF, verifierHash: `'${hash}'` }) });
+		expect(lock.configured).toBe(true);
+		expect((await lock.unlock(VERIFIER)).ok).toBe(true);
+	});
+
+	test("🔴 a seed whose WHOLE BLOB arrived shell-quoted is repaired too", async () => {
+		// The value is written single-quoted into a file a shell sources, because an argon2id
+		// hash contains `$`. Every reader in the fleet strips that pair — and one of them was
+		// wrong once, for a day, in production. Both shapes have to work.
+		const { lock } = build({ seed: `'${SEED}'` });
+		expect(lock.configured).toBe(true);
+		expect((await lock.unlock(VERIFIER)).ok).toBe(true);
+	});
+});
+
+describe("unlock", () => {
+	test("the right verifier opens it; the wrong one does not", async () => {
+		const { lock, locked } = build();
+		expect(lock.unlocked).toBe(false);
+		expect((await lock.unlock("not it")).ok).toBe(false);
+		expect(lock.unlocked).toBe(false);
+
+		const result = await lock.unlock(VERIFIER);
+		expect(result.ok).toBe(true);
+		expect(lock.unlocked).toBe(true);
+		expect(locked).toEqual([false]);
+	});
+
+	test("the minted token is what `presents` recognises, and nothing else is", async () => {
+		const { lock } = build();
+		const result = await lock.unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		expect(lock.presents(req(result.token))).toBe(true);
+		expect(lock.presents(req("a-different-token-of-the-same-length"))).toBe(false);
+		expect(lock.presents(req())).toBe(false);
+	});
+
+	test("a hash this build cannot parse answers 'no' without counting a failure", async () => {
+		const { lock } = build({
+			seed: JSON.stringify({ kdf: KDF, verifierHash: "$argon2id$this-is-not-a-hash" }),
+		});
+		for (let i = 0; i < 8; i += 1) expect((await lock.unlock(VERIFIER)).ok).toBe(false);
+		// Never throttled: the owner is not guessing, the machine is broken.
+		expect(lock.status().retryAfterMs).toBe(0);
+	});
+});
+
+describe("the idle clock", () => {
+	test("🔴 an ordinary request does NOT slide it — only interaction does", async () => {
+		let now = 1_000_000;
+		const { lock } = build({ now: () => now });
+		const result = await lock.unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		const token = result.token;
+
+		// Nine minutes of a page polling every thirty seconds, with a real read of the lock
+		// state on every tick — i.e. exactly what react-query does to an idle tab. A clock
+		// slid by traffic would still be open at the end; the assertion is that it is not.
+		const start = now;
+		let sawLocked = false;
+		for (let i = 0; i < 18; i += 1) {
+			now += 30_000;
+			const open = lock.presents(req(token));
+			expect(open).toBe(now - start <= DEFAULT_IDLE_MS);
+			sawLocked ||= !open;
+		}
+		expect(sawLocked).toBe(true);
+		expect(lock.unlocked).toBe(false);
+	});
+
+	test("touch() slides it, so an active session never lapses", async () => {
+		let now = 1_000_000;
+		const { lock } = build({ now: () => now });
+		const result = await lock.unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		const token = result.token;
+
+		for (let i = 0; i < 20; i += 1) {
+			now += DEFAULT_IDLE_MS - 1_000;
+			expect(lock.touch(req(token))).toBe(true);
+		}
+		expect(lock.unlocked).toBe(true);
+	});
+
+	test("🔴 touch() never REVIVES a lapsed unlock", async () => {
+		let now = 1_000_000;
+		const { lock } = build({ now: () => now });
+		const result = await lock.unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		now += DEFAULT_IDLE_MS + 1;
+		expect(lock.touch(req(result.token))).toBe(false);
+		expect(lock.unlocked).toBe(false);
+	});
+
+	test("lapsing fires onLockedChange, so a route swap can follow it", async () => {
+		let now = 1_000_000;
+		const { lock, locked } = build({ now: () => now });
+		await lock.unlock(VERIFIER);
+		now += DEFAULT_IDLE_MS + 1;
+		expect(lock.unlocked).toBe(false);
+		expect(locked).toEqual([false, true]);
+	});
+
+	test("the manual lock closes it at once", async () => {
+		const { lock, locked } = build();
+		await lock.unlock(VERIFIER);
+		lock.lock();
+		expect(lock.unlocked).toBe(false);
+		expect(locked).toEqual([false, true]);
+		// Idempotent — a second lock is not a second event.
+		lock.lock();
+		expect(locked).toEqual([false, true]);
+	});
+
+	test("setIdleMs clamps and persists", () => {
+		const { lock, store } = build();
+		expect(lock.setIdleMs(60_000)).toBe(60_000);
+		expect(readRecord(store.read())?.idleMs).toBe(60_000);
+		expect(lock.setIdleMs(1)).toBe(MIN_IDLE_MS);
+		expect(lock.setIdleMs(999 * 60 * 60_000)).toBe(MAX_IDLE_MS);
+		expect(lock.setIdleMs(Number.NaN)).toBe(DEFAULT_IDLE_MS);
+	});
+});
+
+/**
+ * 🔴 The two tests below declare their own budget, and it is not padding.
+ *
+ * Every `unlock()` runs a real argon2id verification — that IS the thing under test — and
+ * these two are the only ones in the file that do it in bulk: 9 attempts and 17 attempts.
+ * Measured 2026-09-13 on this machine: 4.5s and 7.2s against bun's DEFAULT per-test budget
+ * of 5000ms, so the second failed on every run and the first was one hiccup behind it. The
+ * file's header says it "leans on the repo's per-test budget"; this repo's `bunfig.toml`
+ * declares none, so that budget is 5s and the claim was simply false.
+ *
+ * Stated per test rather than raised in `bunfig.toml`, deliberately: a repo-wide 20s would
+ * buy these two nothing the line below does not, and would cost all 5,200 other tests the
+ * fast failure that tells you something is HUNG rather than slow.
+ */
+const KDF_BULK_MS = 20_000;
+
+describe("the guess throttle", () => {
+	test("five failures are free, the sixth costs a wait, and a success clears it", async () => {
+		let now = 1_000_000;
+		const { lock } = build({ now: () => now });
+		for (let i = 0; i < 5; i += 1) {
+			expect((await lock.unlock("wrong")).ok).toBe(false);
+			expect(lock.status().retryAfterMs).toBe(0);
+		}
+		const sixth = await lock.unlock("wrong");
+		expect(sixth.ok).toBe(false);
+		expect(sixth.ok === false && sixth.retryAfterMs).toBe(30_000);
+
+		// 🔴 Inside the window even the CORRECT verifier is refused — otherwise the throttle
+		// would be an oracle that says "that one was right".
+		const early = await lock.unlock(VERIFIER);
+		expect(early.ok).toBe(false);
+		expect(lock.unlocked).toBe(false);
+
+		now += 30_001;
+		expect((await lock.unlock(VERIFIER)).ok).toBe(true);
+		expect(lock.status().retryAfterMs).toBe(0);
+	}, KDF_BULK_MS);
+
+	test("a windowed refusal does not advance the counter", async () => {
+		let now = 1_000_000;
+		const { lock } = build({ now: () => now });
+		for (let i = 0; i < 6; i += 1) await lock.unlock("wrong");
+		for (let i = 0; i < 10; i += 1) await lock.unlock("wrong");
+		now += 30_001;
+		// Still the 6th failure's delay, not the 16th's — the hammering bought nothing and
+		// cost nothing.
+		const next = await lock.unlock("wrong");
+		expect(next.ok === false && next.retryAfterMs).toBe(60_000);
+	}, KDF_BULK_MS);
+});
+
+describe("rotation", () => {
+	test("needs the current password, rewrites the record, and locks the site", async () => {
+		const { lock, store, locked } = build();
+		await lock.unlock(VERIFIER);
+
+		const nextKdf = newMasterLockKdfParams();
+		const nextVerifier = await deriveMasterLockVerifier("a different one", nextKdf);
+
+		const refused = await lock.change({
+			currentVerifier: "wrong",
+			kdf: nextKdf,
+			verifier: nextVerifier,
+		});
+		expect(refused).toEqual({ ok: false, reason: "wrong" });
+		expect(lock.unlocked).toBe(true);
+
+		const done = await lock.change({
+			currentVerifier: VERIFIER,
+			kdf: nextKdf,
+			verifier: nextVerifier,
+		});
+		expect(done).toEqual({ ok: true });
+		// 🔴 Every open page dies with the old password.
+		expect(lock.unlocked).toBe(false);
+		expect(locked.at(-1)).toBe(true);
+
+		// The OLD one no longer opens it; the new one does.
+		expect((await lock.unlock(VERIFIER)).ok).toBe(false);
+		expect((await lock.unlock(nextVerifier)).ok).toBe(true);
+		expect(readRecord(store.read())?.kdf.salt).toBe(nextKdf.salt);
+	});
+
+	test("refuses params it could not derive under, before touching the record", async () => {
+		const { lock, store } = build();
+		const before = store.read();
+		const result = await lock.change({
+			currentVerifier: VERIFIER,
+			kdf: { v: 2 } as unknown as MasterLockKdfParams,
+			verifier: "x",
+		});
+		expect(result).toEqual({ ok: false, reason: "invalid" });
+		expect(store.read()).toBe(before);
+	});
+
+	test("keeps this app's idle timeout across a rotation", async () => {
+		const { lock, store } = build();
+		lock.setIdleMs(120_000);
+		await lock.unlock(VERIFIER);
+		const nextKdf = newMasterLockKdfParams();
+		await lock.change({
+			currentVerifier: VERIFIER,
+			kdf: nextKdf,
+			verifier: await deriveMasterLockVerifier("next", nextKdf),
+		});
+		expect(readRecord(store.read())?.idleMs).toBe(120_000);
+	});
+});
+
+describe("readRecord", () => {
+	test("rejects everything that is not a usable record", () => {
+		expect(readRecord(null)).toBeNull();
+		expect(readRecord("")).toBeNull();
+		expect(readRecord("not json")).toBeNull();
+		expect(readRecord("[]")).toBeNull();
+		expect(readRecord(JSON.stringify({ kdf: KDF }))).toBeNull();
+		expect(readRecord(JSON.stringify({ kdf: KDF, verifierHash: "plaintext" }))).toBeNull();
+		expect(readRecord(JSON.stringify({ verifierHash: "$argon2id$x" }))).toBeNull();
+	});
+
+	test("defaults a missing or absurd idleMs rather than inheriting it", () => {
+		const base = { kdf: KDF, verifierHash: "$argon2id$v=19$m=1,t=1,p=1$c2FsdA$aGFzaA" };
+		expect(readRecord(JSON.stringify(base))?.idleMs).toBe(DEFAULT_IDLE_MS);
+		expect(readRecord(JSON.stringify({ ...base, idleMs: -5 }))?.idleMs).toBe(MIN_IDLE_MS);
+	});
+});