cursedbelt-server 2.1.0 → 3.0.1

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

@@ -38,6 +38,12 @@
  * an env var that pre-set someone's password would be exactly the "one credential opens
  * everybody" shape this replaces. A principal with no record is `awaitingEnrollment` —
  * locked, and offered the choose-a-password form.
+ *
+ * 🔴 That last sentence used to need an `enrollable: true` flag, and does not any more.
+ * Failing closed with an enrollment form is now what EVERY lock does when it holds no
+ * account (see `masterLock.ts`'s `unlocked`), so the flag that used to separate the two
+ * modes has nothing left to decide. What still makes this file per-PERSON is the key each
+ * record is stored under, which is the only thing it ever really was.
  */
 import { createHash } from "node:crypto";
 import { MasterLock, readRecord } from "./masterLock";
@@ -86,7 +92,6 @@ export class MasterLockDirectory {
         };
         const lock = new MasterLock({
             store,
-            enrollable: true,
             ...(this.options.now ? { now: this.options.now } : {}),
             ...(this.options.log
                 ? { log: (line) => this.options.log?.(`[${principalId}] ${line}`) }

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

@@ -1,5 +1,5 @@
 import { type MasterLockKdfParams } from "cursedbelt-core/master-lock/kdf";
-import type { MasterLockRecord } from "./masterLock";
+import { type MasterLockRecord } from "./masterLock";
 /**
  * The idle window a freshly minted lock starts with.
  *
@@ -17,6 +17,10 @@ export interface MintMasterLockSeedOptions {
     idleMs?: number;
     /** Reuse existing params instead of generating a salt — for a rotation. */
     kdf?: MasterLockKdfParams;
+    /** What to call the tenant this seed creates. Defaults to `Account 1`. */
+    label?: string;
+    /** The owner's reminder for this password, shown on the lock page's "I forgot". */
+    hint?: string;
 }
 /**
  * `password` → the record an app can be seeded with.

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

@@ -24,6 +24,7 @@
  */
 import { DEFAULT_IDLE_MS } from "cursedbelt-core/master-lock/policy";
 import { deriveMasterLockVerifier, newMasterLockKdfParams, } from "cursedbelt-core/master-lock/kdf";
+import { FIRST_ACCOUNT_ID } from "./masterLock";
 /**
  * The idle window a freshly minted lock starts with.
  *
@@ -52,8 +53,24 @@ export async function mintMasterLockSeed(password, options = {}) {
     const verifier = await deriveMasterLockVerifier(password, kdf);
     return {
         kdf,
-        verifierHash: await Bun.password.hash(verifier, { algorithm: "argon2id" }),
         idleMs: options.idleMs ?? DEFAULT_SEED_IDLE_MS,
+        /*
+         * 🔴 ONE account, and its id is `FIRST_ACCOUNT_ID` rather than anything derived
+         * from `options`. A seed is what an app boots with before anybody has typed
+         * anything, so the tenant it names is the tenant whose rows the app already holds —
+         * and `readRecord` maps the legacy single-password shape onto the same id for
+         * exactly that reason. Two different "first" ids would give a seeded app and a
+         * migrated app different answers to "whose library is this".
+         */
+        accounts: [
+            {
+                id: FIRST_ACCOUNT_ID,
+                label: options.label ?? "Account 1",
+                hint: options.hint ?? "",
+                verifierHash: await Bun.password.hash(verifier, { algorithm: "argon2id" }),
+                createdAt: 0,
+            },
+        ],
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "2.1.0",
+	"version": "3.0.1",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -200,7 +200,7 @@
 		}
 	},
 	"dependencies": {
-		"cursedbelt-core": "^1.2.0",
+		"cursedbelt-core": "^2.0.0",
 		"cwip": "^4.1.0",
 		"jose": "^6.2.3"
 	},

package/src/server/activity/index.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/src/server/master-lock/accounts.spec.ts

@@ -0,0 +1,308 @@
+/**
+ * 🔴 **The accounts model — a master password IS a tenant.**
+ *
+ * The owner's words, and the whole specification:
+ *
+ * > *"If I login with a master password I only see the files I added or removed with that
+ * > login. If I login with my other password I have not made yet I only see the other ones
+ * > I add in that login. 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."*
+ *
+ * This file proves the half that lives in the lock. The half that lives in an app — every
+ * query scoped by the id this hands out — is that app's own gate to prove.
+ *
+ * The claim each `describe` carries is the thing that would be catastrophic to get wrong,
+ * and three of them are catastrophic in a way that is SILENT: a tenant that cannot be
+ * reached looks exactly like a tenant with nothing in it.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+} from "cursedbelt-core/master-lock";
+import { FIRST_ACCOUNT_ID, MasterLock, readRecord } from "./masterLock";
+import { createMemoryMasterLockStore } from "./store";
+
+/** `iter: 1` — the ROUND COUNT is pinned in `cursedbelt-core`'s `kdf.spec.ts`; 600k × N
+ *  argon2 verifies here would be minutes of gate for nothing this file is testing. */
+const KDF: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 1,
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+
+const FIRST = "the owner's vault master password";
+const SECOND = "password";
+
+let firstVerifier = "";
+let secondVerifier = "";
+/** The LEGACY record: one password, no accounts — the shape every `MASTER_LOCK_SEED` in
+ *  the fleet carries, and the shape every un-upgraded app already has in its database. */
+let legacyJson = "";
+
+beforeEach(async () => {
+	if (firstVerifier) return;
+	firstVerifier = await deriveMasterLockVerifier(FIRST, KDF);
+	secondVerifier = await deriveMasterLockVerifier(SECOND, KDF);
+	legacyJson = JSON.stringify({
+		kdf: KDF,
+		verifierHash: await Bun.password.hash(firstVerifier, { algorithm: "argon2id" }),
+		idleMs: 300_000,
+	});
+});
+
+const build = (stored?: string | null) => {
+	const store = createMemoryMasterLockStore(stored ?? null);
+	return { store, lock: new MasterLock({ store }) };
+};
+
+const req = (token: string): Request =>
+	new Request("http://app.test/", { headers: { cookie: `master_lock=${token}` } });
+
+/** Unlock and hand back a request that presents the resulting token. */
+async function open(lock: MasterLock, verifier: string) {
+	const result = await lock.unlock(verifier);
+	if (!result.ok) throw new Error("expected the unlock to succeed");
+	return { ...result, req: req(result.token) };
+}
+
+describe("🔴 claim 1 — the owner's existing password keeps opening everything he has", () => {
+	test("a legacy single-password record becomes acct-1, and that password still works", async () => {
+		// THE migration guarantee. `apps/collections` stamps its 279 existing rows with this
+		// id, so an id that moved — or a record that failed to parse and armed nothing —
+		// would orphan the entire library this migration exists to carry across.
+		const { lock } = build(legacyJson);
+		expect(lock.configured).toBe(true);
+		expect(lock.accounts.length).toBe(1);
+		expect(lock.accounts[0]?.id).toBe(FIRST_ACCOUNT_ID);
+
+		const opened = await open(lock, firstVerifier);
+		expect(opened.accountId).toBe(FIRST_ACCOUNT_ID);
+		// And nothing else was invented along the way.
+		expect(lock.idleMs).toBe(300_000);
+	});
+
+	test("the migration is a READ — it does not rewrite the row until something else does", async () => {
+		// A record that rewrote itself on boot would mean a rollback to the previous build
+		// could no longer read its own store. Nothing is persisted until a write happens for
+		// a reason of its own.
+		const { lock, store } = build(legacyJson);
+		expect(lock.configured).toBe(true);
+		expect(store.read()).toBe(legacyJson);
+
+		lock.setIdleMs(600_000);
+		const rewritten = readRecord(store.read());
+		expect(rewritten?.accounts[0]?.id).toBe(FIRST_ACCOUNT_ID);
+		expect(rewritten?.idleMs).toBe(600_000);
+	});
+});
+
+describe("🔴 claim 2 — a second password is a second tenant, and never the first one", () => {
+	test("adding one needs a live unlock AND the current password, re-typed", async () => {
+		const { lock } = build(legacyJson);
+
+		// No unlock at all.
+		expect(
+			await lock.addAccount(req("nope"), {
+				currentVerifier: firstVerifier,
+				verifier: secondVerifier,
+				label: "Account 2",
+			}),
+		).toEqual({ ok: false, reason: "locked" });
+
+		const opened = await open(lock, firstVerifier);
+
+		// Unlocked, but the current password not proved.
+		expect(
+			await lock.addAccount(opened.req, {
+				currentVerifier: "not it",
+				verifier: secondVerifier,
+				label: "Account 2",
+			}),
+		).toEqual({ ok: false, reason: "wrong" });
+		expect(lock.accounts.length).toBe(1);
+
+		const added = await lock.addAccount(opened.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+			hint: "the obvious one",
+		});
+		expect(added.ok && added.account.id).toBe("acct-2");
+	});
+
+	test("each password opens its OWN account, and a token never reads as the other", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+		const second = await open(lock, secondVerifier);
+
+		expect(first.accountId).toBe("acct-1");
+		expect(second.accountId).toBe("acct-2");
+		// The property everything else rests on: a token is bound to the account that minted
+		// it, so two browsers open at once are two tenants, not one ambient state.
+		expect(lock.accountFor(first.req)).toBe("acct-1");
+		expect(lock.accountFor(second.req)).toBe("acct-2");
+	});
+
+	test("creating a tenant does NOT enter it", async () => {
+		// Switching means typing that tenant's password. If creating one dropped you into
+		// it, the owner would add an account and watch his library apparently vanish.
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+		expect(lock.accountFor(first.req)).toBe("acct-1");
+	});
+
+	test("🔴 a password that already opens something is refused", async () => {
+		// Two accounts under one password would make `unlock` serve whichever the loop
+		// reached first — so the owner would type the password he has always typed and be
+		// handed an empty library, with his real one apparently gone.
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		expect(
+			await lock.addAccount(first.req, {
+				currentVerifier: firstVerifier,
+				verifier: firstVerifier,
+				label: "A clone",
+			}),
+		).toEqual({ ok: false, reason: "duplicate" });
+		expect(lock.accounts.length).toBe(1);
+	});
+});
+
+describe("🔴 claim 3 — changing a password never changes which content it opens", () => {
+	test("the account id survives a rotation, and the siblings survive it too", async () => {
+		// The owner: *"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."*
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+
+		const second = await open(lock, secondVerifier);
+		const picked = await deriveMasterLockVerifier("passwordIPicked", KDF);
+		expect(
+			await lock.change(second.req, { currentVerifier: secondVerifier, verifier: picked }),
+		).toEqual({ ok: true });
+
+		// The new password opens the SAME tenant…
+		const reopened = await open(lock, picked);
+		expect(reopened.accountId).toBe("acct-2");
+		// …the old one opens nothing…
+		expect((await lock.unlock(secondVerifier)).ok).toBe(false);
+		// …and account 1 is untouched, which is what a shared KDF salt is protecting.
+		const stillFirst = await open(lock, firstVerifier);
+		expect(stillFirst.accountId).toBe("acct-1");
+	});
+
+	test("a rotation cannot collide a password onto a sibling", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+		const second = await open(lock, secondVerifier);
+		expect(
+			await lock.change(second.req, {
+				currentVerifier: secondVerifier,
+				verifier: firstVerifier,
+			}),
+		).toEqual({ ok: false, reason: "invalid" });
+	});
+});
+
+describe("🔴 claim 4 — the hints are readable while locked, and nothing else is", () => {
+	test("a hint survives a rotation and can be rewritten without the password", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+			hint: "the obvious one",
+		});
+
+		expect(lock.hints()).toEqual([
+			{ label: "Account 1", hint: "" },
+			{ label: "Account 2", hint: "the obvious one" },
+		]);
+
+		const second = await open(lock, secondVerifier);
+		expect(lock.editAccount(second.req, { id: "acct-2", hint: "rhymes with lassword" })).toBe(true);
+		expect(lock.hints()[1]?.hint).toBe("rhymes with lassword");
+	});
+
+	test("🔴 one session cannot rewrite another tenant's label or hint", async () => {
+		// The hint is the one field designed to be read by somebody who is LOCKED OUT, so a
+		// session holding one password must not be able to rewrite the note that gets the
+		// other one back in.
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+			hint: "the obvious one",
+		});
+		expect(lock.editAccount(first.req, { id: "acct-2", hint: "overwritten" })).toBe(false);
+		expect(lock.hints()[1]?.hint).toBe("the obvious one");
+	});
+
+	test("a hint is trimmed and capped, so it cannot become a wall of text on the lock screen", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "  Account\n\n2  ",
+			hint: `${"x".repeat(400)}`,
+		});
+		expect(lock.accounts[1]?.label).toBe("Account 2");
+		expect(lock.accounts[1]?.hint.length).toBe(200);
+	});
+});
+
+describe("🔴 claim 5 — a malformed row costs one account, never the keyring", () => {
+	test("an unreadable account is dropped and the others still open", async () => {
+		// This record is the ONLY thing that says which password opens which library.
+		// Refusing the whole file over one bad row would take every tenant down with it.
+		const good = await Bun.password.hash(firstVerifier, { algorithm: "argon2id" });
+		const stored = JSON.stringify({
+			kdf: KDF,
+			idleMs: 300_000,
+			accounts: [
+				{ id: "acct-1", label: "Account 1", hint: "", verifierHash: good, createdAt: 1 },
+				{ id: "acct-2", label: "Broken", hint: "", verifierHash: "not-a-hash", createdAt: 2 },
+				// A duplicate id, and an id shaped like something that could reach SQL.
+				{ id: "acct-1", label: "Dupe", hint: "", verifierHash: good, createdAt: 3 },
+				{ id: "../escape", label: "Nope", hint: "", verifierHash: good, createdAt: 4 },
+			],
+		});
+		const { lock } = build(stored);
+		expect(lock.accounts.map((account) => account.id)).toEqual(["acct-1"]);
+		expect((await open(lock, firstVerifier)).accountId).toBe("acct-1");
+	});
+
+	test("an empty keyring is a legitimate state, not a parse failure", async () => {
+		const { lock } = build(JSON.stringify({ kdf: KDF, idleMs: 300_000, accounts: [] }));
+		expect(lock.configured).toBe(false);
+		expect(lock.awaitingEnrollment).toBe(true);
+		expect(lock.unlocked).toBe(false);
+	});
+});

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

