cursedbelt-server 2.1.0 → 3.0.1

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

@@ -47,16 +47,75 @@
  * `retryAfterMs` a throttled caller is told — which they already know, since they are the
  * one who has been guessing.
  */
-import { type MasterLockKdfParams, type MasterLockStatus } from "cursedbelt-core/master-lock";
-/** The persisted record. Three public values — none of them is a secret, and the two that
- *  look like one are a salt and a one-way hash. */
+import { type MasterLockAccountSummary, type MasterLockKdfParams, type MasterLockStatus } from "cursedbelt-core/master-lock";
+/**
+ * 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 declare 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.
@@ -96,32 +155,19 @@ 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;
+    accountId: string;
 } | {
     ok: false;
     retryAfterMs: number;
@@ -131,9 +177,19 @@ export type MasterLockUnlockResult = {
 export type MasterLockEnrollResult = {
     ok: true;
     token: string;
+    accountId: string;
 } | {
     ok: false;
-    reason: "not-enrollable" | "already-configured" | "invalid";
+    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 app's lock. Constructed once at boot and held for the process's life.
@@ -150,8 +206,6 @@ export declare class MasterLock {
     private readonly now;
     private readonly onLockedChange;
     private readonly log;
-    /** Per-person mode — see {@link MasterLockOptions.enrollable}. */
-    private readonly enrollable;
     private record;
     /**
      * The live unlocks: token → when that token last saw real interaction. Moved only by
@@ -175,73 +229,182 @@ export declare class MasterLock {
     private failures;
     private lastFailureAt;
     constructor(options: MasterLockOptions);
-    /** 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;
     /** The params the browser must derive under, or null. Public by design. */
     get kdf(): MasterLockKdfParams | null;
     get idleMs(): number;
-    /** Is this lock in per-person mode? */
-    get isEnrollable(): boolean;
-    /** May a first password be chosen right now? Per-person mode, and no record yet. */
+    /** Every account, oldest first. Empty on an app nobody has chosen a password for. */
+    get accounts(): readonly MasterLockAccount[];
+    /**
+     * 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;
     /**
-     * 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(): boolean;
-    /** Milliseconds of idleness left before the unlock lapses; 0 when locked. */
     /** Milliseconds of idleness left before the LONGEST-lived unlock lapses; 0 when none
      *  is live. The status page counts down with it, so it is the most generous of the
      *  open devices rather than an arbitrary one. */
     get remainingMs(): number;
-    status(): MasterLockStatus;
-    /** Does this request carry the live unlock? The cookie, or the header for a caller with
-     *  no cookie jar. */
+    /**
+     * 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;
+    /**
+     * 🔴 **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;
+    /** 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;
+    /** One account by id, or null. */
+    accountById(id: string): MasterLockAccount | 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;
+    }[];
+    /** 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[];
+    /**
+     * 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.)
      */
     unlock(verifier: string): Promise<MasterLockUnlockResult>;
     /**
-     * Choose the FIRST master password for this lock — per-person mode only.
+     * 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;
+    /**
+     * 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 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.
+     *  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.
      *
-     * The unlock is minted with the record, deliberately: being asked to type a password
+     * 🔴 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.
      */
     enroll(input: {
         kdf: MasterLockKdfParams;
         verifier: string;
+        label?: string;
+        hint?: string;
     }): Promise<MasterLockEnrollResult>;
+    /**
+     * 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.
+     */
+    addAccount(req: Request, input: {
+        currentVerifier: string;
+        verifier: string;
+        label: string;
+        hint?: string;
+    }): Promise<MasterLockAddAccountResult>;
+    /**
+     * 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;
     /**
      * Record real user interaction. The ONE thing that moves the idle clock — see decision 2
      * in the module note.
@@ -254,25 +417,36 @@ export declare class MasterLock {
      *  the master password"*. Also what a change of password does to every open page. */
     lock(): void;
     /**
-     * Rotate this app's master password. Requires the CURRENT one, re-typed — an open session
-     * proves somebody is at the keyboard, not that it is the owner, and the whole feature
-     * exists for the minutes when it is not.
+     * 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}.
      */
-    change(input: {
+    change(req: Request, input: {
         currentVerifier: string;
-        kdf: MasterLockKdfParams;
         verifier: string;
     }): Promise<{
         ok: true;
     } | {
         ok: false;
-        reason: "wrong" | "invalid" | "unconfigured";
+        reason: "wrong" | "invalid" | "unconfigured" | "locked";
     }>;
     /** The owner's *"customizable by me"* idle timeout, clamped to the usable band. */
     setIdleMs(value: number): number;
+    /** 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;
     /** Drop the in-memory unlock without notifying — for tests between cases. */
     resetForTest(): void;
     /** Retire a session whose idle window has passed. Called on every read of the state, so