@tacet-ink/journal-core 0.2.0 → 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)`
@@ -24,8 +60,10 @@
 - **extractable 鐵律**：要被 exportKey/wrap 的 key（noteKey 全部產生路徑），
   import 當下就必須 `extractable=true`；KEK/guest key 恆 nonextractable。
 - **opt-in 原語**：選配契約（cipherGuest／wrapDual／wrapShare／pinLock／cipherAttach／cipherLocal／
-  wrap4／wrapDual4／wrapLocal）未配置即拒絕，各 fork 未選用的原語行為不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
-  解密面 guest 家族整面拒絕、不明字串與畸形空字串配置不當明文顯示）。
+  wrap4／wrapDual4／wrapLocal／wrapRec＋recKekHkdf（兩欄一體——同缺同在，部分配置拒寫）／recKekSalt）未配置＝回落語意（wrapRec 系照走舊契約面；其他面拒絕或退場），各 fork 未選用的原語行為不受影響（cipherGuest 未配置時 bound 路徑不受牽連，
+  解密面 guest 家族整面拒絕、不明字串與畸形空字串配置不當明文顯示）。wrapLocal 為選配：
+  未配置＝寫面功能退場——v1 可用者（借用期部署）升級後需配置 wrapLocal 才保留本機包裹寫入
+  （讀取面照走舊形回落，零資料損失面）。
 
 ## 模組（Modules）
 
@@ -37,7 +75,7 @@
 | `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/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） |
 
@@ -53,7 +91,8 @@ Tacet 部署實例（config 傳入）：
 | `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` |
+| `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` |
@@ -78,11 +117,12 @@ jr3d/jr4d 兩入參數同輸入，域分離由 info 承載；凍結 KAT 兩 blob
 ## 驗證（Verification）
 
 ```sh
-npm run verify   # 384 斷言對真模組（禁鏡像；限流單句 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）
@@ -116,6 +156,10 @@ const cfg = {
   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：選配，未配置即拒絕
 };
@@ -164,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
 
@@ -194,9 +240,13 @@ and salted hashes, and never learns your passphrase or the content of any note.
   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.
+`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
@@ -206,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 384 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.2.0",
+  "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,
@@ -45,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