cursedbelt-server 2.1.0 → 3.0.1

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

@@ -81,6 +81,16 @@ const LOCK_CSP =
 export interface MasterLockGuard {
 	/** `Response` when handled, `null` when the app should serve the request. */
 	handle(req: Request): Promise<Response | null>;
+	/**
+	 * 🔴 **WHICH tenant this request is for** — the answer an app must scope every query by.
+	 *
+	 * `null` when the request carries no live unlock, which is exactly when {@link handle}
+	 * would have refused it. So the safe shape in an app is to read this AFTER the guard has
+	 * stood aside, and to treat `null` as "serve nothing" rather than "serve the default" —
+	 * a fallback tenant is how a locked request ends up being answered with somebody's
+	 * library.
+	 */
+	accountFor(req: Request): string | null;
 }
 
 export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLockGuard {
@@ -105,24 +115,23 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 		);
 
 	/**
-	 * 🔴 May THIS request through — and the difference between the two modes is the whole
-	 * security property of the per-person wall.
+	 * 🔴 May THIS request through — and the answer is a PRESENTED TOKEN, always.
 	 *
-	 * **App-wide**: `unlocked` is enough. The site has one user and one unlock; the token
-	 * is how a caller with no cookie jar says "it's still me", not a per-browser
-	 * credential. Reading the ambient state is the behaviour `apps/collections` and the
-	 * binary-server inspector have always had.
+	 * Until the accounts model there was a second branch: an app-wide lock let `unlocked`
+	 * alone open the door, on the reasoning that such a site had one user and one unlock,
+	 * so the token was merely how a caller with no cookie jar said "it's still me". The
+	 * per-person wall already refused that shape, and 2026-08-25 measured why — with
+	 * `unlocked ||` in front, one browser unlocking meant every OTHER browser signed in as
+	 * that person walked straight through having typed nothing, and an invented
+	 * `x-master-lock` value was accepted because the check never looked at it.
 	 *
-	 * **Per-person**: the token is REQUIRED. `unlocked` there means only "somebody's
-	 * device is open", and honouring that would make the unlock ambient — measured while
-	 * building this (2026-08-25): with `unlocked ||` in front, one browser unlocking meant
-	 * every OTHER browser signed in as that person walked straight through, having typed
-	 * nothing. The owner's phone would ride his desk's unlock, and an invented
-	 * `x-master-lock` value would be accepted because the check never looked at it. Two
-	 * tests in `principals.spec.ts` fail on the `||`, which is why it is gone.
+	 * The accounts model removes the last reason to keep the branch, and turns it from
+	 * sloppy into wrong: the password decides WHICH TENANT'S DATA the app serves, so a
+	 * request with no token has no account, and admitting it means serving whichever
+	 * library somebody else's browser happens to have open. There is one rule now, for
+	 * every app.
 	 */
-	const opens = (lock: MasterLock, req: Request): boolean =>
-		lock.isEnrollable ? lock.presents(req) : lock.unlocked || lock.presents(req);
+	const opens = (lock: MasterLock, req: Request): boolean => lock.presents(req);
 
 	async function handleOwnRoute(req: Request, url: URL, lock: MasterLock): Promise<Response> {
 		const path = url.pathname;
@@ -140,7 +149,21 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 				});
 			}
 			if (path === MASTER_LOCK_PATHS.status) {
-				return Response.json(lock.status(), { headers: noStore });
+				return Response.json(lock.status(req), { headers: noStore });
+			}
+			if (path === MASTER_LOCK_PATHS.hints) {
+				// 🔴 Readable WHILE LOCKED, and the only surface here that is. See the path's
+				// note in `cursedbelt-core/master-lock/wire.ts`: a hint nobody can read until
+				// they are already in is not a hint, and everyone who reaches this has passed
+				// the app's own owner-only sign-in. It is a separate route, fetched only when
+				// somebody clicks "I forgot", so the default lock screen stays byte-identical
+				// whether this app has one tenant or ten.
+				return Response.json({ hints: lock.hints() }, { headers: noStore });
+			}
+			if (path === MASTER_LOCK_PATHS.accounts) {
+				// Unlike the hints, this needs the site already open — it names every tenant.
+				if (!opens(lock, req)) return refuse();
+				return Response.json({ accounts: lock.summaries(req) }, { headers: noStore });
 			}
 			if (path === MASTER_LOCK_PATHS.page || path === MASTER_LOCK_PREFIX) {
 				// Already open FOR THIS CALLER, so there is nothing to type — send them to
@@ -153,6 +176,18 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 			return new Response("not found", { status: 404, headers: noStore });
 		}
 
