cursedbelt-core 1.0.0

package/src/core/folder-tree/tree.ts

@@ -0,0 +1,244 @@
+/**
+ * The folder TREE model — pure, React-free, and the single source of truth for
+ * "given the folder paths the items carry, what is the tree, and what does a
+ * rename / move / delete DO to those paths".
+ *
+ * The consumer owns the items and their storage; this module never touches an item.
+ * A structural edit is expressed as a set of {@link FolderRemap}s — `from`→`to`
+ * serialized-path rewrites the consumer applies to every item whose folder matches
+ * `from`. That keeps the tree generic (it works the same for the vault's encrypted
+ * entries and for notes' groups) and keeps the dangerous part — rewriting stored
+ * items — a small, testable list of string swaps.
+ */
+
+import {
+	folderPathKey,
+	isFolderPathUnder,
+	normalizeFolderName,
+	parseFolderPath,
+	serializeFolderPath,
+} from "./path";
+
+/** A node in the derived tree. `path` is the full segment array from the root; a
+ *  `child` node's path is its parent's plus one segment. */
+export interface FolderNode {
+	/** The leaf name of this node (its last path segment). */
+	name: string;
+	/** Full path from the root, e.g. `["Home","Phones"]`. */
+	path: string[];
+	/** Serialized full path — the value an item at THIS folder stores. */
+	serialized: string;
+	/** Case-insensitive identity key for the full path. */
+	key: string;
+	/** Depth from the root (a root folder is 0). */
+	depth: number;
+	/** Child folders, sorted case-insensitively by name. */
+	children: FolderNode[];
+}
+
+/**
+ * Build the nested tree from a flat collection of serialized folder-path strings
+ * (one per item, duplicates fine). EVERY prefix becomes a node, so a tree with only
+ * `Home/Phones/Noah` still surfaces `Home` and `Home/Phones` as ancestors. Names
+ * dedupe case-insensitively, first spelling wins; siblings sort by name.
+ */
+export function buildFolderTree(serializedPaths: Iterable<string>): FolderNode[] {
+	interface Building {
+		name: string;
+		path: string[];
+		children: Map<string, Building>;
+	}
+	const roots = new Map<string, Building>();
+
+	for (const serialized of serializedPaths) {
+		const segments = parseFolderPath(serialized);
+		if (segments.length === 0) continue;
+		let level = roots;
+		const acc: string[] = [];
+		for (const seg of segments) {
+			acc.push(seg);
+			const k = normalizeFolderName(seg).toLowerCase();
+			let node = level.get(k);
+			if (!node) {
+				node = { name: seg, path: [...acc], children: new Map() };
+				level.set(k, node);
+			}
+			level = node.children;
+		}
+	}
+
+	const toNode = (b: Building, depth: number): FolderNode => ({
+		name: b.name,
+		path: b.path,
+		serialized: serializeFolderPath(b.path),
+		key: folderPathKey(b.path),
+		depth,
+		children: sortNodes([...b.children.values()].map((c) => toNode(c, depth + 1))),
+	});
+
+	return sortNodes([...roots.values()].map((b) => toNode(b, 0)));
+}
+
+/** The derived tree plus a CUMULATIVE per-folder count — how many of the supplied
+ *  paths sit at-or-under each folder. */
+export interface FolderIndex {
+	tree: FolderNode[];
+	/** Items at-or-under the folder with this serialized path. Unknown folder → 0. */
+	count: (serialized: string) => number;
+}
+
+/**
+ * {@link buildFolderTree} plus counts, in ONE pass over the paths.
+ *
+ * Counts are cumulative: an item in `Home/Phones/Noah` counts for `Home`,
+ * `Home/Phones` AND `Home/Phones/Noah`, so a collapsed parent still shows a
+ * meaningful total rather than the zero its own direct membership would report.
+ * That is the number a rail wants next to a folder, and every consumer wants the
+ * same one — it was written once in the vault and lifted here when notes needed
+ * it, rather than counted twice with two chances to disagree about whether a
+ * parent includes its children.
+ */
+export function buildFolderIndex(serializedPaths: Iterable<string>): FolderIndex {
+	const paths: string[] = [];
+	const counts = new Map<string, number>();
+	for (const serialized of serializedPaths) {
+		const segments = parseFolderPath(serialized);
+		if (segments.length === 0) continue;
+		paths.push(serializeFolderPath(segments));
+		for (let i = 1; i <= segments.length; i++) {
+			const key = folderPathKey(segments.slice(0, i));
+			counts.set(key, (counts.get(key) ?? 0) + 1);
+		}
+	}
+	return {
+		tree: buildFolderTree(paths),
+		count: (serialized) => counts.get(folderPathKey(parseFolderPath(serialized))) ?? 0,
+	};
+}
+
+function sortNodes(nodes: FolderNode[]): FolderNode[] {
+	return nodes.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+}
+
+/** Depth-first flatten (parent before children) — the order a picker lists options
+ *  and a rail renders rows. */
+export function flattenFolderTree(nodes: readonly FolderNode[]): FolderNode[] {
+	const out: FolderNode[] = [];
+	const walk = (list: readonly FolderNode[]) => {
+		for (const n of list) {
+			out.push(n);
+			walk(n.children);
+		}
+	};
+	walk(nodes);
+	return out;
+}
+
+/** A single stored-path rewrite. `to === ""` means the item drops to the root
+ *  (uncategorized). Consumers apply one to every item whose serialized folder path
+ *  equals `from`. */
+export interface FolderRemap {
+	from: string;
+	to: string;
+}
+
+/** The distinct set of serialized paths that actually appear on items (parents that
+ *  exist only as ancestors are not stored on any item, so they never need a remap).
+ *  Deduped by identity key. */
+function distinctStoredPaths(serializedPaths: Iterable<string>): string[][] {
+	const seen = new Map<string, string[]>();
+	for (const s of serializedPaths) {
+		const segs = parseFolderPath(s);
+		if (segs.length === 0) continue;
+		const k = folderPathKey(segs);
+		if (!seen.has(k)) seen.set(k, segs);
+	}
+	return [...seen.values()];
+}
+
+/** Rebuild a stored path by swapping its first `prefixLen` segments for `replacement`
+ *  (which may be empty, re-homing to the root). */
+function replacePrefix(path: string[], prefixLen: number, replacement: string[]): string[] {
+	return [...replacement, ...path.slice(prefixLen)];
+}
+
+/**
+ * Rename the folder at `target` to `newName`, keeping it under the same parent. Every
+ * item at `target` OR beneath it is remapped so descendants move with it. Returns the
+ * `from`→`to` rewrites the consumer applies; an empty list means nothing to change.
+ * Throws on an invalid/blank `newName`.
+ */
+export function planFolderRename(
+	serializedPaths: Iterable<string>,
+	target: readonly string[],
+	newName: string,
+): FolderRemap[] {
+	const name = normalizeFolderName(newName);
+	if (name.length === 0) throw new Error("a folder name cannot be blank");
+	if (target.length === 0) throw new Error("cannot rename the root");
+	const renamedPrefix = [...target.slice(0, -1), name];
+	return remapUnder(serializedPaths, target, renamedPrefix);
+}
+
+/**
+ * Move the folder at `source` under `newParent` (an empty array = the root),
+ * carrying its descendants. Refuses to move a folder into itself or a descendant
+ * (which would orphan the subtree), and to move a folder to where it already is.
+ * Returns the rewrites to apply.
+ */
+export function planFolderMove(
+	serializedPaths: Iterable<string>,
+	source: readonly string[],
+	newParent: readonly string[],
+): FolderRemap[] {
+	if (source.length === 0) throw new Error("cannot move the root");
+	if (isFolderPathUnder(newParent, source)) {
+		throw new Error("cannot move a folder into itself or one of its descendants");
+	}
+	const movedPrefix = [...newParent, source[source.length - 1] as string];
+	if (folderPathKey(movedPrefix) === folderPathKey(source)) return [];
+	return remapUnder(serializedPaths, source, movedPrefix);
+}
+
+/**
+ * Delete the folder at `target` by SPLICING it out: every item at or beneath it is
+ * re-homed to `target`'s parent, preserving the relative sub-structure. An item
+ * directly in `target` moves to the parent (or the root, if `target` was a root);
+ * an item in `target/child` moves to `parent/child`. Nothing is deleted from the
+ * consumer's store — items keep their secrets, they just lose one path segment.
+ */
+export function planFolderDelete(
+	serializedPaths: Iterable<string>,
+	target: readonly string[],
+): FolderRemap[] {
+	if (target.length === 0) throw new Error("cannot delete the root");
+	const parent = target.slice(0, -1);
+	const out: FolderRemap[] = [];
+	for (const path of distinctStoredPaths(serializedPaths)) {
+		if (!isFolderPathUnder(path, target)) continue;
+		// Drop the target segment: keep the parent, then everything below target.
+		const spliced = [...parent, ...path.slice(target.length)];
+		const from = serializeFolderPath(path);
+		const to = serializeFolderPath(spliced);
+		if (from !== to) out.push({ from, to });
+	}
+	return out;
+}
+
+/** Shared core for rename/move: replace the `target`-length prefix of every matching
+ *  stored path with `replacement`. */
+function remapUnder(
+	serializedPaths: Iterable<string>,
+	target: readonly string[],
+	replacement: string[],
+): FolderRemap[] {
+	const out: FolderRemap[] = [];
+	for (const path of distinctStoredPaths(serializedPaths)) {
+		if (!isFolderPathUnder(path, target)) continue;
+		const rebuilt = replacePrefix(path, target.length, replacement);
+		const from = serializeFolderPath(path);
+		const to = serializeFolderPath(rebuilt);
+		if (from !== to) out.push({ from, to });
+	}
+	return out;
+}

