cursedbelt-server 2.0.0 → 3.0.0

package/src/server/d1/types.ts

@@ -0,0 +1,163 @@
+/**
+ * The async database seam every app crosses to reach SQLite — locally on `bun:sqlite`,
+ * remotely on Cloudflare D1.
+ *
+ * ## 🔴 It is async on BOTH sides, and that is the entire point
+ *
+ * `bun:sqlite` is synchronous: `db.query(sql).all()` returns rows. D1 is
+ * `await db.prepare(sql).all()`. No adapter, no proxy and no `Proxy` trap makes a
+ * synchronous call site await — so the port is a real edit at every call site, and the
+ * only question this seam answers is whether that edit has to happen TWICE.
+ *
+ * A seam that is sync locally and async remotely passes every test on this machine and
+ * fails in production. So {@link D1LikeDatabase} is the same async shape on both sides,
+ * the local driver is the one that changes, and a ported call site runs unmodified
+ * against either.
+ *
+ * ## 🔴 The local driver is as STRICT as the remote one, never as lenient as Bun
+ *
+ * The same argument applies one level down, and it is where the real bugs live. Measured
+ * against `bun:sqlite` on 2026-09-16, four things differ between the two drivers, and two
+ * of them are silent-here / throw-there:
+ *
+ *   | value                | `bun:sqlite`                  | D1 (`workerd`)          |
+ *   |----------------------|-------------------------------|-------------------------|
+ *   | `undefined` bind     | 🔴 silently binds NULL        | throws                  |
+ *   | `boolean` bind       | 🔴 silently coerces to 0/1    | throws                  |
+ *   | BLOB column read     | `Uint8Array`                  | `number[]`              |
+ *   | `.run()` result      | `{changes, lastInsertRowid}`  | `{success, meta, …}`    |
+ *
+ * Lenient-locally is the same defect as sync-locally wearing a different costume: it is
+ * green on this Mac and red in the Worker. `normalizeBind` in `./values` therefore makes
+ * the LOCAL driver refuse what D1 refuses, and normalizes what both accept to one shape.
+ * The one deliberate exception is `boolean`, which is coerced to 0/1 on both sides rather
+ * than refused on both: SQLite has no boolean type, so 0/1 is not a guess about intent,
+ * and refusing it would break every natural `where('disabled', '=', false)` in the fleet.
+ * `undefined` is refused, because "missing argument" and "intentional NULL" are genuinely
+ * different and only the caller knows which was meant.
+ *
+ * ## Transactions are refused on both sides, and `batch()` is the answer
+ *
+ * D1 has no interactive transaction — there is no `BEGIN`/`COMMIT` over HTTP, only
+ * {@link D1LikeDatabase.batch}, which is atomic and runs as one round trip. A local
+ * driver that happily honoured `BEGIN` would be the sync-vs-async trap a third time, so
+ * {@link D1UnsupportedError} is thrown by both. Wrap the statements in `batch()` instead;
+ * it is atomic on D1 and wrapped in a real `bun:sqlite` transaction locally, so the
+ * guarantee is the same.
+ *
+ * The shape below deliberately mirrors Cloudflare's own `D1Database` rather than
+ * inventing a vocabulary: the remote driver is then close to a pass-through, and the
+ * thing an app author reads in Cloudflare's docs is the thing they have.
+ */
+
+/** A row as it comes back from either driver — column name to normalized value. */
+export type D1LikeRow = Record<string, D1LikeValue>;
+
+/**
+ * Every value either driver can RETURN, after normalization. Note there is no `boolean`
+ * and no `bigint`: SQLite stores neither, and a driver that invented one on read would
+ * disagree with the other driver on the way back in.
+ */
+export type D1LikeValue = string | number | null | Uint8Array;
+
+/**
+ * Every value either driver accepts as a BOUND parameter. `boolean` is accepted and
+ * coerced to 0/1; `bigint` is accepted within the safe-integer range and refused outside
+ * it (where it could not survive the round trip anyway). `undefined` is absent on
+ * purpose — see the header.
+ */
+export type D1LikeBindable = string | number | boolean | bigint | null | Uint8Array | ArrayBuffer;
+
+/**
+ * What a statement reports about its own execution. Mirrors D1's `meta`, with the fields
+ * the local driver can honestly fill. A field the local driver cannot know is `null`
+ * rather than a plausible-looking zero — a fabricated `rows_read` of 0 would read as a
+ * measurement in `192`'s CPU accounting rather than as an absence.
+ */
+export interface D1LikeMeta {
+	/** Rows changed by the statement. `0` for a read. */
+	changes: number;
+	/** Rowid of the last insert, or `null` when the statement inserted nothing. */
+	last_row_id: number | null;
+	/** Wall-clock milliseconds the driver spent on the statement. */
+	duration: number;
+	/** D1 only — rows the query engine read. `null` locally, where nothing counts them. */
+	rows_read: number | null;
+	/** D1 only — rows the query engine wrote. `null` locally. */
+	rows_written: number | null;
+}
+
+/** The result of `.all()` / `.run()` on either driver. */
+export interface D1LikeResult<T = D1LikeRow> {
+	results: T[];
+	success: true;
+	meta: D1LikeMeta;
+}
+
+/**
+ * A prepared statement. `bind()` returns a NEW statement rather than mutating this one,
+ * which is D1's own contract and what makes a statement safe to keep and re-bind.
+ */
+export interface D1LikeStatement {
+	bind(...values: D1LikeBindable[]): D1LikeStatement;
+	/** The first row, or `null` when the query matched nothing. */
+	first<T = D1LikeRow>(): Promise<T | null>;
+	/** One column of the first row, or `null` when the query matched nothing. */
+	first<V = D1LikeValue>(column: string): Promise<V | null>;
+	all<T = D1LikeRow>(): Promise<D1LikeResult<T>>;
+	run(): Promise<D1LikeResult<never>>;
+	/** Rows as positional arrays rather than objects — the cheap shape for bulk reads. */
+	raw<V = D1LikeValue>(): Promise<V[][]>;
+}
+
+/**
+ * The database handle an app holds. One of these is constructed per request on a Worker
+ * and once per process locally; nothing below this line knows which it got.
+ */
+export interface D1LikeDatabase {
+	prepare(sql: string): D1LikeStatement;
+	/**
+	 * Run several statements atomically as ONE round trip. This is the transaction
+	 * primitive — see the header for why there is no `begin()`.
+	 */
+	batch<T = D1LikeRow>(statements: D1LikeStatement[]): Promise<D1LikeResult<T>[]>;
+	/**
+	 * Run one or more statements for their side effects, with no bound parameters —
+	 * schema migrations, `PRAGMA`s, DDL. Not for anything carrying user input.
+	 */
+	exec(sql: string): Promise<{ count: number; duration: number }>;
+	/** Which side of the seam this handle is. Lets a caller branch where it genuinely must. */
+	readonly flavor: 'local' | 'd1';
+}
+
+/** Thrown when a bound parameter is of a type D1 will not accept. */
+export class D1BindError extends TypeError {
+	readonly index: number;
+	constructor(index: number, message: string) {
+		super(`parameter ${index + 1}: ${message}`);
+		this.name = 'D1BindError';
+		this.index = index;
+	}
+}
+
+/** Thrown for an operation D1 cannot perform, so the local driver refuses it too. */
+export class D1UnsupportedError extends Error {
+	constructor(what: string, instead: string) {
+		super(`${what} is not supported on D1 — ${instead}`);
+		this.name = 'D1UnsupportedError';
+	}
+}
+
+/** Thrown when a statement would exceed one of D1's hard limits. See `./limits`. */
+export class D1LimitError extends RangeError {
+	readonly limit: string;
+	readonly actual: number;
+	readonly max: number;
+	constructor(limit: string, actual: number, max: number, remedy: string) {
+		super(`D1 limit '${limit}' exceeded: ${actual} > ${max}. ${remedy}`);
+		this.name = 'D1LimitError';
+		this.limit = limit;
+		this.actual = actual;
+		this.max = max;
+	}
+}

