@usethink/cf-core 0.3.0

package/features/email/index.ts

@@ -0,0 +1,172 @@
+/**
+ * email-resend — Resend 邮件发送插件
+ *
+ * 通过 Resend API 发送事务邮件，支持：
+ * - 模板插值（{{变量}}）+ HTML 转义
+ * - 3 次重试（指数退避）
+ * - 邮件日志记录（可选，需传入 Drizzle DB 实例）
+ *
+ * 来源：eshop src/services/email-service.ts
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 模板引擎
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c] ?? c),
+  );
+}
+
+export function interpolate(template: string, data: Record<string, string>): string {
+  return template
+    .replace(/\{\{(\w+)\}\}/g, (_, key) => escapeHtml(String(data[key] ?? "")))
+    .replace(/\{\{#if (\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, key, content) =>
+      data[key] ? content : "",
+    );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EmailService
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface EmailTemplate {
+  subject: string;
+  html: string;
+}
+
+export interface ResendConfig {
+  apiKey: string;
+  from?: string;
+  defaultFrom?: string;
+}
+
+export interface SendEmailOptions {
+  to: string;
+  subject: string;
+  html: string;
+  from?: string;
+}
+
+export interface SendResult {
+  ok: boolean;
+  messageId?: string;
+  error?: string;
+}
+
+/**
+ * Resend 邮件发送服务
+ *
+ * @example
+ * ```ts
+ * import { EmailService } from "@usethink/cf-core/plugins/email-resend";
+ *
+ * const email = new EmailService({ apiKey: env.RESEND_API_KEY, from: "noreply@example.com" });
+ * const result = await email.send({
+ *   to: "buyer@example.com",
+ *   subject: "订单确认",
+ *   html: "<h1>您的订单已确认</h1>",
+ * });
+ * ```
+ */
+export class EmailService {
+  readonly name = "email-resend";
+  readonly version = "0.1.0";
+
+  private config: ResendConfig;
+
+  constructor(config: ResendConfig) {
+    this.config = config;
+  }
+
+  /**
+   * 发送邮件
+   */
+  async send(opts: SendEmailOptions): Promise<SendResult> {
+    const { to, subject, html } = opts;
+    const from = opts.from || this.config.from || this.config.defaultFrom || "noreply@example.com";
+
+    if (!to || !to.includes("@")) {
+      return { ok: false, error: "无效的收件人邮箱" };
+    }
+
+    const MAX_RETRIES = 3;
+    const RETRY_DELAYS = [500, 1000, 2000];
+    let lastError = "";
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const res = await fetch("https://api.resend.com/emails", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ from, to, subject, html }),
+        });
+
+        const data = (await res.json()) as { id?: string; message?: string };
+
+        if (res.ok) {
+          return { ok: true, messageId: data.id };
+        }
+
+        if (res.status >= 400 && res.status < 500) {
+          return { ok: false, error: data.message || `HTTP ${res.status}` };
+        }
+
+        lastError = data.message || `HTTP ${res.status}`;
+        if (attempt < MAX_RETRIES) {
+          await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt - 1]));
+          continue;
+        }
+
+        return { ok: false, error: lastError };
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        if (attempt < MAX_RETRIES) {
+          await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt - 1]));
+          continue;
+        }
+        return { ok: false, error: lastError };
+      }
+    }
+
+    return { ok: false, error: lastError };
+  }
+
+  /**
+   * 使用模板发送邮件
+   */
+  async sendWithTemplate(
+    to: string,
+    template: EmailTemplate,
+    data: Record<string, string>,
+    opts?: { from?: string },
+  ): Promise<SendResult> {
+    const subject = interpolate(template.subject, data);
+    const html = interpolate(template.html, data);
+    return this.send({ to, subject, html, from: opts?.from });
+  }
+
+  /**
+   * 健康检查 — 验证 API Key 是否有效
+   */
+  async healthCheck(): Promise<boolean> {
+    try {
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ from: "test@test.com", to: "test@test.com", subject: "", html: "" }),
+      });
+      // 422 = 参数无效但 Key 有效; 401/403 = Key 无效
+      return res.status !== 401 && res.status !== 403;
+    } catch {
+      return false;
+    }
+  }
+}

