cursedbelt-core 1.2.0 → 2.0.0

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

@@ -10,5 +10,5 @@
  */
 export { MASTER_LOCK_KDF, type MasterLockKdfParams, b64u, deriveMasterLockVerifier, isMasterLockKdfParams, newMasterLockKdfParams, unb64u, } from "./kdf";
 export { BASE_DELAY_MS, DEFAULT_IDLE_MS, FREE_ATTEMPTS, MAX_DELAY_MS, MAX_IDLE_MS, MIN_IDLE_MS, clampIdleMs, delayAfter, windowRemaining, } from "./policy";
-export { MASTER_LOCK_COOKIE, masterLockCookieName, MASTER_LOCK_HEADER, MASTER_LOCK_PATHS, MASTER_LOCK_PREFIX, MASTER_LOCK_STATE_HEADER, type MasterLockChangeRequest, type MasterLockEnrollRequest, type MasterLockRefusal, type MasterLockSettingsRequest, type MasterLockStatus, type MasterLockUnlockRequest, } from "./wire";
+export { MASTER_LOCK_COOKIE, masterLockCookieName, MASTER_LOCK_HEADER, MASTER_LOCK_PATHS, MASTER_LOCK_PREFIX, MASTER_LOCK_STATE_HEADER, type MasterLockAccountSummary, type MasterLockAccountsResponse, type MasterLockAddAccountRequest, type MasterLockChangeRequest, type MasterLockEditAccountRequest, type MasterLockEnrollRequest, type MasterLockHintsResponse, type MasterLockRefusal, type MasterLockSettingsRequest, type MasterLockStatus, type MasterLockUnlockRequest, } from "./wire";
 export { PRESENCE_ATTRIBUTE, type PresenceMedia, isPresenceMedia, isSomebodyWatching, } from "./presence";

package/dist/core/master-lock/wire.d.ts

@@ -36,6 +36,30 @@ export declare const MASTER_LOCK_PATHS: {
      * current one.
      */
     readonly enroll: "/__lock/enroll";
+    /**
+     * The ACCOUNTS surface — `GET` lists them, `POST` adds one, `PATCH` renames one or
+     * rewrites its hint.
+     *
+     * 🔴 Reachable only with a live unlock, unlike everything above it. Listing the
+     * accounts says how many master passwords exist and what they are called, which is
+     * the one fact the lock page is built never to disclose (see {@link hints}).
+     */
+    readonly accounts: "/__lock/accounts";
+    /**
+     * The hints, and the ONE thing here that is readable while locked.
+     *
+     * The owner asked for it in as many words: *"let me setup hints for them … since the
+     * passwords are not recorded anywhere I will want a way to help me if I forget it."*
+     * A hint nobody can read until they are already in is not a hint.
+     *
+     * 🔴 It is a SEPARATE route rather than a field on {@link MasterLockStatus} precisely
+     * because it discloses what status must not: the number of accounts and their labels.
+     * The lock page fetches it only when the person clicks "I forgot", so the default
+     * page is byte-identical whether there is one account or ten, and revealing the list
+     * is a deliberate act rather than a side effect of loading a page. Everyone who can
+     * reach it has already passed the app's own owner-only sign-in.
+     */
+    readonly hints: "/__lock/hints";
 };
 /**
  * The base name of the cookie the unlock token rides in. Callers want
@@ -112,6 +136,71 @@ export interface MasterLockStatus {
     remainingMs: number;
     /** Milliseconds until another guess will be evaluated. `0` normally. */
     retryAfterMs: number;
