@usethink/cf-core 0.3.0

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @usethink/cf-core — Cloudflare Workers 共享内核
+ *
+ * 统一导出所有模块，支持两种导入方式：
+ *
+ * 1. 从根导入（适合小项目）：
+ *    import { ok, fail, sha256, verifyTurnstile } from "@usethink/cf-core";
+ *
+ * 2. 按子路径导入（推荐，tree-shakeable）：
+ *    import { ok, fail } from "@usethink/cf-core/http";
+ *    import { sha256 } from "@usethink/cf-core/security";
+ */
+
+// ── HTTP 工具 ──
+export { ok, fail, failRateLimit, getOrigin, safeJsonBody, maskContact, normalizeCode, csvEscape, toCsv } from "./http";
+
+// ── 安全工具 ──
+export {
+  sha256,
+  constantTimeEqual,
+  getIpHash,
+  getClientIp,
+  getBearerToken,
+  verifyTurnstile,
+  buildSecurityHeaders,
+  type SecurityHeadersOptions,
+} from "./security";
+
+// ── 缓存 ──
+export { createCache, cache } from "./cache";
+
+// ── 限流 ──
+export { MemoryRateLimiter, KvRateLimiter, DbRateLimiter, type RateLimiter } from "./rate-limit";
+
+// ── 幂等性 ──
+export { checkIdempotency, saveIdempotentResponse, getIdempotentResponse } from "./idempotency";
+
+// ── 审计日志 ──
+export { writeAdminAudit, type AuditInput } from "./audit";
+
+// ── 系统配置 ──
+export { SystemConfig, type SystemConfigOptions } from "./config";
+
+// ── 错误处理 ──
+export { classifyError, retryWithBackoff, ErrorType, type RetryOptions } from "./error";
+
+// ── 结构化日志 ──
+export { logger, type LogLevel, type LogEntry } from "./logger";
+
+// ── 加解密 ──
+export { encrypt, decrypt, isEncryptionAvailable, generateUUID } from "./crypto";
+
+// ── 数据库 ──
+export { initDatabase, initDatabaseWithHealthCheck, getOrCreateClient, createDrizzle, type DrizzleInstance } from "./db/connection";
+
+// ── 公共 Schema ──
+export {
+  systemConfig,
+  adminAuditLogs,
+  rateLimitWindows,
+  idempotencyKeys,
+  apiKeys,
+} from "./db/schema";
+
+// ── 认证 ──
+export { signJwt, verifyJwt, extractJwt, type JwtPayload } from "./auth/jwt";
+export { hashPassword, verifyPassword } from "./auth/password";
+
+// ── 中间件 ──
+export { createAdminAuth, type AdminAuthOptions } from "./middleware/admin-auth";
+export { createApiKeyAuth, extractApiKey, type ApiKeyAuthOptions, type ApiKeyContext } from "./middleware/api-key-auth";
+
+// ── Bootstrap ──
+export { bootstrap, type BootstrapOptions } from "./bootstrap";
+
+// ── 类型 ──
+export type {
+  CoreBindings,
+  CoreVariables,
+  CoreEnv,
+  OkResponse,
+  FailResponse,
+  TurnstileResult,
+  RateLimitResult,
+} from "./types";

package/src/logger.ts