package/features/email/tests/index.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { escapeHtml, interpolate } from "../index";
+
+describe("escapeHtml", () => {
+  it("转义特殊字符", () => {
+    expect(escapeHtml("<script>alert('xss')</script>")).toBe(
+      "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;",
+    );
+  });
+
+  it("普通文本不变", () => {
+    expect(escapeHtml("hello world")).toBe("hello world");
+  });
+
+  it("转义 & 和引号", () => {
+    expect(escapeHtml('a & b "c"')).toBe("a &amp; b &quot;c&quot;");
+  });
+});
+
+describe("interpolate", () => {
+  it("替换变量", () => {
+    const result = interpolate("Hello {{name}}, your order is {{orderNo}}", {
+      name: "Alice",
+      orderNo: "12345",
+    });
+    expect(result).toBe("Hello Alice, your order is 12345");
+  });
+
+  it("缺失变量替换为空", () => {
+    const result = interpolate("Hello {{name}}", {});
+    expect(result).toBe("Hello ");
+  });
+
+  it("变量值自动 HTML 转义", () => {
+    const result = interpolate("{{content}}", { content: "<b>bold</b>" });
+    expect(result).toBe("&lt;b&gt;bold&lt;/b&gt;");
+  });
+
+  it("条件块", () => {
+    const template = "{{#if showNote}}Note: {{note}}{{/if}}";
+    expect(interpolate(template, { showNote: "yes", note: "hello" })).toBe("Note: hello");
+    expect(interpolate(template, { note: "hello" })).toBe("");
+  });
+});

package/features/payment/fetch-utils.ts

@@ -0,0 +1,65 @@
+/**
+ * 支付功能模块 — HTTP 工具
+ *
+ * 带超时和指数退避重试的 fetch 封装。
+ * 所有第三方 API 调用都应通过此函数，避免 Workers CPU 耗尽。
+ */
+
+const FETCH_TIMEOUT_MS = 10_000;
+const FETCH_RETRIES = 2;
+const RETRY_DELAYS = [500, 1500];
+
+/**
+ * 带超时和指数退避重试的 fetch 封装。
+ *
+ * HTTP 4xx 不重试（客户端错误），5xx/网络错误重试。
+ * 超时通过 AbortController 实现，兼容 Workers 环境。
+ */
+export async function fetchWithRetry(
+  url: string,
+  options: RequestInit & { retries?: number; timeoutMs?: number } = {},
+): Promise<Response> {
+  const maxRetries = options.retries ?? FETCH_RETRIES;
+  const timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
+  let lastError = "";
+
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+      const resp = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      // 4xx 不重试（客户端错误）
+      if (resp.status >= 400 && resp.status < 500 && resp.status !== 429) return resp;
+
+      // 5xx 或 429 重试
+      if (!resp.ok && attempt <= maxRetries) {
+        lastError = `HTTP ${resp.status}`;
+        await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt - 1] ?? 1000));
+        continue;
+      }
+
+      return resp;
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        lastError = `Timeout after ${timeoutMs}ms`;
+      } else {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+
+      if (attempt <= maxRetries) {
+        await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt - 1] ?? 1000));
+        continue;
+      }
+      throw new Error(`[fetchWithRetry] ${lastError} (after ${attempt - 1} retries)`);
+    }
+  }
+
+  throw new Error(`[fetchWithRetry] ${lastError} (after ${maxRetries + 1} attempts)`);
+}

