@tacet-ink/journal-core 0.1.4 → 0.1.6

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,7 +128,7 @@ 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>;

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 {

package/src/server/ratelimit.ts

@@ -1,17 +1,26 @@
 /**
- * ratelimit.ts — per-IP 滑動視窗限流（D1 計數，跨 isolate 有效；併發安全版）。
+ * ratelimit.ts — per-IP fixed-window 限流（D1 計數，跨 isolate 有效；單句 UPSERT…RETURNING）。
  *
- * 教訓來源（生產實證）：
- * - in-memory Map 在多 isolate/多 colo 下無效（實測 24 發分散多機房全 200）
- * - 原單句 UPDATE 計數在併發下輕微超額 → 改單條件寫入鏈：INSERT 競態輸家先試
- *   「作用中未超額」計數 UPDATE（輸家直接掉到 reset 會把贏家的作用中視窗誤判成拒絕）
- * - fail-open 裁定：限流儲存故障時放行（保護面不可反噬主功能），只擋明確超額
+ * 設計（2026-10-04 t_b91ed07f，外部審查 MAJOR：原 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 照實回報（r2 MINOR-3：異形不反向成 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';
+import type { Env } from './env.ts';
 
 export interface RateWindow {
   table: string;
@@ -19,35 +28,42 @@ export interface RateWindow {
   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 {
-    // 快路徑：未超額的既有列直接 +1（單句原子，競態安全）
-    const upd = await env.DB.prepare(
-      `UPDATE ${w.table} SET count = count + 1
-       WHERE ip = ? AND window_start > ? AND count < ?`
-    ).bind(ip, now - w.windowMs, w.max).run();
-    if ((upd.meta?.changes ?? 0) > 0) return true;
-    // 無列或窗口過期：INSERT；主鍵競態（同 IP 併發首發）→ 輸家先試「作用中未超額」
-    // 計數 UPDATE（外部審查 MAJOR 修復：輸家直接掉到 reset 會把贏家的作用中視窗誤判成
-    // 拒絕 → 空視窗併發首發 undercount 到只剩 1 次）。再 fallback 到重置式 UPDATE。
-    const ins = await env.DB.prepare(
-      `INSERT INTO ${w.table} (ip, window_start, count) VALUES (?, ?, 1)
-       ON CONFLICT(ip) DO NOTHING`
-    ).bind(ip, now).run();
-    if ((ins.meta?.changes ?? 0) > 0) return true;
-    const loser = await env.DB.prepare(
-      `UPDATE ${w.table} SET count = count + 1
-       WHERE ip = ? AND window_start > ? AND count < ?`
-    ).bind(ip, now - w.windowMs, w.max).run();
-    if ((loser.meta?.changes ?? 0) > 0) return true;
-    // 列已存在且未超額：窗口過期 → 重置；窗口內但剛才 count>=max 沒吃到 → 拒絕
-    const reset = await env.DB.prepare(
-      `UPDATE ${w.table} SET window_start = ?, count = 1
-       WHERE ip = ? AND window_start <= ?`
-    ).bind(now, ip, now - w.windowMs).run();
-    if ((reset.meta?.changes ?? 0) > 0) return true;
-    return false;
+    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);