@tacet-ink/journal-core 0.3.2 → 0.3.4

package/src/server/auth.ts

@@ -1,225 +0,0 @@
-/**
- * auth.ts — 零知識伺服器端 auth 核心邏輯（品牌／schema 參數化）。
- *
- * 本檔實作的契約：
- * - pass 明文永不過線：線上憑證送 PH1（雜湊形），伺服器存 PH2 = SHA-256(PH1)。
- *   PH1 派生方式由各產品自定義（快雜湊或 Argon2id 派生皆可）——本層只驗
- *   hex64 形，不驗 PH1 派生方式（伺服器零知識，無從也無需區分形別）。
- * - 入庫前密文／包裹格式驗證（inboundCipher／isCipherFor／validWrappedKey／
- *   pickKeyPackage 等，前綴由 config 注入）。
- * - /auth/login 核心動線（loginRouteCore）：rate-limit 閘 → PH1 驗形 →
- *   PH2 → store 查詢（現值 miss → ladder 查表守衛——0.2.4 內建，optional 未配置
- *   即退場）／建號 → session token 簽發（30 天）。
- *
- * 呼叫端（fork）職責——本檔只定義介面，機制在呼叫端實作：
- * - identity 生成：AuthStore.createUser 由各 fork 自決（隨機 account_id 或
- *   客戶端帶入語意皆可）；PH2 UNIQUE 衝突（兩個同時首登同密語）是 store
- *   責任——tacet 參考實作：UNIQUE 失敗重查既有列回 userKey（非 5xx）。
- * - hash-ladder 雙軌（舊式 PH1 直比 → 升級寫回 PH2）與密語重設後的 session
- *   撤銷時機：fork 呼叫端接線（revokeAllSessions 介面已備）；ladder 查表守衛已
- *   內建 loginRouteCore（optional——fork 只需配 ladderLookup＋0011 migration，接線零寫）。
- * - 常數時間比較 timingSafeEq：./hash.ts 匯出（login 動線經 PH2 查詢不直比）。
- *
- * 不變量（勿破壞）：
- * - 金鑰包裹欄組（wrapped+salt）缺一整組放棄——pair 檢查本體在 pickKeyPackage。
- * - recPkg 與 recHash 成對出現＝呼叫端（fork store）職責：本層介面兩參各自可空、
- *   不做 pair 檢查（裁定照此收口；pickKeyPackage 是同職責的成對檢查先例）。
- */
-
-import { corsResponse } from './cors.ts';
-import { sha256Hex, generateSessionToken } from './hash.ts';
-import { checkRate, type RateWindow } from './ratelimit.ts';
-import type { Env } from './env.ts';
-
-// ── 格式驗證（自 noteCrypt.ts 抽出；前綴由 config 注入） ─────────────────────
-
-export interface CipherFormats {
-  /** 密文前綴家族字面（startsWith 語意，非 regex 來源），如 'jr1b.'。 */
-  cipherPrefixes: [string, string];
-  /** 金鑰包裹前綴，如 'jr1w.'。 */
-  wrapPrefix: string;
-  /** 密文上限：UTF-16 code unit 計數（.length 語意；非 UTF-8 bytes）。 */
-  cipherMax: number;
-}
-
-const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
-const BINARY_RE = /[\x00-\x08\x0e-\x1f]/;
-const HASH64_RE = /^[0-9a-f]{64}$/;
-const SALT32_RE = /^[0-9a-f]{32}$/;
-
-/** regex 用字面跳脫：全字元掃描（.replace('.',) 只跳第一個點——前綴含第二個 . 即壞）。 */
-function escapeReLiteral(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/** 前綴家族 → 密文形 regex（單一組裝點；cipherRe 死碼退場）。
- *  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 實證：`[]` 對純 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}$`);
-}
-
-/**
- * 入庫前校正：前綴密文原樣入庫；超限密文／編碼丟棄（截斷必壞）、明文截到上限照收。
- * cipherMax（UTF-16 單位）同為明文截斷帽：明文相容層無 opt-out——明文一律照收、
- * 截到 cipherMax 入庫（JSDoc 幽靈參數 plainMax 已摘除）。
- */
-export function makeInboundCipher(c: CipherFormats) {
-  const RE = cipherPrefixRe(c.cipherPrefixes);
-  return function inboundCipher(raw: unknown): string | null {
-    if (typeof raw !== 'string') return null;
-    const text = raw.trim();
-    if (!text) return null;
-    if (text.length > c.cipherMax) {
-      return RE.test(text) || BASE64_RE.test(text)
-        ? null // 密文/編碼超限：截斷必壞，直接丟棄
-        : text.slice(0, c.cipherMax); // 純明文（舊版客戶端）：截到上限照收
-    }
-    if (RE.test(text)) return text; // 前綴密文：原樣入庫
-    if (BASE64_RE.test(text) && text.length > 40) return text; // 舊客戶端 b64 慣例：照收
-    if (BINARY_RE.test(text)) return null; // 控制字元垃圾：丟棄
-    return text; // 真明文：照收（舊版相容）
-  };
-}
-
-export function isCipherFor(text: string | null | undefined, c: CipherFormats): boolean {
-  if (typeof text !== 'string') return false;
-  // 空字首組態同面守衛（範圍增補）：'' 態 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 re = cipherPrefixRe(prefixes);
-  return typeof v === 'string' && v.length <= 200 && re.test(v) ? v : null;
-}
-
-export function validHash64(v: unknown): string | null {
-  return typeof v === 'string' && HASH64_RE.test(v) ? v : null;
-}
-
-export function validSalt(v: unknown): string | null {
-  return typeof v === 'string' && SALT32_RE.test(v) ? v : null;
-}
-
-/** 綁定/復原共用的金鑰包裹欄組：wrapped 與 salt 必須成對，缺一整組放棄。 */
-export function pickKeyPackage(body: any, wrapPrefix: string | string[]): { wrapped: string | null; salt: string | null } {
-  const wrapped = validWrappedKey(body?.note_wrapped ?? body?.wrapped, wrapPrefix);
-  const salt = validSalt(body?.note_salt ?? body?.salt);
-  return { wrapped: wrapped && salt ? wrapped : null, salt: wrapped && salt ? salt : null };
-}
-
-// ── 介面：各 fork 接線自己的 schema 欄位 ─────────────────────────────────────
-
-export interface KeyPackage {
-  wrapped: string;
-  salt: string;
-}
-
-export interface AuthStore {
-  /** 以 PH2 查身份（PH2 UNIQUE；tacet：隨機 account_id 在此建立）。 */
-  findByIdentityQuery(ph2: string): Promise<AuthRow | null>;
-  /** 建立（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 重鑰：舊值入 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。
-   * loginRouteCore 內建接線（0.2.4 外審 #8 幽靈守衛上位）：現值 miss → ladderLookup →
-   * 命中＝回舊帳（不建幽靈；ph2Kind 語意照 ladder.ts 檔頭註解——core 端回帳序：
-   * ladder hit → getByUserKey → 可續 buildSession），兩面皆 miss 才 createUser。
-   * 未配置（optional undefined）＝查表面退場（現行單查行為零變——向後相容：
-   * fork 未配 ladder（0011 未上）時行為與 0.2.3 恆等，sennight/vestige 未來接 core 也零炸）。
-   * 錯誤處理照 tacet store.ts 母型：lookup 拋任何錯（0011 未上的 ladder 表缺席、ladder store
-   * 停機故障）＝fail-open 視同 miss，不炸登入（ladder store 停機中登入＝建幽靈——fail-open
-   * 語意的已知代價；接線端 ladderGuard 統一 catch 只包 lookup）＋非 lookup 錯誤照常外拋。
-   */
-  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>;
-}
-
-export interface AuthRow {
-  userKey: string; // identity（account_id / user id）
-  ph2: string | null; // SHA-256(PH1)；null = 未綁定 guest
-  salt: string | null;
-  wrapped: string | null;
-  wrappedRec: string | null;
-  recHash: string | null;
-  /** 訂閱方案（tacet：users.plan，'free'/'paid'）；兄弟 fork 無訂閱面時預設 'free'。 */
-  plan?: string;
-}
-
-export const AUTH_RATE: RateWindow = { table: 'login_rate', windowMs: 60_000, max: 10 };
-
-export function errResponse(code: string, status: number): Response {
-  return corsResponse(new Response(code, { status }));
-}
-
-// ── /auth/login：PH1 進站 → PH2 查詢（UNIQUE）→ session ─────────────────────
-
-/**
- * loginRouteCore ladder 查表守衛（0.2.4 外審 #8 幽靈帳真洞收口——tacet fork 母型上位）：
- * 現值（PH2 UNIQUE 查表）miss 時，先查 ladder 表（ph2_ladder：遷移線落下的「舊 ph2 值」），
- * 命中＝回舊帳不建幽靈；ladder 也 miss（或未配置）＝才 createUser。
- * - ladder hit 語意照 ladder.ts 檔頭註解：表列只承載舊值，帳戶現行憑證面以
- *   `getByUserKey` 讀到的 users 現值為準（v3 帳的 salt/wrapped 已是 v3 形）；
- *   ladder hit → getByUserKey 落查無列（帳戶已刪、行殘留）＝誠實 miss 續走建幽靈。
- * - lookup 未配置（optional undefined）＝零呼叫，行為與 0.2.3 單查恆等（向後相容鐵律）；
- *   insert 是遷移線（rekeyWithLadder）職責、delete 已綁 delete-account（fork 面）——
- *   本守衛只動查表，零寫入面。
- * - lookup 拋錯（表缺席/儲存故障）＝fail-open 視同 miss，不炸登入（tacet store.ts 母型；
- *   靜默面照 tacet 慣例只 console.error）。
- * - 零知識照舊：ladder 只存 ph2 hash 與 account_id，本函式零新洩漏面。
- */
-async function ladderGuard(
-  store: AuthStore,
-  ph2: string,
-): Promise<AuthRow | null> {
-  if (!store.ladderLookup) return null;
-  let ladderAcc: string | null = null;
-  try {
-    ladderAcc = await store.ladderLookup(ph2);
-  } catch (e) {
-    console.error('[ph2-ladder] lookup failed (fail-open):', e);
-    return null;
-  }
-  if (!ladderAcc) return null;
-  return store.getByUserKey(ladderAcc);
-}
-
-export async function loginRouteCore(env: Env & Record<string, unknown>, store: AuthStore, ip: string, ph1In: unknown): Promise<Response> {
-  if (!(await checkRate(env, AUTH_RATE, ip))) return errResponse('ERR_RATE_LIMITED', 429);
-  const ph1 = validHash64(ph1In);
-  if (!ph1) return errResponse('ERR_BAD_REQUEST', 400);
-  const ph2 = await sha256Hex(ph1);
-  const user = (await store.findByIdentityQuery(ph2)) ?? (await ladderGuard(store, ph2));
-  const userKey: string = user ? user.userKey : await store.createUser(ph2);
-  const token = generateSessionToken();
-  const expiresAt = Date.now() + 30 * 24 * 60 * 60 * 1000; // PWA：30 天
-  await store.insertSession(await sha256Hex(token), userKey, expiresAt);
-  return corsResponse(new Response(JSON.stringify({
-    sessionToken: token,
-    userKey,
-    status: user?.ph2 ? 'ready' : 'require_binding',
-  }), { headers: { 'Content-Type': 'application/json' } }));
-}

package/src/server/cors.ts

@@ -1,22 +0,0 @@
-/**
- * cors.ts — 共用 CORS 本體（多產品 diff 證實完全一致，直取）。
- */
-export const CORS_HEADERS = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-  // preflight 快取（缺 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 {
-  const newHeaders = new Headers(res.headers);
-  Object.entries(CORS_HEADERS).forEach(([k, v]) => newHeaders.set(k, v));
-  return new Response(res.body, {
-    status: res.status,
-    statusText: res.statusText,
-    headers: newHeaders,
-  });
-}

