@tacet-ink/journal-core 0.3.0 → 0.3.2

package/src/client/argon-auto.ts

@@ -0,0 +1,224 @@
+/**
+ * argon-auto.ts — Argon2id 載體平台預設。
+ *
+ * 優先序（向後相容鐵律：setArgonLoader 照舊優先）：
+ *   1. 呼叫端已 setArgonLoader 注入（非本模組自裝）＝'injected'——本模組零介入。
+ *   2. 回退鏈 chain（可覆寫；預設 ['node','worker','inline']）逐項取第一個可用者：
+ *      - 'node'：node:crypto.argon2 在場（argon2.ts 原生腿；本模組不注入）。
+ *      - 'worker'：Web Worker（argon-worker.ts 內嵌 blob 形）；執行期失效＝若 chain 於其後含
+ *        'inline' 則回退 inline（onFallback 通知＋currentArgonCarrier 翻 'inline'＝行為顯形），否則 throw。
+ *      - 'inline'：同執行緒 vendor hash-wasm（WebAssembly 在場即可）。
+ *   3. 皆不可用＝ERR_VAULT_KDF_UNSUPPORTED（zero-fallback：禁 PBKDF2／zeros 兜底）。
+ * 裝載即 KAT：每個載體首用前跑 RFC 9106 KAT（verifyArgonKat）——錯值載體＝拒用，不只是缺席才拒。
+ *
+ * 'worker'／'inline' 經 setArgonLoader 全域注入（argon2.ts 派生本體唯一入口）：同頁其他 argon2.ts
+ * 呼叫端共享此載體；呼叫端之後自行 setArgonLoader 即覆寫（下次 ensure 判 'injected'）。
+ * resetArgonCarrier() 撤除本模組自裝載體（不動呼叫端注入）並終止 Worker。
+ */
+
+import { getArgonLoader, setArgonLoader, verifyArgonKat, type ArgonLoader, type HashWasmArgon2id } from './argon2.ts';
+import { makeWorkerArgon2id, createBlobArgonWorker, type ArgonWorkerLike } from './argon-worker.ts';
+import { hashWasmArgon2Factory } from './vendor/hash-wasm-argon2.ts';
+import { VaultError } from './vault-error.ts';
+
+export type ArgonCarrierKind = 'injected' | 'node' | 'worker' | 'inline';
+export type ArgonCarrierChoice = 'node' | 'worker' | 'inline';
+export type { ArgonWorkerLike };
+
+export interface ArgonFallbackEvent {
+  from: 'worker';
+  to: 'inline';
+  error: unknown;
+}
+
+export interface ArgonCarrierOptions {
+  /** 回退鏈（預設 ['node','worker','inline']）。例：['worker']＝只准 Worker（失效即拒，不回退）。 */
+  chain?: readonly ArgonCarrierChoice[];
+  /** Worker 工廠覆寫（預設瀏覽器 blob Worker；測試／特殊宿主注入轉接層）。 */
+  createWorker?: () => ArgonWorkerLike;
+  /** Worker → inline 回退通知（行為顯形；不提供＝靜默回退但 currentArgonCarrier 仍翻 'inline'）。 */
+  onFallback?: (ev: ArgonFallbackEvent) => void;
+}
+
+export const DEFAULT_ARGON_CHAIN: readonly ArgonCarrierChoice[] = ['node', 'worker', 'inline'];
+
+function nodeArgonAvailable(): boolean {
+  const nodeCrypto = (globalThis as unknown as {
+    process?: { getBuiltinModule?: (id: string) => { argon2?: unknown } | undefined };
+  }).process?.getBuiltinModule?.('node:crypto');
+  return typeof nodeCrypto?.argon2 === 'function';
+}
+
+function workerAvailable(opts: ArgonCarrierOptions): boolean {
+  if (opts.createWorker) return true;
+  const g = globalThis as unknown as { Worker?: unknown; Blob?: unknown; URL?: { createObjectURL?: unknown } };
+  return typeof g.Worker === 'function' && typeof g.Blob === 'function' && typeof g.URL?.createObjectURL === 'function';
+}
+
+function wasmAvailable(): boolean {
+  return typeof (globalThis as unknown as { WebAssembly?: unknown }).WebAssembly === 'object';
+}
+
+// ── 狀態 ────────────────────────────────────────────────────────────────────
+
+interface AutoState {
+  loader: ArgonLoader;
+  kind: 'worker' | 'inline';
+  chainKey: string;
+  createWorker: ArgonCarrierOptions['createWorker'];
+  onFallback: ArgonCarrierOptions['onFallback'];
+  dispose(): void;
+}
+
+let auto: AutoState | null = null;
+let nodeVerified = false;
+const verified = new WeakSet<ArgonLoader>();
+let failures = 0;
+
+/** 載體終端失效累計（拋出派生本體的失效才計；回退成功不計）。vault 以前後差分辨
+ *  「解包 null＝密語錯」與「載體失效」（低階 unwrap 吞錯回 null，邊界還原真因）。 */
+export function argonCarrierFailures(): number {
+  return failures;
+}
+
+/** 現行載體（未 ensure 過且無注入、非 node＝null）。 */
+export function currentArgonCarrier(): ArgonCarrierKind | null {
+  const cur = getArgonLoader();
+  if (cur) return auto && cur === auto.loader ? auto.kind : 'injected';
+  return nodeArgonAvailable() ? 'node' : null;
+}
+
+/** 撤除本模組自裝載體（呼叫端 setArgonLoader 注入不動）＋終止 Worker。 */
+export function resetArgonCarrier(): void {
+  if (!auto) return;
+  const a = auto;
+  auto = null;
+  if (getArgonLoader() === a.loader) setArgonLoader(null);
+  a.dispose();
+}
+
+// ── inline 載體（同執行緒 vendor hash-wasm；串行） ────────────────────────────
+
+function makeInlineArgon2id(): HashWasmArgon2id {
+  let mod: { argon2id: HashWasmArgon2id } | null = null;
+  let queue: Promise<unknown> = Promise.resolve();
+  return (params) => {
+    const job = queue.then(() => {
+      if (!mod) mod = hashWasmArgon2Factory();
+      return mod.argon2id(params);
+    });
+    queue = job.catch(() => undefined);
+    return job;
+  };
+}
+
+function terminal(e: unknown, what: string): VaultError {
+  failures++;
+  return new VaultError('ERR_VAULT_KDF_UNSUPPORTED', what, { cause: e });
+}
+
+function installInline(chainKey: string, opts: ArgonCarrierOptions): AutoState {
+  const inline = makeInlineArgon2id();
+  const argon2id: HashWasmArgon2id = async (params) => {
+    try { return await inline(params); } catch (e) { throw terminal(e, 'inline carrier failed'); }
+  };
+  const mod = { argon2id };
+  const st: AutoState = {
+    loader: () => Promise.resolve(mod),
+    kind: 'inline',
+    chainKey,
+    createWorker: opts.createWorker,
+    onFallback: opts.onFallback,
+    dispose: () => {},
+  };
+  return st;
+}
+
+function installWorker(chainKey: string, opts: ArgonCarrierOptions, fallbackInline: boolean): AutoState {
+  const w = makeWorkerArgon2id(opts.createWorker ?? createBlobArgonWorker);
+  let inline: HashWasmArgon2id | null = null;
+  const st: AutoState = {
+    loader: () => Promise.resolve(mod),
+    kind: 'worker',
+    chainKey,
+    createWorker: opts.createWorker,
+    onFallback: opts.onFallback,
+    dispose: () => w.terminate(),
+  };
+  const argon2id: HashWasmArgon2id = async (params) => {
+    if (st.kind === 'worker') {
+      try {
+        return await w.argon2id(params);
+      } catch (e) {
+        if (!fallbackInline) throw terminal(e, 'worker carrier failed (chain has no inline fallback)');
+        // 回退：整載體翻 inline（不再試 Worker）——顯形：kind 翻面＋onFallback 通知。
+        if (st.kind === 'worker') {
+          st.kind = 'inline';
+          w.terminate();
+          try { opts.onFallback?.({ from: 'worker', to: 'inline', error: e }); } catch { /* 通知面不影響派生 */ }
+        }
+      }
+    }
+    inline ??= makeInlineArgon2id();
+    try { return await inline(params); } catch (e) { throw terminal(e, 'inline carrier failed'); }
+  };
+  const mod = { argon2id };
+  return st;
+}
+
+async function katOrThrow(): Promise<void> {
+  let ok = false;
+  try { ok = await verifyArgonKat(); } catch (e) {
+    if (e instanceof VaultError) throw e;
+    throw terminal(e, 'carrier KAT threw');
+  }
+  if (!ok) throw terminal(null, 'carrier KAT mismatch (RFC 9106)');
+}
+
+/**
+ * 確保 Argon2id 載體可用並回報種類。冪等：同選項重呼沿用既裝載體（Worker 不重建）；
+ * 選項（chain／createWorker／onFallback）改變＝撤除重裝。首用載體必過 RFC 9106 KAT。
+ */
+export async function ensureArgonCarrier(opts: ArgonCarrierOptions = {}): Promise<ArgonCarrierKind> {
+  const cur = getArgonLoader();
+  if (cur && (!auto || cur !== auto.loader)) {
+    // 呼叫端覆寫優先：自裝殘留（若有）撤除但不碰全域注入。
+    if (auto) { const a = auto; auto = null; a.dispose(); }
+    if (!verified.has(cur)) { await katOrThrow(); verified.add(cur); }
+    return 'injected';
+  }
+  const chain = opts.chain ?? DEFAULT_ARGON_CHAIN;
+  if (!Array.isArray(chain) || chain.length === 0 || !chain.every((c) => c === 'node' || c === 'worker' || c === 'inline')) {
+    throw new VaultError('ERR_VAULT_CONFIG', 'carrier.chain');
+  }
+  const chainKey = chain.join(',');
+  if (auto && cur === auto.loader && auto.chainKey === chainKey && auto.createWorker === opts.createWorker && auto.onFallback === opts.onFallback) {
+    return auto.kind;
+  }
+  resetArgonCarrier();
+  for (let i = 0; i < chain.length; i++) {
+    const choice = chain[i];
+    if (choice === 'node') {
+      if (!nodeArgonAvailable()) continue;
+      if (!nodeVerified) { await katOrThrow(); nodeVerified = true; }
+      return 'node';
+    }
+    if (choice === 'worker') {
+      if (!workerAvailable(opts)) continue;
+      const st = installWorker(chainKey, opts, chain.slice(i + 1).includes('inline') && wasmAvailable());
+      auto = st;
+      setArgonLoader(st.loader);
+      try { await katOrThrow(); } catch (e) { resetArgonCarrier(); throw e; }
+      return st.kind;
+    }
+    if (choice === 'inline') {
+      if (!wasmAvailable()) continue;
+      const st = installInline(chainKey, opts);
+      auto = st;
+      setArgonLoader(st.loader);
+      try { await katOrThrow(); } catch (e) { resetArgonCarrier(); throw e; }
+      return st.kind;
+    }
+  }
+  throw new VaultError('ERR_VAULT_KDF_UNSUPPORTED', 'no Argon2id carrier in chain [' + chainKey + ']');
+}

