npm - @usethink/cf-core - Versions diffs - 0.3.0 - Mend

@usethink/cf-core 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (169) hide show

package/README.md +88 -0
package/dist/features/anti-abuse/index.d.ts +62 -0
package/dist/features/anti-abuse/index.d.ts.map +1 -0
package/dist/features/anti-abuse/index.js +139 -0
package/dist/features/anti-abuse/index.js.map +1 -0
package/dist/features/email/index.d.ts +68 -0
package/dist/features/email/index.d.ts.map +1 -0
package/dist/features/email/index.js +120 -0
package/dist/features/email/index.js.map +1 -0
package/dist/features/payment/fetch-utils.d.ts +17 -0
package/dist/features/payment/fetch-utils.d.ts.map +1 -0
package/dist/features/payment/fetch-utils.js +56 -0
package/dist/features/payment/fetch-utils.js.map +1 -0
package/dist/features/payment/index.d.ts +20 -0
package/dist/features/payment/index.d.ts.map +1 -0
package/dist/features/payment/index.js +21 -0
package/dist/features/payment/index.js.map +1 -0
package/dist/features/payment/providers/alipay.d.ts +30 -0
package/dist/features/payment/providers/alipay.d.ts.map +1 -0
package/dist/features/payment/providers/alipay.js +149 -0
package/dist/features/payment/providers/alipay.js.map +1 -0
package/dist/features/payment/providers/stripe.d.ts +34 -0
package/dist/features/payment/providers/stripe.d.ts.map +1 -0
package/dist/features/payment/providers/stripe.js +168 -0
package/dist/features/payment/providers/stripe.js.map +1 -0
package/dist/features/payment/providers/trc20.d.ts +24 -0
package/dist/features/payment/providers/trc20.d.ts.map +1 -0
package/dist/features/payment/providers/trc20.js +96 -0
package/dist/features/payment/providers/trc20.js.map +1 -0
package/dist/features/payment/registry.d.ts +43 -0
package/dist/features/payment/registry.d.ts.map +1 -0
package/dist/features/payment/registry.js +65 -0
package/dist/features/payment/registry.js.map +1 -0
package/dist/features/payment/types.d.ts +72 -0
package/dist/features/payment/types.d.ts.map +1 -0
package/dist/features/payment/types.js +8 -0
package/dist/features/payment/types.js.map +1 -0
package/dist/features/thompson-router/index.d.ts +101 -0
package/dist/features/thompson-router/index.d.ts.map +1 -0
package/dist/features/thompson-router/index.js +186 -0
package/dist/features/thompson-router/index.js.map +1 -0
package/dist/features/webhook/index.d.ts +76 -0
package/dist/features/webhook/index.d.ts.map +1 -0
package/dist/features/webhook/index.js +127 -0
package/dist/features/webhook/index.js.map +1 -0
package/dist/src/audit.d.ts +45 -0
package/dist/src/audit.d.ts.map +1 -0
package/dist/src/audit.js +40 -0
package/dist/src/audit.js.map +1 -0
package/dist/src/auth/jwt.d.ts +33 -0
package/dist/src/auth/jwt.d.ts.map +1 -0
package/dist/src/auth/jwt.js +87 -0
package/dist/src/auth/jwt.js.map +1 -0
package/dist/src/auth/password.d.ts +26 -0
package/dist/src/auth/password.d.ts.map +1 -0
package/dist/src/auth/password.js +52 -0
package/dist/src/auth/password.js.map +1 -0
package/dist/src/bootstrap.d.ts +74 -0
package/dist/src/bootstrap.d.ts.map +1 -0
package/dist/src/bootstrap.js +231 -0
package/dist/src/bootstrap.js.map +1 -0
package/dist/src/cache.d.ts +52 -0
package/dist/src/cache.d.ts.map +1 -0
package/dist/src/cache.js +76 -0
package/dist/src/cache.js.map +1 -0
package/dist/src/config.d.ts +83 -0
package/dist/src/config.d.ts.map +1 -0
package/dist/src/config.js +96 -0
package/dist/src/config.js.map +1 -0
package/dist/src/crypto.d.ts +33 -0
package/dist/src/crypto.d.ts.map +1 -0
package/dist/src/crypto.js +87 -0
package/dist/src/crypto.js.map +1 -0
package/dist/src/db/connection.d.ts +53 -0
package/dist/src/db/connection.d.ts.map +1 -0
package/dist/src/db/connection.js +104 -0
package/dist/src/db/connection.js.map +1 -0
package/dist/src/db/index.d.ts +6 -0
package/dist/src/db/index.d.ts.map +1 -0
package/dist/src/db/index.js +6 -0
package/dist/src/db/index.js.map +1 -0
package/dist/src/db/schema.d.ts +649 -0
package/dist/src/db/schema.d.ts.map +1 -0
package/dist/src/db/schema.js +76 -0
package/dist/src/db/schema.js.map +1 -0
package/dist/src/error.d.ts +47 -0
package/dist/src/error.d.ts.map +1 -0
package/dist/src/error.js +94 -0
package/dist/src/error.js.map +1 -0
package/dist/src/http.d.ts +83 -0
package/dist/src/http.d.ts.map +1 -0
package/dist/src/http.js +116 -0
package/dist/src/http.js.map +1 -0
package/dist/src/idempotency.d.ts +78 -0
package/dist/src/idempotency.d.ts.map +1 -0
package/dist/src/idempotency.js +84 -0
package/dist/src/idempotency.js.map +1 -0
package/dist/src/index.d.ts +31 -0
package/dist/src/index.d.ts.map +1 -0
package/dist/src/index.js +45 -0
package/dist/src/index.js.map +1 -0
package/dist/src/logger.d.ts +31 -0
package/dist/src/logger.d.ts.map +1 -0
package/dist/src/logger.js +45 -0
package/dist/src/logger.js.map +1 -0
package/dist/src/middleware/admin-auth.d.ts +38 -0
package/dist/src/middleware/admin-auth.d.ts.map +1 -0
package/dist/src/middleware/admin-auth.js +55 -0
package/dist/src/middleware/admin-auth.js.map +1 -0
package/dist/src/middleware/api-key-auth.d.ts +42 -0
package/dist/src/middleware/api-key-auth.d.ts.map +1 -0
package/dist/src/middleware/api-key-auth.js +104 -0
package/dist/src/middleware/api-key-auth.js.map +1 -0
package/dist/src/middleware/index.d.ts +3 -0
package/dist/src/middleware/index.d.ts.map +1 -0
package/dist/src/middleware/index.js +3 -0
package/dist/src/middleware/index.js.map +1 -0
package/dist/src/rate-limit.d.ts +54 -0
package/dist/src/rate-limit.d.ts.map +1 -0
package/dist/src/rate-limit.js +134 -0
package/dist/src/rate-limit.js.map +1 -0
package/dist/src/security.d.ts +78 -0
package/dist/src/security.d.ts.map +1 -0
package/dist/src/security.js +175 -0
package/dist/src/security.js.map +1 -0
package/dist/src/types.d.ts +64 -0
package/dist/src/types.d.ts.map +1 -0
package/dist/src/types.js +8 -0
package/dist/src/types.js.map +1 -0
package/features/anti-abuse/index.ts +180 -0
package/features/anti-abuse/tests/index.test.ts +50 -0
package/features/email/index.ts +172 -0
package/features/email/tests/index.test.ts +44 -0
package/features/payment/fetch-utils.ts +65 -0
package/features/payment/index.ts +39 -0
package/features/payment/providers/alipay.ts +171 -0
package/features/payment/providers/stripe.ts +192 -0
package/features/payment/providers/trc20.ts +115 -0
package/features/payment/registry.ts +87 -0
package/features/payment/tests/index.test.ts +506 -0
package/features/payment/types.ts +93 -0
package/features/telegram-miniapp/index.ts +109 -0
package/features/telegram-miniapp/tests/index.test.ts +11 -0
package/features/thompson-router/index.ts +243 -0
package/features/thompson-router/tests/index.test.ts +93 -0
package/features/webhook/index.ts +183 -0
package/features/webhook/tests/index.test.ts +21 -0
package/package.json +202 -0
package/src/audit.ts +70 -0
package/src/auth/jwt.ts +114 -0
package/src/auth/password.ts +75 -0
package/src/bootstrap.ts +322 -0
package/src/cache.ts +78 -0
package/src/config.ts +134 -0
package/src/crypto.ts +106 -0
package/src/db/connection.ts +127 -0
package/src/db/index.ts +6 -0
package/src/db/schema.ts +90 -0
package/src/error.ts +125 -0
package/src/http.ts +150 -0
package/src/idempotency.ts +127 -0
package/src/index.ts +85 -0
package/src/logger.ts +63 -0
package/src/middleware/admin-auth.ts +71 -0
package/src/middleware/api-key-auth.ts +164 -0
package/src/middleware/index.ts +2 -0
package/src/rate-limit.ts +167 -0
package/src/security.ts +219 -0
package/src/types.ts +70 -0