package/src/server/env.ts

@@ -1,13 +0,0 @@
-/**
- * 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/hash.ts

@@ -1,28 +0,0 @@
-/**
- * hash.ts — 品牌無關的雜湊／token 工具。
- * 產品專屬 obfuscate/deobfuscate 不入 core（透明品牌裁定：明文 JSON + TLS）。
- */
-
-export async function sha256Hex(text: string): Promise<string> {
-  const data = new TextEncoder().encode(text);
-  const digest = await crypto.subtle.digest('SHA-256', data);
-  return Array.from(new Uint8Array(digest)).map(b => b.toString(16).padStart(2, '0')).join('');
-}
-
-/** 相容別名：姊妹產品呼叫點用此名。 */
-export const hashString = sha256Hex;
-
-/** 256-bit 隨機 session token（hex）。伺服器只存 SHA-256。 */
-export function generateSessionToken(): string {
-  return Array.from(crypto.getRandomValues(new Uint8Array(32)))
-    .map(b => b.toString(16).padStart(2, '0'))
-    .join('');
-}
-
-/** 常數時間字串比較（防時序側信道；多產品共用抽出）。 */
-export function timingSafeEq(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}

package/src/server/ladder.ts

@@ -1,76 +0,0 @@
-/**
- * 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 查列」與「遷移時入表」原語。查表守衛自 0.2.4 起
- * 內建 loginRouteCore（現值 miss → ladder → 兩面 miss 才建幽靈；lookup 未配置＝零呼叫
- * 行為零變）——自帶 login route 的 fork（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 對位面）。
- *  欄名映射註解（讀帳面——schema 欄名 vs Row 形名差異；t_87ef62dd #13 只補註解不改名，
- *  禁 consumer breaking）：schema 欄是 `upgraded_at`（D1/SQLite 欄面——「舊形被覆蓋的時刻」），
- *  Row 形名 `createdAt`（fork 消費面語意——「該舊值歷列建立時刻」）；同一值、兩層命名——
- *  findByOldPh2 讀取面做 upgraded_at→createdAt 的逐欄映射，改任一層名都是 breaking（禁動）。 */
-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,123 +0,0 @@
-/**
- * ratelimit.ts — per-IP fixed-window 限流（D1 計數，跨 isolate 有效；單句 UPSERT…RETURNING）。
- *
- * 設計（2026-10-04 定案：原 4 往返條件寫入鏈 1 往返收口）：
- * - 限流語意是 fixed window：以 window_start 為窗錨，窗過期整窗重置。
- *   （原檔頭「滑動視窗」措辭錯誤——c7c8701 只修 README 未修本檔；本檔一併收口。）
- * - 單條 UPSERT…RETURNING 原子完成「計數＋窗重置＋讀回放行判準」：
- *   同 IP 併發首發不再有 INSERT/輸家競態（同語句同鍵衝突時第二發原子吃到
- *   count+1；D1 實測 RETURNING 逐發回真值——同 IP 併發首發不 undercount）。
- * - fail-open 裁定不變（2026-09-06）：限流儲存故障時放行（保護面不可反噬主功能），
- *   只擋明確超額。RETURNING 異形回應（results 空／alias 斷裂）同向 fail-open
- *   並 console.error 照實回報（異形不反向成 deny）。
- *
- * 放行判準：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);
- * 可選 GC（未內建）：定期 DELETE WHERE window_start < {now} - windowMs。
- */
-
-import type { Env } from './env.ts';
-
-export interface RateWindow {
-  table: string;
-  windowMs: number;
-  max: number;
-}
-
-/**
- * 表名只允許 \w 字元（字母／數字／底線）：表名直接拼進 SQL 字串，禁注入符號。
- * 違例 throw——配置錯誤在開發期炸開，不靜默。
- */
-function assertSafeTable(table: string): void {
-  if (!/^[\w]+$/.test(table)) throw new Error(`ERR_RATE_TABLE_NAME: ${table}`);
-}
-
-/** @internal（0.1.6 公開面走 index.ts checkRate）。UPSERT…RETURNING 單句（{table} 佔位由呼叫端替換；D1 實測 RETURNING 列經 results 回帶）。 */
-export const SQL_RATE_BUMP = `INSERT INTO {table} (ip, window_start, count) VALUES (?1, ?2, 1)
-  ON CONFLICT(ip) DO UPDATE SET
-    count        = CASE WHEN window_start <= ?3 THEN 1 ELSE count + 1 END,
-    window_start = CASE WHEN window_start <= ?3 THEN ?2 ELSE window_start END
-  RETURNING count AS n`;
-
-/** @internal（0.1.6 公開面走 index.ts checkRate）。放行判準單一真相：窗口內超額後照實回實際 count，呼叫端以 count <= max 拒絕。 */
-export function isRateAllowed(count: number, max: number): boolean {
-  return count <= max;
-}
-
-async function bumpRate(env: Env, w: RateWindow, ip: string): Promise<boolean> {
-  assertSafeTable(w.table);
-  const now = Date.now();
-  try {
-    const { results } = await env.DB.prepare(
-      SQL_RATE_BUMP.replaceAll('{table}', w.table)
-    ).bind(ip, now, now - w.windowMs).run();
-    const first = results[0] as { n?: unknown } | undefined;
-    const n = first?.n;
-    if (typeof n !== 'number' || !Number.isFinite(n)) {
-      // 異形回應（results 空／alias 斷裂）與儲存故障同向 fail-open（2026-09-06 裁定：
-      // 缺陷偏向放行，不反向成 deny）；真 D1 不產生（探針實證）——守衛照實回報。
-      console.error(`[ratelimit] ${w.table} unexpected RETURNING shape:`, first);
-      return true;
-    }
-    return isRateAllowed(n, w.max);
-  } catch (e) {
-    // fail-open 裁定（2026-09-06）：儲存故障時放行，只擋明確超額
-    console.error(`[ratelimit] ${w.table} update failed:`, e);
-    return true;
-  }
-}
-
-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, normalizeRateIp(ip));
-}