cursedbelt-server 4.11.1 → 4.12.0

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

@@ -26,4 +26,4 @@ export { LOCK_SCRIPT, LOCK_STYLE, MASTER_LOCK_DERIVE_SOURCE, type LockPageOption
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, type MasterLockDirectoryOptions, masterLockPrincipalKey, } from "./principals";
 export { FIRST_ACCOUNT_ID, MasterLock, type MasterLockAccount, type MasterLockAddAccountResult, 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";
+export { MASTER_LOCK_SETTING_KEY, MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store";

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

@@ -26,4 +26,4 @@ export { LOCK_SCRIPT, LOCK_STYLE, MASTER_LOCK_DERIVE_SOURCE, lockPageHtml, } fro
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, masterLockPrincipalKey, } from "./principals";
 export { FIRST_ACCOUNT_ID, MasterLock, readRecord, } from "./masterLock";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed";
-export { MASTER_LOCK_SETTING_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store";
+export { MASTER_LOCK_SETTING_KEY, MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store";

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

@@ -1,52 +1,3 @@
-/**
- * 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 MasterLockAccountSummary, type MasterLockKdfParams, type MasterLockStatus } from "cursedbelt-core/master-lock";
 /**
  * ONE master password, and therefore one TENANT of the app behind it.
@@ -127,8 +78,29 @@ export interface MasterLockStore {
     read(): string | null;
     write(json: string): void;
 }
+/**
+ * Where the LIVE state goes when the process that holds it does not live — the unlocks that are
+ * open and the throttle's failure count. Synchronous by the same contract as
+ * {@link MasterLockStore}, so a Worker satisfies it from its per-invocation snapshot exactly as
+ * it does the record.
+ *
+ * 🔴 Why it exists (2026-09-22, the night `collections` moved to a Worker): the lock kept its
+ * unlocks in a `Map` on the instance, and a Worker builds the instance once per REQUEST. The
+ * owner typed the right password, got a 200 and a cookie, and the very next request was locked
+ * again — measured on `collections-stage` by `worker-stage-walk.ts`. The throttle had the same
+ * shape: every guess met a fresh counter, so nothing slowed a brute force at all.
+ *
+ * Omitted (the Mac's daemons), the state stays in memory, exactly as before: a restart locks.
+ * Tokens are never stored — only their SHA-256, so a leaked row opens nothing.
+ */
+export interface MasterLockStateStore {
+    read(): string | null;
+    write(json: string): void;
+}
 export interface MasterLockOptions {
     store: MasterLockStore;
+    /** See {@link MasterLockStateStore}. Required wherever the instance does not outlive a request. */
+    state?: MasterLockStateStore;
     /**
      * The BOOTSTRAP record, as JSON, used only when the store is empty — the same shape as
      * {@link MasterLockRecord} with `idleMs` optional.
@@ -225,6 +197,7 @@ export declare class MasterLock {
      * entered again"* — one button, every device.
      */
     private sessions;
+    private readonly stateStore;
     private expiryTimer;
     private failures;
     private lastFailureAt;
@@ -449,6 +422,10 @@ export declare class MasterLock {
     private write;
     /** Drop the in-memory unlock without notifying — for tests between cases. */
     resetForTest(): void;
+    /** Adopt the persisted live state, if there is a store and it holds a readable one. */
+    private loadState;
+    /** Persist the live state — every mutation of it calls this, or a Worker forgets it. */
+    private saveState;
     /** 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;

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

@@ -47,6 +47,7 @@
  * `retryAfterMs` a throttled caller is told — which they already know, since they are the
  * one who has been guessing.
  */
+import { createHash } from "node:crypto";
 import { clampIdleMs, isMasterLockKdfParams, windowRemaining, } from "cursedbelt-core/master-lock";
 /** The id a legacy single-password record migrates to. Fixed, because the app that adopts
  *  this stamps its existing rows with it — a random id would orphan the library it is
@@ -87,11 +88,14 @@ export class MasterLock {
      * entered again"* — one button, every device.
      */
     sessions = new Map();
+    stateStore = null;
     expiryTimer = null;
     failures = 0;
     lastFailureAt = 0;
     constructor(options) {
         this.store = options.store;
+        this.stateStore = options.state ?? null;
+        this.loadState();
         this.now = options.now ?? Date.now;
         this.onLockedChange = options.onLockedChange;
         this.log = options.log ?? (() => undefined);
@@ -220,7 +224,7 @@ export class MasterLock {
         if (this.sessions.size === 0)
             return null;
         let found = null;
-        for (const presented of presentedTokens(req)) {
+        for (const presented of presentedTokens(req).map(tokenDigest)) {
             for (const [live, session] of this.sessions) {
                 // No early `return`: every candidate is compared against every live token so
                 // the loop's duration does not say which cookie in the jar was the right one.
@@ -307,6 +311,7 @@ export class MasterLock {
             }
             this.failures += 1;
             this.lastFailureAt = now;
+            this.saveState();
             return { ok: false, retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, now) };
         }
         return { ok: true, ...this.open(opened.id, now) };
@@ -322,7 +327,8 @@ export class MasterLock {
         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, { accountId, lastActivityAt: now });
+        this.sessions.set(tokenDigest(token), { accountId, lastActivityAt: now });
+        this.saveState();
         this.scheduleExpiry();
         if (wasLocked)
             this.onLockedChange?.(false);
@@ -481,7 +487,7 @@ export class MasterLock {
         // 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.
         let slid = false;
-        for (const presented of presentedTokens(req)) {
+        for (const presented of presentedTokens(req).map(tokenDigest)) {
             for (const [live, session] of this.sessions) {
                 // No early `return`, for the reason `accountFor` gives: the loop's duration
                 // must not say which of the jar's cookies was this app's.
@@ -491,8 +497,10 @@ export class MasterLock {
                 }
             }
         }
-        if (slid)
+        if (slid) {
+            this.saveState();
             this.scheduleExpiry();
+        }
         return slid;
     }
     /** The manual lock — the owner's *"I want a lock option to turn the site back to needing
@@ -504,6 +512,7 @@ export class MasterLock {
         // 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.saveState();
         this.clearExpiry();
         this.onLockedChange?.(true);
     }
@@ -588,6 +597,33 @@ export class MasterLock {
         this.lastFailureAt = 0;
         this.clearExpiry();
     }
+    /** Adopt the persisted live state, if there is a store and it holds a readable one. */
+    loadState() {
+        if (!this.stateStore)
+            return;
+        const raw = this.stateStore.read();
+        if (!raw)
+            return;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.v !== 1)
+                return;
+            for (const [digest, session] of parsed.sessions ?? []) {
+                if (typeof digest === "string" && typeof session?.accountId === "string" && Number.isFinite(session.lastActivityAt)) {
+                    this.sessions.set(digest, { accountId: session.accountId, lastActivityAt: session.lastActivityAt });
+                }
+            }
+            this.failures = Number.isFinite(parsed.failures) ? Number(parsed.failures) : 0;
+            this.lastFailureAt = Number.isFinite(parsed.lastFailureAt) ? Number(parsed.lastFailureAt) : 0;
+        }
+        catch {
+            // Unreadable state is LOCKED state: nothing is open, which is the safe reading.
+        }
+    }
+    /** Persist the live state — every mutation of it calls this, or a Worker forgets it. */
+    saveState() {
+        this.stateStore?.write(JSON.stringify({ v: 1, sessions: [...this.sessions], failures: this.failures, lastFailureAt: this.lastFailureAt }));
+    }
     /** 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() {
@@ -596,11 +632,14 @@ export class MasterLock {
             return;
         const now = this.now();
         const wasOpen = this.sessions.size > 0;
+        const before = this.sessions.size;
         for (const [token, session] of this.sessions) {
             // Each device expires on its OWN clock, so one going idle never shortens another.
             if (now - session.lastActivityAt > record.idleMs)
                 this.sessions.delete(token);
         }
+        if (this.sessions.size !== before)
+            this.saveState();
         if (wasOpen && this.sessions.size === 0) {
             this.clearExpiry();
             this.onLockedChange?.(true);
@@ -791,6 +830,10 @@ async function equalize(candidate) {
     equalizerHash ??= Bun.password.hash("master-lock-timing-equalizer", { algorithm: "argon2id" });
     await Bun.password.verify(candidate || "x", await equalizerHash).catch(() => false);
 }
+/** What a session is KEYED by — never the token itself, so persisted state opens nothing. */
+function tokenDigest(token) {
+    return createHash("sha256").update(token).digest("base64url");
+}
 function randomToken() {
     const bytes = new Uint8Array(TOKEN_BYTES);
     crypto.getRandomValues(bytes);

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

@@ -9,6 +9,11 @@
 import type { MasterLockStore } from "./masterLock";
 /** The default key, so two apps' rows look the same when somebody goes looking. */
 export declare const MASTER_LOCK_SETTING_KEY = "master_lock:record";
+/**
+ * The key the LIVE state (open unlocks, the throttle) is kept under, beside the record — see
+ * `MasterLockStateStore`. `createKvMasterLockStore(kv, MASTER_LOCK_STATE_KEY)` is that store.
+ */
+export declare const MASTER_LOCK_STATE_KEY = "master_lock:state";
 /** Wrap an app's existing key/value settings surface. */
 export declare function createKvMasterLockStore(kv: {
     get(key: string): string | null | undefined;

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

@@ -1,5 +1,10 @@
 /** The default key, so two apps' rows look the same when somebody goes looking. */
 export const MASTER_LOCK_SETTING_KEY = "master_lock:record";
+/**
+ * The key the LIVE state (open unlocks, the throttle) is kept under, beside the record — see
+ * `MasterLockStateStore`. `createKvMasterLockStore(kv, MASTER_LOCK_STATE_KEY)` is that store.
+ */
+export const MASTER_LOCK_STATE_KEY = "master_lock:state";
 /** Wrap an app's existing key/value settings surface. */
 export function createKvMasterLockStore(kv, key = MASTER_LOCK_SETTING_KEY) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.11.1",
+	"version": "4.12.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

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

@@ -67,6 +67,7 @@ export {
 } from "./seed";
 export {
 	MASTER_LOCK_SETTING_KEY,
+	MASTER_LOCK_STATE_KEY,
 	createKvMasterLockStore,
 	createMemoryMasterLockStore,
 } from "./store";

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

@@ -369,3 +369,60 @@ describe("readRecord", () => {
 		expect(readRecord(JSON.stringify({ ...base, idleMs: -5 }))?.idleMs).toBe(MIN_IDLE_MS);
 	});
 });
+
+describe("the live state, when the instance does not outlive a request (a Worker)", () => {
+	/** One record store and one state store, and a fresh MasterLock per "request" over both. */
+	function perRequest(now: () => number = Date.now) {
+		const store = createMemoryMasterLockStore(null);
+		const state = createMemoryMasterLockStore(null);
+		const fresh = () => new MasterLock({ store, state, seedJson: SEED, now });
+		return { fresh, state };
+	}
+
+	test("🔴 an unlock made in one instance opens the NEXT one — the collections-stage defect", async () => {
+		const { fresh } = perRequest();
+		const result = await fresh().unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		const next = fresh();
+		expect(next.presents(req(result.token))).toBe(true);
+		expect(next.unlocked).toBe(true);
+	});
+
+	test("the defect it replaced: with no state store, the next instance has forgotten", async () => {
+		const store = createMemoryMasterLockStore(null);
+		const result = await new MasterLock({ store, seedJson: SEED }).unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		expect(new MasterLock({ store, seedJson: SEED }).presents(req(result.token))).toBe(false);
+	});
+
+	test("🔴 the throttle holds ACROSS instances — a fresh counter per request throttled nothing", async () => {
+		const now = 1_000_000;
+		const { fresh } = perRequest(() => now);
+		for (let i = 0; i < 6; i += 1) await fresh().unlock("wrong");
+		expect(fresh().status().retryAfterMs).toBe(30_000);
+		expect((await fresh().unlock(VERIFIER)).ok).toBe(false);
+	}, KDF_BULK_MS);
+
+	test("a lock in one instance closes every other — the manual lock reaches every device", async () => {
+		const { fresh } = perRequest();
+		const result = await fresh().unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		fresh().lock();
+		expect(fresh().presents(req(result.token))).toBe(false);
+	});
+
+	test("🔴 the persisted state holds no token — a leaked row opens nothing", async () => {
+		const { fresh, state } = perRequest();
+		const result = await fresh().unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		const stored = state.read() ?? "";
+		expect(stored).toContain("sessions");
+		expect(stored).not.toContain(result.token);
+	});
+
+	test("unreadable state is LOCKED state", () => {
+		const store = createMemoryMasterLockStore(null);
+		const lock = new MasterLock({ store, state: createMemoryMasterLockStore("{not json"), seedJson: SEED });
+		expect(lock.unlocked).toBe(false);
+	});
+});

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

@@ -47,6 +47,7 @@
  * `retryAfterMs` a throttled caller is told — which they already know, since they are the
  * one who has been guessing.
  */
+import { createHash } from "node:crypto";
 import {
 	type MasterLockAccountSummary,
 	type MasterLockKdfParams,
@@ -139,8 +140,30 @@ export interface MasterLockStore {
 	write(json: string): void;
 }
 
+/**
+ * Where the LIVE state goes when the process that holds it does not live — the unlocks that are
+ * open and the throttle's failure count. Synchronous by the same contract as
+ * {@link MasterLockStore}, so a Worker satisfies it from its per-invocation snapshot exactly as
+ * it does the record.
+ *
+ * 🔴 Why it exists (2026-09-22, the night `collections` moved to a Worker): the lock kept its
+ * unlocks in a `Map` on the instance, and a Worker builds the instance once per REQUEST. The
+ * owner typed the right password, got a 200 and a cookie, and the very next request was locked
+ * again — measured on `collections-stage` by `worker-stage-walk.ts`. The throttle had the same
+ * shape: every guess met a fresh counter, so nothing slowed a brute force at all.
+ *
+ * Omitted (the Mac's daemons), the state stays in memory, exactly as before: a restart locks.
+ * Tokens are never stored — only their SHA-256, so a leaked row opens nothing.
+ */
+export interface MasterLockStateStore {
+	read(): string | null;
+	write(json: string): void;
+}
+
 export interface MasterLockOptions {
 	store: MasterLockStore;
+	/** See {@link MasterLockStateStore}. Required wherever the instance does not outlive a request. */
+	state?: MasterLockStateStore;
 	/**
 	 * The BOOTSTRAP record, as JSON, used only when the store is empty — the same shape as
 	 * {@link MasterLockRecord} with `idleMs` optional.
@@ -236,6 +259,7 @@ export class MasterLock {
 	 * entered again"* — one button, every device.
 	 */
 	private sessions = new Map<string, MasterLockSession>();
+	private readonly stateStore: MasterLockStateStore | null = null;
 	private expiryTimer: ReturnType<typeof setTimeout> | null = null;
 
 	private failures = 0;
@@ -243,6 +267,8 @@ export class MasterLock {
 
 	constructor(options: MasterLockOptions) {
 		this.store = options.store;
+		this.stateStore = options.state ?? null;
+		this.loadState();
 		this.now = options.now ?? Date.now;
 		this.onLockedChange = options.onLockedChange;
 		this.log = options.log ?? (() => undefined);
@@ -374,7 +400,7 @@ export class MasterLock {
 		this.sweep();
 		if (this.sessions.size === 0) return null;
 		let found: string | null = null;
-		for (const presented of presentedTokens(req)) {
+		for (const presented of presentedTokens(req).map(tokenDigest)) {
 			for (const [live, session] of this.sessions) {
 				// No early `return`: every candidate is compared against every live token so
 				// the loop's duration does not say which cookie in the jar was the right one.
@@ -465,6 +491,7 @@ export class MasterLock {
 			}
 			this.failures += 1;
 			this.lastFailureAt = now;
+			this.saveState();
 			return { ok: false, retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, now) };
 		}
 
@@ -482,7 +509,8 @@ export class MasterLock {
 		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, { accountId, lastActivityAt: now });
+		this.sessions.set(tokenDigest(token), { accountId, lastActivityAt: now });
+		this.saveState();
 		this.scheduleExpiry();
 		if (wasLocked) this.onLockedChange?.(false);
 		return { token, accountId };
@@ -651,7 +679,7 @@ export class MasterLock {
 		// 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.
 		let slid = false;
-		for (const presented of presentedTokens(req)) {
+		for (const presented of presentedTokens(req).map(tokenDigest)) {
 			for (const [live, session] of this.sessions) {
 				// No early `return`, for the reason `accountFor` gives: the loop's duration
 				// must not say which of the jar's cookies was this app's.
@@ -661,7 +689,10 @@ export class MasterLock {
 				}
 			}
 		}
-		if (slid) this.scheduleExpiry();
+		if (slid) {
+			this.saveState();
+			this.scheduleExpiry();
+		}
 		return slid;
 	}
 
@@ -673,6 +704,7 @@ export class MasterLock {
 		// 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.saveState();
 		this.clearExpiry();
 		this.onLockedChange?.(true);
 	}
@@ -762,6 +794,38 @@ export class MasterLock {
 		this.clearExpiry();
 	}
 
+	/** Adopt the persisted live state, if there is a store and it holds a readable one. */
+	private loadState(): void {
+		if (!this.stateStore) return;
+		const raw = this.stateStore.read();
+		if (!raw) return;
+		try {
+			const parsed = JSON.parse(raw) as {
+				v?: number;
+				sessions?: Array<[string, MasterLockSession]>;
+				failures?: number;
+				lastFailureAt?: number;
+			};
+			if (parsed.v !== 1) return;
+			for (const [digest, session] of parsed.sessions ?? []) {
+				if (typeof digest === "string" && typeof session?.accountId === "string" && Number.isFinite(session.lastActivityAt)) {
+					this.sessions.set(digest, { accountId: session.accountId, lastActivityAt: session.lastActivityAt });
+				}
+			}
+			this.failures = Number.isFinite(parsed.failures) ? Number(parsed.failures) : 0;
+			this.lastFailureAt = Number.isFinite(parsed.lastFailureAt) ? Number(parsed.lastFailureAt) : 0;
+		} catch {
+			// Unreadable state is LOCKED state: nothing is open, which is the safe reading.
+		}
+	}
+
+	/** Persist the live state — every mutation of it calls this, or a Worker forgets it. */
+	private saveState(): void {
+		this.stateStore?.write(
+			JSON.stringify({ v: 1, sessions: [...this.sessions], failures: this.failures, lastFailureAt: this.lastFailureAt }),
+		);
+	}
+
 	/** 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 {
@@ -769,10 +833,12 @@ export class MasterLock {
 		if (!record || this.sessions.size === 0) return;
 		const now = this.now();
 		const wasOpen = this.sessions.size > 0;
+		const before = this.sessions.size;
 		for (const [token, session] of this.sessions) {
 			// Each device expires on its OWN clock, so one going idle never shortens another.
 			if (now - session.lastActivityAt > record.idleMs) this.sessions.delete(token);
 		}
+		if (this.sessions.size !== before) this.saveState();
 		if (wasOpen && this.sessions.size === 0) {
 			this.clearExpiry();
 			this.onLockedChange?.(true);
@@ -963,6 +1029,11 @@ async function equalize(candidate: string): Promise<void> {
 	await Bun.password.verify(candidate || "x", await equalizerHash).catch(() => false);
 }
 
+/** What a session is KEYED by — never the token itself, so persisted state opens nothing. */
+function tokenDigest(token: string): string {
+	return createHash("sha256").update(token).digest("base64url");
+}
+
 function randomToken(): string {
 	const bytes = new Uint8Array(TOKEN_BYTES);
 	crypto.getRandomValues(bytes);

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

@@ -11,6 +11,12 @@ import type { MasterLockStore } from "./masterLock";
 /** The default key, so two apps' rows look the same when somebody goes looking. */
 export const MASTER_LOCK_SETTING_KEY = "master_lock:record";
 
+/**
+ * The key the LIVE state (open unlocks, the throttle) is kept under, beside the record — see
+ * `MasterLockStateStore`. `createKvMasterLockStore(kv, MASTER_LOCK_STATE_KEY)` is that store.
+ */
+export const MASTER_LOCK_STATE_KEY = "master_lock:state";
+
 /** Wrap an app's existing key/value settings surface. */
 export function createKvMasterLockStore(
 	kv: { get(key: string): string | null | undefined; set(key: string, value: string): void },