package/src/server/d1/values.ts

@@ -0,0 +1,138 @@
+/**
+ * The one place that decides what a bound parameter and a returned column MEAN, shared by
+ * both drivers.
+ *
+ * 🔴 **Both drivers call these, and that is why the identical-shapes test can pass.** If
+ * the local driver normalized its own way and the remote driver normalized its own way,
+ * the test in `sameShape.spec.ts` would be asserting that two independent implementations
+ * happen to agree today — which is a coincidence with a maintenance schedule. Here there
+ * is one implementation of the meaning and two implementations of the transport.
+ *
+ * Every rule below was measured against `bun:sqlite` on 2026-09-16 (`Bun 1.3`), not
+ * recalled: the probe wrote each type into a `CREATE TABLE t (v)` column and read it back.
+ */
+
+import { D1BindError, type D1LikeBindable, type D1LikeMeta, type D1LikeValue } from './types';
+
+/**
+ * The largest integer a JS number holds exactly. A `bigint` beyond this cannot survive the
+ * round trip through either driver — measured, `bun:sqlite` returns `9007199254740992` for
+ * a stored `9007199254740993` — so it is refused rather than silently rounded.
+ */
+const SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+/**
+ * Normalize one bound parameter to something BOTH drivers accept, or throw.
+ *
+ * The local driver is deliberately made as strict as D1 here. `bun:sqlite` accepts
+ * `undefined` (binding NULL) and `boolean` (coercing to 0/1) where D1 throws; a local
+ * driver that inherited that leniency would go green on this Mac and red in the Worker,
+ * which is the same defect as a sync seam.
+ */
+export function normalizeBind(value: unknown, index: number): D1LikeBindable {
+	if (value === null) return null;
+
+	switch (typeof value) {
+		case 'string':
+		case 'number':
+			// 🔴 NaN and ±Infinity have no SQLite representation. `bun:sqlite` stores NaN as
+			// NULL; D1 rejects it. Refusing both is the only answer that reads the same.
+			if (typeof value === 'number' && !Number.isFinite(value)) {
+				throw new D1BindError(index, `${value} has no SQLite representation — store null, or a string`);
+			}
+			return value;
+
+		// SQLite has no boolean type: 0/1 is the storage, not a guess about intent. Coerced
+		// on BOTH sides so the two agree, rather than refused on both, which would break
+		// every natural `where('disabled', '=', false)` in the fleet.
+		case 'boolean':
+			return value ? 1 : 0;
+
+		case 'bigint':
+			if (value > SAFE || value < -SAFE) {
+				throw new D1BindError(
+					index,
+					`bigint ${value} is outside the safe-integer range and cannot round-trip — store it as TEXT`,
+				);
+			}
+			return Number(value);
+
+		case 'undefined':
+			// 🔴 The measured trap. `bun:sqlite` binds NULL and says nothing; D1 throws.
+			// "Missing argument" and "intentional NULL" are different, and only the caller
+			// knows which was meant — so the caller says so.
+			throw new D1BindError(index, 'undefined — pass null explicitly if you mean SQL NULL');
+
+		case 'object':
+			if (value instanceof Uint8Array) return value;
+			if (value instanceof ArrayBuffer) return new Uint8Array(value);
+			if (value instanceof Date) {
+				// Common enough to deserve its own sentence rather than "not supported".
+				throw new D1BindError(index, 'Date — store an ISO string (`d.toISOString()`) or an epoch number');
+			}
+			throw new D1BindError(index, `${value.constructor?.name ?? 'object'} — bind a string, number, null or Uint8Array`);
+
+		default:
+			throw new D1BindError(index, `${typeof value} is not bindable`);
+	}
+}
+
+/** Normalize a whole parameter list, reporting the offending position on failure. */
+export const normalizeBinds = (values: readonly unknown[]): D1LikeBindable[] =>
+	values.map((v, i) => normalizeBind(v, i));
+
+/**
+ * Normalize one column value coming BACK from a driver.
+ *
+ * The measured disagreement is BLOBs: `bun:sqlite` returns a `Uint8Array`, D1 returns a
+ * plain `number[]` (it crosses the wire as JSON). `Uint8Array` wins on both — it is the
+ * type every consumer of a blob actually wants, and `Array.isArray` is a reliable way to
+ * spot D1's shape because no other column type returns an array.
+ */
+export function normalizeValue(value: unknown): D1LikeValue {
+	if (value === null || value === undefined) return null;
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	if (Array.isArray(value)) return Uint8Array.from(value as number[]);
+	if (typeof value === 'bigint') return Number(value);
+	if (typeof value === 'boolean') return value ? 1 : 0;
+	if (typeof value === 'string' || typeof value === 'number') return value;
+	// Nothing else can come out of either driver; if it does, that is a driver change we
+	// want to hear about loudly rather than pass through as an opaque object.
+	throw new TypeError(`unexpected column value of type ${typeof value} from the database driver`);
+}
+
+/** Normalize a row object, preserving column order. */
+export function normalizeRow<T>(row: Record<string, unknown>): T {
+	const out: Record<string, D1LikeValue> = {};
+	for (const key of Object.keys(row)) out[key] = normalizeValue(row[key]);
+	return out as T;
+}
+
+/** Normalize a whole result set. */
+export const normalizeRows = <T>(rows: readonly Record<string, unknown>[]): T[] =>
+	rows.map((r) => normalizeRow<T>(r));
+
+/**
+ * Build a {@link D1LikeMeta}. `rows_read`/`rows_written` default to `null` — the local
+ * driver genuinely cannot count them, and a plausible-looking `0` would be read as a
+ * measurement by `192`'s CPU accounting rather than as an absence.
+ */
+export function makeMeta(partial: {
+	changes?: number;
+	last_row_id?: number | bigint | null;
+	duration: number;
+	rows_read?: number | null;
+	rows_written?: number | null;
+}): D1LikeMeta {
+	const raw = partial.last_row_id ?? null;
+	return {
+		changes: partial.changes ?? 0,
+		// A rowid of 0 means "nothing was inserted" in both drivers; report it as absent
+		// so a caller can `?? ` it rather than having to know that 0 is a sentinel.
+		last_row_id: raw === null || Number(raw) === 0 ? null : Number(raw),
+		duration: partial.duration,
+		rows_read: partial.rows_read ?? null,
+		rows_written: partial.rows_written ?? null,
+	};
+}