package/src/client/argon-worker.ts

@@ -0,0 +1,147 @@
+/**
+ * argon-worker.ts — Argon2id Web Worker 載體：登入不卡畫面。
+ *
+ * Worker 本體＝內嵌 blob 形（免 bundle 步）：vendor 工廠 hashWasmArgon2Factory 的原文
+ *（Function#toString）＋訊息膠水組成 Worker 源碼字串 → Blob → object URL → new Worker。
+ * 協定：main → { id, password, salt, iterations, parallelism, memorySize, hashLength }；
+ *       worker → { id, ok: true, out: Uint8Array } | { id, ok: false, error }。
+ * 串行：main 端單一佇列（hash-wasm Argon2 禁並行——argon2.ts deriveKek2Argon 註同理），
+ * worker 端亦以 promise 鏈串行（雙防線）。
+ * 失敗態：建構拋出／error 事件／ok:false 回應＝本載體失效（dead），佇列內與後續請求一律 reject——
+ * 回退與否由 argon-auto.ts 回退鏈決定（本檔不自帶回退，行為顯形）。
+ */
+
+import type { HashWasmArgon2id } from './argon2.ts';
+import { hashWasmArgon2Factory } from './vendor/hash-wasm-argon2.ts';
+
+/** Worker 最小介面（瀏覽器 Worker 直接相容；node worker_threads 等可包轉接層注入）。 */
+export interface ArgonWorkerLike {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+  terminate(): void;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+}
+
+/** Worker 源碼字串（self.onmessage 形；瀏覽器 DedicatedWorkerGlobalScope 語意）。 */
+export function argonWorkerSource(): string {
+  return [
+    "'use strict';",
+    'const factory = (' + hashWasmArgon2Factory.toString() + ');',
+    'let mod = null;',
+    'let q = Promise.resolve();',
+    'self.onmessage = (ev) => {',
+    '  const m = ev.data;',
+    '  q = q.then(async () => {',
+    '    try {',
+    '      if (!mod) mod = factory();',
+    "      const r = await mod.argon2id({ password: m.password, salt: m.salt, iterations: m.iterations, parallelism: m.parallelism, memorySize: m.memorySize, hashLength: m.hashLength, outputType: 'binary' });",
+    '      const out = new Uint8Array(r);',
+    '      self.postMessage({ id: m.id, ok: true, out }, [out.buffer]);',
+    '    } catch (e) {',
+    '      self.postMessage({ id: m.id, ok: false, error: String((e && e.message) || e) });',
+    '    }',
+    '  });',
+    '};',
+    '',
+  ].join('\n');
+}
+
+/** 瀏覽器預設 Worker 工廠：blob URL（CSP 需 worker-src blob:；不允許時建構拋出或 error 事件→回退鏈接手）。 */
+export function createBlobArgonWorker(): ArgonWorkerLike {
+  const url = URL.createObjectURL(new Blob([argonWorkerSource()], { type: 'text/javascript' }));
+  let w: Worker;
+  try {
+    w = new Worker(url);
+  } catch (e) {
+    URL.revokeObjectURL(url);
+    throw e;
+  }
+  const like: ArgonWorkerLike = {
+    postMessage: (m, t) => w.postMessage(m, t ?? []),
+    terminate: () => { w.terminate(); URL.revokeObjectURL(url); },
+    onmessage: null,
+    onerror: null,
+  };
+  w.onmessage = (ev) => like.onmessage?.({ data: ev.data });
+  w.onerror = (ev) => like.onerror?.(ev);
+  w.onmessageerror = (ev) => like.onerror?.(ev);
+  return like;
+}
+
+interface Pending {
+  resolve: (v: Uint8Array) => void;
+  reject: (e: unknown) => void;
+}
+
+/** Worker 載體：回 hash-wasm 同形 argon2id（argon2.ts ArgonLoader 契約）＋terminate。 */
+export function makeWorkerArgon2id(createWorker: () => ArgonWorkerLike): { argon2id: HashWasmArgon2id; terminate(): void } {
+  let worker: ArgonWorkerLike | null = null;
+  let dead: unknown = null;
+  let seq = 0;
+  const pending = new Map<number, Pending>();
+  let queue: Promise<unknown> = Promise.resolve();
+
+  const die = (e: unknown): void => {
+    if (!dead) dead = e ?? new Error('ERR_ARGON_WORKER_DEAD');
+    for (const p of pending.values()) p.reject(dead);
+    pending.clear();
+    if (worker) { try { worker.terminate(); } catch { /* 已終止 */ } }
+    worker = null;
+  };
+
+  const boot = (): ArgonWorkerLike => {
+    if (worker) return worker;
+    const w = createWorker();
+    w.onmessage = (ev) => {
+      const d = ev.data as { id?: number; ok?: boolean; out?: Uint8Array; error?: string } | null;
+      const p = d && typeof d.id === 'number' ? pending.get(d.id) : undefined;
+      if (!p || !d) return;
+      pending.delete(d.id!);
+      if (d.ok && d.out instanceof Uint8Array) p.resolve(d.out);
+      else {
+        const err = new Error('ERR_ARGON_WORKER: ' + (d.error ?? 'bad response'));
+        p.reject(err);
+        die(err); // ok:false＝worker 內 wasm 失效（CSP wasm-eval／記憶體）——整載體 dead，交回退鏈
+      }
+    };
+    w.onerror = (ev) => die(new Error('ERR_ARGON_WORKER_ERROR', { cause: ev }));
+    worker = w;
+    return w;
+  };
+
+  const run = (params: Parameters<HashWasmArgon2id>[0]): Promise<Uint8Array> =>
+    new Promise<Uint8Array>((resolve, reject) => {
+      if (dead) { reject(dead); return; }
+      let w: ArgonWorkerLike;
+      try { w = boot(); } catch (e) { die(e); reject(dead); return; }
+      const id = ++seq;
+      pending.set(id, { resolve, reject });
+      try {
+        w.postMessage({
+          id,
+          password: params.password,
+          salt: params.salt,
+          iterations: params.iterations,
+          parallelism: params.parallelism,
+          memorySize: params.memorySize,
+          hashLength: params.hashLength,
+        });
+      } catch (e) {
+        pending.delete(id);
+        die(e);
+        reject(dead);
+      }
+    });
+
+  const argon2id: HashWasmArgon2id = (params) => {
+    const job = queue.then(() => run(params));
+    queue = job.catch(() => undefined);
+    return job.then((out) => {
+      if (params.outputType === 'binary') return out;
+      if (params.outputType === 'hex') return Array.from(out).map((b) => b.toString(16).padStart(2, '0')).join('');
+      throw new Error('ERR_ARGON_WORKER_OUTPUT_TYPE');
+    });
+  };
+
+  return { argon2id, terminate: () => die(new Error('ERR_ARGON_WORKER_TERMINATED')) };
+}

