@tacet-ink/journal-core 0.1.6 → 0.2.1

package/README.md

@@ -13,6 +13,42 @@
 這是 [默·Tacet（tacet.ink）](https://tacet.ink) 的客戶端/伺服端核心原語層，
 從多個姊妹產品共用的密碼學本體抽取而成，以品牌前綴參數化（前綴契約見下表）。
 
+## Quickstart
+
+```sh
+git clone https://github.com/tacet-ink/journal-core.git && cd journal-core
+npm ci
+npm run verify   # 429 assertions, all green, run against the real modules (no mocks)
+```
+
+```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`
+
+完整 API 見[使用（Usage）](#使用usage)節。Live product: [https://tacet.ink](https://tacet.ink)
+（驗證頁：[https://tacet.ink/verify](https://tacet.ink/verify)）。
+
 ## 設計（Design）
 
 - **兩時代金鑰模型**：未綁定（guest）時代以 `K_u = SHA-256(guestKdfPrefix ‖ identity)`
@@ -23,24 +59,27 @@
   前綴全部可配置，AAD（防搬移綁結）由呼叫端傳入。
 - **extractable 鐵律**：要被 exportKey/wrap 的 key（noteKey 全部產生路徑），
   import 當下就必須 `extractable=true`；KEK/guest key 恆 nonextractable。
-- **opt-in 原語**：選配契約（cipherGuest／wrapDual／wrapShare／pinLock／cipherAttach／cipherLocal）
-  未配置即拒絕，各 fork 未選用的原語行為不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
-  解密面 guest 家族整面拒絕、不明字串與畸形空字串配置不當明文顯示）。
+- **opt-in 原語**：選配契約（cipherGuest／wrapDual／wrapShare／pinLock／cipherAttach／cipherLocal／
+  wrap4／wrapDual4／wrapLocal／wrapRec＋recKekHkdf（兩欄一體——同缺同在，部分配置拒寫）／recKekSalt）未配置＝回落語意（wrapRec 系照走舊契約面；其他面拒絕或退場），各 fork 未選用的原語行為不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
+  解密面 guest 家族整面拒絕、不明字串與畸形空字串配置不當明文顯示）。wrapLocal 為選配：
+  未配置＝寫面功能退場——v1 可用者（借用期部署）升級後需配置 wrapLocal 才保留本機包裹寫入
+  （讀取面照走舊形回落，零資料損失面）。
 
 ## 模組（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 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 傳入）：
@@ -51,22 +90,42 @@ 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` 欄 |
-| `jr1w.` | passphrase 包裹＋復原套件包裹 | PBKDF2-SHA256 600k | b64(iv[12] ‖ GCM(hex(noteKey)))，AAD `notekey` |
+| `jr1l.` | 本機包裹（PWA session 期免重打密語；選配） | deriveGuestKey＝K_u 同 guest 面（identity 派生、passphrase-free） | 同 jr1w. 形，AAD `notekey-local` |
+| `jr1r.` | 復原套件包裹（wrappedRec 專用；v0.2.0 批卡⑤，選配，與 recKekHkdf 兩欄一體） | HKDF-SHA256(ikm=recToken, salt=recKekSalt？, info=`journal-kek-rec-v1:`+recKekHkdf)——兩欄齊備才寫 jr1r. 面 | 同 jr1w. 形，AAD `notekey-rec`（部分配置拒寫；舊契約面 jr1w.＋PBKDF2＋AAD `notekey` 永不變——新世代讀舊寫新雙試） |
+| `jr1w.` | passphrase 包裹＋復原套件包裹（未配置世代） | PBKDF2-SHA256 600k（復原套件 KEK＝PBKDF2(recToken, recSaltPrefix‖identity)） | b64(iv[12] ‖ GCM(hex(noteKey)))，AAD `notekey`（復原套件與 passphrase 同 AAD 慣例＝未配置世代借形） |
 | `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   # 249 斷言對真模組（禁鏡像；限流單句 UPSERT…RETURNING 直載真 SQLite）：roundtrip/AAD 防搬移/
+npm run verify   # 429 斷言對真模組（禁鏡像；限流單句 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＋讀舊寫新自癒）
+                 # ＋復原套件專用前綴與 HKDF 世代 [20]（wrapRec=jr1r.＋recKekHkdf opt-in＋讀舊寫新雙試＋KAT）
+                 # ＋ladder 表與重取鹽面 [19]（ph2_ladder 原語／upsert 值主權威行為面／unwrapNoteKeyDual4WithSalt）
+                 # ＋常駐毒化矩陣 [16][18]（/tmp 拷貝樹突變重跑＝毒化證據隨每執行重建）
+                 # ＋KAT 凍結向量 [17]（HKDF info 域世代分離＋v3/raw 入口契約四 blob）
 ```
 
 - 產品碼**零執行時依賴**（WebCrypto 原語）；devDependencies 僅閘用（typescript、@scure/bip39 對照、workers types）。
@@ -96,6 +155,11 @@ const cfg = {
   cipherGuest: 'jr1g.',      // 換成你自己的品牌前綴家族
   cipherBound: 'jr1b.',
   wrap: 'jr1w.',
+  wrapLocal: 'jr1l.',       // 選配：本機包裹專用前綴（未配置 = 讀舊形回落、寫面退場）
+  // 復原套件 v0.2.0 世代（選配）：wrapRec+jr1r. 專用前綴＋recKekHkdf HKDF 派生
+  // （info='journal-kek-rec-v1:'+recKekHkdf；recKekSalt 16B hex 鹽域）。兩欄一體：
+  // 要開就兩欄一起配（部分配置＝ERR_REC_CFG_PARTIAL 拒寫）。兩欄皆缺席 =
+  // 行為不變態（jr1w.＋PBKDF2＋AAD 'notekey' 舊契約面照走，舊 blob 永遠可解）。
   store: makeKeyStore({ brand: 'myapp' }),
   // cipherGuest / wrapDual / wrapShare / pinLock / cipherAttach / cipherLocal：選配，未配置即拒絕
 };
@@ -106,16 +170,26 @@ const cipher = await encryptNote(cfg, held, '今天寫了一點東西。', 'note
 ```
 
 PH1 派生（登入憑證）：`derivePh1Argon(pass, saltArg?)` 預設鹽 `PH1_V2_SALT`
-（`'tacet-ph1-v1'`，Tacet 實例）。其他產品可自選**固定域鹽**傳入 `saltArg`——
+（`'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`）：拋 `ERR_PIN_EMPTY`——與
-  「功能未配置」（`ERR_DUAL_NOT_CONFIGURED`/`ERR_JR3W_NOT_CONFIGURED`）語意分離。
+- 空 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 不拋）不變。
@@ -134,7 +208,9 @@ hash-wasm 並以 `setArgonLoader()` 注入（詳 `src/client/argon2.ts` 檔頭
 
 ## 授權
 
-MIT。安全問題聯絡 tacetink.csd@gmail.com。
+版本歷史見 [CHANGELOG.md](./CHANGELOG.md)。
+
+MIT。安全問題聯絡 tacetink.csd@gmail.com（安全回報流程見 [SECURITY.md](./SECURITY.md)）。
 
 ## English Summary
 
@@ -154,15 +230,23 @@ and salted hashes, and never learns your passphrase or the content of any note.
   (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.
+  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`) are rejected unless explicitly configured, so forks that don't use
-a primitive are unaffected. Unknown or malformed strings never decrypt to plaintext.
+`cipherAttach` / `cipherLocal` / `wrap4` / `wrapDual4` / `wrapLocal` / `wrapRec` (paired with
+`recKekHkdf`: configured together or not at all; partial configuration is rejected on write) /
+`recKekHkdf` / `recKekSalt`): the wrapRec family falls back to the legacy face when unconfigured,
+so forks that don't use a primitive are unaffected. Unknown or malformed strings never
+decrypt to plaintext. `wrapLocal` is opt-in: unconfigured means the write face retires —
+v1-era deployments (borrow-period) must configure `wrapLocal` after upgrading to keep local
+key-wrap writes (the read face still falls back to the legacy blob; no data is lost).
 
 **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
@@ -172,7 +256,7 @@ PH1→PH2 login flow, inbound cipher/package validation and paired key-package s
 (`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 249 assertions against the real modules (no mocks):
+**Verification.** `npm run verify` runs 429 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacet-ink/journal-core",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Zero-knowledge journal core — e2e crypto, passphrase-only auth, transport, ratelimit. The server never sees plaintext.",
   "homepage": "https://tacet.ink",
   "repository": {
@@ -11,6 +11,20 @@
     "url": "https://github.com/tacet-ink/journal-core/issues"
   },
   "type": "module",
+  "keywords": [
+    "journal",
+    "diary",
+    "encryption",
+    "e2ee",
+    "end-to-end-encryption",
+    "argon2id",
+    "bip39",
+    "passphrase",
+    "zero-knowledge",
+    "webcrypto",
+    "privacy",
+    "tacet"
+  ],
   "main": "src/index.ts",
   "types": "src/index.ts",
   "sideEffects": false,
@@ -26,7 +40,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",
@@ -44,6 +59,6 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260831.1",
     "@scure/bip39": "^2.4.0",
-    "typescript": "~6.0.2"
+    "typescript": "~7.0.2"
   }
 }

package/scripts/open-card-pr.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# open-card-pr.sh — journal-core 同 repo card branch PR 產生器。
+#
+# Usage: open-card-pr.sh <branch> <title> <body-file>
+#   branch     card branch（head），例：card/<id>
+#   title      PR 標題
+#   body-file  PR body 純文字檔（完整讀入）
+#
+# 行為：純 curl POST /repos/tacet-ink/journal-core/pulls
+#   （head=<branch>、base=main、Token 取自 /srv/dropbox/csoft/tacet/.env 的
+#    GITHUB_TOKEN）。成功時 print PR 編號＋URL；僅 print，不做其他事
+#   （不 push branch、不合併、不關閉）。
+set -euo pipefail
+
+REPO_URL="https://api.github.com/repos/tacet-ink/journal-core/pulls"
+# 位置面：預設為本機絕對路徑（host-specific）；其他環境以 ENV_FILE 覆寫
+: "${ENV_FILE:=/srv/dropbox/csoft/tacet/.env}"
+
+BRANCH="${1:?usage: open-card-pr.sh <branch> <title> <body-file>}"
+TITLE="${2:?missing PR title}"
+BODY_FILE="${3:?missing body file}"
+
+[ -f "$BODY_FILE" ] || { echo "body file not found: $BODY_FILE" >&2; exit 1; }
+
+TOKEN="$(grep '^GITHUB_TOKEN=' "$ENV_FILE" | head -1 | cut -d= -f2-)"
+[ -n "$TOKEN" ] || { echo "GITHUB_TOKEN not found in $ENV_FILE" >&2; exit 1; }
+
+PAYLOAD="$(jq -n --arg title "$TITLE" --arg head "$BRANCH" --arg base main \
+  --rawfile body "$BODY_FILE" \
+  '{title: $title, head: $head, base: $base, body: $body}')"
+
+RESP="$(curl -sS -X POST \
+  -H "Authorization: token ${TOKEN}" \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  -d "$PAYLOAD" \
+  "$REPO_URL")"
+
+NUM="$(printf '%s' "$RESP" | jq -r '.number // empty')"
+if [ -n "$NUM" ]; then
+  URL="$(printf '%s' "$RESP" | jq -r '.html_url')"
+  echo "PR number: $NUM"
+  echo "PR url: $URL"
+else
+  # 失敗（422 常見＝branch 已有 PR／無 diff）：print API 訊息不做事
+  printf '%s' "$RESP" | jq -r 'if .message then .message
+    else . end' >&2
+  exit 1
+fi