cursedbelt-server 2.1.0 → 3.0.1

package/dist/server/activity/index.d.ts

@@ -10,7 +10,7 @@
  *
  * ── Retention ───────────────────────────────────────────────────────────────
  * This package never deletes an event. An app whose stream is high-volume opts
- * into the fleet standard (`docs/retention.md` in `cursed-satellites`) by
+ * into the fleet standard (`cursedbelt-server/retention`, in this package) by
  * declaring the table, which puts the number under the owner's control in the
  * station rather than in a constant here:
  *

package/dist/server/activity/index.js

@@ -10,7 +10,7 @@
  *
  * ── Retention ───────────────────────────────────────────────────────────────
  * This package never deletes an event. An app whose stream is high-volume opts
- * into the fleet standard (`docs/retention.md` in `cursed-satellites`) by
+ * into the fleet standard (`cursedbelt-server/retention`, in this package) by
  * declaring the table, which puts the number under the owner's control in the
  * station rather than in a constant here:
  *

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

@@ -49,5 +49,15 @@ export interface MasterLockGuardOptions extends LockPageOptions {
 export interface MasterLockGuard {
     /** `Response` when handled, `null` when the app should serve the request. */
     handle(req: Request): Promise<Response | null>;
+    /**
+     * 🔴 **WHICH tenant this request is for** — the answer an app must scope every query by.
+     *
+     * `null` when the request carries no live unlock, which is exactly when {@link handle}
+     * would have refused it. So the safe shape in an app is to read this AFTER the guard has
+     * stood aside, and to treat `null` as "serve nothing" rather than "serve the default" —
+     * a fallback tenant is how a locked request ends up being answered with somebody's
+     * library.
+     */
+    accountFor(req: Request): string | null;
 }
 export declare function createMasterLockGuard(options: MasterLockGuardOptions): MasterLockGuard;

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

@@ -34,23 +34,23 @@ export function createMasterLockGuard(options) {
     /** The ONE refusal. Identical for wrong, throttled, unconfigured and not-unlocked. */
     const refuse = (retryAfterMs = 0) => Response.json({ error: "locked", retryAfterMs }, { status: 401, headers: { ...noStore, [MASTER_LOCK_STATE_HEADER]: "locked" } });
     /**
-     * 🔴 May THIS request through — and the difference between the two modes is the whole
-     * security property of the per-person wall.
+     * 🔴 May THIS request through — and the answer is a PRESENTED TOKEN, always.
      *
-     * **App-wide**: `unlocked` is enough. The site has one user and one unlock; the token
-     * is how a caller with no cookie jar says "it's still me", not a per-browser
-     * credential. Reading the ambient state is the behaviour `apps/collections` and the
-     * binary-server inspector have always had.
+     * Until the accounts model there was a second branch: an app-wide lock let `unlocked`
+     * alone open the door, on the reasoning that such a site had one user and one unlock,
+     * so the token was merely how a caller with no cookie jar said "it's still me". The
+     * per-person wall already refused that shape, and 2026-08-25 measured why — with
+     * `unlocked ||` in front, one browser unlocking meant every OTHER browser signed in as
+     * that person walked straight through having typed nothing, and an invented
+     * `x-master-lock` value was accepted because the check never looked at it.
      *
-     * **Per-person**: the token is REQUIRED. `unlocked` there means only "somebody's
-     * device is open", and honouring that would make the unlock ambient — measured while
-     * building this (2026-08-25): with `unlocked ||` in front, one browser unlocking meant
-     * every OTHER browser signed in as that person walked straight through, having typed
-     * nothing. The owner's phone would ride his desk's unlock, and an invented
-     * `x-master-lock` value would be accepted because the check never looked at it. Two
-     * tests in `principals.spec.ts` fail on the `||`, which is why it is gone.
+     * The accounts model removes the last reason to keep the branch, and turns it from
+     * sloppy into wrong: the password decides WHICH TENANT'S DATA the app serves, so a
+     * request with no token has no account, and admitting it means serving whichever
+     * library somebody else's browser happens to have open. There is one rule now, for
+     * every app.
      */
-    const opens = (lock, req) => lock.isEnrollable ? lock.presents(req) : lock.unlocked || lock.presents(req);
+    const opens = (lock, req) => lock.presents(req);
     async function handleOwnRoute(req, url, lock) {
         const path = url.pathname;
         const secure = isSecure(url, req);
@@ -66,7 +66,22 @@ export function createMasterLockGuard(options) {
                 });
             }
             if (path === MASTER_LOCK_PATHS.status) {
-                return Response.json(lock.status(), { headers: noStore });
+                return Response.json(lock.status(req), { headers: noStore });
+            }
+            if (path === MASTER_LOCK_PATHS.hints) {
+                // 🔴 Readable WHILE LOCKED, and the only surface here that is. See the path's
+                // note in `cursedbelt-core/master-lock/wire.ts`: a hint nobody can read until
+                // they are already in is not a hint, and everyone who reaches this has passed
+                // the app's own owner-only sign-in. It is a separate route, fetched only when
+                // somebody clicks "I forgot", so the default lock screen stays byte-identical
+                // whether this app has one tenant or ten.
+                return Response.json({ hints: lock.hints() }, { headers: noStore });
+            }
+            if (path === MASTER_LOCK_PATHS.accounts) {
+                // Unlike the hints, this needs the site already open — it names every tenant.
+                if (!opens(lock, req))
+                    return refuse();
+                return Response.json({ accounts: lock.summaries(req) }, { headers: noStore });
             }
             if (path === MASTER_LOCK_PATHS.page || path === MASTER_LOCK_PREFIX) {
                 // Already open FOR THIS CALLER, so there is nothing to type — send them to
@@ -79,6 +94,19 @@ export function createMasterLockGuard(options) {
             }
             return new Response("not found", { status: 404, headers: noStore });
         }
+        if (req.method === "PATCH" && path === MASTER_LOCK_PATHS.accounts) {
+            if (!opens(lock, req))
+                return refuse();
+            const body = await readJson(req);
+            const ok = lock.editAccount(req, {
+                id: typeof body?.id === "string" ? body.id : "",
+                ...(typeof body?.label === "string" ? { label: body.label } : {}),
+                ...(typeof body?.hint === "string" ? { hint: body.hint } : {}),
+            });
+            if (!ok)
+                return Response.json({ error: "wrong" }, { status: 400, headers: noStore });
+            return Response.json({ ok: true, accounts: lock.summaries(req) }, { headers: noStore });
+        }
         if (req.method !== "POST") {
             return new Response("method not allowed", { status: 405, headers: noStore });
         }
@@ -93,7 +121,7 @@ export function createMasterLockGuard(options) {
             // becomes a way to ask whether a given account has a master password yet.
             if (!result.ok)
                 return refuse();
-            return Response.json({ ok: true, idleMs: lock.idleMs }, { headers: { ...noStore, "set-cookie": cookie(result.token, secure) } });
+            return Response.json({ ok: true, idleMs: lock.idleMs, accountId: result.accountId }, { headers: { ...noStore, "set-cookie": cookie(result.token, secure) } });
         }
         if (path === MASTER_LOCK_PATHS.unlock) {
             const body = await readJson(req);
@@ -101,7 +129,11 @@ export function createMasterLockGuard(options) {
             const result = await lock.unlock(verifier);
             if (!result.ok)
                 return refuse(result.retryAfterMs);
-            return Response.json({ ok: true, idleMs: lock.idleMs }, { headers: { ...noStore, "set-cookie": cookie(result.token, secure) } });
+            // 🔴 The account id is in the REPLY and not only in the cookie, because the page
+            // that just unlocked has to reload into the right tenant. It names the account
+            // that opened and never the ones that did not, so a wrong password still learns
+            // nothing about what else is here.
+            return Response.json({ ok: true, idleMs: lock.idleMs, accountId: result.accountId }, { headers: { ...noStore, "set-cookie": cookie(result.token, secure) } });
         }
         // Everything below CHANGES something and therefore needs the site already open.
         if (!lock.presents(req))
@@ -119,11 +151,43 @@ export function createMasterLockGuard(options) {
             const idleMs = lock.setIdleMs(Number(body?.idleMs));
             return Response.json({ ok: true, idleMs }, { headers: noStore });
         }
+        if (path === MASTER_LOCK_PATHS.accounts) {
+            const body = await readJson(req);
+            const result = await lock.addAccount(req, {
+                currentVerifier: typeof body?.currentVerifier === "string" ? body.currentVerifier : "",
+                verifier: typeof body?.verifier === "string" ? body.verifier : "",
+                label: typeof body?.label === "string" ? body.label : "",
+                hint: typeof body?.hint === "string" ? body.hint : "",
+            });
+            if (!result.ok) {
+                return Response.json({ error: result.reason }, { status: 400, headers: noStore });
+            }
+            // 🔴 No cookie. Creating a tenant does not enter it — switching means typing that
+            // tenant's password, which is the entire boundary this feature is made of.
+            return Response.json({ ok: true, account: result.account }, { headers: noStore });
+        }
         if (path === MASTER_LOCK_PATHS.change) {
             const body = await readJson(req);
-            const result = await lock.change({
+            /*
+             * 🔴 An OLDER client sends a freshly-minted `kdf` with a rotation, because that is
+             * what the wire looked like before accounts existed. Ignoring it silently would be
+             * a lockout, not a compatibility shim: the verifier in the same body was derived
+             * under THAT salt, so storing it would leave a hash nothing can ever match — the
+             * owner would set a new password, be logged out by the rotation, and find that
+             * neither the old nor the new one opens the app.
+             *
+             * There is no safe way to honour it either, since every account on this app shares
+             * one descriptor. So it is refused, loudly, with the one thing that distinguishes
+             * it from a wrong password.
+             */
+            if (body?.kdf !== undefined) {
+                const supplied = body.kdf;
+                if (!lock.kdf || supplied?.salt !== lock.kdf.salt) {
+                    return Response.json({ error: "stale-client" }, { status: 409, headers: noStore });
+                }
+            }
+            const result = await lock.change(req, {
                 currentVerifier: typeof body?.currentVerifier === "string" ? body.currentVerifier : "",
-                kdf: body?.kdf,
                 verifier: typeof body?.verifier === "string" ? body.verifier : "",
             });
             if (!result.ok) {
@@ -136,6 +200,11 @@ export function createMasterLockGuard(options) {
         return new Response("not found", { status: 404, headers: noStore });
     }
     return {
+        accountFor(req) {
+            // The SAME resolution the guard itself uses, so an app can never be told a
+            // different tenant from the one the wall admitted.
+            return resolve(req)?.accountFor(req) ?? null;
+        },
         async handle(req) {
             const url = new URL(req.url);
             const own = url.pathname === MASTER_LOCK_PREFIX || url.pathname.startsWith(`${MASTER_LOCK_PREFIX}/`);

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

@@ -16,6 +16,6 @@
 export { type MasterLockGuard, type MasterLockGuardOptions, createMasterLockGuard } from "./guard";
 export { LOCK_SCRIPT, LOCK_STYLE, type LockPageOptions, lockPageHtml } from "./lockPage";
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, type MasterLockDirectoryOptions, masterLockPrincipalKey, } from "./principals";
-export { MasterLock, type MasterLockEnrollResult, type MasterLockOptions, type MasterLockRecord, type MasterLockStore, type MasterLockUnlockResult, readRecord, } from "./masterLock";
+export { FIRST_ACCOUNT_ID, MasterLock, type MasterLockAccount, type MasterLockAddAccountResult, type MasterLockEnrollResult, type MasterLockOptions, type MasterLockRecord, type MasterLockStore, type MasterLockUnlockResult, readRecord, } from "./masterLock";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, type MintMasterLockSeedOptions, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed";
 export { MASTER_LOCK_SETTING_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store";

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

@@ -16,6 +16,6 @@
 export { createMasterLockGuard } from "./guard";
 export { LOCK_SCRIPT, LOCK_STYLE, lockPageHtml } from "./lockPage";
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, masterLockPrincipalKey, } from "./principals";
-export { MasterLock, readRecord, } from "./masterLock";
+export { FIRST_ACCOUNT_ID, MasterLock, readRecord, } from "./masterLock";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed";
 export { MASTER_LOCK_SETTING_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store";

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

@@ -21,7 +21,7 @@ export interface LockPageOptions {
  */
 export declare function lockPageHtml(options: LockPageOptions): string;
 /** The stylesheet. Follows the viewer's theme and commits to nothing else. */
-export declare const LOCK_STYLE = ":root{color-scheme:light dark;\n  --ml-bg:#f4f5f7;--ml-card:#ffffff;--ml-text:#14171c;--ml-muted:#69707c;--ml-border:#d9dde3;\n  --ml-accent:#1f6feb;--ml-accent-text:#ffffff;--ml-danger:#b42318;\n  --ml-shadow:0 18px 48px rgba(16,18,22,.14)}\n@media (prefers-color-scheme:dark){:root{\n  --ml-bg:#0d0f13;--ml-card:#171a20;--ml-text:#e7eaef;--ml-muted:#8b93a1;--ml-border:#2b3039;\n  --ml-accent:#4f8cf7;--ml-accent-text:#0b0d11;--ml-danger:#f97066;\n  --ml-shadow:0 18px 48px rgba(0,0,0,.55)}}\n*{box-sizing:border-box}\nbody{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px;\n  background:var(--ml-bg);color:var(--ml-text);\n  font:15px/1.55 ui-sans-serif,system-ui,-apple-system,\"Segoe UI\",sans-serif}\n.card{width:100%;max-width:23rem;background:var(--ml-card);border:1px solid var(--ml-border);\n  border-radius:16px;padding:28px 26px 24px;box-shadow:var(--ml-shadow);text-align:center}\n.glyph{font-size:30px;line-height:1;margin-bottom:10px}\nh1{margin:0 0 6px;font-size:18px;font-weight:650;letter-spacing:-.01em}\n.note{margin:0 0 20px;font-size:13px;color:var(--ml-muted)}\n.field{display:block;text-align:left;margin-bottom:14px}\n.field span{display:block;font-size:12px;font-weight:600;color:var(--ml-muted);margin-bottom:6px}\ninput{width:100%;height:40px;padding:0 12px;border:1px solid var(--ml-border);border-radius:9px;\n  background:var(--ml-bg);color:inherit;font:inherit}\ninput:focus{outline:2px solid var(--ml-accent);outline-offset:1px;border-color:transparent}\nbutton{width:100%;height:40px;border:0;border-radius:9px;background:var(--ml-accent);\n  color:var(--ml-accent-text);font:inherit;font-weight:600;cursor:pointer}\nbutton[disabled]{opacity:.6;cursor:progress}\n.status{margin:14px 0 0;min-height:1.2em;font-size:12.5px;color:var(--ml-muted)}\n.status[data-tone=\"error\"]{color:var(--ml-danger)}\n";
+export declare const LOCK_STYLE = ":root{color-scheme:light dark;\n  --ml-bg:#f4f5f7;--ml-card:#ffffff;--ml-text:#14171c;--ml-muted:#69707c;--ml-border:#d9dde3;\n  --ml-accent:#1f6feb;--ml-accent-text:#ffffff;--ml-danger:#b42318;\n  --ml-shadow:0 18px 48px rgba(16,18,22,.14)}\n@media (prefers-color-scheme:dark){:root{\n  --ml-bg:#0d0f13;--ml-card:#171a20;--ml-text:#e7eaef;--ml-muted:#8b93a1;--ml-border:#2b3039;\n  --ml-accent:#4f8cf7;--ml-accent-text:#0b0d11;--ml-danger:#f97066;\n  --ml-shadow:0 18px 48px rgba(0,0,0,.55)}}\n*{box-sizing:border-box}\nbody{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px;\n  background:var(--ml-bg);color:var(--ml-text);\n  font:15px/1.55 ui-sans-serif,system-ui,-apple-system,\"Segoe UI\",sans-serif}\n.card{width:100%;max-width:23rem;background:var(--ml-card);border:1px solid var(--ml-border);\n  border-radius:16px;padding:28px 26px 24px;box-shadow:var(--ml-shadow);text-align:center}\n.glyph{font-size:30px;line-height:1;margin-bottom:10px}\nh1{margin:0 0 6px;font-size:18px;font-weight:650;letter-spacing:-.01em}\n.note{margin:0 0 20px;font-size:13px;color:var(--ml-muted)}\n.field{display:block;text-align:left;margin-bottom:14px}\n.field span{display:block;font-size:12px;font-weight:600;color:var(--ml-muted);margin-bottom:6px}\ninput{width:100%;height:40px;padding:0 12px;border:1px solid var(--ml-border);border-radius:9px;\n  background:var(--ml-bg);color:inherit;font:inherit}\ninput:focus{outline:2px solid var(--ml-accent);outline-offset:1px;border-color:transparent}\nbutton{width:100%;height:40px;border:0;border-radius:9px;background:var(--ml-accent);\n  color:var(--ml-accent-text);font:inherit;font-weight:600;cursor:pointer}\nbutton[disabled]{opacity:.6;cursor:progress}\n.status{margin:14px 0 0;min-height:1.2em;font-size:12.5px;color:var(--ml-muted)}\n.status[data-tone=\"error\"]{color:var(--ml-danger)}\n.field span em{font-style:normal;font-weight:500;text-transform:none;opacity:.7}\nbutton.quiet{margin-top:10px;height:32px;background:none;color:var(--ml-muted);font-weight:500;\n  font-size:12.5px;text-decoration:underline;text-underline-offset:3px}\nbutton.quiet:hover{color:var(--ml-text)}\nbutton.quiet[disabled]{opacity:.5}\n.hints{margin:10px 0 0;padding:12px 14px;text-align:left;border:1px solid var(--ml-border);\n  border-radius:10px;background:var(--ml-bg);font-size:12.5px}\n.hints dt{font-weight:650;color:var(--ml-text)}\n.hints dd{margin:2px 0 10px;color:var(--ml-muted);overflow-wrap:anywhere}\n.hints dd:last-child{margin-bottom:0}\n";
 /**
  * The page's script.
  *

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

@@ -34,7 +34,7 @@ export function lockPageHtml(options) {
         (enroll
             ? "You are signed in, but this site needs a master password of your own. " +
                 "Choose one now. Nobody else can see it and nobody else can reset it — " +
-                "if you forget it, it cannot be recovered."
+                "if you forget it, it cannot be recovered, so leave yourself a hint."
             : "This site is locked. Signing in is not enough — enter the master password to continue."));
     return `<!doctype html>
 <html lang="en">
@@ -64,11 +64,21 @@ export function lockPageHtml(options) {
       <input id="ml-confirm" type="password" name="confirm-master-password"
              autocomplete="new-password" required spellcheck="false" enterkeyhint="go"
              minlength="10">
+    </label>
+    <label class="field">
+      <span>Hint <em>optional</em></span>
+      <input id="ml-hint" type="text" name="master-password-hint" maxlength="200"
+             spellcheck="false" autocomplete="off"
+             placeholder="Something only you would understand">
     </label>`
         : ""}
     <button id="ml-submit" type="submit">${enroll ? "Set master password" : "Unlock"}</button>
   </form>
-  <p id="ml-status" class="status" role="status" aria-live="polite"></p>
+  <p id="ml-status" class="status" role="status" aria-live="polite"></p>${enroll
+        ? ""
+        : `
+  <button id="ml-forgot" type="button" class="quiet">I forgot which password</button>
+  <dl id="ml-hints" class="hints" hidden></dl>`}
 </main>
 <script type="module" src="${MASTER_LOCK_PATHS.script}"></script>
 </body>
@@ -103,6 +113,16 @@ button{width:100%;height:40px;border:0;border-radius:9px;background:var(--ml-acc
 button[disabled]{opacity:.6;cursor:progress}
 .status{margin:14px 0 0;min-height:1.2em;font-size:12.5px;color:var(--ml-muted)}
 .status[data-tone="error"]{color:var(--ml-danger)}
+.field span em{font-style:normal;font-weight:500;text-transform:none;opacity:.7}
+button.quiet{margin-top:10px;height:32px;background:none;color:var(--ml-muted);font-weight:500;
+  font-size:12.5px;text-decoration:underline;text-underline-offset:3px}
+button.quiet:hover{color:var(--ml-text)}
+button.quiet[disabled]{opacity:.5}
+.hints{margin:10px 0 0;padding:12px 14px;text-align:left;border:1px solid var(--ml-border);
+  border-radius:10px;background:var(--ml-bg);font-size:12.5px}
+.hints dt{font-weight:650;color:var(--ml-text)}
+.hints dd{margin:2px 0 10px;color:var(--ml-muted);overflow-wrap:anywhere}
+.hints dd:last-child{margin-bottom:0}
 `;
 /**
  * The page's script.
@@ -118,8 +138,11 @@ export const LOCK_SCRIPT = `const paths = ${JSON.stringify(MASTER_LOCK_PATHS)};
 const form = document.getElementById("ml-form");
 const input = document.getElementById("ml-input");
 const confirmInput = document.getElementById("ml-confirm");
+const hintInput = document.getElementById("ml-hint");
 const submit = document.getElementById("ml-submit");
 const status = document.getElementById("ml-status");
+const forgot = document.getElementById("ml-forgot");
+const hints = document.getElementById("ml-hints");
 
 function say(message, tone) {
   status.textContent = message;
@@ -217,7 +240,11 @@ async function doEnroll(password) {
     method: "POST",
     credentials: "same-origin",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({ kdf: params, verifier: verifier }),
+    body: JSON.stringify({
+      kdf: params,
+      verifier: verifier,
+      hint: hintInput ? hintInput.value : "",
+    }),
   });
   if (res.ok) { say("Master password set."); location.reload(); return true; }
   // The server collapses every enrollment refusal into one, so this cannot say more
@@ -243,6 +270,44 @@ async function doUnlock(password) {
   return false;
 }
 
+// ── the hints, and why they are behind a click ───────────────────────────────
+// Reading them says how many master passwords this app has and what each is called, which
+// is the one fact the rest of this page is built never to disclose. Fetching them on load
+// would leak it to anyone who merely opened the door; a button makes it something the
+// owner ASKS for. Everyone who gets this far has already passed the app's own sign-in.
+if (forgot && hints) {
+  forgot.addEventListener("click", async () => {
+    if (!hints.hidden) { hints.hidden = true; return; }
+    forgot.disabled = true;
+    try {
+      const res = await fetch(paths.hints, { credentials: "same-origin" });
+      const body = await res.json();
+      const rows = (body && body.hints) || [];
+      hints.replaceChildren();
+      if (rows.length === 0) {
+        const dd = document.createElement("dd");
+        dd.textContent = "No hints have been written yet.";
+        hints.append(dd);
+      }
+      for (const row of rows) {
+        const dt = document.createElement("dt");
+        dt.textContent = row.label;
+        const dd = document.createElement("dd");
+        // 🔴 textContent, never innerHTML. The hint is free text the owner typed and this
+        // page runs under a CSP that permits no inline script — writing it as markup would
+        // be the one way to get some in.
+        dd.textContent = row.hint || "— no hint —";
+        hints.append(dt, dd);
+      }
+      hints.hidden = false;
+    } catch {
+      say("Cannot reach this site right now.", "error");
+    } finally {
+      forgot.disabled = false;
+    }
+  });
+}
+
 form.addEventListener("submit", async (event) => {
   event.preventDefault();
   if (busy || submit.disabled) return;