+		if (req.method === "PATCH" && path === MASTER_LOCK_PATHS.accounts) {
+			if (!opens(lock, req)) return refuse();
+			const body = await readJson(req);
+			const ok = lock.editAccount(req, {
+				id: typeof body?.id === "string" ? body.id : "",
+				...(typeof body?.label === "string" ? { label: body.label } : {}),
+				...(typeof body?.hint === "string" ? { hint: body.hint } : {}),
+			});
+			if (!ok) return Response.json({ error: "wrong" }, { status: 400, headers: noStore });
+			return Response.json({ ok: true, accounts: lock.summaries(req) }, { headers: noStore });
+		}
+
 		if (req.method !== "POST") {
 			return new Response("method not allowed", { status: 405, headers: noStore });
 		}
@@ -168,7 +203,7 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 			// becomes a way to ask whether a given account has a master password yet.
 			if (!result.ok) return refuse();
 			return Response.json(
-				{ ok: true, idleMs: lock.idleMs },
+				{ ok: true, idleMs: lock.idleMs, accountId: result.accountId },
 				{ headers: { ...noStore, "set-cookie": cookie(result.token, secure) } },
 			);
 		}
@@ -178,8 +213,12 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 			const verifier = typeof body?.verifier === "string" ? body.verifier : "";
 			const result = await lock.unlock(verifier);
 			if (!result.ok) return refuse(result.retryAfterMs);
+			// 🔴 The account id is in the REPLY and not only in the cookie, because the page
+			// that just unlocked has to reload into the right tenant. It names the account
+			// that opened and never the ones that did not, so a wrong password still learns
+			// nothing about what else is here.
 			return Response.json(
-				{ ok: true, idleMs: lock.idleMs },
+				{ ok: true, idleMs: lock.idleMs, accountId: result.accountId },
 				{ headers: { ...noStore, "set-cookie": cookie(result.token, secure) } },
 			);
 		}
@@ -203,11 +242,46 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 			const idleMs = lock.setIdleMs(Number(body?.idleMs));
 			return Response.json({ ok: true, idleMs }, { headers: noStore });
 		}
