safebyok 0.0.0-stage → 0.0.0

package/dist/device-db-D3SBnJdR.d.ts

@@ -0,0 +1,326 @@
+import * as Z from "zod";
+//#region src/types.d.ts
+/**
+ * The JSON a whisper is made of. `null` is legal here -- inside an array or object -- because
+ * real JSON payloads carry it; see {@link Whisper} for why a whisper can't be null as a whole.
+ */
+type WhisperJson = string | number | boolean | null | WhisperJson[] | {
+  [ckey: string]: WhisperJson;
+};
+/**
+ * The secret kept in a lockbox: a JSON value -- a string, number, boolean, array or plain object.
+ * Two shapes are refused rather than silently mangled:
+ *  * `undefined`, anywhere in the value: JSON cannot carry it.
+ *  * a bare `null` as the whole whisper: nobody's secret is "nothing here", and emptying a
+ *    lockbox is `erase`'s job. (`null` inside a structure is fine: {@link WhisperJson}.)
+ *
+ * @example 'sk-ant-api03-...'
+ * @example { apiKey: 'sk-ant-...', orgId: null }
+ */
+type Whisper = Exclude<WhisperJson, null>;
+/**
+ * Validator for a {@link Whisper}: accepts exactly what JSON can carry, refuses what JSON would
+ * mangle (undefined, functions, class instances such as Date or Map), and refuses a bare null.
+ *
+ * @example Whisper.parse('sk-ant-...')                  // a string passes through
+ * @example Whisper.safeParse(new Date()).success        // false: JSON would flatten it to {}
+ * @example Whisper.safeParse(undefined).success         // false: undefined cannot be stored
+ * @example Whisper.safeParse(null).success              // false: emptying a lockbox is erase's job
+ * @example Whisper.safeParse({ orgId: null }).success   // true: null inside a structure is JSON
+ */
+declare const Whisper: Z.ZodType<Whisper>;
+/**
+ * A freely chosen identifier (STYLE.md tag glossary): lowercase words of letters and digits
+ * joined by single underscores, starting with a letter, two to forty characters. Shared by every
+ * label in the package: `applabel`, `vaultlabel`, `boxlabel`, `userlabel`.
+ *
+ * @example Label.parse('anthropic_api_key')
+ * @example Label.safeParse('ANTHROPIC_API_KEY').success  // false: lowercase only
+ * @example Label.safeParse('_nope').success              // false
+ */
+declare const Label: Z.ZodString;
+/**
+ * What names one vault: the host application's label, the authenticated user, and the vault's own
+ * label. Two users may each have a vault labelled `main` without collision; so may two apps
+ * sharing a backend.
+ */
+declare const VaultScope: Z.ZodObject<{
+  applabel: Z.ZodString;
+  user_id: Z.ZodString;
+  vaultlabel: Z.ZodString;
+}, Z.z.core.$strip>;
+type VaultScope = Z.infer<typeof VaultScope>;
+/**
+ * One lockbox as the storage layer holds it: the whisper ciphered under its own lockboxKey, that
+ * lockboxKey wrapped under the vaultKey, and the public shell -- boxlabel, note, timestamps --
+ * a locked vault may show. Nothing in this record opens without the vaultKey.
+ *
+ * `revision_id` is minted fresh on every write and bound into both encryptions, so ciphertext
+ * moved between revisions (or boxes, or vaults) refuses to open.
+ *
+ * Stored fields are underbar_case: this record is written to the storage layer as-is, and it is
+ * plain JSON -- any backend that can hold text can hold it.
+ */
+declare const Lockbox: Z.ZodObject<{
+  format: Z.ZodLiteral<"safebyok-lockbox-v1">;
+  boxlabel: Z.ZodString;
+  revision_id: Z.ZodString;
+  lockbox_key_wrapped: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  whisper_ciphered: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  note: Z.ZodOptional<Z.ZodString>;
+  created_at: Z.ZodString;
+  updated_at: Z.ZodString;
+}, Z.z.core.$strip>;
+type Lockbox = Z.infer<typeof Lockbox>;
+/**
+ * The public face of a lockbox: everything but its two encrypted fields. This is what `list()`
+ * returns and what a locked vault may show.
+ */
+declare const LockboxSummary: Z.ZodObject<{
+  boxlabel: Z.ZodString;
+  revision_id: Z.ZodString;
+  note: Z.ZodOptional<Z.ZodString>;
+  created_at: Z.ZodString;
+  updated_at: Z.ZodString;
+}, Z.z.core.$strip>;
+type LockboxSummary = Z.infer<typeof LockboxSummary>;
+/**
+ * The per-vault record the storage layer holds so any device can unlock the vault: the
+ * passphraseSalt, the keyDeriverLabel saying how the passphraseKey is made, and the vaultKey
+ * wrapped under that passphraseKey. All of it is safe in the open; none of it opens without
+ * the passphrase.
+ *
+ * `passphrase_epoch` goes up by one on every passphrase change, so other devices and remembered
+ * unlocks know to ask again.
+ */
+declare const VaultBundle: Z.ZodObject<{
+  format: Z.ZodLiteral<"safebyok-vault-v1">;
+  applabel: Z.ZodString;
+  user_id: Z.ZodString;
+  vaultlabel: Z.ZodString;
+  vault_id: Z.ZodString;
+  passphrase_epoch: Z.ZodNumber;
+  key_deriver_label: Z.ZodString;
+  passphrase_salt_b64: Z.ZodString;
+  vault_key_passphrase_wrapped: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  created_at: Z.ZodString;
+  updated_at: Z.ZodString;
+}, Z.z.core.$strip>;
+type VaultBundle = Z.infer<typeof VaultBundle>;
+/**
+ * The device-local record of a remembered unlock: this browser's localUnlockKey (a
+ * non-extractable handle -- it cannot leave the device even through the code that made it) and
+ * the vaultKey wrapped under it. Held only by structured-clone storage (IndexedDB) or memory;
+ * it has no JSON form, and nothing in it ever goes to the backend.
+ */
+declare const DeviceUnlock: Z.ZodObject<{
+  format: Z.ZodLiteral<"safebyok-unlock-v1">;
+  applabel: Z.ZodString;
+  user_id: Z.ZodString;
+  vaultlabel: Z.ZodString;
+  vault_id: Z.ZodString;
+  passphrase_epoch: Z.ZodNumber;
+  local_unlock_key: Z.ZodCustom<CryptoKey, CryptoKey>;
+  vault_key_local_wrapped: Z.ZodObject<{
+    cipher_iv_b64: Z.ZodString;
+    ciphertext_b64: Z.ZodString;
+  }, Z.z.core.$strip>;
+  expires_at: Z.ZodNumber;
+}, Z.z.core.$strip>;
+type DeviceUnlock = Z.infer<typeof DeviceUnlock>;
+/** How long an entered passphrase is remembered on the device, unless the caller says otherwise. */
+declare const SevenDaysMs: number;
+/**
+ * The largest whisper a vault stores unless the caller says otherwise, in bytes of its JSON:
+ * several times the beefiest credential (an RSA-8192 private key as PEM is about 6.4 KB), and
+ * well inside what every storage backend can hold. A larger whisper is usually a sign that the
+ * wrong value is being stored.
+ */
+declare const MaxWhisperBytes = 40444;
+/** Injected time source, so expiry is testable; defaults to the wall clock. */
+type Clock = {
+  now(): number;
+};
+/** The wall clock: the default `Clock`. */
+declare const wallClock: Clock;
+//#endregion
+//#region src/string-store.d.ts
+/**
+ * The smallest storage the stub adapters need: strings by string ckey, with change notification
+ * so the vault and the demo's inspector can watch it. The browser demo backs one with
+ * localStorage; the tests back one with a Map.
+ */
+type StringStore = {
+  /** The stored text under `ckey`, or null when there is none. */
+  read(ckey: string): string | null;
+  write(ckey: string, text: string): void;
+  erase(ckey: string): void;
+  /** Every ckey currently stored, in no particular order. */
+  ckeys(): string[];
+  /** Calls `listener` after any write or erase; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+};
+/**
+ * In-memory StringStore over a Map: what the tests use, and a fallback anywhere localStorage
+ * is missing.
+ *
+ * @example
+ *   const store = memoryStore()
+ *   store.write('greeting', 'hi'); store.read('greeting')  // 'hi'
+ */
+declare const memoryStore: () => StringStore;
+/**
+ * StringStore over a DOM Storage object (localStorage), confined to one prefix: each store sees
+ * only its own entries, so the demo can keep a pretend-remote database and a device cache in the
+ * same localStorage while showing them as the distinct places they stand in for.
+ *
+ * Change notification covers this tab's own writes (DOM `storage` events only fire in *other*
+ * tabs, which the demo does not chase).
+ *
+ * @param webStorage - The Storage to write through, usually `window.localStorage`.
+ * @param prefix - Namespace for this store's entries, e.g. 'safebyok-demo:db:'.
+ *
+ * @example
+ *   const dbStore = domStore(localStorage, 'safebyok-demo:db:')
+ *   dbStore.write('vault:acme:u1:main', text)   // lands at 'safebyok-demo:db:vault:acme:u1:main'
+ */
+declare const domStore: (webStorage: Storage, prefix: string) => StringStore;
+//#endregion
+//#region src/vault-db.d.ts
+/**
+ * Remote storage for vault records, as the host application plugs it in: extend this class and
+ * implement the seven `fetch`/`save`/`trash` primitives against your backend. That is the whole
+ * job -- you are a shelf, not a safe:
+ *
+ *  * **Store what you are handed, return what you stored.** Every record is plain JSON (binary
+ *    fields are base64url text), so any backend that can hold JSON can hold a vault, as-is.
+ *  * **Never look inside.** Every secret field arrives encrypted; nothing you hold can open a
+ *    vault, and nothing safebyok does ever needs you to understand a record.
+ *  * **Enforce who may reach which rows.** Your backend should let a signed-in user reach only
+ *    their own records: safebyok's encryption protects the contents, your authorization decides who
+ *    may fetch or overwrite them at all.
+ *  * **Don't repair.** Return a record exactly as stored, or null when there is none. safebyok
+ *    validates everything it reads back; a damaged record is safebyok's to refuse, never yours to fix
+ *    or quietly drop.
+ *
+ * The verbs the vault actually calls -- `readBundle`, `listBoxes`, `eraseVault` and the rest --
+ * are built for you on top of your primitives, validation included. Each compound verb documents
+ * the default composition; a backend that can do better (a transactional delete, a projected
+ * list, a push subscription) overrides that one method and leaves the rest.
+ */
+declare abstract class VaultDB {
+  /**
+   * The most this backend holds in one record, in bytes: a plain fact about the backend, or
+   * `Infinity` when it sets no per-record limit. A vault refuses to open with a `maxWhisperBytes`
+   * over half of it, leaving room for encoding and the record's other fields.
+   */
+  abstract readonly maxRecordBytes: number;
+  /** The stored bundle record for `scope`, exactly as saved, or null when there is none. */
+  protected abstract fetchBundle(scope: VaultScope): Promise<unknown>;
+  /** Store `bundle`, replacing any bundle already under its scope. */
+  protected abstract saveBundle(bundle: VaultBundle): Promise<void>;
+  /** Remove the bundle record for `scope`; succeed quietly when there is none. */
+  protected abstract trashBundle(scope: VaultScope): Promise<void>;
+  /** The stored lockbox record under `boxlabel`, exactly as saved, or null when there is none. */
+  protected abstract fetchBox(scope: VaultScope, boxlabel: string): Promise<unknown>;
+  /** Store `lockbox`, replacing any lockbox already under its boxlabel. */
+  protected abstract saveBox(scope: VaultScope, lockbox: Lockbox): Promise<void>;
+  /** Remove the lockbox record under `boxlabel`; succeed quietly when there is none. */
+  protected abstract trashBox(scope: VaultScope, boxlabel: string): Promise<void>;
+  /** Every stored lockbox record in `scope`, in any order. */
+  protected abstract fetchBoxes(scope: VaultScope): Promise<unknown[]>;
+  /** The vault's bundle, validated, or null when the vault has never been created. */
+  readBundle(scope: VaultScope): Promise<VaultBundle | null>;
+  /** Store `bundle`, replacing whatever bundle its scope held. */
+  writeBundle(bundle: VaultBundle): Promise<void>;
+  /**
+   * Store `bundle` only if its scope holds none, and return whichever bundle ends up there: the
+   * given one, or the one another device got in first with.
+   *
+   * Default composition: a fetch, then a save -- two devices creating at the same instant can
+   * still race between those steps. A backend with an atomic create should override this with
+   * one, and resolve the race for real.
+   */
+  createBundle(bundle: VaultBundle): Promise<VaultBundle>;
+  /** One lockbox record, validated, or null when there is none under that label. */
+  readBox(scope: VaultScope, boxlabel: string): Promise<Lockbox | null>;
+  /** Store `lockbox`, replacing whatever its boxlabel held. */
+  writeBox(scope: VaultScope, lockbox: Lockbox): Promise<void>;
+  /** Remove the lockbox under `boxlabel`. */
+  eraseBox(scope: VaultScope, boxlabel: string): Promise<void>;
+  /**
+   * Public faces of every lockbox in the vault -- ciphered fields stripped, sorted by boxlabel --
+   * valid while locked.
+   *
+   * Default composition: fetch every full record and strip it here. A backend that can project
+   * away the ciphered fields server-side should override this and skip hauling them.
+   */
+  listBoxes(scope: VaultScope): Promise<LockboxSummary[]>;
+  /**
+   * Remove the bundle and every lockbox: the backend's part of deleting a vault.
+   *
+   * Default composition: trash each lockbox, then the bundle -- an interruption can strand some
+   * rows, though never usable ones. A backend with a transaction or batch delete should override
+   * this with one.
+   */
+  eraseVault(scope: VaultScope): Promise<void>;
+  /**
+   * Calls `onChange` after any write touching `scope`, from this device or another; returns the
+   * unsubscribe. The default never calls: safebyok refreshes after its own writes regardless, so all
+   * a silent backend loses is news of *other* devices' writes. A backend with live queries or
+   * push (Convex, a websocket) should override this and ring the bell.
+   */
+  subscribe(_scope: VaultScope, _onChange: () => void): () => void;
+}
+/**
+ * VaultDB over a {@link StringStore}: rows as JSON text under scope-prefixed ckeys. The demo
+ * backs one with localStorage to stand in for a real backend; tests back one with a Map. Every
+ * secret field in what it stores is ciphertext, so the only thing pretend about it is reach --
+ * rows stay on this device instead of syncing through a shared database.
+ *
+ * @example
+ *   const vaultDB = localVaultDB(memoryStore())
+ *   await vaultDB.readBundle({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null
+ */
+declare const localVaultDB: (store: StringStore) => VaultDB;
+//#endregion
+//#region src/device-db.d.ts
+/**
+ * Device-local storage for remembered unlocks: what lets "enter your passphrase once, keep it for
+ * seven days" survive a page reload. A {@link DeviceUnlock} record holds this browser's
+ * localUnlockKey -- a non-extractable CryptoKey handle, which has no JSON form -- so an adapter
+ * must keep records by structured clone (IndexedDB: see `safebyok/idb`) or in memory; nothing here
+ * ever goes to the backend.
+ *
+ * An adapter may answer a damaged or unreadable record with null rather than an error: losing a
+ * remembered unlock only means asking for the passphrase again, and that is the safe failure.
+ */
+interface DeviceDB {
+  /** The remembered unlock for one vault, or null when there is none. Expiry is the vault's call. */
+  readUnlock(scope: VaultScope): Promise<DeviceUnlock | null>;
+  writeUnlock(unlock: DeviceUnlock): Promise<void>;
+  eraseUnlock(scope: VaultScope): Promise<void>;
+  /** Remove every remembered unlock on this device: the device's part of a full reset. */
+  eraseAll(): Promise<void>;
+}
+/**
+ * DeviceDB over a Map: what the tests use, and the fallback anywhere without IndexedDB. Remembered
+ * unlocks last exactly as long as the page -- which is to say, it remembers nothing, safely.
+ *
+ * @example
+ *   const deviceDB = memoryDeviceDB()
+ *   await deviceDB.readUnlock({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null
+ */
+declare const memoryDeviceDB: () => DeviceDB;
+//#endregion
+export { Whisper as _, StringStore as a, Clock as c, Lockbox as d, LockboxSummary as f, VaultScope as g, VaultBundle as h, localVaultDB as i, DeviceUnlock as l, SevenDaysMs as m, memoryDeviceDB as n, domStore as o, MaxWhisperBytes as p, VaultDB as r, memoryStore as s, DeviceDB as t, Label as u, WhisperJson as v, wallClock as y };
+//# sourceMappingURL=device-db-D3SBnJdR.d.ts.map

package/dist/idb.cjs

@@ -0,0 +1,181 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_vault_db = require("./vault-db-C19pMom1.cjs");
+let idb_keyval = require("idb-keyval");
+//#region src/idb.ts
+const shelfStores = /* @__PURE__ */ new Map();
+const shelfStore = (dbName, shelf) => {
+	const ckey = `${dbName}:${shelf}`;
+	const kept = shelfStores.get(ckey);
+	if (kept !== void 0) return kept;
+	const fresh = (0, idb_keyval.createStore)(`${dbName}:${shelf}`, "records");
+	shelfStores.set(ckey, fresh);
+	return fresh;
+};
+const bells = /* @__PURE__ */ new Map();
+const channels = /* @__PURE__ */ new Map();
+const bellCkey = (dbName, shelf) => `safebyok-idb:${dbName}:${shelf}`;
+const ringBell = (dbName, shelf) => {
+	const ckey = bellCkey(dbName, shelf);
+	bells.get(ckey)?.forEach((listener) => {
+		listener();
+	});
+	channels.get(ckey)?.postMessage("changed");
+};
+const onBell = (dbName, shelf, listener) => {
+	const ckey = bellCkey(dbName, shelf);
+	let ringers = bells.get(ckey);
+	if (ringers === void 0) {
+		ringers = /* @__PURE__ */ new Set();
+		bells.set(ckey, ringers);
+		if (typeof BroadcastChannel !== "undefined") {
+			const channel = new BroadcastChannel(ckey);
+			channel.addEventListener("message", () => {
+				bells.get(ckey)?.forEach((ring) => {
+					ring();
+				});
+			});
+			channels.set(ckey, channel);
+		}
+	}
+	ringers.add(listener);
+	return () => {
+		ringers.delete(listener);
+	};
+};
+const scopePath = (scope) => `${scope.applabel}:${scope.user_id}:${scope.vaultlabel}`;
+const bundleCkey = (scope) => `vault:${scopePath(scope)}`;
+const boxCkey = (scope, boxlabel) => `box:${scopePath(scope)}:${boxlabel}`;
+const boxPrefix = (scope) => `box:${scopePath(scope)}:`;
+const unlockCkey = (scope) => `unlock:${scopePath(scope)}`;
+/**
+* VaultDB over this browser's IndexedDB: the local-only tier. Nothing syncs -- this "backend"
+* never leaves the device -- but every secret field is ciphertext all the same, and the stored
+* rows are exactly what a real backend would hold.
+*
+* @example
+*   const vaultDB = idbVaultDB({ dbName: 'my_app' })
+*   const vault = await openVault({ applabel: 'my_app', userId, vaultlabel: 'main', vaultDB, deviceDB: idbDeviceDB({ dbName: 'my_app' }) })
+*/
+const idbVaultDB = (opts = {}) => new IdbVaultDB(opts.dbName ?? "safebyok");
+var IdbVaultDB = class extends require_vault_db.VaultDB {
+	dbName;
+	maxRecordBytes = Infinity;
+	constructor(dbName) {
+		super();
+		this.dbName = dbName;
+	}
+	shelf() {
+		return shelfStore(this.dbName, "vault_db");
+	}
+	ring() {
+		ringBell(this.dbName, "vault_db");
+	}
+	async fetchBundle(scope) {
+		return await (0, idb_keyval.get)(bundleCkey(scope), this.shelf()) ?? null;
+	}
+	async saveBundle(bundle) {
+		await (0, idb_keyval.set)(bundleCkey(bundle), bundle, this.shelf());
+		this.ring();
+	}
+	async trashBundle(scope) {
+		await (0, idb_keyval.del)(bundleCkey(scope), this.shelf());
+		this.ring();
+	}
+	async fetchBox(scope, boxlabel) {
+		return await (0, idb_keyval.get)(boxCkey(scope, boxlabel), this.shelf()) ?? null;
+	}
+	async saveBox(scope, lockbox) {
+		await (0, idb_keyval.set)(boxCkey(scope, lockbox.boxlabel), lockbox, this.shelf());
+		this.ring();
+	}
+	async trashBox(scope, boxlabel) {
+		await (0, idb_keyval.del)(boxCkey(scope, boxlabel), this.shelf());
+		this.ring();
+	}
+	async fetchBoxes(scope) {
+		return (await (0, idb_keyval.entries)(this.shelf())).filter(([ckey]) => typeof ckey === "string" && ckey.startsWith(boxPrefix(scope))).map(([, row]) => row);
+	}
+	subscribe(_scope, onChange) {
+		return onBell(this.dbName, "vault_db", onChange);
+	}
+};
+/**
+* DeviceDB over this browser's IndexedDB: the real device storage. IndexedDB keeps the
+* DeviceUnlock record by structured clone, which is the only way a browser persists the
+* non-extractable localUnlockKey -- as a handle, never as bytes.
+*
+* A record that will not read back (damaged, or written by another version) reads as "no
+* remembered unlock" and is dropped: losing the convenience is the safe failure.
+*
+* @example
+*   const deviceDB = idbDeviceDB()
+*   await deviceDB.readUnlock({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null
+*/
+const idbDeviceDB = (opts = {}) => {
+	const dbName = opts.dbName ?? "safebyok";
+	const shelf = () => shelfStore(dbName, "device_db");
+	const ring = () => {
+		ringBell(dbName, "device_db");
+	};
+	return {
+		readUnlock: async (scope) => {
+			const raw = await (0, idb_keyval.get)(unlockCkey(scope), shelf());
+			if (raw === void 0 || raw === null) return null;
+			const checked = require_vault_db.DeviceUnlock.safeParse(raw);
+			if (!checked.success) {
+				await (0, idb_keyval.del)(unlockCkey(scope), shelf());
+				ring();
+				return null;
+			}
+			return checked.data;
+		},
+		writeUnlock: async (unlock) => {
+			await (0, idb_keyval.set)(unlockCkey(unlock), unlock, shelf());
+			ring();
+		},
+		eraseUnlock: async (scope) => {
+			await (0, idb_keyval.del)(unlockCkey(scope), shelf());
+			ring();
+		},
+		eraseAll: async () => {
+			const ckeys = await (0, idb_keyval.keys)(shelf());
+			for (const ckey of ckeys) if (typeof ckey === "string" && ckey.startsWith("unlock:")) await (0, idb_keyval.del)(ckey, shelf());
+			ring();
+		}
+	};
+};
+/**
+* A window onto one safebyok shelf in IndexedDB, for inspectors and debug panels: the raw rows, a
+* change bell, and a wipe. This is how the demo shows "what the backend sees" without asking the
+* vault's opinion -- what it reports is what is actually stored.
+*
+* @example
+*   const inspector = inspectIdb({ shelf: 'vault_db' })
+*   const rows = await inspector.rows()
+*   const stop = inspector.subscribe(() => { void inspector.rows().then(render) })
+*/
+const inspectIdb = (opts) => {
+	const dbName = opts.dbName ?? "safebyok";
+	return {
+		/** Every stored row on the shelf, sorted by ckey. */
+		rows: async () => {
+			return (await (0, idb_keyval.entries)(shelfStore(dbName, opts.shelf))).filter((pair) => typeof pair[0] === "string").map(([ckey, row]) => ({
+				ckey,
+				row
+			})).toSorted((one, two) => one.ckey.localeCompare(two.ckey));
+		},
+		/** Calls `listener` after any write to the shelf, this tab or another; returns the unsubscribe. */
+		subscribe: (listener) => onBell(dbName, opts.shelf, listener),
+		/** Remove every row on the shelf. */
+		wipe: async () => {
+			await (0, idb_keyval.clear)(shelfStore(dbName, opts.shelf));
+			ringBell(dbName, opts.shelf);
+		}
+	};
+};
+//#endregion
+exports.idbDeviceDB = idbDeviceDB;
+exports.idbVaultDB = idbVaultDB;
+exports.inspectIdb = inspectIdb;
+
+//# sourceMappingURL=idb.cjs.map

package/dist/idb.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"idb.cjs","names":["createStore","VaultDB","get","set","del","entries","DeviceUnlock","keys","clear"],"sources":["../src/idb.ts"],"sourcesContent":["import { createStore, del, entries, get, keys, set, clear, type UseStore } from 'idb-keyval'\nimport { DeviceUnlock, Lockbox, VaultBundle, type VaultScope } from './types'\nimport { VaultDB } from './vault-db'\nimport type { DeviceDB } from './device-db'\n\n/**\n * The browser adapters, over IndexedDB (through `idb-keyval`): a vault that lives entirely on\n * this device. `idbDeviceDB` is the real thing -- device storage is exactly what IndexedDB is,\n * and the only browser storage that can hold a non-extractable localUnlockKey. `idbVaultDB` is\n * the no-backend tier: everything a synced backend would hold, kept on this device instead, so a\n * purely client-side app still gets its whispers encrypted at rest.\n *\n * Browser storage is best-effort: the browser may evict it under pressure, and \"clear site data\"\n * removes it. An app leaning on `idbVaultDB` should call `navigator.storage.persist()` and say\n * plainly that the vault lives only in this browser.\n *\n * This entry point touches IndexedDB only when an adapter is used, so importing it is safe\n * anywhere; the adapters themselves need a browser (or anything else with `indexedDB`).\n */\n\nexport type IdbOpts = {\n  /** The IndexedDB database to keep records in. Default 'safebyok'. */\n  dbName?: string\n}\n\n/** Which of the two safebyok shelves an IndexedDB database holds records on. */\nexport type IdbShelf = 'vault_db' | 'device_db'\n\n// One UseStore per (dbName, shelf), shared by adapters and inspectors alike: idb-keyval opens\n// the underlying database lazily, so making these is free until something reads or writes.\nconst shelfStores = new Map<string, UseStore>()\nconst shelfStore = (dbName: string, shelf: IdbShelf): UseStore => {\n  const ckey = `${dbName}:${shelf}`\n  const kept = shelfStores.get(ckey)\n  if (kept !== undefined) { return kept }\n  const fresh = createStore(`${dbName}:${shelf}`, 'records')\n  shelfStores.set(ckey, fresh)\n  return fresh\n}\n\n// Change bells, one per (dbName, shelf): local listeners hear this tab's writes directly, and a\n// BroadcastChannel carries them to other tabs (the channel never echoes to its own sender).\nconst bells = new Map<string, Set<() => void>>()\nconst channels = new Map<string, BroadcastChannel>()\nconst bellCkey = (dbName: string, shelf: IdbShelf) => `safebyok-idb:${dbName}:${shelf}`\n\nconst ringBell = (dbName: string, shelf: IdbShelf) => {\n  const ckey = bellCkey(dbName, shelf)\n  bells.get(ckey)?.forEach((listener) => { listener() })\n  channels.get(ckey)?.postMessage('changed')\n}\n\nconst onBell = (dbName: string, shelf: IdbShelf, listener: () => void): (() => void) => {\n  const ckey = bellCkey(dbName, shelf)\n  let ringers = bells.get(ckey)\n  if (ringers === undefined) {\n    ringers = new Set()\n    bells.set(ckey, ringers)\n    if (typeof BroadcastChannel !== 'undefined') {\n      const channel = new BroadcastChannel(ckey)\n      channel.addEventListener('message', () => { bells.get(ckey)?.forEach((ring) => { ring() }) })\n      channels.set(ckey, channel)\n    }\n  }\n  ringers.add(listener)\n  return () => { ringers.delete(listener) }\n}\n\nconst scopePath = (scope: VaultScope) => `${scope.applabel}:${scope.user_id}:${scope.vaultlabel}`\nconst bundleCkey = (scope: VaultScope) => `vault:${scopePath(scope)}`\nconst boxCkey = (scope: VaultScope, boxlabel: string) => `box:${scopePath(scope)}:${boxlabel}`\nconst boxPrefix = (scope: VaultScope) => `box:${scopePath(scope)}:`\nconst unlockCkey = (scope: VaultScope) => `unlock:${scopePath(scope)}`\n\n/**\n * VaultDB over this browser's IndexedDB: the local-only tier. Nothing syncs -- this \"backend\"\n * never leaves the device -- but every secret field is ciphertext all the same, and the stored\n * rows are exactly what a real backend would hold.\n *\n * @example\n *   const vaultDB = idbVaultDB({ dbName: 'my_app' })\n *   const vault = await openVault({ applabel: 'my_app', userId, vaultlabel: 'main', vaultDB, deviceDB: idbDeviceDB({ dbName: 'my_app' }) })\n */\nexport const idbVaultDB = (opts: IdbOpts = {}): VaultDB => new IdbVaultDB(opts.dbName ?? 'safebyok')\n\nclass IdbVaultDB extends VaultDB {\n  // IndexedDB sets no per-record limit: the origin's storage quota bounds the whole database.\n  readonly maxRecordBytes = Infinity\n\n  constructor(private readonly dbName: string) { super() }\n  private shelf() { return shelfStore(this.dbName, 'vault_db') }\n  private ring() { ringBell(this.dbName, 'vault_db') }\n\n  protected async fetchBundle(scope: VaultScope): Promise<unknown> {\n    return (await get(bundleCkey(scope), this.shelf())) ?? null\n  }\n\n  protected async saveBundle(bundle: VaultBundle): Promise<void> {\n    await set(bundleCkey(bundle), bundle, this.shelf())\n    this.ring()\n  }\n\n  protected async trashBundle(scope: VaultScope): Promise<void> {\n    await del(bundleCkey(scope), this.shelf())\n    this.ring()\n  }\n\n  protected async fetchBox(scope: VaultScope, boxlabel: string): Promise<unknown> {\n    return (await get(boxCkey(scope, boxlabel), this.shelf())) ?? null\n  }\n\n  protected async saveBox(scope: VaultScope, lockbox: Lockbox): Promise<void> {\n    await set(boxCkey(scope, lockbox.boxlabel), lockbox, this.shelf())\n    this.ring()\n  }\n\n  protected async trashBox(scope: VaultScope, boxlabel: string): Promise<void> {\n    await del(boxCkey(scope, boxlabel), this.shelf())\n    this.ring()\n  }\n\n  protected async fetchBoxes(scope: VaultScope): Promise<unknown[]> {\n    const rows = await entries(this.shelf())\n    return rows\n      .filter(([ckey]) => typeof ckey === 'string' && ckey.startsWith(boxPrefix(scope)))\n      .map(([, row]) => row as unknown)\n  }\n\n  // Rings on every write to the shelf, not only ones in scope: a spurious refresh is harmless,\n  // and cross-tab news arrives over the BroadcastChannel for free.\n  override subscribe(_scope: VaultScope, onChange: () => void): () => void {\n    return onBell(this.dbName, 'vault_db', onChange)\n  }\n}\n\n/**\n * DeviceDB over this browser's IndexedDB: the real device storage. IndexedDB keeps the\n * DeviceUnlock record by structured clone, which is the only way a browser persists the\n * non-extractable localUnlockKey -- as a handle, never as bytes.\n *\n * A record that will not read back (damaged, or written by another version) reads as \"no\n * remembered unlock\" and is dropped: losing the convenience is the safe failure.\n *\n * @example\n *   const deviceDB = idbDeviceDB()\n *   await deviceDB.readUnlock({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null\n */\nexport const idbDeviceDB = (opts: IdbOpts = {}): DeviceDB => {\n  const dbName = opts.dbName ?? 'safebyok'\n  const shelf = () => shelfStore(dbName, 'device_db')\n  const ring = () => { ringBell(dbName, 'device_db') }\n\n  return {\n    readUnlock: async (scope) => {\n      const raw: unknown = await get(unlockCkey(scope), shelf())\n      if (raw === undefined || raw === null) { return null }\n      const checked = DeviceUnlock.safeParse(raw)\n      if (! checked.success) {\n        await del(unlockCkey(scope), shelf())\n        ring()\n        return null\n      }\n      return checked.data\n    },\n\n    writeUnlock: async (unlock) => {\n      await set(unlockCkey(unlock), unlock, shelf())\n      ring()\n    },\n\n    eraseUnlock: async (scope) => {\n      await del(unlockCkey(scope), shelf())\n      ring()\n    },\n\n    eraseAll: async () => {\n      const ckeys = await keys(shelf())\n      for (const ckey of ckeys) {\n        if (typeof ckey === 'string' && ckey.startsWith('unlock:')) { await del(ckey, shelf()) }\n      }\n      ring()\n    },\n  }\n}\n\n/** One stored row, as {@link inspectIdb} reports it: its ckey and the raw stored value. */\nexport type IdbRow = { ckey: string, row: unknown }\n\n/**\n * A window onto one safebyok shelf in IndexedDB, for inspectors and debug panels: the raw rows, a\n * change bell, and a wipe. This is how the demo shows \"what the backend sees\" without asking the\n * vault's opinion -- what it reports is what is actually stored.\n *\n * @example\n *   const inspector = inspectIdb({ shelf: 'vault_db' })\n *   const rows = await inspector.rows()\n *   const stop = inspector.subscribe(() => { void inspector.rows().then(render) })\n */\nexport const inspectIdb = (opts: IdbOpts & { shelf: IdbShelf }) => {\n  const dbName = opts.dbName ?? 'safebyok'\n  return {\n    /** Every stored row on the shelf, sorted by ckey. */\n    rows: async (): Promise<IdbRow[]> => {\n      const stored = await entries(shelfStore(dbName, opts.shelf))\n      return stored\n        .filter((pair): pair is [string, unknown] => typeof pair[0] === 'string')\n        .map(([ckey, row]) => ({ ckey, row }))\n        .toSorted((one, two) => one.ckey.localeCompare(two.ckey))\n    },\n    /** Calls `listener` after any write to the shelf, this tab or another; returns the unsubscribe. */\n    subscribe: (listener: () => void): (() => void) => onBell(dbName, opts.shelf, listener),\n    /** Remove every row on the shelf. */\n    wipe: async (): Promise<void> => {\n      await clear(shelfStore(dbName, opts.shelf))\n      ringBell(dbName, opts.shelf)\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/idb.d.cts

@@ -0,0 +1,72 @@
+import { r as VaultDB, t as DeviceDB } from "./device-db-D3SBnJdR.cjs";
+//#region src/idb.d.ts
+/**
+ * The browser adapters, over IndexedDB (through `idb-keyval`): a vault that lives entirely on
+ * this device. `idbDeviceDB` is the real thing -- device storage is exactly what IndexedDB is,
+ * and the only browser storage that can hold a non-extractable localUnlockKey. `idbVaultDB` is
+ * the no-backend tier: everything a synced backend would hold, kept on this device instead, so a
+ * purely client-side app still gets its whispers encrypted at rest.
+ *
+ * Browser storage is best-effort: the browser may evict it under pressure, and "clear site data"
+ * removes it. An app leaning on `idbVaultDB` should call `navigator.storage.persist()` and say
+ * plainly that the vault lives only in this browser.
+ *
+ * This entry point touches IndexedDB only when an adapter is used, so importing it is safe
+ * anywhere; the adapters themselves need a browser (or anything else with `indexedDB`).
+ */
+export type IdbOpts = {
+  /** The IndexedDB database to keep records in. Default 'safebyok'. */
+  dbName?: string;
+};
+/** Which of the two safebyok shelves an IndexedDB database holds records on. */
+export type IdbShelf = 'vault_db' | 'device_db';
+/**
+ * VaultDB over this browser's IndexedDB: the local-only tier. Nothing syncs -- this "backend"
+ * never leaves the device -- but every secret field is ciphertext all the same, and the stored
+ * rows are exactly what a real backend would hold.
+ *
+ * @example
+ *   const vaultDB = idbVaultDB({ dbName: 'my_app' })
+ *   const vault = await openVault({ applabel: 'my_app', userId, vaultlabel: 'main', vaultDB, deviceDB: idbDeviceDB({ dbName: 'my_app' }) })
+ */
+export declare const idbVaultDB: (opts?: IdbOpts) => VaultDB;
+/**
+ * DeviceDB over this browser's IndexedDB: the real device storage. IndexedDB keeps the
+ * DeviceUnlock record by structured clone, which is the only way a browser persists the
+ * non-extractable localUnlockKey -- as a handle, never as bytes.
+ *
+ * A record that will not read back (damaged, or written by another version) reads as "no
+ * remembered unlock" and is dropped: losing the convenience is the safe failure.
+ *
+ * @example
+ *   const deviceDB = idbDeviceDB()
+ *   await deviceDB.readUnlock({ applabel: 'acme', user_id: 'u1', vaultlabel: 'main' })  // null
+ */
+export declare const idbDeviceDB: (opts?: IdbOpts) => DeviceDB;
+/** One stored row, as {@link inspectIdb} reports it: its ckey and the raw stored value. */
+export type IdbRow = {
+  ckey: string;
+  row: unknown;
+};
+/**
+ * A window onto one safebyok shelf in IndexedDB, for inspectors and debug panels: the raw rows, a
+ * change bell, and a wipe. This is how the demo shows "what the backend sees" without asking the
+ * vault's opinion -- what it reports is what is actually stored.
+ *
+ * @example
+ *   const inspector = inspectIdb({ shelf: 'vault_db' })
+ *   const rows = await inspector.rows()
+ *   const stop = inspector.subscribe(() => { void inspector.rows().then(render) })
+ */
+export declare const inspectIdb: (opts: IdbOpts & {
+  shelf: IdbShelf;
+}) => {
+  /** Every stored row on the shelf, sorted by ckey. */
+  rows: () => Promise<IdbRow[]>;
+  /** Calls `listener` after any write to the shelf, this tab or another; returns the unsubscribe. */
+  subscribe: (listener: () => void) => (() => void);
+  /** Remove every row on the shelf. */
+  wipe: () => Promise<void>;
+};
+//#endregion
+//# sourceMappingURL=idb.d.cts.map