cursedbelt-core 1.1.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.1.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.",
@@ -356,7 +356,7 @@
 	},
 	"dependencies": {
 		"@leeoniya/ufuzzy": "^1.0.19",
-		"cwip": "^3.0.2"
+		"cwip": "^4.1.0"
 	},
 	"peerDependencies": {
 		"zod": "^4.4.0"

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;
 }
 

package/src/leafSubpathsImportNothing.spec.ts

@@ -152,8 +152,10 @@ const sourceOf = (subpath: string): string => {
  * Resolution here is therefore explicit rather than inherited. The redirected root is
  * used when it lies outside the repo (the normal case — the runner always sets
  * `$FORGE_STATE`, and the preload's sweep then cleans up after a killed run). When it
- * does not, this hops to `$HOME`, which `resolveTestTmpRoot` refuses for the general
- * default and which this check genuinely requires: an isolated root is the whole
+ * does not, this hops to `$FORGE_STATE/test-scratch.noindex` — or, with no generation
+ * in the environment, `~/.code/test-scratch.noindex`, which is where this machine keeps
+ * everything it builds for itself. `resolveTestTmpRoot` refuses `$HOME` for the general
+ * default and this check genuinely requires an isolated root: that isolation is the whole
  * measurement. Stale siblings are swept by mtime, the same way the preload does it,
  * so the hop cannot accumulate.
  */
@@ -171,7 +173,17 @@ const fixtureRoot = (): string => {
         'a check that cannot isolate itself is not a passing check',
     );
   }
-  const outside = `${home}/.${pkg.name}-leaf-fixture.noindex`;
+  // 🔴 Under `$FORGE_STATE`, or under `~/.code` — never a dotted directory of its own in
+  // `$HOME`. Measured 2026-09-17: this hop had left three `~/.cursedbelt*-leaf-fixture.noindex`
+  // trees in the owner's home directory, indistinguishable at a glance from the forty a Mac's
+  // real software puts there, and the sweep below only ever cleaned their INSIDES. A check that
+  // tidies up after itself and still leaves its address behind for ever is the shape this
+  // generation's home-dir rule exists to stop; `tools/check-home-dir.ts` now fails on it.
+  const state = process.env.FORGE_STATE?.trim();
+  const outside =
+    state !== undefined && state !== '' && !`${state}/`.startsWith(REPO_PREFIX)
+      ? `${state}/test-scratch.noindex/${pkg.name}-leaf-fixture`
+      : `${home}/.code/test-scratch.noindex/${pkg.name}-leaf-fixture`;
   try {
     const cutoff = Date.now() - 6 * 60 * 60 * 1000;
     for (const entry of readdirSync(outside)) {

package/src/shippedFilesAreTracked.spec.ts

@@ -0,0 +1,69 @@
+/**
+ * 🔴 `bun publish` packs the WORKING DIRECTORY, not the git index — so a package can
+ * ship a file the repo does not have.
+ *
+ * ── What this cost, 2026-09-15 ─────────────────────────────────────────────────────
+ * The cursedbelt split (task 148) moved two integration specs into this package from
+ * `cursedbelt`. `git add -u .` stages only files git already knows about, so both were
+ * committed nowhere — and `bun run verify` was green *because they were present on disk*,
+ * which is the same reason nobody noticed. `1.0.2` went to the registry carrying two
+ * `src/` files that existed in no commit, and `git status` said `tracked-dirty=0`.
+ *
+ * "The tree is clean" and "everything that ships is committed" are different claims, and
+ * only the first one is what people actually check. npm versions are immutable, so the
+ * window to notice closes at publish time.
+ *
+ * ── Why this shape ─────────────────────────────────────────────────────────────────
+ * It asks git, for exactly the directories `package.json#files` promises to ship, which
+ * of those paths git does not track. That is narrower than "any untracked file" on
+ * purpose: scratch files, `.agent.noindex/`, a half-written script and an uncommitted
+ * lockfile are all legitimate states for a working tree and reddening on them would teach
+ * people to skip this. A file INSIDE the published surface is the only case where
+ * untracked means "about to ship something no one can review or revert".
+ *
+ * 🔴 It must run from a real checkout to mean anything, so it refuses rather than passes
+ * when `git` cannot answer — a check that silently degrades to green is worse than none.
+ */
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+
+/** The directories `files` promises to ship, minus build output nobody commits. */
+const shippedDirs = (): string[] =>
+	((pkg as { files?: string[] }).files ?? []).filter((f) => f !== 'dist' && existsSync(`${repoRoot}/${f}`));
+
+const git = (...args: string[]): { ok: boolean; out: string } => {
+	const r = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });
+	return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
+};
+
+describe('every file inside the published surface is tracked', () => {
+	test('git can answer at all — a degraded check must refuse, not pass', () => {
+		expect(git('rev-parse', '--is-inside-work-tree').ok, 'not a git checkout, so this check proves nothing').toBe(true);
+	});
+
+	test('package.json names a shippable directory to scan', () => {
+		// Vacuity guard: an empty `files`, or one naming only `dist`, makes the assertion
+		// below pass while scanning nothing at all.
+		expect(shippedDirs().length, '`files` names no committed directory — nothing would be scanned').toBeGreaterThan(0);
+	});
+
+	test('no untracked file sits inside a directory `files` ships', () => {
+		// --others = untracked; --exclude-standard honours .gitignore, so deliberately
+		// ignored paths (.agent.noindex, node_modules) are not offences.
+		const { ok, out } = git('ls-files', '--others', '--exclude-standard', '--', ...shippedDirs());
+		expect(ok, 'git ls-files failed').toBe(true);
+		const untracked = out === '' ? [] : out.split('\n');
+		expect(
+			untracked,
+			'these would be PUBLISHED but exist in no commit — `bun publish` packs the working directory, not the index,\n' +
+				'so the registry would carry code nobody can review, diff or revert, and npm versions are immutable.\n' +
+				'Commit them (or add them to .gitignore if they genuinely must not ship):\n  ' +
+				untracked.join('\n  '),
+		).toEqual([]);
+	});
+});