cursedbelt-server 1.0.0

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

@@ -0,0 +1,378 @@
+/**
+ * 🔴 The per-person wall's isolation properties, as tests rather than as prose.
+ *
+ * The owner's constraint when this was built (2026-08-25): *"ensure it cannot be used to
+ * bypass the password by real users or used to access any real user data"*. Every claim
+ * the design makes about that is exercised here, because a wall whose isolation is only
+ * argued for in a comment is a wall nobody can prove still holds next month.
+ *
+ * The four claims:
+ *   1. One person's unlock token does not open another person's lock — cookie or header.
+ *   2. There is no route from "signed in" to "past the wall" without a password: a new
+ *      principal is LOCKED, not open, and no env/header/label changes that.
+ *   3. `enroll` creates only the password that was never set. It cannot overwrite one,
+ *      cannot run outside per-person mode, and cannot be raced into overwriting one.
+ *   4. Nothing a caller sends chooses WHICH lock they are measured against.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+	MASTER_LOCK_HEADER,
+	MASTER_LOCK_PATHS,
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+	newMasterLockKdfParams,
+} from "cursedbelt-core/master-lock";
+import { createMasterLockGuard } from "./guard";
+import { MasterLock, type MasterLockStore } from "./masterLock";
+import { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, masterLockPrincipalKey } from "./principals";
+import { createMemoryMasterLockStore } from "./store";
+
+const KDF: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 1,
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+
+/** A key/value surface the directory writes into, plus a window on what it wrote. */
+function memoryKv() {
+	const rows = new Map<string, string>();
+	return {
+		rows,
+		get: (key: string) => rows.get(key) ?? null,
+		set: (key: string, value: string) => void rows.set(key, value),
+	};
+}
+
+const OWNER = "curtwphillips@gmail.com";
+const GUEST = "ameena.phillips@gmail.com";
+
+let kv: ReturnType<typeof memoryKv>;
+let directory: MasterLockDirectory;
+
+beforeEach(() => {
+	kv = memoryKv();
+	directory = new MasterLockDirectory({ kv });
+});
+
+/** Enroll `principal` with `password` and return the unlock token it was handed. */
+async function enroll(principal: string, password: string): Promise<string> {
+	const kdf = newMasterLockKdfParams();
+	const result = await directory.for(principal).enroll({
+		kdf,
+		verifier: await deriveMasterLockVerifier(password, kdf),
+	});
+	if (!result.ok) throw new Error(`enrollment refused: ${result.reason}`);
+	return result.token;
+}
+
+describe("claim 1 — one person's unlock never opens another's", () => {
+	test("the owner's token is refused by the guest's lock, cookie or header", async () => {
+		const ownerToken = await enroll(OWNER, "the owner's own password");
+		await enroll(GUEST, "a different password entirely");
+		// The guest's lock is open on the guest's OWN token, so this is a real comparison
+		// and not merely "everything is locked".
+		directory.for(GUEST).lock();
+
+		const withCookie = new Request("https://orch.example/api/board", {
+			headers: { cookie: `master_lock=${ownerToken}` },
+		});
+		const withHeader = new Request("https://orch.example/api/board", {
+			headers: { [MASTER_LOCK_HEADER]: ownerToken },
+		});
+		expect(directory.for(GUEST).presents(withCookie)).toBe(false);
+		expect(directory.for(GUEST).presents(withHeader)).toBe(false);
+		// …and it is still exactly right for the person it was minted for.
+		expect(directory.for(OWNER).presents(withCookie)).toBe(true);
+		expect(directory.for(OWNER).presents(withHeader)).toBe(true);
+	});
+
+	test("🔴 the header is a TOKEN channel, not a bypass — an invented value opens nothing", async () => {
+		await enroll(OWNER, "the owner's own password");
+		directory.for(OWNER).lock();
+		for (const forged of ["1", "true", "yes", "smoke", "", "x".repeat(32)]) {
+			const req = new Request("https://orch.example/api/board", {
+				headers: { [MASTER_LOCK_HEADER]: forged },
+			});
+			expect(directory.for(OWNER).presents(req)).toBe(false);
+		}
+	});
+
+	test("locking one person leaves the other open — the unit is the person", async () => {
+		await enroll(OWNER, "the owner's own password");
+		await enroll(GUEST, "a different password entirely");
+		expect(directory.for(OWNER).unlocked).toBe(true);
+		expect(directory.for(GUEST).unlocked).toBe(true);
+		directory.for(OWNER).lock();
+		expect(directory.for(OWNER).unlocked).toBe(false);
+		expect(directory.for(GUEST).unlocked).toBe(true);
+	});
+
+	test("rotating one person's password cannot lock the other out of their own", async () => {
+		await enroll(OWNER, "the owner's own password");
+		const guestPassword = "a different password entirely";
+		await enroll(GUEST, guestPassword);
+		const kdf = newMasterLockKdfParams();
+		const rotated = await directory.for(OWNER).change({
+			currentVerifier: await deriveMasterLockVerifier("the owner's own password", directory.for(OWNER).kdf as MasterLockKdfParams),
+			kdf,
+			verifier: await deriveMasterLockVerifier("something new", kdf),
+		});
+		expect(rotated.ok).toBe(true);
+		// The guest's still opens on the guest's unchanged password.
+		directory.for(GUEST).lock();
+		const guestKdf = directory.for(GUEST).kdf as MasterLockKdfParams;
+		const reopened = await directory
+			.for(GUEST)
+			.unlock(await deriveMasterLockVerifier(guestPassword, guestKdf));
+		expect(reopened.ok).toBe(true);
+	});
+});
+
+describe("🔴 claim 1b — the unlock is a TOKEN, never ambient state", () => {
+	/**
+	 * Measured while building this, and the reason the guard no longer reads `unlocked` in
+	 * per-person mode: with `lock.unlocked ||` in front of the token check, the owner
+	 * enrolling in one browser opened the app for every OTHER browser signed in as him —
+	 * his phone rode his desk's unlock, and an invented `x-master-lock` value was accepted
+	 * because nothing ever looked at it. Both tests below fail if that `||` comes back.
+	 */
+	test("a second device signed in as the SAME person still has to type it", async () => {
+		await enroll(OWNER, "the owner's own password");
+		const guard = createMasterLockGuard({
+			appLabel: "Orchestrator",
+			lock: () => directory.for(OWNER),
+		});
+		// The lock IS open — the desk holds a token. This request carries none.
+		expect(directory.for(OWNER).unlocked).toBe(true);
+		const phone = await guard.handle(
+			new Request("https://orch.example/api/board", { headers: { accept: "application/json" } }),
+		);
+		expect(phone?.status).toBe(401);
+	});
+
+	test("both devices stay open once BOTH have typed it — neither evicts the other", async () => {
+		const desk = await enroll(OWNER, "the owner's own password");
+		const lock = directory.for(OWNER);
+		const phone = await lock.unlock(
+			await deriveMasterLockVerifier("the owner's own password", lock.kdf as MasterLockKdfParams),
+		);
+		expect(phone.ok).toBe(true);
+		const token = phone.ok ? phone.token : "";
+		// The owner asked to use this from the desk AND a phone; an unlock that replaced
+		// the previous one would sign the other out on every sign-in.
+		expect(lock.presents(new Request("https://orch.example/", { headers: { cookie: `master_lock=${desk}` } }))).toBe(true);
+		expect(lock.presents(new Request("https://orch.example/", { headers: { cookie: `master_lock=${token}` } }))).toBe(true);
+	});
+
+	test("the manual lock closes EVERY device that person has open", async () => {
+		const desk = await enroll(OWNER, "the owner's own password");
+		const lock = directory.for(OWNER);
+		const second = await lock.unlock(
+			await deriveMasterLockVerifier("the owner's own password", lock.kdf as MasterLockKdfParams),
+		);
+		lock.lock();
+		expect(lock.presents(new Request("https://orch.example/", { headers: { cookie: `master_lock=${desk}` } }))).toBe(false);
+		expect(
+			lock.presents(
+				new Request("https://orch.example/", {
+					headers: { cookie: `master_lock=${second.ok ? second.token : ""}` },
+				}),
+			),
+		).toBe(false);
+	});
+});
+
+describe("claim 2 — signed in is never enough", () => {
+	test("🔴 a principal with no record reads LOCKED, not open", () => {
+		const fresh = directory.for("somebody-brand-new");
+		expect(fresh.configured).toBe(false);
+		expect(fresh.unlocked).toBe(false);
+		expect(fresh.awaitingEnrollment).toBe(true);
+	});
+
+	test("the app-wide mode keeps its opposite default, so collections is untouched", () => {
+		const appWide = new MasterLock({ store: createMemoryMasterLockStore(null) });
+		expect(appWide.configured).toBe(false);
+		expect(appWide.unlocked).toBe(true);
+		expect(appWide.awaitingEnrollment).toBe(false);
+	});
+
+	test("the guard refuses every app path for an un-enrolled principal", async () => {
+		const guard = createMasterLockGuard({
+			appLabel: "Orchestrator",
+			lock: () => directory.for(GUEST),
+		});
+		const refused = await guard.handle(
+			new Request("https://orch.example/api/board", { headers: { accept: "application/json" } }),
+		);
+		expect(refused?.status).toBe(401);
+		const page = await guard.handle(
+			new Request("https://orch.example/", { headers: { accept: "text/html" } }),
+		);
+		// A document gets the choose-a-password page in place — 200, but it is the WALL,
+		// not the app: it must carry the locked marker and none of the app's HTML.
+		expect(page?.status).toBe(200);
+		expect(page?.headers.get("x-master-lock-state")).toBe("locked");
+		const html = await page?.text();
+		expect(html).toContain('data-mode="enroll"');
+		expect(html).toContain("Confirm master password");
+	});
+});
+
+describe("claim 3 — enroll only ever creates the password that was never set", () => {
+	test("🔴 it refuses once a record exists — there is no overwrite", async () => {
+		await enroll(OWNER, "the owner's own password");
+		const kdf = newMasterLockKdfParams();
+		const second = await directory.for(OWNER).enroll({
+			kdf,
+			verifier: await deriveMasterLockVerifier("an attacker's password", kdf),
+		});
+		expect(second).toEqual({ ok: false, reason: "already-configured" });
+		// And the ORIGINAL still opens it.
+		directory.for(OWNER).lock();
+		const opened = await directory
+			.for(OWNER)
+			.unlock(await deriveMasterLockVerifier("the owner's own password", directory.for(OWNER).kdf as MasterLockKdfParams));
+		expect(opened.ok).toBe(true);
+	});
+
+	test("🔴 a second lock over the SAME row cannot enroll past the first", async () => {
+		// Two MasterLock instances over one store is what two processes — or one process
+		// that rebuilt its map — actually look like. The re-read in `enroll` is what makes
+		// the second lose, and without it the last writer would silently win.
+		const store: MasterLockStore = (() => {
+			const kvv = memoryKv();
+			const key = "shared";
+			return { read: () => kvv.get(key), write: (json) => kvv.set(key, json) };
+		})();
+		const a = new MasterLock({ store, enrollable: true });
+		const b = new MasterLock({ store, enrollable: true });
+		const first = await a.enroll({ kdf: KDF, verifier: await deriveMasterLockVerifier("first", KDF) });
+		expect(first.ok).toBe(true);
+		const second = await b.enroll({ kdf: KDF, verifier: await deriveMasterLockVerifier("second", KDF) });
+		expect(second).toEqual({ ok: false, reason: "already-configured" });
+	});
+
+	test("🔴 it refuses outside per-person mode, so no app-wide lock can be armed by a POST", async () => {
+		const appWide = new MasterLock({ store: createMemoryMasterLockStore(null) });
+		const result = await appWide.enroll({
+			kdf: KDF,
+			verifier: await deriveMasterLockVerifier("anything", KDF),
+		});
+		expect(result).toEqual({ ok: false, reason: "not-enrollable" });
+	});
+
+	test("a malformed submission is refused rather than stored", async () => {
+		const lock = directory.for(OWNER);
+		expect(await lock.enroll({ kdf: { v: 9 } as never, verifier: "x" })).toEqual({
+			ok: false,
+			reason: "invalid",
+		});
+		expect(await lock.enroll({ kdf: KDF, verifier: "" })).toEqual({ ok: false, reason: "invalid" });
+		expect(lock.configured).toBe(false);
+	});
+
+	test("the route's refusal is the SAME refusal as every other — it cannot be used to probe", async () => {
+		await enroll(OWNER, "the owner's own password");
+		const guard = createMasterLockGuard({ appLabel: "Orchestrator", lock: () => directory.for(OWNER) });
+		const kdf = newMasterLockKdfParams();
+		const enrolled = await guard.handle(
+			new Request(`https://orch.example${MASTER_LOCK_PATHS.enroll}`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ kdf, verifier: await deriveMasterLockVerifier("x", kdf) }),
+			}),
+		);
+		expect(enrolled?.status).toBe(401);
+		expect(await enrolled?.json()).toEqual({ error: "locked", retryAfterMs: 0 });
+	});
+});
+
+describe("seed() — a pre-derived record for a machine account", () => {
+	/** The shape `MASTER_LOCK_SEED` carries: derived params + argon2(verifier), no password. */
+	async function seedJsonFor(password: string): Promise<string> {
+		const kdf = newMasterLockKdfParams();
+		const verifier = await deriveMasterLockVerifier(password, kdf);
+		return JSON.stringify({
+			kdf,
+			verifierHash: await Bun.password.hash(verifier, { algorithm: "argon2id" }),
+			idleMs: 300_000,
+		});
+	}
+
+	test("arms a principal that has none, and the seeded password then unlocks it", async () => {
+		const SMOKE = "smoke@auth.local";
+		expect(directory.seed(SMOKE, await seedJsonFor("the smoke's own password"))).toBe(true);
+		const lock = directory.for(SMOKE);
+		expect(lock.configured).toBe(true);
+		// Locked until it is opened — seeding decides that an account HAS a password, never
+		// that anybody may skip it.
+		expect(lock.unlocked).toBe(false);
+		const opened = await lock.unlock(
+			await deriveMasterLockVerifier("the smoke's own password", lock.kdf as MasterLockKdfParams),
+		);
+		expect(opened.ok).toBe(true);
+	});
+
+	test("🔴 a WRONG password still fails against a seeded record", async () => {
+		const SMOKE = "smoke@auth.local";
+		directory.seed(SMOKE, await seedJsonFor("the smoke's own password"));
+		const lock = directory.for(SMOKE);
+		const refused = await lock.unlock(
+			await deriveMasterLockVerifier("not it", lock.kdf as MasterLockKdfParams),
+		);
+		expect(refused.ok).toBe(false);
+	});
+
+	test("🔴 it REFUSES to rotate an existing record out from under its owner", async () => {
+		await enroll(OWNER, "the owner's own password");
+		expect(directory.seed(OWNER, await seedJsonFor("an attacker's password"))).toBe(false);
+		// The original still opens it.
+		const lock = directory.for(OWNER);
+		lock.lock();
+		const opened = await lock.unlock(
+			await deriveMasterLockVerifier("the owner's own password", lock.kdf as MasterLockKdfParams),
+		);
+		expect(opened.ok).toBe(true);
+	});
+
+	test("a malformed seed installs nothing rather than half a record", async () => {
+		expect(directory.seed("nobody@example.test", "not json")).toBe(false);
+		expect(directory.seed("nobody@example.test", JSON.stringify({ kdf: { v: 9 } }))).toBe(false);
+		expect(directory.for("nobody@example.test").configured).toBe(false);
+	});
+
+	test("seeding one principal arms NOBODY else", async () => {
+		directory.seed("smoke@auth.local", await seedJsonFor("the smoke's own password"));
+		expect(directory.for(OWNER).configured).toBe(false);
+		expect(directory.for(GUEST).configured).toBe(false);
+	});
+});
+
+describe("claim 4 — nothing a caller sends chooses whose lock they meet", () => {
+	test("🔴 a null principal refuses /__lock/* rather than falling through", async () => {
+		const guard = createMasterLockGuard({ appLabel: "Orchestrator", lock: () => null });
+		const status = await guard.handle(new Request(`https://orch.example${MASTER_LOCK_PATHS.status}`));
+		expect(status?.status).toBe(401);
+		// An ordinary path stands aside: the app's own sign-in owns a signed-out caller.
+		expect(await guard.handle(new Request("https://orch.example/"))).toBeNull();
+	});
+
+	test("the storage key is a hash, so no id can collide with or escape another's", () => {
+		const key = masterLockPrincipalKey("a:b/../c");
+		expect(key.startsWith(MASTER_LOCK_PRINCIPAL_KEY_PREFIX)).toBe(true);
+		expect(key.slice(MASTER_LOCK_PRINCIPAL_KEY_PREFIX.length)).toMatch(/^[0-9a-f]{64}$/);
+		expect(masterLockPrincipalKey(OWNER)).not.toBe(masterLockPrincipalKey(GUEST));
+		expect(masterLockPrincipalKey(OWNER)).toBe(masterLockPrincipalKey(OWNER));
+	});
+
+	test("the stored row carries no principal id and no password", async () => {
+		await enroll(OWNER, "the owner's own password");
+		const [key, value] = [...kv.rows.entries()][0] as [string, string];
+		expect(key).toBe(masterLockPrincipalKey(OWNER));
+		expect(value).not.toContain(OWNER);
+		expect(value).not.toContain("the owner's own password");
+		expect(JSON.parse(value).verifierHash.startsWith("$argon2")).toBe(true);
+	});
+});

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