package/src/core/layout/index.ts

@@ -0,0 +1,7 @@
+// src/core/layout — re-export of `cwip/layout`, the single source of truth for the
+// framework-agnostic layout/widget engine core (v2 node model + idempotent migration,
+// pure treeOps, aggregates, container-query grid/style class maps, binding resolution,
+// undo/redo history, wire version). cursedbelt's copy was absorbed into cwip
+// (feat/layout-absorb) — add layout-engine core logic THERE, and the React
+// renderer/editor on top of it here (src/react/layoutEngine).
+export * from 'cwip/layout';

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

@@ -0,0 +1,50 @@
+/**
+ * `cursedbelt-core/master-lock` — the isomorphic half of the sitewide master-password lock.
+ *
+ * Derivation, policy numbers and the wire contract: everything both the browser and the
+ * server need to agree on, and nothing that needs either. The server engine is
+ * `cursedbelt-server/master-lock`; the in-app controls are `cursedbelt/react/master-lock`.
+ *
+ * What the whole feature is, and what it is NOT, is written once in the engine's module
+ * note — read that before changing anything here.
+ */
+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 {
+	PRESENCE_ATTRIBUTE,
+	type PresenceMedia,
+	isPresenceMedia,
+	isSomebodyWatching,
+} from "./presence";

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

