@tacet-ink/journal-core 0.1.6 → 0.2.1

package/src/client/note-crypto.ts

@@ -3,7 +3,7 @@
  *
  * 血統：抽取自姊妹專案的日記加密模組（37 斷言驗證閘母型）；
  * fork diff 已證實：除品牌前綴（guest KDF 前綴、密文前綴家族、KDF salt 前綴）
- * 與產品附加機制外，密碼學本體在多個產品間完全一致——本檔收編該本體。
+ * 與產品附加機制外，密碼學本體在多個產品間完全一致——本檔承載該本體。
  *
  * 兩時代金鑰模型（不變量，勿破壞）：
  *   時代 1（未綁定 guest）：K_u = SHA-256(guestKdfPrefix ‖ identity) — 純客戶端派生，混淆級
@@ -11,6 +11,11 @@
  *     KEK = PBKDF2(pass, salt, 600000, SHA-256) 包裹成 wrapped 上傳；復原套件 wrappedRec
  *     = 同款包裹在 KEK_rec = PBKDF2(recToken, salt = recSaltPrefix ‖ identity) 下。
  *     passphrase 從此不過線：線上憑證送 PH1（雜湊形，派生方式由各產品自定義），伺服器存 PH2。
+ *     復原套件 v0.2.0 世代：前綴專用化（wrapRec=jr1r.）＋KEK_rec 派生
+ *     世代化（recKekHkdf 配置＝HKDF-SHA256，info='journal-kek-rec-v1:'+recKekHkdf）＋
+ *     AAD 帶內切換（'notekey'→'notekey-rec'）；新世代讀舊寫新——unwrap 新面先行、回落
+ *     舊契約面（PBKDF2＋AAD 'notekey'）雙試（過渡保護承諾：舊 blob 永遠可解；摘雙試
+ *     時點＝遷移率裁定非日曆）。
  *
  * 前綴全部可配置（帶內版本化：升級 KDF 參數 = 換新前綴）。AAD 由呼叫端傳入——
  * 例如綁 `noteId`（跨列搬移必解密失敗）、`lifeId:day`（逐日日記）或留言綁 `tst:<lifeId>`。
