@tacet-ink/journal-core 0.3.0 → 0.3.1

package/README.md

@@ -18,7 +18,7 @@
 ```sh
 git clone https://github.com/tacet-ink/journal-core.git && cd journal-core
 npm ci --ignore-scripts
-npm run verify   # 492 assertions, all green, run against the real modules (no mocks)
+npm run verify   # 506 assertions, all green, run against the real modules (no mocks)
 ```
 
 ```ts
@@ -124,7 +124,7 @@ jr3d/jr4d 兩入參數同輸入，域分離由 info 承載；凍結 KAT 兩 blob
 
 ```sh
 npm ci --ignore-scripts
-npm run verify   # 492 斷言對真模組（禁鏡像；限流單句 UPSERT…RETURNING 直載真 SQLite）：roundtrip/AAD 防搬移/
+npm run verify   # 506 斷言對真模組（禁鏡像；限流單句 UPSERT…RETURNING 直載真 SQLite）：roundtrip/AAD 防搬移/
                  # extractable/時代隔離/跨前綴家族隔離/payload 竄改/RFC 9106 KAT/BIP39 @scure 對照 200 組/
                  # server-side（inboundCipher/validWrappedKey/pickKeyPackage/checkRate/timingSafeEq）+ pinlock 全函式
                  # + 密語正規化 v3 世代（normalizePassphrase／jr4w./jr4d.／PH1 v3 鹽域分離＋帶內版本化舊契約向量）
@@ -136,9 +136,10 @@ npm run verify   # 492 斷言對真模組（禁鏡像；限流單句 UPSERT…RE
                  # ＋KAT 凍結向量 [17]（HKDF info 域世代分離＋v3/raw 入口契約四 blob）
                  # ＋包裹前綴快檢 [13-2]（錯前綴試探免付 KDF：五入口行為＋計時帽＋計數錨）
                  # ＋CI 供應鏈面 [21]（npm ci --ignore-scripts＋dependabot runner fromJSON 分流＋腳本摘除＋NIT-1 錨＋r2 MINOR-1 URL 直傳；
-                 #   492 帳＝repo 樹——發行包內無 .github＝[21] 四條 workflow 錨收斂為 1 顯性 SKIP 行→489，SKIP 顯形非靜默）
+                 #   506 帳＝repo 樹——發行包內無 .github＝[21] 四條 workflow 錨收斂為 1 顯性 SKIP 行→503，SKIP 顯形非靜默）
                  # ＋發行 tarball 治理面 [22]（pack 白名單零 open-card-pr.sh）
                  # ＋格式規格＋測試向量 [26]（docs/format-spec.md＋docs/vectors 存在性／位元組 shape／欄位名對規格／凍結 KAT 逐字對閘）