package/features/payment/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @usethink/cf-core/features/payment — 支付功能模块
+ *
+ * 统一导出所有支付相关能力。支持两种导入方式：
+ *
+ * 1. 从根导入（适合小项目）：
+ *    import { alipayFactory, stripeFactory } from "@usethink/cf-core/features/payment";
+ *
+ * 2. 按子路径导入（推荐，tree-shakeable）：
+ *    import { alipayFactory } from "@usethink/cf-core/features/payment/providers/alipay";
+ *    import { stripeFactory } from "@usethink/cf-core/features/payment/providers/stripe";
+ */
+
+// ── 类型 ──
+export type {
+  CreatePaymentInput,
+  CreatePaymentResult,
+  CallbackResult,
+  QueryStatusResult,
+  RefundInput,
+  RefundResult,
+  PaymentProvider,
+  ProviderRegistry,
+  ProviderFactory,
+} from "./types";
+
+// ── 注册表 ──
+export { createProviderRegistry } from "./registry";
+export type { DbProviderConfig, DbProviderConfigMap } from "./registry";
+
+// ── 支付宝 ──
+export { AlipayProvider, alipayFactory, signRSA2, verifyRSA2 } from "./providers/alipay";
+export type { AlipayConfig } from "./providers/alipay";
+
+// ── Stripe ──
+export { StripeProvider, stripeFactory } from "./providers/stripe";
+
+// ── USDT/TRC20 ──
+export { Trc20Provider, trc20Factory } from "./providers/trc20";

package/features/payment/providers/alipay.ts