@@ -0,0 +1,175 @@
+/**
+ * PER-PERSON master locks — one record, one password and one unlock per account.
+ *
+ * ── What this changes, and what it deliberately does not ────────────────────
+ * The engine next door (`masterLock.ts`) was built for an app with exactly one user, and
+ * its module note says so at length: *"There is exactly ONE unlock at a time, not one per
+ * browser session … the unit is the SITE."* That is still true of `apps/collections` and
+ * the binary-server inspector, and this file does not touch them.
+ *
+ * It stops being true the moment a second person may open the app. The owner, 2026-08-25:
+ * *"I would pick one that only I know and use and she could pick one for only she knows
+ * just like we did for the vault app."* Two people cannot share one record — the first to
+ * rotate it locks the second out of an app they were granted — and they must not share one
+ * unlock either, or her phone opens his desk.
+ *
+ * So the unit here is the PERSON. Each principal gets its own {@link MasterLock}: its own
+ * KDF salt, its own `argon2id(verifier)`, its own idle clock, its own guess throttle and
+ * its own in-memory unlock. Everything the engine already reasons about holds per person
+ * instead of per app, unchanged.
+ *
+ * ── 🔴 Three properties this file is responsible for ────────────────────────
+ *
+ * **1. One principal's unlock can never open another's.** Falls out of the construction —
+ * a token is compared only against the session of the lock it was minted by, and the lock
+ * is selected by the principal on the request's own signed-in session, never by anything
+ * the caller sends. There is no code path that takes a token and searches for a matching
+ * lock, and there must never be one.
+ *
+ * **2. A principal id can never reach the storage key.** Ids in this fleet are sometimes
+ * uuids and sometimes raw email addresses (`apps/auth` carries ca's originals verbatim),
+ * so they are attacker-adjacent strings of unbounded shape. They are HASHED into the key
+ * rather than interpolated: a fixed-length hex suffix cannot collide with another key,
+ * cannot escape the namespace, and cannot smuggle a `:` that makes one person's row look
+ * like another's.
+ *
+ * **3. There is no seed.** `MASTER_LOCK_SEED` arms an app-wide lock from the vault's own
+ * record; per-person there is nothing sensible to seed a *stranger's* password from, and
+ * an env var that pre-set someone's password would be exactly the "one credential opens
+ * everybody" shape this replaces. A principal with no record is `awaitingEnrollment` —
+ * locked, and offered the choose-a-password form.
+ */
+import { createHash } from "node:crypto";
+import { MasterLock, type MasterLockStore, readRecord } from "./masterLock";
+
+/** Namespace for every per-person record, so one glance at the table says what they are. */
+export const MASTER_LOCK_PRINCIPAL_KEY_PREFIX = "master_lock:principal:";
+
+/**
+ * The storage key for one principal.
+ *
+ * SHA-256 hex of the id — see property 2 in the module note. It is not a security
+ * boundary (the id is not a secret and the hash is not salted); it is a SHAPE boundary,
+ * which is the thing that was actually at risk.
+ */
+export function masterLockPrincipalKey(principalId: string): string {
+	const digest = createHash("sha256").update(principalId, "utf8").digest("hex");
+	return `${MASTER_LOCK_PRINCIPAL_KEY_PREFIX}${digest}`;
+}
+
+export interface MasterLockDirectoryOptions {
+	/**
+	 * The app's key/value surface. One row per principal, written under
+	 * {@link masterLockPrincipalKey} — no migration, same shape as the app-wide record.
+	 */
+	kv: {
+		get(key: string): string | null | undefined;
+		set(key: string, value: string): void;
+	};
+	/** Injected clock. The tests drive it; production omits it. */
+	now?: () => number;
+	/** Where to log a rotation or a first enrollment. Receives the principal LABEL. */
+	log?: (line: string) => void;
+}
+
+/**
+ * Every person's lock, made on first sight and held for the process's life.
+ *
+ * Locks live in memory alongside their unlock, exactly as the single-app engine's do, so
+ * a restart re-locks everybody. That is the correct default for a wall whose whole risk
+ * model is "this browser is somewhere it should not be".
+ */
+export class MasterLockDirectory {
+	private readonly locks = new Map<string, MasterLock>();
+	private readonly options: MasterLockDirectoryOptions;
+
+	constructor(options: MasterLockDirectoryOptions) {
+		this.options = options;
+	}
+
+	/**
+	 * This principal's lock, created on first sight.
+	 *
+	 * 🔴 `principalId` must come from the request's own verified session and never from a
+	 * header, a query parameter or a body field. The guard's `resolve` is the one place
+	 * that decides it; see property 1 in the module note.
+	 */
+	for(principalId: string): MasterLock {
+		const existing = this.locks.get(principalId);
+		if (existing) return existing;
+		const key = masterLockPrincipalKey(principalId);
+		const { kv } = this.options;
+		const store: MasterLockStore = {
+			read: () => kv.get(key) ?? null,
+			write: (json) => kv.set(key, json),
+		};
+		const lock = new MasterLock({
+			store,
+			enrollable: true,
+			...(this.options.now ? { now: this.options.now } : {}),
+			...(this.options.log
+				? { log: (line: string) => this.options.log?.(`[${principalId}] ${line}`) }
+				: {}),
+		});
+		this.locks.set(principalId, lock);
+		return lock;
+	}
+
+	/** Has this principal chosen a master password? Reads storage, so it is true of a
+	 *  person who enrolled in a previous boot and has not been seen in this one. */
+	isEnrolled(principalId: string): boolean {
+		return this.for(principalId).configured;
+	}
+
+	/**
+	 * Install a PRE-DERIVED record for one principal, if and only if it has none.
+	 *
+	 * ── What this is for, and what it is not ───────────────────────────────────
+	 * A machine account — `apps/orch`'s deploy smoke is the only one so far. Its master
+	 * password lives 0600 on the owner's Mac, so there is no browser to type it in, and
+	 * the alternative shapes are both worse: letting the smoke `POST /__lock/enroll` makes
+	 * it WRITE to a live production site (which `scripts/smokeCleanup.test.ts` refuses, on
+	 * the owner's rule), and giving the smoke a bypass makes the wall unproven.
+	 *
+	 * 🔴 It is NOT an opening and cannot become one. `json` is `{kdf, verifierHash}` —
+	 * already derived, the same shape `MASTER_LOCK_SEED` has carried since 2026-08-15 — so
+	 * no password passes through this process, and whoever unlocks still has to present a
+	 * verifier that matches. Seeding an account only decides that it HAS a password, never
+	 * that anybody may skip it.
+	 *
+	 * Refuses when a record already exists, so it can never rotate one out from under the
+	 * person holding it. Returns whether it installed anything.
+	 */
+	seed(principalId: string, json: string): boolean {
+		const key = masterLockPrincipalKey(principalId);
+		const { kv } = this.options;
+		if (readRecord(kv.get(key) ?? null)) return false;
+		const record = readRecord(json);
+		if (!record) return false;
+		kv.set(key, JSON.stringify(record));
+		// Drop any lock built before the row existed, so `for()` re-reads it rather than
+		// serving the cached "unconfigured" one. Nothing can be unlocked yet by definition.
+		this.locks.delete(principalId);
+		return true;
+	}
+
+	/** Lock every open session — the "I am handing this laptop over" button, fleet-wide.
+	 *  Only ever reaches principals seen since boot, which is all that can be unlocked. */
+	lockAll(): void {
+		for (const lock of this.locks.values()) lock.lock();
+	}
+
+	/** How many principals hold a live unlock right now. For `/healthz` and the boot log;
+	 *  a COUNT discloses nothing about who. */
+	unlockedCount(): number {
+		let count = 0;
+		for (const lock of this.locks.values()) if (lock.unlocked) count += 1;
+		return count;
+	}
+
+	/** Drop every in-memory lock — for tests between cases. */
+	resetForTest(): void {
+		for (const lock of this.locks.values()) lock.resetForTest();
+		this.locks.clear();
+	}
+}

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+import { deriveMasterLockVerifier } from "cursedbelt-core/master-lock/kdf";
+import { MasterLock, readRecord } from "./masterLock";
+import { createMemoryMasterLockStore } from "./store";
+import { generateStagePassword, mintMasterLockSeed, serializeMasterLockSeed } from "./seed";
+
+describe("mintMasterLockSeed", () => {
+	// The whole point: a seed minted here must UNLOCK, through the real engine,
+	// under the real derivation. Anything less is a hash that looks plausible.
+	it("produces a record the lock actually opens with that password", async () => {
+		const record = await mintMasterLockSeed("stage-password-1", { idleMs: 60_000 });
+		const lock = new MasterLock({
+			store: createMemoryMasterLockStore(),
+			seedJson: serializeMasterLockSeed(record),
+		});
+		expect(lock.configured).toBe(true);
+		const verifier = await deriveMasterLockVerifier("stage-password-1", record.kdf);
+		const result = await lock.unlock(verifier);
+		expect(result.ok).toBe(true);
+		expect(lock.unlocked).toBe(true);
+	});
+
+	it("does not open with a different password", async () => {
+		const record = await mintMasterLockSeed("stage-password-1");
+		const lock = new MasterLock({
+			store: createMemoryMasterLockStore(),
+			seedJson: serializeMasterLockSeed(record),
+		});
+		const wrong = await deriveMasterLockVerifier("stage-password-2", record.kdf);
+		expect((await lock.unlock(wrong)).ok).toBe(false);
+	});
+
+	it("gives every mint its own salt, so two stages are not one lock", async () => {
+		const a = await mintMasterLockSeed("stage-password-1");
+		const b = await mintMasterLockSeed("stage-password-1");
+		expect(a.kdf.salt).not.toBe(b.kdf.salt);
+		expect(a.verifierHash).not.toBe(b.verifierHash);
+	});
+
+	it("refuses a password short enough to make the lock decorative", async () => {
+		await expect(mintMasterLockSeed("short")).rejects.toThrow(/at least 8/);
+	});
+});
+
+describe("serializeMasterLockSeed", () => {
+	// 🔴 The argon2 hash contains `$` and the file is sourced by a shell. An
+	// unquoted value arrives with `$argon2id` expanded to nothing.
+	it("single-quotes the blob, and readRecord strips exactly that pair", async () => {
+		const record = await mintMasterLockSeed("stage-password-1");
+		const env = serializeMasterLockSeed(record);
+		expect(env.startsWith("'")).toBe(true);
+		expect(env.endsWith("'")).toBe(true);
+		expect(readRecord(env)?.verifierHash).toBe(record.verifierHash);
+	});
+});
+
+describe("generateStagePassword", () => {
+	it("avoids the characters that get misread when typed by hand", () => {
+		for (let i = 0; i < 40; i += 1) {
+			expect(generateStagePassword()).not.toMatch(/[l1O0]/);
+		}
+	});
+
+	it("is long enough to seed a lock", async () => {
+		const password = generateStagePassword();
+		expect(password.length).toBeGreaterThanOrEqual(20);
+		await expect(mintMasterLockSeed(password)).resolves.toBeTruthy();
+	});
+});