cursedbelt-core 1.0.0

package/dist/core/folder-tree/path.js

@@ -0,0 +1,146 @@
+/**
+ * Folder PATH encoding — the storage contract every consumer of the folder tree
+ * shares. A folder path is an ordered array of segment names (`["Home","Phones",
+ * "Noah"]`); on disk it is a single delimiter-joined STRING so it can ride in one
+ * field (an entry's `meta.folder`, a note's group tag) without a separate registry.
+ *
+ * ── Why a delimited string and not id references ─────────────────────────────
+ * The first consumer (the vault) is a zero-knowledge, op-log-synced store: a folder
+ * lives inside an entry's ENCRYPTED meta, and there is no server-side place to keep
+ * an id→name map that every device would have to converge on. Deriving the whole
+ * tree from the set of path strings on the items keeps folders a pure function of
+ * the items — nothing extra to sync, nothing to version-skew. The cost is that a
+ * folder exists only while it (or a descendant) holds an item; that is the same
+ * "derived, not declared" model the vault already used for flat folders, extended
+ * to nesting.
+ *
+ * ── The delimiter, and why it is ESCAPED rather than forbidden ───────────────
+ * `/` joins segments. A `/` is common enough inside a real folder name ("TV/Film",
+ * "and/or") that forbidding it would be a footgun, and — critically — a MIGRATION
+ * hazard: a legacy flat folder literally named "TV/Movies" must stay ONE folder,
+ * not silently split into two. So the delimiter is escaped, not banned: a literal
+ * `/` in a name becomes `\/` and a literal `\` becomes `\\`. Serialize→parse is a
+ * lossless round trip for any name that is non-empty and free of control chars.
+ */
+/** The character that joins path segments in the stored string. */
+export const FOLDER_PATH_DELIMITER = "/";
+/** The escape character. A literal delimiter or escape inside a name is prefixed. */
+export const FOLDER_PATH_ESCAPE = "\\";
+/** Trim a raw name for use as a segment. Internal whitespace is preserved; only the
+ *  ends are trimmed, so "  My Bank " and "My Bank" are the same folder. */
+export function normalizeFolderName(name) {
+    return name.trim();
+}
+/** A folder name is valid iff it is non-empty after trimming and carries no control
+ *  characters (which would corrupt the stored string and never render). The
+ *  delimiter and escape are ALLOWED — they are escaped on serialize. */
+export function isValidFolderName(name) {
+    const n = normalizeFolderName(name);
+    if (n.length === 0)
+        return false;
+    // Reject C0 control chars (0x00–0x1F) and DEL (0x7F): they never render and would
+    // corrupt the stored string. Checked by code point so no literal control byte
+    // (or the no-control-characters-in-regex lint) ever appears in this source.
+    for (const ch of n) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+/** Escape one segment: `\` → `\\`, then `/` → `\/`. Order matters — escape the
+ *  escape first so a name containing `\/` is not double-decoded. */
+function escapeSegment(seg) {
+    return seg
+        .replaceAll(FOLDER_PATH_ESCAPE, FOLDER_PATH_ESCAPE + FOLDER_PATH_ESCAPE)
+        .replaceAll(FOLDER_PATH_DELIMITER, FOLDER_PATH_ESCAPE + FOLDER_PATH_DELIMITER);
+}
+/**
+ * Serialize a path (array of segment names) into the stored string. Empty and
+ * whitespace-only segments are dropped, and each surviving segment is trimmed, so
+ * the output is canonical: `serialize(parse(s))` normalizes any spelling of `s`.
+ */
+export function serializeFolderPath(segments) {
+    return segments
+        .map(normalizeFolderName)
+        .filter((s) => s.length > 0)
+        .map(escapeSegment)
+        .join(FOLDER_PATH_DELIMITER);
+}
+/**
+ * Parse a stored string back into its segment array. Splits on UNESCAPED delimiters
+ * only, then unescapes each segment. Empty segments (a leading/trailing/double
+ * delimiter) are dropped rather than becoming blank folders.
+ */
+export function parseFolderPath(serialized) {
+    const out = [];
+    let seg = "";
+    let escaped = false;
+    for (const ch of serialized) {
+        if (escaped) {
+            seg += ch;
+            escaped = false;
+        }
+        else if (ch === FOLDER_PATH_ESCAPE) {
+            escaped = true;
+        }
+        else if (ch === FOLDER_PATH_DELIMITER) {
+            out.push(seg);
+            seg = "";
+        }
+        else {
+            seg += ch;
+        }
+    }
+    out.push(seg);
+    // A trailing lone escape (malformed input) is dropped with the empty tail.
+    return out.map(normalizeFolderName).filter((s) => s.length > 0);
+}
+/**
+ * A case-insensitive identity key for a path — the thing two paths compare equal by.
+ * Folder names dedupe case-insensitively (like the flat rail always did), so "Work"
+ * and "work" are one folder, but the key is still per-SEGMENT so "Home/Phones" and
+ * "Homework/hones" never collide (which a naive lowercased-string prefix would).
+ */
+export function folderPathKey(segments) {
+    return serializeFolderPath(segments.map((s) => normalizeFolderName(s).toLowerCase()));
+}
+/** True when `child` is `parent` or sits anywhere beneath it (segment-aligned, so
+ *  `Home` contains `Home/Phones` but NOT `Homework`). An empty `parent` (the root)
+ *  contains everything. */
+export function isFolderPathUnder(child, parent) {
+    if (parent.length === 0)
+        return true;
+    if (child.length < parent.length)
+        return false;
+    for (let i = 0; i < parent.length; i++) {
+        const c = normalizeFolderName(child[i] ?? "").toLowerCase();
+        const p = normalizeFolderName(parent[i] ?? "").toLowerCase();
+        if (c !== p)
+            return false;
+    }
+    return true;
+}
+/**
+ * The stored-string prefix EVERY descendant of `segments` starts with, and nothing
+ * else does — `serialize(segments) + "/"`. It exists so a store that keeps the
+ * serialized path in one column (a SQL `LIKE 'Home/%'`, a `startsWith` on a key/value
+ * store) can select a whole subtree without parsing every row.
+ *
+ * It is exact BECAUSE the delimiter is escaped: a folder literally named `TV/Film`
+ * serializes as `TV\/Film`, whose fifth character is the escape, so it can never be
+ * mistaken for `TV` + a child. `Homework` does not start with `Home/` either. The one
+ * thing the prefix does NOT cover is the folder itself — a caller wants
+ * `path = serialized OR path LIKE prefix || '%'`, which is what `isFolderPathUnder`
+ * says in memory. The root (an empty path) has no prefix that means "everything", so
+ * it returns `""` and the caller should skip the filter entirely.
+ */
+export function folderDescendantPrefix(segments) {
+    const serialized = serializeFolderPath(segments);
+    return serialized === "" ? "" : serialized + FOLDER_PATH_DELIMITER;
+}
+/** Render a path as a human breadcrumb: `Home › Phones › Noah`. The separator is a
+ *  display choice; the default is the one the picker and rail use. */
+export function formatFolderPath(segments, separator = " › ") {
+    return segments.map(normalizeFolderName).join(separator);
+}

package/dist/core/folder-tree/tree.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+/** 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 declare function buildFolderTree(serializedPaths: Iterable<string>): FolderNode[];
+/** 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 declare function buildFolderIndex(serializedPaths: Iterable<string>): FolderIndex;
+/** Depth-first flatten (parent before children) — the order a picker lists options
+ *  and a rail renders rows. */
+export declare function flattenFolderTree(nodes: readonly FolderNode[]): FolderNode[];
+/** 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;
+}
+/**
+ * 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 declare function planFolderRename(serializedPaths: Iterable<string>, target: readonly string[], newName: string): FolderRemap[];
+/**
+ * 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 declare function planFolderMove(serializedPaths: Iterable<string>, source: readonly string[], newParent: readonly string[]): FolderRemap[];
+/**
+ * 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 declare function planFolderDelete(serializedPaths: Iterable<string>, target: readonly string[]): FolderRemap[];

package/dist/core/folder-tree/tree.js

@@ -0,0 +1,184 @@
+/**
+ * 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";
+/**
+ * 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) {
+    const roots = new Map();
+    for (const serialized of serializedPaths) {
+        const segments = parseFolderPath(serialized);
+        if (segments.length === 0)
+            continue;
+        let level = roots;
+        const acc = [];
+        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, depth) => ({
+        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)));
+}
+/**
+ * {@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) {
+    const paths = [];
+    const counts = new Map();
+    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) {
+    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) {
+    const out = [];
+    const walk = (list) => {
+        for (const n of list) {
+            out.push(n);
+            walk(n.children);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+/** 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) {
+    const seen = new Map();
+    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, prefixLen, replacement) {
+    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, target, newName) {
+    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, source, newParent) {
+    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]];
+    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, target) {
+    if (target.length === 0)
+        throw new Error("cannot delete the root");
+    const parent = target.slice(0, -1);
+    const out = [];
+    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, target, replacement) {
+    const out = [];
+    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/dist/core/layout/index.d.ts

@@ -0,0 +1 @@
+export * from 'cwip/layout';

package/dist/core/layout/index.js

@@ -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/dist/core/master-lock/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `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/dist/core/master-lock/index.js

@@ -0,0 +1,14 @@
+/**
+ * `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, 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, } from "./wire";
+export { PRESENCE_ATTRIBUTE, isPresenceMedia, isSomebodyWatching, } from "./presence";

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

@@ -0,0 +1,63 @@
+/**
+ * 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 declare const MASTER_LOCK_KDF: {
+    readonly v: 1;
+    readonly alg: "PBKDF2-SHA256";
+    readonly iter: 600000;
+    readonly saltBytes: 16;
+};
+/** 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;
+}
+/** 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 declare function isMasterLockKdfParams(value: unknown): value is MasterLockKdfParams;
+/** Fresh params for a NEW master password: today's pinned numbers, a random salt. */
+export declare function newMasterLockKdfParams(): MasterLockKdfParams;
+/**
+ * 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 declare function deriveMasterLockVerifier(masterPassword: string, params: MasterLockKdfParams): Promise<string>;
+/** base64url, unpadded — the vault's `b64u`. */
+export declare function b64u(bytes: Uint8Array): string;
+/** The inverse of {@link b64u}. */
+export declare function unb64u(text: string): Uint8Array;

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

@@ -0,0 +1,117 @@
+/**
+ * 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,
+};
+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) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const p = value;
+    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() {
+    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, params) {
+    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, salt, iterations) {
+    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) {
+    const out = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(out).set(bytes);
+    return out;
+}
+function utf8(text) {
+    return new TextEncoder().encode(text);
+}
+function concat(a, b) {
+    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) {
+    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) {
+    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;
+}