@tacet-ink/journal-core 0.2.5 → 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   # 491 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
@@ -80,9 +80,14 @@ run: `node --experimental-strip-types example.ts`
 | `src/server/ratelimit.ts` | per-IP fixed-window 限流（單句 UPSERT…RETURNING；D1 計數，跨 isolate 有效） |
 | `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；
+`src/` 同包隨附（稽核／閱讀用，import 恆走 dist）。
+
 ## 前綴契約（家族表：13 個資料前綴＋閘對照組 jr1g.）
 
 前綴是版本契約：payload 佈局與 KDF 由前綴界定，升級 = 新前綴。
+逐位元組布局、KDF 參數、AAD 與世代契約的完整規格見 [docs/format-spec.md](./docs/format-spec.md)，
+測試向量見 [docs/vectors/](./docs/vectors/)（真原語產生的凍結證據；閘 [26] 檢存在性與 shape）。
 Tacet 部署實例（config 傳入）：
 
 | 前綴 | 語意 | KDF | payload |
@@ -119,7 +124,7 @@ jr3d/jr4d 兩入參數同輸入，域分離由 info 承載；凍結 KAT 兩 blob
 
 ```sh
 npm ci --ignore-scripts
-npm run verify   # 491 斷言對真模組（禁鏡像；限流單句 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 鹽域分離＋帶內版本化舊契約向量）
@@ -131,8 +136,10 @@ npm run verify   # 491 斷言對真模組（禁鏡像；限流單句 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 直傳；
-                 #   491 帳＝repo 樹——發行包內無 .github＝[21] 四條 workflow 錨收斂為 1 顯性 SKIP 行→480，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）。
@@ -146,8 +153,9 @@ npm run verify   # 491 斷言對真模組（禁鏡像；限流單句 UPSERT…RE
 
 ## 使用（Usage）
 
-TypeScript 原始碼發行（exports 直指 .ts）。**注意**：Node 的 strip-types 不適用於
-node_modules 內的檔案，npm 安裝的消費者請走打包器；源碼 clone 可直接 node --experimental-strip-types。
+0.3.0 起發行 `dist/`（ESM `.js`＋`.d.ts`）：npm 安裝後瀏覽器、Node、Deno、Bun、Workers
+皆可直接 import，不需打包器、不需 strip-types（0.2.x 的「npm 安裝必走打包器」限制已退役）。
+源碼 clone 仍可直接 `node --experimental-strip-types` 跑 `src/`。
 
 ```ts
 import { makeKeyStore, makeHeldKey, generateNoteKey, encryptNote, decryptNote } from '@tacet-ink/journal-core';
@@ -241,8 +249,8 @@ catch）＋套用 `migrations/0011-ph2-ladder.sql`（＋0012 索引修正）；
 - `PinLockConfig`：解包輸出的 noteKey 恆 `extractable=true`（鐵律，非可調選項）——
   config 只帶三個前綴欄（pinLock/pinLockSaltPrefix/pinLockAad），缺任一即拒。
 
-打包器（vite/esbuild）可直接 alias 到源碼目錄使用；Argon2id 瀏覽器載體需另裝
-hash-wasm 並以 `setArgonLoader()` 注入（詳 `src/client/argon2.ts` 檔頭）。
+Argon2id 瀏覽器載體需另裝 hash-wasm 並以 `setArgonLoader()` 注入（詳 `src/client/argon2.ts` 檔頭）；
+Node ≥ 24.7 走內建 `node:crypto` 免注入。
 
 ## 界限（誠實面）
 
@@ -309,16 +317,31 @@ 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.
-
-**Verification.** `npm run verify` runs 491 assertions against the real modules (no mocks):
+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.
+
+**Format spec & test vectors.** The byte-level wire format of every prefix family — payload layout
+and field lengths, KDF parameters, AAD strings, and the in-band versioning contract — is specified
+in [docs/format-spec.md](./docs/format-spec.md) (Chinese; transcribed from the source, not a new
+contract). JSON test vectors live in [docs/vectors/](./docs/vectors/): one wrap/encrypt sample per
+prefix family (`families.json`), known-answer vectors (RFC 9106 Argon2id, the gate's frozen
+`jr2w.`/`jr3w.`/`jr3d.`/`jr4w.`/`jr4d.`/`jr1r.`/`jr1w.` blobs, and PH1/PH2 credential samples in
+`kat.json`), and 34 BIP39 samples (`bip39.json`). They were generated once by
+`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 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).
-
-**Usage.** TypeScript source is published (exports point at `.ts`). If you install from npm you
-must bundle it (vite/esbuild etc.); Node's strip-types does not apply inside `node_modules`.
-See the code sample in the 使用 section above.
+login ladder-guard behavior suite (external audit #8), and presence/shape checks for the format
+spec and test vectors.
+
+**Usage.** Since 0.3.0 the npm package ships compiled ESM in `dist/`, so browsers, Node, Deno, Bun
+and Workers can import it directly — no bundler and no strip-types needed (the 0.2.x "must bundle"
+requirement is retired). A source checkout can still run `src/` with `node --experimental-strip-types`.
+In browsers, inject the hash-wasm Argon2id carrier via `setArgonLoader()`; Node ≥ 24.7 uses the
+built-in `node:crypto`. See the code sample in the 使用 section above.
 
 **Honest limits.** The guest era is obfuscation-grade, not E2E. PH1 derivation is defined by each
 product (fast hash or Argon2id); this layer only validates its hex64 form. Product concerns

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')) };
+}