+    /**
+     * WHICH account the caller's unlock belongs to, or `null` when locked.
+     *
+     * 🔴 This is the whole point of the accounts model and it is the only account fact
+     * status carries. The master password a person types decides which tenant's data the
+     * app serves them, so the app needs to know which one opened — but nothing here says
+     * how many OTHER accounts exist, because that would let a stolen session count the
+     * owner's tenants by loading a page. See {@link MASTER_LOCK_PATHS.hints}.
+     */
+    accountId: string | null;
+    /** The label of {@link accountId}, for a header chip. `null` when locked. */
+    accountLabel: string | null;
+}
+/**
+ * One account, as the management UI is allowed to see it.
+ *
+ * 🔴 Never the verifier hash and never anything derived from the password. The `hint` IS
+ * disclosed, because a hint the owner cannot read is not a hint — it is their own words,
+ * written by them, for the moment they have forgotten which password opens which tenant.
+ */
+export interface MasterLockAccountSummary {
+    id: string;
+    label: string;
+    /** The owner's own reminder. Empty string when they set none. */
+    hint: string;
+    createdAt: number;
+    /** Is this the account the caller's own unlock belongs to? */
+    current: boolean;
+}
+/** What `GET /__lock/accounts` answers — requires a live unlock. */
+export interface MasterLockAccountsResponse {
+    accounts: MasterLockAccountSummary[];
+}
+/**
+ * Adding an account: a SECOND master password, and therefore a second tenant.
+ *
+ * The current password is re-typed for the same reason {@link MasterLockChangeRequest}
+ * demands it — an open session proves somebody is at the keyboard, not that it is the
+ * owner, and minting a whole new tenant is at least as consequential as rotating one.
+ *
+ * 🔴 There is no `kdf`. Every account on an app derives under the SAME params, so one
+ * PBKDF2 pass in the browser can be measured against all of them and the lock page
+ * cannot be made to disclose how many exist by how many salts it has to publish. See
+ * the engine's note on the shared descriptor.
+ */
+export interface MasterLockAddAccountRequest {
+    /** Derived under the app's params — proof the caller knows the password they are in. */
+    currentVerifier: string;
+    /** The NEW account's verifier, derived under those same params. */
+    verifier: string;
+    label: string;
+    hint?: string;
+}
+/** Renaming an account or rewriting its hint. Never its password — that is `change`. */
+export interface MasterLockEditAccountRequest {
+    id: string;
+    label?: string;
+    hint?: string;
+}
+/** What `GET /__lock/hints` answers, readable WHILE LOCKED — see the path's note. */
+export interface MasterLockHintsResponse {
+    hints: {
+        label: string;
+        hint: string;
+    }[];
 }
 export interface MasterLockUnlockRequest {
     verifier: string;
@@ -122,11 +211,23 @@ export interface MasterLockEnrollRequest {
     verifier: string;
 }
 export interface MasterLockChangeRequest {
-    /** Derived under the CURRENT params — proof that the person changing it is the person
+    /** Derived under the app's params — proof that the person changing it is the person
      *  who knows it, re-typed rather than inherited from the open session. */
     currentVerifier: string;
-    /** The NEW params (a fresh salt) and the verifier derived under them. */
-    kdf: MasterLockKdfParams;
+    /**
+     * The new verifier, derived under those SAME params.
+     *
+     * 🔴 It used to carry a fresh `kdf`, and it may not any more. The params are now one
+     * app-wide descriptor that every account derives under, so minting a new salt here
+     * would silently invalidate every OTHER account's stored hash — the owner would
+     * change account 2's password and lock himself out of account 1. The cost is that the
+     * salt never rotates; it is 16 random bytes whose job is to stop precomputation
+     * across apps, and it does that for as long as it exists.
+     *
+     * Rotating a password never changes which tenant it opens. That is the owner's
+     * requirement, in his words: *"If I change account 2 password it just changes how I
+     * get the access … I would still access the same content afterward."*
+     */
     verifier: string;
 }
 export interface MasterLockSettingsRequest {

package/dist/core/master-lock/wire.js

@@ -29,6 +29,30 @@ export const MASTER_LOCK_PATHS = {
      * current one.
      */
     enroll: `${MASTER_LOCK_PREFIX}/enroll`,
+    /**
+     * The ACCOUNTS surface — `GET` lists them, `POST` adds one, `PATCH` renames one or
+     * rewrites its hint.
+     *
+     * 🔴 Reachable only with a live unlock, unlike everything above it. Listing the
+     * accounts says how many master passwords exist and what they are called, which is
+     * the one fact the lock page is built never to disclose (see {@link hints}).
+     */
+    accounts: `${MASTER_LOCK_PREFIX}/accounts`,
+    /**
+     * The hints, and the ONE thing here that is readable while locked.
+     *
+     * The owner asked for it in as many words: *"let me setup hints for them … since the
+     * passwords are not recorded anywhere I will want a way to help me if I forget it."*
+     * A hint nobody can read until they are already in is not a hint.
+     *
+     * 🔴 It is a SEPARATE route rather than a field on {@link MasterLockStatus} precisely
+     * because it discloses what status must not: the number of accounts and their labels.
+     * The lock page fetches it only when the person clicks "I forgot", so the default
+     * page is byte-identical whether there is one account or ten, and revealing the list
+     * is a deliberate act rather than a side effect of loading a page. Everyone who can
+     * reach it has already passed the app's own owner-only sign-in.
+     */
+    hints: `${MASTER_LOCK_PREFIX}/hints`,
 };
 /**
  * The base name of the cookie the unlock token rides in. Callers want

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "1.2.0",
+	"version": "2.0.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split \u2014 isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",

package/src/core/master-lock/index.ts

@@ -35,8 +35,13 @@ export {
 	MASTER_LOCK_PATHS,
 	MASTER_LOCK_PREFIX,
 	MASTER_LOCK_STATE_HEADER,
+	type MasterLockAccountSummary,
+	type MasterLockAccountsResponse,
+	type MasterLockAddAccountRequest,
 	type MasterLockChangeRequest,
+	type MasterLockEditAccountRequest,
 	type MasterLockEnrollRequest,
+	type MasterLockHintsResponse,
 	type MasterLockRefusal,
 	type MasterLockSettingsRequest,
 	type MasterLockStatus,

package/src/core/master-lock/wire.spec.ts

@@ -0,0 +1,33 @@
+/**
+ * The wire's own shape — the two properties a typo here would break silently.
+ *
+ * Every surface of this feature is a string constant in one object, and two of them
+ * arrived together (`accounts`, `hints`) with very different disclosure rules: one is
+ * reachable only with a live unlock, the other is readable while locked. A copy-paste that
+ * gave them the same string would route the management surface to the public one, and
+ * every unit test either side of the wire would stay green — the server would mount what
+ * it was told to mount and the browser would fetch what it was told to fetch.
+ */
+import { describe, expect, it } from "bun:test";
+import { MASTER_LOCK_PATHS, MASTER_LOCK_PREFIX } from "./wire";
+
+describe("MASTER_LOCK_PATHS", () => {
+	it("keeps every surface under the one prefix the guard reserves", () => {
+		for (const [name, path] of Object.entries(MASTER_LOCK_PATHS)) {
+			expect(`${name}:${path}`).toBe(`${name}:${path}`);
+			expect(path.startsWith(`${MASTER_LOCK_PREFIX}/`)).toBe(true);
+		}
+	});
+
+	it("gives every surface its own path", () => {
+		const paths = Object.values(MASTER_LOCK_PATHS);
+		expect(new Set(paths).size).toBe(paths.length);
+	});
+
+	it("keeps the locked-readable hints apart from the unlock-only accounts surface", () => {
+		// The one pair whose collision would be a disclosure rather than a 404.
+		expect(MASTER_LOCK_PATHS.hints).not.toBe(MASTER_LOCK_PATHS.accounts);
+		expect(MASTER_LOCK_PATHS.accounts.startsWith(MASTER_LOCK_PATHS.hints)).toBe(false);
+		expect(MASTER_LOCK_PATHS.hints.startsWith(MASTER_LOCK_PATHS.accounts)).toBe(false);
+	});
+});

package/src/core/master-lock/wire.ts

@@ -38,6 +38,30 @@ export const MASTER_LOCK_PATHS = {
 	 * current one.
 	 */
 	enroll: `${MASTER_LOCK_PREFIX}/enroll`,
+	/**
+	 * The ACCOUNTS surface — `GET` lists them, `POST` adds one, `PATCH` renames one or
+	 * rewrites its hint.
+	 *
+	 * 🔴 Reachable only with a live unlock, unlike everything above it. Listing the
+	 * accounts says how many master passwords exist and what they are called, which is
+	 * the one fact the lock page is built never to disclose (see {@link hints}).
+	 */
+	accounts: `${MASTER_LOCK_PREFIX}/accounts`,
+	/**
+	 * The hints, and the ONE thing here that is readable while locked.
+	 *
+	 * The owner asked for it in as many words: *"let me setup hints for them … since the
+	 * passwords are not recorded anywhere I will want a way to help me if I forget it."*
+	 * A hint nobody can read until they are already in is not a hint.
+	 *
+	 * 🔴 It is a SEPARATE route rather than a field on {@link MasterLockStatus} precisely
+	 * because it discloses what status must not: the number of accounts and their labels.
+	 * The lock page fetches it only when the person clicks "I forgot", so the default
+	 * page is byte-identical whether there is one account or ten, and revealing the list
+	 * is a deliberate act rather than a side effect of loading a page. Everyone who can
+	 * reach it has already passed the app's own owner-only sign-in.
+	 */
+	hints: `${MASTER_LOCK_PREFIX}/hints`,
 } as const;
 
 /**
@@ -123,6 +147,73 @@ export interface MasterLockStatus {
 	remainingMs: number;
 	/** Milliseconds until another guess will be evaluated. `0` normally. */
 	retryAfterMs: number;
+	/**
+	 * WHICH account the caller's unlock belongs to, or `null` when locked.
+	 *
+	 * 🔴 This is the whole point of the accounts model and it is the only account fact
+	 * status carries. The master password a person types decides which tenant's data the
+	 * app serves them, so the app needs to know which one opened — but nothing here says
+	 * how many OTHER accounts exist, because that would let a stolen session count the
+	 * owner's tenants by loading a page. See {@link MASTER_LOCK_PATHS.hints}.
+	 */
+	accountId: string | null;
+	/** The label of {@link accountId}, for a header chip. `null` when locked. */
+	accountLabel: string | null;
+}
+
+/**
+ * One account, as the management UI is allowed to see it.
+ *
+ * 🔴 Never the verifier hash and never anything derived from the password. The `hint` IS
+ * disclosed, because a hint the owner cannot read is not a hint — it is their own words,
+ * written by them, for the moment they have forgotten which password opens which tenant.
+ */
+export interface MasterLockAccountSummary {
+	id: string;
+	label: string;
+	/** The owner's own reminder. Empty string when they set none. */
+	hint: string;
+	createdAt: number;
+	/** Is this the account the caller's own unlock belongs to? */
+	current: boolean;
+}
+
+/** What `GET /__lock/accounts` answers — requires a live unlock. */
+export interface MasterLockAccountsResponse {
+	accounts: MasterLockAccountSummary[];
+}
+
+/**
+ * Adding an account: a SECOND master password, and therefore a second tenant.
+ *
+ * The current password is re-typed for the same reason {@link MasterLockChangeRequest}
+ * demands it — an open session proves somebody is at the keyboard, not that it is the
+ * owner, and minting a whole new tenant is at least as consequential as rotating one.
+ *
+ * 🔴 There is no `kdf`. Every account on an app derives under the SAME params, so one
+ * PBKDF2 pass in the browser can be measured against all of them and the lock page
+ * cannot be made to disclose how many exist by how many salts it has to publish. See
+ * the engine's note on the shared descriptor.
+ */
+export interface MasterLockAddAccountRequest {
+	/** Derived under the app's params — proof the caller knows the password they are in. */
+	currentVerifier: string;
+	/** The NEW account's verifier, derived under those same params. */
+	verifier: string;
+	label: string;
+	hint?: string;
+}
+
+/** Renaming an account or rewriting its hint. Never its password — that is `change`. */
+export interface MasterLockEditAccountRequest {
+	id: string;
+	label?: string;
+	hint?: string;
+}
+
+/** What `GET /__lock/hints` answers, readable WHILE LOCKED — see the path's note. */
+export interface MasterLockHintsResponse {
+	hints: { label: string; hint: string }[];
 }
 
 export interface MasterLockUnlockRequest {
@@ -136,11 +227,23 @@ export interface MasterLockEnrollRequest {
 }
 
 export interface MasterLockChangeRequest {
-	/** Derived under the CURRENT params — proof that the person changing it is the person
+	/** Derived under the app's params — proof that the person changing it is the person
 	 *  who knows it, re-typed rather than inherited from the open session. */
 	currentVerifier: string;
-	/** The NEW params (a fresh salt) and the verifier derived under them. */
-	kdf: MasterLockKdfParams;
+	/**
+	 * The new verifier, derived under those SAME params.
+	 *
+	 * 🔴 It used to carry a fresh `kdf`, and it may not any more. The params are now one
+	 * app-wide descriptor that every account derives under, so minting a new salt here
+	 * would silently invalidate every OTHER account's stored hash — the owner would
+	 * change account 2's password and lock himself out of account 1. The cost is that the
+	 * salt never rotates; it is 16 random bytes whose job is to stop precomputation
+	 * across apps, and it does that for as long as it exists.
+	 *
+	 * Rotating a password never changes which tenant it opens. That is the owner's
+	 * requirement, in his words: *"If I change account 2 password it just changes how I
+	 * get the access … I would still access the same content afterward."*
+	 */
 	verifier: string;
 }