@@ -27,12 +32,38 @@ export interface NoteCryptoConfig {
   guestKdfPrefix: string;
   /** 復原包裹 KDF salt 前綴，如 'journal-note-rec1:'。 */
   recSaltPrefix: string;
-  /** 密文前綴：guest 時代，如 'jr1g.'。未配置 = guest API 拒絕（未配置行為不變；2026-09-19 選配收編）。 */
+  /** 密文前綴：guest 時代，如 'jr1g.'。未配置 = guest API 拒絕（未配置行為不變；2026-09-19 轉選配）。 */
   cipherGuest?: string;
   /** 密文前綴：綁定時代，如 'jr1b.'。 */
   cipherBound: string;
   /** 金鑰包裹前綴，如 'jr1w.'。 */
   wrap: string;
+  /** 本機包裹前綴（jr1l.：本機包裹不再借用 cfg.wrap——「一個前綴一份契約」
+   *  的第二違例收口）。未配置 = storeLocalWrap/loadLocalWrap 退場（無寫入／讀取照走
+   *  舊形回落，零資料損失——cipherLocal opt-in 母型；寫面功能退場——v1 可用者升級後
+   *  需配置 wrapLocal 才保留本機包裹寫入）。 */
+  wrapLocal?: string;
+  /** 復原套件專用前綴（jr1r.：wrappedRec 不再借用 cfg.wrap——同前例收口）。
+   *  AAD 亦帶內切換 'notekey'→'notekey-rec'（共用 AAD 收口）。與 recKekHkdf **兩欄一體**
+   *  （同缺同在；部分配置＝ERR_REC_CFG_PARTIAL 拒寫——世代配對門，fail-closed 禁寫出
+   *  「前綴面 jr1r.×派生面 PBKDF2」跨契約 blob）。兩欄皆缺席 = wrap/unwrap 復原套件面
+   *  照走舊契約（cfg.wrap＋PBKDF2＋AAD 'notekey'）＝行為不變態（配置形正確
+   *  時舊 wrappedRec blob 永遠可解——HKDF 腿誤配拋點整面 fail-closed 既有契約）。 */
+  wrapRec?: string;
+  /** 復原套件「KEK 派生」世代開關：KEK_rec = HKDF-SHA256(
+   *  ikm = recToken（256-bit 實體因子）， salt = recKekSalt？:16B hex（未配置＝零鹽），
+   *  info = 'journal-kek-rec-v1:' + recKekHkdf, L = 32 )——info 合成名沿 argon2 家族
+   *  慣例（呼叫端帶入；KEK 派生世代空間由前綴＋info 承載）。HKDF 世代 identity 不入
+   *  KEK（identity-free by design——256-bit 實體因子足綁；identity 綁域由
+   *  舊契約面 recSaltPrefix‖identity 專屬承載，兩世代綁域刻意分離）。與 wrapRec 兩欄
+   *  一體（同缺同在；部分配置＝ERR_REC_CFG_PARTIAL 拒寫）。未配置 = PBKDF2 舊世代
+   *  （裁定：HKDF 強化屬 v0.2.0 世代；強度差異對 256-bit recToken 無意義，
+   *  收的是「派生域＋前綴契約面分離」的語意收口）。 */
+  recKekHkdf?: string;
+  /** HKDF salt：16B hex 專屬鹽域（與 PBKDF2 面 recSaltPrefix 前綴域分離
+   *  ——KEK 派生世代鹽）。未配置 = HKDF 零鹽（HKDF salt 欄位本就 optional；語意不變，
+   *  域由 info 承載）。 */
+  recKekSalt?: string;
   /** 雙因子合鑰包裹前綴（jr2w.，PIN 第二因子）。未配置 = dual API 拒絕（未配置行為不變）。 */
   wrapDual?: string;
   /** 雙因子 pin 段 PBKDF2 salt 前綴，如 'journal-note-pin1:'（pinSalt 內嵌 payload 後拼接）。 */
@@ -53,7 +84,7 @@ export const IV_LEN = 12;
 
 const HEX32_RE = /^[0-9a-f]{32}$/; // 16-byte salt hex
 /**
- * hex 合法性（fail-closed 目標 #2）：大小寫正規化後長度恰 2n（n bytes＝2 hex digits×n）＋
+ * hex 合法性（fail-closed）：大小寫正規化後長度恰 2n（n bytes＝2 hex digits×n）＋
  * 每雙位元組真 hex。
  */
 const HEX_RE = /^([0-9a-f][0-9a-f])+$/;
@@ -61,11 +92,11 @@ const HEX_RE = /^([0-9a-f][0-9a-f])+$/;
 // ── 基礎工具（export 供 argon2.ts 等同檔模組複用；語意不變） ─────────────────
 
 export function b64(bytes: Uint8Array): string {
-  // 分塊 String.fromCharCode.apply（t_7361b68c 目標 2：review 實測瀏覽器 4MiB 222ms→27ms；
-  // node 端分塊形 132-181ms→18ms，與閘執行帳同源——review 的 Node-only toBase64 1ms 帳是
-  // 不同形，非本體帳：round 2 MINOR-2 對齊）。瀏覽器端恆走本形——core 是 isomorphic TS
+  // 分塊 String.fromCharCode.apply（瀏覽器實測 4MiB 222ms→27ms；
+  // node 端分塊形 132-181ms→18ms，與閘執行帳同源——Node-only toBase64 的 1ms 帳是
+  // 不同形，非本體帳）。瀏覽器端恆走本形——core 是 isomorphic TS
   // 源碼發行，不引入 Node-only
-  // toBase64 分支（卡面否決案）。apply 參數上限安全窗 8192；輸出 byte 等價
+  // toBase64 分支（評估後否決的路線）。apply 參數上限安全窗 8192；輸出 byte 等價
   // （驗證閘 [14] 有 0/1/7/8191/8192/8193/65539 邊界逐位元組對照＋unb64 roundtrip）。
   let binary = '';
   for (let i = 0; i < bytes.byteLength; i += 8192) {
@@ -86,15 +117,15 @@ export function toHex(bytes: Uint8Array): string {
 }
 
 export function hexToBytes(hex: string): Uint8Array {
-  // fail-closed（目標 #2）：非法字元靜默歸零是 unwrap 家族的假金鑰生產器——
+  // fail-closed：非法字元靜默歸零是 unwrap 家族的假金鑰生產器——
   // 拋 ERR_BAD_HEX（呼叫端 unwrap 全部 try/catch 回 null；非 catch 端僅 bip39
   // HEX64_RE 前置自守）。奇數長度、非 hex、空字串皆拒；大小寫/全形 NFKC 收容。
-  // 測與 parse 同一（正規化後）真相——round 1 審查 MINOR-4：形檢吃正規化串、
+  // 測與 parse 同一（正規化後）真相——形檢吃正規化串、
   // parseInt 吃原始串＝全形 hex digit NaN 歸零殘形（README 例外契約自穿透），收口殲滅。
-  // NFKC 寬容＝設計面刻意（round 2 NIT 記錄 t_580f9c54）：'⑩'→'10' 等相容字元收容後是真 hex
+  // NFKC 寬容＝設計面刻意：'⑩'→'10' 等相容字元收容後是真 hex
   // 值（⑩→[16] 實帳），非缺陷形（NaN 歸零已殲滅＝輸出恆數學等值）；rawHex 檢查同式（HEX_RE 同行後置
   // ＝rawHex 前置守衛）；鹽欄同為同行後置（note-crypto/argon2 各 unwrap 面鹽欄形檢——行號帳不寫死，
-  // 新增段推移行號＝註解行號帳漂移，NIT-a 同病禁再犯）。
+  // 新增段推移行號＝註解行號帳漂移，同病禁再犯）。
   // 行為恆 null（純註解）；正式輸入面形檢在場，公開原語只保證「正規化後真 hex 恆等值、垃圾恆拒」。
   // 若要 ASCII-only 收緊＝帶內版本化（換前綴），禁原地改語意。
   const norm = hex.normalize('NFKC').toLowerCase();
@@ -127,7 +158,7 @@ export async function deriveGuestKey(cfg: NoteCryptoConfig, identity: string): P
 
 async function deriveKek(password: string, salt: Uint8Array): Promise<CryptoKey> {
   // 這裡的 importKey 是 deriveKey 用途集——與 derivePbkdf2Bits 的 deriveBits 面不是同一形，
-  // 禁共用 importKeyRawForKdf（usage 不符＝InvalidAccessError；t_7361b68c probe 實證）。
+  // 禁共用 importKeyRawForKdf（usage 不符＝InvalidAccessError；probe 實證）。
   const keyMat = await crypto.subtle.importKey('raw', new TextEncoder().encode(password) as BufferSource, 'PBKDF2', false, ['deriveKey']);
   return crypto.subtle.deriveKey(
     { name: 'PBKDF2', salt: salt as BufferSource, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
@@ -157,6 +188,20 @@ export function normalizePin(pin: string): string {
   return pin.normalize('NFKC').trim().toLowerCase();
 }
 
+/**
+ * 密語正規化契約 v3（NFKC-only 裁定）：NFKC——**大小寫摺疊禁絕：區分大小寫
+ * （大小寫差＝不同 KEK/ph2）＋首尾空白保留（不 trim）**。
+ * 消費面只有 v3 世代：jr4w./jr4d. 包裹家族與 PH1 v3（derivePh1ArgonV3）——
+ * 舊前綴家族（jr1w./jr3w./jr2w./jr3d.）契約面永不變（raw pass 派生，帶內版本化＝
+ * KEK 輸入契約改變＝換新前綴，禁原地改語意），禁把本函式接進舊家族入口。
+ * 與 normalizePin 契約並存不混（NFKC→trim→lowercase，pinlock/dual 面不動）：
+ * 兩函式是正交契約，閘有「同輸入不同輸出」行為向量承載分離。
+ * 三面單一真相：本體（此處）＋README 家族表＋驗證閘 [15] 行為向量——改 NFKC 語意＝帶內版本化（換世代），禁原地改。
+ */
+export function normalizePassphrase(passphrase: string): string {
+  return passphrase.normalize('NFKC');
+}
+
 async function derivePbkdf2Bits(password: string, salt: Uint8Array, iterations: number): Promise<Uint8Array> {
   const km = await importKeyRawForKdf(password);
   const bits = await crypto.subtle.deriveBits({ name: 'PBKDF2', salt: salt as BufferSource, iterations, hash: 'SHA-256' }, km, 256);
@@ -164,12 +209,12 @@ async function derivePbkdf2Bits(password: string, salt: Uint8Array, iterations:
 }
 
 async function deriveKek2(cfg: NoteCryptoConfig, passphrase: string, pin: string, salt1: Uint8Array, pinSalt: Uint8Array): Promise<CryptoKey> {
-  // pass 段與 pin 段 PBKDF2 相互獨立（不同 salt/密碼不同鹽源）＝可並行（t_7361b68c 目標 1）。
+  // pass 段與 pin 段 PBKDF2 相互獨立（不同 salt/密碼不同鹽源）＝可並行。
   // ⚠️ 瀏覽器 hash-wasm Argon2（jr3d. 對應形 deriveKek2Argon）禁並行——純 wasm Argon2id
-  // 共享記憶體池、兩實例並行在部分引擎靜態直 throw，卡面 review 明示；並行只收 PBKDF2 家族。
-  // 兩段各自 importKeyRawForKdf（round 2 NIT-2：keyMat 參數化退場——pass/pin 段絕不共享 PBKDF2 基材）。
+  // 共享記憶體池、兩實例並行在部分引擎靜態直 throw（設計已明示）；並行只收 PBKDF2 家族。
+  // 兩段各自 importKeyRawForKdf（keyMat 參數化退場——pass/pin 段絕不共享 PBKDF2 基材）。
   // 輸出序＝ikm 組裝序＝passBits@0 ‖ pinBits@32（與原串行逐位一致）；閘錨綁左手側 destructure，
-  // 對調滑接＝既有 jr2w. 帳戶全不可解（round 2 MAJOR-1 reviewer rev-harm 一手實證）。
+  // 對調滑接＝既有 jr2w. 帳戶全不可解（一手實證）。
   const [passBits, pinBits] = await Promise.all([
     derivePbkdf2Bits(passphrase, salt1, PBKDF2_ITERATIONS),
     derivePbkdf2Bits(pin, new TextEncoder().encode(cfg.pinSaltPrefix + toHex(pinSalt)), PIN_PBKDF2_ITERATIONS),
@@ -194,7 +239,7 @@ const DUAL_IV_LEN = 12;
 export async function wrapNoteKeyDual(cfg: NoteCryptoConfig, noteKey: CryptoKey, passphrase: string, pin: string): Promise<{ wrapped: string; salt: string }> {
   if (!cfg.wrapDual || !cfg.pinSaltPrefix) throw new Error('ERR_DUAL_NOT_CONFIGURED');
   const pinNorm = normalizePin(pin);
-  if (!pinNorm) throw new Error('ERR_PIN_EMPTY'); // 空 PIN ≠ 未配置（t_7710c766 語意分離）
+  if (!pinNorm) throw new Error('ERR_PIN_EMPTY'); // 空 PIN ≠ 未配置（語意分離）
   const salt1 = crypto.getRandomValues(new Uint8Array(16));
   const pinSalt = crypto.getRandomValues(new Uint8Array(DUAL_SALT_LEN));
   const kek2 = await deriveKek2(cfg, passphrase, pinNorm, salt1, pinSalt);
@@ -338,8 +383,11 @@ export function recTokenHash(recToken: string): Promise<string> {
 const NOTEKEY_HEX_LEN = 64;
 
 /**
- * 共用包裹核心（目標 #1 收口）：prefix + b64(iv[12] ‖ GCM(KEK, hex(noteKey), aad))。
- * 全家族單因子包裹（jr1w./jrsw./jr3w./jr3s.）與復原套件（wrappedRec，前綴共用 cfg.wrap）
+ * 共用包裹核心（收口）：prefix + b64(iv[12] ‖ GCM(KEK, hex(noteKey), aad))。
+ * 鹽外置家族字首家系清點（七呼叫端）：jr1w.（wrapNoteKey）/jrsw.
+ *（wrapNoteKeyShare）/jr3w.（wrapNoteKey3）/jr4w.（wrapNoteKey4）/jr3s.
+ *（wrapNoteKeyShare3）/jr1l.（storeLocalWrap）/jr1r.＋jr1w.（wrapNoteKeyWithRecToken——
+ * HKDF 世代專用前綴＋AAD 'notekey-rec'、未配置世代 legacy 面＝cfg.wrap＋AAD 'notekey'）
  * 同一本體；KDF 差異在呼叫端 KEK、payload 形狀（salt 外置 vs 內嵌）由各家族維持。
  * prefix null/undefined＝未配置拒絕（呼叫端亦可先行拒絕，帶自家錯誤碼形；雙防線）。
  */
@@ -351,14 +399,17 @@ export async function sealNoteKey(prefix: string | null | undefined, noteKey: Cr
 }
 
 /**
- * 共用解包核心（目標 #1 收口）：任何不符——前綴、base64 形、payload 長度、
+ * 共用解包核心（收口）：任何不符——前綴、base64 形、payload 長度、
  * GCM（金鑰/AAD/密文損壞）、rawHex 長度/hex 形——恆回 null 不拋。
- * round 1 審查 MINOR-5：atob 對非法字元會拋、原 docstring「不拋」與實作不符——
+ * 修正紀錄：atob 對非法字元會拋、原 docstring「不拋」與實作不符——
  * 本體吞收 null（公開原語誠實契約；呼叫端 unwrap 家族 try/catch 是雙防線非依賴面）。
- * 家族嚴格度收口實況（round 1 審查 MINOR-2 校正＋r2 MINOR-1 殘餘校正 t_580f9c54）：
- * 鹽外置 6 點由本體嚴格 92B 終結——note-crypto 四點（unwrapNoteKey＝jr1w／
- * unwrapNoteKeyShare＝jrsw／unwrapNoteKeyWithRecToken＝jr1wRec 同本體／loadLocalWrap）
- * ＋argon2 兩點（unwrapNoteKey3＝jr3w／unwrapNoteKeyShare3＝jr3s；own 92B 檢已隨收口摘除）；
+ * 家族嚴格度收口實況（校正＋殘餘校正；
+ * 七呼叫端帳同步——鹽外置家族字首家系清點，6 點帳已過期）：
+ * 本體嚴格 92B 終結七呼叫端＝note-crypto 四點（unwrapNoteKey＝jr1w／
+ * unwrapNoteKeyShare＝jrsw／unwrapNoteKeyWithRecToken（legacy 面 jr1w.／HKDF 面 jr1r.）
+ * ／loadLocalWrap＝jr1l.）
+ * ＋argon2 三點（unwrapNoteKey3＝jr3w／unwrapNoteKey4＝jr4w／unwrapNoteKeyShare3＝jr3s；
+ * own 92B 檢已隨收口摘除）；
  * 鹽內嵌 3 點（jr2w/jr3d/jr1p）own 108B＋rawHex 形檢——與本體同嚴格度、刻意不經本體
  * （pinSalt 前綴不在鹽外置形契約內）。維護本體時鹽內嵌三族不隨行。
  */
@@ -426,32 +477,83 @@ export async function unwrapNoteKeyShare(cfg: NoteCryptoConfig, wrapped: string,
   }
 }
 
-/** 復原套件包裹：KEK_rec = PBKDF2(recToken, salt = recSaltPrefix ‖ identity)。 */
-async function deriveRecKek(cfg: NoteCryptoConfig, recToken: string, identity: string): Promise<CryptoKey> {
-  return deriveKek(recToken, new TextEncoder().encode(cfg.recSaltPrefix + identity));
+/** 復原套件 KEK 派生：HKDF 專責（本體只承載 recKekHkdf 配置世代——
+ *  呼叫端須先過世代配對門）。KEK_rec = HKDF-SHA256(
+ *    ikm = recToken（TextEncoder UTF-8；recToken 恆 hex64 256-bit 實體因子），
+ *    salt = recKekSalt？(16B hex → 16 raw bytes；未配置＝零鹽)，
+ *    info = 'journal-kek-rec-v1:' + recKekHkdf, L = 32 )——輸出 AES-GCM 256 nonextractable。
+ *  HKDF 世代 identity 不入 KEK（identity-free by design——256-bit 實體因子足綁；
+ *  identity 綁域由舊契約面 recSaltPrefix‖identity 專屬承載，兩世代綁域刻意分離）。
+ *  強度語意：recToken 256-bit 實體因子，KDF 強度無意義——收的是
+ *  派生域（HKDF info）＋前綴契約面（jr1r.）的世代分離；非防爆破強化帳。
+ *  鹽域二分（鹽家族）：HKDF salt 屬「派生面內嵌 cfg、payload 零內嵌」——
+ *  92B 帳純粹來自 hex(noteKey) 64B＋iv 12＋tag 16（pinSalt 內嵌 payload 是 jr2w./jr3d.
+ *  鹽內嵌族的事，不入此帳）。PBKDF2 舊世代派生＝deriveRecLegacyKek（單一本體，檢查對齊
+ *  收口：deriveRecKek 禁 PBKDF2 fallback——派生源雙模＝C2 缺口形）。 */
+async function deriveRecKek(cfg: NoteCryptoConfig, recToken: string): Promise<CryptoKey> {
+  const hkdfTail = cfg.recKekHkdf as string;
+  const info = 'journal-kek-rec-v1:' + hkdfTail;
+  if (cfg.recKekSalt && !HEX32_RE.test(cfg.recKekSalt)) throw new Error('ERR_REC_KEK_SALT');
+  const salt = cfg.recKekSalt ? hexToBytes(cfg.recKekSalt) : new Uint8Array(0);
+  const hkdfBase = await crypto.subtle.importKey('raw', new TextEncoder().encode(recToken) as BufferSource, 'HKDF', false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: salt as BufferSource, info: new TextEncoder().encode(info) as BufferSource },
+    hkdfBase,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
 }
 
 export async function wrapNoteKeyWithRecToken(cfg: NoteCryptoConfig, noteKey: CryptoKey, recToken: string, identity: string): Promise<string> {
-  const kek = await deriveRecKek(cfg, recToken, identity);
+  // 世代配對門（檢查對齊 C1/C2 收口）：一前綴一份契約補完。
+  // 禁寫面＝「前綴面 jr1r.×派生面 PBKDF2」（wrapRec-only，C1：寫得出讀不回）與
+  // 「前綴面 jr1w.×派生面 HKDF」（HKDF-only，C2：借 jr1w. 前綴 carrying 第二派生、
+  // 升級即失資料）——兩面都由部分配置自然接線產生，門 fail-closed 拒寫。
+  if (cfg.wrapRec || cfg.recKekHkdf) {
+    if (!cfg.wrapRec || !cfg.recKekHkdf) throw new Error('ERR_REC_CFG_PARTIAL');
+    const kek = await deriveRecKek(cfg, recToken);
+    return sealNoteKey(cfg.wrapRec, noteKey, kek, 'notekey-rec');
+  }
+  // 未配置世代（兩欄皆缺席＝legacy 契約面永不變）：cfg.wrap＋PBKDF2＋AAD 'notekey'
+  //（既有向量 byte 不變；cfg.wrap 缺席由 sealNoteKey 守衛承載——雙防線）。
+  const kek = await deriveRecLegacyKek(cfg, recToken, identity);
   return sealNoteKey(cfg.wrap, noteKey, kek, 'notekey');
 }
 
 export async function unwrapNoteKeyWithRecToken(cfg: NoteCryptoConfig, wrapped: string, recToken: string, identity: string): Promise<CryptoKey | null> {
   try {
+    // 次序契約：jr1r. 面只在兩欄齊備時試（HKDF 專責派生——cfg.wrap 面零 HKDF 腿，
+    // jr1w. 前綴只 carrying passphrase-PBKDF2 派生：「一個前綴一份契約」第二違例收口）。
+    if (cfg.wrapRec && cfg.recKekHkdf) {
+      const recKek = await deriveRecKek(cfg, recToken);
+      const fresh = await openNoteKey(wrapped, recKek, 'notekey-rec', cfg.wrapRec);
+      if (fresh) return fresh;
+    }
+    // 舊面回落（過渡保護）：cfg.wrap 在場即試（部分配置讀面照走——寫面已被配對門
+    // 拒，讀面寬容＝舊 blob 永遠可解的承載面）。
     if (!cfg.wrap) return null;
-    const kek = await deriveRecKek(cfg, recToken, identity);
-    return await openNoteKey(wrapped, kek, 'notekey', cfg.wrap);
+    const legacyKek = await deriveRecLegacyKek(cfg, recToken, identity);
+    return await openNoteKey(wrapped, legacyKek, 'notekey', cfg.wrap);
   } catch {
     return null;
   }
 }
 
+/** 舊契約派生本體（legacy 派生全案單一本體）：PBKDF2(recToken,
+ *  salt = recSaltPrefix ‖ identity)——永不變（配置形正確時既有 wrappedRec
+ *  blob 逐位可解）。寫面未配置世代與讀面回落同源呼叫本體；deriveRecKek 改 HKDF 專責
+ *  （檢查對齊 C2 收口：HKDF 派生禁借 cfg.wrap 前綴面，派生源不再雙模）。 */
+async function deriveRecLegacyKek(cfg: NoteCryptoConfig, recToken: string, identity: string): Promise<CryptoKey> {
+  return deriveKek(recToken, new TextEncoder().encode(cfg.recSaltPrefix + identity));
+}
+
 /**
  * 綁定請求的金鑰包裹三件套（bind 用）+ recovery_token_hash。
  * 兩段 600k PBKDF2 相互獨立（pass 鹽隨機、rec 鹽=recSaltPrefix‖identity 定值）＝並行
- *（t_7361b68c 目標 1：node 實測 133-152ms→68-84ms，與閘執行帳同源——round 2 MINOR-2 對齊）。
+ *（node 實測 133-152ms→68-84ms，與閘執行帳同源）。
  * AES-GCM derive 佔 600k 迴圈 99%，兩段 wrapped 各自隨機 iv（pass 段另隨機鹽 16B；rec 腿
- * KEK 鹽定值、回傳 salt 來自 pass 腿 w1——round 2 MINOR-2 措辭修正）——逐位等值帳由
+ * KEK 鹽定值、回傳 salt 來自 pass 腿 w1）——逐位等值帳由
  * 「兩段各自與 wrapNoteKey 直呼相等」承載。
  */
 export async function buildBindPayload(
@@ -475,11 +577,23 @@ export async function buildBindPayload(
 
 // ── 本機包裹（PWA session 期免重打密語） ─────────────────────────────────────
 
+/**
+ * 本機包裹：KEK = deriveGuestKey（identity 派生、passphrase-free——
+ * session 期免重打密語的機制原樣），payload 改走專用前綴 cfg.wrapLocal（jr1l.）。
+ * 舊實作借用 cfg.wrap（jr1w. passphrase 包裹前綴）寫本機包裹＝「一個前綴一份契約」
+ * 的第二違例（wrappedRec 專用前綴歸 v0.2.0 世代收口）：本機包裹的 KDF 與 caller 不同、
+ * 儲存面（localStorage）不同、生命週期不同（clearLocalWrap 隨時摘除）——共前綴讓
+ * 「本機字串是否可能誤入 server 包裹欄」對帳失真。新前綴＝讀舊寫新自癒：
+ * loadLocalWrap 先試 jr1l.（本體嚴格面），命中舊形（jr1w.）回落解密後即重包
+ * cfg.wrapLocal 回寫（自癒一次），寫入恆 jr1l.。
+ */
 export async function storeLocalWrap(cfg: NoteCryptoConfig, identity: string, noteKey: CryptoKey): Promise<void> {
   try {
-    if (!cfg.wrap) throw new Error('ERR_WRAP_NOT_CONFIGURED');
+    // 寫入恆專用前綴 cfg.wrapLocal（jr1l.；未配置＝無寫入退場，讀取面照走舊形回落——
+    // 行為不變態）。單一真相：loadLocalWrap 自癒腿經本函式回寫（前綴契約不二寫）。
+    if (!cfg.wrapLocal) return;
     const guest = await deriveGuestKey(cfg, identity);
-    const wrapped = await sealNoteKey(cfg.wrap, noteKey, guest, 'notekey-local');
+    const wrapped = await sealNoteKey(cfg.wrapLocal, noteKey, guest, 'notekey-local');
     cfg.store.set(cfg.store.noteKeyWrap(identity), wrapped);
   } catch { /* private mode：不阻擋主流程 */ }
 }
@@ -487,9 +601,23 @@ export async function storeLocalWrap(cfg: NoteCryptoConfig, identity: string, no
 async function loadLocalWrap(cfg: NoteCryptoConfig, identity: string): Promise<CryptoKey | null> {
   try {
     const stored = cfg.store.get(cfg.store.noteKeyWrap(identity));
-    if (!stored || !cfg.wrap) return null;
+    if (!stored) return null;
     const guest = await deriveGuestKey(cfg, identity);
-    return await openNoteKey(stored, guest, 'notekey-local', cfg.wrap);
+    // 次序契約：新形必先於舊形試——新形 blob 在舊前綴面恆拒（family isolation）；先新後舊
+    // 仍是要件（新形命中即不跑舊解包），但兩前綴互斥 startsWith 下單一三元只有一腿成立，
+    // 實際次序不可觀察。
+    const fresh = cfg.wrapLocal
+      ? await openNoteKey(stored, guest, 'notekey-local', cfg.wrapLocal) // 本體嚴格面（92B＋rawHex hex 形）
+      : null;
+    if (fresh) return fresh;
+    const legacy = cfg.wrap
+      ? await openNoteKey(stored, guest, 'notekey-local', cfg.wrap)
+      : null;
+    if (legacy) {
+      await storeLocalWrap(cfg, identity, legacy);
+      return legacy;
+    }
+    return null;
   } catch {
     return null;
   }
@@ -534,7 +662,7 @@ export async function encryptNote(
     return cfg.cipherBound + await encryptWithKey(held.get()!, plaintext, aad);
   }
   if (!cfg.cipherGuest) throw new Error('ERR_GUEST_NOT_CONFIGURED'); // guest 路徑選配：未配置即拒（bound 路徑不受牽連）
-  // 空 identity 拒絕（t_7710c766 目標 3）：K_u = SHA-256(prefix ‖ '') 仍可派生（sha256 不拋），
+  // 空 identity 拒絕：K_u = SHA-256(prefix ‖ '') 仍可派生（sha256 不拋），
   // 靜默產出「空帳號金鑰」＝可解同樣空 identity 的任何 guest 密文（對稱面誤配）。fail-closed。
   const identity = idp.current();
   if (!identity) throw new Error('ERR_NO_IDENTITY');
@@ -552,7 +680,7 @@ export async function decryptNote(
   idp: IdentityProvider,
 ): Promise<string | null> {
   try {
-    // guest 前綴正規化（follow-up ②，t_44239f5f）：畸形配置 ''（空字串）會讓
+    // guest 前綴正規化：畸形配置 ''（空字串）會讓
     // startsWith('') 恆真＝bound 列誤導 guest 分支回 null（解密面整列滅失）。
     // falsy 一律收斂為 undefined，與加密面「未配置即拒」truthiness 對稱。
     const guestPrefix = cfg.cipherGuest || undefined;
@@ -564,7 +692,7 @@ export async function decryptNote(
       return guestPrefix === undefined ? null : cipher;
     }
     if (isGuest) {
-      // 空 identity 拒絕（t_7710c766 目標 3，對稱面）：guest 密文在 identity 缺席時必 null
+      // 空 identity 拒絕（對稱面）：guest 密文在 identity 缺席時必 null
       //（K_u 仍可派生但「空帳號金鑰」不是該密文作者的 intent；誤配下兩態皆 fail-closed）。
       const identity = idp.current();
       if (!identity) return null;

package/src/client/pinlock.ts

@@ -28,7 +28,7 @@ const IV_LEN = 12;
 const PAYLOAD_LEN = SALT_LEN + IV_LEN + 80;
 
 /** 本機鎖定 cfg（各 fork config 注入；未配置 = API 拒絕，兄弟 fork 行為不變）。
- *  t_7710c766：noteKeyExtractable 必填死欄移除——解包輸出恆 extractable（鐵律 1，
+ *  noteKeyExtractable 必填死欄移除——解包輸出恆 extractable（鐵律 1，
  *  要能再包裹／匯出）不是可調選項；tacet 消費端 TACET_PINLOCK 同步摘欄。 */
 export interface PinLockConfig {
   /** 本機鎖定包裹前綴，如 'jr1p.'. 未配置 = 拒絕。 */
@@ -65,7 +65,7 @@ async function deriveLockKek(pinNorm: string, pinSalt: Uint8Array, cfg: PinLockC
 
 /** jr1p. 包裹：payload = pinSalt[16] ‖ iv[12] ‖ GCM(KEK, hex(noteKey), aad)；全自描述（salt 內嵌）。
  *  鹽內嵌家族（jr2w./jr3d./jr1p.）自帶三段組裝——sealNoteKey 是鹽外置家族形（iv‖ct），
- *  內嵌鹽的 pinSalt 前綴不在其契約內（t_7710c766 毒化輪回歸實證：亂收口＝unwrap 恆 null）。 */
+ *  內嵌鹽的 pinSalt 前綴不在其契約內（毒化輪回歸實證：亂收口＝unwrap 恆 null）。 */
 export async function wrapNoteKeyPinLock(cfg: PinLockConfig, noteKey: CryptoKey, pin: string): Promise<string> {
   if (!cfg.pinLock || !cfg.pinLockSaltPrefix || !cfg.pinLockAad) throw new Error('ERR_PINLOCK_NOT_CONFIGURED');
   const pinNorm = normalizePin(pin);
@@ -87,7 +87,7 @@ export async function wrapNoteKeyPinLock(cfg: PinLockConfig, noteKey: CryptoKey,
 }
 
 /** jr1p. 解包：全自描述；任何不符（前綴/長度/PIN 空/AAD）回 null 不拋；成功 → noteKey extractable=true（鐵律 1）。
- *  t_7710c766：嚴格檢查為鹽內嵌族自有（payload 嚴格 108B＋rawHex hex 形檢查；
+ *  嚴格檢查為鹽內嵌族自有（payload 嚴格 108B＋rawHex hex 形檢查；
  *  hexToBytes fail-closed 由 try/catch 承接＝行為不變）——不經 openNoteKey 本體
  *  （openNoteKey 是鹽外置家族 92B 形，pinSalt 前綴不在其契約內）。 */
 export async function unwrapNoteKeyPinLock(cfg: PinLockConfig, wrapped: string, pin: string): Promise<CryptoKey | null> {

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   buildBindPayload,
   ph1Of,
   normalizePin,
+  normalizePassphrase,
   recTokenHash,
   generateRecToken,
   PBKDF2_ITERATIONS,
@@ -38,10 +39,16 @@ export {
   unwrapNoteKey3,
   wrapNoteKeyDual3,
   unwrapNoteKeyDual3,
+  wrapNoteKey4,
+  unwrapNoteKey4,
+  wrapNoteKeyDual4,
+  unwrapNoteKeyDual4,
   wrapNoteKeyShare3,
   unwrapNoteKeyShare3,
   derivePh1Argon,
+  derivePh1ArgonV3,
   PH1_V2_SALT,
+  PH1_V3_SALT,
   ARGON_MEMORY_KIB,
   ARGON_ITERATIONS,
   ARGON_PARALLELISM,
@@ -87,4 +94,11 @@ export {
   generateSessionToken,
   timingSafeEq,
 } from './server/hash.ts';
-export type { Env } from './server/env.ts';
+export type { Env } from './server/env.ts';
+export {
+  PH2_LADDER_TABLE,
+  PH2_LADDER_KIND_LEGACY,
+  PH2_LADDER_KIND_V2,
+  type Ph2LadderKind,
+  type Ph2LadderRow,
+} from './server/ladder.ts';

package/src/server/auth.ts

@@ -21,7 +21,7 @@
  * 不變量（勿破壞）：
  * - 金鑰包裹欄組（wrapped+salt）缺一整組放棄——pair 檢查本體在 pickKeyPackage。
  * - recPkg 與 recHash 成對出現＝呼叫端（fork store）職責：本層介面兩參各自可空、
- *   不做 pair 檢查（r2 MINOR-4 照此收口；pickKeyPackage 是同職責的成對檢查先例）。
+ *   不做 pair 檢查（裁定照此收口；pickKeyPackage 是同職責的成對檢查先例）。
  */
 
 import { corsResponse } from './cors.ts';
@@ -51,11 +51,11 @@ function escapeReLiteral(s: string): string {
 }
 
 /** 前綴家族 → 密文形 regex（單一組裝點；cipherRe 死碼退場）。
- *  never-match 守衛（t_580f9c54 N-7，opt-in 鐵律面；run 574 r2 實測校正）：空字首組態會
+ *  never-match 守衛（空字首組態防線，opt-in 鐵律面）：空字首組態會
  *  組裝出 accept-all 形——`[]` 與 `['']` 組裝出 byte-identical `^()[A-Za-z0-9+/]+={0,2}$`
  *  （join('|') 同為空串），無點純 b64 串（≤200）在舊碼 validWrappedKey/pickKeyPackage 放行＝真洞；
  *  回恆不匹配 regex（`/^(?=a)b/` 正 lookahead 錨死永假）＝未配置形整面拒絕，與 opt-in 律同向。
- *  （probe 實證 /tmp/t580f9c54-r2/n7-corrected-probe.mjs：`[]` 對純 b64 樣本 NON-NULL——
+ *  （probe 實證：`[]` 對純 b64 樣本 NON-NULL——
  *  「charset 恆假自帶防線」是錯誤敘事；帶點前綴向量舊碼本就 null＝帳面無承載。） */
 function cipherPrefixRe(cipherPrefixes: readonly string[]): RegExp {
   const usable = cipherPrefixes.filter(p => typeof p === 'string' && p.length > 0);
@@ -67,7 +67,7 @@ function cipherPrefixRe(cipherPrefixes: readonly string[]): RegExp {
 /**
  * 入庫前校正：前綴密文原樣入庫；超限密文／編碼丟棄（截斷必壞）、明文截到上限照收。
  * cipherMax（UTF-16 單位）同為明文截斷帽：明文相容層無 opt-out——明文一律照收、
- * 截到 cipherMax 入庫（r2 MINOR-5：JSDoc 幽靈參數 plainMax 摘除）。
+ * 截到 cipherMax 入庫（JSDoc 幽靈參數 plainMax 已摘除）。
  */
 export function makeInboundCipher(c: CipherFormats) {
   const RE = cipherPrefixRe(c.cipherPrefixes);
@@ -89,7 +89,7 @@ export function makeInboundCipher(c: CipherFormats) {
 
 export function isCipherFor(text: string | null | undefined, c: CipherFormats): boolean {
   if (typeof text !== 'string') return false;
-  // 空字首組態同面守衛（t_580f9c54 N-7 範圍增補，run 574 r2）：'' 態 startsWith('') 恆真＝
+  // 空字首組態同面守衛（範圍增補）：'' 態 startsWith('') 恆真＝
   // 整體分類面 accept-all（cipherPrefixRe never-match 守衛不覆蓋此直讀 tuple 面——本函式是
   // 另一組裝點）。守衛形＝跳過空字首的 some() 單點承載：空集恆 false（與 never-match 家族拒絕、
   // opt-in 未配置即拒鐵律同向）、混合形只摘空槽（['','jr1b.']＝jr1b. 家族面照活）——
@@ -133,6 +133,17 @@ export interface AuthStore {
   getByUserKey(key: string): Promise<AuthRow | null>;
   getByRecHash(recHash: string): Promise<AuthRow | null>;
   setWrapped(userKey: string, ph2: string, pkg: KeyPackage, recPkg: string | null, recHash: string | null): Promise<void>;
+  /** v3 重鑰：舊值入 ladder 表＋ph2/wrapped/salt/wrappedRec/rec_hash
+   *  五欄同列覆蓋（rec 欄在場才覆蓋——四欄形契約面不動；fork 實作三語句同批寫入）。 */
+  rekeyWithLadder?(userKey: string, oldPh2: string, oldKind: 'legacy' | 'v2', ph2: string, pkg: KeyPackage, recPkg: string | null, recHash: string | null): Promise<void>;
+  /** ladder 查表：以「舊 ph2 值」（v2/legacy 形）查 ladder 表，
+   *  命中回帳戶 id（login route 的「不建幽靈、回舊帳＋ph2Kind='legacy' 語意」守衛面）；
+   *  未配置（optional）＝查表面退場（fork 離線/無表態，行為不變）。 */
+  ladderLookup?(oldPh2: string): Promise<string | null>;
+  /** ladder 入表（遷移線用；upsert冪等）。 */
+  ladderInsert?(accountId: string, oldPh2: string, oldKind: 'legacy' | 'v2'): Promise<void>;
+  /** ladder 刪列（直銷面；遷移批次同批或後續呼叫端承擔）。 */
+  ladderDelete?(accountId: string): Promise<void>;
   revokeAllSessions(userKey: string): Promise<void>;
   insertSession(tokenHash: string, userKey: string, expiresAt: number): Promise<void>;
 }

package/src/server/cors.ts

@@ -5,7 +5,7 @@ export const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
   'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-  // preflight 快取（卡C t_7361b68c：缺 Max-Age＝瀏覽器對每個跨域請求重跑 OPTIONS preflight）。
+  // preflight 快取（缺 Max-Age＝瀏覽器對每個跨域請求重跑 OPTIONS preflight）。
   // 86400 落業界 600-86400 慣例上緣；瀏覽器端自行 clamp（Chromium 2h／WebKit 10m、Firefox
   // 照走）——快取命中不影響伺服器語意；消費端 inline OPTIONS 分流照 corsResponse 放行。
   'Access-Control-Max-Age': '86400',

package/src/server/ladder.ts

@@ -0,0 +1,71 @@
+/**
+ * ladder.ts — 密語正規化 v3 世代 ladder 表（server 內部表）。
+ *
+ * （a+）方案（設計裁定）：遷移時舊 ph2 值入 server 內部表（ph2_ladder），
+ * users 表零 schema 變更、ph2 欄 UNIQUE 恆動──client 舊 bundle 的單欄 v2-first 查表
+ * 在遷移後仍對既有帳戶命中（查 users.ph2 現值＝v2 形），行為不變。
+ *
+ * 語意面：
+ * - ladder hit（現值未命中 → ladder 命中）＝不建幽靈、回舊帳（fork 語意面 ph2Kind='legacy'）。
+ *   v3 帳戶：鹽與包裹已旋轉成 v3 形；fork 語意「本 login 的舊形憑證 unwrap 必失敗；
+ *   client 以 ladder 缺鹽面誠實告知升級」對應 v0.2.0 前的單欄舊 bundle（帶 ph1_v3 的
+ *   新 client 恰命中 v3 現值、前綴自描述走 v3 腿）。
+ * - ladder miss（兩面皆查無）＝才建幽靈（fork createUser，v2 先行）。
+ * - 幽靈帳戶走完遷移後以同舊值 upsert（ON CONFLICT(ph2)＝值主權威覆蓋，最新持有者勝）。
+ * - 表列隨帳戶刪除清理（FK ON DELETE CASCADE，fork delete-account 面零新語句）；
+ *   users 列是真值面，ladder 表列可重建（v2 形重新遷移即重落）——表列毀損不傷帳戶面。
+ * - 幽靈 GC（wrapped_key IS NULL 判準）不收 ladder 命中面（帳戶列仍在＝判準不變）。
+ *
+ * 零知識照舊：ladder 只存 ph2 hash 與 account_id，零 PII、零密語材料。
+ *
+ * 職責分工（fork 對位面）：表名／migration 由 fork migrations 承載（0011-ph2-ladder.sql，
+ * PK=ph2 值主權威形）；本層提供「以舊 ph2 查列」與「遷移時入表」原語，查表接線
+ * （現值 miss → ladder → 建幽靈）在 fork route（tacet loginRoute，v2-first 裁定）。
+ */
+
+import type { Env } from './env.ts';
+
+/** ladder 表名（migration 同名；單一真相，fork migration 與本原語同字面）。 */
+export const PH2_LADDER_TABLE = 'ph2_ladder';
+
+/** ladder 行 kinds：'legacy'（SHA-256 快雜湊世代）與 'v2'（v2 形前身，遷移的正常前身）。
+ *  「帳戶現在用什麼形」的真相在 users.ph2 班表行（ph2_ladder 只承載舊值）；kind 欄
+ *  純粹是「這個舊值當年是什麼形」的語意記錄。 */
+export type Ph2LadderKind = 'legacy' | 'v2';
+export const PH2_LADDER_KIND_LEGACY = 'legacy';
+export const PH2_LADDER_KIND_V2 = 'v2';
+
+/** ladder 行形（fork schema 對位面）。 */
+export interface Ph2LadderRow {
+  accountId: string;
+  ph2Kind: string;
+  createdAt: number;
+}
+
+/** 以「舊 ph2」查 ladder（fork store 對位面）。null = ladder miss。 */
+export function makePh2LadderStore(env: Env): {
+  findByOldPh2(oldPh2: string): Promise<Ph2LadderRow | null>;
+  insert(accountId: string, oldPh2: string, oldKind: Ph2LadderKind): Promise<void>;
+} {
+  return {
+    async findByOldPh2(oldPh2: string): Promise<Ph2LadderRow | null> {
+      const row = await env.DB.prepare(
+        `SELECT account_id, ph2_kind, upgraded_at FROM ${PH2_LADDER_TABLE} WHERE ph2 = ?`,
+      ).bind(oldPh2).first<{ account_id: string; ph2_kind: string; upgraded_at: number }>();
+      if (!row) return null;
+      return { accountId: row.account_id, ph2Kind: row.ph2_kind, createdAt: row.upgraded_at };
+    },
+    async insert(accountId: string, oldPh2: string, oldKind: Ph2LadderKind): Promise<void> {
+      // upsert ON CONFLICT(ph2)（值主權威，PK 定形）：同一舊值恰一列，最新持有者勝——
+      // A 遷移落 (V→A) 後 V 值幽靈帳戶後建並遷移＝覆蓋為 (V→B)。無 DELETE 語句：行留存
+      // 續供幽靈守衛（行隨帳戶刪除由 FK CASCADE 清）；fork 寫入面另備 ladderDelete 給
+      // delete-account 清場面。
+      // fail-open（遷移率聚合面）：插表失敗只讓下一輪 login 重試同一 upsert
+      //（v3 查表 miss 再走 ladder miss → 建 v2 幽靈的行為面）──遷移本體不因本表故障回退。
+      await env.DB.prepare(
+        `INSERT INTO ${PH2_LADDER_TABLE} (ph2, account_id, ph2_kind, upgraded_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(ph2) DO UPDATE SET account_id = excluded.account_id, ph2_kind = excluded.ph2_kind, upgraded_at = excluded.upgraded_at`,
+      ).bind(oldPh2, accountId, oldKind, Date.now()).run();
+    },
+  };
+}

package/src/server/ratelimit.ts

@@ -1,15 +1,15 @@
 /**
  * ratelimit.ts — per-IP fixed-window 限流（D1 計數，跨 isolate 有效；單句 UPSERT…RETURNING）。
  *
- * 設計（2026-10-04 t_b91ed07f，外部審查 MAJOR：原 4 往返條件寫入鏈 1 往返收口）：
+ * 設計（2026-10-04 定案：原 4 往返條件寫入鏈 1 往返收口）：
  * - 限流語意是 fixed window：以 window_start 為窗錨，窗過期整窗重置。
- *   （原檔頭「滑動視窗」措辭錯誤——c7c8701 只修 README 未修本檔；本卡一併收口。）
+ *   （原檔頭「滑動視窗」措辭錯誤——c7c8701 只修 README 未修本檔；本檔一併收口。）
  * - 單條 UPSERT…RETURNING 原子完成「計數＋窗重置＋讀回放行判準」：
  *   同 IP 併發首發不再有 INSERT/輸家競態（同語句同鍵衝突時第二發原子吃到
  *   count+1；D1 實測 RETURNING 逐發回真值——同 IP 併發首發不 undercount）。
  * - fail-open 裁定不變（2026-09-06）：限流儲存故障時放行（保護面不可反噬主功能），
  *   只擋明確超額。RETURNING 異形回應（results 空／alias 斷裂）同向 fail-open
- *   並 console.error 照實回報（r2 MINOR-3：異形不反向成 deny）。
+ *   並 console.error 照實回報（異形不反向成 deny）。
  *
  * 放行判準：RETURNING 的 count <= max（窗口內超額後的每一發都回實際 count，
  * 由呼叫端以 count <= max 拒絕——計數不封頂，超額仍逐發累計）。