@@ -0,0 +1,95 @@
+/**
+ * The derivation, pinned.
+ *
+ * 🔴 The first test is the load-bearing one, and it is not a tautology. `apps/vault`'s own
+ * `kdf.test.ts` asserts a FIXED (salt, password) → verifier vector; this asserts the SAME
+ * vector. That is what makes "seed an app from the vault's stored row and the owner's
+ * existing vault master password opens it" true — and it is the one property no integration
+ * test can check, because nobody involved knows the password.
+ *
+ * If this vector ever has to change, every app seeded from a vault record has to be
+ * re-seeded on the same day, and the owner has to be told before it lands.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	MASTER_LOCK_KDF,
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+	isMasterLockKdfParams,
+	newMasterLockKdfParams,
+} from ".";
+import { b64u, unb64u } from "./kdf";
+
+// The exact fixture `apps/vault/src/crypto/kdf.test.ts` derives against.
+const FIXED: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 600_000,
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+
+describe("deriveMasterLockVerifier", () => {
+	test("agrees with the vault on a fixed vector — this is what makes the seed work", async () => {
+		const verifier = await deriveMasterLockVerifier("correct horse battery staple", FIXED);
+		// The literal IS the pin — recomputing it here would only prove this file agrees
+		// with itself. It is `EXPECTED_VERIFIER` copied from
+		// `apps/vault/src/crypto/kdf.test.ts`, and both were re-derived side by side on
+		// 2026-08-15 to confirm the two implementations produce it.
+		expect(verifier).toBe("xnUVRdpRFD1tjzd7Il-Jd-YpvfVTGOs-6gAdsf2VfXc");
+	});
+
+	test("a different password under the same salt derives differently", async () => {
+		const a = await deriveMasterLockVerifier("one", FIXED);
+		const b = await deriveMasterLockVerifier("two", FIXED);
+		expect(a).not.toBe(b);
+	});
+
+	test("the same password under a different salt derives differently", async () => {
+		const a = await deriveMasterLockVerifier("same", FIXED);
+		const b = await deriveMasterLockVerifier("same", { ...FIXED, salt: "DwoNDAsKCQgHBgUEAwIB" });
+		expect(a).not.toBe(b);
+	});
+
+	test("refuses params it cannot derive under, rather than deriving something wrong", async () => {
+		await expect(
+			deriveMasterLockVerifier("x", { ...FIXED, alg: "scrypt" } as unknown as MasterLockKdfParams),
+		).rejects.toThrow(/unsupported/);
+	});
+});
+
+describe("newMasterLockKdfParams", () => {
+	test("carries today's pinned numbers and a fresh salt each time", () => {
+		const a = newMasterLockKdfParams();
+		const b = newMasterLockKdfParams();
+		expect(a.iter).toBe(MASTER_LOCK_KDF.iter);
+		expect(a.alg).toBe("PBKDF2-SHA256");
+		expect(unb64u(a.salt).length).toBe(MASTER_LOCK_KDF.saltBytes);
+		expect(a.salt).not.toBe(b.salt);
+	});
+});
+
+describe("isMasterLockKdfParams", () => {
+	test("accepts a real descriptor and rejects every near miss", () => {
+		expect(isMasterLockKdfParams(FIXED)).toBe(true);
+		expect(isMasterLockKdfParams(null)).toBe(false);
+		expect(isMasterLockKdfParams({ ...FIXED, v: 2 })).toBe(false);
+		expect(isMasterLockKdfParams({ ...FIXED, alg: "PBKDF2-SHA512" })).toBe(false);
+		expect(isMasterLockKdfParams({ ...FIXED, iter: 0 })).toBe(false);
+		expect(isMasterLockKdfParams({ ...FIXED, iter: 1.5 })).toBe(false);
+		expect(isMasterLockKdfParams({ ...FIXED, salt: "" })).toBe(false);
+		// A salt with base64 padding or a `+`/`/` is not base64URL — it would decode to
+		// different bytes on one side than the other, which is the silent version of this bug.
+		expect(isMasterLockKdfParams({ ...FIXED, salt: "AA+/" })).toBe(false);
+	});
+});
+
+describe("b64u", () => {
+	test("round-trips arbitrary bytes without padding", () => {
+		for (const length of [0, 1, 2, 3, 16, 31, 32]) {
+			const bytes = new Uint8Array(length).map((_, i) => (i * 37 + 11) % 256);
+			const text = b64u(bytes);
+			expect(text).not.toContain("=");
+			expect([...unb64u(text)]).toEqual([...bytes]);
+		}
+	});
+});

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

@@ -0,0 +1,145 @@
+/**
+ * The master-password derivation — deliberately BYTE-IDENTICAL to `apps/vault`'s.
+ *
+ * ── Why identical, and not merely similar ───────────────────────────────────
+ * The owner's instruction for this feature was *"set the master password to be the same
+ * as the vault master password for now … apply the verification like vault uses so I can
+ * type in the same master password I have on the vault and it works"*. Nobody — not the
+ * vault, not an agent, not this code — knows that password. The only way an app can accept
+ * it on day one is to be seeded with the vault's own KDF params and the vault's own stored
+ * `argon2id(verifier)`, and for that seed to mean anything the derivation has to agree to
+ * the byte. So this is a deliberate DUPLICATE of `apps/vault/src/crypto/kdf.ts`, pinned by
+ * `kdf.spec.ts` against the same fixed (salt, password) → verifier vector that file pins.
+ *
+ * It is not imported from the vault because the dependency would point the wrong way: a
+ * satellite app is a consumer of this package, and `cursedbelt` may never import one.
+ *
+ * ── The two outputs ────────────────────────────────────────────────────────
+ *   KEK      = PBKDF2-SHA256(password, salt, 600_000) → 256 bits
+ *   verifier = PBKDF2-SHA256(KEK ‖ password, salt, 1), base64url
+ *
+ * The extra round exists so the value the server sees is one step past the key. Here there
+ * IS no encryption key — this lock guards a UI, and the bytes behind it are plaintext at
+ * rest by nature (see the module note in `../../server/master-lock/masterLock.ts`). The KEK
+ * is computed only because dropping it would change the verifier and break the whole point
+ * of the paragraph above.
+ *
+ * The server stores `argon2id(verifier)`, never the verifier, and the password never leaves
+ * the browser.
+ */
+
+/** The pinned v1 parameters. Iterations may only ever be RAISED, and only by a change. */
+export const MASTER_LOCK_KDF = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 600_000,
+	saltBytes: 16,
+} as const;
+
+/** The versioned KDF descriptor. Every field is PUBLIC — it is served to the lock page
+ *  before anyone has proved anything, exactly as the vault serves it. */
+export interface MasterLockKdfParams {
+	readonly v: 1;
+	readonly alg: "PBKDF2-SHA256";
+	readonly iter: number;
+	/** base64url of the random salt. */
+	readonly salt: string;
+}
+
+const B64_ALPHABET = /^[0-9A-Za-z_-]+$/;
+
+/** Is this a KDF descriptor this build knows how to derive under? Used at the seam where
+ *  params arrive from a database, an env seed or the network — all three are outside this
+ *  module's control, and a silently-wrong `iter` derives a verifier that can never match. */
+export function isMasterLockKdfParams(value: unknown): value is MasterLockKdfParams {
+	if (value === null || typeof value !== "object") return false;
+	const p = value as Record<string, unknown>;
+	return (
+		p.v === 1 &&
+		p.alg === "PBKDF2-SHA256" &&
+		typeof p.iter === "number" &&
+		Number.isInteger(p.iter) &&
+		p.iter >= 1 &&
+		typeof p.salt === "string" &&
+		p.salt.length > 0 &&
+		B64_ALPHABET.test(p.salt)
+	);
+}
+
+/** Fresh params for a NEW master password: today's pinned numbers, a random salt. */
+export function newMasterLockKdfParams(): MasterLockKdfParams {
+	const salt = new Uint8Array(MASTER_LOCK_KDF.saltBytes);
+	crypto.getRandomValues(salt);
+	return { v: MASTER_LOCK_KDF.v, alg: MASTER_LOCK_KDF.alg, iter: MASTER_LOCK_KDF.iter, salt: b64u(salt) };
+}
+
+/**
+ * Derive the unlock verifier from a typed master password.
+ *
+ * Runs in the BROWSER (the lock page and the change-password dialog) and in `bun test`.
+ * `crypto.subtle` ships PBKDF2 natively in both, which is why it is PBKDF2 and not argon2 —
+ * the same reasoning the vault records at length.
+ */
+export async function deriveMasterLockVerifier(
+	masterPassword: string,
+	params: MasterLockKdfParams,
+): Promise<string> {
+	if (!isMasterLockKdfParams(params)) {
+		throw new Error(`unsupported master-lock KDF params: ${JSON.stringify(params)}`);
+	}
+	const salt = unb64u(params.salt);
+	const kek = await pbkdf2(utf8(masterPassword), salt, params.iter);
+	// Same salt as the KEK, by design: it individualises the verifier without a second
+	// stored value. One round, over KEK ‖ password.
+	const verifier = await pbkdf2(concat(kek, utf8(masterPassword)), salt, 1);
+	return b64u(verifier);
+}
+
+async function pbkdf2(material: Uint8Array, salt: Uint8Array, iterations: number): Promise<Uint8Array> {
+	const key = await crypto.subtle.importKey("raw", buf(material), "PBKDF2", false, ["deriveBits"]);
+	const bits = await crypto.subtle.deriveBits(
+		{ name: "PBKDF2", salt: buf(salt), iterations, hash: "SHA-256" },
+		key,
+		256,
+	);
+	return new Uint8Array(bits);
+}
+
+// ── bytes ───────────────────────────────────────────────────────────────────
+// Local rather than imported: this module is the one piece that must stay derivable with
+// nothing behind it, and `atob`/`btoa` exist in every runtime it runs in.
+
+/** A copy whose backing store is a plain `ArrayBuffer` — what `BufferSource` wants, and
+ *  what a `Uint8Array` over a `SharedArrayBuffer` is not. */
+function buf(bytes: Uint8Array): ArrayBuffer {
+	const out = new ArrayBuffer(bytes.byteLength);
+	new Uint8Array(out).set(bytes);
+	return out;
+}
+
+function utf8(text: string): Uint8Array {
+	return new TextEncoder().encode(text);
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+	const out = new Uint8Array(a.length + b.length);
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+}
+
+/** base64url, unpadded — the vault's `b64u`. */
+export function b64u(bytes: Uint8Array): string {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** The inverse of {@link b64u}. */
+export function unb64u(text: string): Uint8Array {
+	const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+	const out = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+	return out;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The numbers — how long an unlock survives being ignored, and how hard it is to guess at.
+ *
+ * Pure functions with no clock and no I/O of their own, so every edge of the schedule is a
+ * unit test rather than a wait. The engine in `../../server/master-lock/` supplies `now`.
+ */
+
+/** The owner's default: *"default to 5 minutes if I haven't configured it"*. */
+export const DEFAULT_IDLE_MS = 5 * 60_000;
+/** Short enough to be a real lock, long enough that typing a password is not the task. */
+export const MIN_IDLE_MS = 30_000;
+/** A day. Past this the timer is not what is protecting anything — the manual lock is. */
+export const MAX_IDLE_MS = 24 * 60 * 60_000;
+
+/** Clamp a submitted idle timeout into the usable band. A value that is not a finite
+ *  number at all falls back to the default rather than to a bound: a corrupt record must
+ *  not silently become "locks in 30 seconds" or "never locks". */
+export function clampIdleMs(value: unknown): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_IDLE_MS;
+	return Math.min(MAX_IDLE_MS, Math.max(MIN_IDLE_MS, Math.round(value)));
+}
+
+// ── The guess throttle ──────────────────────────────────────────────────────
+// The same schedule `apps/vault`'s unlock guard implements, and for the same reason: the
+// owner mistypes, an attacker iterates. Never a lockout — the owner locking themselves out
+// of their own laptop is a worse outcome than a slow attacker.
+
+/** Consecutive failures that cost nothing. */
+export const FREE_ATTEMPTS = 5;
+/** The first enforced wait once those are spent. Doubles thereafter. */
+export const BASE_DELAY_MS = 30_000;
+/** The ceiling on that wait. */
+export const MAX_DELAY_MS = 15 * 60_000;
+
+/**
+ * How long must pass after `failures` consecutive failures before another attempt is
+ * evaluated. `failures` includes the one that just happened.
+ *
+ *   ≤5 → 0 · 6 → 30s · 7 → 60s · 8 → 2m · … · ≥11 → 15m (capped)
+ */
+export function delayAfter(failures: number): number {
+	if (failures <= FREE_ATTEMPTS) return 0;
+	// Clamp the EXPONENT, not the product: a client that keeps hammering must not shift
+	// past a finite number into Infinity.
+	const exponent = Math.min(failures - FREE_ATTEMPTS - 1, 32);
+	return Math.min(BASE_DELAY_MS * 2 ** exponent, MAX_DELAY_MS);
+}
+
+/** Milliseconds still to wait, given the failure count, when the last one happened, and
+ *  now. `0` means "evaluate it". */
+export function windowRemaining(failures: number, lastFailureAt: number, now: number): number {
+	const delay = delayAfter(failures);
+	if (delay === 0) return 0;
+	return Math.max(0, lastFailureAt + delay - now);
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Watching a film is being present — and a decorative loop is not.
+ *
+ * Owner ask, 2026-08-25: *"apps that lock like collections with a master password should not
+ * lock when I am watching a video even if the timer runs out."*
+ *
+ * 🔴 The decorative-loop test is the security half. Presence that a muted autoplaying
+ * background clip could assert would hold a shared laptop unlocked all night with nobody in
+ * the room, which is the exact scenario the master lock exists for — a fix that opens the
+ * hole it was asked to close.
+ */
+import { describe, expect, test } from "bun:test";
+import { PRESENCE_ATTRIBUTE, type PresenceMedia, isPresenceMedia, isSomebodyWatching } from "./presence";
+
+const media = (over: Partial<PresenceMedia> & { presence?: string } = {}): PresenceMedia => ({
+	paused: false,
+	ended: false,
+	muted: false,
+	loop: false,
+	duration: 5_400,
+	getAttribute: (name: string) => (name === PRESENCE_ATTRIBUTE ? (over.presence ?? null) : null),
+	...over,
+});
+
+describe("isPresenceMedia", () => {
+	test("a film that is playing is somebody watching", () => {
+		expect(isPresenceMedia(media())).toBe(true);
+	});
+
+	test("paused or ended is not", () => {
+		expect(isPresenceMedia(media({ paused: true }))).toBe(false);
+		expect(isPresenceMedia(media({ ended: true }))).toBe(false);
+	});
+
+	test("🔴 a muted looping backdrop is NOT a person", () => {
+		expect(isPresenceMedia(media({ muted: true, loop: true }))).toBe(false);
+	});
+
+	test("muted alone, or looping alone, still counts — neither is the backdrop signature", () => {
+		expect(isPresenceMedia(media({ muted: true }))).toBe(true);
+		expect(isPresenceMedia(media({ loop: true }))).toBe(true);
+	});
+
+	test("a live stream (Infinity) counts; one with no duration yet does not", () => {
+		expect(isPresenceMedia(media({ duration: Number.POSITIVE_INFINITY }))).toBe(true);
+		expect(isPresenceMedia(media({ duration: 0 }))).toBe(false);
+		expect(isPresenceMedia(media({ duration: Number.NaN }))).toBe(false);
+	});
+
+	test("the attribute overrules the heuristic in both directions", () => {
+		// A backdrop that insists it is being watched still is.
+		expect(isPresenceMedia(media({ muted: true, loop: true, presence: "watch" }))).toBe(true);
+		// …and a real film that opts out is not, even mid-play.
+		expect(isPresenceMedia(media({ presence: "ignore" }))).toBe(false);
+	});
+
+	test("🔴 `ignore` beats `paused` too — an opted-out element is never evidence", () => {
+		expect(isPresenceMedia(media({ paused: true, presence: "ignore" }))).toBe(false);
+	});
+});
+
+describe("isSomebodyWatching", () => {
+	test("one playing element among many is enough", () => {
+		expect(
+			isSomebodyWatching([media({ paused: true }), media({ muted: true, loop: true }), media()]),
+		).toBe(true);
+	});
+
+	test("an empty page, or a page of stopped media, is an empty room", () => {
+		expect(isSomebodyWatching([])).toBe(false);
+		expect(isSomebodyWatching([media({ paused: true }), media({ ended: true })])).toBe(false);
+	});
+});