@@ -0,0 +1,63 @@
+/**
+ * 结构化日志模块
+ *
+ * 提供 JSON 格式的结构化日志输出，便于 Workers 日志分析和 Cloudflare 日志查询。
+ *
+ * 来源：vcode src/lib/logger.ts
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: string;
+  [key: string]: unknown;
+}
+
+function createEntry(level: LogLevel, message: string, meta?: Record<string, unknown>): LogEntry {
+  return { level, message, timestamp: new Date().toISOString(), ...meta };
+}
+
+export const logger = {
+  debug(message: string, meta?: Record<string, unknown>) {
+    console.log(JSON.stringify(createEntry("debug", message, meta)));
+  },
+
+  info(message: string, meta?: Record<string, unknown>) {
+    console.log(JSON.stringify(createEntry("info", message, meta)));
+  },
+
+  warn(message: string, meta?: Record<string, unknown>) {
+    console.warn(JSON.stringify(createEntry("warn", message, meta)));
+  },
+
+  error(message: string, meta?: Record<string, unknown>) {
+    console.error(JSON.stringify(createEntry("error", message, meta)));
+  },
+
+  /** 业务日志 — 资源操作（凭证/订单/卡密等） */
+  resourceAction(action: string, resourceId: string, meta?: Record<string, unknown>) {
+    this.info(`resource.${action}`, { resourceId, ...meta });
+  },
+
+  /** 业务日志 — 渠道/驱动操作 */
+  channelAction(action: string, channel: string, meta?: Record<string, unknown>) {
+    this.info(`channel.${action}`, { channel, ...meta });
+  },
+
+  /** 业务日志 — 定时任务 */
+  cronJob(jobName: string, meta?: Record<string, unknown>) {
+    this.info(`cron.${jobName}`, meta);
+  },
+
+  /** 安全日志 — 认证/授权事件 */
+  security(action: string, meta?: Record<string, unknown>) {
+    this.warn(`security.${action}`, meta);
+  },
+
+  /** 审计日志 — 管理操作 */
+  audit(action: string, adminId: string, targetId?: string, meta?: Record<string, unknown>) {
+    this.info(`audit.${action}`, { adminId, targetId, ...meta });
+  },
+};

package/src/middleware/admin-auth.ts

@@ -0,0 +1,71 @@
+/**
+ * 管理员认证中间件
+ *
+ * 支持两种认证方式：
+ * 1. Bearer Token（eshop/vcode 方式）：Authorization: Bearer <token>
+ * 2. 自定义 Header（xtools 方式）：X-Admin-Token: <token>
+ *
+ * 安全措施：
+ * - 时序安全比较（timingSafeEqual）防时序攻击
+ * - 默认 Token 仅限本地地址使用
+ * - 未配置 ADMIN_TOKEN 时返回 503
+ *
+ * 来源：eshop requireAdmin + xtools adminAuthMiddleware 合并
+ */
+
+import type { Context, Next } from "hono";
+import { fail } from "../http";
+import { constantTimeEqual, getBearerToken } from "../security";
+
+export interface AdminAuthOptions {
+  /**
+   * Token 提取方式：
+   * - "bearer" — 从 Authorization: Bearer 提取（eshop/vcode 默认）
+   * - "header" — 从 X-Admin-Token 提取（xtools 默认）
+   * - "both" — 两种方式都尝试（兼容模式）
+   */
+  mode?: "bearer" | "header" | "both";
+}
+
+/**
+ * 创建管理员认证中间件
+ *
+ * @example
+ * // eshop/vcode 风格
+ * app.route("/admin", new Hono().use("*", createAdminAuth()).route("/", adminRoutes));
+ *
+ * // xtools 风格
+ * app.use("/api/admin/*", createAdminAuth({ mode: "header" }));
+ */
+export function createAdminAuth(options: AdminAuthOptions = {}) {
+  const { mode = "both" } = options;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return async (c: Context<any>, next: Next) => {
+    const expected = c.env.ADMIN_TOKEN;
+    if (!expected) return fail(c, "管理员令牌未配置", 503);
+
+    // 安全检查：默认 Token 仅限本地
+    const hostname = new URL(c.req.url).hostname;
+    if (
+      expected === "dev-only-change-me" &&
+      !["127.0.0.1", "localhost", "::1"].includes(hostname)
+    ) {
+      return fail(c, "生产环境必须配置 ADMIN_TOKEN", 503);
+    }
+
+    // 提取 Token
+    let actual = "";
+    if (mode === "bearer" || mode === "both") {
+      actual = getBearerToken(c);
+    }
+    if (!actual && (mode === "header" || mode === "both")) {
+      actual = c.req.header("X-Admin-Token") || "";
+    }
+
+    if (!actual) return fail(c, "未授权", 401);
+    if (!constantTimeEqual(expected, actual)) return fail(c, "未授权", 401);
+
+    await next();
+  };
+}