package/src/server/master-lock/accounts.spec.ts

@@ -0,0 +1,308 @@
+/**
+ * 🔴 **The accounts model — a master password IS a tenant.**
+ *
+ * The owner's words, and the whole specification:
+ *
+ * > *"If I login with a master password I only see the files I added or removed with that
+ * > login. If I login with my other password I have not made yet I only see the other ones
+ * > I add in that login. The master passwords represent their own tenants or you can think
+ * > of it as a fully separate account even though I am the user in both cases."*
+ *
+ * This file proves the half that lives in the lock. The half that lives in an app — every
+ * query scoped by the id this hands out — is that app's own gate to prove.
+ *
+ * The claim each `describe` carries is the thing that would be catastrophic to get wrong,
+ * and three of them are catastrophic in a way that is SILENT: a tenant that cannot be
+ * reached looks exactly like a tenant with nothing in it.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+} from "cursedbelt-core/master-lock";
+import { FIRST_ACCOUNT_ID, MasterLock, readRecord } from "./masterLock";
+import { createMemoryMasterLockStore } from "./store";
+
+/** `iter: 1` — the ROUND COUNT is pinned in `cursedbelt-core`'s `kdf.spec.ts`; 600k × N
+ *  argon2 verifies here would be minutes of gate for nothing this file is testing. */
+const KDF: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 1,
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+
+const FIRST = "the owner's vault master password";
+const SECOND = "password";
+
+let firstVerifier = "";
+let secondVerifier = "";
+/** The LEGACY record: one password, no accounts — the shape every `MASTER_LOCK_SEED` in
+ *  the fleet carries, and the shape every un-upgraded app already has in its database. */
+let legacyJson = "";
+
+beforeEach(async () => {
+	if (firstVerifier) return;
+	firstVerifier = await deriveMasterLockVerifier(FIRST, KDF);
+	secondVerifier = await deriveMasterLockVerifier(SECOND, KDF);
+	legacyJson = JSON.stringify({
+		kdf: KDF,
+		verifierHash: await Bun.password.hash(firstVerifier, { algorithm: "argon2id" }),
+		idleMs: 300_000,
+	});
+});
+
+const build = (stored?: string | null) => {
+	const store = createMemoryMasterLockStore(stored ?? null);
+	return { store, lock: new MasterLock({ store }) };
+};
+
+const req = (token: string): Request =>
+	new Request("http://app.test/", { headers: { cookie: `master_lock=${token}` } });
+
+/** Unlock and hand back a request that presents the resulting token. */
+async function open(lock: MasterLock, verifier: string) {
+	const result = await lock.unlock(verifier);
+	if (!result.ok) throw new Error("expected the unlock to succeed");
+	return { ...result, req: req(result.token) };
+}
+
+describe("🔴 claim 1 — the owner's existing password keeps opening everything he has", () => {
+	test("a legacy single-password record becomes acct-1, and that password still works", async () => {
+		// THE migration guarantee. `apps/collections` stamps its 279 existing rows with this
+		// id, so an id that moved — or a record that failed to parse and armed nothing —
+		// would orphan the entire library this migration exists to carry across.
+		const { lock } = build(legacyJson);
+		expect(lock.configured).toBe(true);
+		expect(lock.accounts.length).toBe(1);
+		expect(lock.accounts[0]?.id).toBe(FIRST_ACCOUNT_ID);
+
+		const opened = await open(lock, firstVerifier);
+		expect(opened.accountId).toBe(FIRST_ACCOUNT_ID);
+		// And nothing else was invented along the way.
+		expect(lock.idleMs).toBe(300_000);
+	});
+
+	test("the migration is a READ — it does not rewrite the row until something else does", async () => {
+		// A record that rewrote itself on boot would mean a rollback to the previous build
+		// could no longer read its own store. Nothing is persisted until a write happens for
+		// a reason of its own.
+		const { lock, store } = build(legacyJson);
+		expect(lock.configured).toBe(true);
+		expect(store.read()).toBe(legacyJson);
+
+		lock.setIdleMs(600_000);
+		const rewritten = readRecord(store.read());
+		expect(rewritten?.accounts[0]?.id).toBe(FIRST_ACCOUNT_ID);
+		expect(rewritten?.idleMs).toBe(600_000);
+	});
+});
+
+describe("🔴 claim 2 — a second password is a second tenant, and never the first one", () => {
+	test("adding one needs a live unlock AND the current password, re-typed", async () => {
+		const { lock } = build(legacyJson);
+
+		// No unlock at all.
+		expect(
+			await lock.addAccount(req("nope"), {
+				currentVerifier: firstVerifier,
+				verifier: secondVerifier,
+				label: "Account 2",
+			}),
+		).toEqual({ ok: false, reason: "locked" });
+
+		const opened = await open(lock, firstVerifier);
+
+		// Unlocked, but the current password not proved.
+		expect(
+			await lock.addAccount(opened.req, {
+				currentVerifier: "not it",
+				verifier: secondVerifier,
+				label: "Account 2",
+			}),
+		).toEqual({ ok: false, reason: "wrong" });
+		expect(lock.accounts.length).toBe(1);
+
+		const added = await lock.addAccount(opened.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+			hint: "the obvious one",
+		});
+		expect(added.ok && added.account.id).toBe("acct-2");
+	});
+
+	test("each password opens its OWN account, and a token never reads as the other", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+		const second = await open(lock, secondVerifier);
+
+		expect(first.accountId).toBe("acct-1");
+		expect(second.accountId).toBe("acct-2");
+		// The property everything else rests on: a token is bound to the account that minted
+		// it, so two browsers open at once are two tenants, not one ambient state.
+		expect(lock.accountFor(first.req)).toBe("acct-1");
+		expect(lock.accountFor(second.req)).toBe("acct-2");
+	});
+
+	test("creating a tenant does NOT enter it", async () => {
+		// Switching means typing that tenant's password. If creating one dropped you into
+		// it, the owner would add an account and watch his library apparently vanish.
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+		expect(lock.accountFor(first.req)).toBe("acct-1");
+	});
+
+	test("🔴 a password that already opens something is refused", async () => {
+		// Two accounts under one password would make `unlock` serve whichever the loop
+		// reached first — so the owner would type the password he has always typed and be
+		// handed an empty library, with his real one apparently gone.
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		expect(
+			await lock.addAccount(first.req, {
+				currentVerifier: firstVerifier,
+				verifier: firstVerifier,
+				label: "A clone",
+			}),
+		).toEqual({ ok: false, reason: "duplicate" });
+		expect(lock.accounts.length).toBe(1);
+	});
+});
+
+describe("🔴 claim 3 — changing a password never changes which content it opens", () => {
+	test("the account id survives a rotation, and the siblings survive it too", async () => {
+		// The owner: *"If I change account 2 password it just changes how I get the access.
+		// For instance I could change it from 'password' to 'passwordIPicked' later and I
+		// would still access the same content afterward."*
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+
+		const second = await open(lock, secondVerifier);
+		const picked = await deriveMasterLockVerifier("passwordIPicked", KDF);
+		expect(
+			await lock.change(second.req, { currentVerifier: secondVerifier, verifier: picked }),
+		).toEqual({ ok: true });
+
+		// The new password opens the SAME tenant…
+		const reopened = await open(lock, picked);
+		expect(reopened.accountId).toBe("acct-2");
+		// …the old one opens nothing…
+		expect((await lock.unlock(secondVerifier)).ok).toBe(false);
+		// …and account 1 is untouched, which is what a shared KDF salt is protecting.
+		const stillFirst = await open(lock, firstVerifier);
+		expect(stillFirst.accountId).toBe("acct-1");
+	});
+
+	test("a rotation cannot collide a password onto a sibling", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+		});
+		const second = await open(lock, secondVerifier);
+		expect(
+			await lock.change(second.req, {
+				currentVerifier: secondVerifier,
+				verifier: firstVerifier,
+			}),
+		).toEqual({ ok: false, reason: "invalid" });
+	});
+});
+
+describe("🔴 claim 4 — the hints are readable while locked, and nothing else is", () => {
+	test("a hint survives a rotation and can be rewritten without the password", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+			hint: "the obvious one",
+		});
+
+		expect(lock.hints()).toEqual([
+			{ label: "Account 1", hint: "" },
+			{ label: "Account 2", hint: "the obvious one" },
+		]);
+
+		const second = await open(lock, secondVerifier);
+		expect(lock.editAccount(second.req, { id: "acct-2", hint: "rhymes with lassword" })).toBe(true);
+		expect(lock.hints()[1]?.hint).toBe("rhymes with lassword");
+	});
+
+	test("🔴 one session cannot rewrite another tenant's label or hint", async () => {
+		// The hint is the one field designed to be read by somebody who is LOCKED OUT, so a
+		// session holding one password must not be able to rewrite the note that gets the
+		// other one back in.
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "Account 2",
+			hint: "the obvious one",
+		});
+		expect(lock.editAccount(first.req, { id: "acct-2", hint: "overwritten" })).toBe(false);
+		expect(lock.hints()[1]?.hint).toBe("the obvious one");
+	});
+
+	test("a hint is trimmed and capped, so it cannot become a wall of text on the lock screen", async () => {
+		const { lock } = build(legacyJson);
+		const first = await open(lock, firstVerifier);
+		await lock.addAccount(first.req, {
+			currentVerifier: firstVerifier,
+			verifier: secondVerifier,
+			label: "  Account\n\n2  ",
+			hint: `${"x".repeat(400)}`,
+		});
+		expect(lock.accounts[1]?.label).toBe("Account 2");
+		expect(lock.accounts[1]?.hint.length).toBe(200);
+	});
+});
+
+describe("🔴 claim 5 — a malformed row costs one account, never the keyring", () => {
+	test("an unreadable account is dropped and the others still open", async () => {
+		// This record is the ONLY thing that says which password opens which library.
+		// Refusing the whole file over one bad row would take every tenant down with it.
+		const good = await Bun.password.hash(firstVerifier, { algorithm: "argon2id" });
+		const stored = JSON.stringify({
+			kdf: KDF,
+			idleMs: 300_000,
+			accounts: [
+				{ id: "acct-1", label: "Account 1", hint: "", verifierHash: good, createdAt: 1 },
+				{ id: "acct-2", label: "Broken", hint: "", verifierHash: "not-a-hash", createdAt: 2 },
+				// A duplicate id, and an id shaped like something that could reach SQL.
+				{ id: "acct-1", label: "Dupe", hint: "", verifierHash: good, createdAt: 3 },
+				{ id: "../escape", label: "Nope", hint: "", verifierHash: good, createdAt: 4 },
+			],
+		});
+		const { lock } = build(stored);
+		expect(lock.accounts.map((account) => account.id)).toEqual(["acct-1"]);
+		expect((await open(lock, firstVerifier)).accountId).toBe("acct-1");
+	});
+
+	test("an empty keyring is a legitimate state, not a parse failure", async () => {
+		const { lock } = build(JSON.stringify({ kdf: KDF, idleMs: 300_000, accounts: [] }));
+		expect(lock.configured).toBe(false);
+		expect(lock.awaitingEnrollment).toBe(true);
+		expect(lock.unlocked).toBe(false);
+	});
+});