cursedbelt-server 2.1.0 → 3.0.1

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

@@ -48,6 +48,7 @@
  * one who has been guessing.
  */
 import {
+	type MasterLockAccountSummary,
 	type MasterLockKdfParams,
 	type MasterLockStatus,
 	clampIdleMs,
@@ -55,16 +56,77 @@ import {
 	windowRemaining,
 } from "cursedbelt-core/master-lock";
 
-/** The persisted record. Three public values — none of them is a secret, and the two that
- *  look like one are a salt and a one-way hash. */
+/**
+ * ONE master password, and therefore one TENANT of the app behind it.
+ *
+ * 🔴 The id is the account's identity and it never changes — not when the password is
+ * rotated, not when the label or the hint is rewritten. That is the property the whole
+ * model rests on, in the owner's words: *"If I change account 2 password it just changes
+ * how I get the access … I would still access the same content afterward."* An app stamps
+ * its rows with this id, so an id that moved would orphan a tenant's entire library.
+ */
+export interface MasterLockAccount {
+	/** Stable, app-local, `[a-z0-9-]`. `acct-1` is the one a legacy record migrates to. */
+	id: string;
+	/** What the owner calls this tenant. Shown in the header once unlocked. */
+	label: string;
+	/**
+	 * The owner's own reminder for this password, or `""`.
+	 *
+	 * Nobody — not this server, not an agent, not the owner's own backups — can recover a
+	 * master password, so a forgotten one is a deleted tenant. The hint is the only
+	 * recovery this design permits, and it is deliberately the owner's plain words rather
+	 * than anything derived from the password.
+	 */
+	hint: string;
+	/** `argon2id(verifier)`. The PHC string is self-describing, so there is no salt field. */
+	verifierHash: string;
+	createdAt: number;
+}
+
+/**
+ * The persisted record — the app's KEYRING.
+ *
+ * ── 🔴 ONE `kdf` for every account, and it is not an economy ────────────────
+ * Each account could carry its own salt. It must not, for three reasons, and the third is
+ * the security one:
+ *
+ *  1. **One derivation per attempt.** The browser runs 600,000 PBKDF2 iterations to turn a
+ *     typed password into a verifier. Per-account salts would mean running that once per
+ *     account before the server could say yes or no, so the lock page would get measurably
+ *     slower every time the owner added a tenant.
+ *  2. **A rotation stays local.** `change` rewrites one account's `verifierHash` under
+ *     these same params. A fresh salt would invalidate every sibling's stored hash at once.
+ *  3. **The page cannot be made to count the tenants.** `GET /__lock/status` has to publish
+ *     the params before anyone has proved anything. With one descriptor it publishes one,
+ *     whether there is a single account or ten — so the lock screen is byte-identical in
+ *     both cases. With per-account salts it would have to publish a list, and the length of
+ *     that list is exactly the fact this feature exists to keep quiet.
+ *
+ * What it costs: somebody holding this record can spend one PBKDF2 chain per candidate
+ * password and test it against every account, instead of one chain per account. Each
+ * candidate still costs a separate argon2id per account. Against a 16-byte random salt that
+ * is not a meaningful saving, and it is the same trade the fleet already makes by seeding an
+ * app from the vault's own params.
+ */
 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. */
+	/** The owner's configured idle timeout for THIS app. One clock, all accounts. */
 	idleMs: number;
+	/**
+	 * Every master password this app answers to, oldest first.
+	 *
+	 * 🔴 EMPTY is a real and expected state — a fresh app nobody has chosen a password for
+	 * yet. It reads as LOCKED and offers enrollment; see {@link MasterLock.unlocked}.
+	 */
+	accounts: MasterLockAccount[];
 }
 
+/** 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
+ *  supposed to inherit. */
+export const FIRST_ACCOUNT_ID = "acct-1";
+
 /**
  * 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.
@@ -105,39 +167,37 @@ export interface MasterLockOptions {
 	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. */
+/**
+ * What an unlock attempt answers. `ok` carries the token to set as a cookie, and the
+ * ACCOUNT it opened.
+ *
+ * 🔴 The account id is the answer to "whose data do I serve now", and it comes from the
+ * password that was typed — never from anything the caller sends. A refusal carries no
+ * account, and says nothing about which of them was closest.
+ */
 export type MasterLockUnlockResult =