@@ -150,10 +150,77 @@ describe("while locked", () => {
 			idleMs: 5 * 60_000,
 			remainingMs: 0,
 			retryAfterMs: 0,
+			// Locked, so there is no account to name.
+			accountId: null,
+			accountLabel: null,
 		});
 		expect(JSON.stringify(body)).not.toContain("argon2");
 	});
 
+	test("🔴 a rotation carrying a STALE kdf is refused, not silently honoured", async () => {
+		// The pre-accounts wire minted a fresh salt on every rotation. Every account now
+		// derives under one shared descriptor, so honouring that would store a verifier hash
+		// nothing can ever match — the owner sets a new password, the rotation logs him out,
+		// and neither the old nor the new one opens the app. `409 stale-client` is the one
+		// refusal here that is deliberately distinguishable from a wrong password.
+		const { guard } = build();
+		const cookie = await open(guard);
+		const stale = await guard.handle(
+			post(
+				MASTER_LOCK_PATHS.change,
+				{
+					currentVerifier: VERIFIER,
+					kdf: { v: 1, alg: "PBKDF2-SHA256", iter: 600_000, salt: "ZZZZZZZZZZZZZZZZZZZZZZ" },
+					verifier: "whatever-that-salt-produced",
+				},
+				cookie,
+			),
+		);
+		expect(stale?.status).toBe(409);
+		expect(await stale?.json()).toEqual({ error: "stale-client" });
+		// And the password that already worked still does.
+		expect((await guard.handle(post(MASTER_LOCK_PATHS.unlock, { verifier: VERIFIER })))?.status).toBe(200);
+	});
+
+	test("🔴 status never says how many accounts this app has", async () => {
+		// The lock screen must read identically whether the owner keeps one tenant or ten:
+		// the number of master passwords is itself a fact worth hiding, and `status` is
+		// served to anyone who got past the app's own sign-in, before they prove anything
+		// else. `hints` is the one surface that discloses it, behind a deliberate click.
+		const { lock, guard } = build();
+		const cookie = await open(guard);
+		const added = await guard.handle(
+			post(
+				MASTER_LOCK_PATHS.accounts,
+				{
+					currentVerifier: VERIFIER,
+					verifier: await deriveMasterLockVerifier("second tenant", KDF),
+					label: "Second",
+				},
+				cookie,
+			),
+		);
+		expect(added?.status).toBe(200);
+		expect(lock.accounts.length).toBe(2);
+
+		const res = await guard.handle(xhr(MASTER_LOCK_PATHS.status));
+		const body = (await res?.json()) as Record<string, unknown>;
+		expect(Object.keys(body).sort()).toEqual([
+			"accountId",
+			"accountLabel",
+			"configured",
+			"enrollable",
+			"idleMs",
+			"kdf",
+			"locked",
+			"remainingMs",
+			"retryAfterMs",
+		]);
+		const serialized = JSON.stringify(body);
+		expect(serialized).not.toContain("Second");
+		expect(serialized).not.toContain("acct-2");
+	});
+
 	test("an `allow` path is passed through — that is where a machine surface lives", async () => {
 		const { guard } = build((url) => url.pathname === "/healthz");
 		expect(await guard.handle(xhr("/healthz"))).toBeNull();
@@ -249,11 +316,12 @@ describe("while unlocked", () => {
 	test("rotation needs the current password and locks the site behind it", async () => {
 		const { guard } = build();
 		const cookie = await open(guard);
-		const nextKdf = newMasterLockKdfParams();
-		const nextVerifier = await deriveMasterLockVerifier("something else", nextKdf);
+		// 🔴 Derived under the app's OWN params, not a fresh set. Every account shares one
+		// descriptor, so a rotation that minted a new salt would invalidate the others.
+		const nextVerifier = await deriveMasterLockVerifier("something else", KDF);
 
 		const refused = await guard.handle(
-			post(MASTER_LOCK_PATHS.change, { currentVerifier: "no", kdf: nextKdf, verifier: nextVerifier }, cookie),
+			post(MASTER_LOCK_PATHS.change, { currentVerifier: "no", verifier: nextVerifier }, cookie),
 		);
 		expect(refused?.status).toBe(400);
 		expect(await refused?.json()).toEqual({ error: "wrong" });
@@ -261,7 +329,7 @@ describe("while unlocked", () => {
 		const done = await guard.handle(
 			post(
 				MASTER_LOCK_PATHS.change,
-				{ currentVerifier: VERIFIER, kdf: nextKdf, verifier: nextVerifier },
+				{ currentVerifier: VERIFIER, verifier: nextVerifier },
 				cookie,
 			),
 		);
@@ -272,12 +340,31 @@ describe("while unlocked", () => {
 });
 
 describe("an app with no master password configured", () => {
-	test("is served normally — an unopenable lock would brick it", async () => {
+	test("🔴 boots to NOTHING, and offers to take a first password", async () => {
+		// This INVERTS what it asserted until the accounts model. "Unconfigured means open"
+		// was right while the lock only decided whether a UI was visible — failing closed
+		// would have bricked an app nobody could type a password into. Both halves of that
+		// reasoning are gone: `enroll` means an unconfigured app offers to take one, and the
+		// password now decides WHOSE DATA the app serves, so "open with no password" has no
+		// tenant it could answer with. The owner ruled the same way: *"It would be booting
+		// to nothing until the password is created."*
 		const lock = new MasterLock({ store: createMemoryMasterLockStore(), seedJson: null });
 		const guard = createMasterLockGuard({ lock, appLabel: "Test App" });
-		expect(await guard.handle(doc("/"))).toBeNull();
+
+		const page = await guard.handle(doc("/"));
+		expect(page?.status).toBe(200);
+		expect(await page?.text()).toContain("master password");
+		// And no tenant is invented for a caller who has typed nothing.
+		expect(guard.accountFor(doc("/"))).toBeNull();
+
 		const status = await guard.handle(xhr(MASTER_LOCK_PATHS.status));
-		expect(await status?.json()).toMatchObject({ configured: false, locked: false, kdf: null });
+		expect(await status?.json()).toMatchObject({
+			configured: false,
+			locked: true,
+			enrollable: true,
+			kdf: null,
+			accountId: null,
+		});
 	});
 });