@tacet-ink/journal-core 0.1.5 → 0.2.0

package/src/client/note-crypto.ts

@@ -33,6 +33,10 @@ export interface NoteCryptoConfig {
   cipherBound: string;
   /** 金鑰包裹前綴，如 'jr1w.'。 */
   wrap: string;
+  /** 本機包裹前綴（jr1l.，v0.2.0 批卡③：本機包裹不再借用 cfg.wrap——「一個前綴一份契約」
+   *  的第二違例收口）。未配置 = storeLocalWrap/loadLocalWrap 退場（無寫入／讀取照走
+   *  舊形回落，行為不變——cipherLocal opt-in 母型）。 */
+  wrapLocal?: string;
   /** 雙因子合鑰包裹前綴（jr2w.，PIN 第二因子）。未配置 = dual API 拒絕（未配置行為不變）。 */
   wrapDual?: string;
   /** 雙因子 pin 段 PBKDF2 salt 前綴，如 'journal-note-pin1:'（pinSalt 內嵌 payload 後拼接）。 */
@@ -52,12 +56,25 @@ export const PIN_PBKDF2_ITERATIONS = 2_000_000; // 雙因子 pin 段（設計 v2
 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。
+ */
+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
+  // 源碼發行，不引入 Node-only
+  // toBase64 分支（卡面否決案）。apply 參數上限安全窗 8192；輸出 byte 等價
+  // （驗證閘 [14] 有 0/1/7/8191/8192/8193/65539 邊界逐位元組對照＋unb64 roundtrip）。
   let binary = '';
-  for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
+  for (let i = 0; i < bytes.byteLength; i += 8192) {
+    binary += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192) as unknown as number[]);
+  }
   return btoa(binary);
 }
 
@@ -73,7 +90,22 @@ export function toHex(bytes: Uint8Array): string {
 }
 
 export function hexToBytes(hex: string): Uint8Array {
-  return new Uint8Array((hex.match(/.{2}/g) ?? []).map(h => parseInt(h, 16)));
+  // fail-closed（目標 #2）：非法字元靜默歸零是 unwrap 家族的假金鑰生產器——
+  // 拋 ERR_BAD_HEX（呼叫端 unwrap 全部 try/catch 回 null；非 catch 端僅 bip39
+  // HEX64_RE 前置自守）。奇數長度、非 hex、空字串皆拒；大小寫/全形 NFKC 收容。
+  // 測與 parse 同一（正規化後）真相——round 1 審查 MINOR-4：形檢吃正規化串、
+  // parseInt 吃原始串＝全形 hex digit NaN 歸零殘形（README 例外契約自穿透），收口殲滅。
+  // NFKC 寬容＝設計面刻意（round 2 NIT 記錄 t_580f9c54）：'⑩'→'10' 等相容字元收容後是真 hex
+  // 值（⑩→[16] 實帳），非缺陷形（NaN 歸零已殲滅＝輸出恆數學等值）；rawHex 檢查同式（HEX_RE 同行後置
+  // ＝rawHex 前置守衛）；鹽欄同為同行後置（note-crypto/argon2 各 unwrap 面鹽欄形檢——行號帳不寫死，
+  // 新增段推移行號＝註解行號帳漂移，NIT-a 同病禁再犯）。
+  // 行為恆 null（純註解）；正式輸入面形檢在場，公開原語只保證「正規化後真 hex 恆等值、垃圾恆拒」。
+  // 若要 ASCII-only 收緊＝帶內版本化（換前綴），禁原地改語意。
+  const norm = hex.normalize('NFKC').toLowerCase();
+  if (!HEX_RE.test(norm)) {
+    throw new Error('ERR_BAD_HEX');
+  }
+  return new Uint8Array((norm.match(/.{2}/g) ?? []).map(h => parseInt(h, 16)));
 }
 
 async function sha256Hex(text: string): Promise<string> {
@@ -98,6 +130,8 @@ 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 實證）。
   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' },
@@ -108,6 +142,11 @@ async function deriveKek(password: string, salt: Uint8Array): Promise<CryptoKey>
   );
 }
 
+/** raw → PBKDF2 import（僅供 deriveBits 用途；與 deriveKek 的 deriveKey 用途分行）。 */
+async function importKeyRawForKdf(password: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey('raw', new TextEncoder().encode(password) as BufferSource, 'PBKDF2', false, ['deriveBits']);
+}
+
 // ── 雙因子合鑰（jr2w.，PIN 第二因子；2026-09-09 定案 v2） ────────────────────
 //
 // KEK2 = HKDF-SHA256( ikm = PBKDF2(pass, salt1, 600k)[32B] ‖ PBKDF2(pin, pinSaltPrefix‖pinSalt, 2M)[32B],
