@tacet-ink/journal-core 0.2.4 → 0.3.0

package/dist/server/auth.js

@@ -0,0 +1,158 @@
+/**
+ * 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.js';
+import { sha256Hex, generateSessionToken } from './hash.js';
+import { checkRate } from './ratelimit.js';
+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) {
+    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) {
+    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) {
+    const RE = cipherPrefixRe(c.cipherPrefixes);
+    return function inboundCipher(raw) {
+        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, c) {
+    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, wrapPrefix) {
+    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) {
+    return typeof v === 'string' && HASH64_RE.test(v) ? v : null;
+}
+export function validSalt(v) {
+    return typeof v === 'string' && SALT32_RE.test(v) ? v : null;
+}
+/** 綁定/復原共用的金鑰包裹欄組：wrapped 與 salt 必須成對，缺一整組放棄。 */
+export function pickKeyPackage(body, wrapPrefix) {
+    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 };
+}
+export const AUTH_RATE = { table: 'login_rate', windowMs: 60_000, max: 10 };
+export function errResponse(code, status) {
+    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, ph2) {
+    if (!store.ladderLookup)
+        return null;
+    let ladderAcc = 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, store, ip, ph1In) {
+    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 = 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/dist/server/cors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * cors.ts — 共用 CORS 本體（多產品 diff 證實完全一致，直取）。
+ */
+export declare const CORS_HEADERS: {
+    'Access-Control-Allow-Origin': string;
+    'Access-Control-Allow-Methods': string;
+    'Access-Control-Allow-Headers': string;
+    'Access-Control-Max-Age': string;
+};
+export declare function corsResponse(res: Response): Response;

package/dist/server/cors.js

@@ -0,0 +1,21 @@
+/**
+ * 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) {
+    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/dist/server/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * env.ts — core 對 Worker Env 的最小介面。各 fork 的 Env 以此為基底擴充。
+ */
+export interface Env {
+    DB: D1Database;
+}

package/dist/server/env.js

@@ -0,0 +1 @@
+export {};

package/dist/server/hash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * hash.ts — 品牌無關的雜湊／token 工具。
+ * 產品專屬 obfuscate/deobfuscate 不入 core（透明品牌裁定：明文 JSON + TLS）。
+ */
+export declare function sha256Hex(text: string): Promise<string>;
+/** 相容別名：姊妹產品呼叫點用此名。 */
+export declare const hashString: typeof sha256Hex;
+/** 256-bit 隨機 session token（hex）。伺服器只存 SHA-256。 */
+export declare function generateSessionToken(): string;
+/** 常數時間字串比較（防時序側信道；多產品共用抽出）。 */
+export declare function timingSafeEq(a: string, b: string): boolean;

package/dist/server/hash.js

@@ -0,0 +1,26 @@
+/**
+ * hash.ts — 品牌無關的雜湊／token 工具。
+ * 產品專屬 obfuscate/deobfuscate 不入 core（透明品牌裁定：明文 JSON + TLS）。
+ */
+export async function sha256Hex(text) {
+    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() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(32)))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** 常數時間字串比較（防時序側信道；多產品共用抽出）。 */
+export function timingSafeEq(a, b) {
+    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/dist/server/ladder.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare const PH2_LADDER_TABLE = "ph2_ladder";
+/** ladder 行 kinds：'legacy'（SHA-256 快雜湊世代）與 'v2'（v2 形前身，遷移的正常前身）。
+ *  「帳戶現在用什麼形」的真相在 users.ph2 班表行（ph2_ladder 只承載舊值）；kind 欄
+ *  純粹是「這個舊值當年是什麼形」的語意記錄。 */
+export type Ph2LadderKind = 'legacy' | 'v2';
+export declare const PH2_LADDER_KIND_LEGACY = "legacy";
+export declare 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 declare function makePh2LadderStore(env: Env): {
+    findByOldPh2(oldPh2: string): Promise<Ph2LadderRow | null>;
+    insert(accountId: string, oldPh2: string, oldKind: Ph2LadderKind): Promise<void>;
+};

package/dist/server/ladder.js

@@ -0,0 +1,50 @@
+/**
+ * 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 裁定）續走自身接線。
+ */
+/** ladder 表名（migration 同名；單一真相，fork migration 與本原語同字面）。 */
+export const PH2_LADDER_TABLE = 'ph2_ladder';
+export const PH2_LADDER_KIND_LEGACY = 'legacy';
+export const PH2_LADDER_KIND_V2 = 'v2';
+/** 以「舊 ph2」查 ladder（fork store 對位面）。null = ladder miss。 */
+export function makePh2LadderStore(env) {
+    return {
+        async findByOldPh2(oldPh2) {
+            const row = await env.DB.prepare(`SELECT account_id, ph2_kind, upgraded_at FROM ${PH2_LADDER_TABLE} WHERE ph2 = ?`).bind(oldPh2).first();
+            if (!row)
+                return null;
+            return { accountId: row.account_id, ph2Kind: row.ph2_kind, createdAt: row.upgraded_at };
+        },
+        async insert(accountId, oldPh2, oldKind) {
+            // 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/dist/server/ratelimit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 拒絕——計數不封頂，超額仍逐發累計）。
+ *
+ * 呼叫端須自建表（無 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;
+}
+/** @internal（0.1.6 公開面走 index.ts checkRate）。UPSERT…RETURNING 單句（{table} 佔位由呼叫端替換；D1 實測 RETURNING 列經 results 回帶）。 */
+export declare const SQL_RATE_BUMP = "INSERT INTO {table} (ip, window_start, count) VALUES (?1, ?2, 1)\n  ON CONFLICT(ip) DO UPDATE SET\n    count        = CASE WHEN window_start <= ?3 THEN 1 ELSE count + 1 END,\n    window_start = CASE WHEN window_start <= ?3 THEN ?2 ELSE window_start END\n  RETURNING count AS n";
+/** @internal（0.1.6 公開面走 index.ts checkRate）。放行判準單一真相：窗口內超額後照實回實際 count，呼叫端以 count <= max 拒絕。 */
+export declare function isRateAllowed(count: number, max: number): boolean;
+export declare function checkRate(env: Env, w: RateWindow, ip: string): Promise<boolean>;

package/dist/server/ratelimit.js

@@ -0,0 +1,63 @@
+/**
+ * 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 拒絕——計數不封頂，超額仍逐發累計）。
+ *
+ * 呼叫端須自建表（無 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。
+ */
+/**
+ * 表名只允許 \w 字元（字母／數字／底線）：表名直接拼進 SQL 字串，禁注入符號。
+ * 違例 throw——配置錯誤在開發期炸開，不靜默。
+ */
+function assertSafeTable(table) {
+    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, max) {
+    return count <= max;
+}
+async function bumpRate(env, w, ip) {
+    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];
+        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;
+    }
+}
+export function checkRate(env, w, ip) {
+    return bumpRate(env, w, ip);
+}