@tacet-ink/journal-core 0.3.0 → 0.3.2

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   # 521 assertions, all green, run against the real modules (no mocks)
 ```
 
 ```ts
@@ -77,7 +77,7 @@ run: `node --experimental-strip-types example.ts`
 | `src/client/keys.ts` | 品牌前綴 localStorage 命名空間 |
 | `src/server/auth.ts` | 零知識 auth 核心：PH1→PH2 login 動線、入庫格式驗證、包裹欄組成對（pair 檢查 pickKeyPackage）；PH2 UNIQUE 衝突與 session 撤銷＝呼叫端職責 |
 | `src/server/ladder.ts` | 密語正規化 v3 世代 ladder 表原語（ph2_ladder：以舊 ph2 查列／遷移入表 upsert 值主權威）＋幽靈守衛查表接線已內建 loginRouteCore——fork 只需配 `ladderLookup` store＋0011 migration（未配置＝單查行為零變） |
-| `src/server/ratelimit.ts` | per-IP fixed-window 限流（單句 UPSERT…RETURNING；D1 計數，跨 isolate 有效） |
+| `src/server/ratelimit.ts` | per-IP fixed-window 限流（單句 UPSERT…RETURNING；D1 計數，跨 isolate 有效；IPv6 鍵經 `normalizeRateIp` 聚合至 /64；IPv4-mapped 位址回點分 IPv4 鍵（＝原生同 /32 鍵）） |
 | `src/server/cors.ts`／`hash.ts` | 共用 CORS／雜湊工具（`src/server/env.ts` 為內部 Env 介面，不入 exports） |
 
 發行形（0.3.0 起）：`dist/`＝tsc 原生 emit 的 ESM `.js`＋`.d.ts`，`exports` 全部子路徑指向 dist；
@@ -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   # 521 斷言對真模組（禁鏡像；限流單句 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 顯形非靜默）
+                 #   521 帳＝repo 樹——發行包內無 .github＝[21] 四條 workflow 錨收斂為 1 顯性 SKIP 行→518，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）。
@@ -316,7 +317,7 @@ carrier: `node:crypto` ≥ Node 24.7 / hash-wasm in browsers, RFC 9106 test vect
 @scure/bip39), brand-namespaced key storage (`keys.ts`). Server: zero-knowledge auth core with a
 PH1→PH2 login flow, inbound cipher/package validation and paired key-package selection
 (`auth.ts`; PH2-UNIQUE conflict and session revocation are caller-owned wiring), per-IP
-fixed-window rate limiting on D1 (`ratelimit.ts`), shared CORS/hash utilities. Since 0.3.0 the
+(IPv6 keyed per /64 prefix; IPv4-mapped addresses un-map to the native dotted IPv4 key) fixed-window rate limiting on D1 (`ratelimit.ts`), shared CORS/hash utilities. Since 0.3.0 the
 package ships `dist/` (tsc-emitted ESM `.js` + `.d.ts`); every `exports` subpath resolves to dist,
 and `src/` is included for reading and auditing only.
 
@@ -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 521 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

@@ -35,6 +35,17 @@
  */
 /** RFC 9106 無 secret/ad 標準向量（Argon2id v=0x13, t=3, m=32, p=4, T=32, pwd=32B 0x01, salt=16B 0x00）。 */
 export declare 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 declare const ARGON_RFC9106_PARAMS: Readonly<{
+    readonly memoryKib: 32;
+    readonly iterations: 3;
+    readonly parallelism: 4;
+    readonly tagLen: 32;
+    readonly passwordByte: 1;
+    readonly passwordLen: 32;
+    readonly saltLen: 16;
+}>;
 /**
  * PH1 v2 固定域鹽（登入憑證 Argon2id 派生，2026-09-10 安全路線第 4 步）。
  *
@@ -94,7 +105,7 @@ export interface Argon3Config {
     /** 密語正規化 v3 世代雙因子包裹前綴（jr4d.，pass 段正規化＋PIN 段照舊）。未配置 = 拒絕。 */
     wrapDual4?: string;
 }
-interface HashWasmArgon2id {
+export interface HashWasmArgon2id {
     (params: {
         password: string | Uint8Array;
         salt: Uint8Array;
@@ -105,16 +116,18 @@ 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）。 */
 export declare function deriveKekArgon(password: string, salt: Uint8Array): Promise<CryptoKey>;
-/** 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 declare function wrapNoteKey3(cfg: Argon3Config, noteKey: CryptoKey, passphrase: string): Promise<{
     wrapped: string;
     salt: string;
@@ -125,7 +138,7 @@ export declare function wrapNoteKey3(cfg: Argon3Config, noteKey: CryptoKey, pass
  *  家族守衛（wrap3 未配置回 null）、salt1 hex-形檢查與 KEK 派生——payload 形是鹽外置家族（iv‖ct），
  *  own 92B 檢已隨收口摘除（jr3s 同；鹽內嵌族 own 108B 保留）。 */
 export declare function unwrapNoteKey3(cfg: Argon3Config, wrapped: string, passphrase: string, saltHex: string): Promise<CryptoKey | null>;
-/** 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 declare function wrapNoteKey4(cfg: Argon3Config, noteKey: CryptoKey, passphrase: string): Promise<{
     wrapped: string;
     salt: string;
@@ -163,4 +176,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

@@ -45,6 +45,11 @@ function deriveInput(passphrase) {
 }
 /** RFC 9106 無 secret/ad 標準向量（Argon2id v=0x13, t=3, m=32, p=4, T=32, pwd=32B 0x01, salt=16B 0x00）。 */
 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,
+});
 /**
  * PH1 v2 固定域鹽（登入憑證 Argon2id 派生，2026-09-10 安全路線第 4 步）。
  *
@@ -103,6 +108,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）。
@@ -141,7 +150,8 @@ async function deriveArgon2id(password, salt, memoryKib, passes, parallelism) {
 }
 /** 標準向量 KAT：驗證當前載體的 Argon2id 實作正確性（驗證閘起手式）。 */
 export async function verifyArgonKat() {
-    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;
 }
 // ── jr3w. 單因子包裹 ──────────────────────────────────────────────────────────
@@ -152,7 +162,7 @@ async function argonKekFromRaw(raw) {
 export async function deriveKekArgon(password, salt) {
     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, noteKey, passphrase) {
     if (!cfg.wrap3)
         throw new Error('ERR_JR3W_NOT_CONFIGURED');
@@ -189,7 +199,7 @@ export async function unwrapNoteKey3(cfg, wrapped, passphrase, saltHex) {
 // 92B、AAD 'notekey'、嚴格長度全在 openNoteKey 本體），唯一差異＝入口吃 normalizePassphrase(pass)
 // 與 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, noteKey, passphrase) {
     if (!cfg.wrap4)
         throw new Error('ERR_JR4W_NOT_CONFIGURED');

package/dist/client/note-crypto.d.ts

@@ -24,6 +24,7 @@
  * import 當下就必須 extractable=true。noteKey 全部產生路徑（generate/unwrap×3）
  * 一律顯式 true；KEK/guest key 保持 nonextractable（只加解密、永不 export）。
  */
+import type { KeyStore } from './keys.js';
 export interface NoteCryptoConfig {
     /** guest 時代 KDF 前綴，如 'journal-note-u1'。 */
     guestKdfPrefix: string;
@@ -72,7 +73,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 declare const PBKDF2_ITERATIONS = 600000;
 export declare const PIN_PBKDF2_ITERATIONS = 2000000;