package/src/client/argon2.ts

@@ -52,6 +52,12 @@ function deriveInput(passphrase: string): string {
 export const ARGON_RFC9106_EXPECTED =
   '72d2a36fd5c266bcc96121b24937bc253338cdfcbd273713655748c54b4dd503';
 
+/** RFC 9106 KAT 參數單一真相（verifyArgonKat／scripts/generate-vectors.ts 寫 kat.json／閘 [26] 對帳共用）。
+ *  tagLen＝派生本體固定輸出長（ARGON_TAG_LEN）；pwd＝passwordLen 位元組 passwordByte、salt＝saltLen 位元組 0x00。 */
+export const ARGON_RFC9106_PARAMS = Object.freeze({
+  memoryKib: 32, iterations: 3, parallelism: 4, tagLen: 32, passwordByte: 0x01, passwordLen: 32, saltLen: 16,
+} as const);
+
 /**
  * PH1 v2 固定域鹽（登入憑證 Argon2id 派生，2026-09-10 安全路線第 4 步）。
  *
@@ -140,7 +146,7 @@ export interface Argon3Config {
   wrapDual4?: string;
 }
 
-interface HashWasmArgon2id {
+export interface HashWasmArgon2id {
   (params: {
     password: string | Uint8Array;
     salt: Uint8Array;
@@ -152,7 +158,7 @@ interface HashWasmArgon2id {
   }): Promise<Uint8Array | string>;
 }
 
-type ArgonLoader = () => Promise<{ argon2id: HashWasmArgon2id }>;
+export type ArgonLoader = () => Promise<{ argon2id: HashWasmArgon2id }>;
 
 let injectedLoader: ArgonLoader | null = null;
 
@@ -161,6 +167,11 @@ export function setArgonLoader(loader: ArgonLoader | null): void {
   injectedLoader = loader;
 }
 
+/** 現行注入載體（唯讀查詢；未注入＝null）。argon-auto.ts 據此判「呼叫端覆寫優先」——0.3.1 新增 export。 */
+export function getArgonLoader(): ArgonLoader | null {
+  return injectedLoader;
+}
+
 /**
  * Argon2id 派生 32B。雙載體：injectedLoader（瀏覽器 hash-wasm）優先；
  * 無注入時走 node:crypto 原生（僅 node 執行環境可達）。皆不可得即 throw（禁 fallback）。
@@ -224,7 +235,8 @@ type NodeArgonFn = (
 
 /** 標準向量 KAT：驗證當前載體的 Argon2id 實作正確性（驗證閘起手式）。 */
 export async function verifyArgonKat(): Promise<boolean> {
-  const raw = await deriveArgon2id(new Uint8Array(32).fill(1), new Uint8Array(16), 32, 3, 4);
+  const k = ARGON_RFC9106_PARAMS;
+  const raw = await deriveArgon2id(new Uint8Array(k.passwordLen).fill(k.passwordByte), new Uint8Array(k.saltLen), k.memoryKib, k.iterations, k.parallelism);
   return toHex(raw) === ARGON_RFC9106_EXPECTED;
 }
 
@@ -239,7 +251,7 @@ export async function deriveKekArgon(password: string, salt: Uint8Array): Promis
   return argonKekFromRaw(await deriveArgon2id(password, salt, ARGON_MEMORY_KIB, ARGON_ITERATIONS, ARGON_PARALLELISM));
 }
 