package/src/middleware/api-key-auth.ts

@@ -0,0 +1,164 @@
+/**
+ * API Key 认证中间件
+ *
+ * 功能：
+ * - SHA-256 哈希存储（不存明文）
+ * - 月度配额 + 原子递增（消除 TOCTOU 竞态）
+ * - 支持 Bearer 和自定义 Header 提取
+ * - 分级管理（free/basic/pro/enterprise）
+ *
+ * 来源：xtools + vcode api-auth.ts 合并
+ */
+
+import type { Context, Next } from "hono";
+import { fail } from "../http";
+import { sha256 } from "../security";
+import { apiKeys } from "../db/schema";
+import { eq, and, sql } from "drizzle-orm";
+
+export interface ApiKeyContext {
+  id: string;
+  name: string;
+  tier: string;
+  userId: string;
+  monthlyQuota: number;
+  monthlyUsage: number;
+}
+
+interface ApiKeyDbLike {
+  select: (...args: unknown[]) => {
+    from: (table: typeof apiKeys) => {
+      where: (cond: unknown) => {
+        limit: (n: number) => Promise<Array<{
+          id: string;
+          name: string;
+          keyHash: string;
+          userId: string;
+          tier: string;
+          enabled: number;
+          monthlyQuota: number;
+          monthlyUsage: number;
+          monthlyResetAt: string | null;
+          expiresAt: string | null;
+        }>>;
+      };
+    };
+  };
+  update: (table: typeof apiKeys) => {
+    set: (data: Record<string, unknown>) => {
+      where: (cond: unknown) => {
+        returning: () => Promise<unknown[]>;
+      };
+    };
+  };
+}
+
+export interface ApiKeyAuthOptions {
+  /** Key 前缀（如 "xtools_"、"vcode_"），默认不限制 */
+  prefix?: string;
+  /** 是否必须认证，默认 true */
+  required?: boolean;
+  /** 自定义变量名（注入到 Hono Variables），默认 "apiKeyContext" */
+  variableName?: string;
+}
+
+/**
+ * 从请求中提取 API Key
+ */
+export function extractApiKey(c: Context, prefix?: string): string | null {
+  // 1. Authorization: Bearer <key>
+  const auth = c.req.header("Authorization");
+  if (auth) {
+    const parts = auth.split(" ");
+    if (parts.length === 2) {
+      const [scheme, credentials] = parts;
+      if (
+        (scheme.toLowerCase() === "bearer" || scheme.toLowerCase() === "token") &&
+        (!prefix || credentials.startsWith(prefix))
+      ) {
+        return credentials;
+      }
+    }
+  }
+
+  // 2. X-API-Key header
+  const apiKey = c.req.header("X-API-Key");
+  if (apiKey && (!prefix || apiKey.startsWith(prefix))) {
+    return apiKey;
+  }
+
+  return null;
+}
+
+/**
+ * 创建 API Key 认证中间件
+ */
+export function createApiKeyAuth(options: ApiKeyAuthOptions = {}) {
+  const { prefix, required = true, variableName = "apiKeyContext" } = options;
+
+  return async (
+    c: Context<{ Bindings: Record<string, unknown>; Variables: Record<string, unknown> }>,
+    next: Next,
+  ) => {
+    const key = extractApiKey(c, prefix);
+
+    if (!key) {
+      if (required) return fail(c, "缺少 API Key", 401);
+      await next();
+      return;
+    }
+
+    const db = c.get("db") as ApiKeyDbLike | undefined;
+    if (!db) return fail(c, "数据库不可用", 503);
+
+    const keyHash = await sha256(key);
+    const rows = await db
+      .select()
+      .from(apiKeys)
+      .where(eq(apiKeys.keyHash, keyHash))
+      .limit(1);
+
+    if (rows.length === 0) return fail(c, "API Key 无效", 401);
+
+    const record = rows[0];
+    if (!record.enabled) return fail(c, "API Key 已禁用", 401);
+    if (record.expiresAt && new Date(record.expiresAt) < new Date()) {
+      return fail(c, "API Key 已过期", 401);
+    }
+
+    // 原子配额检查 + 递增
+    if (record.monthlyQuota > 0) {
+      const updated = await db
+        .update(apiKeys)
+        .set({
+          monthlyUsage: sql`monthly_usage + 1`,
+          lastUsedAt: new Date().toISOString(),
+        })
+        .where(and(eq(apiKeys.id, record.id), sql`monthly_usage < monthly_quota`))
+        .returning();
+
+      if (updated.length === 0) return fail(c, "已超过月度配额", 429);
+    } else {
+      await db
+        .update(apiKeys)
+        .set({
+          monthlyUsage: sql`monthly_usage + 1`,
+          lastUsedAt: new Date().toISOString(),
+        })
+        .where(eq(apiKeys.id, record.id));
+    }
+
+    const context: ApiKeyContext = {
+      id: record.id,
+      name: record.name,
+      tier: record.tier || "free",
+      userId: record.userId,
+      monthlyQuota: record.monthlyQuota,
+      monthlyUsage: record.monthlyUsage,
+    };
+
+    c.set(variableName, context);
+    c.set("userId", record.userId || record.id);
+    await next();
+  };
+}

