@tacet-ink/journal-core 0.1.5 → 0.2.0

package/README.md

@@ -8,37 +8,40 @@
 零知識日記核心：端對端加密、密語即身份的 auth、傳輸與限流原語。
 伺服器看不到任何一個字：passphrase 永不過線，密鑰包裹與密文都在客戶端完成。
 
+> **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.
+
 這是 [默·Tacet（tacet.ink）](https://tacet.ink) 的客戶端/伺服端核心原語層，
 從多個姊妹產品共用的密碼學本體抽取而成，以品牌前綴參數化（前綴契約見下表）。
 
-## 設計
+## 設計（Design）
 
 - **兩時代金鑰模型**：未綁定（guest）時代以 `K_u = SHA-256(guestKdfPrefix ‖ identity)`
   純客戶端派生（混淆級）；綁定後改用隨機 256-bit noteKey 加密，
   noteKey 再以 passphrase（KEK）與復原套件（KEK_rec）雙重包裹上傳。
   此後 passphrase 不再過線：線上只送 PH1（雜湊形），伺服器存 PH2 = SHA-256(PH1)。
 - **帶內版本化**：升級 KDF 參數 = 換新前綴（舊前綴照解、原地改語意是禁手）。
-  前綴全部可配置，AAD（防搬移繫結）由呼叫端傳入。
+  前綴全部可配置，AAD（防搬移綁結）由呼叫端傳入。
 - **extractable 鐵律**：要被 exportKey/wrap 的 key（noteKey 全部產生路徑），
   import 當下就必須 `extractable=true`；KEK/guest key 恆 nonextractable。
-- **opt-in 原語**：選配契約（cipherGuest／wrapDual／wrapShare／pinLock／cipherAttach／cipherLocal）
-  未配置即拒絕，各 fork 未選用的原語行為不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
+- **opt-in 原語**：選配契約（cipherGuest／wrapDual／wrapShare／pinLock／cipherAttach／cipherLocal／
+  wrap4／wrapDual4／wrapLocal）未配置即拒絕，各 fork 未選用的原語行為不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
   解密面 guest 家族整面拒絕、不明字串與畸形空字串配置不當明文顯示）。
 
-## 模組
+## 模組（Modules）
 
 | 模組 | 內容 |
 | --- | --- |
 | `src/client/note-crypto.ts` | 兩時代加解密、passphrase/復原套件/本機三路包裹、PIN 第二因子合鑰（jr2w.） |
-| `src/client/argon2.ts` | Argon2id 包裹原語（jr3w./jr3d./jr3s.）、PH1 v2 派生、RFC 9106 KAT、雙載體（node:crypto＋hash-wasm） |
+| `src/client/argon2.ts` | Argon2id 包裹原語（jr3w./jr3d./jr3s.＋密語正規化 v3 世代 jr4w./jr4d.）、PH1 v2/v3 派生、RFC 9106 KAT、雙載體（node:crypto＋hash-wasm） |
 | `src/client/pinlock.ts` | 本機 PIN 鎖定包裹（jr1p.，開啟時鎖定） |
 | `src/client/bip39.ts` | 復原套件 24 詞 ⇄ hex64 轉寫層（BIP39，零依賴自製） |
 | `src/client/keys.ts` | 品牌前綴 localStorage 命名空間 |
-| `src/server/auth.ts` | 零知識 auth 核心：PH1/PH2 hash-ladder、PH2 UNIQUE、session 撤銷、包裹欄組成對契約 |
-| `src/server/ratelimit.ts` | per-IP 滑動視窗限流（D1 計數，併發安全版） |
+| `src/server/auth.ts` | 零知識 auth 核心：PH1→PH2 login 動線、入庫格式驗證、包裹欄組成對（pair 檢查 pickKeyPackage）；PH2 UNIQUE 衝突與 session 撤銷＝呼叫端職責 |
+| `src/server/ladder.ts` | 密語正規化 v3 世代 ladder 表原語（ph2_ladder：以舊 ph2 查列／遷移入表 upsert 值主權威）——幽靈守衛的資料承载位（查表接線在 fork route） |
+| `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） |
 
-## 前綴契約（家族表：10 個資料前綴＋閘對照組 jr1g.）
+## 前綴契約（家族表：13 個資料前綴＋閘對照組 jr1g.）
 
 前綴是版本契約：payload 佈局與 KDF 由前綴界定，升級 = 新前綴。
 Tacet 部署實例（config 傳入）：
@@ -49,29 +52,48 @@ Tacet 部署實例（config 傳入）：
 | `jr1b.` | 綁定時代密文 | 隨機 256-bit noteKey | AES-GCM，AAD 綁 noteId |
 | `jr1c.` | 附件密文（image attachments；選配） | 同筆記金鑰（noteKey／guest key 由呼叫端決定） | AES-GCM，AAD `jr1a:<noteId>:<attachId>` |
 | `jr1d.` | 本機 IDB stored 密文（notes store；選配） | 同筆記金鑰（呼叫端注入） | AES-GCM，AAD 綁 note_id，payload 自帶 `v` 欄 |
+| `jr1l.` | 本機包裹（PWA session 期免重打密語；選配） | deriveGuestKey＝K_u 同 guest 面（identity 派生、passphrase-free） | 同 jr1w. 形，AAD `notekey-local` |
 | `jr1w.` | passphrase 包裹＋復原套件包裹 | PBKDF2-SHA256 600k | b64(iv[12] ‖ GCM(hex(noteKey)))，AAD `notekey` |
 | `jr2w.` | PIN 第二因子合鑰（PBKDF2 版） | PBKDF2 600k(pass)＋2M(pin) → HKDF-SHA256 | pinSalt[16] ‖ iv[12] ‖ GCM，108B，AAD `notekey2` |
 | `jr3w.` | passphrase 包裹（Argon2id 版） | Argon2id m=64MiB t=3 p=1 tag=32B | 同 jr1w. 形，AAD `notekey` |
 | `jr3d.` | PIN 第二因子合鑰（Argon2id 版） | Argon2id(pass)＋Argon2id(pin) → HKDF-SHA256 | 同 jr2w. 形，108B，AAD `notekey2` |
+| `jr4w.` | passphrase 包裹（密語正規化 v3 世代） | Argon2id(normalizePassphrase(pass)，NFKC-only) 同上參數 | 同 jr1w./jr3w. 形，AAD `notekey` |
+| `jr4d.` | PIN 第二因子合鑰（密語正規化 v3 世代） | Argon2id(normalizePassphrase(pass))＋Argon2id(pin) → HKDF-SHA256 | 同 jr2w./jr3d. 形，108B，AAD `notekey2` |
 | `jr3s.` | 單篇分享連結包裹 | Argon2id（同上參數） | 同 jr1w. 形，AAD `notekey-share` |
 | `jr1p.` | 本機 PIN 鎖定（開啟時鎖定） | PBKDF2-SHA256 600k（刻意不用 Argon2id：解鎖要即時） | 同 jr2w. 形，AAD `notekey-pinlock` |
 
 guest 密文前綴在閘對照組另驗 `jr1g.`（閘自造前綴，驗證品牌參數化本身；tacet 部署實例 guest 用 `jr1u.`）。
 跨前綴呼叫一律回 null（前綴守衛＋AAD＋長度把關），不拋、不降級。
 
-## 驗證
+**世代命名兩軸**（jr4w./jr4d. 起）：前綴數字軸＝KDF 世代代（jr1w→jr2w→jr3w→jr4w，
+KEK 輸入契約改變即換世代）；「v3 家族」文案＝PH1 規格代（PH1 v3 用 `derivePh1ArgonV3`）。
+密語正規化 v3 世代＝KEK 吃 `normalizePassphrase`（NFKC-only：不 trim、不分大小寫——
+大小寫摺疊禁絕＝大小寫差恆不同 KEK/ph2）——
+舊前綴家族（jr1w./jr3w./jr2w./jr3d.）契約面永不變（raw 密語派生，帶內版本化禁原地改語意）；
+跨前綴呼叫恆 null（家族隔離）。同密語寫法差（全形/NFD/NFC）在 v3 世代收容為同一 KEK/PH2，
+首尾空白與大小寫仍刻意分流（v3 契約只收容寫法差）。
+jr4d. 的 KEK2 HKDF info 域＝`'journal-kek2-v1:' + wrapDual4`（自有域——NFKC-effective 密語下
+jr3d/jr4d 兩入參數同輸入，域分離由 info 承載；凍結 KAT 兩 blob 互解 null 為證）。
+
+## 驗證（Verification）
 
 ```sh
-npm run verify   # 127 斷言對真模組（禁鏡像）：roundtrip/AAD 防搬移/extractable/時代隔離/
-                 # 跨前綴家族隔離/payload 竄改/RFC 9106 KAT/BIP39 @scure 對照 200 組
+npm run verify   # 384 斷言對真模組（禁鏡像；限流單句 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 鹽域分離＋帶內版本化舊契約向量）
+                 # + 本機包裹專用前綴（wrapLocal=jr1l. opt-in＋讀舊寫新自癒）
+                 # ＋ladder 表與重取鹽面 [19]（ph2_ladder 原語／upsert 值主權威行為面／unwrapNoteKeyDual4WithSalt）
+                 # ＋常駐毒化矩陣 [16][18]（/tmp 拷貝樹突變重跑＝毒化證據隨每執行重建）
+                 # ＋KAT 凍結向量 [17]（HKDF info 域世代分離＋v3/raw 入口契約四 blob）
 ```
 
 - 產品碼**零執行時依賴**（WebCrypto 原語）；devDependencies 僅閘用（typescript、@scure/bip39 對照、workers types）。
-- Argon2id 雙載體：node 走 `node:crypto`（Node 26+ 原生）、瀏覽器走 hash-wasm（wasm 內嵌），
+- Argon2id 雙載體：node 走 `node:crypto`（Node 24.7+ 原生）、瀏覽器走 hash-wasm（wasm 內嵌），
   RFC 9106 標準向量逐位元一致；無載體即 throw（禁 fallback 鐵律）。
 - BIP39 原語自製零依賴，與 @scure/bip39 參照 200 組雙向對照（僅 entropy↔words 轉寫層，禁用其 seed 派生）。
 
-## 使用
+## 使用（Usage）
 
 TypeScript 原始碼發行（exports 直指 .ts）。**注意**：Node 的 strip-types 不適用於
 node_modules 內的檔案，npm 安裝的消費者請走打包器；源碼 clone 可直接 node --experimental-strip-types。
@@ -85,6 +107,7 @@ import { makeKeyStore, makeHeldKey, generateNoteKey, encryptNote, decryptNote }
 import { generateNoteKey, encryptNote, decryptNote, makeHeldKey,
          wrapNoteKey, unwrapNoteKey } from '@tacet-ink/journal-core/client/note-crypto';
 import { makeKeyStore } from '@tacet-ink/journal-core/client/keys';
+import { derivePh1Argon } from '@tacet-ink/journal-core/client/argon2';
 
 const cfg = {
   guestKdfPrefix: 'myapp-note-u1',
@@ -92,6 +115,7 @@ const cfg = {
   cipherGuest: 'jr1g.',      // 換成你自己的品牌前綴家族
   cipherBound: 'jr1b.',
   wrap: 'jr1w.',
+  wrapLocal: 'jr1l.',       // 選配：本機包裹專用前綴（未配置 = 讀舊形回落、寫面退場）
   store: makeKeyStore({ brand: 'myapp' }),
   // cipherGuest / wrapDual / wrapShare / pinLock / cipherAttach / cipherLocal：選配，未配置即拒絕
 };
@@ -101,6 +125,33 @@ const identity = { current: () => 'acct-xxxxxxxxxxxxxxxx' };
 const cipher = await encryptNote(cfg, held, '今天寫了一點東西。', 'noteId:n1', identity);
 ```
 
+PH1 派生（登入憑證）：`derivePh1Argon(pass, saltArg?)` 預設鹽 `PH1_V2_SALT`
+（`'tacet-ph1-v1'`，Tacet 實例，raw pass）。其他產品可自選**固定域鹽**傳入 `saltArg`——
+鹽一經選定即 per-product 恆固定（PH2 UNIQUE 約束：同一密語必須恆生同一 PH2；
+per-user 鹽會摧毀幽靈帳號機制）。改鹽＝帶內版本化換鹽尾碼重遷移，禁原地改語意。
+
+PH1 v3（密語正規化世代）：`derivePh1ArgonV3(pass, saltArg?)` 預設鹽 `PH1_V3_SALT`
+（`'tacet-ph1-v2'`，新鹽域＝世代 ph2 命名空間分離——同鹽域會讓 v3 'ＰＡＳＳ' 與 v2 世代
+raw 'PASS' 撞同一 ph2）。派生輸入吃 `normalizePassphrase`（NFKC-only；大小寫摺疊禁絕＝
+大小寫差恆不同 ph2）；v2/legacy 派生面零變更（舊帳戶憑證 raw 契約）。兩代 ph2 可並存查表＝
+tacet 遷移層職責（v0.2.0 批卡②）。
+⚠️ 鹽撞位警告（MINOR-5）：`PH1_V3_SALT` 禁當 `derivePh1Argon` 的 `saltArg` 餵入（反之亦然）——
+把 v3 鹽域值餵 v2 派生（或 fork 把同一 saltArg 帶到兩面）＝NFKC-effective 密語與 v2 raw 密語
+同值撞 ph2，跨世代帳戶空間混合。v3 的 `saltArg` 必須異於本 product 的 v2 鹽域值。
+
+### 例外契約（錯誤碼語意）
+
+- 空 identity（guest 派生）：加密面拋 `ERR_NO_IDENTITY`、解密面回 `null`
+  （K_u = SHA-256(prefix ‖ '') 會靜默產出「空帳號金鑰」＝誤配炸彈，兩面皆 fail-closed）。
+- 空 PIN（`wrapNoteKeyDual`/`wrapNoteKeyDual3`/`wrapNoteKeyDual4`）：拋 `ERR_PIN_EMPTY`——與
+  「功能未配置」（`ERR_DUAL_NOT_CONFIGURED`/`ERR_JR3W_NOT_CONFIGURED`/`ERR_JR4W_NOT_CONFIGURED`/
+  `ERR_JR4D_NOT_CONFIGURED`）語意分離。
+- `hexToBytes` fail-closed：非法 hex（奇數長度/非 hex 字元/空字串）拋 `ERR_BAD_HEX`，
+  不再 parseInt 靜默歸零（假金鑰生產器）。unwrap 家族的 try/catch 承接＝跨前綴鐵律
+  （回 null 不拋）不變。
+- `PinLockConfig`：解包輸出的 noteKey 恆 `extractable=true`（鐵律，非可調選項）——
+  config 只帶三個前綴欄（pinLock/pinLockSaltPrefix/pinLockAad），缺任一即拒。
+
 打包器（vite/esbuild）可直接 alias 到源碼目錄使用；Argon2id 瀏覽器載體需另裝
 hash-wasm 並以 `setArgonLoader()` 注入（詳 `src/client/argon2.ts` 檔頭）。
 
@@ -114,3 +165,61 @@ hash-wasm 並以 `setArgonLoader()` 注入（詳 `src/client/argon2.ts` 檔頭
 ## 授權
 
 MIT。安全問題聯絡 tacetink.csd@gmail.com。
+
+## English Summary
+
+**What this is.** `@tacet-ink/journal-core` is the cryptographic and server-primitive layer powering
+[默·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.
+
+**Security model.**
+
+- **Two key eras.** Before binding an account, notes are encrypted with a client-derived key
+  `K_u = SHA-256(guestKdfPrefix ‖ identity)` (obfuscation-grade, not true E2E). After binding,
+  notes are encrypted with a random 256-bit noteKey. The noteKey is wrapped twice — with the
+  passphrase (KEK) and with a recovery package (KEK_rec) — before upload. From that point the
+  passphrase never crosses the wire: only PH1 (a client-side hash form) is transmitted, and the
+  server stores only `PH2 = SHA-256(PH1)`.
+- **In-band versioning.** Payload layout and KDF are defined by configurable cipher prefixes
+  (e.g. `jr1b.` for bound-era ciphertext, `jr3w.` for Argon2id-wrapped note keys). Upgrading KDF
+  parameters always means a new prefix; old prefixes keep decrypting forever (no in-place
+  semantic changes). Cross-prefix calls always return `null` — prefix guard + AAD + length
+  checks; they never throw or fall back. The passphrase-normalization generation follows the
+  same rule: `jr4w.`/`jr4d.` wrap with `normalizePassphrase` (NFKC-only — no trim, no
+  case-folding); older prefixes keep deriving from the raw passphrase, so every legacy payload
+  stays decryptable as-is.
+- **Tamper-evidence.** Every AES-GCM operation binds additional authenticated data (AAD) —
+  e.g. ciphertext is bound to its note id, so records cannot be shuffled between notes.
+- **Key hygiene.** Any key that must be exported/wrapped is imported with `extractable=true`;
+  KEK and guest keys are permanently non-extractable.
+
+**Opt-in primitives.** Optional contracts (`cipherGuest` / `wrapDual` / `wrapShare` / `pinLock` /
+`cipherAttach` / `cipherLocal` / `wrap4` / `wrapDual4` / `wrapLocal`) are rejected unless explicitly
+configured, so forks that don't use a primitive are unaffected. Unknown or malformed strings never
+decrypt to plaintext.
+
+**Modules.** Client: two-era crypto (`note-crypto.ts`), Argon2id wrapping (`argon2.ts`, dual
+carrier: `node:crypto` ≥ Node 24.7 / hash-wasm in browsers, RFC 9106 test vectors), local PIN lock
+(`pinlock.ts`), recovery-package BIP39 codec (`bip39.ts`, zero-dependency, cross-checked against
+@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 384 assertions against the real modules (no mocks):
+roundtrips, AAD tamper-evidence, extractability rules, era isolation, cross-prefix family
+isolation, payload tampering, RFC 9106 KAT, and a 200-vector BIP39 cross-check.
+
+**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.
+
+**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
+(routing, quotas, subscriptions, GC, webhooks) live in the product forks. No third-party audit
+yet. A lost passphrase is unrecoverable by design — that is the price of server-side zero
+knowledge.
+
+## License
+
+MIT. Security contact: tacetink.csd@gmail.com.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacet-ink/journal-core",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Zero-knowledge journal core — e2e crypto, passphrase-only auth, transport, ratelimit. The server never sees plaintext.",
   "homepage": "https://tacet.ink",
   "repository": {
@@ -13,6 +13,7 @@
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
     "./client/note-crypto": "./src/client/note-crypto.ts",
@@ -25,7 +26,8 @@
     "./server/ratelimit": "./src/server/ratelimit.ts",
     "./server/cors": "./src/server/cors.ts",
     "./server/hash": "./src/server/hash.ts",
-    "./server/env": "./src/server/env.ts"
+    "./server/env": "./src/server/env.ts",
+    "./server/ladder": "./src/server/ladder.ts"
   },
   "files": [
     "src",
@@ -34,10 +36,11 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=24.7.0"
   },
   "scripts": {
-    "verify": "node --experimental-strip-types scripts/verify-core-crypto.ts"
+    "verify": "node --experimental-strip-types scripts/verify-core-crypto.ts",
+    "typecheck": "tsc -p ."
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260831.1",