package/src/bootstrap.ts ADDED Viewed

@@ -0,0 +1,322 @@
+/**
+ * Worker 入口工厂
+ *
+ * 将三项目 index.ts 中高度重复的 Worker 启动逻辑抽象为统一工厂函数：
+ * - 数据库初始化中间件
+ * - 请求体大小限制
+ * - 安全响应头注入
+ * - API 路由 / 静态资源分流
+ * - 全局错误处理
+ *
+ * 来源：eshop/xtools/vcode 三项目 index.ts 入口合并
+ */
+import { Hono } from "hono";
+import { initDatabaseWithHealthCheck, type DrizzleInstance } from "./db/connection";
+import { fail } from "./http";
+import { buildSecurityHeaders, type SecurityHeadersOptions } from "./security";
+export interface BootstrapOptions<TSchema extends Record<string, unknown> = Record<string, never>> {
+  /** Drizzle schema（传入后支持关系查询） */
+  schema?: TSchema;
+  /** API 路由前缀，默认 "/api" */
+  apiPrefix?: string;
+  /** 请求体大小限制（字节），默认 100KB */
+  maxBodySize?: number;
+  /**
+   * 请求级超时（毫秒），默认 25000（25 秒）。
+   * Cloudflare Workers 硬限制 30 秒，留 5 秒余量给 CF 运行时。
+   * 超时后请求会被中止并返回 504 Gateway Timeout。
+   */
+  requestTimeoutMs?: number;
+  /** 安全响应头配置 */
+  securityHeaders?: SecurityHeadersOptions;
+  /**
+   * 错误告警回调 — 生产环境错误通知。
+   * 当请求处理过程中发生未捕获错误时调用，可用于发送到外部告警系统
+   * （如 Slack webhook、邮件、PagerDuty 等）。
+   *
+   * @example
+   * ```ts
+   * onErrorAlert: async (error, context) => {
+   *   await fetch("https://hooks.slack.com/...", {
+   *     method: "POST",
+   *     body: JSON.stringify({ text: `[ERROR] ${error.message}` }),
+   *   });
+   * }
+   * ```
+   */
+  onErrorAlert?: (error: Error, context: { path: string; method: string; ip?: string }) => void | Promise<void>;
+  /** 注册 API 路由的回调 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registerRoutes: (api: Hono<any>) => void;
+  /**
+   * 静态资源路由表 — 页面路径到 HTML 文件的映射
+   * @example { "/admin": "/admin.html", "/shop": "/index.html" }
+   */
+  pageRoutes?: Record<string, string>;
+  /**
+   * SPA 路由 — 这些路径都返回同一个 HTML 文件
+   * @example { fallback: "/_app/index.html", paths: ["/shop", "/order"] }
+   */
+  spaRoutes?: {
+    fallback: string;
+    paths: string[];
+  };
+  /**
+   * 长缓存路径前缀（如 /_app/assets/）
+   * 匹配的路径会设置 Cache-Control: immutable, max-age=31536000
+   */
+  immutablePrefixes?: string[];
+}
+/**
+ * 创建 Cloudflare Workers 应用
+ *
+ * 返回标准的 Workers fetch handler 导出对象。
+ *
+ * @example
+ * ```ts
+ * import * as schema from "./db/schema";
+ * import { bootstrap } from "@usethink/cf-core/bootstrap";
+ *
+ * export default bootstrap({
+ *   schema,
+ *   registerRoutes: (api) => {
+ *     api.route("/products", productRoutes);
+ *     api.route("/orders", orderRoutes);
+ *   },
+ *   pageRoutes: { "/admin": "/admin.html" },
+ *   spaRoutes: { fallback: "/_app/index.html", paths: ["/shop", "/order"] },
+ *   immutablePrefixes: ["/_app/assets/"],
+ * });
+ * ```
+ */
+/** 生成友好的 HTML 错误页面（内联 CSS，无外部依赖） */
+function errorPageHtml(status: number, message: string): string {
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${status} - ${message}</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#0f0f0f;color:#e0e0e0;display:flex;align-items:center;justify-content:center;min-height:100vh;padding:20px}
+.container{text-align:center;max-width:480px}
+.code{font-size:6rem;font-weight:800;background:linear-gradient(135deg,#6c63ff,#a78bfa);-webkit-background-clip:text;-webkit-text-fill-color:transparent;line-height:1}
+.msg{font-size:1.25rem;color:#888;margin:1rem 0 2rem}
+a{color:#6c63ff;text-decoration:none;font-weight:500}
+a:hover{text-decoration:underline}
+</style>
+</head>
+<body>
+<div class="container">
+<p class="code">${status}</p>
+<p class="msg">${message}</p>
+<a href="/">← 返回首页</a>
+</div>
+</body>
+</html>`;
+}
+export function bootstrap<TSchema extends Record<string, unknown>>(
+  options: BootstrapOptions<TSchema>,
+) {
+  const {
+    schema,
+    apiPrefix = "/api",
+    maxBodySize = 1024 * 100,
+    requestTimeoutMs = 25_000,
+    securityHeaders: secOpts = {},
+    onErrorAlert,
+    registerRoutes,
+    pageRoutes = {},
+    spaRoutes,
+    immutablePrefixes = [],
+  } = options;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const api = new Hono<any>();
+  // ── 请求级超时中间件（防止慢请求耗尽 Workers CPU） ──
+  api.use("*", async (c, next) => {
+    // /health 不受超时限制（用于监控探活）
+    if (c.req.path === "/health") {
+      await next();
+      return;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), requestTimeoutMs);
+    try {
+      // 将 signal 传递给下游（路由可选择性使用）
+      c.set("abortSignal", controller.signal);
+      await next();
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        console.error(`[bootstrap:timeout] 请求超时 ${requestTimeoutMs}ms: ${c.req.method} ${c.req.path}`);
+        return fail(c, "请求处理超时", 504);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  });
+  // ── DB 初始化中间件（带连接验证 + 重试） ──
+  api.use("*", async (c, next) => {
+    const isHealth = c.req.path === "/health";
+    try {
+      const db = await initDatabaseWithHealthCheck(c.env.TURSO_URL, c.env.TURSO_TOKEN, schema);
+      c.set("db", db);
+      if ("executionCtx" in c) {
+        c.set("executionCtx", c.env.executionCtx);
+      }
+      await next();
+    } catch (err) {
+      console.error("[bootstrap:db-init]", err);
+      if (isHealth) {
+        c.set("db", undefined);
+        await next();
+        return;
+      }
+      return fail(c, "服务暂时不可用", 503);
+    }
+  });
+  // ── 请求体大小限制 ──
+  api.use("*", async (c, next) => {
+    const len = parseInt(c.req.header("content-length") || "0");
+    if (len > maxBodySize) return fail(c, `请求体过大（最大 ${Math.floor(maxBodySize / 1024)}KB）`, 413);
+    await next();
+  });
+  // ── 注册业务路由 ──
+  registerRoutes(api);
+  // ── 404 + 全局错误（浏览器返回 HTML，API 返回 JSON） ──
+  api.notFound((c) => {
+    const accept = c.req.header("accept") || "";
+    if (accept.includes("text/html")) {
+      return c.html(errorPageHtml(404, "页面未找到"), 404);
+    }
+    return fail(c, "API not found", 404);
+  });
+  api.onError((error, c) => {
+    console.error("[bootstrap:onError]", error?.constructor?.name, error?.message, error?.stack);
+    // 触发告警回调（如果配置了）
+    if (onErrorAlert) {
+      const ip = c.req.header("cf-connecting-ip") || c.req.header("x-forwarded-for") || "unknown";
+      // 异步发送告警，不阻塞响应
+      Promise.resolve(onErrorAlert(error as Error, {
+        path: c.req.path,
+        method: c.req.method,
+        ip,
+      })).catch((alertErr) => {
+        console.error("[bootstrap:onErrorAlert] 告警发送失败:", alertErr);
+      });
+    }
+    const accept = c.req.header("accept") || "";
+    if (accept.includes("text/html")) {
+      return c.html(errorPageHtml(500, "服务暂时不可用"), 500);
+    }
+    return fail(c, "服务暂时不可用", 500, { error: error?.message });
+  });
+  // ── 预计算安全响应头 ──
+  const defaultHeaders = buildSecurityHeaders(secOpts);
+  const adminHeaders = buildSecurityHeaders({ ...secOpts, allowUnsafeEval: true });
+  function applyHeaders(response: Response, isImmutable = false, isAdmin = false): Response {
+    const headers = new Headers(response.headers);
+    const base = isAdmin ? adminHeaders : defaultHeaders;
+    for (const [k, v] of base) headers.set(k, v);
+    if (isImmutable) {
+      headers.set("Cache-Control", "public, max-age=31536000, immutable");
+    }
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+  }
+  return {
+    async fetch(request: Request, env: Record<string, unknown>, ctx: ExecutionContext) {
+      try {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        // API 路由 → Hono
+        const prefix = apiPrefix.replace(/\/$/, "");
+        if (path === prefix || path.startsWith(`${prefix}/`)) {
+          url.pathname = path.replace(new RegExp(`^${prefix}`), "") || "/";
+          return api.fetch(new Request(url, request), env, ctx);
+        }
+        // 静态资源处理需要 ASSETS binding
+        const assets = env.ASSETS as Fetcher | undefined;
+        if (!assets) {
+          return new Response(JSON.stringify({ ok: false, error: "ASSETS binding not configured" }), {
+            status: 500,
+            headers: { "content-type": "application/json" },
+          });
+        }
+        // 长缓存静态资源
+        if (immutablePrefixes.some((p) => path.startsWith(p))) {
+          return applyHeaders(await assets.fetch(request), true);
+        }
+        // 页面路由（pageRoutes 精确匹配）
+        for (const [route, file] of Object.entries(pageRoutes)) {
+          if (path === route || path.startsWith(`${route}/`)) {
+            url.pathname = file;
+            const isAdmin = route === "/admin" || route.startsWith("/admin");
+            return applyHeaders(await assets.fetch(new Request(url, request)), false, isAdmin);
+          }
+        }
+        // SPA 路由
+        if (spaRoutes && spaRoutes.paths.some((p) => path === p || path.startsWith(`${p}/`))) {
+          url.pathname = spaRoutes.fallback;
+          const res = await assets.fetch(new Request(url, request));
+          if (res.ok) return applyHeaders(res);
+          url.pathname = "/index.html";
+          return applyHeaders(await assets.fetch(new Request(url, request)));
+        }
+        // 根路径
+        if (path === "/") {
+          url.pathname = "/index.html";
+          return applyHeaders(await assets.fetch(new Request(url, request)));
+        }
+        // 其他静态资源
+        return applyHeaders(await assets.fetch(request));
+      } catch (err) {
+        console.error("[bootstrap:fetch]", err);
+        const accept = request.headers.get("accept") || "";
+        if (accept.includes("text/html")) {
+          return new Response(errorPageHtml(500, "服务暂时不可用"), {
+            status: 500,
+            headers: { "content-type": "text/html; charset=utf-8" },
+          });
+        }
+        return new Response(JSON.stringify({ ok: false, error: "服务暂时不可用" }), {
+          status: 500,
+          headers: { "content-type": "application/json" },
+        });
+      }
+    },
+  };
+}

package/src/cache.ts ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * Workers Cache API 封装
+ *
+ * Cloudflare Free 套餐的 Cache API 完全免费，不计入 10 万次/天的请求限制。
+ * 这是 Free 套餐下唯一能免费扩容的手段，必须充分利用。
+ *
+ * 使用场景：
+ * - GET /products（商品列表，TTL 5 分钟）
+ * - GET /system-config（系统配置，TTL 30 分钟）
+ * - 任何读多写少的 API 响应
+ *
+ * 来源：eshop src/lib/cache.ts
+ */
+/**
+ * 创建命名空间化的 Cache 实例。
+ *
+ * @param namespace - 缓存命名空间（通常为项目名，如 "eshop-v1"）
+ */
+export function createCache(namespace: string) {
+  function key(path: string, query?: string): string {
+    const base = `https://cache.local/${namespace}${path}`;
+    return query ? `${base}?${query}` : base;
+  }
+  return {
+    /**
+     * 从 Cache API 读取
+     */
+    async get(cacheKey: string): Promise<Response | null> {
+      try {
+        const match = await caches.default.match(cacheKey);
+        return match || null;
+      } catch (err) {
+        console.warn("[cache] get failed:", err);
+        return null;
+      }
+    },
+    /**
+     * 写入 Cache API
+     */
+    async put(cacheKey: string, response: Response, ttlSeconds: number): Promise<void> {
+      try {
+        const clone = response.clone();
+        const headers = new Headers(clone.headers);
+        headers.set("Cache-Control", `public, max-age=${ttlSeconds}`);
+        headers.set("CF-Cache-Status", "HIT");
+        const cachedResponse = new Response(clone.body, {
+          status: clone.status,
+          statusText: clone.statusText,
+          headers,
+        });
+        await caches.default.put(cacheKey, cachedResponse);
+      } catch (err) {
+        console.warn("[cache] put failed:", err);
+      }
+    },
+    /**
+     * 删除缓存
+     */
+    async delete(cacheKey: string): Promise<boolean> {
+      try {
+        return await caches.default.delete(cacheKey);
+      } catch (err) {
+        console.warn("[cache] delete failed:", err);
+        return false;
+      }
+    },
+    /** 缓存键生成器（暴露供外部使用） */
+    key,
+  };
+}
+/** 默认实例（无命名空间，适用于单项目场景） */
+export const cache = createCache("default");

package/src/config.ts ADDED Viewed

@@ -0,0 +1,134 @@
+/**
+ * 运行时系统配置模块（热生效 KV 存储）
+ *
+ * 使用 system_config 表存储运行时配置，支持热生效（无需重启）。
+ * 可选启用 Cache API 缓存以减少数据库查询。
+ *
+ * 三项目均有 system_config 表且结构完全一致。
+ *
+ * 来源：eshop/xtools/vcode system_config 表 + eshop cache.ts 合并
+ */
+import { eq } from "drizzle-orm";
+import { systemConfig } from "./db/schema";
+interface ConfigDbLike {
+  select: (cols: { value: typeof systemConfig.value }) => {
+    from: (table: typeof systemConfig) => {
+      where: (cond: unknown) => {
+        limit: (n: number) => Promise<{ value: string }[]>;
+      };
+    };
+  };
+  insert: (table: typeof systemConfig) => {
+    values: (data: { key: string; value: string; updatedAt: string }) => {
+      onConflictDoUpdate: (opts: {
+        target: typeof systemConfig.key;
+        set: { value: string; updatedAt: string };
+      }) => Promise<unknown>;
+    };
+  };
+  delete: (table: typeof systemConfig) => {
+    where: (cond: unknown) => Promise<unknown>;
+  };
+}
+export interface SystemConfigOptions {
+  /** 内存缓存 TTL（毫秒），0 表示不缓存，默认 5 分钟 */
+  cacheTtlMs?: number;
+}
+/**
+ * 系统配置管理器
+ */
+export class SystemConfig {
+  private db: ConfigDbLike;
+  private cache = new Map<string, { value: string; expiresAt: number }>();
+  private cacheTtlMs: number;
+  constructor(db: ConfigDbLike, options: SystemConfigOptions = {}) {
+    this.db = db;
+    this.cacheTtlMs = options.cacheTtlMs ?? 5 * 60 * 1000; // 5 分钟
+  }
+  /**
+   * 读取配置值
+   *
+   * 优先从内存缓存读取，过期后从数据库重新加载。
+   */
+  async get(key: string, defaultValue = ""): Promise<string> {
+    // 内存缓存
+    if (this.cacheTtlMs > 0) {
+      const cached = this.cache.get(key);
+      if (cached && Date.now() < cached.expiresAt) {
+        return cached.value;
+      }
+    }
+    try {
+      const [row] = await this.db
+        .select({ value: systemConfig.value })
+        .from(systemConfig)
+        .where(eq(systemConfig.key, key))
+        .limit(1);
+      const value = row?.value ?? defaultValue;
+      if (this.cacheTtlMs > 0) {
+        this.cache.set(key, { value, expiresAt: Date.now() + this.cacheTtlMs });
+      }
+      return value;
+    } catch {
+      return defaultValue;
+    }
+  }
+  /**
+   * 读取配置值并解析为数字
+   */
+  async getNumber(key: string, defaultValue: number): Promise<number> {
+    const raw = await this.get(key, String(defaultValue));
+    const num = Number(raw);
+    return Number.isFinite(num) ? num : defaultValue;
+  }
+  /**
+   * 读取配置值并解析为布尔
+   */
+  async getBoolean(key: string, defaultValue = false): Promise<boolean> {
+    const raw = await this.get(key, String(defaultValue));
+    return raw === "true" || raw === "1";
+  }
+  /**
+   * 写入配置值（UPSERT）
+   */
+  async set(key: string, value: string): Promise<void> {
+    await this.db
+      .insert(systemConfig)
+      .values({ key, value, updatedAt: new Date().toISOString() })
+      .onConflictDoUpdate({
+        target: systemConfig.key,
+        set: { value, updatedAt: new Date().toISOString() },
+      });
+    // 清除内存缓存
+    this.cache.delete(key);
+  }
+  /**
+   * 删除配置
+   */
+  async delete(key: string): Promise<void> {
+    await this.db.delete(systemConfig).where(eq(systemConfig.key, key));
+    this.cache.delete(key);
+  }
+  /**
+   * 清除所有内存缓存（用于强制刷新）
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+}

package/src/crypto.ts ADDED Viewed

@@ -0,0 +1,106 @@
+/**
+ * AES-256-GCM 加解密模块
+ *
+ * 使用 Web Crypto API（Workers 原生），零外部依赖。
+ * 凭据在写入数据库前加密，读取后解密，确保数据库中不存明文。
+ *
+ * 密钥来源：环境变量（32 字节 hex = 64 字符 = 256 bit）
+ * 格式：iv(12B) + ciphertext + authTag(16B)，整体 base64 编码存储
+ *
+ * 来源：xtools src/lib/crypto.ts
+ */
+const ALGO = "AES-GCM";
+const IV_LENGTH = 12;
+/** 安全地将 Uint8Array 编码为 base64（分块避免大数组展开栈溢出） */
+function arrayToBase64(bytes: Uint8Array): string {
+  const chunks: string[] = [];
+  const chunkSize = 8192;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    const chunk = bytes.subarray(i, Math.min(i + chunkSize, bytes.length));
+    chunks.push(String.fromCharCode(...chunk));
+  }
+  return btoa(chunks.join(""));
+}
+/** 安全地将 base64 解码为 Uint8Array */
+function base64ToArray(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+/** 从 hex 字符串导入 AES-256-GCM 密钥 */
+async function importKey(rawHex: string): Promise<CryptoKey> {
+  if (!rawHex || rawHex.length !== 64) {
+    throw new Error("加密密钥必须为 64 字符 hex（32 字节 / 256 bit）");
+  }
+  const keyBytes = new Uint8Array(rawHex.match(/.{2}/g)!.map((b) => parseInt(b, 16)));
+  return crypto.subtle.importKey("raw", keyBytes, { name: ALGO }, false, ["encrypt", "decrypt"]);
+}
+/**
+ * 加密 JSON 对象 → base64 字符串
+ */
+export async function encrypt(
+  data: Record<string, unknown>,
+  encryptionKeyHex: string,
+): Promise<string> {
+  const key = await importKey(encryptionKeyHex);
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const plaintext = new TextEncoder().encode(JSON.stringify(data));
+  const cipherBuffer = await crypto.subtle.encrypt({ name: ALGO, iv }, key, plaintext);
+  const combined = new Uint8Array(iv.length + cipherBuffer.byteLength);
+  combined.set(iv, 0);
+  combined.set(new Uint8Array(cipherBuffer), iv.length);
+  return arrayToBase64(combined);
+}
+/**
+ * 解密 base64 字符串 → JSON 对象
+ */
+export async function decrypt(
+  encryptedBase64: string,
+  encryptionKeyHex: string,
+): Promise<Record<string, unknown>> {
+  const key = await importKey(encryptionKeyHex);
+  const combined = base64ToArray(encryptedBase64);
+  const iv = combined.slice(0, IV_LENGTH);
+  const ciphertext = combined.slice(IV_LENGTH);
+  const plainBuffer = await crypto.subtle.decrypt({ name: ALGO, iv }, key, ciphertext);
+  return JSON.parse(new TextDecoder().decode(plainBuffer));
+}
+/**
+ * 检查加密密钥是否已配置
+ */
+export function isEncryptionAvailable(env: { CREDENTIALS_ENCRYPTION_KEY?: string }): boolean {
+  return !!(env.CREDENTIALS_ENCRYPTION_KEY && env.CREDENTIALS_ENCRYPTION_KEY.length === 64);
+}
+/**
+ * 生成 UUID v4（兼容 Cloudflare Workers）
+ *
+ * 使用 crypto.getRandomValues()（100% Workers 支持），
+ * 不依赖 crypto.randomUUID()（部分旧版本不支持）。
+ */
+export function generateUUID(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // v4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant
+  const hex = Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}