@tacet-ink/journal-core 0.3.1 → 0.3.2

package/scripts/verify-core-crypto.ts

@@ -90,7 +90,7 @@ import {
   AUTH_RATE,
   type CipherFormats,
 } from '../src/server/auth.ts';
-import { checkRate, isRateAllowed, SQL_RATE_BUMP, type RateWindow } from '../src/server/ratelimit.ts';
+import { checkRate, isRateAllowed, normalizeRateIp, SQL_RATE_BUMP, type RateWindow } from '../src/server/ratelimit.ts';
 import { generateSessionToken, timingSafeEq } from '../src/server/hash.ts';
 import { CORS_HEADERS, corsResponse } from '../src/server/cors.ts';
 import {
@@ -157,7 +157,7 @@ async function A(name: string, cond: boolean | Promise<boolean>, detail = ''): P
 // 帳面契約：--only 態總帳顯形「本輪 X/選段帳 N（N 案非本輪載）」＋OK 標記帶 (--ONLY …) 尾碼；skip 段帳面恆列「未跑非通過」；[24]/[25] runner 自證段隨每輪在場。
 // 段標記 helper（secOpen）：全跑態輸出位元組恆等原 console.log('\n[N] …')；--only 態僅選中段輸出段頭。
 // 毒化矩陣內層 rerun（execFileSync＋POISON_GATE_INNER=1）不傳遞 --only＝內層恆全帳（POISON_GATE_INNER 語意不變）。
-// 段帳＝執行帳（healthy-repo 全跑 runtime 真值，2026-10-10 實測 506——A3 [27] +14）；帳面語意契約（逐段「案 X/帳」
+// 段帳＝執行帳（healthy-repo 全跑 runtime 真值，2026-10-11 實測 521——[12] 限流鍵 /64 正規化 +14＋IPv4-mapped 面 +1）；帳面語意契約（逐段「案 X/帳」
 // 對 secRan 執行值顯形）：執行 < 帳 的段＝本環境條件態未行使（非 skip 態），--only 期望算術對齊本帳。
 // [23] 執行 18 帳 21＝[23]④ lookup 未配置（0.2.3 單查恆等）／[23]⑤ fail-open（表缺席）兩情境
 // 在本機樹由 [8]（登入憑證 Argon2id 派生）內登入 lane 的訊號面真行使（try/catch 異常面）——車道分流非帳面虛報。
@@ -166,7 +166,7 @@ async function A(name: string, cond: boolean | Promise<boolean>, detail = ''): P
 // for (const [k] of secRan) if (!secCases[k] && k !== 22) FAIL（負向斷言本體在 [25] 段
 //——secCases 全摘即 RED）；反向缺席段＝帳面誠實「案 0/N · skip」。
 // secCases 載體三群：[24]/[25] self-account＋--only 段存在面＋teeth（段帳由 secRan 執行自記）。
-const secCases: Record<number, number> = { 1: 3, 2: 7, 3: 9, 4: 4, 5: 3, 6: 20, 7: 27, 8: 8, 9: 22, 10: 5, 11: 41, 12: 50, 13: 39, 14: 18, 15: 59, 16: 15, 17: 14, 18: 39, 19: 17, 20: 47, 21: 10, 23: 18, 24: 5, 25: 4, 26: 8, 27: 14 };
+const secCases: Record<number, number> = { 1: 3, 2: 7, 3: 9, 4: 4, 5: 3, 6: 20, 7: 27, 8: 8, 9: 22, 10: 5, 11: 41, 12: 65, 13: 39, 14: 18, 15: 59, 16: 15, 17: 14, 18: 39, 19: 17, 20: 47, 21: 10, 23: 18, 24: 5, 25: 4, 26: 8, 27: 14 };
 function parseOnly(spec: string): { err: string | null; set: number[] } {
   const set = new Set<number>();
   const specStr = spec.trim();
@@ -773,7 +773,7 @@ secOpen(12, '[12] 伺服器端原語（auth/ratelimit/hash）＋ 本機鎖定（
 // UPSERT…RETURNING 於 wrangler 4.129.0 workerd 逐發回真值；併發首發兩發計數 1→2）。
 type RateRow = { ip: string; window_start: number; count: number };
 const RATE: RateWindow = { table: 'login_rate', windowMs: 60_000, max: 3 };
-const makeRateDb = (): {
+const makeRateDb = (cr: typeof checkRate = checkRate): {
   db: {
     exec: (s: string) => void;
     prepare: (s: string) => { all: (...p: unknown[]) => Array<Record<string, unknown>>; get: (...p: unknown[]) => Record<string, unknown> | undefined };
@@ -798,7 +798,7 @@ const makeRateDb = (): {
   runRaw: (sql) => db.exec(sql),
     // 真 checkRate 直驅：?1/?2/?3 有名參數語意在 node:sqlite 與 workerd 一致（端對端探針實證，見卡 comments）。
     check: (ip) =>
-      checkRate(
+      cr(
         {
           DB: {
             prepare: (sql: string) => ({
@@ -871,6 +871,120 @@ await A('rate：RETURNING 異形回應守衛 fail-open（results 空／alias 斷
 })());
 await A('rate：SQL_RATE_BUMP 常數形（UPSERT…RETURNING…count AS n；{table} 佔位）',
   /^INSERT INTO \{table\} \(ip, window_start, count\) VALUES \(\?1, \?2, 1\)\n\s+ON CONFLICT\(ip\) DO UPDATE SET\n\s+count\s+= CASE WHEN window_start <= \?3 THEN 1 ELSE count \+ 1 END,\n\s+window_start = CASE WHEN window_start <= \?3 THEN \?2 ELSE window_start END\n\s+RETURNING count AS n$/.test(SQL_RATE_BUMP));
+// 限流鍵正規化（t_b30cbc5f）：checkRate 入口 normalizeRateIp——IPv6 聚合至 /64（尾段漂移不再每發新鍵）。
+// v6 面謂詞以模組參數化：同一謂詞本體先對真模組（綠）、再對拷貝樹毒化模組（IPv6 聚合分支摘除）須逐案真翻紅。
+type RateMod12 = { checkRate: typeof checkRate; normalizeRateIp: typeof normalizeRateIp };
+const rateReal12: RateMod12 = { checkRate, normalizeRateIp };
+const v6Cases12: Array<[string, (m: RateMod12) => Promise<boolean>]> = [
+  ['rate：IPv6 同 /64 尾段漂移兩地址（2001:db8:5678::1／2001:db8:5678:0:ffff:ffff:ffff:9）經真 checkRate 共用鍵 2001:db8:5678::/64 計數 2（裸地址不入表）', async (m) => {
+    const r = makeRateDb(m.checkRate);
+    await r.check('2001:db8:5678::1'); await r.check('2001:db8:5678:0:ffff:ffff:ffff:9');
+    return r.row('2001:db8:5678::/64')?.count === 2 && r.row('2001:db8:5678::1') === undefined;
+  }],
+  ['rate：IPv6 同 /64 輪換四個介面 ID → 三發 pass、第四發 reject（尾段漂移不再繞過 max）', async (m) => {
+    const r = makeRateDb(m.checkRate);
+    const seq: boolean[] = [];
+    for (const ip of ['2001:db8:77::1', '2001:db8:77::2', '2001:db8:77:0:a:b:c:d', '2001:db8:77::ffff']) seq.push(await r.check(ip));
+    return seq.join() === 'true,true,true,false';
+  }],
+  ['rate：IPv6 跨 /64 分鍵（2001:db8:5678::1／2001:db8:9999::1 → 兩 /64 鍵各計 1）', async (m) => {
+    const r = makeRateDb(m.checkRate);
+    await r.check('2001:db8:5678::1'); await r.check('2001:db8:9999::1');
+    return r.row('2001:db8:5678::/64')?.count === 1 && r.row('2001:db8:9999::/64')?.count === 1;
+  }],
+  ['rate：IPv6 同 /48 異 /64 分鍵（第 4 hextet 屬前綴：2001:db8:5678::1 → 2001:db8:5678::/64、2001:db8:5678:ffff::9 → 2001:db8:5678:ffff::/64 各計 1——聚合粒度恰 /64 非 /48）', async (m) => {
+    const r = makeRateDb(m.checkRate);
+    await r.check('2001:db8:5678::1'); await r.check('2001:db8:5678:ffff::9');
+    return r.row('2001:db8:5678::/64')?.count === 1 && r.row('2001:db8:5678:ffff::/64')?.count === 1;
+  }],
+  ['normalizeRateIp RFC 5952 形：2001:0DB8:0000:000A::1 → 2001:db8:0:a::/64（前導零摘、小寫、內部單零組不壓縮、尾零串 ::）；2001:db8:a::1 → 2001:db8:a::/64 異鍵（零組不吞＝前綴不碰撞）', async (m) =>
+    m.normalizeRateIp('2001:0DB8:0000:000A::1') === '2001:db8:0:a::/64' && m.normalizeRateIp('2001:db8:a::1') === '2001:db8:a::/64'],
+  ['normalizeRateIp 邊界：::1／0000:0000:0000:0000:1:2:3:4（全零前綴）／:: → 恆 ::/64（IPv4-mapped 位址另行回點分 IPv4，見下案）', async (m) =>
+    ['::1', '0000:0000:0000:0000:1:2:3:4', '::'].every((ip) => m.normalizeRateIp(ip) === '::/64')],
+  ['rate：normalizeRateIp IPv4-mapped 回點分 IPv4 鍵（/32 契約）：::ffff:192.0.2.1 → 192.0.2.1；hex 尾組同主機 twin ::ffff:c000:201 同鍵 192.0.2.1（mapped 裸形絕不入表）；兩台相異 mapped 主機經真 checkRate 各自鍵各計 1（不共 ::/64 桶）', async (m) => {
+    const r = makeRateDb(m.checkRate);
+    await r.check('::ffff:192.0.2.1'); await r.check('::ffff:c000:201'); await r.check('::ffff:192.0.2.2');
+    return m.normalizeRateIp('::ffff:192.0.2.1') === '192.0.2.1'
+      && m.normalizeRateIp('::ffff:c000:201') === '192.0.2.1'
+      && r.row('192.0.2.1')?.count === 2
+      && r.row('192.0.2.2')?.count === 1
+      && r.row('::ffff:192.0.2.1') === undefined && r.row('::ffff:c000:201') === undefined
+      && r.row('::/64') === undefined;
+  }],
+  ['normalizeRateIp zone id 剝除＋輸出小寫＋嵌入 IPv4 末組：fe80::1%eth0 → fe80::/64；FE80::ABCD → fe80::/64；1:2:3:4:5:6:1.2.3.4 → 1:2:3:4::/64', async (m) =>
+    m.normalizeRateIp('fe80::1%eth0') === 'fe80::/64' && m.normalizeRateIp('FE80::ABCD') === 'fe80::/64'
+    && m.normalizeRateIp('1:2:3:4:5:6:1.2.3.4') === '1:2:3:4::/64'],
+];
+const plainCases12: Array<[string, (m: RateMod12) => Promise<boolean>]> = [
+  ['rate：IPv4 原樣鍵（192.0.2.1 經真 checkRate 鍵面＝self、計數 1）', async (m) => {
+    const r = makeRateDb(m.checkRate);
+    await r.check('192.0.2.1');
+    return m.normalizeRateIp('192.0.2.1') === '192.0.2.1' && r.row('192.0.2.1')?.count === 1;
+  }],
+  ["rate：'unknown'／空串原樣鍵（經真 checkRate 照樣進表＝可見面，不靜默丟鍵）", async (m) => {
+    const r = makeRateDb(m.checkRate);
+    await r.check('unknown'); await r.check('');
+    return m.normalizeRateIp('unknown') === 'unknown' && m.normalizeRateIp('') === ''
+      && r.row('unknown')?.count === 1 && r.row('')?.count === 1;
+  }],
+  ['normalizeRateIp 無法解析形原樣且零 throw（IPv4 五段／IPv6 單段 2001／缺組／雙 ::／:::／非 hex／9 組／:: 外 8 組／嵌入 IPv4 越界／方括號／前導空白／非字串）', async (m) => {
+    const bad = ['1.2.3.4.5', '2001', '2001:db8', '1::2::3', ':::', '2001:db8::g', '1:2:3:4:5:6:7:8:9', '1:2:3:4:5:6:7:8::', '::ffff:999.0.0.1', '[2001:db8::1]', ' 2001:db8::1'];
+    try {
+      return bad.every((ip) => m.normalizeRateIp(ip) === ip)
+        && (m.normalizeRateIp(undefined as unknown as string) as unknown) === undefined;
+    } catch { return false; }
+  }],
+];
+for (const [name, pred] of [...v6Cases12, ...plainCases12]) await A(name, await pred(rateReal12));
+await A('index barrel 匯出 normalizeRateIp（＝ratelimit 子路徑同一函式——單一真相）',
+  (await import('../src/index.ts')).normalizeRateIp === normalizeRateIp);
+// 毒化（拷貝樹 in-gate，[23] 母型）：IPv6 聚合分支入口 `if (!g) return ip;` → `return ip;`（IPv6 一律原樣成鍵）
+// → v6 面謂詞逐案真翻紅（false 非 crash）、非 v6 面照綠（毒面恰此面翻）。毒化跑在 /tmp 拷貝＝本 repo 樹零接觸、樹出生即棄。
+{
+  const gb12 = (id: string): unknown =>
+    (globalThis as unknown as { process?: { getBuiltinModule?: (i: string) => unknown } }).process?.getBuiltinModule?.(id);
+  const fs12 = gb12('node:fs') as {
+    mkdtempSync: (p: string) => string;
+    writeFileSync: (p: string, s: string, e: string) => void;
+    rmSync: (p: string, o?: unknown) => void;
+    existsSync: (p: string) => boolean;
+  } | undefined;
+  const os12 = gb12('node:os') as { tmpdir: () => string } | undefined;
+  const path12 = gb12('node:path') as { join: (...p: string[]) => string } | undefined;
+  const url12 = gb12('node:url') as { pathToFileURL: (p: string) => { href: string } } | undefined;
+  const needle12 = '  if (!g) return ip;\n';
+  const src12 = await srcOf('../src/server/ratelimit.ts');
+  const cnt12 = src12.split(needle12).length - 1;
+  await A('rate 毒化錨恰 1（IPv6 聚合分支入口單點承載）', cnt12 === 1, 'cnt=' + cnt12);
+  if (!fs12 || !os12 || !path12 || !url12) {
+    await A('rate 毒化面（原語缺席環境）＝顯性 RED 行，毒化證據缺席顯形非 silent true', false, 'node fs/os/path/url 原語缺席');
+  } else if (cnt12 === 1) {
+    const tree12 = fs12.mkdtempSync(path12.join(os12.tmpdir(), 't12-ratekey-'));
+    const flipped12: string[] = [];
+    const held12: string[] = [];
+    let plainOk12 = false;
+    try {
+      fs12.writeFileSync(path12.join(tree12, 'ratelimit.ts'), src12.replace(needle12, '  return ip;\n'), 'utf8');
+      fs12.writeFileSync(path12.join(tree12, 'env.ts'), await srcOf('../src/server/env.ts'), 'utf8');
+      const modP12 = (await import(url12.pathToFileURL(path12.join(tree12, 'ratelimit.ts')).href)) as RateMod12;
+      for (const [name, pred] of v6Cases12) {
+        let res: string;
+        try { res = String(await pred(modP12)); } catch (e) { res = 'crash: ' + String((e as Error).message).slice(0, 80); }
+        (res === 'false' ? flipped12 : held12).push(name.slice(0, 40) + ' → ' + res);
+      }
+      plainOk12 = (await Promise.all(plainCases12.map(([, pred]) => pred(modP12)))).every((x) => x);
+    } catch (e) {
+      held12.push('poison import crash: ' + String((e as Error).message).slice(0, 120));
+    } finally {
+      fs12.rmSync(tree12, { recursive: true, force: true });
+    }
+    await A('rate 毒化（IPv6 聚合分支摘除）→ v6 面謂詞逐案真翻紅（' + v6Cases12.length + ' 案全 false、零 crash）',
+      held12.length === 0 && flipped12.length === v6Cases12.length,
+      'flipped=' + flipped12.length + '/' + v6Cases12.length + (held12.length ? '；未翻：' + held12.join('｜') : ''));
+    await A('rate 毒化面精準：非 v6 面照綠（IPv4／unknown／無效形——毒面恰 IPv6 聚合面翻）＋毒化樹出生即棄（本 repo 樹零接觸）',
+      plainOk12 && !fs12.existsSync(tree12));
+  }
+}
 await A('AUTH_RATE 契約（60s 窗 max 10）', AUTH_RATE.windowMs === 60_000 && AUTH_RATE.max === 10);
 const sessA = generateSessionToken();
 const sessB = generateSessionToken();
@@ -2810,7 +2924,7 @@ secOpen(23, '[23] loginRouteCore ladder 查表守衛（外審 #8 幽靈帳——
 // 單向契約：源碼 → scripts/generate-vectors.ts → JSON（凍結證據，commit 入 repo）→ 本段只檢存在＋shape。
 // 本段不依賴產生器、不重算 KDF（向量含隨機 iv/鹽＝重算即漂移）；BIP39 是確定性轉寫，逐組對照現行原語。
 // teeth：payload 位元組長度＝b64 解碼真值、fields 拼接＝payload 逐位元組、布局長度＝規格表列、
-// 欄位名逐一在規格檔、凍結 blob 逐字＝本閘 KAT 字面（[14]/[17]/[20]）、RFC 9106 期望值＝argon2.ts 常數。
+// 欄位名限定形逐一在規格對應節、凍結 blob 逐字＝本閘 KAT 字面（[14]/[17]/[20]）、RFC 9106 期望值＋參數＝argon2.ts 常數。
 secOpen(26, '[26] 格式規格＋測試向量（docs/format-spec.md＋docs/vectors 存在性＋shape）'); if (secEnter(26)) {
 {
   const readJson26 = async (rel: string): Promise<Record<string, unknown> | null> => {
@@ -2851,16 +2965,37 @@ secOpen(26, '[26] 格式規格＋測試向量（docs/format-spec.md＋docs/vecto
       const head = v.layout === 'salt-embedded' ? v.fields[0]?.name === 'pinSalt' && v.fields[0]?.len === 16 : v.fields[0]?.name === 'iv';
       return want === v.payload_len && head && specRows26.some((l) => l.startsWith('| `' + v.prefix + '`') && l.includes('| ' + v.layout + ' | ' + lenCol + ' |'));
     }));
-  const KKEYS26 = ['rfc9106', 'frozen_blobs', 'credentials', 'expected_tag_hex', 'expected_note_key_hex', 'expected_hex', 'samples', 'entropy_hex', 'checksum_hex', 'words', 'source'];
-  await A('[26] 欄位名對規格：families 每筆欄名＋fields 子欄（name/offset/len/hex）＋kat/bip39 欄名，逐一以 `欄名` 形出現在 format-spec.md',
-    spec26.length > 0 && [...HEAD26, ...VKEYS26, 'name', 'offset', 'len', 'hex', ...KKEYS26].every((k) => spec26.includes('`' + k + '`'))
-    && KKEYS26.slice(0, 3).every((k) => !!kat26 && k in kat26) && !!bip26 && 'samples' in bip26);
+  // 欄位名限定形（通用字 name/len/hex/source… 在規格檔隨處可見＝裸字檢查無咬力）：頂層欄＝§7 頭表／§7.1／§7.2 對應節
+  // 的表列 `| \`欄\` |`；巢狀欄＝限定形 `父[].欄`／`rfc9106.欄` 逐字在規格檔。欄名集取自向量檔實際鍵（新增欄未入規格＝紅）。
+  const sec26 = (from: string, to: string): string => { const i = spec26.indexOf(from); const j = to ? spec26.indexOf(to, i + 1) : spec26.length; return i < 0 || j < 0 ? '' : spec26.slice(i, j); };
+  const s7h26 = sec26('## 7. ', '### 7.1 '), s71_26 = sec26('### 7.1 ', '### 7.2 '), s72_26 = sec26('### 7.2 ', '### 7.3 '), s73_26 = sec26('### 7.3 ', '');
+  const row26 = (sec: string, k: string): boolean => sec.includes('\n| `' + k + '` |');
+  const keysOf26 = (xs: unknown): string[] => [...new Set((Array.isArray(xs) ? xs : []).flatMap((x) => (x && typeof x === 'object' ? Object.keys(x) : [])))];
+  const fieldKeys26 = keysOf26(vecs26.flatMap((v) => (Array.isArray(v.fields) ? v.fields : [])));
+  const rfcKeys26 = Object.keys((kat26?.rfc9106 ?? {}) as object);
+  const frozenKeys26 = keysOf26(kat26?.frozen_blobs), credKeys26 = keysOf26(kat26?.credentials), sampleKeys26 = keysOf26(bip26?.samples);
+  // 反空轉下限：實際鍵集須涵蓋閘面讀取的欄（鍵集取自資料＝資料缺欄時下限擋住空集合真值）
+  const floor26 = (ks: string[], need: string[]): boolean => need.every((k) => ks.includes(k));
+  await A('[26] 欄位名對規格（限定形）：頂層欄＝§7 頭表／§7.1 vectors 表／§7.2 kat 表逐列；巢狀欄逐一以 `fields[].欄`／`rfc9106.欄`／`frozen_blobs[].欄`／`credentials[].欄`／`samples[].欄` 出現在對應節（欄名集取自向量檔實鍵＋閘讀欄下限）',
+    spec26.length > 0 && !!kat26 && !!bip26
+    && HEAD26.every((k) => row26(s7h26, k)) && keysOf26(vecs26).every((k) => row26(s71_26, k)) && VKEYS26.every((k) => row26(s71_26, k))
+    && ['rfc9106', 'frozen_blobs', 'credentials'].every((k) => k in kat26! && row26(s72_26, k)) && 'samples' in bip26! && s73_26.includes('`samples`')
+    && floor26(fieldKeys26, ['name', 'offset', 'len', 'hex']) && fieldKeys26.every((k) => s71_26.includes('`fields[].' + k + '`'))
+    && floor26(rfcKeys26, ['memory_kib', 'iterations', 'parallelism', 'tag_len', 'password_hex', 'salt_hex', 'expected_tag_hex']) && rfcKeys26.every((k) => s72_26.includes('`rfc9106.' + k + '`'))
+    && floor26(frozenKeys26, ['prefix', 'wire', 'payload_len', 'expected_note_key_hex', 'source']) && frozenKeys26.every((k) => s72_26.includes('`frozen_blobs[].' + k + '`'))
+    && floor26(credKeys26, ['kind', 'expected_hex']) && credKeys26.every((k) => s72_26.includes('`credentials[].' + k + '`'))
+    && floor26(sampleKeys26, ['entropy_hex', 'checksum_hex', 'words', 'source']) && sampleKeys26.every((k) => s73_26.includes('`samples[].' + k + '`')));
   const gate26 = await srcOf('./verify-core-crypto.ts');
   const frozen26 = (Array.isArray(kat26?.frozen_blobs) ? kat26!.frozen_blobs : []) as { prefix: string; wire: string; payload_len: number; expected_note_key_hex: string; source: string }[];
   const rfc26 = (kat26?.rfc9106 ?? {}) as Record<string, unknown>;
   const creds26 = (Array.isArray(kat26?.credentials) ? kat26!.credentials : []) as { kind: string; expected_hex: string }[];
-  await A('[26] kat 對帳：RFC 9106 expected_tag_hex＝ARGON_RFC9106_EXPECTED（argon2.ts 常數）；凍結 blob 7 筆逐字＝本閘 KAT 字面（[14]/[17]/[20]）且 payload_len＝解碼真長；憑證樣本 5 筆 hex64',
-    (await import('../src/client/argon2.ts')).ARGON_RFC9106_EXPECTED === rfc26.expected_tag_hex
+  const argon26 = await import('../src/client/argon2.ts');
+  const kp26 = argon26.ARGON_RFC9106_PARAMS;
+  await A('[26] kat 對帳：RFC 9106 expected_tag_hex＝ARGON_RFC9106_EXPECTED、參數 m/t/p/tag/pwd/salt＝ARGON_RFC9106_PARAMS（argon2.ts 常數——verifyArgonKat／產生器同源）；凍結 blob 7 筆逐字＝本閘 KAT 字面（[14]/[17]/[20]）且 payload_len＝解碼真長；憑證樣本 5 筆 hex64',
+    argon26.ARGON_RFC9106_EXPECTED === rfc26.expected_tag_hex
+    && rfc26.memory_kib === kp26.memoryKib && rfc26.iterations === kp26.iterations && rfc26.parallelism === kp26.parallelism
+    && rfc26.tag_len === kp26.tagLen && kp26.tagLen === argon26.ARGON_TAG_LEN
+    && rfc26.password_hex === kp26.passwordByte.toString(16).padStart(2, '0').repeat(kp26.passwordLen) && rfc26.salt_hex === '00'.repeat(kp26.saltLen)
     && frozen26.length === 7 && frozen26.every((b) => gate26.includes("'" + b.wire + "'") && b.wire.startsWith(b.prefix)
       && unb64Mod(b.wire.slice(b.prefix.length)).length === b.payload_len && /^[0-9a-f]{64}$/.test(b.expected_note_key_hex))
     && creds26.length === 5 && creds26.every((c) => /^[0-9a-f]{64}$/.test(c.expected_hex)));

package/src/client/argon2.ts

@@ -52,6 +52,12 @@ function deriveInput(passphrase: string): string {
 export const ARGON_RFC9106_EXPECTED =
   '72d2a36fd5c266bcc96121b24937bc253338cdfcbd273713655748c54b4dd503';
 
+/** RFC 9106 KAT 參數單一真相（verifyArgonKat／scripts/generate-vectors.ts 寫 kat.json／閘 [26] 對帳共用）。
+ *  tagLen＝派生本體固定輸出長（ARGON_TAG_LEN）；pwd＝passwordLen 位元組 passwordByte、salt＝saltLen 位元組 0x00。 */
+export const ARGON_RFC9106_PARAMS = Object.freeze({
+  memoryKib: 32, iterations: 3, parallelism: 4, tagLen: 32, passwordByte: 0x01, passwordLen: 32, saltLen: 16,
+} as const);
+
 /**
  * PH1 v2 固定域鹽（登入憑證 Argon2id 派生，2026-09-10 安全路線第 4 步）。
  *
@@ -229,7 +235,8 @@ type NodeArgonFn = (
 
 /** 標準向量 KAT：驗證當前載體的 Argon2id 實作正確性（驗證閘起手式）。 */
 export async function verifyArgonKat(): Promise<boolean> {
-  const raw = await deriveArgon2id(new Uint8Array(32).fill(1), new Uint8Array(16), 32, 3, 4);
+  const k = ARGON_RFC9106_PARAMS;
+  const raw = await deriveArgon2id(new Uint8Array(k.passwordLen).fill(k.passwordByte), new Uint8Array(k.saltLen), k.memoryKib, k.iterations, k.parallelism);
   return toHex(raw) === ARGON_RFC9106_EXPECTED;
 }
 
@@ -244,7 +251,7 @@ export async function deriveKekArgon(password: string, salt: Uint8Array): Promis
   return argonKekFromRaw(await deriveArgon2id(password, salt, ARGON_MEMORY_KIB, ARGON_ITERATIONS, ARGON_PARALLELISM));
 }
 
-/** jr3w. 包裹：payload = salt[16] ‖ iv[12] ‖ AES-GCM(KEK, hex(noteKey), aad='notekey')；salt 由呼叫端存 users.salt。 */
+/** jr3w. 包裹：payload = iv[12] ‖ AES-GCM(KEK, hex(noteKey), aad='notekey')（鹽外置家族，嚴格 92B）；salt 不入 payload，由呼叫端存 users.salt。 */
 export async function wrapNoteKey3(cfg: Argon3Config, noteKey: CryptoKey, passphrase: string): Promise<{ wrapped: string; salt: string }> {
   if (!cfg.wrap3) throw new Error('ERR_JR3W_NOT_CONFIGURED');
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LEN));
@@ -279,7 +286,7 @@ export async function unwrapNoteKey3(cfg: Argon3Config, wrapped: string, passphr
 // 與 cfg.wrap4 前綴。舊 payload（jr1w./jr3w.）永遠可解＝raw 派生；新 payload 只由 jr4w. 產生。
 // pinSaltPrefix 沿用 cfg 既有欄（Argon3 家族 PIN 鹽域，非 jr3d. 專屬）。
 
-/** jr4w. 包裹（v3 密語）：payload = salt[16] ‖ iv[12] ‖ GCM(KEK, hex(noteKey), aad='notekey')；salt 呼叫端存 users.salt。 */
+/** jr4w. 包裹（v3 密語）：payload = iv[12] ‖ GCM(KEK, hex(noteKey), aad='notekey')（鹽外置家族，嚴格 92B）；salt 不入 payload，呼叫端存 users.salt。 */
 export async function wrapNoteKey4(cfg: Argon3Config, noteKey: CryptoKey, passphrase: string): Promise<{ wrapped: string; salt: string }> {
   if (!cfg.wrap4) throw new Error('ERR_JR4W_NOT_CONFIGURED');
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LEN));

package/src/client/note-crypto.ts

@@ -27,6 +27,8 @@
 
 // ── 配置 ────────────────────────────────────────────────────────────────────
 
+import type { KeyStore } from './keys.js';
+
 export interface NoteCryptoConfig {
   /** guest 時代 KDF 前綴，如 'journal-note-u1'。 */
   guestKdfPrefix: string;
@@ -75,7 +77,7 @@ export interface NoteCryptoConfig {
   /** 本機 IDB 密文前綴（jr1d.，notes store stored 形）。未配置 = local API 拒絕（未配置行為不變）。 */
   cipherLocal?: string;
   /** localStorage key store（品牌前綴由 keys.ts 管理）。 */
-  store: import('./keys').KeyStore;
+  store: KeyStore;
 }
 
 export const PBKDF2_ITERATIONS = 600_000; // OWASP 2023 建議值

package/src/index.ts

@@ -86,7 +86,7 @@ export {
   type CipherFormats,
   type KeyPackage,
 } from './server/auth.ts';
-export { checkRate, type RateWindow } from './server/ratelimit.ts';
+export { checkRate, normalizeRateIp, type RateWindow } from './server/ratelimit.ts';
 export { corsResponse, CORS_HEADERS } from './server/cors.ts';
 export {
   sha256Hex,

package/src/server/env.ts

@@ -1,6 +1,13 @@
 /**
  * env.ts — core 對 Worker Env 的最小介面。各 fork 的 Env 以此為基底擴充。
+ *
+ * D1Database 型別以模組 import 承載（非全域 triple-slash reference）：
+ * 消費者未帶 @cloudflare/workers-types 時，吃 client 面 .d.ts 不會被 env.d.ts 的
+ * 全域型別缺席炸掉（types= reference 在 types 套件缺席＝TS2688 全檔紅；import type
+ * 缺席＝該欄型別 any 化＋TS2304 只在吃 env.d.ts 的檔案現形＝影響面收斂）。
  */
+import type { D1Database } from '@cloudflare/workers-types';
+
 export interface Env {
   DB: D1Database;
 }

package/src/server/ratelimit.ts

@@ -14,6 +14,10 @@
  * 放行判準：RETURNING 的 count <= max（窗口內超額後的每一發都回實際 count，
  * 由呼叫端以 count <= max 拒絕——計數不封頂，超額仍逐發累計）。
  *
+ * 限流鍵（2026-10-11 定案）：checkRate 入口經 normalizeRateIp 正規化——IPv6 聚合至 /64
+ * （單一終端可自由輪換 /64 內尾段＝完整地址當鍵即每發新鍵、限流失效）；IPv4-mapped
+ * 位址回點分 IPv4（＝原生 IPv4 同 /32 鍵，review r1 MAJOR-1 收口）；IPv4 與非 IPv6 形原樣。
+ *
  * 呼叫端須自建表（無 GC 機制：舊 IP 列不清，表隨活躍 IP 數緩慢增長——
  * 每列 ~40 bytes，量級可忽略；如需回收見下方 GC 註記）：
  *   CREATE TABLE IF NOT EXISTS {table} (ip TEXT PRIMARY KEY, window_start INTEGER, count INTEGER);
@@ -71,6 +75,49 @@ async function bumpRate(env: Env, w: RateWindow, ip: string): Promise<boolean> {
   }
 }
 
+const HEXTET = /^[0-9a-f]{1,4}$/i;
+const IPV4_OCTET = /^(0|[1-9]\d{0,2})$/;
+
+/** IPv6 文字形 → 8 組 hextet 數值（RFC 4291 §2.2：`::` 至多一處、嵌入 IPv4 僅居末）；非法形回 null。 */
+function parseIpv6(s: string): number[] | null {
+  const halves = s.split('::');
+  if (halves.length > 2) return null;
+  const parts = halves.map((h) => (h === '' ? [] : h.split(':')));
+  const last = parts[parts.length - 1];
+  const v4: number[] = [];
+  if (last.length > 0 && last[last.length - 1].includes('.')) {
+    const q = last.pop()!.split('.');
+    if (q.length !== 4 || !q.every((o) => IPV4_OCTET.test(o) && Number(o) <= 255)) return null;
+    v4.push(Number(q[0]) * 256 + Number(q[1]), Number(q[2]) * 256 + Number(q[3]));
+  }
+  if (!parts.every((p) => p.every((g) => HEXTET.test(g)))) return null;
+  const n = parts.reduce((a, p) => a + p.length, 0) + v4.length;
+  const hex = (p: string[]): number[] => p.map((g) => parseInt(g, 16));
+  if (halves.length === 1) return n === 8 ? [...hex(parts[0]), ...v4] : null;
+  if (n > 7) return null;
+  return [...hex(parts[0]), ...new Array<number>(8 - n).fill(0), ...hex(parts[1]), ...v4];
+}
+
+/**
+ * 限流鍵正規化（單一真相；純函式、零 throw）：
+ * - IPv6 → /64 前綴＋`/64` 標記（RFC 5952 規範形：hextet 前導零摘除、小寫、零串壓縮），
+ *   例 `2001:0DB8:0000:000A::1` → `2001:db8:0:a::/64`、`::1` → `::/64`；zone id（`%…`）先剝除。
+ *   介面 ID 歸零後末 4 組恆零＝最長零串恆為尾串（前綴內零串至多 3 組），故壓縮形＝前綴摘尾零組＋`::`。
+ * - IPv4-mapped（::/96 前綴＋映射尾組，RFC 4291 §2.5.5.2）→ 點分 IPv4 原鍵——mapped 位址就是 IPv4
+ *   節點的表示法，回 /32 與原生同鍵（hex 尾組 twin `::ffff:c000:201` 同鍵 192.0.2.1；禁併入 ::/64 全域桶）。
+ * - IPv4／`'unknown'`／空串／無法解析形：原樣返回（鍵照樣進表＝可見面，不靜默丟鍵）。
+ */
+export function normalizeRateIp(ip: string): string {
+  if (typeof ip !== 'string' || !ip.includes(':')) return ip;
+  const pct = ip.indexOf('%');
+  const g = parseIpv6(pct >= 0 ? ip.slice(0, pct) : ip);
+  if (!g) return ip;
+  if (g[0] === 0 && g[1] === 0 && g[2] === 0 && g[3] === 0 && g[4] === 0 && g[5] === 0xffff) return [g[6] >> 8, g[6] & 255, g[7] >> 8, g[7] & 255].join('.');
+  const net = g.slice(0, 4);
+  while (net.length > 0 && net[net.length - 1] === 0) net.pop();
+  return net.map((h) => h.toString(16)).join(':') + '::/64';
+}
+
 export function checkRate(env: Env, w: RateWindow, ip: string): Promise<boolean> {
-  return bumpRate(env, w, ip);
+  return bumpRate(env, w, normalizeRateIp(ip));
 }