cursedbelt-server 1.0.0

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

@@ -0,0 +1,523 @@
+/**
+ * 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 { clampIdleMs, isMasterLockKdfParams, windowRemaining, } from "cursedbelt-core/master-lock";
+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 {
+    store;
+    now;
+    onLockedChange;
+    log;
+    /** Per-person mode — see {@link MasterLockOptions.enrollable}. */
+    enrollable;
+    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.
+     */
+    sessions = new Map();
+    expiryTimer = null;
+    failures = 0;
+    lastFailureAt = 0;
+    constructor(options) {
+        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() {
+        return this.record !== null;
+    }
+    /** The params the browser must derive under, or null. Public by design. */
+    get kdf() {
+        return this.record?.kdf ?? null;
+    }
+    get idleMs() {
+        return this.record?.idleMs ?? clampIdleMs(undefined);
+    }
+    /** Is this lock in per-person mode? */
+    get isEnrollable() {
+        return this.enrollable;
+    }
+    /** May a first password be chosen right now? Per-person mode, and no record yet. */
+    get awaitingEnrollment() {
+        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() {
+        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() {
+        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() {
+        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) {
+        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) {
+        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) {
+        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 = {
+            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) {
+        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() {
+        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) {
+        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 = {
+            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) {
+        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() {
+        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. */
+    sweep() {
+        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.
+     */
+    scheduleExpiry() {
+        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.unref?.();
+        this.expiryTimer = timer;
+    }
+    clearExpiry() {
+        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) {
+    if (!json)
+        return null;
+    let parsed;
+    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;
+    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) {
+    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, hash) {
+    try {
+        return await Bun.password.verify(candidate, hash);
+    }
+    catch {
+        return null;
+    }
+}
+let equalizerHash = null;
+async function equalize(candidate) {
+    equalizerHash ??= Bun.password.hash("master-lock-timing-equalizer", { algorithm: "argon2id" });
+    await Bun.password.verify(candidate || "x", await equalizerHash).catch(() => false);
+}
+function randomToken() {
+    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) {
+    const out = [];
+    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, b) {
+    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;
+}

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

@@ -0,0 +1,76 @@
+import { MasterLock } from "./masterLock";
+/** Namespace for every per-person record, so one glance at the table says what they are. */
+export declare 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 declare function masterLockPrincipalKey(principalId: string): string;
+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 declare class MasterLockDirectory {
+    private readonly locks;
+    private readonly options;
+    constructor(options: MasterLockDirectoryOptions);
+    /**
+     * 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;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+    /** How many principals hold a live unlock right now. For `/healthz` and the boot log;
+     *  a COUNT discloses nothing about who. */
+    unlockedCount(): number;
+    /** Drop every in-memory lock — for tests between cases. */
+    resetForTest(): void;
+}