cursedbelt-server 2.1.0 → 3.0.1

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

@@ -48,6 +48,10 @@
  * one who has been guessing.
  */
 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
+ *  supposed to inherit. */
+export const FIRST_ACCOUNT_ID = "acct-1";
 const TOKEN_BYTES = 24;
 /**
  * One app's lock. Constructed once at boot and held for the process's life.
@@ -64,8 +68,6 @@ export class MasterLock {
     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
@@ -93,7 +95,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);
@@ -109,9 +110,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() {
-        return this.record !== null;
+        return this.accounts.length > 0;
     }
     /** The params the browser must derive under, or null. Public by design. */
     get kdf() {
@@ -120,50 +122,71 @@ export class MasterLock {
     get idleMs() {
         return this.record?.idleMs ?? clampIdleMs(undefined);
     }
-    /** Is this lock in per-person mode? */
-    get isEnrollable() {
-        return this.enrollable;
+    /** Every account, oldest first. Empty on an app nobody has chosen a password for. */
+    get accounts() {
+        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() {
-        return this.enrollable && this.record === null;
+        return this.accounts.length === 0;
     }
     /**
-     * Is the site open right now?
+     * Is anybody's unlock live 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.
+     * 🔴 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."*
      *
-     * 🔴 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}.
+     * 🔴 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() {
-        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() {
-        if (!this.record)
+        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() {
+    /**
+     * 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) {
+        const accountId = req ? this.accountFor(req) : null;
+        const account = accountId ? this.accountById(accountId) : null;
         return {
             configured: this.configured,
             enrollable: this.awaitingEnrollment,
@@ -172,30 +195,87 @@ 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) {
+    /**
+     * 🔴 **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) {
         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.
+            return null;
+        let found = null;
         for (const presented of presentedTokens(req)) {
-            for (const live of this.sessions.keys()) {
+            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))
-                    return true;
+                    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) {
+        return this.accountFor(req) !== null;
+    }
+    /** One account by id, or null. */
+    accountById(id) {
+        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() {
+        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) {
+        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) {
         const now = this.now();
@@ -203,83 +283,190 @@ 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 = 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.
+     */
+    open(accountId, 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.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:
+     * 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.
      *
-     *  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.
+     * 🔴 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 record, deliberately: being asked to type a password
+     * 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) {
-        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 = {
-            kdf: input.kdf,
+        const now = this.now();
+        const account = {
+            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, input) {
+        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 = {
+            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, input) {
+        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;
     }
     /**
      * Record real user interaction. The ONE thing that moves the idle clock — see decision 2
@@ -293,16 +480,20 @@ 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
      *  the master password"*. Also what a change of password does to every open page. */
@@ -317,37 +508,61 @@ export class MasterLock {
         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.
+     * Rotate ONE account's master password — the account the caller's own unlock opened.
      *
-     * 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.
+     * 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.
+     *
+     * 🔴 **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) {
+    async change(req, input) {
         const record = this.record;
-        if (!record)
+        if (!record || record.accounts.length === 0)
             return { ok: false, reason: "unconfigured" };
-        if (!isMasterLockKdfParams(input.kdf) || typeof input.verifier !== "string" || !input.verifier) {
+        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 = {
-            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 };
     }
     /** The owner's *"customizable by me"* idle timeout, clamped to the usable band. */
@@ -356,11 +571,16 @@ export class MasterLock {
         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. */
+    write(record) {
+        this.record = record;
+        this.store.write(JSON.stringify(record));
+    }
     /** Drop the in-memory unlock without notifying — for tests between cases. */
     resetForTest() {
         this.sessions.clear();
@@ -376,9 +596,9 @@ export class MasterLock {
             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)
+            if (now - session.lastActivityAt > record.idleMs)
                 this.sessions.delete(token);
         }
         if (wasOpen && this.sessions.size === 0) {
@@ -401,7 +621,11 @@ export class MasterLock {
             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;
@@ -441,10 +665,98 @@ export function readRecord(json) {
     const value = parsed;
     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 = [];
+    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) {
+    if (value === null || typeof value !== "object")
+        return null;
+    const row = value;
+    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) {
+    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) {
+    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) {
+    return (value ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
 }
 /**
  * Strip a wrapping quote pair.