+		if (path === MASTER_LOCK_PATHS.accounts) {
+			const body = await readJson(req);
+			const result = await lock.addAccount(req, {
+				currentVerifier: typeof body?.currentVerifier === "string" ? body.currentVerifier : "",
+				verifier: typeof body?.verifier === "string" ? body.verifier : "",
+				label: typeof body?.label === "string" ? body.label : "",
+				hint: typeof body?.hint === "string" ? body.hint : "",
+			});
+			if (!result.ok) {
+				return Response.json({ error: result.reason }, { status: 400, headers: noStore });
+			}
+			// 🔴 No cookie. Creating a tenant does not enter it — switching means typing that
+			// tenant's password, which is the entire boundary this feature is made of.
+			return Response.json({ ok: true, account: result.account }, { headers: noStore });
+		}
 		if (path === MASTER_LOCK_PATHS.change) {
 			const body = await readJson(req);
-			const result = await lock.change({
+			/*
+			 * 🔴 An OLDER client sends a freshly-minted `kdf` with a rotation, because that is
+			 * what the wire looked like before accounts existed. Ignoring it silently would be
+			 * a lockout, not a compatibility shim: the verifier in the same body was derived
+			 * under THAT salt, so storing it would leave a hash nothing can ever match — the
+			 * owner would set a new password, be logged out by the rotation, and find that
+			 * neither the old nor the new one opens the app.
+			 *
+			 * There is no safe way to honour it either, since every account on this app shares
+			 * one descriptor. So it is refused, loudly, with the one thing that distinguishes
+			 * it from a wrong password.
+			 */
+			if (body?.kdf !== undefined) {
+				const supplied = body.kdf as { salt?: unknown };
+				if (!lock.kdf || supplied?.salt !== lock.kdf.salt) {
+					return Response.json(
+						{ error: "stale-client" },
+						{ status: 409, headers: noStore },
+					);
+				}
+			}
+			const result = await lock.change(req, {
 				currentVerifier: typeof body?.currentVerifier === "string" ? body.currentVerifier : "",
-				kdf: body?.kdf as never,
 				verifier: typeof body?.verifier === "string" ? body.verifier : "",
 			});
 			if (!result.ok) {
@@ -224,6 +298,11 @@ export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLo
 	}
 
 	return {
+		accountFor(req: Request): string | null {
+			// The SAME resolution the guard itself uses, so an app can never be told a
+			// different tenant from the one the wall admitted.
+			return resolve(req)?.accountFor(req) ?? null;
+		},
 		async handle(req: Request): Promise<Response | null> {
 			const url = new URL(req.url);
 			const own =

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

@@ -22,7 +22,10 @@ export {
 	masterLockPrincipalKey,
 } from "./principals";
 export {
+	FIRST_ACCOUNT_ID,
 	MasterLock,
+	type MasterLockAccount,
+	type MasterLockAddAccountResult,
 	type MasterLockEnrollResult,
 	type MasterLockOptions,
 	type MasterLockRecord,

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

@@ -59,7 +59,7 @@ export function lockPageHtml(options: LockPageOptions): string {
 			(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."
+					"if you forget it, it cannot be recovered, so leave yourself a hint."
 				: "This site is locked. Signing in is not enough — enter the master password to continue."),
 	);
 	return `<!doctype html>
@@ -93,12 +93,24 @@ export function lockPageHtml(options: LockPageOptions): string {
       <input id="ml-confirm" type="password" name="confirm-master-password"
              autocomplete="new-password" required spellcheck="false" enterkeyhint="go"
              minlength="10">
+    </label>
+    <label class="field">
+      <span>Hint <em>optional</em></span>
+      <input id="ml-hint" type="text" name="master-password-hint" maxlength="200"
+             spellcheck="false" autocomplete="off"
+             placeholder="Something only you would understand">
     </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>
+  <p id="ml-status" class="status" role="status" aria-live="polite"></p>${
+    enroll
+      ? ""
+      : `
+  <button id="ml-forgot" type="button" class="quiet">I forgot which password</button>
+  <dl id="ml-hints" class="hints" hidden></dl>`
+  }
 </main>
 <script type="module" src="${MASTER_LOCK_PATHS.script}"></script>
 </body>
@@ -134,6 +146,16 @@ button{width:100%;height:40px;border:0;border-radius:9px;background:var(--ml-acc
 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)}
+.field span em{font-style:normal;font-weight:500;text-transform:none;opacity:.7}
+button.quiet{margin-top:10px;height:32px;background:none;color:var(--ml-muted);font-weight:500;
+  font-size:12.5px;text-decoration:underline;text-underline-offset:3px}
+button.quiet:hover{color:var(--ml-text)}
+button.quiet[disabled]{opacity:.5}
+.hints{margin:10px 0 0;padding:12px 14px;text-align:left;border:1px solid var(--ml-border);
+  border-radius:10px;background:var(--ml-bg);font-size:12.5px}
+.hints dt{font-weight:650;color:var(--ml-text)}
+.hints dd{margin:2px 0 10px;color:var(--ml-muted);overflow-wrap:anywhere}
+.hints dd:last-child{margin-bottom:0}
 `;
 
 /**
@@ -150,8 +172,11 @@ 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 hintInput = document.getElementById("ml-hint");
 const submit = document.getElementById("ml-submit");
 const status = document.getElementById("ml-status");
+const forgot = document.getElementById("ml-forgot");
+const hints = document.getElementById("ml-hints");
 
 function say(message, tone) {
   status.textContent = message;
@@ -249,7 +274,11 @@ async function doEnroll(password) {
     method: "POST",
     credentials: "same-origin",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({ kdf: params, verifier: verifier }),
+    body: JSON.stringify({
+      kdf: params,
+      verifier: verifier,
+      hint: hintInput ? hintInput.value : "",
+    }),
   });
   if (res.ok) { say("Master password set."); location.reload(); return true; }
   // The server collapses every enrollment refusal into one, so this cannot say more
@@ -275,6 +304,44 @@ async function doUnlock(password) {
   return false;
 }
 
+// ── the hints, and why they are behind a click ───────────────────────────────
+// Reading them says how many master passwords this app has and what each is called, which
+// is the one fact the rest of this page is built never to disclose. Fetching them on load
+// would leak it to anyone who merely opened the door; a button makes it something the
+// owner ASKS for. Everyone who gets this far has already passed the app's own sign-in.
+if (forgot && hints) {
+  forgot.addEventListener("click", async () => {
+    if (!hints.hidden) { hints.hidden = true; return; }
+    forgot.disabled = true;
+    try {
+      const res = await fetch(paths.hints, { credentials: "same-origin" });
+      const body = await res.json();
+      const rows = (body && body.hints) || [];
+      hints.replaceChildren();
+      if (rows.length === 0) {
+        const dd = document.createElement("dd");
+        dd.textContent = "No hints have been written yet.";
+        hints.append(dd);
+      }
+      for (const row of rows) {
+        const dt = document.createElement("dt");
+        dt.textContent = row.label;
+        const dd = document.createElement("dd");
+        // 🔴 textContent, never innerHTML. The hint is free text the owner typed and this
+        // page runs under a CSP that permits no inline script — writing it as markup would
+        // be the one way to get some in.
+        dd.textContent = row.hint || "— no hint —";
+        hints.append(dt, dd);
+      }
+      hints.hidden = false;
+    } catch {
+      say("Cannot reach this site right now.", "error");
+    } finally {
+      forgot.disabled = false;
+    }
+  });
+}
+
 form.addEventListener("submit", async (event) => {
   event.preventDefault();
   if (busy || submit.disabled) return;

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

@@ -77,10 +77,32 @@ describe("seeding", () => {
 		expect(lock.configured).toBe(false);
 	});
 
-	test("🔴 an UNCONFIGURED app reads as unlocked — a lock nobody can open is not protection", () => {
+	test("🔴 an UNCONFIGURED app reads as LOCKED, and offers to take a first password", () => {
+		// This INVERTS what it asserted until the accounts model, and the inversion is the
+		// owner's ruling: *"if there is no master password then it has to get one set before
+		// a user could add anything. It would be booting to nothing until the password is
+		// created."* Nothing is bricked, because `enroll` is the way out — which is the
+		// half that made the old "unconfigured means open" reasoning necessary.
 		const { lock } = build({ seed: null });
 		expect(lock.configured).toBe(false);
+		expect(lock.unlocked).toBe(false);
+		expect(lock.awaitingEnrollment).toBe(true);
+	});
+
+	test("🔴 an unlock is never AMBIENT — a second browser that typed nothing gets no account", async () => {
+		// The property the whole tenant model rests on. `unlocked` says somebody's device is
+		// open; it may never answer "whose library do I serve", because the answer would be
+		// "whichever one is open", and that is how one tenant's files reach a session that
+		// holds the other tenant's password.
+		const { lock } = build();
+		const opened = await lock.unlock(VERIFIER);
+		expect(opened.ok).toBe(true);
 		expect(lock.unlocked).toBe(true);
+		// A request carrying no token at all.
+		expect(lock.accountFor(req())).toBeNull();
+		expect(lock.presents(req())).toBe(false);
+		// An invented one.
+		expect(lock.accountFor(req("not-a-real-token"))).toBeNull();
 	});
 
 	test("a seed whose hash arrived shell-quoted is repaired, not refused", async () => {
@@ -262,24 +284,24 @@ describe("the guess throttle", () => {
 });
 
 describe("rotation", () => {
-	test("needs the current password, rewrites the record, and locks the site", async () => {
+	test("needs the current password, keeps the ACCOUNT, and locks the site", async () => {
 		const { lock, store, locked } = build();
-		await lock.unlock(VERIFIER);
+		const opened = await lock.unlock(VERIFIER);
+		const token = opened.ok ? opened.token : "";
+		const account = opened.ok ? opened.accountId : "";
+		expect(account).toBe("acct-1");
 
-		const nextKdf = newMasterLockKdfParams();
-		const nextVerifier = await deriveMasterLockVerifier("a different one", nextKdf);
+		const nextVerifier = await deriveMasterLockVerifier("a different one", KDF);
 
-		const refused = await lock.change({
+		const refused = await lock.change(req(token), {
 			currentVerifier: "wrong",
-			kdf: nextKdf,
 			verifier: nextVerifier,
 		});
 		expect(refused).toEqual({ ok: false, reason: "wrong" });
 		expect(lock.unlocked).toBe(true);
 
-		const done = await lock.change({
+		const done = await lock.change(req(token), {
 			currentVerifier: VERIFIER,
-			kdf: nextKdf,
 			verifier: nextVerifier,
 		});
 		expect(done).toEqual({ ok: true });
@@ -287,36 +309,47 @@ describe("rotation", () => {
 		expect(lock.unlocked).toBe(false);
 		expect(locked.at(-1)).toBe(true);
 
-		// The OLD one no longer opens it; the new one does.
+		// The OLD one no longer opens it; the new one does — and opens the SAME account.
 		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);
+		const again = await lock.unlock(nextVerifier);
+		expect(again.ok && again.accountId).toBe("acct-1");
+		// 🔴 The salt did NOT move. Every account derives under one app-wide descriptor, so
+		// a rotation that minted a fresh one would invalidate every sibling's stored hash.
+		expect(readRecord(store.read())?.kdf.salt).toBe(KDF.salt);
+	}, KDF_BULK_MS);
+
+	test("🔴 a rotation is refused outright without a live unlock of the account it names", async () => {
+		// An open session is not proof the owner is at the keyboard, and a caller with no
+		// session at all has not even got that far. There is no account to rotate.
+		const { lock, store } = build();
+		const before = store.read();
+		const result = await lock.change(req(), { currentVerifier: VERIFIER, verifier: "x" });
+		expect(result).toEqual({ ok: false, reason: "locked" });
+		expect(store.read()).toBe(before);
 	});
 
-	test("refuses params it could not derive under, before touching the record", async () => {
+	test("refuses an empty verifier before touching the record", async () => {
 		const { lock, store } = build();
+		const opened = await lock.unlock(VERIFIER);
 		const before = store.read();
-		const result = await lock.change({
+		const result = await lock.change(req(opened.ok ? opened.token : ""), {
 			currentVerifier: VERIFIER,
-			kdf: { v: 2 } as unknown as MasterLockKdfParams,
-			verifier: "x",
+			verifier: "",
 		});
 		expect(result).toEqual({ ok: false, reason: "invalid" });
 		expect(store.read()).toBe(before);
-	});
+	}, KDF_BULK_MS);
 
 	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({
+		const opened = await lock.unlock(VERIFIER);
+		await lock.change(req(opened.ok ? opened.token : ""), {
 			currentVerifier: VERIFIER,
-			kdf: nextKdf,
-			verifier: await deriveMasterLockVerifier("next", nextKdf),
+			verifier: await deriveMasterLockVerifier("next", KDF),
 		});
 		expect(readRecord(store.read())?.idleMs).toBe(120_000);
-	});
+	}, KDF_BULK_MS);
 });
 
 describe("readRecord", () => {