@tacet-ink/journal-core 0.3.3 → 0.3.5

package/README.md

@@ -10,43 +10,69 @@
 
 > **English**: Zero-knowledge journaling core — E2E-encrypted notes, passphrase-as-identity auth, transport & rate-limiting primitives. The server never sees a single word: the passphrase never crosses the wire, and all key wrapping and encryption happen client-side. See the [English summary](#english-summary) below.
 
+高階 Vault API（`client/vault`）：`createVault(pass, { app })` 零設定建 vault → 記錄包裹加解密 → 解鎖／24 詞復原 → PH1 登入憑證，一個子路徑走完。
+
 這是 [默·Tacet（tacet.ink）](https://tacet.ink) 的客戶端/伺服端核心原語層，
 從多個姊妹產品共用的密碼學本體抽取而成，以品牌前綴參數化（前綴契約見下表）。
 
-## Quickstart
+## Live demo
 
-```sh
-git clone https://github.com/tacet-ink/journal-core.git && cd journal-core
-npm ci --ignore-scripts
-npm run verify   # 522 assertions, all green, run against the real modules (no mocks); 0.3.3: 519 inside the published package ([21] SKIP line)
-```
+[https://tacet.ink/secret](https://tacet.ink/secret)：默·Tacet 的一次性分享站，也是本函式庫原語的線上演示。
+read-once（讀取一次即失效）、零帳號、免安裝；伺服器永不落明文：加密與解密都在瀏覽器端完成（端對端），
+密文經 AES-GCM-256 加密、連結 id 是 SHA-256 截斷（兩者皆與本函式庫同組 WebCrypto 原語、同一呼叫形）。單頁、無框架；
+原始碼在 Tacet 主 repo（private），頁尾另有[驗證頁](https://tacet.ink/verify)入口。
+
+**English**: Live demo: https://tacet.ink/secret. Read-once, zero-account, E2E secret sharing
+built on this library's WebCrypto primitives. Single-page, no framework.
+
+## Quickstart
 
 ```ts
-// example.ts
-import { makeHeldKey, generateNoteKey, encryptNote, decryptNote } from './src/index.ts';
-import { makeKeyStore } from './src/client/keys.ts';
+// example.mts
+import { createVault, unlockVault, recoverVault, deriveVaultPh1, isVaultError }
+  from '@tacet-ink/journal-core/client/vault';
+
+const PASS = 'correct horse battery staple';
+const cfg = { app: 'myapp', recovery: true };  // 零設定：全前綴由 app 推導（myapp1v./myapp4w./myapp1r.…）；recovery＝復原套件 opt-in
+
+// 1. 建 vault：隨機 noteKey＋Argon2id 密語包裹。serverRecord＝上傳伺服器的包裹欄；kit＝復原套件（只顯示一次）
+const { vault, serverRecord, recovery: kit } = await createVault(PASS, cfg);
+
+// 2. 記錄加解密：AAD 綁 app+recordId——密文搬到別筆 recordId 即 ERR_VAULT_DECRYPT
+const blob = await vault.encrypt('note-1', { title: '今天', body: '寫了一點東西。' });
+console.log(blob.slice(0, 8));                         // 'myapp1v.'
+console.log(await vault.decrypt('note-1', blob));      // { title: '今天', body: '寫了一點東西。' }
+
+// 3. 換裝置解鎖：密語＋伺服器帶回的 serverRecord（同一 cfg）
+const unlocked = await unlockVault(PASS, serverRecord, cfg);
+console.log(await unlocked.decrypt('note-1', blob));   // 同上
+try { await unlockVault('wrong passphrase', serverRecord, cfg); }
+catch (e) { console.log(isVaultError(e, 'ERR_VAULT_WRONG_PASSPHRASE')); }  // true（拋出碼恆 ERR_VAULT_WRAP_MISMATCH）
+
+// 4. 忘記密語：24 詞復原（伺服器存 kit.wrappedRec＋kit.recTokenHash；詞只給使用者抄寫）
+if (!kit) throw new Error('recovery kit missing');    // cfg 未開 recovery＝null
+console.log(kit.words.length);                         // 24
+const recovered = await recoverVault(kit.words, kit.wrappedRec, cfg);
+console.log(await recovered.decrypt('note-1', blob));  // 同上
+const newRecord = await recovered.changePassphrase('a new passphrase');  // 設新密語 → 覆存 serverRecord
+
+// 5. 登入憑證：PH1（hex64）上線、密語本體不過線；鹽＝per-product 固定域鹽（⚠️ 見下方「PH1 派生」節鹽域警告）
+const ph1 = await deriveVaultPh1(PASS, new TextEncoder().encode('myapp-ph1-v1'));
+console.log(ph1.length);                               // 64
+// server（fork 端，'@tacet-ink/journal-core/server/auth'）：return loginRouteCore(env, store, ip, ph1);
+```
 
-const cfg = {
-  guestKdfPrefix: 'myapp-note-u1',
-  recSaltPrefix: 'myapp-note-rec1:',
-  cipherGuest: 'jr1g.',      // your own brand prefix family (guest era, opt-in)
-  cipherBound: 'jr1b.',
-  wrap: 'jr1w.',
-  store: makeKeyStore({ brand: 'myapp' }),
-};
+run: `npm install @tacet-ink/journal-core && node example.mts`（0.3.4 起；Node ≥ 24.7——dist ESM 直載免 strip-types 旗標，`.mts` 不受 package.json `type` 影響；Argon2id 走內建 `node:crypto` 免注入 loader）
 
-const held = makeHeldKey();
-held.set(await generateNoteKey());             // bound era: random 256-bit noteKey
-const identity = { current: () => 'acct-xxxxxxxxxxxxxxxx' };
+源碼 clone 跑驗證閘：
 
-const cipher = await encryptNote(cfg, held, '今天寫了一點東西。', 'noteId:n1', identity);
-console.log(cipher.slice(0, 5));  // 'jr1b.' — ciphertext; nobody reads it without the key
-console.log(await decryptNote(cfg, held, cipher, 'noteId:n1', identity));  // '今天寫了一點東西。' — roundtrip
+```sh
+git clone https://github.com/tacet-ink/journal-core.git && cd journal-core
+npm ci --ignore-scripts
+npm run verify   # 531 assertions, all green, run against the real modules (no mocks); needs this repo checkout — the published package is dist-only since 0.3.4 (no gate, no src/, no scripts/)
 ```
 
-run: `node --experimental-strip-types example.ts`
-
-完整 API 見[使用（Usage）](#使用usage)節。Live product: [https://tacet.ink](https://tacet.ink)
+上例為高階 Vault API；錯誤碼見[例外契約](#例外契約錯誤碼語意)（`VaultError` 表）。低階原語範例（note-crypto 兩時代加解密、前綴自配）與完整 API 見[使用（Usage）](#使用usage)節。Live product: [https://tacet.ink](https://tacet.ink)
 （驗證頁：[https://tacet.ink/verify](https://tacet.ink/verify)）。
 安全回報流程見 [SECURITY.md](./SECURITY.md)、版本歷史見 [CHANGELOG.md](./CHANGELOG.md)。
 
@@ -80,8 +106,10 @@ run: `node --experimental-strip-types example.ts`
 | `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；
-`src/` 同包隨附（稽核／閱讀用，import 恆走 dist）。
+發行形（0.3.0 起）：`dist/`＝tsc 原生 emit 的 ESM `.js`＋`.d.ts`，`exports` 全部子路徑指向 dist。
+0.3.4 起發行包 dist-only：`files` 白名單恰 `dist`／`docs`／`migrations`／README／LICENSE——`src/`、`scripts/`
+不再隨包（驗證閘與向量產生器為 repo 樹面，走源碼 clone 動線）；稽核／閱讀路徑＝GitHub 瀏覽 `src/`＋
+[docs/format-spec.md](./docs/format-spec.md) 規格＋[docs/vectors/](./docs/vectors/) 向量（`docs/` 仍隨包）。
 
 ## 前綴契約（家族表：13 個資料前綴＋閘對照組 jr1g.）
 
@@ -124,7 +152,7 @@ jr3d/jr4d 兩入參數同輸入，域分離由 info 承載；凍結 KAT 兩 blob
 
 ```sh
 npm ci --ignore-scripts
-npm run verify   # 522 斷言對真模組（禁鏡像；限流單句 UPSERT…RETURNING 直載真 SQLite）：roundtrip/AAD 防搬移/
+npm run verify   # 531 斷言對真模組（禁鏡像；限流單句 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,7 +164,7 @@ npm run verify   # 522 斷言對真模組（禁鏡像；限流單句 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 直傳；
-                 #   522 帳＝repo 樹——發行包內無 .github＝[21] 四條 workflow 錨收斂為 1 顯性 SKIP 行→519（=522−3；消費端帳數真相源＝本行，隨版記帳——閘 SKIP 行摘死數字指回本行，0.3.3 實測），SKIP 顯形非靜默）
+                 #   531 帳＝repo 樹——workflow 錨在 .github＝repo 樹恆在、四條全跑；包內 SKIP 對照帳段隨 0.3.4 dist-only 瘦身退役：發行包不再帶閘＝無包內帳可言）
                  # ＋發行 tarball 治理面 [22]（pack 白名單零 open-card-pr.sh）
                  # ＋格式規格＋測試向量 [26]（docs/format-spec.md＋docs/vectors 存在性／位元組 shape／欄位名對規格／凍結 KAT 逐字對閘）
                  # ＋高階 Vault API [27]（roundtrip 三形／新舊前綴解鎖／upgrade／換密語／復原／VaultError 毒化／載體覆寫＋Worker 回退鏈／vendor 孿生）
@@ -162,6 +190,35 @@ import { makeKeyStore, makeHeldKey, generateNoteKey, encryptNote, decryptNote }
 // 或子路徑：'@tacet-ink/journal-core/client/note-crypto'
 ```
 
+低階原語最小 roundtrip（源碼 clone 形，import `./src/*`）：
+
+```ts
+// example.ts
+import { makeHeldKey, generateNoteKey, encryptNote, decryptNote } from './src/index.ts';
+import { makeKeyStore } from './src/client/keys.ts';
+
+const cfg = {
+  guestKdfPrefix: 'myapp-note-u1',
+  recSaltPrefix: 'myapp-note-rec1:',
+  cipherGuest: 'jr1g.',      // your own brand prefix family (guest era, opt-in)
+  cipherBound: 'jr1b.',
+  wrap: 'jr1w.',
+  store: makeKeyStore({ brand: 'myapp' }),
+};
+
+const held = makeHeldKey();
+held.set(await generateNoteKey());             // bound era: random 256-bit noteKey
+const identity = { current: () => 'acct-xxxxxxxxxxxxxxxx' };
+
+const cipher = await encryptNote(cfg, held, '今天寫了一點東西。', 'noteId:n1', identity);
+console.log(cipher.slice(0, 5));  // 'jr1b.' — ciphertext; nobody reads it without the key
+console.log(await decryptNote(cfg, held, cipher, 'noteId:n1', identity));  // '今天寫了一點東西。' — roundtrip
+```
+
+run: `node --experimental-strip-types example.ts`
+
+npm 安裝形（完整 cfg 欄位）：
+
 ```ts
 import { generateNoteKey, encryptNote, decryptNote, makeHeldKey,
          wrapNoteKey, unwrapNoteKey } from '@tacet-ink/journal-core/client/note-crypto';
@@ -199,7 +256,7 @@ raw 'PASS' 撞同一 ph2）。派生輸入吃 `normalizePassphrase`（NFKC-only
 大小寫差恆不同 ph2）；v2/legacy 派生面零變更（舊帳戶憑證 raw 契約）。兩代 ph2 可並存查表＝
 tacet 遷移層職責（v0.2.0 世代收口）。
 
-server 登入動線（fork 端）：`loginRouteCore(request-ish, store, ip, ph1)` 內建
+server 登入動線（fork 端）：`loginRouteCore(env, store, ip, ph1)` 內建
 ladder 查表守衛——現值 miss 時經 `AuthStore.ladderLookup`（optional）查 ph2_ladder，
 命中回舊帳不建幽靈、兩面 miss 才 `createUser`；未配置＝行為與 0.2.3 單查恆等。
 接法：store 實作 `ladderLookup`（tacet 參考形＝`SQL_FIND_PH2_LADDER_BY_OLD`＋fail-open
@@ -209,6 +266,20 @@ catch）＋套用 `migrations/0011-ph2-ladder.sql`（＋0012 索引修正）；
 把 v3 鹽域值餵 v2 派生（或 fork 把同一 saltArg 帶到兩面）＝NFKC-effective 密語與 v2 raw 密語
 同值撞 ph2，跨世代帳戶空間混合。v3 的 `saltArg` 必須異於本 product 的 v2 鹽域值。
 
+高階 Vault API 零設定前綴（`resolveVaultConfig`，0.3.4）：`createVault(pass, { app })` 最小設定
+——全前綴由 app 決定性推導：記錄密文 `<app>1v.`、寫面 `<app>4w.`／PIN `<app>4d.`、
+鹽域 `<app>3s:`、舊世代讀面 `<app>3w.`/`<app>3d.`/`<app>1w.`/`<app>2w.`/`<app>1s.`；
+`recovery: true` opt-in（復原套件 `<app>1r.`＋HKDF info 域 `<app>kek1`，recKekSalt 未指定＝
+零鹽契約照舊）——**未指定恆不推導**（零鹽選擇不可靜默）。app 契約 `^[A-Za-z0-9_-]+$`
+（前綴字面＝線上 ASCII 契約）＝**零設定路徑專載**——非契約 app 誤入零設定＝
+`ERR_VAULT_CONFIG` fail-closed 不猜；**顯式全配置路徑 app 字面照 0.3.3 既有契約零驗形**
+（非 ASCII／帶點 app 走顯式全配置照舊——契約閘不跨路徑加寬、顯式回歸 diff 恆 0）。
+**顯式路徑判別**：`argon` 或 `cipher` 任一在場＝顯式全配置路徑（resolver 零推導——既有
+五值手填契約照舊、顯式配置回歸 diff 恆 0）；半顯式態（argon 組推導＋`legacy` 物件槽顯式欄位）
+推導值與顯式值同進前綴互斥檢查（例 `legacy: { wrap: <app>4w.bait }` 與推導 `<app>4w.` 互為
+前綴＝拒——歧義配置不猜）。跨設定形前綴隔離照舊（推導包裹顯式設定不解、顯式包裹他設定不解
+＝`ERR_VAULT_WRAP_UNKNOWN`，app 即前綴契約域）。
+
 ### 例外契約（錯誤碼語意）
 
 **客戶端（client/）**
@@ -236,6 +307,31 @@ catch）＋套用 `migrations/0011-ph2-ladder.sql`（＋0012 索引修正）；
 | `ERR_ARGON2_TAGLEN` | Argon2id 載體 tag 非 32B（載體契約面） |
 | `ERR_ARGON2_UNAVAILABLE` | 無 Argon2id 載體（node<24.7 且無 hash-wasm 注入——禁 fallback） |
 
+**高階 Vault API（client/vault）**
+
+低階原語面不動（throw 'ERR_*' 字串錯誤＋unwrap 恆 null 的混態照舊）——只在 vault.ts／argon-auto.ts 邊界轉譯：高階 API 一律 throw VaultError，呼叫端以 `code` 分流，不比對 message。
+失敗面刻意不細分「密語錯」與「密文竄改」（同一 GCM 失敗——細分＝oracle）。
+
+`VaultError`（`e.code`）＋型別守衛 `isVaultError(e, code?)`：14 個拋出碼＋1 個查詢別名。
+
+| 錯誤碼 | 拋出面 |
+| --- | --- |
+| `ERR_VAULT_CONFIG` | 配置缺欄／畸形（app、cipher、argon.wrap4、recovery 兩欄一體…）——opt-in 未配置即拒 |
+| `ERR_VAULT_BAD_RECORD` | serverRecord 缺 wrapped/salt 欄或形不符（不猜） |
+| `ERR_VAULT_WRAP_UNKNOWN` | wrapped 前綴不屬任何已配置家族（未知世代／他產品前綴） |
+| `ERR_VAULT_WRAP_MISMATCH` | 家族辨識成功但解包失敗：密語／PIN 錯或包裹竄改（刻意不分） |
+| `ERR_VAULT_WRONG_PASSPHRASE` | 查詢別名（拋出面恆 WRAP_MISMATCH）：`isVaultError(e, 'ERR_VAULT_WRONG_PASSPHRASE')` 與查 `ERR_VAULT_WRAP_MISMATCH` 雙向等值；本 API 不拋此碼 |
+| `ERR_VAULT_PIN_REQUIRED` | 雙因子家族（jr2w./jr3d./jr4d. 形）缺 PIN |
+| `ERR_VAULT_BAD_PASSPHRASE` | 密語空值／非字串 |
+| `ERR_VAULT_BAD_PIN` | PIN 正規化後為空 |
+| `ERR_VAULT_KDF_UNSUPPORTED` | Argon2id 載體缺席或失效（zero-fallback：禁 PBKDF2／zeros 兜底） |
+| `ERR_VAULT_BAD_RECORD_ID` | recordId 非字串或空 |
+| `ERR_VAULT_BAD_DATA` | encrypt 資料形不支援（undefined、BigInt、循環 JSON、非 Uint8Array 的 ArrayBuffer 族…） |
+| `ERR_VAULT_BAD_BLOB` | 密文 blob 形不符（前綴／base64／長度／型別標記） |
+| `ERR_VAULT_DECRYPT` | 密文解密失敗：recordId（AAD）不符、金鑰不符或密文竄改（刻意不分） |
+| `ERR_VAULT_RECOVERY` | 復原套件形不符（recToken 非 hex64／24 詞不符、wrappedRec 前綴不符）或解包失敗 |
+| `ERR_VAULT_INTERNAL` | 未預期的低階錯誤（`cause` 帶原錯） |
+
 **伺服端（server/）＋閘**
 
 | 錯誤碼 | 拋出面 |
@@ -271,6 +367,17 @@ MIT。安全問題聯絡 security@tacet.ink（安全回報流程見 [SECURITY.md
 [默·Tacet (tacet.ink)](https://tacet.ink), a zero-knowledge journal: the server stores only ciphertext
 and salted hashes, and never learns your passphrase or the content of any note.
 
+**High-level Vault API.** `@tacet-ink/journal-core/client/vault` (0.3.4+) wraps the primitives in a
+single flow. `createVault(passphrase, { app: 'myapp', recovery: true })` derives every prefix from
+`app` (zero config), wraps a random note key with Argon2id, and returns the `serverRecord` to upload
+plus an opt-in 24-word recovery kit. `vault.encrypt(recordId, data)` / `vault.decrypt(recordId, blob)`
+bind each record to `app:recordId` as AAD, so a ciphertext moved to another record fails to decrypt.
+`unlockVault(passphrase, serverRecord, cfg)` reopens the vault on another device, and
+`recoverVault(words, wrappedRec, cfg)` reopens it from the recovery kit. `deriveVaultPh1(passphrase, salt)`
+produces the hex64 login credential your server passes to `loginRouteCore(env, store, ip, ph1)`.
+Failures throw a `VaultError` with a stable `code`; a wrong passphrase and a tampered wrap
+deliberately share one code, since telling them apart would create an oracle.
+
 **Security model.**
 
 - **Two key eras.** Before binding an account, notes are encrypted with a client-derived key
@@ -292,7 +399,7 @@ and salted hashes, and never learns your passphrase or the content of any note.
 - **Key hygiene.** Any key that must be exported/wrapped is imported with `extractable=true`;
   KEK and guest keys are permanently non-extractable.
 
-**Server login wiring.** `loginRouteCore(store, ip, ph1)` ships with the ladder guard built in
+**Server login wiring.** `loginRouteCore(env, store, ip, ph1)` ships with the ladder guard built in
 (v0.2.4, external-review #8 ghost-account fix): on a current-value (PH2) miss it consults the
 `ph2_ladder` table via the optional `AuthStore.ladderLookup` — a ladder hit returns the
 existing account (no ghost creation); a ladder miss, an unconfigured lookup, or a
@@ -318,8 +425,10 @@ carrier: `node:crypto` ≥ Node 24.7 / hash-wasm in browsers, RFC 9106 test vect
 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
 (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.
+package ships `dist/` (tsc-emitted ESM `.js` + `.d.ts`); every `exports` subpath resolves to dist.
+Since 0.3.4 the package is dist-only: `src/` and `scripts/` no longer ship (the tarball carries `dist/`,
+`docs/`, `migrations/`, README and LICENSE). To read or audit the source, browse `src/` on GitHub
+alongside the format spec and test vectors in `docs/`.
 
 **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
@@ -331,7 +440,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 522 assertions against the real modules (no mocks; 0.3.3: the in-package count is 519 because the [21] workflow anchors skip as one line):
+**Verification.** `npm run verify` runs 531 assertions against the real modules (no mocks; run it from a repo checkout — since 0.3.4 the published package is dist-only and carries no gate):
 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
@@ -341,7 +450,8 @@ spec and test vectors.
 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.
+built-in `node:crypto`. The Quickstart opens with a runnable Vault walkthrough (create → encrypt →
+unlock → recover → PH1); the low-level primitive samples are in the 使用 section.
 
 **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/bip39.d.ts

@@ -9,3 +9,36 @@ export declare function wordsToRecToken(input: string | string[]): Promise<strin
 export declare function recTokenToWords(recToken: string): Promise<string[] | null>;
 /** 抄寫抽驗位置：24 詞中抽 4 個不重複位置（0-23），排序回傳（顯示順序穩定）。 */
 export declare function spotCheckIndexes(): number[];
+/** 24 詞固定長 tuple（BIP39 英文——復原套件詞形契約面；wordsToRecToken/recTokenToWords 的載體形）。 */
+export type Bip39Words = [
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string
+];
+/**
+ * 詞形輸入正規化（normalizeWords 的公開收口）：字串形＝既有路（NFKC→trim→lower→split(/\s+/)→filter）；
+ * 陣列形＝每詞 NFKC→trim→lower 同構（wordsToRecToken 陣列腿同契約）、非字串元素入空串後濾除。
+ * 呼叫端：recoverVault 詞形入參先經此再走 wordsToRecToken——任何不符（錯數/詞表外/checksum）照舊 null。
+ */
+export declare function normalizeWordInput(input: string | string[]): string[];

package/dist/client/bip39.js

@@ -137,3 +137,15 @@ export function spotCheckIndexes() {
     }
     return pool.slice(0, 4).sort((a, b) => a - b);
 }
+/**
+ * 詞形輸入正規化（normalizeWords 的公開收口）：字串形＝既有路（NFKC→trim→lower→split(/\s+/)→filter）；
+ * 陣列形＝每詞 NFKC→trim→lower 同構（wordsToRecToken 陣列腿同契約）、非字串元素入空串後濾除。
+ * 呼叫端：recoverVault 詞形入參先經此再走 wordsToRecToken——任何不符（錯數/詞表外/checksum）照舊 null。
+ */
+export function normalizeWordInput(input) {
+    if (typeof input === 'string')
+        return normalizeWords(input);
+    return (Array.isArray(input) ? input : [])
+        .map((w) => (typeof w === 'string' ? w.normalize('NFKC').trim().toLowerCase() : ''))
+        .filter((w) => w.length > 0);
+}

package/dist/client/note-crypto.js

@@ -566,6 +566,12 @@ export async function encryptNote(cfg, held, plaintext, aad, idp) {
  *  不明字串一律 null＝guest 家族整面拒絕，跨前綴鐵律不降級）；失敗回 null。 */
 export async function decryptNote(cfg, held, cipher, aad, idp) {
     try {
+        // 空字串密文正規化（2026-10-18 t_b81f22cd 面1）：trim 後空＝拒（null）。
+        // 既有「無前綴＝舊明文原樣返回」相容層對 ''／純空白會原樣回傳＝空/空白密文
+        // 畸形進解密面、被當舊明文落 UI（truthiness 正規化缺失）。空/空白非合法舊明文，
+        // fail-closed 回 null（與本函式任何不符面同一 null 契約，不拋）；非空字串零影響。
+        if (cipher.trim() === '')
+            return null;
         // guest 前綴正規化：畸形配置 ''（空字串）會讓
         // startsWith('') 恆真＝bound 列誤導 guest 分支回 null（解密面整列滅失）。
         // falsy 一律收斂為 undefined，與加密面「未配置即拒」truthiness 對稱。

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

@@ -14,6 +14,10 @@ export type VaultErrorCode =
  | 'ERR_VAULT_WRAP_UNKNOWN'
 /** 家族辨識成功但解包失敗：密語／PIN 錯或包裹竄改（刻意不分）。 */
  | 'ERR_VAULT_WRAP_MISMATCH'
+/** 查詢別名字面：`isVaultError(e, 'ERR_VAULT_WRONG_PASSPHRASE')` 對 code === 'ERR_VAULT_WRAP_MISMATCH'
+ *  回 true（反之亦然）。拋出面零動——仍拋 WRAP_MISMATCH；失敗面刻意不細分密語錯／竄改
+ *  （同 GCM 失敗——細分＝oracle）。別名只在查詢面：本 union 判準仍以拋出碼為單一真相。 */
+ | 'ERR_VAULT_WRONG_PASSPHRASE'
 /** 雙因子家族（jr2w./jr3d./jr4d.）缺 PIN。 */
  | 'ERR_VAULT_PIN_REQUIRED'
 /** 密語空值／非字串。 */
@@ -40,5 +44,4 @@ export declare class VaultError extends Error {
         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

@@ -13,7 +13,14 @@ export class VaultError extends Error {
         this.code = code;
     }
 }
-/** 型別守衛：`isVaultError(e)` 或指定碼 `isVaultError(e, 'ERR_VAULT_DECRYPT')`。 */
+/** 型別守衛：`isVaultError(e)` 或指定碼 `isVaultError(e, 'ERR_VAULT_DECRYPT')`。
+ *  查詢別名（雙向）：`'ERR_VAULT_WRONG_PASSPHRASE'` 是 `'ERR_VAULT_WRAP_MISMATCH'` 的查詢面別名——
+ *  查詢帶別名、或錯誤實例帶別名（union 收了別名字面，手建實例可能），判定時兩側都投影到
+ *  拋出碼 WRAP_MISMATCH 再比；對其餘錯誤碼恆 false。拋出面恆 WRAP_MISMATCH（別名不產生第四碼形）。 */
+const VAULT_ERROR_CODE_ALIAS = 'ERR_VAULT_WRONG_PASSPHRASE';
+const canonVaultErrorCode = (c) => c === VAULT_ERROR_CODE_ALIAS ? 'ERR_VAULT_WRAP_MISMATCH' : c;
 export function isVaultError(e, code) {
-    return e instanceof VaultError && (code === undefined || e.code === code);
+    const q = canonVaultErrorCode(code);
+    const ec = e instanceof VaultError ? canonVaultErrorCode(e.code) : undefined;
+    return e instanceof VaultError && (q === undefined || ec === q);
 }

package/dist/client/vault.d.ts

@@ -1,5 +1,5 @@
 /**
- * vault.ts — 高階 Vault API：createVault／unlockVault／recoverVault → VaultHandle。
+ * vault.ts — 高階 Vault API：createVault／unlockVault／recoverVault → VaultHandle＋零設定前綴推導 resolver。
  *
  * 定位：低階原語（note-crypto.ts／argon2.ts）的**呼叫端**——additive-only，零改動原語語意。
  * 一個 vault＝一把隨機 256-bit noteKey（generateNoteKey）＋伺服器存的包裹欄（wrapped＋salt）
@@ -20,11 +20,48 @@
  *   tag：0x73 's'＝字串（body＝UTF-8）／0x6a 'j'＝JSON（body＝UTF-8(JSON.stringify)）／0x62 'b'＝位元組（body＝原樣）。
  */
 import { type Argon3Config } from './argon2.ts';
+import { type Bip39Words } from './bip39.ts';
 import { VaultError, isVaultError, type VaultErrorCode } from './vault-error.ts';
 import { type ArgonCarrierKind, type ArgonCarrierOptions } from './argon-auto.ts';
 export { VaultError, isVaultError, type VaultErrorCode };
 export { ensureArgonCarrier, currentArgonCarrier, resetArgonCarrier, DEFAULT_ARGON_CHAIN, type ArgonCarrierKind, type ArgonCarrierChoice, type ArgonCarrierOptions, type ArgonFallbackEvent, } from './argon-auto.ts';
 export { argonWorkerSource, createBlobArgonWorker, type ArgonWorkerLike } from './argon-worker.ts';
+/** 復原套件規格形（= 既顯式物件形；resolver 對 app 推導同形輸出——名稱是接線層措語，型別零新增）。 */
+export type VaultRecoverySpec = {
+    wrapRec: string;
+    recKekHkdf: string;
+    recKekSalt?: string;
+};
+/**
+ * resolveVaultConfig(input)：零設定前綴推導（resolver）。
+ * 輸入 `{ app, ...任意顯式欄位 }`，輸出完整 VaultConfig＋defaulted 旗標：
+ * `defaulted`＝真時 cipher/argon/legacy/recovery 四組**整組**由 app 決定性推導（10 欄，recovery opt-in 時含）——
+ * 命名自定（語意＝resolveVaultConfig：`{app}`＋零設定前綴推導）：前綴零手填、家族尾碼恆固定（契約三要素 app＋尾碼＋佈局；
+ * 帶內版本化：尾碼代即版本代，升級＝新尾碼；家族佈局不隨字面——README 前綴契約節同源）。
+ * `defaulted`＝假時輸入即顯式全配置（回歸 diff 恆 0——validateConfig 逐對檢查照守）。
+ *
+ * 推導表（app 契約 `^[A-Za-z0-9_-]+$`——前綴字面＝線上 ASCII 契約；**契約閘＝零設定（推導）路徑專載**：
+ * 零設定路徑上 app 在場但含契約外字元＝ERR_VAULT_CONFIG fail-closed 不猜；顯式全配置路徑
+ * app 字面照 0.3.3 既有契約零驗形（非 ASCII／帶點 app 走顯式全配置照舊）——契約閘不跨路徑加寬）：
+ *   cipher='foo1v.'／wrap4='foo4w.'／wrapDual4='foo4d.'／pinSalt3Prefix='foo3s:'（鹽域 ':' 同 tacet 形）
+ *   wrap3='foo3w.'／wrapDual3='foo3d.'／legacy wrap='foo1w.'／wrapDual='foo2w.'／pinSaltPrefix='foo1s.'
+ *   recovery（`recovery: true` 時）wrapRec='foo1r.'／recKekHkdf='fookek1'（KEK info 域帶 k 代——刻意
+ *   異於 wrapRec 字面：HKDF info 域與前綴域恆非前綴關係，鹽外置 payload 邊界不重疊）；
+ *   wrap3／wrapDual3 舊世代讀面同由 app 推導（`app + '3w.'`／`app + '3d.'`——app 族半顯式 legacy 槽的推導殘部）。
+ *   `foo`＝示例形；任兩推導值互不為前綴（startsWith 唯一性前提）；尾碼代＝家族表 README 行。
+ *
+ * 顯式路徑判別：`argon` 或 `cipher` 任一在場＝顯式全配置路徑（resolver 不再推導任何欄位——
+ * 顯式欄位優先、缺欄照 validateConfig 拒＝opt-in 母型；app 契約閘不跨路徑加寬——**契約閘＝
+ * 零設定路徑專載**（顯式全配置路徑 app 字面照 0.3.3 契約零驗；`resolveVaultConfig(opts)`
+ * 三入口單點接線共用）。
+ * recovery 物件形同判（呼叫端自管面）。半顯式態（argon 組推導＋legacy 物件槽顯式欄位共存）：
+ * 推導值與顯式值同進前綴互斥檢查（validateConfig——例 `legacy: { wrap: 'foo4w.bait' }` 與推導
+ * wrap4 'foo4w.' 互為前綴＝CONFIG 拒；歧義配置不猜。
+ */
+export declare function resolveVaultConfig(input: VaultOptions | VaultConfigInput): {
+    config: VaultConfig;
+    defaulted: boolean;
+};
 export interface VaultConfig {
     /** 應用域（AAD 前段）：記錄密文 AAD＝`<app>:<recordId>`。必填非空。 */
     app: string;
@@ -33,18 +70,37 @@ export interface VaultConfig {
     /** Argon2id 家族前綴：`wrap4` 必填（寫面）；`wrapDual4`＋`pinSalt3Prefix`＝PIN 寫面；
      *  `wrap3`／`wrapDual3`＝舊世代讀面（unlock＋upgrade 來源）。`wrapShare3` 本 API 不用。 */
     argon: Argon3Config;
-    /** PBKDF2 舊世代讀面（jr1w.＝`wrap`；jr2w.＝`wrapDual`＋`pinSaltPrefix`）。只讀不寫。 */
+    /** PBKDF2 舊世代讀面（jr1w.＝`wrap`；jr2w.＝`wrapDual`＋`pinSaltPrefix`）。只讀不寫。
+     *  `wrap: false`＝舊契約回落腿關閉（零設定 vault 預設語意——identity 綁域的 jr1w. 復原套件不屬本 API）。 */
     legacy?: {
-        wrap?: string;
+        wrap?: string | false;
         wrapDual?: string;
         pinSaltPrefix?: string;
     };
-    /** 復原套件（jr1r. HKDF 世代；兩欄一體）。未配置＝createVault 不產復原套件、recoverVault 拒。 */
-    recovery?: {
-        wrapRec: string;
-        recKekHkdf: string;
-        recKekSalt?: string;
-    };
+    /** 復原套件（jr1r. HKDF 世代；兩欄一體）。物件形＝顯式（呼叫端自管前綴與鹽域）；
+     *  true＝opt-in 零設定（wrapRec／recKekHkdf 由 resolver 以 app 推導；recKekSalt 未指定＝零鹽契約）；
+     *  false／undefined＝不產生復原套件（recoverVault 拒）。 */
+    recovery?: VaultRecoverySpec | boolean;
+}
+/** VaultConfigInput：resolveVaultConfig 輸入形（三入口共用——零設定 `{app}` 與顯式全配置同形進位；
+ *  pin／carrier＝入口進位欄，resolver 不消費）。 */
+export interface VaultConfigInput {
+    /** app 契約 `^[A-Za-z0-9_-]+$`：零設定路徑 fail-closed（缺 app 亦拒——推導無從）；顯式路徑放行顯式全配置。 */
+    app?: string;
+    /** 顯式記錄密文前綴（在場＝顯式全配置路徑——resolver 不推導）。 */
+    cipher?: string;
+    /** 顯式 Argon3 家族前綴組（在場＝顯式全配置路徑）。 */
+    argon?: Argon3Config;
+    /** 舊世代讀面 opt-in：true＝全推導；false／undefined＝falsable 預設 `{ wrap: false }`（wrap 舊契約回落腿關閉）；
+     *  物件形＝顯式欄位優先、缺欄由 app 推導（`wrap: false` 原樣保留）。 */
+    legacy?: VaultConfig['legacy'] | boolean;
+    /** 復原套件 opt-in：true＝resolver 推導（wrapRec＝`<app>1r.`、recKekHkdf＝`<app>kek1`、零鹽契約）；
+     *  物件形＝顯式（呼叫端自管前綴與鹽域——＝顯式路徑判別）；false／undefined＝無（recoverVault 拒）。 */
+    recovery?: VaultRecoverySpec | boolean;
+    /** PIN 第二因子（入口進位欄——resolver 不消費；VaultOptions 同欄）。 */
+    pin?: string;
+    /** Argon2id 載體選項（入口進位欄——resolver 不消費；VaultOptions 同欄）。 */
+    carrier?: ArgonCarrierOptions;
 }
 export interface VaultOptions extends VaultConfig {
     /** PIN 第二因子：create＝寫 jr4d.；unlock＝雙因子家族必帶。 */
@@ -60,6 +116,9 @@ export interface VaultServerRecord {
 /** 復原套件：recToken 只顯示一次（可經 bip39.ts 轉 24 詞）；伺服器存 wrappedRec＋recTokenHash。 */
 export interface VaultRecoveryKit {
     recToken: string;
+    /** 24 詞形（＝recTokenToWords(recToken) 的 BIP39 轉寫；伺服器零存——bip39 轉寫層可逆再導出；
+     *  recToken hex64 欄保留＝雙形相容既有 kit）。 */
+    words: Bip39Words;
     wrappedRec: string;
     recTokenHash: string;
 }
@@ -94,14 +153,34 @@ export interface VaultHandle {
         pin?: string;
     }): Promise<VaultServerRecord>;
 }
-/** 新 vault：隨機 noteKey＋最新家族包裹（pin＝jr4d.，否則 jr4w.）＋選配復原套件（jr1r.）。 */
-export declare function createVault(passphrase: string, opts: VaultOptions): Promise<{
+/**
+ * deriveVaultPh1(passphrase, ph1Salt)：高階 Vault API 的 PH1 登入憑證派生（hex64）。
+ * 本體委派 `derivePh1ArgonV3(pass, ph1Salt)`（PH1 v3：Argon2id(normalizePassphrase(pass), 鹽, m=64MiB, t=3, p=1)→hex64）
+ * ——語意單一真相同在 argon2.ts，本函式只是 vault 子路徑的入口收口位（呼叫端免跨 import argon2）。
+ *
+ * ⚠️ 契約三行（README PH1 節同款）：
+ * 1. 鹽一經選定恆固定（per-product）——PH2 UNIQUE 約束：同一密語必須恆生同一 PH2；
+ *    per-user 鹽會摧毀它。改鹽＝帶內版本化換鹽尾碼重遷移，禁原地改語意。
+ * 2. `PH1_V3_SALT`（'tacet-ph1-v2'）禁當 saltArg 餵 v2 派生面 `derivePh1Argon`——
+ *    反之亦然：同鹽域值跨面餵入＝NFKC-effective 密語與 v2 raw 密語同值撞 PH2（鹽撞位警告）。
+ * 3. 其他產品用自有鹽域——禁硬編 tacet 鹽當預設；必須顯式帶入 `ph1Salt`。
+ */
+export declare function deriveVaultPh1(passphrase: string, ph1Salt: Uint8Array): Promise<string>;
+/** 新 vault：隨機 noteKey＋最新家族包裹（pin＝<app>4d.，否則 <app>4w.）＋選配復原套件（<app>1r.）。
+ *  前綴零手填態（resolver）：`{ app }` 最小設定——全前綴由 app 決定性推導（resolveVaultConfig；
+ *  `recovery: true` opt-in、PIN 帶值＝同族尾碼推導 <app>4d. 不拒）；顯式 `argon`／`cipher` 在場
+ *  ＝顯式全配置路徑（零設定語意退出——缺欄照 validateConfig 拒）。輸入形 VaultOptions | VaultConfigInput。 */
+export declare function createVault(passphrase: string, opts: VaultOptions | VaultConfigInput): Promise<{
     vault: VaultHandle;
     serverRecord: VaultServerRecord;
     recovery: VaultRecoveryKit | null;
 }>;
 /** 解鎖：serverRecord（wrapped＋salt 成對）按前綴辨識家族（新→舊次序），舊世代照解；
- *  needsUpgrade() 為真時呼叫端可於同一動線 upgrade(passphrase) 靜默重包（Argon 遷移契約同構）。 */
-export declare function unlockVault(passphrase: string, serverRecord: VaultServerRecord, opts: VaultOptions): Promise<VaultHandle>;
-/** 復原：recToken（hex64）＋wrappedRec（jr1r.）→ handle（無包裹欄——呼叫端隨即 changePassphrase 設新密語）。 */
-export declare function recoverVault(recToken: string, wrappedRec: string, opts: VaultOptions): Promise<VaultHandle>;
+ *  前綴零手填態（resolver）：整組前綴缺省＝全前綴由 app 推導（resolveVaultConfig）；顯式欄位
+ *  在場＝顯式全配置路徑（零推導）。needsUpgrade() 為真時呼叫端可於同一動線
+ *  upgrade(passphrase) 靜默重包（Argon 遷移契約同構）。輸入形 VaultOptions | VaultConfigInput。 */
+export declare function unlockVault(passphrase: string, serverRecord: VaultServerRecord, opts: VaultOptions | VaultConfigInput): Promise<VaultHandle>;
+/** 復原：recToken（hex64）＋wrappedRec（<app>1r.）→ handle（無包裹欄——呼叫端隨即 changePassphrase 設新密語）。
+ *  前綴零手填態同上：recovery 未配置＝ERR_VAULT_CONFIG（零鹽選擇不可靜默——opt-in 鐵律；resolver 對
+ *  `recovery: true` 推導零鹽契約、物件形＝顯式零動）。輸入形 VaultOptions | VaultConfigInput。 */
+export declare function recoverVault(recToken: string | string[], wrappedRec: string, opts: VaultOptions | VaultConfigInput): Promise<VaultHandle>;