cursedbelt-core 1.2.0 → 2.1.0

package/dist/core/duplicates/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * "Are these two files the same thing?" — the fleet's ONE answer, with no I/O in it.
+ *
+ * ── Why this is here and not in an app ──────────────────────────────────────────────────
+ * `binary-server` wrote these rules first (2026-08-13, the owner: *"make strategy to always
+ * check for duplicate binaries in same app for same user … mark likely the duplicates for
+ * users to confirm"*), and they were measured against a real store: the copy-counter cap, the
+ * camera-generic stem list and the 5% size window each exist because a wider rule proposed
+ * thousands of pairs nobody could ever review. `music` then needed the same question asked of
+ * a 5,400-track library — *"I want to see a duplicate next to the file that it is a possible
+ * duplicate of … The 'binary-server' app (bs) already has this feature for checking duplicate
+ * files. We can reuse it and enhance the customizability if needed so the main strategy is
+ * shared."*
+ *
+ * So the strategy lives once, here, and both consume it. What each app keeps for itself is the
+ * evidence only it has: bs's perceptual frame hashes, music's artist/title key.
+ *
+ * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
+ * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
+ * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * store, and so a browser bundle may import it (music renders the pair side by side).
+ */
+/**
+ * How far two sizes may differ and still be called the same thing.
+ *
+ * A re-encode at a different quality is the case this exists for, and those land within a few
+ * percent. Zero would make a name match a strict subset of "same name AND same size", which
+ * misses precisely the files worth asking about; much larger starts pairing a clip with its
+ * own trailer.
+ */
+export declare const SIZE_TOLERANCE = 0.05;
+/**
+ * How far two playing times may differ and still be the same recording.
+ *
+ * Wide enough for a re-encode (a trim of a trailing black frame, a container that rounds), far
+ * too narrow for the owner's 2026-08-14 report of a 3:56 video paired with a 1:52 one.
+ */
+export declare const DURATION_TOLERANCE = 0.05;
+/**
+ * The name to compare, reduced to what a human means by "the same file".
+ *
+ * Strips the directory, the extension, and the marks a copy picks up along the way —
+ * `Finder`'s ` copy`/` copy 2`, a browser's ` (1)`, a script's `_1`/`-1` — then collapses
+ * everything that is not a letter or a digit. `My Video (1).mp4`, `my_video.MP4` and
+ * `My-Video copy 2.mov` all reduce to `myvideo`.
+ *
+ * 🔴 The extension is stripped ON PURPOSE, so a re-encode (`.mov` → `.mp4`, `.wma` → `.mp3`)
+ * still pairs with its source. That is the single most common likely-duplicate in this fleet's
+ * stores and a rule that kept the extension would never see one.
+ *
+ * 🔴 **The copy-counter strip is capped at two digits**, and that cap is a measured bug fix
+ * (bs, 2026-08-14). It used to be `[-_]\d+$`, which eats a CAMERA SEQUENCE as readily as a copy
+ * marker: `IMG_4595` and `IMG_4646` both reduced to `img`, so every iPhone capture in a tenant
+ * shared one bucket and paired with every other one whose size was within 5%. `_1`…`_99` is
+ * what a copy marker actually looks like; four digits is a photo's identity, and it must
+ * survive.
+ */
+export declare function normalizeName(name: string | null | undefined): string;
+/**
+ * Stems that name a CAMERA, not a file.
+ *
+ * `IMG`, `DSC`, `PXL`, `VID` are what a device calls everything it produces; two files whose
+ * names reduce to one of these have told us nothing except that they came from a phone. Even
+ * with the counter cap above, `IMG_1.MOV` still reduces to `img`, and a bucket called "img" is
+ * every photo the owner has ever taken.
+ *
+ * 🔴 This rejects a MATCH, never a file. Both copies stay wherever they are, and an
+ * identical-bytes pair is unaffected — a checksum match never consults the name.
+ */
+export declare const GENERIC_STEMS: ReadonlySet<string>;
+/**
+ * A name that could belong to any file from that device tells us nothing about identity.
+ *
+ * 🔴 The trailing digit run is stripped BEFORE the lookup, and only here — never in
+ * {@link normalizeName}, where removing it is what made every camera capture one bucket. The
+ * two are asked at different moments: `normalizeName` decides whether two names are the SAME
+ * (so `img4595` and `img4646` must stay apart), and this decides whether a name that already
+ * matched is worth anything (so two files both called `Track01` have told us nothing, and a
+ * ripper names half a library that).
+ */
+export declare const isGenericName: (normalized: string) => boolean;
+/** Within {@link SIZE_TOLERANCE} of each other. Two zero-byte files are not "close" — they
+ *  are two files nothing is known about. */
+export declare function sizesClose(a: number, b: number, tolerance?: number): boolean;
+/**
+ * Within {@link DURATION_TOLERANCE} of each other.
+ *
+ * 🔴 A missing or zero duration answers `null`, never `false`: "nobody has measured this yet"
+ * and "these are different lengths" are opposite answers, and collapsing them makes an
+ * unprobed library look like a library with no duplicates in it.
+ */
+export declare function durationsClose(a: number | null | undefined, b: number | null | undefined, tolerance?: number): boolean | null;
+/** One file, reduced to what this module can reason about. Units are the caller's — pass
+ *  both durations in the same unit or not at all. */
+export interface NamedFileFacts {
+    /** The name a person would recognise: a display title, else the last path segment. */
+    name: string | null | undefined;
+    sizeBytes: number;
+    /** Playing time, in whatever unit the caller uses consistently. Null = never measured. */
+    duration?: number | null;
+}
+export interface NameMatchVerdict {
+    match: boolean;
+    /** Written for the owner reading a review queue, never for a log. Empty when `match` is
+     *  false — a non-match has nothing to explain. */
+    reason: string;
+}
+/**
+ * The shared "these look like the same thing" test: the NAME agrees after normalization, the
+ * sizes are close, and nothing about the length says otherwise.
+ *
+ * It is deliberately a QUESTION and never an action. Both consumers act only on a checksum,
+ * which is proof; this decides what is worth showing a person side by side.
+ */
+export declare function likelyTheSameFile(a: NamedFileFacts, b: NamedFileFacts): NameMatchVerdict;

package/dist/core/duplicates/index.js

@@ -0,0 +1,177 @@
+/**
+ * "Are these two files the same thing?" — the fleet's ONE answer, with no I/O in it.
+ *
+ * ── Why this is here and not in an app ──────────────────────────────────────────────────
+ * `binary-server` wrote these rules first (2026-08-13, the owner: *"make strategy to always
+ * check for duplicate binaries in same app for same user … mark likely the duplicates for
+ * users to confirm"*), and they were measured against a real store: the copy-counter cap, the
+ * camera-generic stem list and the 5% size window each exist because a wider rule proposed
+ * thousands of pairs nobody could ever review. `music` then needed the same question asked of
+ * a 5,400-track library — *"I want to see a duplicate next to the file that it is a possible
+ * duplicate of … The 'binary-server' app (bs) already has this feature for checking duplicate
+ * files. We can reuse it and enhance the customizability if needed so the main strategy is
+ * shared."*
+ *
+ * So the strategy lives once, here, and both consume it. What each app keeps for itself is the
+ * evidence only it has: bs's perceptual frame hashes, music's artist/title key.
+ *
+ * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
+ * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
+ * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * store, and so a browser bundle may import it (music renders the pair side by side).
+ */
+/**
+ * How far two sizes may differ and still be called the same thing.
+ *
+ * A re-encode at a different quality is the case this exists for, and those land within a few
+ * percent. Zero would make a name match a strict subset of "same name AND same size", which
+ * misses precisely the files worth asking about; much larger starts pairing a clip with its
+ * own trailer.
+ */
+export const SIZE_TOLERANCE = 0.05;
+/**
+ * How far two playing times may differ and still be the same recording.
+ *
+ * Wide enough for a re-encode (a trim of a trailing black frame, a container that rounds), far
+ * too narrow for the owner's 2026-08-14 report of a 3:56 video paired with a 1:52 one.
+ */
+export const DURATION_TOLERANCE = 0.05;
+/**
+ * The name to compare, reduced to what a human means by "the same file".
+ *
+ * Strips the directory, the extension, and the marks a copy picks up along the way —
+ * `Finder`'s ` copy`/` copy 2`, a browser's ` (1)`, a script's `_1`/`-1` — then collapses
+ * everything that is not a letter or a digit. `My Video (1).mp4`, `my_video.MP4` and
+ * `My-Video copy 2.mov` all reduce to `myvideo`.
+ *
+ * 🔴 The extension is stripped ON PURPOSE, so a re-encode (`.mov` → `.mp4`, `.wma` → `.mp3`)
+ * still pairs with its source. That is the single most common likely-duplicate in this fleet's
+ * stores and a rule that kept the extension would never see one.
+ *
+ * 🔴 **The copy-counter strip is capped at two digits**, and that cap is a measured bug fix
+ * (bs, 2026-08-14). It used to be `[-_]\d+$`, which eats a CAMERA SEQUENCE as readily as a copy
+ * marker: `IMG_4595` and `IMG_4646` both reduced to `img`, so every iPhone capture in a tenant
+ * shared one bucket and paired with every other one whose size was within 5%. `_1`…`_99` is
+ * what a copy marker actually looks like; four digits is a photo's identity, and it must
+ * survive.
+ */
+export function normalizeName(name) {
+    if (!name)
+        return "";
+    const leaf = name.split(/[\\/]/).pop() ?? "";
+    const stem = leaf.replace(/\.[a-z0-9]{1,5}$/i, "");
+    return stem
+        .toLowerCase()
+        .replace(/\s*\(\d+\)\s*$/, "")
+        .replace(/\s+copy(\s+\d+)?\s*$/, "")
+        .replace(/[-_]\d{1,2}\s*$/, "")
+        .replace(/[^a-z0-9]+/g, "");
+}
+/**
+ * Stems that name a CAMERA, not a file.
+ *
+ * `IMG`, `DSC`, `PXL`, `VID` are what a device calls everything it produces; two files whose
+ * names reduce to one of these have told us nothing except that they came from a phone. Even
+ * with the counter cap above, `IMG_1.MOV` still reduces to `img`, and a bucket called "img" is
+ * every photo the owner has ever taken.
+ *
+ * 🔴 This rejects a MATCH, never a file. Both copies stay wherever they are, and an
+ * identical-bytes pair is unaffected — a checksum match never consults the name.
+ */
+export const GENERIC_STEMS = new Set([
+    "img",
+    "image",
+    "images",
+    "dsc",
+    "dscf",
+    "dscn",
+    "pxl",
+    "vid",
+    "video",
+    "movie",
+    "mov",
+    "photo",
+    "pic",
+    "picture",
+    "screenshot",
+    "screenrecording",
+    "untitled",
+    "unknown",
+    "file",
+    "download",
+    "scan",
+    "capture",
+    "copy",
+    "new",
+    "temp",
+    "tmp",
+    // Music's own version of the same problem: an untagged rip is called this by every ripper
+    // ever written, and `track01` from two albums is two different songs.
+    "track",
+    "audiotrack",
+    "unknownartist",
+]);
+/**
+ * A name that could belong to any file from that device tells us nothing about identity.
+ *
+ * 🔴 The trailing digit run is stripped BEFORE the lookup, and only here — never in
+ * {@link normalizeName}, where removing it is what made every camera capture one bucket. The
+ * two are asked at different moments: `normalizeName` decides whether two names are the SAME
+ * (so `img4595` and `img4646` must stay apart), and this decides whether a name that already
+ * matched is worth anything (so two files both called `Track01` have told us nothing, and a
+ * ripper names half a library that).
+ */
+export const isGenericName = (normalized) => normalized.length < 3 ||
+    GENERIC_STEMS.has(normalized) ||
+    GENERIC_STEMS.has(normalized.replace(/\d+$/, ""));
+/** Within {@link SIZE_TOLERANCE} of each other. Two zero-byte files are not "close" — they
+ *  are two files nothing is known about. */
+export function sizesClose(a, b, tolerance = SIZE_TOLERANCE) {
+    if (a === b && a > 0)
+        return true;
+    const larger = Math.max(a, b);
+    if (larger <= 0)
+        return false;
+    return Math.abs(a - b) / larger <= tolerance;
+}
+/**
+ * Within {@link DURATION_TOLERANCE} of each other.
+ *
+ * 🔴 A missing or zero duration answers `null`, never `false`: "nobody has measured this yet"
+ * and "these are different lengths" are opposite answers, and collapsing them makes an
+ * unprobed library look like a library with no duplicates in it.
+ */
+export function durationsClose(a, b, tolerance = DURATION_TOLERANCE) {
+    if (!a || !b || a <= 0 || b <= 0)
+        return null;
+    return Math.abs(a - b) / Math.max(a, b) <= tolerance;
+}
+/**
+ * The shared "these look like the same thing" test: the NAME agrees after normalization, the
+ * sizes are close, and nothing about the length says otherwise.
+ *
+ * It is deliberately a QUESTION and never an action. Both consumers act only on a checksum,
+ * which is proof; this decides what is worth showing a person side by side.
+ */
+export function likelyTheSameFile(a, b) {
+    const na = normalizeName(a.name);
+    const nb = normalizeName(b.name);
+    // Two empty names are not a match with each other — it means neither file has a name worth
+    // comparing (a bare digest key, an untitled upload), and pairing those proposes every
+    // unnamed object as a duplicate of every other.
+    if (!na || na !== nb)
+        return { match: false, reason: "" };
+    if (isGenericName(na))
+        return { match: false, reason: "" };
+    if (!sizesClose(a.sizeBytes, b.sizeBytes))
+        return { match: false, reason: "" };
+    if (durationsClose(a.duration, b.duration) === false)
+        return { match: false, reason: "" };
+    const pct = Math.round((Math.abs(a.sizeBytes - b.sizeBytes) / Math.max(a.sizeBytes, b.sizeBytes, 1)) * 100);
+    return {
+        match: true,
+        reason: a.sizeBytes === b.sizeBytes
+            ? "same name, same size, different bytes"
+            : `same name, size within ${pct}%, different bytes`,
+    };
+}

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,9 +1,9 @@
 {
 	"name": "cursedbelt-core",
-	"version": "1.2.0",
+	"version": "2.1.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.",
+	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
 	"cursed": {
 		"schemaVersion": 1,
 		"app": {
@@ -20,7 +20,7 @@
 		"typecheck": "tsc -p tsconfig.build.json --noEmit",
 		"test": "NODE_ENV=development bun test src",
 		"build": "bun run clean && tsc -p tsconfig.build.json",
-		"paths": "bun ../../tools/check-paths.ts .",
+		"paths": "bun run scripts/paths.ts",
 		"verify": "bun run paths && bun run typecheck && bun run build && bun run test",
 		"prepublishOnly": "bun run verify"
 	},
@@ -125,6 +125,12 @@
 			"source": "./src/core/download.ts",
 			"import": "./dist/core/download.js"
 		},
+		"./duplicates": {
+			"types": "./dist/core/duplicates/index.d.ts",
+			"bun": "./src/core/duplicates/index.ts",
+			"source": "./src/core/duplicates/index.ts",
+			"import": "./dist/core/duplicates/index.js"
+		},
 		"./errors": {
 			"types": "./dist/shared/errors.d.ts",
 			"bun": "./src/shared/errors.ts",

package/src/core/duplicates/index.spec.ts

@@ -0,0 +1,116 @@
+/**
+ * The shared duplicate rules, proved against the cases that produced them.
+ *
+ * Every assertion here is a measured incident from `binary-server` or `music`, not an
+ * invented example — see the module header for which.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+	DURATION_TOLERANCE,
+	durationsClose,
+	isGenericName,
+	likelyTheSameFile,
+	normalizeName,
+	SIZE_TOLERANCE,
+	sizesClose,
+} from "./index";
+
+describe("normalizeName", () => {
+	it("reduces the marks a copy picks up to the same stem", () => {
+		expect(normalizeName("My Video (1).mp4")).toBe("myvideo");
+		expect(normalizeName("my_video.MP4")).toBe("myvideo");
+		expect(normalizeName("My-Video copy 2.mov")).toBe("myvideo");
+	});
+
+	it("strips the extension, so a re-encode still pairs with its source", () => {
+		expect(normalizeName("Song.wma")).toBe(normalizeName("Song.mp3"));
+	});
+
+	it("🔴 keeps a four-digit camera sequence — the 2026-08-14 flood", () => {
+		// `IMG_4595` and `IMG_4646` must NOT collapse onto each other.
+		expect(normalizeName("IMG_4595.MOV")).not.toBe(normalizeName("IMG_4646.MOV"));
+		// …while a two-digit copy marker still does.
+		expect(normalizeName("mix_2.mp3")).toBe(normalizeName("mix.mp3"));
+	});
+
+	it("drops the directory", () => {
+		expect(normalizeName("Main 1/rap/Song.mp3")).toBe("song");
+	});
+});
+
+describe("isGenericName", () => {
+	it("rejects the stems that name a device rather than a file", () => {
+		expect(isGenericName(normalizeName("IMG_1.MOV"))).toBe(true);
+		expect(isGenericName(normalizeName("Track01.mp3"))).toBe(true);
+		expect(isGenericName(normalizeName("Between U.mp3"))).toBe(false);
+	});
+});
+
+describe("sizesClose", () => {
+	it("accepts a re-encode and refuses a different file", () => {
+		expect(sizesClose(10_000_000, 10_400_000)).toBe(true);
+		expect(sizesClose(10_000_000, 20_000_000)).toBe(false);
+	});
+
+	it("🔴 two zero-byte files are not close — nothing is known about either", () => {
+		expect(sizesClose(0, 0)).toBe(false);
+	});
+
+	it("is bounded by the exported tolerance", () => {
+		expect(sizesClose(100, 100 * (1 + SIZE_TOLERANCE))).toBe(true);
+		expect(sizesClose(100, 100 * (1 + SIZE_TOLERANCE * 2))).toBe(false);
+	});
+});
+
+describe("durationsClose", () => {
+	it("🔴 answers null when nobody has measured, never false", () => {
+		expect(durationsClose(null, 200)).toBeNull();
+		expect(durationsClose(0, 200)).toBeNull();
+		expect(durationsClose(undefined, undefined)).toBeNull();
+	});
+
+	it("refuses the owner's 3:56-vs-1:52 pair", () => {
+		expect(durationsClose(236, 112)).toBe(false);
+		expect(durationsClose(236, 236 * (1 + DURATION_TOLERANCE / 2))).toBe(true);
+	});
+});
+
+describe("likelyTheSameFile", () => {
+	const facts = (name: string, sizeBytes: number, duration?: number | null) => ({
+		name,
+		sizeBytes,
+		...(duration === undefined ? {} : { duration }),
+	});
+
+	it("pairs a re-encode of the same song", () => {
+		const verdict = likelyTheSameFile(
+			facts("Between U.mp3", 8_000_000, 312),
+			facts("Between U.wma", 7_800_000, 312),
+		);
+		expect(verdict.match).toBe(true);
+		expect(verdict.reason).toContain("same name");
+	});
+
+	it("does not pair two different songs of a similar size", () => {
+		expect(likelyTheSameFile(facts("A.mp3", 8_000_000), facts("B.mp3", 8_010_000)).match).toBe(
+			false,
+		);
+	});
+
+	it("🔴 a length that disagrees kills a name+size match", () => {
+		expect(
+			likelyTheSameFile(facts("Set.mp3", 8_000_000, 236), facts("Set.mp3", 8_100_000, 112)).match,
+		).toBe(false);
+	});
+
+	it("🔴 an unmeasured length does not — that would find nothing in an unprobed library", () => {
+		expect(
+			likelyTheSameFile(facts("Set.mp3", 8_000_000, null), facts("Set.mp3", 8_100_000, null)).match,
+		).toBe(true);
+	});
+
+	it("refuses a generic stem, and refuses two nameless files", () => {
+		expect(likelyTheSameFile(facts("IMG_1.MOV", 500), facts("IMG_1.MOV", 500)).match).toBe(false);
+		expect(likelyTheSameFile(facts("", 500), facts("", 500)).match).toBe(false);
+	});
+});

package/src/core/duplicates/index.ts

@@ -0,0 +1,203 @@
+/**
+ * "Are these two files the same thing?" — the fleet's ONE answer, with no I/O in it.
+ *
+ * ── Why this is here and not in an app ──────────────────────────────────────────────────
+ * `binary-server` wrote these rules first (2026-08-13, the owner: *"make strategy to always
+ * check for duplicate binaries in same app for same user … mark likely the duplicates for
+ * users to confirm"*), and they were measured against a real store: the copy-counter cap, the
+ * camera-generic stem list and the 5% size window each exist because a wider rule proposed
+ * thousands of pairs nobody could ever review. `music` then needed the same question asked of
+ * a 5,400-track library — *"I want to see a duplicate next to the file that it is a possible
+ * duplicate of … The 'binary-server' app (bs) already has this feature for checking duplicate
+ * files. We can reuse it and enhance the customizability if needed so the main strategy is
+ * shared."*
+ *
+ * So the strategy lives once, here, and both consume it. What each app keeps for itself is the
+ * evidence only it has: bs's perceptual frame hashes, music's artist/title key.
+ *
+ * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
+ * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
+ * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * store, and so a browser bundle may import it (music renders the pair side by side).
+ */
+
+/**
+ * How far two sizes may differ and still be called the same thing.
+ *
+ * A re-encode at a different quality is the case this exists for, and those land within a few
+ * percent. Zero would make a name match a strict subset of "same name AND same size", which
+ * misses precisely the files worth asking about; much larger starts pairing a clip with its
+ * own trailer.
+ */
+export const SIZE_TOLERANCE = 0.05;
+
+/**
+ * How far two playing times may differ and still be the same recording.
+ *
+ * Wide enough for a re-encode (a trim of a trailing black frame, a container that rounds), far
+ * too narrow for the owner's 2026-08-14 report of a 3:56 video paired with a 1:52 one.
+ */
+export const DURATION_TOLERANCE = 0.05;
+
+/**
+ * The name to compare, reduced to what a human means by "the same file".
+ *
+ * Strips the directory, the extension, and the marks a copy picks up along the way —
+ * `Finder`'s ` copy`/` copy 2`, a browser's ` (1)`, a script's `_1`/`-1` — then collapses
+ * everything that is not a letter or a digit. `My Video (1).mp4`, `my_video.MP4` and
+ * `My-Video copy 2.mov` all reduce to `myvideo`.
+ *
+ * 🔴 The extension is stripped ON PURPOSE, so a re-encode (`.mov` → `.mp4`, `.wma` → `.mp3`)
+ * still pairs with its source. That is the single most common likely-duplicate in this fleet's
+ * stores and a rule that kept the extension would never see one.
+ *
+ * 🔴 **The copy-counter strip is capped at two digits**, and that cap is a measured bug fix
+ * (bs, 2026-08-14). It used to be `[-_]\d+$`, which eats a CAMERA SEQUENCE as readily as a copy
+ * marker: `IMG_4595` and `IMG_4646` both reduced to `img`, so every iPhone capture in a tenant
+ * shared one bucket and paired with every other one whose size was within 5%. `_1`…`_99` is
+ * what a copy marker actually looks like; four digits is a photo's identity, and it must
+ * survive.
+ */
+export function normalizeName(name: string | null | undefined): string {
+	if (!name) return "";
+	const leaf = name.split(/[\\/]/).pop() ?? "";
+	const stem = leaf.replace(/\.[a-z0-9]{1,5}$/i, "");
+	return stem
+		.toLowerCase()
+		.replace(/\s*\(\d+\)\s*$/, "")
+		.replace(/\s+copy(\s+\d+)?\s*$/, "")
+		.replace(/[-_]\d{1,2}\s*$/, "")
+		.replace(/[^a-z0-9]+/g, "");
+}
+
+/**
+ * Stems that name a CAMERA, not a file.
+ *
+ * `IMG`, `DSC`, `PXL`, `VID` are what a device calls everything it produces; two files whose
+ * names reduce to one of these have told us nothing except that they came from a phone. Even
+ * with the counter cap above, `IMG_1.MOV` still reduces to `img`, and a bucket called "img" is
+ * every photo the owner has ever taken.
+ *
+ * 🔴 This rejects a MATCH, never a file. Both copies stay wherever they are, and an
+ * identical-bytes pair is unaffected — a checksum match never consults the name.
+ */
+export const GENERIC_STEMS: ReadonlySet<string> = new Set([
+	"img",
+	"image",
+	"images",
+	"dsc",
+	"dscf",
+	"dscn",
+	"pxl",
+	"vid",
+	"video",
+	"movie",
+	"mov",
+	"photo",
+	"pic",
+	"picture",
+	"screenshot",
+	"screenrecording",
+	"untitled",
+	"unknown",
+	"file",
+	"download",
+	"scan",
+	"capture",
+	"copy",
+	"new",
+	"temp",
+	"tmp",
+	// Music's own version of the same problem: an untagged rip is called this by every ripper
+	// ever written, and `track01` from two albums is two different songs.
+	"track",
+	"audiotrack",
+	"unknownartist",
+]);
+
+/**
+ * A name that could belong to any file from that device tells us nothing about identity.
+ *
+ * 🔴 The trailing digit run is stripped BEFORE the lookup, and only here — never in
+ * {@link normalizeName}, where removing it is what made every camera capture one bucket. The
+ * two are asked at different moments: `normalizeName` decides whether two names are the SAME
+ * (so `img4595` and `img4646` must stay apart), and this decides whether a name that already
+ * matched is worth anything (so two files both called `Track01` have told us nothing, and a
+ * ripper names half a library that).
+ */
+export const isGenericName = (normalized: string): boolean =>
+	normalized.length < 3 ||
+	GENERIC_STEMS.has(normalized) ||
+	GENERIC_STEMS.has(normalized.replace(/\d+$/, ""));
+
+/** Within {@link SIZE_TOLERANCE} of each other. Two zero-byte files are not "close" — they
+ *  are two files nothing is known about. */
+export function sizesClose(a: number, b: number, tolerance = SIZE_TOLERANCE): boolean {
+	if (a === b && a > 0) return true;
+	const larger = Math.max(a, b);
+	if (larger <= 0) return false;
+	return Math.abs(a - b) / larger <= tolerance;
+}
+
+/**
+ * Within {@link DURATION_TOLERANCE} of each other.
+ *
+ * 🔴 A missing or zero duration answers `null`, never `false`: "nobody has measured this yet"
+ * and "these are different lengths" are opposite answers, and collapsing them makes an
+ * unprobed library look like a library with no duplicates in it.
+ */
+export function durationsClose(
+	a: number | null | undefined,
+	b: number | null | undefined,
+	tolerance = DURATION_TOLERANCE,
+): boolean | null {
+	if (!a || !b || a <= 0 || b <= 0) return null;
+	return Math.abs(a - b) / Math.max(a, b) <= tolerance;
+}
+
+/** One file, reduced to what this module can reason about. Units are the caller's — pass
+ *  both durations in the same unit or not at all. */
+export interface NamedFileFacts {
+	/** The name a person would recognise: a display title, else the last path segment. */
+	name: string | null | undefined;
+	sizeBytes: number;
+	/** Playing time, in whatever unit the caller uses consistently. Null = never measured. */
+	duration?: number | null;
+}
+
+export interface NameMatchVerdict {
+	match: boolean;
+	/** Written for the owner reading a review queue, never for a log. Empty when `match` is
+	 *  false — a non-match has nothing to explain. */
+	reason: string;
+}
+
+/**
+ * The shared "these look like the same thing" test: the NAME agrees after normalization, the
+ * sizes are close, and nothing about the length says otherwise.
+ *
+ * It is deliberately a QUESTION and never an action. Both consumers act only on a checksum,
+ * which is proof; this decides what is worth showing a person side by side.
+ */
+export function likelyTheSameFile(a: NamedFileFacts, b: NamedFileFacts): NameMatchVerdict {
+	const na = normalizeName(a.name);
+	const nb = normalizeName(b.name);
+	// Two empty names are not a match with each other — it means neither file has a name worth
+	// comparing (a bare digest key, an untitled upload), and pairing those proposes every
+	// unnamed object as a duplicate of every other.
+	if (!na || na !== nb) return { match: false, reason: "" };
+	if (isGenericName(na)) return { match: false, reason: "" };
+	if (!sizesClose(a.sizeBytes, b.sizeBytes)) return { match: false, reason: "" };
+	if (durationsClose(a.duration, b.duration) === false) return { match: false, reason: "" };
+
+	const pct = Math.round(
+		(Math.abs(a.sizeBytes - b.sizeBytes) / Math.max(a.sizeBytes, b.sizeBytes, 1)) * 100,
+	);
+	return {
+		match: true,
+		reason:
+			a.sizeBytes === b.sizeBytes
+				? "same name, same size, different bytes"
+				: `same name, size within ${pct}%, different bytes`,
+	};
+}

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