cursedbelt-server 1.0.0

package/dist/server/master-lock/lockPage.js

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

package/dist/server/master-lock/masterLock.d.ts

@@ -0,0 +1,294 @@
+/**
+ * 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 } 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";
+};
+/**
+ * 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 declare class MasterLock {
+    private readonly store;
+    private readonly now;
+    private readonly onLockedChange;
+    private readonly log;
+    /** Per-person mode — see {@link MasterLockOptions.enrollable}. */
+    private readonly enrollable;
+    private record;
+    /**
+     * 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;
+    private expiryTimer;
+    private failures;
+    private lastFailureAt;
+    constructor(options: MasterLockOptions);
+    /** Is a master password set at all? An app with `false` here refuses nothing. */
+    get configured(): boolean;
+    /** The params the browser must derive under, or null. Public by design. */
+    get kdf(): MasterLockKdfParams | null;
+    get idleMs(): number;
+    /** Is this lock in per-person mode? */
+    get isEnrollable(): boolean;
+    /** May a first password be chosen right now? Per-person mode, and no record yet. */
+    get awaitingEnrollment(): boolean;
+    /**
+     * 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;
+    /** 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;
+    status(): MasterLockStatus;
+    /** Does this request carry the live unlock? The cookie, or the header for a caller with
+     *  no cookie jar. */
+    presents(req: Request): boolean;
+    /**
+     * 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.
+     */
+    unlock(verifier: string): Promise<MasterLockUnlockResult>;
+    /**
+     * 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.
+     */
+    enroll(input: {
+        kdf: MasterLockKdfParams;
+        verifier: string;
+    }): Promise<MasterLockEnrollResult>;
+    /**
+     * 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;
+    /** 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;
+    /**
+     * 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.
+     */
+    change(input: {
+        currentVerifier: string;
+        kdf: MasterLockKdfParams;
+        verifier: string;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: "wrong" | "invalid" | "unconfigured";
+    }>;
+    /** The owner's *"customizable by me"* idle timeout, clamped to the usable band. */
+    setIdleMs(value: number): number;
+    /** Drop the in-memory unlock without notifying — for tests between cases. */
+    resetForTest(): void;
+    /** 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;
+    /**
+     * 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;
+    private clearExpiry;
+}
+/** 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 declare function readRecord(json: string | null | undefined): MasterLockRecord | null;