-	| { ok: true; token: string }
+	| { ok: true; token: string; accountId: 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" };
+	| { ok: true; token: string; accountId: string }
+	| { ok: false; reason: "already-configured" | "invalid" };
+
+/** What adding a SECOND (or fifth) master password answers. It does NOT unlock into the
+ *  new account — the owner stays where they were until they type the new password. */
+export type MasterLockAddAccountResult =
+	| { ok: true; account: MasterLockAccountSummary }
+	| { ok: false; reason: "wrong" | "invalid" | "duplicate" | "unconfigured" | "locked" };
+
+/** One live unlock: the token's account, and when it last saw real interaction. */
+interface MasterLockSession {
+	accountId: string;
+	lastActivityAt: number;
+}
 
 const TOKEN_BYTES = 24;
 
@@ -156,8 +216,6 @@ export class MasterLock {
 	private readonly now: () => number;
 	private readonly onLockedChange: ((locked: boolean) => void) | undefined;
 	private readonly log: (line: string) => void;
-	/** Per-person mode — see {@link MasterLockOptions.enrollable}. */
-	private readonly enrollable: boolean;
 
 	private record: MasterLockRecord | null;
 	/**
@@ -177,7 +235,7 @@ export class MasterLock {
 	 * requirement true: *"then no one can see anything until the master password is
 	 * entered again"* — one button, every device.
 	 */
-	private sessions = new Map<string, number>();
+	private sessions = new Map<string, MasterLockSession>();
 	private expiryTimer: ReturnType<typeof setTimeout> | null = null;
 
 	private failures = 0;
@@ -188,7 +246,6 @@ export class MasterLock {
 		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);
@@ -204,9 +261,10 @@ export class MasterLock {
 		}
 	}
 
-	/** Is a master password set at all? An app with `false` here refuses nothing. */
+	/** Is any master password set at all? An app with `false` here admits nobody, and
+	 *  offers the choose-a-password form instead. */
 	get configured(): boolean {
-		return this.record !== null;
+		return this.accounts.length > 0;
 	}
 
 	/** The params the browser must derive under, or null. Public by design. */
@@ -218,51 +276,71 @@ export class MasterLock {
 		return this.record?.idleMs ?? clampIdleMs(undefined);
 	}
 
-	/** Is this lock in per-person mode? */
-	get isEnrollable(): boolean {
-		return this.enrollable;
+	/** Every account, oldest first. Empty on an app nobody has chosen a password for. */
+	get accounts(): readonly MasterLockAccount[] {
+		return this.record?.accounts ?? [];
 	}
 
-	/** May a first password be chosen right now? Per-person mode, and no record yet. */
+	/**
+	 * May a first master password be chosen right now?
+	 *
+	 * 🔴 True whenever there is no account, on EVERY app — there is no longer a mode that
+	 * decides this. The owner's ruling, on what an app with no master password should do:
+	 * *"if there is no master password then it has to get one set before a user could add
+	 * anything. It would be booting to nothing until the password is created."*
+	 */
 	get awaitingEnrollment(): boolean {
-		return this.enrollable && this.record === null;
+		return this.accounts.length === 0;
 	}
 
 	/**
-	 * 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}.
+	 * Is anybody's unlock live right now?
+	 *
+	 * 🔴 An UNCONFIGURED lock reads as LOCKED, and that INVERTS what this used to do.
+	 * App-wide, "no password means open" was the right call while the lock only decided
+	 * whether a UI was visible: failing closed would have bricked an app rather than
+	 * protected it, since nobody could type a password that did not exist. Both halves of
+	 * that reasoning are now gone. {@link enroll} means an app with no password offers to
+	 * take one, so nothing bricks; and the password now decides WHICH TENANT'S DATA the
+	 * app serves, so "open with no password" has no coherent answer to give — there is no
+	 * account whose rows it could show. The owner ruled the same way: *"It would be
+	 * booting to nothing until the password is created."*
+	 *
+	 * 🔴 And this is a HEALTH reading, not an authorization one. Nothing may admit a
+	 * request because `unlocked` is true — see {@link accountFor}, which is what the guard
+	 * asks. The two were the same question only while an app had one tenant.
 	 */
 	get unlocked(): boolean {
-		if (!this.record) return !this.enrollable;
+		if (!this.configured) return false;
 		this.sweep();
 		return this.sessions.size > 0;
 	}
 
-	/** Milliseconds of idleness left before the unlock lapses; 0 when locked. */
 	/** Milliseconds of idleness left before the LONGEST-lived unlock lapses; 0 when none
 	 *  is live. The status page counts down with it, so it is the most generous of the
 	 *  open devices rather than an arbitrary one. */
 	get remainingMs(): number {
-		if (!this.record) return 0;
+		const record = this.record;
+		if (!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());
+		let newest = 0;
+		for (const session of this.sessions.values()) {
+			if (session.lastActivityAt > newest) newest = session.lastActivityAt;
+		}
+		return Math.max(0, newest + record.idleMs - this.now());
 	}
 
-	status(): MasterLockStatus {
+	/**
+	 * The state, for the lock page and for the app's own header.
+	 *
+	 * `req` is optional only so a health check can ask without one. Pass it wherever there
+	 * IS a request: without it the reply carries no account, and a client would read that
+	 * as "locked" while holding a perfectly good unlock.
+	 */
+	status(req?: Request): MasterLockStatus {
+		const accountId = req ? this.accountFor(req) : null;
+		const account = accountId ? this.accountById(accountId) : null;
 		return {
 			configured: this.configured,
 			enrollable: this.awaitingEnrollment,
@@ -271,30 +349,91 @@ export class MasterLock {
 			idleMs: this.idleMs,
 			remainingMs: this.remainingMs,
 			retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, this.now()),
+			accountId: account?.id ?? null,
+			accountLabel: account?.label ?? null,
 		};
 	}
 
-	/** Does this request carry the live unlock? The cookie, or the header for a caller with
-	 *  no cookie jar. */
-	presents(req: Request): boolean {
+	/**
+	 * 🔴 **WHICH account this request's unlock belongs to** — the one authorization
+	 * question this class answers, and the one the guard asks.
+	 *
+	 * `null` means "no live unlock is presented here", which is the only thing that may
+	 * ever refuse a request. It deliberately does not fall back to {@link unlocked}: that
+	 * reads "somebody's device is open", and honouring it would make the unlock AMBIENT —
+	 * a second browser signed in as the owner would walk through having typed nothing, and
+	 * would then be served whichever tenant happened to be open. While an app had one
+	 * password that was merely sloppy; with several it hands the wrong library to the
+	 * wrong session.
+	 *
+	 * The token is matched in constant time against every live one, and deliberately
+	 * WITHOUT a `Map.get` shortcut: a hash lookup on attacker-supplied bytes leaks by
+	 * timing what the comparison is written to hide.
+	 */
+	accountFor(req: Request): string | null {
 		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.
+		if (this.sessions.size === 0) return null;
+		let found: string | null = null;
 		for (const presented of presentedTokens(req)) {
-			for (const live of this.sessions.keys()) {
-				if (constantTimeEqual(presented, live)) return true;
+			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.
+				if (constantTimeEqual(presented, live)) found ??= session.accountId;
 			}
 		}
-		return false;
+		return found;
+	}
+
+	/** Does this request carry a live unlock? The cookie, or the header for a caller with
+	 *  no cookie jar. A thin reading of {@link accountFor}, which is the real answer. */
+	presents(req: Request): boolean {
+		return this.accountFor(req) !== null;
+	}
+
+	/** One account by id, or null. */
+	accountById(id: string): MasterLockAccount | null {
+		return this.accounts.find((account) => account.id === id) ?? null;
 	}
 
 	/**
-	 * Evaluate a verifier and, on a match, mint the unlock.
+	 * The hints, readable WHILE LOCKED — the owner's *"let me setup hints for them"*.
 	 *
-	 * Runs an argon2 verify on EVERY path — no record, throttled, wrong — so the answer's
-	 * latency says nothing the answer itself does not.
+	 * 🔴 This is the one place that discloses how many accounts exist, and it is a
+	 * separate route for exactly that reason (see `MASTER_LOCK_PATHS.hints`). Everyone who
+	 * can reach it has already passed the app's own owner-only sign-in, and the lock page
+	 * asks for it only when somebody clicks "I forgot" — so the default screen stays
+	 * byte-identical whether this app has one tenant or ten.
+	 */
+	hints(): { label: string; hint: string }[] {
+		return this.accounts.map((account) => ({ label: account.label, hint: account.hint }));
+	}
+
+	/** Every account, for the management UI. Never a hash, and never anything derived from
+	 *  a password. `current` marks the one the caller's own unlock opened. */
+	summaries(req: Request): MasterLockAccountSummary[] {
+		const current = this.accountFor(req);
+		return this.accounts.map((account) => ({
+			id: account.id,
+			label: account.label,
+			hint: account.hint,
+			createdAt: account.createdAt,
+			current: account.id === current,
+		}));
+	}
+
+	/**
+	 * Evaluate a verifier and, on a match, mint the unlock for the account that matched.
+	 *
+	 * Runs an argon2 verify on EVERY path — no accounts, throttled, wrong — so the
+	 * answer's latency says nothing the answer itself does not.
+	 *
+	 * 🔴 **Every account is tried, and the loop does not stop at the first match.**
+	 * Stopping early is the obvious optimisation and it is a timing oracle: a password
+	 * matching the first account would answer in one argon2id and a wrong one in N, so the
+	 * shape of the reply would say how many tenants exist and roughly where in the list
+	 * this one sits. The cost is bounded by how many passwords the owner has made — single
+	 * digits — and every outcome now costs the same. (`apps/collections` reached the same
+	 * conclusion for its per-file keys in 2026-08-14; this is that reasoning, kept.)
 	 */
 	async unlock(verifier: string): Promise<MasterLockUnlockResult> {
 		const now = this.now();
@@ -302,86 +441,201 @@ export class MasterLock {
 		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;
+		let opened: MasterLockAccount | null = null;
+		let unparsable = 0;
+		if (retryAfterMs === 0 && record) {
+			for (const account of record.accounts) {
+				const genuine = await verifyArgon(verifier, account.verifierHash);
+				// `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) unparsable += 1;
+				else if (genuine) opened ??= account;
+			}
+		}
 		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) {
+		if (!opened) {
+			if (unparsable > 0 && unparsable === (record?.accounts.length ?? 0)) {
+				this.log(
+					"🔴 master lock: every stored verifier hash is unparsable — nothing can unlock",
+				);
+				return { ok: false, retryAfterMs: 0 };
+			}
 			this.failures += 1;
 			this.lastFailureAt = now;
 			return { ok: false, retryAfterMs: windowRemaining(this.failures, this.lastFailureAt, now) };
 		}
 
+		return { ok: true, ...this.open(opened.id, now) };
+	}
+
+	/**
+	 * Mint a token for one account and start its idle clock. The one place a session is
+	 * created, so `unlock` and `enroll` cannot disagree about what an unlock is.
+	 */
+	private open(accountId: string, now: number): { token: string; accountId: string } {
 		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.sessions.set(token, { accountId, lastActivityAt: now });
 		this.scheduleExpiry();
 		if (wasLocked) this.onLockedChange?.(false);
-		return { ok: true, token };
+		return { token, accountId };
 	}
 
 	/**
-	 * Choose the FIRST master password for this lock — per-person mode only.
+	 * Choose the FIRST master password for this app, creating its first tenant.
 	 *
 	 * ── 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
+	 * It looks like "anyone who can reach the endpoint sets the password", and the two
+	 * things that make it not are checked here rather than at the caller:
+	 *
+	 *  1. **It refuses once any account exists.** There is no overwrite branch and no
+	 *     force flag; rotation is {@link change}, which demands the current password
+	 *     re-typed, and a second tenant is {@link addAccount}, which demands the same. So
+	 *     this can only ever create the password that was never set.
+	 *  2. **Whoever reaches it is already inside the building.** The guard runs behind the
+	 *     app's own sign-in, so to enroll at all a caller must hold a live session for an
+	 *     account the app admits — and if they hold that, the master lock was never what
+	 *     was standing between them and the app.
+	 *
+	 * 🔴 It is no longer gated on a per-person MODE. The owner's ruling is that an app
+	 * with no master password boots to nothing until one is created, so the form is the
+	 * way out of that state on every app — see {@link awaitingEnrollment}.
+	 *
+	 * The unlock is minted with the account, deliberately: being asked to type a password
 	 * back at the person who just chose it, twice, teaches them the app is broken.
 	 */
 	async enroll(input: {
 		kdf: MasterLockKdfParams;
 		verifier: string;
+		label?: string;
+		hint?: string;
 	}): Promise<MasterLockEnrollResult> {
-		if (!this.enrollable) return { ok: false, reason: "not-enrollable" };
 		// Re-read the store rather than trusting the field: two tabs can submit the
 		// choose-a-password form at once, and the second must lose rather than replace.
-		if (this.record || readRecord(this.store.read())) {
-			this.record ??= readRecord(this.store.read());
+		const stored = readRecord(this.store.read());
+		if (stored && stored.accounts.length > 0) {
+			this.record = stored;
 			return { ok: false, reason: "already-configured" };
 		}
+		if (this.configured) return { ok: false, reason: "already-configured" };
 		if (!isMasterLockKdfParams(input.kdf) || typeof input.verifier !== "string" || !input.verifier) {
 			return { ok: false, reason: "invalid" };
 		}
-		const next: MasterLockRecord = {
-			kdf: input.kdf,
+		const now = this.now();
+		const account: MasterLockAccount = {
+			id: FIRST_ACCOUNT_ID,
+			label: cleanLabel(input.label) || "Account 1",
+			hint: cleanHint(input.hint),
 			verifierHash: await Bun.password.hash(input.verifier, { algorithm: "argon2id" }),
-			idleMs: clampIdleMs(undefined),
+			createdAt: now,
 		};
-		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.write({ kdf: input.kdf, idleMs: clampIdleMs(this.record?.idleMs), accounts: [account] });
 		this.log("master lock: a first master password was chosen");
-		return { ok: true, token };
+		return { ok: true, ...this.open(account.id, now) };
+	}
+
+	/**
+	 * Add ANOTHER master password, and with it another tenant.
+	 *
+	 * The owner's model, in his words: *"The master passwords represent their own tenants
+	 * or you can think of it as a fully separate account even though I am the user in both
+	 * cases … If I login with a master password I only see the files I added or removed
+	 * with that login."*
+	 *
+	 * ── The three refusals, and why each one is here ────────────────────────────
+	 *
+	 *  1. **No live unlock → refused.** Minting a tenant is an action from INSIDE the app,
+	 *     not a way into it.
+	 *  2. **The current password, re-typed.** An open session proves somebody is at the
+	 *     keyboard, not that it is the owner — the same reasoning {@link change} runs on,
+	 *     and creating a hidden second library is at least as consequential as a rotation.
+	 *  3. 🔴 **A password that already opens something is refused.** Two accounts sharing
+	 *     one password would make {@link unlock} serve whichever the loop reached first,
+	 *     so the owner would type the password they have always typed and be handed an
+	 *     empty library — with their real one apparently gone. It costs one argon2id per
+	 *     existing account, at creation time only.
+	 *
+	 * It does NOT unlock into the new account. Switching tenants means typing that
+	 * tenant's password, which is the whole boundary.
+	 */
+	async addAccount(
+		req: Request,
+		input: { currentVerifier: string; verifier: string; label: string; hint?: string },
+	): Promise<MasterLockAddAccountResult> {
+		const record = this.record;
+		if (!record || record.accounts.length === 0) return { ok: false, reason: "unconfigured" };
+		const currentId = this.accountFor(req);
+		if (!currentId) return { ok: false, reason: "locked" };
+		const current = this.accountById(currentId);
+		if (!current) return { ok: false, reason: "locked" };
+
+		const label = cleanLabel(input.label);
+		if (!label || typeof input.verifier !== "string" || !input.verifier) {
+			return { ok: false, reason: "invalid" };
+		}
+
+		const genuine = await verifyArgon(input.currentVerifier, current.verifierHash);
+		await equalize(input.currentVerifier);
+		if (genuine === null) return { ok: false, reason: "unconfigured" };
+		if (!genuine) return { ok: false, reason: "wrong" };
+
+		for (const account of record.accounts) {
+			if (await verifyArgon(input.verifier, account.verifierHash)) {
+				return { ok: false, reason: "duplicate" };
+			}
+		}
+
+		const now = this.now();
+		const account: MasterLockAccount = {
+			id: nextAccountId(record.accounts),
+			label,
+			hint: cleanHint(input.hint),
+			verifierHash: await Bun.password.hash(input.verifier, { algorithm: "argon2id" }),
+			createdAt: now,
+		};
+		this.write({ ...record, accounts: [...record.accounts, account] });
+		this.log(`master lock: a new account was created (${account.id})`);
+		return {
+			ok: true,
+			account: {
+				id: account.id,
+				label: account.label,
+				hint: account.hint,
+				createdAt: account.createdAt,
+				current: false,
+			},
+		};
+	}
+
+	/**
+	 * Rename an account or rewrite its hint. Never its password — that is {@link change}.
+	 *
+	 * 🔴 Only the account the caller's own unlock opened. Editing a sibling would let a
+	 * session that holds one tenant's password rewrite another tenant's hint, which is the
+	 * one field designed to be read by somebody who is locked out.
+	 */
+	editAccount(req: Request, input: { id: string; label?: string; hint?: string }): boolean {
+		const record = this.record;
+		const currentId = this.accountFor(req);
+		if (!record || !currentId || currentId !== input.id) return false;
+		const accounts = record.accounts.map((account) =>
+			account.id === input.id
+				? {
+						...account,
+						label: input.label === undefined ? account.label : cleanLabel(input.label) || account.label,
+						hint: input.hint === undefined ? account.hint : cleanHint(input.hint),
+					}
+				: account,
+		);
+		this.write({ ...record, accounts });
+		return true;
 	}
 
 	/**
@@ -396,16 +650,19 @@ export class MasterLock {
 		// 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.
+		let slid = false;
 		for (const presented of presentedTokens(req)) {
-			for (const live of this.sessions.keys()) {
+			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.
 				if (constantTimeEqual(presented, live)) {
-					this.sessions.set(live, this.now());
-					this.scheduleExpiry();
-					return true;
+					this.sessions.set(live, { ...session, lastActivityAt: this.now() });
+					slid = true;
 				}
 			}
 		}
-		return false;
+		if (slid) this.scheduleExpiry();
+		return slid;
 	}
 
 	/** The manual lock — the owner's *"I want a lock option to turn the site back to needing
@@ -421,39 +678,62 @@ export class MasterLock {
 	}
 
 	/**
-	 * 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.
+	 * Rotate ONE account's master password — the account the caller's own unlock opened.
+	 *
+	 * 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.
+	 * 🔴 **The account id does not move, so the tenant's library does not move.** That is
+	 * the owner's requirement stated as code: *"If I change account 2 password it just
+	 * changes how I get the access. For instance I could change it from 'password' to
+	 * 'passwordIPicked' later and I would still access the same content afterward."*
+	 *
+	 * 🔴 **No new KDF params.** They are shared by every account on this app, so minting a
+	 * fresh salt here would invalidate every SIBLING's stored hash — rotating account 2
+	 * would lock the owner out of account 1, silently, with no way back. See
+	 * {@link MasterLockRecord}.
 	 */
-	async change(input: {
-		currentVerifier: string;
-		kdf: MasterLockKdfParams;
-		verifier: string;
-	}): Promise<{ ok: true } | { ok: false; reason: "wrong" | "invalid" | "unconfigured" }> {
+	async change(
+		req: Request,
+		input: { currentVerifier: string; verifier: string },
+	): Promise<{ ok: true } | { ok: false; reason: "wrong" | "invalid" | "unconfigured" | "locked" }> {
 		const record = this.record;
-		if (!record) return { ok: false, reason: "unconfigured" };
-		if (!isMasterLockKdfParams(input.kdf) || typeof input.verifier !== "string" || !input.verifier) {
+		if (!record || record.accounts.length === 0) return { ok: false, reason: "unconfigured" };
+		const currentId = this.accountFor(req);
+		if (!currentId) return { ok: false, reason: "locked" };
+		const current = this.accountById(currentId);
+		if (!current) return { ok: false, reason: "locked" };
+		if (typeof input.verifier !== "string" || !input.verifier) {
 			return { ok: false, reason: "invalid" };
 		}
-		const genuine = await verifyArgon(input.currentVerifier, record.verifierHash);
+		const genuine = await verifyArgon(input.currentVerifier, current.verifierHash);
 		await equalize(input.currentVerifier);
 		if (genuine === null) return { ok: false, reason: "unconfigured" };
 		if (!genuine) return { ok: false, reason: "wrong" };
 
-		const next: MasterLockRecord = {
-			kdf: input.kdf,
-			verifierHash: await Bun.password.hash(input.verifier, { algorithm: "argon2id" }),
-			idleMs: record.idleMs,
-		};
-		this.record = next;
-		this.store.write(JSON.stringify(next));
+		// 🔴 Refused when the NEW password already opens a sibling, for the reason
+		// `addAccount` gives at length: two accounts under one password make `unlock` serve
+		// whichever the loop reaches first, and the owner would find the wrong library.
+		for (const account of record.accounts) {
+			if (account.id === current.id) continue;
+			if (await verifyArgon(input.verifier, account.verifierHash)) {
+				return { ok: false, reason: "invalid" };
+			}
+		}
+
+		const verifierHash = await Bun.password.hash(input.verifier, { algorithm: "argon2id" });
+		this.write({
+			...record,
+			accounts: record.accounts.map((account) =>
+				account.id === current.id ? { ...account, verifierHash } : account,
+			),
+		});
 		// 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.
+		// leaves the session that worried you still holding the door. ALL of them, including
+		// the other accounts': "lock this app" has never meant "lock part of it".
 		this.lock();
-		this.log("master lock: master password rotated for this app");
+		this.log(`master lock: password rotated for ${current.id}`);
 		return { ok: true };
 	}
 
@@ -462,12 +742,18 @@ export class MasterLock {
 		const record = this.record;
 		const idleMs = clampIdleMs(value);
 		if (!record) return idleMs;
-		this.record = { ...record, idleMs };
-		this.store.write(JSON.stringify(this.record));
+		this.write({ ...record, idleMs });
 		this.scheduleExpiry();
 		return idleMs;
 	}
 
+	/** Persist the record and keep the field in step. One place, so no path can write the
+	 *  store and forget the copy this process is answering from. */
+	private write(record: MasterLockRecord): void {
+		this.record = record;
+		this.store.write(JSON.stringify(record));
+	}
+
 	/** Drop the in-memory unlock without notifying — for tests between cases. */
 	resetForTest(): void {
 		this.sessions.clear();
@@ -483,9 +769,9 @@ export class MasterLock {
 		if (!record || this.sessions.size === 0) return;
 		const now = this.now();
 		const wasOpen = this.sessions.size > 0;
-		for (const [token, lastActivityAt] of this.sessions) {
+		for (const [token, session] 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 (now - session.lastActivityAt > record.idleMs) this.sessions.delete(token);
 		}
 		if (wasOpen && this.sessions.size === 0) {
 			this.clearExpiry();
@@ -507,7 +793,10 @@ export class MasterLock {
 		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());
+		let soonest = Number.POSITIVE_INFINITY;
+		for (const session of this.sessions.values()) {
+			if (session.lastActivityAt < soonest) soonest = session.lastActivityAt;
+		}
 		const due = soonest + record.idleMs - this.now();
 		const timer = setTimeout(() => {
 			this.expiryTimer = null;
@@ -545,9 +834,98 @@ export function readRecord(json: string | null | undefined): MasterLockRecord |
 	if (parsed === null || typeof parsed !== "object") return null;
 	const value = parsed as Record<string, unknown>;
 	if (!isMasterLockKdfParams(value.kdf)) return null;
-	const hash = typeof value.verifierHash === "string" ? unquote(value.verifierHash) : "";
+	const idleMs = clampIdleMs(value.idleMs);
+
+	/*
+	 * 🔴 The LEGACY shape — `{kdf, verifierHash, idleMs}`, one password and no accounts —
+	 * is still read, and reading it is not a courtesy. Three live things carry it:
+	 *
+	 *   · every `MASTER_LOCK_SEED` in the fleet's 0600 secrets files, each one copied from
+	 *     `apps/vault`'s own `vault_keys` row, which will never learn a new shape;
+	 *   · `mintMasterLockSeed`, which produces exactly that record for a stage;
+	 *   · the row an app that has not yet been upgraded already has in its database.
+	 *
+	 * It becomes account {@link FIRST_ACCOUNT_ID}, whose id is FIXED — the adopting app
+	 * stamps its existing rows with that id, so a random one would orphan the entire
+	 * library this migration exists to carry across. Nothing is rewritten on read; the
+	 * upgraded shape is persisted the next time anything calls `write`.
+	 */
+	if (!Array.isArray(value.accounts)) {
+		const hash = typeof value.verifierHash === "string" ? unquote(value.verifierHash) : "";
+		if (!hash.startsWith("$argon2")) return null;
+		return {
+			kdf: value.kdf,
+			idleMs,
+			accounts: [
+				{
+					id: FIRST_ACCOUNT_ID,
+					label: "Account 1",
+					hint: "",
+					verifierHash: hash,
+					createdAt: 0,
+				},
+			],
+		};
+	}
+
+	const accounts: MasterLockAccount[] = [];
+	for (const entry of value.accounts) {
+		const account = readAccount(entry);
+		// 🔴 One malformed account drops THAT account, never the record. The alternative
+		// loses every other tenant to one bad row — and this is the only copy of what says
+		// which password opens which library.
+		if (account && !accounts.some((seen) => seen.id === account.id)) accounts.push(account);
+	}
+	// An empty list is legitimate: an app nobody has chosen a password for yet.
+	return { kdf: value.kdf, idleMs, accounts };
+}
+
+function readAccount(value: unknown): MasterLockAccount | null {
+	if (value === null || typeof value !== "object") return null;
+	const row = value as Record<string, unknown>;
+	const id = typeof row.id === "string" ? row.id.trim() : "";
+	// The id reaches an app's SQL and its object-store key namespace, so the shape is
+	// fenced here rather than at every consumer — the same reasoning
+	// `masterLockPrincipalKey` records for a principal id.
+	if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(id)) return null;
+	const hash = typeof row.verifierHash === "string" ? unquote(row.verifierHash) : "";
 	if (!hash.startsWith("$argon2")) return null;
-	return { kdf: value.kdf, verifierHash: hash, idleMs: clampIdleMs(value.idleMs) };
+	return {
+		id,
+		label: cleanLabel(typeof row.label === "string" ? row.label : "") || id,
+		hint: cleanHint(typeof row.hint === "string" ? row.hint : ""),
+		verifierHash: hash,
+		createdAt: typeof row.createdAt === "number" && Number.isFinite(row.createdAt) ? row.createdAt : 0,
+	};
+}
+
+/** `acct-1`, `acct-2`, … — the lowest number no live account already holds. Sequential
+ *  because the owner reads these ids out of his own vault and types them into a terminal;
+ *  a random id would be one more thing to write down. */
+function nextAccountId(accounts: readonly MasterLockAccount[]): string {
+	const taken = new Set(accounts.map((account) => account.id));
+	for (let n = 1; n <= accounts.length + 1; n += 1) {
+		const id = `acct-${n}`;
+		if (!taken.has(id)) return id;
+	}
+	return `acct-${accounts.length + 1}`;
+}
+
+/** A label is a display string. Trimmed, capped, and never empty-by-whitespace. */
+function cleanLabel(value: string | undefined): string {
+	return (value ?? "").replace(/\s+/g, " ").trim().slice(0, 60);
+}
+
+/**
+ * A hint is the owner's own words, and the ONE field here that is readable while locked.
+ *
+ * Capped and stripped of newlines so it cannot become a payload or a wall of text on the
+ * lock screen. Deliberately NOT checked against the password: this server has never seen
+ * the password and cannot, which is the property the whole feature rests on — so "your
+ * hint contains your password" is a warning the browser could give and this cannot.
+ */
+function cleanHint(value: string | undefined): string {
+	return (value ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
 }
 
 /**