cursedbelt-server 1.0.0

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

@@ -0,0 +1,627 @@
+/**
+ * The sitewide MASTER LOCK — a second wall, in front of a whole app, that the app's own
+ * sign-in cannot open.
+ *
+ * ── What the owner asked for (2026-08-15, their words) ──────────────────────
+ * *"I want to be able to share my laptop without certain apps being at risk of other people
+ * viewing them while I am still logged in … Until the master password is entered a user
+ * logged in as me cannot see anything about the site, not even text or images, nothing at
+ * all."*
+ *
+ * So: standard auth still happens FIRST and is unchanged. This sits behind it. A request
+ * that has passed the app's own gate and carries no live unlock is answered with the lock
+ * page (for a document) or a 401 (for anything else) — never with the app.
+ *
+ * ── 🔴 BE HONEST ABOUT WHAT THIS BUYS ───────────────────────────────────────
+ * In `apps/vault` the master password IS the encryption key: the server holds ciphertext
+ * and a total breach yields noise. **This cannot work that way, and must never be described
+ * as if it does.** The apps it guards serve their bytes to browsers; those bytes are
+ * plaintext at rest by nature. This is a LOCK ON THE DOOR — an unlocked laptop, a borrowed
+ * phone, a hijacked session still cannot open the UI. The owner said the same thing back:
+ * *"I am aware that a tech savvy user of my laptop could still get around it by changing
+ * code. This work does not worry about that, we are only securing app UI access."*
+ * The same distinction is written in `fleet/rules/owner-uis-are-one-ui.md` and in
+ * binary-server's `src/admin/passcode.ts`, which is this feature's nearest relative.
+ *
+ * ── The four decisions that are not obvious ─────────────────────────────────
+ *
+ * **1. Sessions live in MEMORY, so a restart re-locks.** The correct default for a surface
+ * whose whole risk model is "the browser is somewhere it should not be". Same call as the
+ * inspector passcode.
+ *
+ * **2. The idle clock is slid by INTERACTION, never by traffic.** The owner said *"if I
+ * leave the site up but don't interact with it"* — and every app here polls. Sliding on any
+ * request would let a background refetch hold the lock open all night with nobody at the
+ * desk, which is exactly the scenario the feature exists for. So an ordinary request only
+ * READS the clock; `touch()` — reached solely by `POST /__lock/ping`, which the browser
+ * sends on real pointer/key/touch activity — is the only thing that moves it.
+ *
+ * **3. The password is never stored, and this process never sees it.** The browser derives
+ * `verifier = PBKDF2(KEK ‖ password)` (see `../../core/master-lock/kdf.ts`); the record
+ * holds `argon2id(verifier)`. It is seeded from the vault's OWN record so the owner's
+ * existing vault master password works on day one without anyone knowing it.
+ *
+ * **4. Every refusal is the same refusal.** Wrong verifier, throttled, unconfigured and
+ * "no unlock" answer with the identical status and body, and a dummy argon2 verify runs on
+ * every path so the TIMING does not separate them either. The one thing that varies is the
+ * `retryAfterMs` a throttled caller is told — which they already know, since they are the
+ * one who has been guessing.
+ */
+import {
+	type MasterLockKdfParams,
+	type MasterLockStatus,
+	clampIdleMs,
+	isMasterLockKdfParams,
+	windowRemaining,
+} from "cursedbelt-core/master-lock";
+
+/** The persisted record. Three public values — none of them is a secret, and the two that
+ *  look like one are a salt and a one-way hash. */
+export interface MasterLockRecord {
+	kdf: MasterLockKdfParams;
+	/** `argon2id(verifier)`. The PHC string is self-describing, so there is no salt column. */
+	verifierHash: string;
+	/** The owner's configured idle timeout for THIS app. */
+	idleMs: number;
+}
+
+/**
+ * Where the record rests. One blob, so an app can keep it in whatever it already has —
+ * binary-server's `settings` table, a satellite's `app_settings` row, a JSON file.
+ *
+ * Synchronous because every consumer's storage is `bun:sqlite`, and an async read here
+ * would make the request-path guard async for no reason any caller could observe.
+ */
+export interface MasterLockStore {
+	read(): string | null;
+	write(json: string): void;
+}
+
+export interface MasterLockOptions {
+	store: MasterLockStore;
+	/**
+	 * The BOOTSTRAP record, as JSON, used only when the store is empty — the same shape as
+	 * {@link MasterLockRecord} with `idleMs` optional.
+	 *
+	 * It arrives as `MASTER_LOCK_SEED` in the app's own 0600 deploy-secrets env file,
+	 * copied from the vault's own `vault_keys` row, so the lock is armed from the first
+	 * request rather than from whenever somebody remembers to set one. A lock that has to
+	 * be configured before it protects anything protects nothing on the day it matters —
+	 * the reasoning `bootstrapPasscode` records in binary-server.
+	 *
+	 * A change made in the app afterwards WINS, permanently: this is consulted only when
+	 * the store has nothing.
+	 */
+	seedJson?: string | null;
+	/** Injected clock. The tests drive it; production omits it. */
+	now?: () => number;
+	/**
+	 * Called whenever this app flips locked ⇄ unlocked, including when the idle timer fires.
+	 *
+	 * `binary-server`'s inspector needs it: its `/` is a Bun `HTMLBundle` matched BEFORE the
+	 * `fetch` handler, so the only way to keep the app shell off the wire while locked is to
+	 * swap that route with `server.reload()` — which needs a signal, not a poll.
+	 */
+	onLockedChange?: (locked: boolean) => void;
+	/** Where to log the few things worth a line (a seed adopted, a rotation). */
+	log?: (line: string) => void;
+	/**
+	 * PER-PERSON mode. Inverts decision 5 below: with no record this lock reads as
+	 * LOCKED rather than open, and {@link MasterLock.enroll} is the way out.
+	 *
+	 * 🔴 It is an option and not the default because the two modes fail in opposite
+	 * directions, and each is right for exactly one situation:
+	 *
+	 *  - **App-wide (`false`, the default).** One record for the whole app, seeded
+	 *    from `MASTER_LOCK_SEED`. Unconfigured must read as OPEN, or a missing seed
+	 *    bricks an app nobody can get into — see `unlocked`.
+	 *  - **Per-person (`true`).** One record per signed-in account, and there is no
+	 *    seed: each person chooses their own. Unconfigured must read as LOCKED,
+	 *    because "this person has not chosen a password yet" is the state of every
+	 *    NEW account, and treating it as open would mean the wall admits everybody
+	 *    it has never met — the precise opposite of the feature.
+	 *
+	 * Nothing bricks in per-person mode, because enrollment is always available to
+	 * a principal with no record. That is what makes failing closed affordable here
+	 * and unaffordable there.
+	 */
+	enrollable?: boolean;
+}
+
+/** What an unlock attempt answers. `ok` carries the token to set as a cookie. */
+export type MasterLockUnlockResult =
+	| { ok: true; token: string }
+	| { ok: false; retryAfterMs: number };
+
+/** What choosing a FIRST master password answers. `ok` carries the unlock, so the
+ *  person who just set it is not asked to type it again in the next breath. */
+export type MasterLockEnrollResult =
+	| { ok: true; token: string }
+	| { ok: false; reason: "not-enrollable" | "already-configured" | "invalid" };
+
+const TOKEN_BYTES = 24;
+
+/**
+ * One app's lock. Constructed once at boot and held for the process's life.
+ *
+ * There is exactly ONE unlock at a time, not one per browser session. That is deliberate
+ * and it is the owner's model: *"entering it in one site will only apply it to that site"* —
+ * the unit is the SITE, and these apps have exactly one user. Minting per-session unlocks
+ * would mean the phone in someone else's hand stays open after the owner locks the desk,
+ * which inverts the manual-lock requirement (*"then no one can see anything until the master
+ * password is entered again"*).
+ */
+export class MasterLock {
+	private readonly store: MasterLockStore;
+	private readonly now: () => number;
+	private readonly onLockedChange: ((locked: boolean) => void) | undefined;
+	private readonly log: (line: string) => void;
+	/** Per-person mode — see {@link MasterLockOptions.enrollable}. */
+	private readonly enrollable: boolean;
+
+	private record: MasterLockRecord | null;
+	/**
+	 * The live unlocks: token → when that token last saw real interaction. Moved only by
+	 * {@link touch}.
+	 *
+	 * 🔴 A MAP, not one session, since 2026-08-25 — and the reason is the per-person mode.
+	 * App-wide, one unlock was right: one person, one site, and the owner's *"entering it
+	 * in one site will only apply it to that site"*. Per person it is wrong twice over.
+	 * The owner asked to *"put in prompts for the orch and monitor it from our phones and
+	 * other devices"* — so the desk and the phone are both his, both open at once, and a
+	 * single-token model would have each unlock silently evict the other. And the guard
+	 * now demands a PRESENTED token rather than reading `unlocked` (see the guard's own
+	 * note), which is only possible if every device that typed the password holds one.
+	 *
+	 * {@link lock} still clears them ALL, which is what keeps the owner's original
+	 * requirement true: *"then no one can see anything until the master password is
+	 * entered again"* — one button, every device.
+	 */
+	private sessions = new Map<string, number>();
+	private expiryTimer: ReturnType<typeof setTimeout> | null = null;
+
+	private failures = 0;
+	private lastFailureAt = 0;
+
+	constructor(options: MasterLockOptions) {
+		this.store = options.store;
+		this.now = options.now ?? Date.now;
+		this.onLockedChange = options.onLockedChange;
+		this.log = options.log ?? (() => undefined);
+		this.enrollable = options.enrollable === true;
+		this.record = readRecord(this.store.read());
+		if (!this.record && options.seedJson) {
+			const seeded = readRecord(options.seedJson);
+			if (seeded) {
+				this.record = seeded;
+				this.store.write(JSON.stringify(seeded));
+				this.log("master lock: seeded from MASTER_LOCK_SEED (the vault's master password)");
+			} else {
+				// Loud, because the alternative is an app that boots with no lock and looks
+				// exactly like an app that was never meant to have one.
+				this.log("🔴 master lock: MASTER_LOCK_SEED is set but unusable — the lock is NOT armed");
+			}
+		}
+	}
+
+	/** Is a master password set at all? An app with `false` here refuses nothing. */
+	get configured(): boolean {
+		return this.record !== null;
+	}
+
+	/** The params the browser must derive under, or null. Public by design. */
+	get kdf(): MasterLockKdfParams | null {
+		return this.record?.kdf ?? null;
+	}
+
+	get idleMs(): number {
+		return this.record?.idleMs ?? clampIdleMs(undefined);
+	}
+
+	/** Is this lock in per-person mode? */
+	get isEnrollable(): boolean {
+		return this.enrollable;
+	}
+
+	/** May a first password be chosen right now? Per-person mode, and no record yet. */
+	get awaitingEnrollment(): boolean {
+		return this.enrollable && this.record === null;
+	}
+
+	/**
+	 * Is the site open right now?
+	 *
+	 * 🔴 An UNCONFIGURED app-wide lock reads as UNLOCKED, and that is the deliberate
+	 * choice. A lock with no password cannot be opened by anybody, including the owner —
+	 * failing closed would brick an app rather than protect it, and this guards a UI whose
+	 * data is already behind the app's own owner-only auth. `/healthz` reports
+	 * `configured` so a smoke can catch the state externally instead of the owner
+	 * discovering it.
+	 *
+	 * 🔴 In PER-PERSON mode the same reasoning runs the other way and this reads as
+	 * LOCKED. Nobody is bricked — {@link enroll} is open to a principal with no record —
+	 * and "has not chosen a password yet" describes every new account, so opening for it
+	 * would admit exactly the people the wall exists to stop. See
+	 * {@link MasterLockOptions.enrollable}.
+	 */
+	get unlocked(): boolean {
+		if (!this.record) return !this.enrollable;
+		this.sweep();
+		return this.sessions.size > 0;
+	}
+
+	/** Milliseconds of idleness left before the unlock lapses; 0 when locked. */
+	/** Milliseconds of idleness left before the LONGEST-lived unlock lapses; 0 when none
+	 *  is live. The status page counts down with it, so it is the most generous of the
+	 *  open devices rather than an arbitrary one. */
+	get remainingMs(): number {
+		if (!this.record) return 0;
+		this.sweep();
+		if (this.sessions.size === 0) return 0;
+		const newest = Math.max(...this.sessions.values());
+		return Math.max(0, newest + this.record.idleMs - this.now());
+	}
+
+	status(): MasterLockStatus {
+		return {
+			configured: this.configured,
+			enrollable: this.awaitingEnrollment,
+			locked: !this.unlocked,
+			kdf: this.kdf,
+			idleMs: this.idleMs,
+			remainingMs: this.remainingMs,
+			retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, this.now()),
+		};
+	}
+
+	/** Does this request carry the live unlock? The cookie, or the header for a caller with
+	 *  no cookie jar. */
+	presents(req: Request): boolean {
+		this.sweep();
+		if (this.sessions.size === 0) return false;
+		// Compared against every live token in constant time, and deliberately WITHOUT a
+		// `Map.has` shortcut: a hash lookup on attacker-supplied bytes leaks by timing what
+		// the comparison is written to hide.
+		for (const presented of presentedTokens(req)) {
+			for (const live of this.sessions.keys()) {
+				if (constantTimeEqual(presented, live)) return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * Evaluate a verifier and, on a match, mint the unlock.
+	 *
+	 * Runs an argon2 verify on EVERY path — no record, throttled, wrong — so the answer's
+	 * latency says nothing the answer itself does not.
+	 */
+	async unlock(verifier: string): Promise<MasterLockUnlockResult> {
+		const now = this.now();
+		const retryAfterMs = windowRemaining(this.failures, this.lastFailureAt, now);
+		const record = this.record;
+		// 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.
+		const genuine =
+			retryAfterMs === 0 && record ? await verifyArgon(verifier, record.verifierHash) : null;
+		await equalize(verifier);
+
+		if (retryAfterMs > 0) return { ok: false, retryAfterMs };
+		// `null` is a hash this build cannot parse. It is NOT a wrong password, and saying so
+		// is what stops the owner re-typing a correct password forever — the exact day
+		// `apps/collections` lost to a quoted hash in its secrets file.
+		if (genuine === null) {
+			if (record) this.log("🔴 master lock: the stored verifier hash cannot be parsed — nothing can unlock");
+			return { ok: false, retryAfterMs: 0 };
+		}
+		if (!genuine) {
+			this.failures += 1;
+			this.lastFailureAt = now;
+			return { ok: false, retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, now) };
+		}
+
+		this.failures = 0;
+		this.lastFailureAt = 0;
+		const token = randomToken();
+		const wasLocked = this.sessions.size === 0;
+		// ADDED, never replacing: the desk and the phone are the same person and both stay
+		// open. See the `sessions` note.
+		this.sessions.set(token, now);
+		this.scheduleExpiry();
+		if (wasLocked) this.onLockedChange?.(false);
+		return { ok: true, token };
+	}
+
+	/**
+	 * Choose the FIRST master password for this lock — per-person mode only.
+	 *
+	 * ── Why this is not a hole ─────────────────────────────────────────────────
+	 * It looks like "anyone who can reach the endpoint sets the password", and the three
+	 * things that make it not are all checked here rather than at the caller:
+	 *
+	 *  1. **It refuses once a record exists.** There is no overwrite branch and no force
+	 *     flag; rotation is {@link change}, which demands the current password re-typed.
+	 *     So this can only ever create the password that was never set.
+	 *  2. **It refuses outside per-person mode**, so mounting the route in an app-wide
+	 *     app cannot silently arm a lock the owner did not choose.
+	 *  3. **The principal is resolved from the app's own session, not from the request
+	 *     body.** That is the guard's job (`resolve`), and it is why a stranger cannot
+	 *     enroll on somebody else's behalf: to reach this at all they must already hold a
+	 *     live signed-in session for the account they are enrolling, and if they hold
+	 *     that, the master lock was never what was standing between them and the app.
+	 *
+	 * The unlock is minted with the record, deliberately: being asked to type a password
+	 * back at the person who just chose it, twice, teaches them the app is broken.
+	 */
+	async enroll(input: {
+		kdf: MasterLockKdfParams;
+		verifier: string;
+	}): Promise<MasterLockEnrollResult> {
+		if (!this.enrollable) return { ok: false, reason: "not-enrollable" };
+		// Re-read the store rather than trusting the field: two tabs can submit the
+		// choose-a-password form at once, and the second must lose rather than replace.
+		if (this.record || readRecord(this.store.read())) {
+			this.record ??= readRecord(this.store.read());
+			return { ok: false, reason: "already-configured" };
+		}
+		if (!isMasterLockKdfParams(input.kdf) || typeof input.verifier !== "string" || !input.verifier) {
+			return { ok: false, reason: "invalid" };
+		}
+		const next: MasterLockRecord = {
+			kdf: input.kdf,
+			verifierHash: await Bun.password.hash(input.verifier, { algorithm: "argon2id" }),
+			idleMs: clampIdleMs(undefined),
+		};
+		this.record = next;
+		this.store.write(JSON.stringify(next));
+		this.failures = 0;
+		this.lastFailureAt = 0;
+		const token = randomToken();
+		this.sessions.set(token, this.now());
+		this.scheduleExpiry();
+		this.onLockedChange?.(false);
+		this.log("master lock: a first master password was chosen");
+		return { ok: true, token };
+	}
+
+	/**
+	 * Record real user interaction. The ONE thing that moves the idle clock — see decision 2
+	 * in the module note.
+	 *
+	 * A no-op on a lapsed session, deliberately: activity must never REVIVE an unlock, or a
+	 * page left open would resurrect itself the moment the cat walked across the keyboard.
+	 */
+	touch(req: Request): boolean {
+		this.sweep();
+		// Slides only the token that was presented. Two devices idle independently, so the
+		// phone left on the counter locks on its own schedule while the desk stays open —
+		// which is decision 2 applied per device rather than per person.
+		for (const presented of presentedTokens(req)) {
+			for (const live of this.sessions.keys()) {
+				if (constantTimeEqual(presented, live)) {
+					this.sessions.set(live, this.now());
+					this.scheduleExpiry();
+					return true;
+				}
+			}
+		}
+		return false;
+	}
+
+	/** The manual lock — the owner's *"I want a lock option to turn the site back to needing
+	 *  the master password"*. Also what a change of password does to every open page. */
+	lock(): void {
+		if (this.sessions.size === 0) return;
+		// EVERY device this person has open, not the one that pressed the button. The
+		// owner's requirement is "no one can see anything until the master password is
+		// entered again", and a lock that left the phone open would not be that.
+		this.sessions.clear();
+		this.clearExpiry();
+		this.onLockedChange?.(true);
+	}
+
+	/**
+	 * Rotate this app's master password. Requires the CURRENT one, re-typed — an open session
+	 * proves somebody is at the keyboard, not that it is the owner, and the whole feature
+	 * exists for the minutes when it is not.
+	 *
+	 * Per-app by construction: the record this writes is this app's own. The owner asked for
+	 * exactly that, and for there to be no way to change them all at once.
+	 */
+	async change(input: {
+		currentVerifier: string;
+		kdf: MasterLockKdfParams;
+		verifier: string;
+	}): Promise<{ ok: true } | { ok: false; reason: "wrong" | "invalid" | "unconfigured" }> {
+		const record = this.record;
+		if (!record) return { ok: false, reason: "unconfigured" };
+		if (!isMasterLockKdfParams(input.kdf) || typeof input.verifier !== "string" || !input.verifier) {
+			return { ok: false, reason: "invalid" };
+		}
+		const genuine = await verifyArgon(input.currentVerifier, record.verifierHash);
+		await equalize(input.currentVerifier);
+		if (genuine === null) return { ok: false, reason: "unconfigured" };
+		if (!genuine) return { ok: false, reason: "wrong" };
+
+		const next: MasterLockRecord = {
+			kdf: input.kdf,
+			verifierHash: await Bun.password.hash(input.verifier, { algorithm: "argon2id" }),
+			idleMs: record.idleMs,
+		};
+		this.record = next;
+		this.store.write(JSON.stringify(next));
+		// Every open page dies with the old password — otherwise rotating it after a bad day
+		// leaves the session that worried you still holding the door.
+		this.lock();
+		this.log("master lock: master password rotated for this app");
+		return { ok: true };
+	}
+
+	/** The owner's *"customizable by me"* idle timeout, clamped to the usable band. */
+	setIdleMs(value: number): number {
+		const record = this.record;
+		const idleMs = clampIdleMs(value);
+		if (!record) return idleMs;
+		this.record = { ...record, idleMs };
+		this.store.write(JSON.stringify(this.record));
+		this.scheduleExpiry();
+		return idleMs;
+	}
+
+	/** Drop the in-memory unlock without notifying — for tests between cases. */
+	resetForTest(): void {
+		this.sessions.clear();
+		this.failures = 0;
+		this.lastFailureAt = 0;
+		this.clearExpiry();
+	}
+
+	/** Retire a session whose idle window has passed. Called on every read of the state, so
+	 *  correctness never depends on the timer having fired. */
+	private sweep(): void {
+		const record = this.record;
+		if (!record || this.sessions.size === 0) return;
+		const now = this.now();
+		const wasOpen = this.sessions.size > 0;
+		for (const [token, lastActivityAt] of this.sessions) {
+			// Each device expires on its OWN clock, so one going idle never shortens another.
+			if (now - lastActivityAt > record.idleMs) this.sessions.delete(token);
+		}
+		if (wasOpen && this.sessions.size === 0) {
+			this.clearExpiry();
+			this.onLockedChange?.(true);
+		}
+	}
+
+	/**
+	 * Wake up exactly when the unlock lapses.
+	 *
+	 * The sweep above already makes every READ correct, so this is not what enforces the
+	 * timeout — it is what lets `onLockedChange` fire with nobody asking, which the
+	 * binary-server route swap needs. `unref` where the runtime has it, so a timer never
+	 * keeps a process alive.
+	 */
+	private scheduleExpiry(): void {
+		this.clearExpiry();
+		const record = this.record;
+		if (!record || this.sessions.size === 0) return;
+		// The SOONEST lapse, so `onLockedChange` cannot be late for the device that goes
+		// first; the sweep it triggers re-arms for whichever is next.
+		const soonest = Math.min(...this.sessions.values());
+		const due = soonest + record.idleMs - this.now();
+		const timer = setTimeout(() => {
+			this.expiryTimer = null;
+			this.sweep();
+		}, Math.max(0, due) + 1);
+		(timer as { unref?: () => void }).unref?.();
+		this.expiryTimer = timer;
+	}
+
+	private clearExpiry(): void {
+		if (this.expiryTimer !== null) {
+			clearTimeout(this.expiryTimer);
+			this.expiryTimer = null;
+		}
+	}
+}
+
+/** Parse a stored/seeded record, or null. Every field is validated because all three
+ *  sources — a database, an env seed, an older build — are outside this module. */
+export function readRecord(json: string | null | undefined): MasterLockRecord | null {
+	if (!json) return null;
+	let parsed: unknown;
+	try {
+		// 🔴 `unquote` FIRST, on the whole blob. The seed is written into a 0600 file that a
+		// shell sources, and the value contains `$` (an argon2id hash does), so it is written
+		// single-quoted — correctly. Every reader in the fleet strips that pair, but "every
+		// reader" has been wrong before: `apps/collections` shipped a quoted hash to prod in
+		// 2026-08-12 and spent a day being told its correct passphrase was wrong. A JSON
+		// document can never legitimately begin with a quote character, so this guesses at
+		// nothing and closes the class rather than the instance.
+		parsed = JSON.parse(unquote(json));
+	} catch {
+		return null;
+	}
+	if (parsed === null || typeof parsed !== "object") return null;
+	const value = parsed as Record<string, unknown>;
+	if (!isMasterLockKdfParams(value.kdf)) return null;
+	const hash = typeof value.verifierHash === "string" ? unquote(value.verifierHash) : "";
+	if (!hash.startsWith("$argon2")) return null;
+	return { kdf: value.kdf, verifierHash: hash, idleMs: clampIdleMs(value.idleMs) };
+}
+
+/**
+ * Strip a wrapping quote pair.
+ *
+ * An argon2id PHC string contains `$`, so it is written SINGLE-QUOTED into the 0600 secrets
+ * file that a shell sources — and a `cut -d= -f2-` somewhere in the handover keeps the
+ * quotes. `apps/collections` lost a day to exactly that in 2026-08-12: the live site
+ * answered "that is not the passphrase" to the correct passphrase while its health check
+ * reported the lock armed. A hash can never legitimately begin with a quote, so nothing is
+ * guessed at here.
+ */
+function unquote(value: string): string {
+	const trimmed = value.trim();
+	const first = trimmed[0];
+	if ((first === '"' || first === "'") && trimmed.endsWith(first) && trimmed.length > 1) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+/** `true`/`false` for a verdict, `null` for a hash this build cannot parse — a distinction
+ *  the caller must keep, because the two send the owner to different places. */
+async function verifyArgon(candidate: string, hash: string): Promise<boolean | null> {
+	try {
+		return await Bun.password.verify(candidate, hash);
+	} catch {
+		return null;
+	}
+}
+
+let equalizerHash: Promise<string> | null = null;
+async function equalize(candidate: string): Promise<void> {
+	equalizerHash ??= Bun.password.hash("master-lock-timing-equalizer", { algorithm: "argon2id" });
+	await Bun.password.verify(candidate || "x", await equalizerHash).catch(() => false);
+}
+
+function randomToken(): string {
+	const bytes = new Uint8Array(TOKEN_BYTES);
+	crypto.getRandomValues(bytes);
+	return Buffer.from(bytes).toString("base64url");
+}
+
+/**
+ * Every token this request offers — the header a non-browser caller uses, and EVERY
+ * `master_lock*` cookie in the jar.
+ *
+ * 🔴 Every one of them, not just this app's: a browser on `localhost` holds one cookie per
+ * locked app (see `masterLockCookieName` for why the name has to be per app), and this
+ * function has no idea which name belongs to the instance asking. Offering them all is
+ * safe and is not a widening — each candidate still has to survive the constant-time
+ * comparison against THIS lock's own live tokens, which are per-instance random. A foreign
+ * app's token is simply a token that does not match, exactly like a stale one.
+ */
+function presentedTokens(req: Request): string[] {
+	const out: string[] = [];
+	const header = req.headers.get("x-master-lock");
+	if (header) out.push(header);
+	const cookie = req.headers.get("cookie");
+	if (cookie) {
+		for (const part of cookie.split(";")) {
+			const [name, ...rest] = part.trim().split("=");
+			if (name === "master_lock" || name?.startsWith("master_lock_")) out.push(rest.join("="));
+		}
+	}
+	return out;
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+	const x = Buffer.from(a);
+	const y = Buffer.from(b);
+	// A length difference is already a non-match, and `timingSafeEqual` throws on one.
+	if (x.length !== y.length) return false;
+	let diff = 0;
+	for (let i = 0; i < x.length; i += 1) diff |= x[i] ^ y[i];
+	return diff === 0;
+}