package/src/middleware/index.ts

@@ -0,0 +1,2 @@
+export { createAdminAuth, type AdminAuthOptions } from "./admin-auth";
+export { createApiKeyAuth, extractApiKey, type ApiKeyAuthOptions, type ApiKeyContext } from "./api-key-auth";

package/src/rate-limit.ts

@@ -0,0 +1,167 @@
+/**
+ * 统一限流模块 — 支持 DB / KV / 内存 三种存储后端
+ *
+ * 三项目的限流实现各有特点：
+ * - eshop: DB 版（原子 upsert，最可靠，适合无 KV 的项目）
+ * - xtools: KV 版（滑动窗口，跨实例共享）
+ * - vcode: 内存版（最轻量，但重启丢失）
+ *
+ * 本模块统一接口，项目按自己的基础设施选择后端。
+ */
+
+import { sql } from "drizzle-orm";
+import type { RateLimitResult } from "./types";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 统一接口
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface RateLimiter {
+  check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 内存版（最轻量 — 适合 vcode 类项目）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * 内存固定窗口限流器
+ *
+ * Workers 实例级别，重启后重置。
+ * 适合请求量不大、对精确性要求不高的场景。
+ */
+export class MemoryRateLimiter implements RateLimiter {
+  private store = new Map<string, { count: number; resetAt: number }>();
+
+  async check(key: string, limit: number, windowMs: number): Promise<RateLimitResult> {
+    const now = Date.now();
+    const record = this.store.get(key);
+
+    if (!record || now > record.resetAt) {
+      this.store.set(key, { count: 1, resetAt: now + windowMs });
+      return { ok: true, remaining: limit - 1 };
+    }
+
+    if (record.count >= limit) {
+      const resetMs = Math.max(0, record.resetAt - now);
+      return { ok: false, message: "请求过于频繁，请稍后再试", status: 429, resetMs };
+    }
+
+    record.count++;
+    return { ok: true, remaining: limit - record.count };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// KV 版（跨实例共享 — 适合 xtools 类项目）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * KV 滑动窗口限流器
+ *
+ * 使用 Cloudflare KV 存储，跨 Workers 实例共享状态。
+ * 滑动窗口算法，避免固定窗口边界突发。
+ *
+ * 来源：xtools src/lib/rate-limiter.ts
+ */
+export class KvRateLimiter implements RateLimiter {
+  private kv: KVNamespace;
+  private prefix: string;
+
+  constructor(kv: KVNamespace, prefix = "rate") {
+    this.kv = kv;
+    this.prefix = prefix;
+  }
+
+  async check(key: string, limit: number, windowMs: number): Promise<RateLimitResult> {
+    const now = Date.now();
+    const windowStart = now - windowMs;
+    const kvKey = `${this.prefix}:${key}`;
+
+    try {
+      const data = await this.kv.get(kvKey, "json");
+      const timestamps: number[] = Array.isArray(data) ? data : [];
+      const valid = timestamps.filter((ts) => ts > windowStart);
+
+      if (valid.length >= limit) {
+        const oldest = Math.min(...valid);
+        const resetMs = Math.max(0, oldest + windowMs - now);
+        return { ok: false, message: "请求过于频繁，请稍后再试", status: 429, remaining: 0, resetMs };
+      }
+
+      valid.push(now);
+      const ttlSeconds = Math.ceil(windowMs / 1000) + 10;
+      await this.kv.put(kvKey, JSON.stringify(valid), { expirationTtl: ttlSeconds });
+
+      const remaining = Math.max(0, limit - valid.length);
+      return { ok: true, remaining };
+    } catch (err) {
+      console.warn("[KvRateLimiter] KV error, failing open:", err instanceof Error ? err.message : String(err));
+      return { ok: true, remaining: limit };
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// DB 版（最可靠 — 适合 eshop 类项目）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * 数据库固定窗口限流器
+ *
+ * 使用 rate_limit_windows 表，通过原子 upsert（INSERT ON CONFLICT UPDATE）实现。
+ * UPDATE 自带 WHERE request_count < :limit 条件，确保计数器永远不会超过阈值，
+ * 从根本上消除高并发场景下的竞态条件。
+ *
+ * 来源：eshop src/lib/rate-limit.ts（竞态修复版）
+ */
+export class DbRateLimiter implements RateLimiter {
+  private db: {
+    execute: (query: unknown) => Promise<{ rows?: Array<{ request_count: number }> }>;
+  };
+  private tableName: string;
+
+  constructor(db: DbRateLimiter["db"]) {
+    this.db = db;
+    this.tableName = "rate_limit_windows";
+  }
+
+  async check(key: string, limit: number, windowMs: number): Promise<RateLimitResult> {
+    const now = Math.floor(Date.now() / 1000);
+    const windowSeconds = Math.floor(windowMs / 1000);
+    const windowStart = Math.floor(now / windowSeconds) * windowSeconds;
+
+    try {
+      // 使用 raw SQL + WHERE 条件保证计数器不会超过 limit：
+      // - 首次插入: request_count = 1
+      // - 后续更新: request_count += 1，但 WHERE request_count < :limit 阻止超额
+      const result = await this.db.execute(
+        sql`INSERT INTO ${sql.identifier(this.tableName)} (action, ip_hash, window_start, request_count)
+            VALUES (${key}, '', ${windowStart}, 1)
+            ON CONFLICT(action, ip_hash, window_start) DO UPDATE SET
+              request_count = request_count + 1
+            WHERE rate_limit_windows.request_count < ${limit}
+            RETURNING request_count`,
+      );
+
+      const currentCount = result.rows?.[0]?.request_count ?? 0;
+
+      // 如果 WHERE 条件不满足（count >= limit），UPDATE 被跳过，返回旧值
+      if (currentCount > limit) {
+        const resetInSeconds = windowStart + windowSeconds - now;
+        return {
+          ok: false,
+          message: "请求过于频繁，请稍后再试",
+          status: 429,
+          remaining: 0,
+          resetMs: Math.max(0, resetInSeconds * 1000),
+        };
+      }
+
+      return { ok: true, remaining: Math.max(0, limit - currentCount) };
+    } catch {
+      // 限流失败时 fail-open 以保持服务可用
+      return { ok: true, remaining: limit };
+    }
+  }
+}