cursedbelt-server 1.0.0

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

@@ -0,0 +1,290 @@
+/**
+ * The guard — one decision function, so a Hono app and a bare `Bun.serve` handler cannot
+ * end up enforcing two different rules.
+ *
+ * `handle(req)` answers a `Response` when it has taken responsibility for the request, and
+ * `null` when the app should serve it as usual. That shape is what lets it be middleware in
+ * one app and an early `return` in another without either of them re-deciding anything.
+ *
+ * 🔴 Registration order is the security property, exactly as it is for the SSO gate this
+ * sits behind. Mount it so that it runs BEFORE any route that serves content, and AFTER
+ * whatever proves the caller is allowed in the building at all — the master password is a
+ * second wall, not a replacement for the first.
+ */
+import {
+	MASTER_LOCK_PATHS,
+	MASTER_LOCK_PREFIX,
+	MASTER_LOCK_STATE_HEADER,
+	masterLockCookieName,
+} from "cursedbelt-core/master-lock";
+import { LOCK_SCRIPT, LOCK_STYLE, type LockPageOptions, lockPageHtml } from "./lockPage";
+import type { MasterLock } from "./masterLock";
+
+export interface MasterLockGuardOptions extends LockPageOptions {
+	/**
+	 * The lock this guard enforces.
+	 *
+	 * A {@link MasterLock} for an app with one app-wide password (collections, the
+	 * binary-server inspector). A FUNCTION for an app where each person has their own
+	 * (`principals.ts`): it is handed the request and returns that caller's lock.
+	 *
+	 * 🔴 The function must resolve the principal from the request's own verified session
+	 * and NOTHING else. A resolver that reads a header, a query parameter or a body field
+	 * hands the caller the choice of whose lock to be measured against, which is the one
+	 * way this feature can be turned inside out. Returning `null` means "no principal" —
+	 * the guard then stands aside for ordinary paths (the app's own sign-in owns the
+	 * request) and refuses `/__lock/*` outright, since there is nobody to unlock for.
+	 */
+	lock: MasterLock | ((req: Request) => MasterLock | null);
+	/**
+	 * Paths that stay reachable while locked, beyond `/__lock/*`.
+	 *
+	 * 🔴 This is where a MACHINE surface is kept out of the lock, and getting it wrong is
+	 * the one way this feature can break something else. binary-server's inspector is a
+	 * UI and is locked whole; binary-server's STORE serves the fleet's bytes and is a
+	 * different process that never mounts this at all. Within one process, a health check
+	 * or a token-authenticated ingest route belongs here — a page does not.
+	 */
+	allow?: (url: URL, req: Request) => boolean;
+	/**
+	 * What makes this app's unlock cookie ITS OWN — `master_lock_<appKey>`.
+	 *
+	 * 🔴 Set it on every app that can ever share a hostname with another locked app, which
+	 * on this fleet means every app: they are all `localhost:<port>` on the owner's Mac, and
+	 * a cookie is scoped by HOST, not by origin. Left unset the cookie is the bare
+	 * `master_lock`, and two such apps overwrite each other's token — see
+	 * `masterLockCookieName` for what that silently breaks. Defaults to {@link appLabel},
+	 * so an app that already names itself is fixed without being changed.
+	 */
+	appKey?: string;
+	/**
+	 * Is this connection HTTPS, so the cookie may carry `Secure`?
+	 *
+	 * Defaults to reading `x-forwarded-proto` then the URL — right for both a satellite
+	 * behind nginx and a loopback daemon speaking plain http, where a `Secure` cookie would
+	 * simply never be stored and the site could never be unlocked.
+	 */
+	secure?: (url: URL, req: Request) => boolean;
+}
+
+const noStore = { "cache-control": "no-store, no-cache, must-revalidate", pragma: "no-cache" } as const;
+
+/**
+ * The lock page's own CSP. Strict enough to stand in front of `apps/vault`'s wall without
+ * loosening it: nothing loads from anywhere but this origin, the form posts nowhere (the
+ * script does the POST), and the page cannot be framed.
+ */
+const LOCK_CSP =
+	"default-src 'none'; style-src 'self'; script-src 'self'; connect-src 'self'; " +
+	"img-src data:; form-action 'none'; base-uri 'none'; frame-ancestors 'none'";
+
+export interface MasterLockGuard {
+	/** `Response` when handled, `null` when the app should serve the request. */
+	handle(req: Request): Promise<Response | null>;
+}
+
+export function createMasterLockGuard(options: MasterLockGuardOptions): MasterLockGuard {
+	const resolve: (req: Request) => MasterLock | null =
+		typeof options.lock === "function" ? options.lock : () => options.lock as MasterLock;
+	const isSecure = options.secure ?? defaultSecure;
+	const cookieName = masterLockCookieName(options.appKey ?? options.appLabel);
+
+	const cookie = (token: string, secure: boolean): string =>
+		// No Max-Age: a SESSION cookie, so closing the browser drops it. The server-side
+		// idle clock is the real expiry — this only keeps the token out of a profile that
+		// somebody else might open tomorrow.
+		`${cookieName}=${token}; Path=/; HttpOnly; SameSite=Strict${secure ? "; Secure" : ""}`;
+	const clearCookie = (secure: boolean): string =>
+		`${cookieName}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0${secure ? "; Secure" : ""}`;
+
+	/** The ONE refusal. Identical for wrong, throttled, unconfigured and not-unlocked. */
+	const refuse = (retryAfterMs = 0): Response =>
+		Response.json(
+			{ error: "locked", retryAfterMs },
+			{ status: 401, headers: { ...noStore, [MASTER_LOCK_STATE_HEADER]: "locked" } },
+		);
+
+	/**
+	 * 🔴 May THIS request through — and the difference between the two modes is the whole
+	 * security property of the per-person wall.
+	 *
+	 * **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.
+	 *
+	 * **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.
+	 */
+	const opens = (lock: MasterLock, req: Request): boolean =>
+		lock.isEnrollable ? lock.presents(req) : lock.unlocked || lock.presents(req);
+
+	async function handleOwnRoute(req: Request, url: URL, lock: MasterLock): Promise<Response> {
+		const path = url.pathname;
+		const secure = isSecure(url, req);
+
+		if (req.method === "GET" || req.method === "HEAD") {
+			if (path === MASTER_LOCK_PATHS.style) {
+				return new Response(LOCK_STYLE, {
+					headers: { "content-type": "text/css; charset=utf-8", ...noStore },
+				});
+			}
+			if (path === MASTER_LOCK_PATHS.script) {
+				return new Response(LOCK_SCRIPT, {
+					headers: { "content-type": "text/javascript; charset=utf-8", ...noStore },
+				});
+			}
+			if (path === MASTER_LOCK_PATHS.status) {
+				return Response.json(lock.status(), { 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
+				// the app rather than showing a password box that would do nothing. Per
+				// person this must be the caller's own state, not the site's: bouncing a
+				// locked-out phone to `/` because the desk is open is an infinite loop.
+				if (opens(lock, req)) return Response.redirect(new URL("/", url), 303);
+				return lockPage(options, lock);
+			}
+			return new Response("not found", { status: 404, headers: noStore });
+		}
+
+		if (req.method !== "POST") {
+			return new Response("method not allowed", { status: 405, headers: noStore });
+		}
+
+		if (path === MASTER_LOCK_PATHS.enroll) {
+			const body = await readJson(req);
+			const result = await lock.enroll({
+				kdf: body?.kdf as never,
+				verifier: typeof body?.verifier === "string" ? body.verifier : "",
+			});
+			// Every refusal is the SAME refusal, as everywhere else here: "you may not
+			// enroll" and "somebody already did" must not be distinguishable, or the route
+			// 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 },
+				{ headers: { ...noStore, "set-cookie": cookie(result.token, secure) } },
+			);
+		}
+
+		if (path === MASTER_LOCK_PATHS.unlock) {
+			const body = await readJson(req);
+			const verifier = typeof body?.verifier === "string" ? body.verifier : "";
+			const result = await lock.unlock(verifier);
+			if (!result.ok) return refuse(result.retryAfterMs);
+			return Response.json(
+				{ ok: true, idleMs: lock.idleMs },
+				{ headers: { ...noStore, "set-cookie": cookie(result.token, secure) } },
+			);
+		}
+
+		// Everything below CHANGES something and therefore needs the site already open.
+		if (!lock.presents(req)) return refuse();
+
+		if (path === MASTER_LOCK_PATHS.ping) {
+			lock.touch(req);
+			return Response.json({ ok: true, remainingMs: lock.remainingMs }, { headers: noStore });
+		}
+		if (path === MASTER_LOCK_PATHS.lock) {
+			lock.lock();
+			return Response.json(
+				{ ok: true },
+				{ headers: { ...noStore, "set-cookie": clearCookie(secure) } },
+			);
+		}
+		if (path === MASTER_LOCK_PATHS.settings) {
+			const body = await readJson(req);
+			const idleMs = lock.setIdleMs(Number(body?.idleMs));
+			return Response.json({ ok: true, idleMs }, { headers: noStore });
+		}
+		if (path === MASTER_LOCK_PATHS.change) {
+			const body = await readJson(req);
+			const result = await lock.change({
+				currentVerifier: typeof body?.currentVerifier === "string" ? body.currentVerifier : "",
+				kdf: body?.kdf as never,
+				verifier: typeof body?.verifier === "string" ? body.verifier : "",
+			});
+			if (!result.ok) {
+				return Response.json({ error: result.reason }, { status: 400, headers: noStore });
+			}
+			// The rotation locked the site; drop the cookie with it so the page it came from
+			// does not sit there holding a token that stopped meaning anything.
+			return Response.json(
+				{ ok: true },
+				{ headers: { ...noStore, "set-cookie": clearCookie(secure) } },
+			);
+		}
+		return new Response("not found", { status: 404, headers: noStore });
+	}
+
+	return {
+		async handle(req: Request): Promise<Response | null> {
+			const url = new URL(req.url);
+			const own =
+				url.pathname === MASTER_LOCK_PREFIX || url.pathname.startsWith(`${MASTER_LOCK_PREFIX}/`);
+			const lock = resolve(req);
+			if (!lock) {
+				// No principal. On the app's own paths the caller is not signed in and the
+				// app's sign-in owns the request; on `/__lock/*` there is nobody to unlock
+				// FOR, and answering the ordinary refusal keeps that indistinguishable from
+				// being locked.
+				return own ? refuse() : null;
+			}
+			if (own) return handleOwnRoute(req, url, lock);
+			if (options.allow?.(url, req)) return null;
+			if (opens(lock, req)) return null;
+
+			// A document request is answered IN PLACE with the lock page — same URL, status
+			// 200 — so unlocking reloads to where they were going instead of dumping them at
+			// the root. Everything else gets the uniform refusal.
+			if (wantsDocument(req)) return lockPage(options, lock);
+			return refuse();
+		},
+	};
+}
+
+function lockPage(options: LockPageOptions, lock: MasterLock): Response {
+	return new Response(lockPageHtml({ ...options, enroll: lock.awaitingEnrollment }), {
+		status: 200,
+		headers: {
+			"content-type": "text/html; charset=utf-8",
+			"content-security-policy": LOCK_CSP,
+			"x-content-type-options": "nosniff",
+			[MASTER_LOCK_STATE_HEADER]: "locked",
+			...noStore,
+		},
+	});
+}
+
+/** Is this the browser asking for a PAGE, as opposed to the app asking for data? */
+function wantsDocument(req: Request): boolean {
+	if (req.method !== "GET") return false;
+	// `Sec-Fetch-Dest` is the browser's own answer and beats guessing from `Accept`; every
+	// engine this fleet runs on sends it. `Accept` is the fallback for curl and for a
+	// request that arrived through something that stripped it.
+	const dest = req.headers.get("sec-fetch-dest");
+	if (dest) return dest === "document" || dest === "iframe";
+	return (req.headers.get("accept") ?? "").includes("text/html");
+}
+
+async function readJson(req: Request): Promise<Record<string, unknown> | null> {
+	try {
+		const body = await req.json();
+		if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+		return body as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}
+
+function defaultSecure(url: URL, req: Request): boolean {
+	const forwarded = req.headers.get("x-forwarded-proto");
+	if (forwarded) return forwarded.split(",")[0]?.trim() === "https";
+	return url.protocol === "https:";
+}

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

@@ -0,0 +1,44 @@
+/**
+ * `cursedbelt-server/master-lock` — the server half of the sitewide master-password lock.
+ *
+ * What the feature is, what it deliberately is NOT, and the four decisions behind it are in
+ * `masterLock.ts`'s module note. Read that first.
+ *
+ * Adopting it in an app is three things:
+ *   1. a {@link MasterLock} built over whatever key/value the app already has,
+ *   2. `createMasterLockGuard(...).handle(req)` in front of everything the app serves,
+ *   3. `cursedbelt/react/master-lock` in the header, for the manual lock and the rotation.
+ *
+ * Removing it is deleting those three. That is the shape the owner asked for: *"the reusable
+ * functionality for this should be in a place that makes it easy to share to add or remove
+ * from apps in the code, such as cb."*
+ */
+export { type MasterLockGuard, type MasterLockGuardOptions, createMasterLockGuard } from "./guard";
+export { LOCK_SCRIPT, LOCK_STYLE, type LockPageOptions, lockPageHtml } from "./lockPage";
+export {
+	MASTER_LOCK_PRINCIPAL_KEY_PREFIX,
+	MasterLockDirectory,
+	type MasterLockDirectoryOptions,
+	masterLockPrincipalKey,
+} from "./principals";
+export {
+	MasterLock,
+	type MasterLockEnrollResult,
+	type MasterLockOptions,
+	type MasterLockRecord,
+	type MasterLockStore,
+	type MasterLockUnlockResult,
+	readRecord,
+} from "./masterLock";
+export {
+	DEFAULT_SEED_IDLE_MS,
+	generateStagePassword,
+	type MintMasterLockSeedOptions,
+	mintMasterLockSeed,
+	serializeMasterLockSeed,
+} from "./seed";
+export {
+	MASTER_LOCK_SETTING_KEY,
+	createKvMasterLockStore,
+	createMemoryMasterLockStore,
+} from "./store";

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

@@ -0,0 +1,88 @@
+/**
+ * 🔴 The one test that stops the whole feature from failing silently.
+ *
+ * `LOCK_SCRIPT` carries a HAND COPY of `deriveMasterLockVerifier`, because the lock page is
+ * served to a browser as plain text and cannot import anything. If the two drift, the page
+ * derives a verifier that can never match, and the symptom is the owner's correct master
+ * password being refused forever — with every health check green, which is precisely how
+ * `apps/collections` lost a day in 2026-08-12.
+ *
+ * So this EVALUATES the function out of the shipped script source and compares it with the
+ * TypeScript one on the vault's pinned vector. Change either, and this fails until you
+ * change the other.
+ */
+import { describe, expect, test } from "bun:test";
+import { MASTER_LOCK_PATHS, type MasterLockKdfParams, deriveMasterLockVerifier } from "cursedbelt-core/master-lock";
+import { LOCK_SCRIPT, LOCK_STYLE, lockPageHtml } from "./lockPage";
+
+const KDF: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 600_000,
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+const PASSWORD = "correct horse battery staple";
+
+/**
+ * Pull `deriveVerifier` out of the served script.
+ *
+ * The script assigns it to `globalThis.__masterLockDerive` for exactly this — a seam that
+ * costs one line in the browser and is the difference between a pinned copy and a hopeful
+ * one. Everything after that assignment touches `document`, so the source is cut there.
+ */
+function extractDerive(): (password: string, kdf: MasterLockKdfParams) => Promise<string> {
+	const marker = "globalThis.__masterLockDerive = deriveVerifier;";
+	const cut = LOCK_SCRIPT.indexOf(marker);
+	expect(cut).toBeGreaterThan(0);
+	const source = LOCK_SCRIPT.slice(0, cut + marker.length);
+	// The prelude reads `document`, which does not exist under `bun test`; the slice above
+	// stops before it, but the leading `const` declarations still run — so evaluate in a
+	// function scope with those globals stubbed.
+	const factory = new Function(
+		"document",
+		`${source}\nreturn globalThis.__masterLockDerive;`,
+	) as (doc: unknown) => (password: string, kdf: MasterLockKdfParams) => Promise<string>;
+	return factory({ getElementById: () => ({ addEventListener() {}, setAttribute() {}, removeAttribute() {} }) });
+}
+
+describe("the lock page's hand-copied derivation", () => {
+	test("🔴 derives EXACTLY what the TypeScript one does", async () => {
+		const pageDerive = extractDerive();
+		const fromPage = await pageDerive(PASSWORD, KDF);
+		const fromModule = await deriveMasterLockVerifier(PASSWORD, KDF);
+		expect(fromPage).toBe(fromModule);
+		// And both are still the vault's pinned vector, so a seeded app opens.
+		expect(fromPage).toBe("xnUVRdpRFD1tjzd7Il-Jd-YpvfVTGOs-6gAdsf2VfXc");
+	});
+
+	test("agrees on a second, unrelated input too", async () => {
+		const pageDerive = extractDerive();
+		const kdf = { ...KDF, iter: 1, salt: "DwoNDAsKCQgHBgUEAwIB" };
+		expect(await pageDerive("another password", kdf)).toBe(
+			await deriveMasterLockVerifier("another password", kdf),
+		);
+	});
+});
+
+describe("the page itself", () => {
+	test("names the app, links only same-origin assets, and carries no inline script", () => {
+		const html = lockPageHtml({ appLabel: "Collections" });
+		expect(html).toContain("<title>Locked · Collections</title>");
+		expect(html).toContain(`href="${MASTER_LOCK_PATHS.style}"`);
+		expect(html).toContain(`src="${MASTER_LOCK_PATHS.script}"`);
+		// An inline <script> would need a CSP nonce; the guard's wall forbids it outright.
+		expect(html).not.toMatch(/<script(?![^>]*\bsrc=)/);
+		expect(html).toContain('name="robots" content="noindex, nofollow"');
+	});
+
+	test("escapes the app label — it is passed in by the consumer", () => {
+		const html = lockPageHtml({ appLabel: '<img src=x onerror="alert(1)">' });
+		expect(html).not.toContain("<img");
+		expect(html).toContain("&lt;img");
+	});
+
+	test("the stylesheet needs no font, image or origin from anywhere", () => {
+		expect(LOCK_STYLE).not.toContain("url(");
+		expect(LOCK_STYLE).not.toContain("@import");
+	});
+});