+                 # ＋高階 Vault API [27]（roundtrip 三形／新舊前綴解鎖／upgrade／換密語／復原／VaultError 毒化／載體覆寫＋Worker 回退鏈／vendor 孿生）
 ```
 
 - 產品碼**零執行時依賴**（WebCrypto 原語）；devDependencies 僅閘用（typescript、@scure/bip39 對照、workers types）。
@@ -330,7 +331,7 @@ prefix family (`families.json`), known-answer vectors (RFC 9106 Argon2id, the ga
 `scripts/generate-vectors.ts` against the real primitives and committed as frozen evidence; the
 verify gate checks their presence and shape (section [26]) and does not regenerate them.
 
-**Verification.** `npm run verify` runs 492 assertions against the real modules (no mocks):
+**Verification.** `npm run verify` runs 506 assertions against the real modules (no mocks):
 roundtrips, AAD tamper-evidence, extractability rules, era isolation, cross-prefix family
 isolation, payload tampering, RFC 9106 KAT, a 200-vector BIP39 cross-check, and the
 login ladder-guard behavior suite (external audit #8), and presence/shape checks for the format

package/dist/client/argon-auto.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { type ArgonWorkerLike } from './argon-worker.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 declare const DEFAULT_ARGON_CHAIN: readonly ArgonCarrierChoice[];
+/** 載體終端失效累計（拋出派生本體的失效才計；回退成功不計）。vault 以前後差分辨
+ *  「解包 null＝密語錯」與「載體失效」（低階 unwrap 吞錯回 null，邊界還原真因）。 */
+export declare function argonCarrierFailures(): number;
+/** 現行載體（未 ensure 過且無注入、非 node＝null）。 */
+export declare function currentArgonCarrier(): ArgonCarrierKind | null;
+/** 撤除本模組自裝載體（呼叫端 setArgonLoader 注入不動）＋終止 Worker。 */
+export declare function resetArgonCarrier(): void;
+/**
+ * 確保 Argon2id 載體可用並回報種類。冪等：同選項重呼沿用既裝載體（Worker 不重建）；
+ * 選項（chain／createWorker／onFallback）改變＝撤除重裝。首用載體必過 RFC 9106 KAT。
+ */
+export declare function ensureArgonCarrier(opts?: ArgonCarrierOptions): Promise<ArgonCarrierKind>;

package/dist/client/argon-auto.js

@@ -0,0 +1,226 @@
+/**
+ * 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 } from './argon2.js';
+import { makeWorkerArgon2id, createBlobArgonWorker } from './argon-worker.js';
+import { hashWasmArgon2Factory } from './vendor/hash-wasm-argon2.js';
+import { VaultError } from './vault-error.js';
+export const DEFAULT_ARGON_CHAIN = ['node', 'worker', 'inline'];
+function nodeArgonAvailable() {
+    const nodeCrypto = globalThis.process?.getBuiltinModule?.('node:crypto');
+    return typeof nodeCrypto?.argon2 === 'function';
+}
+function workerAvailable(opts) {
+    if (opts.createWorker)
+        return true;
+    const g = globalThis;
+    return typeof g.Worker === 'function' && typeof g.Blob === 'function' && typeof g.URL?.createObjectURL === 'function';
+}
+function wasmAvailable() {
+    return typeof globalThis.WebAssembly === 'object';
+}
+let auto = null;
+let nodeVerified = false;
+const verified = new WeakSet();
+let failures = 0;
+/** 載體終端失效累計（拋出派生本體的失效才計；回退成功不計）。vault 以前後差分辨
+ *  「解包 null＝密語錯」與「載體失效」（低階 unwrap 吞錯回 null，邊界還原真因）。 */
+export function argonCarrierFailures() {
+    return failures;
+}
+/** 現行載體（未 ensure 過且無注入、非 node＝null）。 */
+export function currentArgonCarrier() {
+    const cur = getArgonLoader();
+    if (cur)
+        return auto && cur === auto.loader ? auto.kind : 'injected';
+    return nodeArgonAvailable() ? 'node' : null;
+}
+/** 撤除本模組自裝載體（呼叫端 setArgonLoader 注入不動）＋終止 Worker。 */
+export function resetArgonCarrier() {
+    if (!auto)
+        return;
+    const a = auto;
+    auto = null;
+    if (getArgonLoader() === a.loader)
+        setArgonLoader(null);
+    a.dispose();
+}
+// ── inline 載體（同執行緒 vendor hash-wasm；串行） ────────────────────────────
+function makeInlineArgon2id() {
+    let mod = null;
+    let queue = 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, what) {
+    failures++;
+    return new VaultError('ERR_VAULT_KDF_UNSUPPORTED', what, { cause: e });
+}
+function installInline(chainKey, opts) {
+    const inline = makeInlineArgon2id();
+    const argon2id = async (params) => {
+        try {
+            return await inline(params);
+        }
+        catch (e) {
+            throw terminal(e, 'inline carrier failed');
+        }
+    };
+    const mod = { argon2id };
+    const st = {
+        loader: () => Promise.resolve(mod),
+        kind: 'inline',
+        chainKey,
+        createWorker: opts.createWorker,
+        onFallback: opts.onFallback,
+        dispose: () => { },
+    };
+    return st;
+}
+function installWorker(chainKey, opts, fallbackInline) {
+    const w = makeWorkerArgon2id(opts.createWorker ?? createBlobArgonWorker);
+    let inline = null;
+    const st = {
+        loader: () => Promise.resolve(mod),
+        kind: 'worker',
+        chainKey,
+        createWorker: opts.createWorker,
+        onFallback: opts.onFallback,
+        dispose: () => w.terminate(),
+    };
+    const argon2id = 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() {
+    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 = {}) {
+    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/dist/client/argon-worker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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';
+/** 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 declare function argonWorkerSource(): string;
+/** 瀏覽器預設 Worker 工廠：blob URL（CSP 需 worker-src blob:；不允許時建構拋出或 error 事件→回退鏈接手）。 */
+export declare function createBlobArgonWorker(): ArgonWorkerLike;
+/** Worker 載體：回 hash-wasm 同形 argon2id（argon2.ts ArgonLoader 契約）＋terminate。 */
+export declare function makeWorkerArgon2id(createWorker: () => ArgonWorkerLike): {
+    argon2id: HashWasmArgon2id;
+    terminate(): void;
+};

package/dist/client/argon-worker.js

@@ -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 { hashWasmArgon2Factory } from './vendor/hash-wasm-argon2.js';
+/** Worker 源碼字串（self.onmessage 形；瀏覽器 DedicatedWorkerGlobalScope 語意）。 */
+export function argonWorkerSource() {
+    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() {
+    const url = URL.createObjectURL(new Blob([argonWorkerSource()], { type: 'text/javascript' }));
+    let w;
+    try {
+        w = new Worker(url);
+    }
+    catch (e) {
+        URL.revokeObjectURL(url);
+        throw e;
+    }
+    const like = {
+        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;
+}
+/** Worker 載體：回 hash-wasm 同形 argon2id（argon2.ts ArgonLoader 契約）＋terminate。 */
+export function makeWorkerArgon2id(createWorker) {
+    let worker = null;
+    let dead = null;
+    let seq = 0;
+    const pending = new Map();
+    let queue = Promise.resolve();
+    const die = (e) => {
+        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 = () => {
+        if (worker)
+            return worker;
+        const w = createWorker();
+        w.onmessage = (ev) => {
+            const d = ev.data;
+            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) => new Promise((resolve, reject) => {
+        if (dead) {
+            reject(dead);
+            return;
+        }
+        let w;
+        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 = (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/dist/client/argon2.d.ts

@@ -94,7 +94,7 @@ export interface Argon3Config {
     /** 密語正規化 v3 世代雙因子包裹前綴（jr4d.，pass 段正規化＋PIN 段照舊）。未配置 = 拒絕。 */
     wrapDual4?: string;
 }
-interface HashWasmArgon2id {
+export interface HashWasmArgon2id {
     (params: {
         password: string | Uint8Array;
         salt: Uint8Array;
@@ -105,11 +105,13 @@ interface HashWasmArgon2id {
         outputType: 'binary' | 'hex' | 'encoded';
     }): Promise<Uint8Array | string>;
 }
-type ArgonLoader = () => Promise<{
+export type ArgonLoader = () => Promise<{
     argon2id: HashWasmArgon2id;
 }>;
 /** 載體注入（瀏覽器端由接線層指定 hash-wasm；node 端不注入走 node:crypto 原生）。 */
 export declare function setArgonLoader(loader: ArgonLoader | null): void;
+/** 現行注入載體（唯讀查詢；未注入＝null）。argon-auto.ts 據此判「呼叫端覆寫優先」——0.3.1 新增 export。 */
+export declare function getArgonLoader(): ArgonLoader | null;
 /** 標準向量 KAT：驗證當前載體的 Argon2id 實作正確性（驗證閘起手式）。 */
 export declare function verifyArgonKat(): Promise<boolean>;
 /** KEK = Argon2id(pass, salt, m=64MiB, t=3, p=1) → AES-GCM key（nonextractable）。 */
@@ -163,4 +165,3 @@ export declare function wrapNoteKeyShare3(cfg: Argon3Config, noteKey: CryptoKey,
 export declare function unwrapNoteKeyShare3(cfg: Argon3Config, wrapped: string, sharePass: string, saltHex: string): Promise<CryptoKey | null>;
 /** jr4d. 解包（重取 salt1 面）：pinSalt 內嵌自描述，salt1 由呼叫端重取後帶入（ladder 遷移後的新値）；任何不符回 null，不拋。 */
 export declare function unwrapNoteKeyDual4WithSalt(cfg: Argon3Config, wrapped: string, passphrase: string, pin: string, salt1Hex: string): Promise<CryptoKey | null>;
-export {};

package/dist/client/argon2.js

@@ -103,6 +103,10 @@ let injectedLoader = null;
 export function setArgonLoader(loader) {
     injectedLoader = loader;
 }
+/** 現行注入載體（唯讀查詢；未注入＝null）。argon-auto.ts 據此判「呼叫端覆寫優先」——0.3.1 新增 export。 */
+export function getArgonLoader() {
+    return injectedLoader;
+}
 /**
  * Argon2id 派生 32B。雙載體：injectedLoader（瀏覽器 hash-wasm）優先；
  * 無注入時走 node:crypto 原生（僅 node 執行環境可達）。皆不可得即 throw（禁 fallback）。

package/dist/client/vault-error.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare class VaultError extends Error {
+    readonly code: VaultErrorCode;
+    constructor(code: VaultErrorCode, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 型別守衛：`isVaultError(e)` 或指定碼 `isVaultError(e, 'ERR_VAULT_DECRYPT')`。 */
+export declare function isVaultError(e: unknown, code?: VaultErrorCode): e is VaultError;

package/dist/client/vault-error.js

@@ -0,0 +1,19 @@
+/**
+ * vault-error.ts — 高階 Vault API 的型別化錯誤家族。
+ *
+ * 低階原語面不動（throw 'ERR_*' 字串錯誤＋unwrap 恆 null 的混態照舊）——只在 vault.ts／
+ * argon-auto.ts 邊界轉譯：高階 API 一律 throw VaultError，呼叫端以 `code` 分流，不比對 message。
+ * 失敗面刻意不細分「密語錯」與「密文竄改」（同一 GCM 失敗——細分＝oracle）。
+ */
+export class VaultError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message ? code + ': ' + message : code, options);
+        this.name = 'VaultError';
+        this.code = code;
+    }
+}
+/** 型別守衛：`isVaultError(e)` 或指定碼 `isVaultError(e, 'ERR_VAULT_DECRYPT')`。 */
+export function isVaultError(e, code) {
+    return e instanceof VaultError && (code === undefined || e.code === code);
+}