@@ -0,0 +1,171 @@
+/**
+ * 支付功能模块 — 支付宝当面付 Provider
+ *
+ * 包含：
+ * - RSA2 签名工具（Web Crypto API，零依赖）
+ * - AlipayProvider 类（当面付：创建二维码、回调验签、查询状态）
+ * - alipayFactory 工厂
+ */
+
+import type {
+  CreatePaymentInput,
+  CreatePaymentResult,
+  CallbackResult,
+  QueryStatusResult,
+  PaymentProvider,
+  ProviderFactory,
+} from "../types";
+import { fetchWithRetry } from "../fetch-utils";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RSA2 签名工具（Web Crypto API，零依赖）
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const encoder = new TextEncoder();
+
+function buildSignString(params: Record<string, string>): string {
+  return Object.keys(params)
+    .filter((k) => k !== "sign" && k !== "sign_type" && params[k] !== "" && params[k] !== undefined)
+    .sort()
+    .map((k) => `${k}=${params[k]}`)
+    .join("&");
+}
+
+function base64ToUint8Array(base64: string): Uint8Array {
+  const s = atob(base64);
+  const bytes = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) bytes[i] = s.charCodeAt(i);
+  return bytes;
+}
+
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+
+async function importPrivateKey(pem: string): Promise<CryptoKey> {
+  const body = pem.replace(/-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/g, "").replace(/-----END\s+(RSA\s+)?PRIVATE\s+KEY-----/g, "").replace(/\s+/g, "");
+  const der = base64ToUint8Array(body);
+  try {
+    return await crypto.subtle.importKey("pkcs8", der, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
+  } catch {
+    const header = [0x30,0x82,0x01,0x22,0x30,0x0d,0x06,0x09,0x2a,0x86,0x48,0x86,0xf7,0x0d,0x01,0x01,0x01,0x05,0x00,0x04,0x82,0x01,0x0f];
+    const pkcs8 = new Uint8Array(header.length + der.length);
+    pkcs8.set(header); pkcs8.set(der, header.length);
+    return await crypto.subtle.importKey("pkcs8", pkcs8, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
+  }
+}
+
+async function importPublicKey(pem: string): Promise<CryptoKey> {
+  const body = pem.replace(/-----BEGIN\s+(RSA\s+)?PUBLIC\s+KEY-----/g, "").replace(/-----END\s+(RSA\s+)?PUBLIC\s+KEY-----/g, "").replace(/\s+/g, "");
+  return await crypto.subtle.importKey("spki", base64ToUint8Array(body), { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+}
+
+/** RSA2 签名（SHA256withRSA） */
+export async function signRSA2(params: Record<string, string>, privateKeyPem: string): Promise<string> {
+  const key = await importPrivateKey(privateKeyPem);
+  const sig = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, encoder.encode(buildSignString(params)));
+  return uint8ArrayToBase64(new Uint8Array(sig));
+}
+
+/** RSA2 验签 */
+export async function verifyRSA2(params: Record<string, string>, publicKeyPem: string): Promise<boolean> {
+  const sign = params["sign"];
+  if (!sign) return false;
+  const key = await importPublicKey(publicKeyPem);
+  return crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, base64ToUint8Array(sign), encoder.encode(buildSignString(params)));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AlipayProvider — 支付宝当面付
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface AlipayConfig {
+  appId: string;
+  privateKey: string;
+  alipayPublicKey: string;
+}
+
+export class AlipayProvider implements PaymentProvider {
+  readonly name = "alipay";
+  readonly displayName = "支付宝当面付";
+  readonly supportedCurrencies = ["CNY"];
+
+  constructor(private readonly config: AlipayConfig) {}
+
+  async createPayment(input: CreatePaymentInput): Promise<CreatePaymentResult> {
+    const bizContent = JSON.stringify({
+      out_trade_no: input.orderNo,
+      total_amount: (input.amountCents / 100).toFixed(2),
+      subject: input.metadata?.subject || input.description || "商品购买",
+    });
+    const timestamp = new Date().toISOString().replace("T", " ").substring(0, 19);
+    const params: Record<string, string> = {
+      app_id: this.config.appId, method: "alipay.trade.precreate", charset: "utf-8",
+      sign_type: "RSA2", timestamp, version: "1.0", notify_url: input.notifyUrl, biz_content: bizContent,
+    };
+    params.sign = await signRSA2(params, this.config.privateKey);
+
+    const resp = await fetchWithRetry("https://openapi.alipay.com/gateway.do", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded;charset=utf-8" },
+      body: new URLSearchParams(params).toString(),
+      timeoutMs: 10_000,
+      retries: 2,
+    });
+    if (!resp.ok) throw new Error(`Alipay API HTTP error: ${resp.status}`);
+
+    const data = await resp.json() as { alipay_trade_precreate_response?: { code?: string; msg?: string; sub_msg?: string; qr_code?: string } };
+    const result = data.alipay_trade_precreate_response;
+    if (!result || result.code !== "10000") throw new Error(`Alipay precreate failed: ${result?.sub_msg || result?.msg || "unknown"}`);
+    return { qrCode: result.qr_code || "" };
+  }
+
+  async verifyCallback(params: Record<string, string>): Promise<CallbackResult> {
+    if (!(await verifyRSA2(params, this.config.alipayPublicKey))) throw new Error("Alipay callback signature invalid");
+    if (params.app_id !== this.config.appId) throw new Error("Alipay callback app_id mismatch");
+    if (params.trade_status !== "TRADE_SUCCESS") throw new Error(`Unexpected trade_status: ${params.trade_status}`);
+    return {
+      orderNo: params.out_trade_no, providerTradeNo: params.trade_no,
+      amountCents: Math.round(parseFloat(params.total_amount || "0") * 100),
+      currency: "CNY", paidAt: params.gmt_payment || new Date().toISOString(),
+    };
+  }
+
+  async queryStatus(orderNo: string): Promise<QueryStatusResult> {
+    const timestamp = new Date().toISOString().replace("T", " ").substring(0, 19);
+    const params: Record<string, string> = {
+      app_id: this.config.appId, method: "alipay.trade.query", charset: "utf-8",
+      sign_type: "RSA2", timestamp, version: "1.0", biz_content: JSON.stringify({ out_trade_no: orderNo }),
+    };
+    params.sign = await signRSA2(params, this.config.privateKey);
+    const resp = await fetchWithRetry("https://openapi.alipay.com/gateway.do", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded;charset=utf-8" },
+      body: new URLSearchParams(params).toString(),
+      timeoutMs: 10_000,
+      retries: 2,
+    });
+    if (!resp.ok) throw new Error(`Alipay API HTTP error: ${resp.status}`);
+    const data = await resp.json() as { alipay_trade_query_response?: { trade_status?: string } };
+    return { paid: data.alipay_trade_query_response?.trade_status === "TRADE_SUCCESS" };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 支付宝工厂
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const alipayFactory: ProviderFactory = {
+  name: "alipay",
+  priority: 100,
+  isAvailable(env) { return !!(env.ALIPAY_APP_ID && env.ALIPAY_PRIVATE_KEY && env.ALIPAY_PUBLIC_KEY); },
+  create(env) {
+    return new AlipayProvider({
+      appId: env.ALIPAY_APP_ID as string,
+      privateKey: env.ALIPAY_PRIVATE_KEY as string,
+      alipayPublicKey: env.ALIPAY_PUBLIC_KEY as string,
+    });
+  },
+};

package/features/payment/providers/stripe.ts

@@ -0,0 +1,192 @@
+/**
+ * 支付功能模块 — Stripe Provider
+ *
+ * 包含：
+ * - Stripe Checkout Sessions（单次支付）
+ * - Webhook 签名验证（HMAC-SHA256）
+ * - stripeFactory 工厂
+ */
+
+import type {
+  CreatePaymentInput,
+  CreatePaymentResult,
+  CallbackResult,
+  QueryStatusResult,
+  PaymentProvider,
+  ProviderFactory,
+} from "../types";
+import { fetchWithRetry } from "../fetch-utils";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Stripe API 常量
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const STRIPE_API_BASE = "https://api.stripe.com/v1";
+
+/**
+ * 验证 Stripe webhook 签名（HMAC-SHA256）。
+ *
+ * Stripe webhook 签名机制：
+ * - 每个 webhook 请求携带 Stripe-Signature 头
+ * - 格式: t=timestamp,v1=signature
+ * - 签名 = HMAC-SHA256(webhookSecret, timestamp.rawBody)
+ *
+ * 参考 https://docs.stripe.com/webhooks/signatures
+ */
+async function verifyStripeSignature(
+  payload: string,
+  sigHeader: string,
+  webhookSecret: string,
+): Promise<boolean> {
+  const parts = sigHeader.split(",");
+  let timestamp = "";
+  let signature = "";
+  for (const part of parts) {
+    const [key, value] = part.split("=");
+    if (key === "t") timestamp = value;
+    if (key === "v1") signature = value;
+  }
+  if (!timestamp || !signature) return false;
+
+  // 时间戳偏差校验（±5 分钟，防止重放攻击）
+  const sigTime = parseInt(timestamp, 10) * 1000;
+  if (isNaN(sigTime) || Math.abs(Date.now() - sigTime) > 5 * 60 * 1000) return false;
+
+  // HMAC-SHA256(webhookSecret, timestamp.payload)
+  const encoder = new TextEncoder();
+  const signedPayload = `${timestamp}.${payload}`;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(webhookSecret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+  const signatureBytes = new Uint8Array(
+    signature.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [],
+  );
+  return crypto.subtle.verify("HMAC", key, signatureBytes, encoder.encode(signedPayload));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// StripeProvider — 国际信用卡支付
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export class StripeProvider implements PaymentProvider {
+  readonly name = "stripe";
+  readonly displayName = "Stripe";
+  readonly supportedCurrencies = ["USD", "EUR", "GBP", "CAD", "AUD", "JPY"];
+
+  constructor(
+    private readonly secretKey: string,
+    private readonly webhookSecret: string,
+  ) {}
+
+  /**
+   * 创建 Stripe Checkout Session。
+   *
+   * 使用 URLSearchParams（非 stripe-node SDK）构建请求，
+   * 兼容 Workers 环境（无 Node.js 内置模块）。
+   */
+  async createPayment(input: CreatePaymentInput): Promise<CreatePaymentResult> {
+    const origin = (() => {
+      try { return new URL(input.notifyUrl).origin; } catch { return "https://localhost"; }
+    })();
+
+    const params = new URLSearchParams({
+      mode: "payment",
+      "line_items[0][price_data][currency]": input.currency.toLowerCase(),
+      "line_items[0][price_data][product_data][name]": input.metadata?.subject || "商品购买",
+      "line_items[0][price_data][unit_amount]": String(input.amountCents),
+      "line_items[0][quantity]": "1",
+      "metadata[order_no]": input.orderNo,
+      success_url: `${origin}/lookup?session_id={CHECKOUT_SESSION_ID}`,
+      cancel_url: `${origin}/shop`,
+    });
+    if (input.returnUrl) params.set("success_url", input.returnUrl);
+    if (input.notifyUrl) params.set("metadata[notify_url]", input.notifyUrl);
+
+    const resp = await fetchWithRetry(`${STRIPE_API_BASE}/checkout/sessions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.secretKey}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: params.toString(),
+      timeoutMs: 10_000,
+      retries: 2,
+    });
+    if (!resp.ok) {
+      const errorBody = await resp.text();
+      throw new Error(`Stripe API error: ${resp.status} - ${errorBody}`);
+    }
+    const session = (await resp.json()) as { id: string; url?: string };
+    if (!session.url) throw new Error("Stripe returned no checkout URL");
+    return { redirectUrl: session.url, providerTradeNo: session.id };
+  }
+
+  /**
+   * 验证 Stripe webhook 回调。
+   *
+   * 路由层需传递 _raw_body（原始请求体）和 _stripe_signature（Stripe-Signature 头）。
+   */
+  async verifyCallback(params: Record<string, string>): Promise<CallbackResult> {
+    const rawPayload = params["_raw_body"];
+    const sigHeader = params["_stripe_signature"];
+    if (!rawPayload || !sigHeader) {
+      throw new Error("Stripe callback missing signature headers");
+    }
+    if (!(await verifyStripeSignature(rawPayload, sigHeader, this.webhookSecret))) {
+      throw new Error("Stripe webhook signature invalid");
+    }
+    const event = JSON.parse(rawPayload) as {
+      type?: string;
+      data?: { object?: { metadata?: Record<string, string>; amount_total?: number; currency?: string; payment_intent?: string; id?: string } };
+    };
+    if (event.type !== "checkout.session.completed") {
+      throw new Error(`Unexpected Stripe event type: ${event.type}`);
+    }
+    const session = event.data?.object;
+    if (!session) throw new Error("Stripe event missing session object");
+    const orderNo = session.metadata?.order_no;
+    if (!orderNo) throw new Error("Stripe session missing order_no metadata");
+    return {
+      orderNo,
+      providerTradeNo: session.payment_intent || session.id || "",
+      amountCents: session.amount_total || 0,
+      currency: (session.currency || "usd").toUpperCase(),
+      paidAt: new Date().toISOString(),
+    };
+  }
+
+  /** 查询 Checkout Session 支付状态 */
+  async queryStatus(tradeNo: string): Promise<QueryStatusResult> {
+    const resp = await fetchWithRetry(`${STRIPE_API_BASE}/checkout/sessions/${tradeNo}`, {
+      headers: { Authorization: `Bearer ${this.secretKey}` },
+      timeoutMs: 8_000,
+      retries: 2,
+    });
+    if (!resp.ok) return { paid: false };
+    const session = (await resp.json()) as { payment_status?: string; payment_intent?: string };
+    return {
+      paid: session.payment_status === "paid",
+      providerTradeNo: session.payment_intent,
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Stripe 工厂
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export const stripeFactory: ProviderFactory = {
+  name: "stripe",
+  priority: 200,
+  isAvailable(env) { return !!(env.STRIPE_SECRET_KEY && env.STRIPE_WEBHOOK_SECRET); },
+  create(env) {
+    return new StripeProvider(
+      env.STRIPE_SECRET_KEY as string,
+      env.STRIPE_WEBHOOK_SECRET as string,
+    );
+  },
+};