@@ -122,15 +161,37 @@ export function normalizePin(pin: string): string {
   return pin.normalize('NFKC').trim().toLowerCase();
 }
 
+/**
+ * 密語正規化契約 v3（v0.2.0 批卡①；卡D 裁定 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 keyMat = await crypto.subtle.importKey('raw', new TextEncoder().encode(password) as BufferSource, 'PBKDF2', false, ['deriveBits']);
-  const bits = await crypto.subtle.deriveBits({ name: 'PBKDF2', salt: salt as BufferSource, iterations, hash: 'SHA-256' }, keyMat, 256);
+  const km = await importKeyRawForKdf(password);
+  const bits = await crypto.subtle.deriveBits({ name: 'PBKDF2', salt: salt as BufferSource, iterations, hash: 'SHA-256' }, km, 256);
   return new Uint8Array(bits);
 }
 
 async function deriveKek2(cfg: NoteCryptoConfig, passphrase: string, pin: string, salt1: Uint8Array, pinSalt: Uint8Array): Promise<CryptoKey> {
-  const passBits = await derivePbkdf2Bits(passphrase, salt1, PBKDF2_ITERATIONS);
-  const pinBits = await derivePbkdf2Bits(pin, new TextEncoder().encode(cfg.pinSaltPrefix + toHex(pinSalt)), PIN_PBKDF2_ITERATIONS);
+  // pass 段與 pin 段 PBKDF2 相互獨立（不同 salt/密碼不同鹽源）＝可並行（t_7361b68c 目標 1）。
+  // ⚠️ 瀏覽器 hash-wasm Argon2（jr3d. 對應形 deriveKek2Argon）禁並行——純 wasm Argon2id
+  // 共享記憶體池、兩實例並行在部分引擎靜態直 throw，卡面 review 明示；並行只收 PBKDF2 家族。
+  // 兩段各自 importKeyRawForKdf（round 2 NIT-2：keyMat 參數化退場——pass/pin 段絕不共享 PBKDF2 基材）。
+  // 輸出序＝ikm 組裝序＝passBits@0 ‖ pinBits@32（與原串行逐位一致）；閘錨綁左手側 destructure，
+  // 對調滑接＝既有 jr2w. 帳戶全不可解（round 2 MAJOR-1 reviewer rev-harm 一手實證）。
+  const [passBits, pinBits] = await Promise.all([
+    derivePbkdf2Bits(passphrase, salt1, PBKDF2_ITERATIONS),
+    derivePbkdf2Bits(pin, new TextEncoder().encode(cfg.pinSaltPrefix + toHex(pinSalt)), PIN_PBKDF2_ITERATIONS),
+  ]);
   const ikm = new Uint8Array(passBits.byteLength + pinBits.byteLength);
   ikm.set(passBits, 0);
   ikm.set(pinBits, passBits.byteLength);
@@ -151,7 +212,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_DUAL_NOT_CONFIGURED');
+  if (!pinNorm) throw new Error('ERR_PIN_EMPTY'); // 空 PIN ≠ 未配置（t_7710c766 語意分離）
   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);
@@ -175,9 +236,9 @@ export async function unwrapNoteKeyDual(cfg: NoteCryptoConfig, wrapped: string,
     if (!cfg.wrapDual || !cfg.pinSaltPrefix) return null;
     if (!wrapped.startsWith(cfg.wrapDual)) return null;
     const salt1 = hexToBytes(salt1Hex);
-    if (salt1.length !== 16) return null;
+    if (salt1.length !== 16 || !HEX32_RE.test(salt1Hex)) return null;
     const payload = unb64(wrapped.slice(cfg.wrapDual.length));
-    // 嚴格長度：pinSalt(16) + iv(12) + ct(hex(noteKey) 64B + GCM tag 16B) = 108B 固定
+    // 嚴格長度：pinSalt(16) + iv(12) + ct(hex 字串 64B + GCM tag 16B) = 108B 固定；rawHex hex 形為本函式自有檢查（鹽內嵌族不經 openNoteKey 本體）
     if (payload.length !== DUAL_SALT_LEN + DUAL_IV_LEN + 80) return null;
     const pinSalt = payload.slice(0, DUAL_SALT_LEN);
     const ivPrefixedCt = payload.slice(DUAL_SALT_LEN); // decryptWithKey 契約：payload = iv[12] ‖ ct
@@ -185,7 +246,7 @@ export async function unwrapNoteKeyDual(cfg: NoteCryptoConfig, wrapped: string,
     if (!pinNorm) return null;
     const kek2 = await deriveKek2(cfg, passphrase, pinNorm, salt1, pinSalt);
     const rawHex = await decryptWithKey(kek2, ivPrefixedCt, 'notekey2');
-    if (!rawHex) return null;
+    if (!rawHex || rawHex.length !== 64 || !/^[0-9a-f]+$/.test(rawHex)) return null;
     return importAesGcm(hexToBytes(rawHex), true); // extractable=true：要能再包裹（鐵律）
   } catch {
     return null;
@@ -291,24 +352,64 @@ export function recTokenHash(recToken: string): Promise<string> {
 
 // ── 金鑰包裹 ────────────────────────────────────────────────────────────────
 
+/** noteKey raw hex 長度（hex(noteKey) 64B ＝ payload ct 面 80B 契約的一半）。 */
+const NOTEKEY_HEX_LEN = 64;
+
+/**
+ * 共用包裹核心（目標 #1 收口）：prefix + b64(iv[12] ‖ GCM(KEK, hex(noteKey), aad))。
+ * 全家族單因子包裹（jr1w./jrsw./jr3w./jr3s.）與復原套件（wrappedRec，前綴共用 cfg.wrap）
+ * 同一本體；KDF 差異在呼叫端 KEK、payload 形狀（salt 外置 vs 內嵌）由各家族維持。
+ * prefix null/undefined＝未配置拒絕（呼叫端亦可先行拒絕，帶自家錯誤碼形；雙防線）。
+ */
+export async function sealNoteKey(prefix: string | null | undefined, noteKey: CryptoKey, kek: CryptoKey, aad: string): Promise<string> {
+  if (!prefix) throw new Error('ERR_WRAP_NOT_CONFIGURED');
+  const raw = await crypto.subtle.exportKey('raw', noteKey);
+  if (raw.byteLength !== 32) throw new Error('ERR_WRAPTAMPER_LEN32');
+  return prefix + await encryptWithKey(kek, toHex(new Uint8Array(raw)), aad);
+}
+
+/**
+ * 共用解包核心（目標 #1 收口）：任何不符——前綴、base64 形、payload 長度、
+ * GCM（金鑰/AAD/密文損壞）、rawHex 長度/hex 形——恆回 null 不拋。
+ * round 1 審查 MINOR-5：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 檢已隨收口摘除）；
+ * 鹽內嵌 3 點（jr2w/jr3d/jr1p）own 108B＋rawHex 形檢——與本體同嚴格度、刻意不經本體
+ * （pinSalt 前綴不在鹽外置形契約內）。維護本體時鹽內嵌三族不隨行。
+ */
+export async function openNoteKey(wrapped: string, kek: CryptoKey, aad: string, prefix: string): Promise<CryptoKey | null> {
+  if (!wrapped.startsWith(prefix)) return null;
+  let payload: Uint8Array;
+  try {
+    payload = unb64(wrapped.slice(prefix.length)); // atob 非法字元拋點吞收 null（公開原語全 null 契約）
+  } catch {
+    return null; // 壞 base64＝任何不符面之一（行為閘有壞 b64 向量承載）
+  }
+  if (payload.length !== IV_LEN + 80) return null; // 嚴格 92B：iv 12＋ct 80（hex64 字串編碼 64B＋tag 16）
+  const rawHex = await decryptWithKey(kek, payload, aad);
+  if (!rawHex || rawHex.length !== NOTEKEY_HEX_LEN || !HEX_RE.test(rawHex)) return null;
+  return importAesGcm(hexToBytes(rawHex), true); // extractable=true：要能再包裹/解密（鐵律）
+}
+
 /** passphrase 包裹：salt 隨機 16 bytes（hex 存於 users.salt）。 */
 export async function wrapNoteKey(cfg: NoteCryptoConfig, noteKey: CryptoKey, passphrase: string): Promise<{ wrapped: string; salt: string }> {
   const salt = crypto.getRandomValues(new Uint8Array(16));
+  if (!cfg.wrap) throw new Error('ERR_WRAP_NOT_CONFIGURED');
   const kek = await deriveKek(passphrase, salt);
-  const payload = new Uint8Array(await crypto.subtle.exportKey('raw', noteKey));
-  const wrapped = cfg.wrap + await encryptWithKey(kek, toHex(payload), 'notekey');
+  const wrapped = await sealNoteKey(cfg.wrap, noteKey, kek, 'notekey');
   return { wrapped, salt: toHex(salt) };
 }
 
 export async function unwrapNoteKey(cfg: NoteCryptoConfig, wrapped: string, passphrase: string, saltHex: string): Promise<CryptoKey | null> {
   try {
-    if (!wrapped.startsWith(cfg.wrap)) return null;
+    if (!cfg.wrap) return null;
     const salt = hexToBytes(saltHex);
     if (salt.length !== 16 || !HEX32_RE.test(saltHex)) return null;
     const kek = await deriveKek(passphrase, salt);
-    const rawHex = await decryptWithKey(kek, unb64(wrapped.slice(cfg.wrap.length)), 'notekey');
-    if (!rawHex) return null;
-    return importAesGcm(hexToBytes(rawHex), true); // extractable=true：要能再包裹
+    return await openNoteKey(wrapped, kek, 'notekey', cfg.wrap);
   } catch {
     return null;
   }
@@ -326,8 +427,7 @@ export async function wrapNoteKeyShare(cfg: NoteCryptoConfig, noteKey: CryptoKey
   if (!cfg.wrapShare) throw new Error('ERR_SHARE_NOT_CONFIGURED');
   const salt = crypto.getRandomValues(new Uint8Array(16));
   const kek = await deriveKek(sharePass, salt);
-  const payload = new Uint8Array(await crypto.subtle.exportKey('raw', noteKey));
-  const wrapped = cfg.wrapShare + await encryptWithKey(kek, toHex(payload), 'notekey-share');
+  const wrapped = await sealNoteKey(cfg.wrapShare, noteKey, kek, 'notekey-share');
   return { wrapped, salt: toHex(salt) };
 }
 
@@ -335,13 +435,10 @@ export async function wrapNoteKeyShare(cfg: NoteCryptoConfig, noteKey: CryptoKey
 export async function unwrapNoteKeyShare(cfg: NoteCryptoConfig, wrapped: string, sharePass: string, saltHex: string): Promise<CryptoKey | null> {
   try {
     if (!cfg.wrapShare) return null;
-    if (!wrapped.startsWith(cfg.wrapShare)) return null;
     const salt = hexToBytes(saltHex);
     if (salt.length !== 16 || !HEX32_RE.test(saltHex)) return null;
     const kek = await deriveKek(sharePass, salt);
-    const rawHex = await decryptWithKey(kek, unb64(wrapped.slice(cfg.wrapShare.length)), 'notekey-share');
-    if (!rawHex) return null;
-    return importAesGcm(hexToBytes(rawHex), true); // extractable=true：解出後要能解日記密文（鐵律）
+    return await openNoteKey(wrapped, kek, 'notekey-share', cfg.wrapShare);
   } catch {
     return null;
   }
@@ -354,23 +451,27 @@ async function deriveRecKek(cfg: NoteCryptoConfig, recToken: string, identity: s
 
 export async function wrapNoteKeyWithRecToken(cfg: NoteCryptoConfig, noteKey: CryptoKey, recToken: string, identity: string): Promise<string> {
   const kek = await deriveRecKek(cfg, recToken, identity);
-  const payload = new Uint8Array(await crypto.subtle.exportKey('raw', noteKey));
-  return cfg.wrap + await encryptWithKey(kek, toHex(payload), 'notekey');
+  return sealNoteKey(cfg.wrap, noteKey, kek, 'notekey');
 }
 
 export async function unwrapNoteKeyWithRecToken(cfg: NoteCryptoConfig, wrapped: string, recToken: string, identity: string): Promise<CryptoKey | null> {
   try {
-    if (!wrapped.startsWith(cfg.wrap)) return null;
+    if (!cfg.wrap) return null;
     const kek = await deriveRecKek(cfg, recToken, identity);
-    const rawHex = await decryptWithKey(kek, unb64(wrapped.slice(cfg.wrap.length)), 'notekey');
-    if (!rawHex) return null;
-    return importAesGcm(hexToBytes(rawHex), true); // 復原後要能重新包裹
+    return await openNoteKey(wrapped, kek, 'notekey', cfg.wrap);
   } catch {
     return null;
   }
 }
 
-/** 綁定請求的金鑰包裹三件套（bind 用）+ recovery_token_hash。 */
+/**
+ * 綁定請求的金鑰包裹三件套（bind 用）+ recovery_token_hash。
+ * 兩段 600k PBKDF2 相互獨立（pass 鹽隨機、rec 鹽=recSaltPrefix‖identity 定值）＝並行
+ *（t_7361b68c 目標 1：node 實測 133-152ms→68-84ms，與閘執行帳同源——round 2 MINOR-2 對齊）。
+ * AES-GCM derive 佔 600k 迴圈 99%，兩段 wrapped 各自隨機 iv（pass 段另隨機鹽 16B；rec 腿
+ * KEK 鹽定值、回傳 salt 來自 pass 腿 w1——round 2 MINOR-2 措辭修正）——逐位等值帳由
+ * 「兩段各自與 wrapNoteKey 直呼相等」承載。
+ */
 export async function buildBindPayload(
   cfg: NoteCryptoConfig,
   noteKey: CryptoKey,
@@ -378,11 +479,13 @@ export async function buildBindPayload(
   recToken: string,
   identity: string,
 ): Promise<{ wrapped: string; salt: string; wrappedRec: string; recTokenHash: string }> {
-  const { wrapped, salt } = await wrapNoteKey(cfg, noteKey, passphrase);
-  const wrappedRec = await wrapNoteKeyWithRecToken(cfg, noteKey, recToken, identity);
+  const [w1, wrappedRec] = await Promise.all([
+    wrapNoteKey(cfg, noteKey, passphrase),
+    wrapNoteKeyWithRecToken(cfg, noteKey, recToken, identity),
+  ]);
   return {
-    wrapped,
-    salt,
+    wrapped: w1.wrapped,
+    salt: w1.salt,
     wrappedRec,
     recTokenHash: await recTokenHash(recToken),
   };
@@ -390,22 +493,45 @@ export async function buildBindPayload(
 
 // ── 本機包裹（PWA session 期免重打密語） ─────────────────────────────────────
 
+/**
+ * 本機包裹（v0.2.0 批卡③）：KEK = deriveGuestKey（identity 派生、passphrase-free——
+ * session 期免重打密語的機制原樣），payload 改走專用前綴 cfg.wrapLocal（jr1l.）。
+ * 舊實作借用 cfg.wrap（jr1w. passphrase 包裹前綴）寫本機包裹＝「一個前綴一份契約」
+ * 的第二違例（wrappedRec 專用前綴歸卡①批面）：本機包裹的 KDF 與 caller 不同、
+ * 儲存面（localStorage）不同、生命週期不同（clearLocalWrap 隨時摘除）——共前綴讓
+ * 「本機字串是否可能誤入 server 包裹欄」對帳失真。新前綴＝讀舊寫新自癒：
+ * loadLocalWrap 先試 jr1l.（本體嚴格面），命中舊形（jr1w.）回落解密後即重包
+ * cfg.wrapLocal 回寫（自癒一次），寫入恆 jr1l.。
+ */
 export async function storeLocalWrap(cfg: NoteCryptoConfig, identity: string, noteKey: CryptoKey): Promise<void> {
   try {
+    // 寫入恆專用前綴 cfg.wrapLocal（jr1l.；未配置＝無寫入退場，讀取面照走舊形回落——
+    // 行為不變態）。單一真相：loadLocalWrap 自癒腿經本函式回寫（前綴契約不二寫）。
+    if (!cfg.wrapLocal) return;
     const guest = await deriveGuestKey(cfg, identity);
-    const raw = toHex(new Uint8Array(await crypto.subtle.exportKey('raw', noteKey)));
-    cfg.store.set(cfg.store.noteKeyWrap(identity), cfg.wrap + await encryptWithKey(guest, raw, 'notekey-local'));
+    const wrapped = await sealNoteKey(cfg.wrapLocal, noteKey, guest, 'notekey-local');
+    cfg.store.set(cfg.store.noteKeyWrap(identity), wrapped);
   } catch { /* private mode：不阻擋主流程 */ }
 }
 
 async function loadLocalWrap(cfg: NoteCryptoConfig, identity: string): Promise<CryptoKey | null> {
   try {
     const stored = cfg.store.get(cfg.store.noteKeyWrap(identity));
-    if (!stored || !stored.startsWith(cfg.wrap)) return null;
+    if (!stored) return null;
     const guest = await deriveGuestKey(cfg, identity);
-    const rawHex = await decryptWithKey(guest, unb64(stored.slice(cfg.wrap.length)), 'notekey-local');
-    if (!rawHex) return null;
-    return importAesGcm(hexToBytes(rawHex), true);
+    // 次序契約：新形必先於舊形試——新形 blob 在舊前綴面恆拒（family isolation），次序可觀察。
+    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;
   }
@@ -450,7 +576,11 @@ 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 路徑不受牽連）
-  const guest = await deriveGuestKey(cfg, idp.current());
+  // 空 identity 拒絕（t_7710c766 目標 3）：K_u = SHA-256(prefix ‖ '') 仍可派生（sha256 不拋），
+  // 靜默產出「空帳號金鑰」＝可解同樣空 identity 的任何 guest 密文（對稱面誤配）。fail-closed。
+  const identity = idp.current();
+  if (!identity) throw new Error('ERR_NO_IDENTITY');
+  const guest = await deriveGuestKey(cfg, identity);
   return cfg.cipherGuest + await encryptWithKey(guest, plaintext, aad);
 }
 
@@ -476,7 +606,11 @@ export async function decryptNote(
       return guestPrefix === undefined ? null : cipher;
     }
     if (isGuest) {
-      const guest = await deriveGuestKey(cfg, idp.current());
+      // 空 identity 拒絕（t_7710c766 目標 3，對稱面）：guest 密文在 identity 缺席時必 null
+      //（K_u 仍可派生但「空帳號金鑰」不是該密文作者的 intent；誤配下兩態皆 fail-closed）。
+      const identity = idp.current();
+      if (!identity) return null;
+      const guest = await deriveGuestKey(cfg, identity);
       return await decryptWithKey(guest, unb64(cipher.slice(guestPrefix!.length)), aad);
     }
     if (!held.get()) {

package/src/client/pinlock.ts

@@ -24,10 +24,12 @@ export const PINLOCK_ITERATIONS = 600_000;
 
 const SALT_LEN = 16;
 const IV_LEN = 12;
-/** pinSalt(16) + iv(12) + ct(hex(noteKey) 64B + GCM tag 16B) = 108B 固定。 */
+/** pinSalt(16) + iv(12) + ct(hex 字串 64B + GCM tag 16B) = 108B 固定。 */
 const PAYLOAD_LEN = SALT_LEN + IV_LEN + 80;
 
-/** 本機鎖定 cfg（各 fork config 注入；未配置 = API 拒絕，兄弟 fork 行為不變）。 */
+/** 本機鎖定 cfg（各 fork config 注入；未配置 = API 拒絕，兄弟 fork 行為不變）。
+ *  t_7710c766：noteKeyExtractable 必填死欄移除——解包輸出恆 extractable（鐵律 1，
+ *  要能再包裹／匯出）不是可調選項；tacet 消費端 TACET_PINLOCK 同步摘欄。 */
 export interface PinLockConfig {
   /** 本機鎖定包裹前綴，如 'jr1p.'. 未配置 = 拒絕。 */
   pinLock?: string;
@@ -35,8 +37,6 @@ export interface PinLockConfig {
   pinLockSaltPrefix?: string;
   /** AAD（鎖定包裹專用，與登入第二因子/分享包裹互斥）。未配置 = 拒絕。 */
   pinLockAad?: string;
-  /** 解包輸出的 noteKey（要能再包裹/匯出，鐵律 1）。 */
-  noteKeyExtractable: boolean;
 }
 
 /** KEK = PBKDF2-SHA256(pinNorm, pinLockSaltPrefix + hex(pinSalt), 600k) → AES-GCM key（nonextractable）。 */
@@ -63,7 +63,9 @@ async function deriveLockKek(pinNorm: string, pinSalt: Uint8Array, cfg: PinLockC
   );
 }
 
-/** jr1p. 包裹：payload = pinSalt[16] ‖ iv[12] ‖ GCM(KEK, hex(noteKey), aad)；全自描述（salt 內嵌）。 */
+/** jr1p. 包裹：payload = pinSalt[16] ‖ iv[12] ‖ GCM(KEK, hex(noteKey), aad)；全自描述（salt 內嵌）。
+ *  鹽內嵌家族（jr2w./jr3d./jr1p.）自帶三段組裝——sealNoteKey 是鹽外置家族形（iv‖ct），
+ *  內嵌鹽的 pinSalt 前綴不在其契約內（t_7710c766 毒化輪回歸實證：亂收口＝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);
@@ -84,7 +86,10 @@ export async function wrapNoteKeyPinLock(cfg: PinLockConfig, noteKey: CryptoKey,
   return cfg.pinLock + b64(payload);
 }
 
-/** jr1p. 解包：全自描述；任何不符（前綴/長度/PIN 空/AAD）回 null 不拋；成功 → noteKey extractable=true（鐵律 1）。 */
+/** jr1p. 解包：全自描述；任何不符（前綴/長度/PIN 空/AAD）回 null 不拋；成功 → noteKey extractable=true（鐵律 1）。
+ *  t_7710c766：嚴格檢查為鹽內嵌族自有（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> {
   try {
     if (!cfg.pinLock || !cfg.pinLockSaltPrefix || !cfg.pinLockAad) return null;
@@ -92,12 +97,12 @@ export async function unwrapNoteKeyPinLock(cfg: PinLockConfig, wrapped: string,
     const payload = unb64(wrapped.slice(cfg.pinLock.length));
     if (payload.length !== PAYLOAD_LEN) return null;
     const pinSalt = payload.slice(0, SALT_LEN);
-    const ivPrefixedCt = payload.slice(SALT_LEN); // decryptWithKey 契約：payload = iv[12] ‖ ct
+    const ivPrefixedCt = payload.slice(SALT_LEN); // 鹽內嵌家族：payload = pinSalt[16] ‖ iv[12] ‖ ct
     const pinNorm = normalizePin(pin);
     if (!pinNorm) return null;
     const kek = await deriveLockKek(pinNorm, pinSalt, cfg);
     const rawHex = await decryptWithKey(kek, ivPrefixedCt, cfg.pinLockAad);
-    if (!rawHex) return null;
+    if (!rawHex || rawHex.length !== 64 || !/^[0-9a-f]+$/.test(rawHex)) return null;
     return importAesGcm(hexToBytes(rawHex), true);
   } catch {
     return null;

package/src/index.ts

@@ -19,8 +19,11 @@ export {
   wrapNoteKeyDual,
   unwrapNoteKeyDual,
   storeLocalWrap,
+  clearLocalWrap,
+  buildBindPayload,
   ph1Of,
   normalizePin,
+  normalizePassphrase,
   recTokenHash,
   generateRecToken,
   PBKDF2_ITERATIONS,
@@ -36,9 +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,
@@ -84,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

@@ -1,33 +1,42 @@
 /**
  * auth.ts — 零知識伺服器端 auth 核心邏輯（品牌／schema 參數化）。
  *
- * 不變量（勿破壞）：
+ * 本檔實作的契約：
  * - pass 明文永不過線：線上憑證送 PH1（雜湊形），伺服器存 PH2 = SHA-256(PH1)。
  *   PH1 派生方式由各產品自定義（快雜湊或 Argon2id 派生皆可）——本層只驗
  *   hex64 形，不驗 PH1 派生方式（伺服器零知識，無從也無需區分形別）。
- * - hash-ladder 雙軌：舊式存 PH1 直比 → 命中即「順手升級」寫回 PH2
- * - 常數時間比較（timingSafeEq）防時序側信道
- * - 密語重設 = 舊憑證可能已洩漏 → 撤銷該身份全部 session
- * - 金鑰包裹欄組（wrapped+salt）缺一整組放棄；rec 包裹與種子 hash 必須成對出現
+ * - 入庫前密文／包裹格式驗證（inboundCipher／isCipherFor／validWrappedKey／
+ *   pickKeyPackage 等，前綴由 config 注入）。
+ * - /auth/login 核心動線（loginRouteCore）：rate-limit 閘 → PH1 驗形 →
+ *   PH2 → store 查詢／建號 → session token 簽發（30 天）。
+ *
+ * 呼叫端（fork）職責——本檔只定義介面，機制在呼叫端實作：
+ * - identity 生成：AuthStore.createUser 由各 fork 自決（隨機 account_id 或
+ *   客戶端帶入語意皆可）；PH2 UNIQUE 衝突（兩個同時首登同密語）是 store
+ *   責任——tacet 參考實作：UNIQUE 失敗重查既有列回 userKey（非 5xx）。
+ * - hash-ladder 雙軌（舊式 PH1 直比 → 升級寫回 PH2）與密語重設後的 session
+ *   撤銷時機：fork 呼叫端接線（revokeAllSessions 介面已備）。
+ * - 常數時間比較 timingSafeEq：./hash.ts 匯出（login 動線經 PH2 查詢不直比）。
  *
- * 與單一產品設計的結構差異（identity 模型已入型別）：
- * - identity 由伺服器端生成（隨機 account_id），不由客戶端帶入 soulKey——
- *   本核心以 identityCallback 抽象兩種模型，schema 欄位名由各 fork 自訂。
+ * 不變量（勿破壞）：
+ * - 金鑰包裹欄組（wrapped+salt）缺一整組放棄——pair 檢查本體在 pickKeyPackage。
+ * - recPkg 與 recHash 成對出現＝呼叫端（fork store）職責：本層介面兩參各自可空、
+ *   不做 pair 檢查（r2 MINOR-4 照此收口；pickKeyPackage 是同職責的成對檢查先例）。
  */
 
 import { corsResponse } from './cors.ts';
 import { sha256Hex, generateSessionToken } from './hash.ts';
 import { checkRate, type RateWindow } from './ratelimit.ts';
-import type { Env } from './env';
+import type { Env } from './env.ts';
 
 // ── 格式驗證（自 noteCrypt.ts 抽出；前綴由 config 注入） ─────────────────────
 
 export interface CipherFormats {
-  /** 密文前綴家族 regex 來源字串，如 '^jr1[gb]\.'。 */
+  /** 密文前綴家族字面（startsWith 語意，非 regex 來源），如 'jr1b.'。 */
   cipherPrefixes: [string, string];
   /** 金鑰包裹前綴，如 'jr1w.'。 */
   wrapPrefix: string;
-  /** 密文位元組上限（入庫原樣、禁截斷密文）。 */
+  /** 密文上限：UTF-16 code unit 計數（.length 語意；非 UTF-8 bytes）。 */
   cipherMax: number;
 }
 
@@ -36,17 +45,32 @@ const BINARY_RE = /[\x00-\x08\x0e-\x1f]/;
 const HASH64_RE = /^[0-9a-f]{64}$/;
 const SALT32_RE = /^[0-9a-f]{32}$/;
 
-function cipherRe(c: CipherFormats): RegExp {
-  const escaped = c.cipherPrefixes.map(p => p.replace('.', '\\.'));
+/** regex 用字面跳脫：全字元掃描（.replace('.',) 只跳第一個點——前綴含第二個 . 即壞）。 */
+function escapeReLiteral(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** 前綴家族 → 密文形 regex（單一組裝點；cipherRe 死碼退場）。
+ *  never-match 守衛（t_580f9c54 N-7，opt-in 鐵律面；run 574 r2 實測校正）：空字首組態會
+ *  組裝出 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——
+ *  「charset 恆假自帶防線」是錯誤敘事；帶點前綴向量舊碼本就 null＝帳面無承載。） */
+function cipherPrefixRe(cipherPrefixes: readonly string[]): RegExp {
+  const usable = cipherPrefixes.filter(p => typeof p === 'string' && p.length > 0);
+  if (usable.length === 0) return /^(?=a)b/; // never-match（lookahead 錨死矛盾面）——空字串/任意串皆不匹配
+  const escaped = usable.map(p => escapeReLiteral(p));
   return new RegExp(`^(${escaped.join('|')})[A-Za-z0-9+/]+={0,2}$`);
 }
 
 /**
  * 入庫前校正：前綴密文原樣入庫；超限密文／編碼丟棄（截斷必壞）、明文截到上限照收。
- * plainMax：明文相容層上限（入庫原樣、禁截斷密文；無明文相容層的產品可設 0）。
+ * cipherMax（UTF-16 單位）同為明文截斷帽：明文相容層無 opt-out——明文一律照收、
+ * 截到 cipherMax 入庫（r2 MINOR-5：JSDoc 幽靈參數 plainMax 摘除）。
  */
 export function makeInboundCipher(c: CipherFormats) {
-  const RE = new RegExp(`^(${c.cipherPrefixes.map(p => p.replace('.', '\\.')).join('|')})[A-Za-z0-9+/]+={0,2}$`);
+  const RE = cipherPrefixRe(c.cipherPrefixes);
   return function inboundCipher(raw: unknown): string | null {
     if (typeof raw !== 'string') return null;
     const text = raw.trim();
@@ -65,13 +89,17 @@ export function makeInboundCipher(c: CipherFormats) {
 
 export function isCipherFor(text: string | null | undefined, c: CipherFormats): boolean {
   if (typeof text !== 'string') return false;
-  return text.startsWith(c.cipherPrefixes[0]) || text.startsWith(c.cipherPrefixes[1]);
+  // 空字首組態同面守衛（t_580f9c54 N-7 範圍增補，run 574 r2）：'' 態 startsWith('') 恆真＝
+  // 整體分類面 accept-all（cipherPrefixRe never-match 守衛不覆蓋此直讀 tuple 面——本函式是
+  // 另一組裝點）。守衛形＝跳過空字首的 some() 單點承載：空集恆 false（與 never-match 家族拒絕、
+  // opt-in 未配置即拒鐵律同向）、混合形只摘空槽（['','jr1b.']＝jr1b. 家族面照活）——
+  // 「空集 if 檢＋保留 startsWith(tuple) 原式」兩行形對混合形不設防（空槽仍經 startsWith('') 放行）。
+  return c.cipherPrefixes.some(p => typeof p === 'string' && p.length > 0 && text.startsWith(p));
 }
 
 export function validWrappedKey(v: unknown, wrapPrefix: string | string[]): string | null {
   const prefixes = Array.isArray(wrapPrefix) ? wrapPrefix : [wrapPrefix];
-  const escaped = prefixes.map(p => p.replace('.', '\\.'));
-  const re = new RegExp(`^(${escaped.join('|')})[A-Za-z0-9+/]+={0,2}$`);
+  const re = cipherPrefixRe(prefixes);
   return typeof v === 'string' && v.length <= 200 && re.test(v) ? v : null;
 }
 
@@ -100,11 +128,22 @@ export interface KeyPackage {
 export interface AuthStore {
   /** 以 PH2 查身份（PH2 UNIQUE；tacet：隨機 account_id 在此建立）。 */
   findByIdentityQuery(ph2: string): Promise<AuthRow | null>;
-  /** 建立（identity 由本層 identityCallback 決定：隨機 account_id 或客戶端帶入語意）。 */
+  /** 建立（identity 生成由各 fork 自決——見檔頭「呼叫端職責」；PH2 UNIQUE 衝突亦是 store 責任）。 */
   createUser(ph2: string): Promise<string>;
   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 重鑰（v0.2.0 批卡② t_ce216a63）：舊值入 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 查表（v0.2.0 批卡② t_ce216a63）：以「舊 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,6 +5,10 @@ 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）。
+  // 86400 落業界 600-86400 慣例上緣；瀏覽器端自行 clamp（Chromium 2h／WebKit 10m、Firefox
+  // 照走）——快取命中不影響伺服器語意；消費端 inline OPTIONS 分流照 corsResponse 放行。
+  'Access-Control-Max-Age': '86400',
 };
 
 export function corsResponse(res: Response): Response {