@noy-db/hub 0.1.0-pre.3

package/dist/ulid-COREQ2RQ.js

@@ -0,0 +1,9 @@
+import {
+  generateULID,
+  isULID
+} from "./chunk-FZU343FL.js";
+export {
+  generateULID,
+  isULID
+};
+//# sourceMappingURL=ulid-COREQ2RQ.js.map

package/dist/ulid-COREQ2RQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/util/index.cjs

@@ -0,0 +1,230 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/util/index.ts
+var util_exports = {};
+__export(util_exports, {
+  sanitizeFilename: () => sanitizeFilename
+});
+module.exports = __toCommonJS(util_exports);
+
+// src/errors.ts
+var NoydbError = class extends Error {
+  /** Machine-readable error code. Stable across library versions. */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NoydbError";
+    this.code = code;
+  }
+};
+var FilenameSanitizationError = class extends NoydbError {
+  constructor(message) {
+    super("FILENAME_SANITIZATION", message);
+    this.name = "FilenameSanitizationError";
+  }
+};
+
+// src/util/sanitize-filename.ts
+var REPLACEMENT = "_";
+var BIDI_OVERRIDES = /[‪-‮⁦-⁩]/g;
+var WINDOWS_RESERVED_CHARS = /[<>:"/\\|?*]/g;
+var WINDOWS_RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9"
+]);
+var MAC_HIDDEN_NOISE = /^(?:\.DS_Store|\.localized|\.fseventsd|\._.+)$/i;
+var URL_UNRESERVED = /[A-Za-z0-9\-._~]/;
+var utf8 = new TextEncoder();
+function isControlCode(cp) {
+  return cp >= 0 && cp <= 31 || cp === 127;
+}
+function stripControlChars(s) {
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    out += isControlCode(s.charCodeAt(i)) ? REPLACEMENT : s[i];
+  }
+  return out;
+}
+function trimWhitespaceAndControls(s) {
+  let start = 0;
+  let end = s.length;
+  while (start < end) {
+    const ch = s[start];
+    if (!isControlCode(s.charCodeAt(start)) && ch.trim() !== "") break;
+    start++;
+  }
+  while (end > start) {
+    const ch = s[end - 1];
+    if (!isControlCode(s.charCodeAt(end - 1)) && ch.trim() !== "") break;
+    end--;
+  }
+  return s.slice(start, end);
+}
+function sanitizeFilename(name, opts) {
+  if (typeof name !== "string") {
+    throw new FilenameSanitizationError("input must be a string");
+  }
+  if (name.includes("\0")) {
+    throw new FilenameSanitizationError("NUL byte in filename");
+  }
+  let s = name.normalize("NFC").replace(BIDI_OVERRIDES, "");
+  if (opts.profile === "opaque") {
+    return applyOpaque(s, opts);
+  }
+  s = trimWhitespaceAndControls(s);
+  switch (opts.profile) {
+    case "posix":
+      return cap(applyPosix(s), opts.maxBytes ?? 255, "utf8");
+    case "windows":
+      return cap(applyWindows(s), opts.maxBytes ?? 255, "utf16");
+    case "macos-smb":
+      return cap(applyMacosSmb(s), opts.maxBytes ?? 240, "utf8");
+    case "zip":
+      return cap(applyZip(s), opts.maxBytes ?? 255, "utf8");
+    case "url-path":
+      return cap(applyUrlPath(s), opts.maxBytes ?? 1024, "bytes-pre-encode");
+    case "s3-key":
+      return cap(applyS3Key(s), opts.maxBytes ?? 1024, "utf8");
+  }
+}
+function applyPosix(s) {
+  const cleaned = s.replace(/\//g, REPLACEMENT);
+  return rejectDotSegments(cleaned);
+}
+function applyWindows(s) {
+  let cleaned = s.replace(WINDOWS_RESERVED_CHARS, REPLACEMENT);
+  cleaned = stripControlChars(cleaned);
+  cleaned = cleaned.replace(/[. ]+$/g, "");
+  cleaned = rejectDotSegments(cleaned);
+  return avoidWindowsReservedName(cleaned);
+}
+function applyMacosSmb(s) {
+  let cleaned = applyWindows(s);
+  if (MAC_HIDDEN_NOISE.test(cleaned)) {
+    cleaned = REPLACEMENT + cleaned;
+  }
+  return cleaned;
+}
+function applyZip(s) {
+  let cleaned = s.replace(/^\/+/, "");
+  cleaned = rejectDotSegments(cleaned);
+  return stripControlChars(cleaned);
+}
+function applyUrlPath(s) {
+  let out = "";
+  for (const ch of s) {
+    if (URL_UNRESERVED.test(ch)) {
+      out += ch;
+      continue;
+    }
+    const bytes = utf8.encode(ch);
+    for (const b of bytes) {
+      out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+    }
+  }
+  return out;
+}
+function applyS3Key(s) {
+  return applyUrlPath(s.replace(/^\/+/, ""));
+}
+function applyOpaque(s, opts) {
+  if (!opts.opaqueId) {
+    throw new FilenameSanitizationError("opaque profile requires opaqueId");
+  }
+  const dot = s.lastIndexOf(".");
+  if (dot > 0 && dot < s.length - 1) {
+    const ext = s.slice(dot + 1);
+    if (/^[A-Za-z0-9]{1,16}$/.test(ext)) {
+      return `${opts.opaqueId}.${ext.toLowerCase()}`;
+    }
+  }
+  return opts.opaqueId;
+}
+function rejectDotSegments(s) {
+  if (s === "." || s === ".." || s.split(/[/\\]/).some((seg) => seg === "..")) {
+    throw new FilenameSanitizationError("path traversal segment in filename");
+  }
+  if (s.length === 0) {
+    throw new FilenameSanitizationError("empty filename after sanitization");
+  }
+  return s;
+}
+function avoidWindowsReservedName(s) {
+  const dot = s.indexOf(".");
+  const base = dot === -1 ? s : s.slice(0, dot);
+  if (WINDOWS_RESERVED_NAMES.has(base.toUpperCase())) {
+    return REPLACEMENT + s;
+  }
+  return s;
+}
+function cap(s, max, unit) {
+  if (max <= 0) {
+    throw new FilenameSanitizationError("maxBytes must be positive");
+  }
+  if (unit === "utf16") {
+    if (s.length <= max) return s;
+    return s.slice(0, max);
+  }
+  if (unit === "bytes-pre-encode") {
+    if (utf8.encode(s).byteLength <= max) return s;
+    return truncateToByteCap(s, max);
+  }
+  if (utf8.encode(s).byteLength <= max) return s;
+  return truncateToByteCap(s, max);
+}
+function truncateToByteCap(s, max) {
+  let out = "";
+  let used = 0;
+  for (const cp of s) {
+    const n = utf8.encode(cp).byteLength;
+    if (used + n > max) break;
+    out += cp;
+    used += n;
+  }
+  if (out.length === 0) {
+    throw new FilenameSanitizationError("maxBytes too small for a single code point");
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sanitizeFilename
+});
+//# sourceMappingURL=index.cjs.map

package/dist/util/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/util/index.ts","../../src/errors.ts","../../src/util/sanitize-filename.ts"],"sourcesContent":["/**\n * `@noy-db/hub/util` — pure helpers that don't belong to any single\n * subsystem and have no dependency on the keyring, ledger, or stores.\n *\n * Currently:\n *   - {@link sanitizeFilename} — target-profile aware filename safety\n *     for export-blobs sites and any other place where adopters write\n *     a record-supplied filename to a real storage destination.\n *\n * @module\n */\n\nexport { sanitizeFilename } from './sanitize-filename.js'\nexport type {\n  FilenameProfile,\n  SanitizeFilenameOptions,\n} from './sanitize-filename.js'\n","/**\n * All NOYDB error classes — a single import surface for `catch` blocks and\n * `instanceof` checks.\n *\n * ## Class hierarchy\n *\n * ```\n * Error\n *  └─ NoydbError (code: string)\n *       ├─ Crypto errors\n *       │    ├─ DecryptionError        — AES-GCM tag failure\n *       │    ├─ TamperedError          — ciphertext modified after write\n *       │    └─ InvalidKeyError        — wrong passphrase / corrupt keyring\n *       ├─ Access errors\n *       │    ├─ NoAccessError          — no DEK for this collection\n *       │    ├─ ReadOnlyError          — ro permission, write attempted\n *       │    ├─ PermissionDeniedError  — role too low for operation\n *       │    ├─ PrivilegeEscalationError — grant wider than grantor holds\n *       │    └─ StoreCapabilityError   — optional store method missing\n *       ├─ Sync errors\n *       │    ├─ ConflictError          — optimistic-lock version mismatch\n *       │    ├─ BundleVersionConflictError — bundle push rejected by remote\n *       │    └─ NetworkError           — push/pull network failure\n *       ├─ Data errors\n *       │    ├─ NotFoundError          — get(id) on missing record\n *       │    ├─ ValidationError        — application-level guard failed\n *       │    └─ SchemaValidationError  — Standard Schema v1 rejection\n *       ├─ Query errors\n *       │    ├─ JoinTooLargeError      — join row ceiling exceeded\n *       │    ├─ DanglingReferenceError — strict ref() points at nothing\n *       │    ├─ GroupCardinalityError  — groupBy bucket cap exceeded\n *       │    ├─ IndexRequiredError      — lazy-mode query touches unindexed field\n *       │    └─ IndexWriteFailureError       — index side-car put/delete failed post-main\n *       ├─ i18n / Dictionary errors\n *       │    ├─ ReservedCollectionNameError\n *       │    ├─ DictKeyMissingError\n *       │    ├─ DictKeyInUseError\n *       │    ├─ MissingTranslationError\n *       │    ├─ LocaleNotSpecifiedError\n *       │    └─ TranslatorNotConfiguredError\n *       ├─ Backup errors\n *       │    ├─ BackupLedgerError      — hash-chain verification failed\n *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump\n *       ├─ Bundle errors\n *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch\n *       └─ Session errors\n *            ├─ SessionExpiredError\n *            ├─ SessionNotFoundError\n *            └─ SessionPolicyError\n * ```\n *\n * ## Catching all NOYDB errors\n *\n * ```ts\n * import { NoydbError, InvalidKeyError, ConflictError } from '@noy-db/hub'\n *\n * try {\n *   await vault.unlock(passphrase)\n * } catch (e) {\n *   if (e instanceof InvalidKeyError) { showBadPassphraseUI(); return }\n *   if (e instanceof NoydbError) { logToSentry(e.code, e); return }\n *   throw e  // unexpected — re-throw\n * }\n * ```\n *\n * @module\n */\n\n/**\n * Base class for all NOYDB errors.\n *\n * Every error thrown by `@noy-db/hub` extends this class, so consumers can\n * catch all NOYDB errors in a single `catch (e) { if (e instanceof NoydbError) ... }`\n * block. The `code` field is a machine-readable string (e.g. `'DECRYPTION_FAILED'`)\n * suitable for `switch` statements and logging pipelines.\n */\nexport class NoydbError extends Error {\n  /** Machine-readable error code. Stable across library versions. */\n  readonly code: string\n\n  constructor(code: string, message: string) {\n    super(message)\n    this.name = 'NoydbError'\n    this.code = code\n  }\n}\n\n// ─── Crypto Errors ─────────────────────────────────────────────────────\n\n/**\n * Thrown when AES-GCM decryption fails.\n *\n * The most common cause is a wrong passphrase or a corrupted ciphertext.\n * A `DecryptionError` at the wrong passphrase level is caught internally\n * and re-thrown as `InvalidKeyError` — so in practice this surfaces for\n * per-record corruption rather than authentication failures.\n */\nexport class DecryptionError extends NoydbError {\n  constructor(message = 'Decryption failed') {\n    super('DECRYPTION_FAILED', message)\n    this.name = 'DecryptionError'\n  }\n}\n\n/**\n * Thrown when GCM tag verification fails, indicating the ciphertext was\n * modified after encryption.\n *\n * AES-256-GCM is authenticated encryption — the tag over the ciphertext\n * is checked on every decrypt. If any byte was flipped (accidental\n * corruption or deliberate tampering), decryption throws this error.\n * Treat it as a security alert: the stored bytes are not what NOYDB wrote.\n */\nexport class TamperedError extends NoydbError {\n  constructor(message = 'Data integrity check failed — record may have been tampered with') {\n    super('TAMPERED', message)\n    this.name = 'TamperedError'\n  }\n}\n\n/**\n * Thrown when key unwrapping fails, typically because the passphrase is wrong\n * or the keyring file is corrupted.\n *\n * NOYDB uses AES-KW (RFC 3394) to wrap DEKs with the KEK. If AES-KW\n * unwrapping fails, it means either the KEK was derived from the wrong\n * passphrase (PBKDF2 with 600K iterations) or the keyring bytes are\n * corrupted. This is the error shown to the user on a failed unlock attempt.\n */\nexport class InvalidKeyError extends NoydbError {\n  constructor(message = 'Invalid key — wrong passphrase or corrupted keyring') {\n    super('INVALID_KEY', message)\n    this.name = 'InvalidKeyError'\n  }\n}\n\n// ─── Access Errors ─────────────────────────────────────────────────────\n\n/**\n * Thrown when the authenticated user does not have a DEK for the requested\n * collection — i.e. the collection is not in their keyring at all.\n *\n * This is the \"no key for this door\" error. It is different from\n * `ReadOnlyError` (user has a key but it only grants ro) and from\n * `PermissionDeniedError` (user's role doesn't allow the operation).\n */\nexport class NoAccessError extends NoydbError {\n  constructor(message = 'No access — user does not have a key for this collection') {\n    super('NO_ACCESS', message)\n    this.name = 'NoAccessError'\n  }\n}\n\n/**\n * Thrown when a user with read-only (`ro`) permission attempts a write\n * operation (`put` or `delete`) on a collection.\n *\n * The user has a DEK for the collection (they can decrypt and read), but\n * their keyring grants only `ro`. To fix: re-grant the user with `rw`\n * permission, or do not attempt writes as a viewer/client role.\n */\nexport class ReadOnlyError extends NoydbError {\n  constructor(message = 'Read-only — user has ro permission on this collection') {\n    super('READ_ONLY', message)\n    this.name = 'ReadOnlyError'\n  }\n}\n\n/**\n * Thrown when a write is attempted against a historical view produced\n * by `vault.at(timestamp)`. Time-machine views are read-only by\n * contract — mutating the past would require either the shadow-vault\n * mechanism or a ledger-history rewrite (which breaks\n * the tamper-evidence guarantee).\n *\n * Distinct from {@link ReadOnlyError} (keyring-level) and\n * {@link PermissionDeniedError} (role-level): this error is about the\n * *view* being historical, independent of the caller's permissions.\n */\nexport class ReadOnlyAtInstantError extends NoydbError {\n  constructor(operation: string, timestamp: string) {\n    super(\n      'READ_ONLY_AT_INSTANT',\n      `Cannot ${operation}() on a vault view anchored at ${timestamp} — time-machine views are read-only`,\n    )\n    this.name = 'ReadOnlyAtInstantError'\n  }\n}\n\n/**\n * Thrown when a write is attempted against a shadow-vault frame\n * produced by `vault.frame()`. Frames are read-only by contract —\n * the use case is screen-sharing / demos / compliance review where\n * the operator wants to prevent accidental edits.\n *\n * Behavioural enforcement only — the underlying keyring still holds\n * write-capable DEKs. See {@link VaultFrame} for the full caveat.\n */\nexport class ReadOnlyFrameError extends NoydbError {\n  constructor(operation: string) {\n    super(\n      'READ_ONLY_FRAME',\n      `Cannot ${operation}() on a vault frame — frames are read-only presentations of the current vault`,\n    )\n    this.name = 'ReadOnlyFrameError'\n  }\n}\n\n/**\n * Thrown when the authenticated user's role does not permit the requested\n * operation — e.g. a `viewer` calling `grantAccess()`, or an `operator`\n * calling `rotateKeys()`.\n *\n * This is a role-level check (what the user's role allows), distinct from\n * `NoAccessError` (collection not in keyring) and `ReadOnlyError` (in\n * keyring, but write not allowed).\n */\nexport class PermissionDeniedError extends NoydbError {\n  constructor(message = 'Permission denied — insufficient role for this operation') {\n    super('PERMISSION_DENIED', message)\n    this.name = 'PermissionDeniedError'\n  }\n}\n\n/**\n * Thrown when an `@noy-db/as-*` export is attempted without the\n * required capability bit on the invoking keyring.\n *\n * Two sub-cases discriminated by the `tier` field:\n *\n * - `tier: 'plaintext'` — a plaintext-tier export (`as-xlsx`,\n *   `as-csv`, `as-blob`, `as-zip`, …) was attempted but the\n *   keyring's `exportCapability.plaintext` does not include the\n *   requested `format` (nor the `'*'` wildcard). Default for every\n *   role is `plaintext: []` — the owner must positively grant.\n * - `tier: 'bundle'` — an encrypted `as-noydb` bundle export was\n *   attempted but the keyring's `exportCapability.bundle` is\n *   `false`. Default for `owner`/`admin` is `true`; for\n *   `operator`/`viewer`/`client` it is `false`.\n *\n * Distinct from `PermissionDeniedError` (role-level check) and\n * `NoAccessError` (collection not readable). Surfaces separately so\n * UI layers can show a \"request the export capability from your\n * admin\" flow rather than a generic permission error.\n */\nexport class ExportCapabilityError extends NoydbError {\n  readonly tier: 'plaintext' | 'bundle'\n  readonly format?: string\n  readonly userId: string\n\n  constructor(opts: {\n    tier: 'plaintext' | 'bundle'\n    userId: string\n    format?: string\n    message?: string\n  }) {\n    const msg =\n      opts.message ??\n      (opts.tier === 'plaintext'\n        ? `Export capability denied — keyring \"${opts.userId}\" is not granted plaintext-export capability for format \"${opts.format ?? '<unknown>'}\". Ask a vault owner or admin to grant it via vault.grant({ exportCapability: { plaintext: ['${opts.format ?? '<format>'}'] } }).`\n        : `Export capability denied — keyring \"${opts.userId}\" is not granted encrypted-bundle export capability. Ask a vault owner or admin to grant it via vault.grant({ exportCapability: { bundle: true } }).`)\n    super('EXPORT_CAPABILITY', msg)\n    this.name = 'ExportCapabilityError'\n    this.tier = opts.tier\n    this.userId = opts.userId\n    if (opts.format !== undefined) this.format = opts.format\n  }\n}\n\n/**\n * Thrown when a keyring file's `expires_at` cutoff has passed.\n * Surfaced by `loadKeyring` before any DEK unwrap is attempted —\n * past the cutoff the slot refuses to open even with the right\n * passphrase. Distinct from PBKDF2 / unwrap errors so consumer code\n * can show a precise \"this bundle slot has expired\" message instead\n * of the generic decryption-failure UX.\n *\n * Used predominantly on `BundleRecipient` slots produced by\n * `writeNoydbBundle({ recipients: [...] })` to time-box audit access.\n */\nexport class KeyringExpiredError extends NoydbError {\n  readonly userId: string\n  readonly expiresAt: string\n  constructor(opts: { userId: string; expiresAt: string }) {\n    super(\n      'KEYRING_EXPIRED',\n      `Keyring \"${opts.userId}\" expired at ${opts.expiresAt}. ` +\n        'The slot refuses to unlock past its expiry timestamp.',\n    )\n    this.name = 'KeyringExpiredError'\n    this.userId = opts.userId\n    this.expiresAt = opts.expiresAt\n  }\n}\n\n/**\n * Thrown when an `@noy-db/as-*` import is attempted but the invoking\n * keyring lacks the required import-capability bit (issue ).\n *\n * - `tier: 'plaintext'` — a plaintext-tier import (`as-csv`, `as-json`,\n *   `as-ndjson`, `as-zip`, …) was attempted but the keyring's\n *   `importCapability.plaintext` does not include the requested\n *   `format` (nor the `'*'` wildcard).\n * - `tier: 'bundle'` — a `.noydb` bundle import was attempted but the\n *   keyring's `importCapability.bundle` is not `true`.\n *\n * Default for every role on every dimension is closed — owners and\n * admins must positively grant the capability. Distinct from\n * `PermissionDeniedError` and `NoAccessError` so UI layers can show a\n * specific \"request the import capability\" flow.\n */\nexport class ImportCapabilityError extends NoydbError {\n  readonly tier: 'plaintext' | 'bundle'\n  readonly format?: string\n  readonly userId: string\n\n  constructor(opts: {\n    tier: 'plaintext' | 'bundle'\n    userId: string\n    format?: string\n    message?: string\n  }) {\n    const msg =\n      opts.message ??\n      (opts.tier === 'plaintext'\n        ? `Import capability denied — keyring \"${opts.userId}\" is not granted plaintext-import capability for format \"${opts.format ?? '<unknown>'}\". Ask a vault owner or admin to grant it via vault.grant({ importCapability: { plaintext: ['${opts.format ?? '<format>'}'] } }).`\n        : `Import capability denied — keyring \"${opts.userId}\" is not granted encrypted-bundle import capability. Ask a vault owner or admin to grant it via vault.grant({ importCapability: { bundle: true } }).`)\n    super('IMPORT_CAPABILITY', msg)\n    this.name = 'ImportCapabilityError'\n    this.tier = opts.tier\n    this.userId = opts.userId\n    if (opts.format !== undefined) this.format = opts.format\n  }\n}\n\n/**\n * Thrown when a grant would give the grantee a permission the grantor\n * does not themselves hold — the \"admin cannot grant what admin cannot\n * do\" rule from the admin-delegation work.\n *\n * Distinct from `PermissionDeniedError` so callers can tell the two\n * cases apart in logs and tests:\n *\n *   - `PermissionDeniedError` — \"you are not allowed to perform this\n *     operation at all\" (wrong role).\n *   - `PrivilegeEscalationError` — \"you are allowed to grant, but not\n *     with these specific permissions\" (widening attempt).\n *\n * Under the admin model the grantee of an admin-grants-admin call\n * inherits the caller's entire DEK set by construction, so this error\n * is structurally unreachable in typical flows. The check and error\n * class exist so that future per-collection admin scoping cannot\n * accidentally bypass the subset rule — the guard is already wired in.\n *\n * `offendingCollection` carries the first collection name that failed\n * the subset check, to make the violation actionable in error output.\n */\n/**\n * Thrown when a caller invokes an API that requires an optional\n * store capability the active store does not implement.\n *\n * Today the only call site is `Noydb.listAccessibleVaults()`,\n * which depends on the optional `NoydbStore.listVaults()`\n * method. The error message names the missing method and the calling\n * API so consumers know exactly which combination is unsupported,\n * and the `capability` field is machine-readable so library code can\n * pattern-match in catch blocks (e.g. fall back to a candidate-list\n * shape).\n *\n * The class lives in `errors.ts` rather than as a generic\n * `ValidationError` because the diagnostic shape is different: a\n * `ValidationError` says \"the inputs you passed are wrong\"; this\n * error says \"the inputs are fine, but the store you wired up\n * doesn't support what you're asking for.\" Different fix, different\n * documentation.\n */\nexport class StoreCapabilityError extends NoydbError {\n  /** The store method/capability that was missing. */\n  readonly capability: string\n\n  constructor(capability: string, callerApi: string, storeName?: string) {\n    super(\n      'STORE_CAPABILITY',\n      `${callerApi} requires the optional store capability \"${capability}\" ` +\n        `but the active store${storeName ? ` (${storeName})` : ''} does not implement it. ` +\n        `Use a store that supports \"${capability}\" (store-memory, store-file) or pass an explicit ` +\n        `vault list to bypass enumeration.`,\n    )\n    this.name = 'StoreCapabilityError'\n    this.capability = capability\n  }\n}\n\nexport class PrivilegeEscalationError extends NoydbError {\n  readonly offendingCollection: string\n\n  constructor(offendingCollection: string, message?: string) {\n    super(\n      'PRIVILEGE_ESCALATION',\n      message ??\n        `Privilege escalation: grantor has no DEK for collection \"${offendingCollection}\" and cannot grant access to it.`,\n    )\n    this.name = 'PrivilegeEscalationError'\n    this.offendingCollection = offendingCollection\n  }\n}\n\n/**\n * Thrown by `Collection.put` / `.delete` when the target record's\n * envelope `_ts` falls within a closed accounting period.\n *\n * Distinct from `ReadOnlyError` (keyring-level), `ReadOnlyAtInstantError`\n * (historical view), and `ReadOnlyFrameError` (shadow vault): this\n * error is about the STORED RECORD being sealed by an operator call\n * to `vault.closePeriod()`, independent of caller permissions or\n * view type. The `periodName` and `endDate` fields name the sealing\n * period so audit UIs can surface a \"this record is locked in\n * FY2026-Q1 (closed 2026-03-31)\" message without parsing the error\n * string.\n *\n * To apply a correction after close, book a compensating entry in a\n * new period rather than unlocking the old one. Re-opening a closed\n * period is deliberately unsupported.\n */\nexport class PeriodClosedError extends NoydbError {\n  readonly periodName: string\n  readonly endDate: string\n  readonly recordTs: string\n\n  constructor(periodName: string, endDate: string, recordTs: string) {\n    super(\n      'PERIOD_CLOSED',\n      `Cannot modify record (last written ${recordTs}) — sealed by closed period ` +\n        `\"${periodName}\" (endDate: ${endDate}). Post a compensating entry in a ` +\n        `new period instead.`,\n    )\n    this.name = 'PeriodClosedError'\n    this.periodName = periodName\n    this.endDate = endDate\n    this.recordTs = recordTs\n  }\n}\n\n// ─── Hierarchical Access Errors ─────────────────────\n\n/**\n * Thrown when a user tries to act at a tier they are not cleared for.\n *\n * This is the umbrella error for tier write refusals:\n *   - `put({ tier: N })` when the user's keyring lacks tier-N DEK.\n *   - `elevate(id, N)` when the caller cannot reach tier N.\n *\n * Distinct from `TierAccessDeniedError` which covers *read* refusals on\n * the invisibility/ghost path.\n */\nexport class TierNotGrantedError extends NoydbError {\n  readonly tier: number\n  readonly collection: string\n\n  constructor(collection: string, tier: number) {\n    super(\n      'TIER_NOT_GRANTED',\n      `User has no DEK for tier ${tier} in collection \"${collection}\"`,\n    )\n    this.name = 'TierNotGrantedError'\n    this.collection = collection\n    this.tier = tier\n  }\n}\n\n/**\n * Thrown when an elevated-handle operation runs after the elevation's\n * TTL expired. Reads continue at the original tier; only writes\n * through the scoped handle flip to throwing once expired.\n */\nexport class ElevationExpiredError extends NoydbError {\n  readonly tier: number\n  readonly expiresAt: number\n\n  constructor(opts: { tier: number; expiresAt: number }) {\n    super(\n      'ELEVATION_EXPIRED',\n      `Elevation to tier ${opts.tier} expired at ${new Date(opts.expiresAt).toISOString()}`,\n    )\n    this.name = 'ElevationExpiredError'\n    this.tier = opts.tier\n    this.expiresAt = opts.expiresAt\n  }\n}\n\n/**\n * Thrown by `vault.elevate(...)` when an elevation is already active\n * on the vault. Adopters must `release()` the existing handle before\n * starting a new elevation.\n */\nexport class AlreadyElevatedError extends NoydbError {\n  readonly activeTier: number\n\n  constructor(activeTier: number) {\n    super(\n      'ALREADY_ELEVATED',\n      `Vault is already elevated to tier ${activeTier}; release the existing handle first`,\n    )\n    this.name = 'AlreadyElevatedError'\n    this.activeTier = activeTier\n  }\n}\n\n/**\n * Thrown when `demote()` is called by someone who is not the original\n * elevator and not an owner.\n */\nexport class TierDemoteDeniedError extends NoydbError {\n  constructor(id: string, tier: number) {\n    super(\n      'TIER_DEMOTE_DENIED',\n      `Only the original elevator or an owner can demote record \"${id}\" from tier ${tier}`,\n    )\n    this.name = 'TierDemoteDeniedError'\n  }\n}\n\n/**\n * Thrown when `db.delegate()` is called against a user that has no\n * keyring in the target vault — the delegation token cannot be\n * constructed without the target user's KEK wrap.\n */\nexport class DelegationTargetMissingError extends NoydbError {\n  readonly toUser: string\n\n  constructor(toUser: string) {\n    super(\n      'DELEGATION_TARGET_MISSING',\n      `Delegation target user \"${toUser}\" has no keyring in this vault`,\n    )\n    this.name = 'DelegationTargetMissingError'\n    this.toUser = toUser\n  }\n}\n\n// ─── Sync Errors ───────────────────────────────────────────────────────\n\n/**\n * Thrown when a `put()` detects an optimistic concurrency conflict.\n *\n * NOYDB uses version numbers (`_v`) for optimistic locking. If a `put()`\n * is called with `expectedVersion: N` but the stored record is at version\n * `M ≠ N`, the write is rejected and the caller must re-read, re-apply their\n * change, and retry. The `version` field carries the actual stored version\n * so callers can decide whether to retry or surface the conflict to the user.\n */\nexport class ConflictError extends NoydbError {\n  /** The actual stored version at the time of conflict. */\n  readonly version: number\n\n  constructor(version: number, message = 'Version conflict') {\n    super('CONFLICT', message)\n    this.name = 'ConflictError'\n    this.version = version\n  }\n}\n\n/**\n * Thrown by `LedgerStore.append()` after exhausting its CAS retry\n * budget under multi-writer contention. Two browser tabs, a\n * web app + an offline mobile peer, or a server worker pool all\n * producing ledger entries against the same vault can race on the\n * \"read head, write head+1\" cycle; the optimistic-CAS retry loop\n * resolves the race for `casAtomic: true` stores, but pathological\n * contention (or a buggy peer) can still exhaust the budget. When\n * that happens, the chain is intact — the failed writer simply\n * couldn't claim a slot. Caller's choice whether to retry, queue,\n * or surface the failure to the user.\n */\nexport class LedgerContentionError extends NoydbError {\n  readonly attempts: number\n\n  constructor(attempts: number) {\n    super(\n      'LEDGER_CONTENTION',\n      `LedgerStore.append: failed to claim a chain slot after ${attempts} optimistic-CAS retries`,\n    )\n    this.name = 'LedgerContentionError'\n    this.attempts = attempts\n  }\n}\n\n/**\n * Thrown when a bundle push is rejected because the remote has been updated\n * since the local bundle was last pulled.\n *\n * Unlike `ConflictError` (per-record), this is a whole-bundle conflict —\n * the remote's bundle handle has changed. The caller must pull the new\n * bundle, merge, and re-push. `remoteVersion` is the handle of the newer\n * remote bundle for use in diagnostics.\n */\nexport class BundleVersionConflictError extends NoydbError {\n  /** The bundle handle of the newer remote version that rejected the push. */\n  readonly remoteVersion: string\n\n  constructor(remoteVersion: string, message = 'Bundle version conflict — remote has been updated') {\n    super('BUNDLE_VERSION_CONFLICT', message)\n    this.name = 'BundleVersionConflictError'\n    this.remoteVersion = remoteVersion\n  }\n}\n\n/**\n * Thrown when a sync operation (push or pull) fails due to a network error.\n *\n * NOYDB's offline-first design means network errors are expected during sync.\n * Callers should catch `NetworkError`, surface connectivity status in the UI,\n * and rely on the `SyncScheduler` to retry when connectivity is restored.\n */\nexport class NetworkError extends NoydbError {\n  constructor(message = 'Network error') {\n    super('NETWORK_ERROR', message)\n    this.name = 'NetworkError'\n  }\n}\n\n// ─── Data Errors ───────────────────────────────────────────────────────\n\n/**\n * Thrown when `collection.get(id)` is called with an ID that does not exist.\n *\n * NOYDB collections are memory-first, so this error is synchronous and cheap —\n * it does not make a network round-trip. Callers that expect the record to be\n * absent should use `collection.getOrNull(id)` instead.\n */\nexport class NotFoundError extends NoydbError {\n  constructor(message = 'Record not found') {\n    super('NOT_FOUND', message)\n    this.name = 'NotFoundError'\n  }\n}\n\n/**\n * Thrown when application-level validation fails before encryption.\n *\n * Distinct from `SchemaValidationError` (Standard Schema v1 validator)\n * and `MissingTranslationError` (i18nText). `ValidationError` is the\n * general-purpose validation base — use it for custom guards in `put()`\n * hooks or store middleware.\n */\nexport class ValidationError extends NoydbError {\n  constructor(message = 'Validation error') {\n    super('VALIDATION_ERROR', message)\n    this.name = 'ValidationError'\n  }\n}\n\n/**\n * Thrown when a Standard Schema v1 validator rejects a record on\n * `put()` (input validation) or on read (output validation). Carries\n * the raw issue list so callers can render field-level errors.\n *\n * `direction` distinguishes the two cases:\n *   - `'input'`: the user passed bad data into `put()`. This is a\n *     normal error case that application code should handle — typically\n *     by showing validation messages in the UI.\n *   - `'output'`: stored data does not match the current schema. This\n *     indicates a schema drift (the schema was changed without\n *     migrating the existing records) and should be treated as a bug\n *     — the application should not swallow it silently.\n *\n * The `issues` type is deliberately `readonly unknown[]` on this class\n * so that `errors.ts` doesn't need to import from `schema.ts` (and\n * create a dependency cycle). Callers who know they're holding a\n * `SchemaValidationError` can cast to the more precise\n * `readonly StandardSchemaV1Issue[]` from `schema.ts`.\n */\nexport class SchemaValidationError extends NoydbError {\n  readonly issues: readonly unknown[]\n  readonly direction: 'input' | 'output'\n\n  constructor(\n    message: string,\n    issues: readonly unknown[],\n    direction: 'input' | 'output',\n  ) {\n    super('SCHEMA_VALIDATION_FAILED', message)\n    this.name = 'SchemaValidationError'\n    this.issues = issues\n    this.direction = direction\n  }\n}\n\n// ─── Query DSL Errors ─────────────────────────────────────────────────\n\n/**\n * Thrown when `.groupBy().aggregate()` produces more than the hard\n * cardinality cap (default 100_000 groups)..\n *\n * The cap exists because `.groupBy()` materializes one bucket per\n * distinct key value in memory, and runaway cardinality — a groupBy\n * on a high-uniqueness field like `id` or `createdAt` — is almost\n * always a query mistake rather than legitimate use. A hard error is\n * better than silent OOM: the consumer sees an actionable message\n * naming the field and the observed cardinality, with guidance to\n * either narrow the query with `.where()` or accept the ceiling\n * override.\n *\n * A separate one-shot warning fires at 10% of the cap (10_000\n * groups) so consumers get a heads-up before the hard error — same\n * pattern as `JoinTooLargeError` and the `.join()` row ceiling.\n *\n * **Not overridable in.** The 100k cap is a fixed constant so\n * the failure mode is consistent across the codebase; a\n * `{ maxGroups }` override can be added later without a break if a\n * real consumer asks.\n */\nexport class GroupCardinalityError extends NoydbError {\n  /** The field being grouped on. */\n  readonly field: string\n  /** Observed number of distinct groups at the moment the cap tripped. */\n  readonly cardinality: number\n  /** The cap that was exceeded. */\n  readonly maxGroups: number\n\n  constructor(field: string, cardinality: number, maxGroups: number) {\n    super(\n      'GROUP_CARDINALITY',\n      `.groupBy(\"${field}\") produced ${cardinality} distinct groups, ` +\n        `exceeding the ${maxGroups}-group ceiling. This is almost always a ` +\n        `query mistake — grouping on a high-uniqueness field like \"id\" or ` +\n        `\"createdAt\" produces one bucket per record. Narrow the query with ` +\n        `.where() before grouping, or group on a lower-cardinality field ` +\n        `(status, category, clientId). If you genuinely need high-cardinality ` +\n        `grouping, file an issue with your use case.`,\n    )\n    this.name = 'GroupCardinalityError'\n    this.field = field\n    this.cardinality = cardinality\n    this.maxGroups = maxGroups\n  }\n}\n\n/**\n * Thrown in lazy mode when a `.query()` / `.where()` / `.orderBy()` clause\n * references a field that does not have a declared index.\n *\n * Lazy-mode queries only work when every touched field is indexed.\n * This is deliberate — silent scan-fallback would hide the performance\n * cliff that lazy-mode indexes exist to prevent.\n *\n * Payload:\n * - `collection` — name of the collection queried\n * - `touchedFields` — every field referenced by the query (filter + order)\n * - `missingFields` — subset of `touchedFields` that have no declared index\n */\nexport class IndexRequiredError extends NoydbError {\n  readonly collection: string\n  readonly touchedFields: readonly string[]\n  readonly missingFields: readonly string[]\n\n  constructor(args: { collection: string; touchedFields: readonly string[]; missingFields: readonly string[] }) {\n    super(\n      'INDEX_REQUIRED',\n      `Collection \"${args.collection}\": query references unindexed fields in lazy mode ` +\n      `(missing: ${args.missingFields.join(', ')}). ` +\n      `Declare an index on each field, or use collection.scan() for non-indexed iteration.`,\n    )\n    this.name = 'IndexRequiredError'\n    this.collection = args.collection\n    this.touchedFields = [...args.touchedFields]\n    this.missingFields = [...args.missingFields]\n  }\n}\n\n/**\n * Thrown (or surfaced via the `index:write-partial` event) when one or more\n * per-indexed-field side-car writes fail after the main record write has\n * already succeeded.\n *\n * Not thrown out of `.put()` / `.delete()` directly — those succeed when the\n * main record succeeds. Instead, `IndexWriteFailureError` instances are collected\n * into the session-scoped reconcile queue and emitted on the Collection\n * emitter as `index:write-partial`.\n *\n * Payload:\n * - `recordId` — the id of the main record whose side-car writes failed\n * - `field` — the indexed field whose side-car write failed\n * - `op` — `'put'` or `'delete'`, indicating which mutation was in flight\n * - `cause` — the underlying error from the store\n */\nexport class IndexWriteFailureError extends NoydbError {\n  readonly recordId: string\n  readonly field: string\n  readonly op: 'put' | 'delete'\n  override readonly cause: unknown\n\n  constructor(args: { recordId: string; field: string; op: 'put' | 'delete'; cause: unknown }) {\n    super(\n      'INDEX_WRITE_FAILURE',\n      `Index side-car ${args.op} failed for field \"${args.field}\" on record \"${args.recordId}\"`,\n    )\n    this.name = 'IndexWriteFailureError'\n    this.recordId = args.recordId\n    this.field = args.field\n    this.op = args.op\n    this.cause = args.cause\n  }\n}\n\n// ─── Bundle Format Errors ─────────────────────────────────\n\n/**\n * Thrown by `readNoydbBundle()` when the body bytes don't match\n * the integrity hash declared in the bundle header — i.e. someone\n * modified the bytes between write and read.\n *\n * Distinct from a generic `Error` (which would be thrown for\n * format violations like a missing magic prefix or malformed\n * header JSON) so consumers can pattern-match the corruption case\n * and handle it differently from a producer bug. A\n * `BundleIntegrityError` indicates \"the bytes you got are not\n * what was written\"; a plain `Error` from `parsePrefixAndHeader`\n * indicates \"what was written wasn't a valid bundle in the first\n * place.\"\n *\n * Also thrown when decompression fails after the integrity hash\n * passed — that's a producer bug (the wrong algorithm byte was\n * written) but it surfaces with the same error class because the\n * end result is \"the body cannot be turned back into a dump.\"\n */\nexport class BundleIntegrityError extends NoydbError {\n  constructor(message: string) {\n    super('BUNDLE_INTEGRITY', `.noydb bundle integrity check failed: ${message}`)\n    this.name = 'BundleIntegrityError'\n  }\n}\n\n// ─── i18n / Dictionary Errors ──────────────────────────\n\n/**\n * Thrown when `vault.collection()` is called with a name that is\n * reserved for NOYDB internal use (any name starting with `_dict_`).\n *\n * Dictionary collections are accessed exclusively via\n * `vault.dictionary(name)` — attempting to open one as a regular\n * collection would bypass the dictionary invariants (ACL, rename\n * tracking, reserved-name policy).\n */\nexport class ReservedCollectionNameError extends NoydbError {\n  /** The rejected collection name. */\n  readonly collectionName: string\n\n  constructor(collectionName: string) {\n    super(\n      'RESERVED_COLLECTION_NAME',\n      `\"${collectionName}\" is a reserved collection name. ` +\n        `Use vault.dictionary(\"${collectionName.replace(/^_dict_/, '')}\") ` +\n        `to access dictionary collections.`,\n    )\n    this.name = 'ReservedCollectionNameError'\n    this.collectionName = collectionName\n  }\n}\n\n/**\n * Thrown by `DictionaryHandle.get()` and `DictionaryHandle.delete()` when\n * the requested key does not exist in the dictionary.\n *\n * Distinct from `NotFoundError` (which is for data records) so callers\n * can distinguish \"data record missing\" from \"dictionary key missing\"\n * without inspecting error messages.\n */\nexport class DictKeyMissingError extends NoydbError {\n  /** The dictionary name. */\n  readonly dictionaryName: string\n  /** The key that was not found. */\n  readonly key: string\n\n  constructor(dictionaryName: string, key: string) {\n    super(\n      'DICT_KEY_MISSING',\n      `Dictionary \"${dictionaryName}\" has no entry for key \"${key}\".`,\n    )\n    this.name = 'DictKeyMissingError'\n    this.dictionaryName = dictionaryName\n    this.key = key\n  }\n}\n\n/**\n * Thrown by `DictionaryHandle.delete()` in strict mode when the key to\n * be deleted is still referenced by one or more records.\n *\n * The caller must either rename the key first (the only sanctioned\n * mass-mutation path) or pass `{ mode: 'warn' }` to skip the check\n * (development only).\n */\nexport class DictKeyInUseError extends NoydbError {\n  /** The dictionary name. */\n  readonly dictionaryName: string\n  /** The key that is still referenced. */\n  readonly key: string\n  /** Name of the first collection found to reference this key. */\n  readonly usedBy: string\n  /** Number of records in `usedBy` that reference this key. */\n  readonly count: number\n\n  constructor(\n    dictionaryName: string,\n    key: string,\n    usedBy: string,\n    count: number,\n  ) {\n    super(\n      'DICT_KEY_IN_USE',\n      `Cannot delete key \"${key}\" from dictionary \"${dictionaryName}\": ` +\n        `${count} record(s) in \"${usedBy}\" still reference it. ` +\n        `Use dictionary.rename(\"${key}\", newKey) to rewrite references first.`,\n    )\n    this.name = 'DictKeyInUseError'\n    this.dictionaryName = dictionaryName\n    this.key = key\n    this.usedBy = usedBy\n    this.count = count\n  }\n}\n\n/**\n * Thrown by `Collection.put()` when an `i18nText` field is missing one\n * or more required translations.\n *\n * The `missing` array names each locale code that was absent from the\n * field value. The `field` property names the field so callers can\n * render a field-level error message without parsing the string.\n */\nexport class MissingTranslationError extends NoydbError {\n  /** The field name whose translation(s) are missing. */\n  readonly field: string\n  /** Locale codes that were required but absent. */\n  readonly missing: readonly string[]\n\n  constructor(field: string, missing: readonly string[], message?: string) {\n    super(\n      'MISSING_TRANSLATION',\n      message ??\n        `Field \"${field}\": missing required translation(s): ${missing.join(', ')}.`,\n    )\n    this.name = 'MissingTranslationError'\n    this.field = field\n    this.missing = missing\n  }\n}\n\n/**\n * Thrown when reading an `i18nText` field without specifying a locale —\n * either at the call site (`get(id, { locale })`) or on the vault\n * (`openVault(name, { locale })`).\n *\n * Also thrown when `resolveI18nText()` exhausts the fallback chain and\n * no translation is available for the requested locale.\n *\n * The `field` property names the field that triggered the error so the\n * caller can surface it in the UI.\n */\nexport class LocaleNotSpecifiedError extends NoydbError {\n  /** The field name that required a locale. */\n  readonly field: string\n\n  constructor(field: string, message?: string) {\n    super(\n      'LOCALE_NOT_SPECIFIED',\n      message ??\n        `Cannot read i18nText field \"${field}\" without a locale. ` +\n        `Pass { locale } to get()/list()/query() or set a default via ` +\n        `openVault(name, { locale }).`,\n    )\n    this.name = 'LocaleNotSpecifiedError'\n    this.field = field\n  }\n}\n\n// ─── Translator Errors ─────────────────────────────────────\n\n/**\n * Thrown when a collection has an `i18nText` field with\n * `autoTranslate: true` but no `plaintextTranslator` was configured\n * on `createNoydb()`.\n *\n * The error is raised at `put()` time (not at schema construction) so\n * the mis-configuration is surfaced by the first write rather than\n * silently at startup.\n */\nexport class TranslatorNotConfiguredError extends NoydbError {\n  /** The field that requested auto-translation. */\n  readonly field: string\n  /** The collection the put was targeting. */\n  readonly collection: string\n\n  constructor(field: string, collection: string) {\n    super(\n      'TRANSLATOR_NOT_CONFIGURED',\n      `Field \"${field}\" in collection \"${collection}\" has autoTranslate: true, ` +\n        `but no plaintextTranslator was configured on createNoydb(). ` +\n        `Either configure a plaintextTranslator or remove autoTranslate from the schema.`,\n    )\n    this.name = 'TranslatorNotConfiguredError'\n    this.field = field\n    this.collection = collection\n  }\n}\n\n// ─── Backup Errors ─────────────────────────────────────────\n\n/**\n * Thrown when `Vault.load()` finds that a backup's hash chain\n * doesn't verify, or that its embedded `ledgerHead.hash` doesn't\n * match the chain head reconstructed from the loaded entries.\n *\n * Distinct from `BackupCorruptedError` so callers can choose to\n * recover from one but not the other (e.g., a corrupted JSON file is\n * unrecoverable; a chain mismatch might mean the backup is from an\n * incompatible noy-db version).\n */\nexport class BackupLedgerError extends NoydbError {\n  /** First-broken-entry index, if known. */\n  readonly divergedAt?: number\n\n  constructor(message: string, divergedAt?: number) {\n    super('BACKUP_LEDGER', message)\n    this.name = 'BackupLedgerError'\n    if (divergedAt !== undefined) this.divergedAt = divergedAt\n  }\n}\n\n/**\n * Thrown when `Vault.load()` finds that the backup's data\n * collection content doesn't match the ledger's recorded\n * `payloadHash`es. This is the \"envelope was tampered with after\n * dump\" detection — the chain itself can be intact, but if any\n * encrypted record bytes were swapped, this check catches it.\n */\nexport class BackupCorruptedError extends NoydbError {\n  /** The (collection, id) pair whose envelope failed the hash check. */\n  readonly collection: string\n  readonly id: string\n\n  constructor(collection: string, id: string, message: string) {\n    super('BACKUP_CORRUPTED', message)\n    this.name = 'BackupCorruptedError'\n    this.collection = collection\n    this.id = id\n  }\n}\n\n// ─── Session Errors ───────────────────────────────────────\n\n/**\n * Thrown by `resolveSession()` when the session token's `expiresAt`\n * timestamp is in the past. The session key is also removed from the\n * in-memory store when this is thrown, so retrying with the same sessionId\n * will produce `SessionNotFoundError`.\n *\n * Separate from `SessionNotFoundError` so callers can distinguish between\n * \"session is gone\" (key store cleared, tab reloaded) and \"session is\n * still in the store but has exceeded its lifetime\" (idle timeout, absolute\n * timeout, policy-driven expiry). The remediation differs: expired sessions\n * should prompt a fresh unlock; not-found sessions may indicate a bug or a\n * cross-tab scenario where the session was never established.\n */\nexport class SessionExpiredError extends NoydbError {\n  readonly sessionId: string\n\n  constructor(sessionId: string) {\n    super('SESSION_EXPIRED', `Session \"${sessionId}\" has expired. Re-unlock to continue.`)\n    this.name = 'SessionExpiredError'\n    this.sessionId = sessionId\n  }\n}\n\n/**\n * Thrown by `resolveSession()` when the session key cannot be found in\n * the module-level store. This happens when:\n *   - The session was explicitly revoked via `revokeSession()`.\n *   - The JS context was reloaded (tab navigation, page refresh, worker restart).\n *   - `Noydb.close()` was called (which calls `revokeAllSessions()`).\n *   - The sessionId is wrong or was generated by a different JS context.\n *\n * The session token (if the caller holds it) is permanently useless after\n * this error — the key is gone and cannot be recovered.\n */\nexport class SessionNotFoundError extends NoydbError {\n  readonly sessionId: string\n\n  constructor(sessionId: string) {\n    super('SESSION_NOT_FOUND', `Session key for \"${sessionId}\" not found. The session may have been revoked or the page reloaded.`)\n    this.name = 'SessionNotFoundError'\n    this.sessionId = sessionId\n  }\n}\n\n/**\n * Thrown when a session policy blocks an operation — for example,\n * `requireReAuthFor: ['export']` is set and the caller attempts to\n * call `exportStream()` without re-authenticating for this session.\n *\n * The `operation` field names the specific operation that was blocked\n * (e.g. `'export'`, `'grant'`, `'rotate'`) so the caller can surface\n * a targeted prompt (\"Please re-enter your passphrase to export data\").\n */\nexport class SessionPolicyError extends NoydbError {\n  readonly operation: string\n\n  constructor(operation: string, message?: string) {\n    super(\n      'SESSION_POLICY',\n      message ?? `Operation \"${operation}\" requires re-authentication per the active session policy.`,\n    )\n    this.name = 'SessionPolicyError'\n    this.operation = operation\n  }\n}\n\n// ─── Query / Join Errors ────────────────────────────────────\n\n/**\n * Thrown when a `.join()` would exceed its configured row ceiling on\n * either side. The ceiling defaults to 50,000 per side and can be\n * overridden via the `{ maxRows }` option on `.join()`.\n *\n * Carries both row counts so the error message can show which side\n * tripped the limit (e.g. \"left had 60,000 rows, right had 1,200,\n * max was 50,000\"). The `side` field is machine-readable so test\n * code and devtools can match on it without regex-parsing the\n * message.\n *\n * The row ceiling exists because joins are bounded in-memory\n * operations over materialized record sets. Consumers whose\n * collections genuinely exceed the ceiling should track \n * (streaming joins over `scan()`) or filter the left side further\n * with `where()` / `limit()` before joining.\n */\nexport class JoinTooLargeError extends NoydbError {\n  readonly leftRows: number\n  readonly rightRows: number\n  readonly maxRows: number\n  readonly side: 'left' | 'right'\n\n  constructor(opts: {\n    leftRows: number\n    rightRows: number\n    maxRows: number\n    side: 'left' | 'right'\n    message: string\n  }) {\n    super('JOIN_TOO_LARGE', opts.message)\n    this.name = 'JoinTooLargeError'\n    this.leftRows = opts.leftRows\n    this.rightRows = opts.rightRows\n    this.maxRows = opts.maxRows\n    this.side = opts.side\n  }\n}\n\n/**\n * Thrown by `.join()` in strict `ref()` mode when a left-side record\n * points at a right-side id that does not exist in the target\n * collection.\n *\n * Distinct from `RefIntegrityError` so test code can pattern-match\n * on the *read-time* dangling case without catching *write-time*\n * integrity violations. Both indicate \"ref points at nothing\" but\n * happen at different lifecycle phases and deserve different\n * remediation in documentation: a RefIntegrityError on `put()`\n * means the input is invalid; a DanglingReferenceError on `.join()`\n * means stored data has drifted and `vault.checkIntegrity()`\n * is the right tool to find the full set of orphans.\n */\nexport class DanglingReferenceError extends NoydbError {\n  readonly field: string\n  readonly target: string\n  readonly refId: string\n\n  constructor(opts: {\n    field: string\n    target: string\n    refId: string\n    message: string\n  }) {\n    super('DANGLING_REFERENCE', opts.message)\n    this.name = 'DanglingReferenceError'\n    this.field = opts.field\n    this.target = opts.target\n    this.refId = opts.refId\n  }\n}\n\n/**\n * Thrown by {@link sanitizeFilename} when an input filename cannot be\n * made safe — NUL byte, empty after normalization, missing\n * `opaqueId` for the opaque profile, `..` segment, or a `maxBytes`\n * cap too small to hold a single code point.\n */\nexport class FilenameSanitizationError extends NoydbError {\n  constructor(message: string) {\n    super('FILENAME_SANITIZATION', message)\n    this.name = 'FilenameSanitizationError'\n  }\n}\n\n/**\n * Thrown when a write target resolves OUTSIDE the requested\n * directory after sanitization — the canonical Zip-Slip class. The\n * sanitizer's job is to strip path-traversal segments; this error\n * is the defense-in-depth fallback at the FS write site.\n */\nexport class PathEscapeError extends NoydbError {\n  readonly attempted: string\n  readonly targetDir: string\n\n  constructor(opts: { attempted: string; targetDir: string }) {\n    super(\n      'PATH_ESCAPE',\n      `Sanitized filename \"${opts.attempted}\" resolves outside target dir \"${opts.targetDir}\"`,\n    )\n    this.name = 'PathEscapeError'\n    this.attempted = opts.attempted\n    this.targetDir = opts.targetDir\n  }\n}\n","/**\n * Target-profile aware filename sanitizer.\n *\n * Pure string in / string out. No filesystem access, no I/O. Use this\n * at the boundary where a user-supplied filename meets a storage\n * destination — local FS, ZIP archive, S3 key, URL path, SMB share —\n * to defuse the canonical 14-class footgun before it reaches that\n * destination.\n *\n * ## Threat model\n *\n *   1. Path injection — `..`, NUL bytes, `\\` on POSIX, absolute paths.\n *   2. Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`,\n *      `COM1-9`, `LPT1-9`, with or without an extension.\n *   3. Windows reserved chars — `< > : \" / \\ | ? *` plus ASCII 0-31.\n *   4. Trailing `.` and ` ` on Windows / SMB.\n *   5. Unicode normalization drift — same display, different bytes →\n *      \"two files with the same name\" sync ghosts.\n *   6. Bidi override spoofing — U+202E reversing `harmless.exe.txt`\n *      into `harmless.txt.exe`.\n *   7. URL `+` ambiguity in S3 presigned URLs.\n *   8. ZIP general-purpose-flag bit 11 (UTF-8 filename) optional in\n *      pre-2006 readers.\n *   9-14. Length caps, leading/trailing whitespace + controls,\n *      `.DS_Store`-style hidden noise, etc.\n *\n * ## Always-on transforms (every profile)\n *\n *   - NFC normalize (`String.prototype.normalize('NFC')`).\n *   - Reject NUL — hard fail, not strip. Silent strip enables a\n *     classic truncation bypass (`safe.txt\\0.exe` → `safe.txt`).\n *   - Strip bidi overrides (`U+202A..U+202E`, `U+2066..U+2069`).\n *   - Trim leading/trailing whitespace and ASCII control chars.\n *\n * ## Non-goals (i18n boundary policy, )\n *\n *   - No transliteration.\n *   - No locale-aware slugging.\n *   - No script-specific segmentation.\n *\n * @module\n */\n\nimport { FilenameSanitizationError } from '../errors.js'\n\n/**\n * One of seven storage destinations the sanitizer knows how to defang\n * for. Pick the most restrictive that covers your write site:\n * `'macos-smb'` is the safe default for \"I don't know where these\n * files end up but they're going to a real filesystem somewhere.\"\n */\nexport type FilenameProfile =\n  | 'posix'\n  | 'windows'\n  | 'macos-smb'\n  | 'zip'\n  | 'url-path'\n  | 's3-key'\n  | 'opaque'\n\nexport interface SanitizeFilenameOptions {\n  /** Target-destination profile. */\n  readonly profile: FilenameProfile\n  /**\n   * Override the per-profile length cap. Useful when leaving headroom\n   * for a collision suffix — e.g. `maxBytes: 240` on a `posix` write\n   * site that wants 15 bytes of slack for `-1`, `-2`, …\n   */\n  readonly maxBytes?: number\n  /**\n   * Required when `profile === 'opaque'`. The opaque profile replaces\n   * the entire input with `${opaqueId}.${ext}` (extension preserved\n   * from the input when present).\n   */\n  readonly opaqueId?: string\n}\n\nconst REPLACEMENT = '_'\n\n// Bidi overrides: U+202A LRE, U+202B RLE, U+202C PDF, U+202D LRO,\n// U+202E RLO, U+2066 LRI, U+2067 RLI, U+2068 FSI, U+2069 PDI.\nconst BIDI_OVERRIDES = /[‪-‮⁦-⁩]/g\n\n// Reserved by Windows / NTFS / FAT / SMB.\nconst WINDOWS_RESERVED_CHARS = /[<>:\"/\\\\|?*]/g\n\nconst WINDOWS_RESERVED_NAMES = new Set([\n  'CON', 'PRN', 'AUX', 'NUL',\n  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',\n  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',\n])\n\n// macOS legacy hidden-noise files. Match the full name.\nconst MAC_HIDDEN_NOISE = /^(?:\\.DS_Store|\\.localized|\\.fseventsd|\\._.+)$/i\n\n// RFC 3986 unreserved set.\nconst URL_UNRESERVED = /[A-Za-z0-9\\-._~]/\n\nconst utf8 = new TextEncoder()\n\nfunction isControlCode(cp: number): boolean {\n  return (cp >= 0 && cp <= 0x1f) || cp === 0x7f\n}\n\nfunction stripControlChars(s: string): string {\n  let out = ''\n  for (let i = 0; i < s.length; i++) {\n    out += isControlCode(s.charCodeAt(i)) ? REPLACEMENT : s[i]\n  }\n  return out\n}\n\nfunction trimWhitespaceAndControls(s: string): string {\n  let start = 0\n  let end = s.length\n  while (start < end) {\n    const ch = s[start]!\n    if (!isControlCode(s.charCodeAt(start)) && ch.trim() !== '') break\n    start++\n  }\n  while (end > start) {\n    const ch = s[end - 1]!\n    if (!isControlCode(s.charCodeAt(end - 1)) && ch.trim() !== '') break\n    end--\n  }\n  return s.slice(start, end)\n}\n\n/**\n * Sanitize a filename for a target-destination profile. Pure: same\n * input + options always returns the same output, no I/O.\n *\n * Returns the sanitized name. Throws {@link FilenameSanitizationError}\n * when the input cannot be made safe at all (NUL byte, empty after\n * normalization, missing `opaqueId` for the opaque profile,\n * `..` segment that would fall out of any reasonable target).\n */\nexport function sanitizeFilename(name: string, opts: SanitizeFilenameOptions): string {\n  if (typeof name !== 'string') {\n    throw new FilenameSanitizationError('input must be a string')\n  }\n  if (name.includes('\\0')) {\n    throw new FilenameSanitizationError('NUL byte in filename')\n  }\n\n  let s = name.normalize('NFC').replace(BIDI_OVERRIDES, '')\n\n  if (opts.profile === 'opaque') {\n    return applyOpaque(s, opts)\n  }\n\n  s = trimWhitespaceAndControls(s)\n\n  switch (opts.profile) {\n    case 'posix':     return cap(applyPosix(s),     opts.maxBytes ?? 255,  'utf8')\n    case 'windows':   return cap(applyWindows(s),   opts.maxBytes ?? 255,  'utf16')\n    case 'macos-smb': return cap(applyMacosSmb(s),  opts.maxBytes ?? 240,  'utf8')\n    case 'zip':       return cap(applyZip(s),       opts.maxBytes ?? 255,  'utf8')\n    case 'url-path':  return cap(applyUrlPath(s),   opts.maxBytes ?? 1024, 'bytes-pre-encode')\n    case 's3-key':    return cap(applyS3Key(s),     opts.maxBytes ?? 1024, 'utf8')\n  }\n}\n\n// ─── Profile implementations ────────────────────────────────────────────\n\nfunction applyPosix(s: string): string {\n  // POSIX is permissive; only `/` and NUL are off-limits.\n  const cleaned = s.replace(/\\//g, REPLACEMENT)\n  return rejectDotSegments(cleaned)\n}\n\nfunction applyWindows(s: string): string {\n  let cleaned = s.replace(WINDOWS_RESERVED_CHARS, REPLACEMENT)\n  cleaned = stripControlChars(cleaned)\n  // Trailing space/dot are stripped by Win32 path resolution.\n  cleaned = cleaned.replace(/[. ]+$/g, '')\n  cleaned = rejectDotSegments(cleaned)\n  return avoidWindowsReservedName(cleaned)\n}\n\nfunction applyMacosSmb(s: string): string {\n  let cleaned = applyWindows(s)\n  if (MAC_HIDDEN_NOISE.test(cleaned)) {\n    cleaned = REPLACEMENT + cleaned\n  }\n  return cleaned\n}\n\nfunction applyZip(s: string): string {\n  let cleaned = s.replace(/^\\/+/, '')\n  cleaned = rejectDotSegments(cleaned)\n  return stripControlChars(cleaned)\n}\n\nfunction applyUrlPath(s: string): string {\n  // RFC 3986 percent-encoding for path segment. Keep `unreserved`,\n  // encode everything else. `+` is encoded as `%2B` because S3 and\n  // legacy servers treat raw `+` as space ambiguously.\n  let out = ''\n  for (const ch of s) {\n    if (URL_UNRESERVED.test(ch)) { out += ch; continue }\n    const bytes = utf8.encode(ch)\n    for (const b of bytes) {\n      out += '%' + b.toString(16).toUpperCase().padStart(2, '0')\n    }\n  }\n  return out\n}\n\nfunction applyS3Key(s: string): string {\n  // Strip leading slashes BEFORE percent-encoding — once `/` is\n  // encoded to `%2F` the leading-slash regex no longer matches.\n  return applyUrlPath(s.replace(/^\\/+/, ''))\n}\n\nfunction applyOpaque(s: string, opts: SanitizeFilenameOptions): string {\n  if (!opts.opaqueId) {\n    throw new FilenameSanitizationError('opaque profile requires opaqueId')\n  }\n  // Preserve a \"safe-looking\" extension only — alphanumeric, ≤16 bytes.\n  const dot = s.lastIndexOf('.')\n  if (dot > 0 && dot < s.length - 1) {\n    const ext = s.slice(dot + 1)\n    if (/^[A-Za-z0-9]{1,16}$/.test(ext)) {\n      return `${opts.opaqueId}.${ext.toLowerCase()}`\n    }\n  }\n  return opts.opaqueId\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────\n\nfunction rejectDotSegments(s: string): string {\n  if (s === '.' || s === '..' || s.split(/[/\\\\]/).some((seg) => seg === '..')) {\n    throw new FilenameSanitizationError('path traversal segment in filename')\n  }\n  if (s.length === 0) {\n    throw new FilenameSanitizationError('empty filename after sanitization')\n  }\n  return s\n}\n\nfunction avoidWindowsReservedName(s: string): string {\n  const dot = s.indexOf('.')\n  const base = dot === -1 ? s : s.slice(0, dot)\n  if (WINDOWS_RESERVED_NAMES.has(base.toUpperCase())) {\n    return REPLACEMENT + s\n  }\n  return s\n}\n\ntype LengthUnit = 'utf8' | 'utf16' | 'bytes-pre-encode'\n\nfunction cap(s: string, max: number, unit: LengthUnit): string {\n  if (max <= 0) {\n    throw new FilenameSanitizationError('maxBytes must be positive')\n  }\n  if (unit === 'utf16') {\n    if (s.length <= max) return s\n    return s.slice(0, max)\n  }\n  if (unit === 'bytes-pre-encode') {\n    if (utf8.encode(s).byteLength <= max) return s\n    return truncateToByteCap(s, max)\n  }\n  if (utf8.encode(s).byteLength <= max) return s\n  return truncateToByteCap(s, max)\n}\n\nfunction truncateToByteCap(s: string, max: number): string {\n  // Walk by code points so we never split a multi-byte sequence in\n  // the middle. Whole-grapheme handling (ZWJ-joined emoji) is a\n  // documented non-goal; we only protect against UTF-8 boundary\n  // splits here.\n  let out = ''\n  let used = 0\n  for (const cp of s) {\n    const n = utf8.encode(cp).byteLength\n    if (used + n > max) break\n    out += cp\n    used += n\n  }\n  if (out.length === 0) {\n    throw new FilenameSanitizationError('maxBytes too small for a single code point')\n  }\n  return out\n}\n"],"mappings":"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","names":[]}

package/dist/util/index.d.cts

@@ -0,0 +1,77 @@
+/**
+ * Target-profile aware filename sanitizer.
+ *
+ * Pure string in / string out. No filesystem access, no I/O. Use this
+ * at the boundary where a user-supplied filename meets a storage
+ * destination — local FS, ZIP archive, S3 key, URL path, SMB share —
+ * to defuse the canonical 14-class footgun before it reaches that
+ * destination.
+ *
+ * ## Threat model
+ *
+ *   1. Path injection — `..`, NUL bytes, `\` on POSIX, absolute paths.
+ *   2. Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`,
+ *      `COM1-9`, `LPT1-9`, with or without an extension.
+ *   3. Windows reserved chars — `< > : " / \ | ? *` plus ASCII 0-31.
+ *   4. Trailing `.` and ` ` on Windows / SMB.
+ *   5. Unicode normalization drift — same display, different bytes →
+ *      "two files with the same name" sync ghosts.
+ *   6. Bidi override spoofing — U+202E reversing `harmless.exe.txt`
+ *      into `harmless.txt.exe`.
+ *   7. URL `+` ambiguity in S3 presigned URLs.
+ *   8. ZIP general-purpose-flag bit 11 (UTF-8 filename) optional in
+ *      pre-2006 readers.
+ *   9-14. Length caps, leading/trailing whitespace + controls,
+ *      `.DS_Store`-style hidden noise, etc.
+ *
+ * ## Always-on transforms (every profile)
+ *
+ *   - NFC normalize (`String.prototype.normalize('NFC')`).
+ *   - Reject NUL — hard fail, not strip. Silent strip enables a
+ *     classic truncation bypass (`safe.txt\0.exe` → `safe.txt`).
+ *   - Strip bidi overrides (`U+202A..U+202E`, `U+2066..U+2069`).
+ *   - Trim leading/trailing whitespace and ASCII control chars.
+ *
+ * ## Non-goals (i18n boundary policy, )
+ *
+ *   - No transliteration.
+ *   - No locale-aware slugging.
+ *   - No script-specific segmentation.
+ *
+ * @module
+ */
+/**
+ * One of seven storage destinations the sanitizer knows how to defang
+ * for. Pick the most restrictive that covers your write site:
+ * `'macos-smb'` is the safe default for "I don't know where these
+ * files end up but they're going to a real filesystem somewhere."
+ */
+type FilenameProfile = 'posix' | 'windows' | 'macos-smb' | 'zip' | 'url-path' | 's3-key' | 'opaque';
+interface SanitizeFilenameOptions {
+    /** Target-destination profile. */
+    readonly profile: FilenameProfile;
+    /**
+     * Override the per-profile length cap. Useful when leaving headroom
+     * for a collision suffix — e.g. `maxBytes: 240` on a `posix` write
+     * site that wants 15 bytes of slack for `-1`, `-2`, …
+     */
+    readonly maxBytes?: number;
+    /**
+     * Required when `profile === 'opaque'`. The opaque profile replaces
+     * the entire input with `${opaqueId}.${ext}` (extension preserved
+     * from the input when present).
+     */
+    readonly opaqueId?: string;
+}
+/**
+ * Sanitize a filename for a target-destination profile. Pure: same
+ * input + options always returns the same output, no I/O.
+ *
+ * Returns the sanitized name. Throws {@link FilenameSanitizationError}
+ * when the input cannot be made safe at all (NUL byte, empty after
+ * normalization, missing `opaqueId` for the opaque profile,
+ * `..` segment that would fall out of any reasonable target).
+ */
+declare function sanitizeFilename(name: string, opts: SanitizeFilenameOptions): string;
+
+export { type FilenameProfile, type SanitizeFilenameOptions, sanitizeFilename };

package/dist/util/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Target-profile aware filename sanitizer.
+ *
+ * Pure string in / string out. No filesystem access, no I/O. Use this
+ * at the boundary where a user-supplied filename meets a storage
+ * destination — local FS, ZIP archive, S3 key, URL path, SMB share —
+ * to defuse the canonical 14-class footgun before it reaches that
+ * destination.
+ *
+ * ## Threat model
+ *
+ *   1. Path injection — `..`, NUL bytes, `\` on POSIX, absolute paths.
+ *   2. Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`,
+ *      `COM1-9`, `LPT1-9`, with or without an extension.
+ *   3. Windows reserved chars — `< > : " / \ | ? *` plus ASCII 0-31.
+ *   4. Trailing `.` and ` ` on Windows / SMB.
+ *   5. Unicode normalization drift — same display, different bytes →
+ *      "two files with the same name" sync ghosts.
+ *   6. Bidi override spoofing — U+202E reversing `harmless.exe.txt`
+ *      into `harmless.txt.exe`.
+ *   7. URL `+` ambiguity in S3 presigned URLs.
+ *   8. ZIP general-purpose-flag bit 11 (UTF-8 filename) optional in
+ *      pre-2006 readers.
+ *   9-14. Length caps, leading/trailing whitespace + controls,
+ *      `.DS_Store`-style hidden noise, etc.
+ *
+ * ## Always-on transforms (every profile)
+ *
+ *   - NFC normalize (`String.prototype.normalize('NFC')`).
+ *   - Reject NUL — hard fail, not strip. Silent strip enables a
+ *     classic truncation bypass (`safe.txt\0.exe` → `safe.txt`).
+ *   - Strip bidi overrides (`U+202A..U+202E`, `U+2066..U+2069`).
+ *   - Trim leading/trailing whitespace and ASCII control chars.
+ *
+ * ## Non-goals (i18n boundary policy, )
+ *
+ *   - No transliteration.
+ *   - No locale-aware slugging.
+ *   - No script-specific segmentation.
+ *
+ * @module
+ */
+/**
+ * One of seven storage destinations the sanitizer knows how to defang
+ * for. Pick the most restrictive that covers your write site:
+ * `'macos-smb'` is the safe default for "I don't know where these
+ * files end up but they're going to a real filesystem somewhere."
+ */
+type FilenameProfile = 'posix' | 'windows' | 'macos-smb' | 'zip' | 'url-path' | 's3-key' | 'opaque';
+interface SanitizeFilenameOptions {
+    /** Target-destination profile. */
+    readonly profile: FilenameProfile;
+    /**
+     * Override the per-profile length cap. Useful when leaving headroom
+     * for a collision suffix — e.g. `maxBytes: 240` on a `posix` write
+     * site that wants 15 bytes of slack for `-1`, `-2`, …
+     */
+    readonly maxBytes?: number;
+    /**
+     * Required when `profile === 'opaque'`. The opaque profile replaces
+     * the entire input with `${opaqueId}.${ext}` (extension preserved
+     * from the input when present).
+     */
+    readonly opaqueId?: string;
+}
+/**
+ * Sanitize a filename for a target-destination profile. Pure: same
+ * input + options always returns the same output, no I/O.
+ *
+ * Returns the sanitized name. Throws {@link FilenameSanitizationError}
+ * when the input cannot be made safe at all (NUL byte, empty after
+ * normalization, missing `opaqueId` for the opaque profile,
+ * `..` segment that would fall out of any reasonable target).
+ */
+declare function sanitizeFilename(name: string, opts: SanitizeFilenameOptions): string;
+
+export { type FilenameProfile, type SanitizeFilenameOptions, sanitizeFilename };