-/** jr3w. 包裹：payload = salt[16] ‖ iv[12] ‖ AES-GCM(KEK, hex(noteKey), aad='notekey')；salt 由呼叫端存 users.salt。 */
+/** jr3w. 包裹：payload = iv[12] ‖ AES-GCM(KEK, hex(noteKey), aad='notekey')（鹽外置家族，嚴格 92B）；salt 不入 payload，由呼叫端存 users.salt。 */
 export async function wrapNoteKey3(cfg: Argon3Config, noteKey: CryptoKey, passphrase: string): Promise<{ wrapped: string; salt: string }> {
   if (!cfg.wrap3) throw new Error('ERR_JR3W_NOT_CONFIGURED');
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LEN));
@@ -274,7 +286,7 @@ export async function unwrapNoteKey3(cfg: Argon3Config, wrapped: string, passphr
 // 與 cfg.wrap4 前綴。舊 payload（jr1w./jr3w.）永遠可解＝raw 派生；新 payload 只由 jr4w. 產生。
 // pinSaltPrefix 沿用 cfg 既有欄（Argon3 家族 PIN 鹽域，非 jr3d. 專屬）。
 
-/** jr4w. 包裹（v3 密語）：payload = salt[16] ‖ iv[12] ‖ GCM(KEK, hex(noteKey), aad='notekey')；salt 呼叫端存 users.salt。 */
+/** jr4w. 包裹（v3 密語）：payload = iv[12] ‖ GCM(KEK, hex(noteKey), aad='notekey')（鹽外置家族，嚴格 92B）；salt 不入 payload，呼叫端存 users.salt。 */
 export async function wrapNoteKey4(cfg: Argon3Config, noteKey: CryptoKey, passphrase: string): Promise<{ wrapped: string; salt: string }> {
   if (!cfg.wrap4) throw new Error('ERR_JR4W_NOT_CONFIGURED');
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LEN));

package/src/client/note-crypto.ts

@@ -27,6 +27,8 @@
 
 // ── 配置 ────────────────────────────────────────────────────────────────────
 
+import type { KeyStore } from './keys.js';
+
 export interface NoteCryptoConfig {
   /** guest 時代 KDF 前綴，如 'journal-note-u1'。 */
   guestKdfPrefix: string;
@@ -75,7 +77,7 @@ export interface NoteCryptoConfig {
   /** 本機 IDB 密文前綴（jr1d.，notes store stored 形）。未配置 = local API 拒絕（未配置行為不變）。 */
   cipherLocal?: string;
   /** localStorage key store（品牌前綴由 keys.ts 管理）。 */
-  store: import('./keys').KeyStore;
+  store: KeyStore;
 }
 
 export const PBKDF2_ITERATIONS = 600_000; // OWASP 2023 建議值

package/src/client/vault-error.ts

@@ -0,0 +1,51 @@
+/**
+ * vault-error.ts — 高階 Vault API 的型別化錯誤家族。
+ *
+ * 低階原語面不動（throw 'ERR_*' 字串錯誤＋unwrap 恆 null 的混態照舊）——只在 vault.ts／
+ * argon-auto.ts 邊界轉譯：高階 API 一律 throw VaultError，呼叫端以 `code` 分流，不比對 message。
+ * 失敗面刻意不細分「密語錯」與「密文竄改」（同一 GCM 失敗——細分＝oracle）。
+ */
+
+export type VaultErrorCode =
+  /** 配置缺欄／畸形（app、cipher、argon.wrap4、recovery 兩欄一體…）——opt-in 未配置即拒。 */
+  | 'ERR_VAULT_CONFIG'
+  /** serverRecord 缺 wrapped/salt 欄或形不符（不猜）。 */
+  | 'ERR_VAULT_BAD_RECORD'
+  /** wrapped 前綴不屬任何已配置家族（未知世代／他產品前綴）。 */
+  | 'ERR_VAULT_WRAP_UNKNOWN'
+  /** 家族辨識成功但解包失敗：密語／PIN 錯或包裹竄改（刻意不分）。 */
+  | 'ERR_VAULT_WRAP_MISMATCH'
+  /** 雙因子家族（jr2w./jr3d./jr4d.）缺 PIN。 */
+  | 'ERR_VAULT_PIN_REQUIRED'
+  /** 密語空值／非字串。 */
+  | 'ERR_VAULT_BAD_PASSPHRASE'
+  /** PIN 正規化後為空。 */
+  | 'ERR_VAULT_BAD_PIN'
+  /** Argon2id 載體缺席或失效（zero-fallback：禁 PBKDF2／zeros 兜底）。 */
+  | 'ERR_VAULT_KDF_UNSUPPORTED'
+  /** recordId 非字串或空。 */
+  | 'ERR_VAULT_BAD_RECORD_ID'
+  /** encrypt 資料形不支援（undefined、BigInt、循環 JSON、非 Uint8Array 的 ArrayBuffer 族…）。 */
+  | 'ERR_VAULT_BAD_DATA'
+  /** 密文 blob 形不符（前綴／base64／長度／型別標記）。 */
+  | 'ERR_VAULT_BAD_BLOB'
+  /** 密文解密失敗：recordId（AAD）不符、金鑰不符或密文竄改（刻意不分）。 */
+  | 'ERR_VAULT_DECRYPT'
+  /** 復原套件形不符（recToken 非 hex64、wrappedRec 前綴不符）或解包失敗。 */
+  | 'ERR_VAULT_RECOVERY'
+  /** 未預期的低階錯誤（cause 帶原錯）。 */
+  | 'ERR_VAULT_INTERNAL';
+
+export class VaultError extends Error {
+  readonly code: VaultErrorCode;
+  constructor(code: VaultErrorCode, message?: string, options?: { cause?: unknown }) {
+    super(message ? code + ': ' + message : code, options);
+    this.name = 'VaultError';
+    this.code = code;
+  }
+}
+
+/** 型別守衛：`isVaultError(e)` 或指定碼 `isVaultError(e, 'ERR_VAULT_DECRYPT')`。 */
+export function isVaultError(e: unknown, code?: VaultErrorCode): e is VaultError {
+  return e instanceof VaultError && (code === undefined || e.code === code);
+}