@usethink/cf-core 0.3.0

package/dist/src/security.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 安全工具模块
+ *
+ * 提供 SHA-256 哈希、IP 哈希（加盐）、时序安全比较、Turnstile 人机验证、安全响应头。
+ * 合并自 eshop/xtools/vcode 三项目的 security.ts，取各版本之长。
+ *
+ * 设计要点：
+ * - 纯函数/泛型 Context，不绑定特定项目的 AppEnv
+ * - 所有加密操作使用 Web Crypto API（Workers 原生）
+ * - IP 仅信任 cf-connecting-ip（CF 边缘注入，客户端无法伪造）
+ */
+import type { Context } from "hono";
+import type { TurnstileResult } from "./types";
+/**
+ * 对字符串进行 SHA-256 哈希，返回 64 位十六进制字符串。
+ */
+export declare function sha256(input: string): Promise<string>;
+/**
+ * 恒定时间字符串比较 — 防止时序攻击。
+ *
+ * 使用 crypto.subtle.timingSafeEqual 比较两个字符串的 UTF-8 字节序列。
+ * 长度不匹配时回退到手写比较（仍为恒定时间），避免长度泄露信息。
+ *
+ * 来源：eshop（crypto.subtle 版）+ xtools（手写 XOR 版）合并
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * 获取客户端 IP 的加盐 SHA-256 哈希。
+ *
+ * - 仅信任 cf-connecting-ip（CF 边缘注入）
+ * - 非 CF 环境降级使用 x-forwarded-for + "dev:" 前缀
+ * - 加盐防止反向查找
+ *
+ * @param c - Hono Context
+ * @param salt - 盐值，默认从 env.RATE_LIMIT_SALT 读取
+ */
+export declare function getIpHash(c: Context<any>, salt?: string): Promise<string>;
+/**
+ * 获取原始客户端 IP（用于日志，不做隐私存储时可用）
+ */
+export declare function getClientIp(c: Context): string;
+/**
+ * 从 Authorization 请求头提取 Bearer Token。
+ * 格式：Authorization: Bearer <token>
+ */
+export declare function getBearerToken(c: Context): string;
+/**
+ * Cloudflare Turnstile 验证。
+ *
+ * - 未配置 TURNSTILE_SECRET_KEY 时直接放行（分阶段部署）
+ * - 无 token 时静默通过（smoke 测试/管理端调用）
+ * - 验证失败返回 { ok: false, message }
+ *
+ * 来源：eshop（FormData 版）+ vcode（urlencoded 版）合并为 FormData 版（更规范）
+ */
+export declare function verifyTurnstile(c: Context<any>, token?: string): Promise<TurnstileResult>;
+export interface SecurityHeadersOptions {
+    /** CSP 额外 script-src（如 CDN 域名） */
+    extraScriptSrc?: string[];
+    /** CSP 额外 style-src */
+    extraStyleSrc?: string[];
+    /** CSP 额外 connect-src */
+    extraConnectSrc?: string[];
+    /** CSP 额外 font-src */
+    extraFontSrc?: string[];
+    /** 是否允许 unsafe-eval（admin 页面的 Vue UMD 需要） */
+    allowUnsafeEval?: boolean;
+    /** 是否允许 Telegram WebApp SDK */
+    allowTelegram?: boolean;
+}
+/**
+ * 生成安全响应头（CSP + 安全头）
+ *
+ * 合并三项目不同的 CSP 策略为统一配置接口。
+ * 返回 Headers 对象，可直接合并到响应中。
+ */
+export declare function buildSecurityHeaders(options?: SecurityHeadersOptions): Headers;
+//# sourceMappingURL=security.d.ts.map

package/dist/src/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAQ/C;;GAEG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK3D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU/D;AAMD;;;;;;;;;GASG;AAEH,wBAAsB,SAAS,CAC7B,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAK9C;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAIjD;AAMD;;;;;;;;GAQG;AAEH,wBAAsB,eAAe,CACnC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAMD,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uBAAuB;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,yBAAyB;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,sBAAsB;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+BAA+B;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAyClF"}

package/dist/src/security.js

@@ -0,0 +1,175 @@
+/**
+ * 安全工具模块
+ *
+ * 提供 SHA-256 哈希、IP 哈希（加盐）、时序安全比较、Turnstile 人机验证、安全响应头。
+ * 合并自 eshop/xtools/vcode 三项目的 security.ts，取各版本之长。
+ *
+ * 设计要点：
+ * - 纯函数/泛型 Context，不绑定特定项目的 AppEnv
+ * - 所有加密操作使用 Web Crypto API（Workers 原生）
+ * - IP 仅信任 cf-connecting-ip（CF 边缘注入，客户端无法伪造）
+ */
+const encoder = new TextEncoder();
+// ═══════════════════════════════════════════════════════════════════════════════
+// 基础密码学工具
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * 对字符串进行 SHA-256 哈希，返回 64 位十六进制字符串。
+ */
+export async function sha256(input) {
+    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(input));
+    return [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * 恒定时间字符串比较 — 防止时序攻击。
+ *
+ * 使用 crypto.subtle.timingSafeEqual 比较两个字符串的 UTF-8 字节序列。
+ * 长度不匹配时回退到手写比较（仍为恒定时间），避免长度泄露信息。
+ *
+ * 来源：eshop（crypto.subtle 版）+ xtools（手写 XOR 版）合并
+ */
+export function constantTimeEqual(a, b) {
+    const aBuf = encoder.encode(a);
+    const bBuf = encoder.encode(b);
+    // 手写 XOR 比较（恒定时间，兼容 Node.js 和 Workers）
+    if (aBuf.byteLength !== bBuf.byteLength)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < aBuf.byteLength; i++) {
+        diff |= aBuf[i] ^ bBuf[i];
+    }
+    return diff === 0;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// IP 哈希
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * 获取客户端 IP 的加盐 SHA-256 哈希。
+ *
+ * - 仅信任 cf-connecting-ip（CF 边缘注入）
+ * - 非 CF 环境降级使用 x-forwarded-for + "dev:" 前缀
+ * - 加盐防止反向查找
+ *
+ * @param c - Hono Context
+ * @param salt - 盐值，默认从 env.RATE_LIMIT_SALT 读取
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function getIpHash(c, salt) {
+    const cfIp = c.req.header("cf-connecting-ip");
+    let ip;
+    if (cfIp) {
+        ip = cfIp;
+    }
+    else {
+        ip = "dev:" + (c.req.header("x-forwarded-for") || "0.0.0.0");
+    }
+    const actualSalt = salt ?? c.env.RATE_LIMIT_SALT ?? "cf-core-salt";
+    return sha256(`${actualSalt}:${ip}`);
+}
+/**
+ * 获取原始客户端 IP（用于日志，不做隐私存储时可用）
+ */
+export function getClientIp(c) {
+    const cfIp = c.req.header("cf-connecting-ip");
+    if (cfIp)
+        return cfIp;
+    const xff = c.req.header("x-forwarded-for");
+    return xff ? xff.split(",")[0].trim() : "unknown";
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Bearer Token 提取
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * 从 Authorization 请求头提取 Bearer Token。
+ * 格式：Authorization: Bearer <token>
+ */
+export function getBearerToken(c) {
+    const auth = c.req.header("authorization") || "";
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    return match?.[1]?.trim() || "";
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Turnstile 人机验证
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Cloudflare Turnstile 验证。
+ *
+ * - 未配置 TURNSTILE_SECRET_KEY 时直接放行（分阶段部署）
+ * - 无 token 时静默通过（smoke 测试/管理端调用）
+ * - 验证失败返回 { ok: false, message }
+ *
+ * 来源：eshop（FormData 版）+ vcode（urlencoded 版）合并为 FormData 版（更规范）
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function verifyTurnstile(c, token) {
+    const secret = c.env.TURNSTILE_SECRET_KEY;
+    if (!secret)
+        return { ok: true };
+    if (!token)
+        return { ok: true };
+    const form = new FormData();
+    form.append("secret", secret);
+    form.append("response", token);
+    const ip = c.req.header("cf-connecting-ip");
+    if (ip)
+        form.append("remoteip", ip);
+    try {
+        const response = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+            method: "POST",
+            body: form,
+        });
+        const data = await response.json();
+        if (!data.success) {
+            console.warn("[turnstile] verification failed", {
+                errorCodes: data["error-codes"] || [],
+            });
+            return { ok: false, message: "人机验证失败" };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        console.error("[turnstile] fetch error:", err);
+        return { ok: true };
+    }
+}
+/**
+ * 生成安全响应头（CSP + 安全头）
+ *
+ * 合并三项目不同的 CSP 策略为统一配置接口。
+ * 返回 Headers 对象，可直接合并到响应中。
+ */
+export function buildSecurityHeaders(options = {}) {
+    const { extraScriptSrc = [], extraStyleSrc = [], extraConnectSrc = [], extraFontSrc = [], allowUnsafeEval = false, allowTelegram = false, } = options;
+    const scriptSrc = [
+        "'self'",
+        "'unsafe-inline'",
+        "https://unpkg.com",
+        "https://static.cloudflareinsights.com",
+        "https://challenges.cloudflare.com",
+        ...(allowUnsafeEval ? ["'unsafe-eval'"] : []),
+        ...(allowTelegram ? ["https://telegram.org"] : []),
+        ...extraScriptSrc,
+    ];
+    const csp = [
+        "default-src 'self'",
+        `style-src 'self' 'unsafe-inline' https://unpkg.com ${extraStyleSrc.join(" ")}`.trim(),
+        `script-src ${scriptSrc.join(" ")}`,
+        "img-src 'self' data: https:",
+        `connect-src 'self' https://unpkg.com https://challenges.cloudflare.com https://static.cloudflareinsights.com ${extraConnectSrc.join(" ")}`.trim(),
+        "frame-src 'self' https://challenges.cloudflare.com",
+        "object-src 'none'",
+        "base-uri 'self'",
+        ...(extraFontSrc.length > 0 ? [`font-src 'self' ${extraFontSrc.join(" ")}`] : []),
+    ].join("; ");
+    return new Headers({
+        "Content-Security-Policy": csp,
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "DENY",
+        "Referrer-Policy": "strict-origin-when-cross-origin",
+        "Permissions-Policy": "camera=(), microphone=(), geolocation=(), payment=()",
+        "Cross-Origin-Opener-Policy": "same-origin",
+    });
+}
+//# sourceMappingURL=security.js.map

package/dist/src/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/security.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @usethink/cf-core — 公共类型定义
+ *
+ * 所有项目共享的基础类型约束。
+ * 各项目通过 extends 扩展自己的 AppEnv，保持与 cf-core 兼容。
+ */
+/**
+ * 所有 Cloudflare Workers 项目必须满足的最小 Bindings 约束。
+ * 各项目在此基础上添加自己的环境变量。
+ */
+export interface CoreBindings {
+    TURSO_URL?: string;
+    TURSO_TOKEN?: string;
+    ADMIN_TOKEN?: string;
+    TURNSTILE_SECRET_KEY?: string;
+    RATE_LIMIT_SALT?: string;
+    APP_ORIGIN?: string;
+}
+/**
+ * Hono Variables 的最小约束。
+ * 各项目的 Variables 至少包含 db 字段，类型由项目自行指定。
+ */
+export interface CoreVariables {
+    db: unknown;
+}
+/**
+ * Hono 上下文的最小环境约束。
+ * cf-core 中所有需要 Context 的函数都以此为泛型上界。
+ */
+export interface CoreEnv {
+    Bindings: CoreBindings;
+    Variables: CoreVariables;
+}
+/**
+ * ok/fail 统一响应格式。
+ */
+export interface OkResponse {
+    ok: true;
+    [key: string]: unknown;
+}
+export interface FailResponse {
+    ok: false;
+    error: string;
+    details?: unknown;
+}
+/**
+ * Turnstile 验证结果。
+ */
+export interface TurnstileResult {
+    ok: boolean;
+    message?: string;
+}
+/**
+ * 限流检查结果。
+ */
+export interface RateLimitResult {
+    ok: boolean;
+    message?: string;
+    status?: number;
+    ipHash?: string;
+    remaining?: number;
+    resetMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,IAAI,CAAC;IACT,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/src/types.js

@@ -0,0 +1,8 @@
+/**
+ * @usethink/cf-core — 公共类型定义
+ *
+ * 所有项目共享的基础类型约束。
+ * 各项目通过 extends 扩展自己的 AppEnv，保持与 cf-core 兼容。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/features/anti-abuse/index.ts

@@ -0,0 +1,180 @@
+/**
+ * anti-abuse — 防刷检测插件
+ *
+ * 提供 API 级别的异常行为检测：
+ * - 多 IP 访问同一资源
+ * - 高频请求检测
+ * - 凭证扫描检测（顺序遍历 ID）
+ * - 快速连续操作检测
+ *
+ * 纯内存实现（Workers 实例级别），无需外部存储。
+ *
+ * 来源：vcode src/services/anti-abuse.ts
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 类型定义
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export type AbuseType = "multi_ip_access" | "high_frequency" | "token_scan" | "rapid_fire";
+
+export interface AbuseEvent {
+  type: AbuseType;
+  resourceId: string;
+  ipHash: string;
+  timestamp: number;
+  detail: string;
+}
+
+export interface AntiAbuseConfig {
+  /** 同一资源允许的最大不同 IP 数（默认 5） */
+  maxIpsPerResource?: number;
+  /** 同一 IP 在窗口内允许的最大请求数（默认 30） */
+  maxRequestsPerIp?: number;
+  /** 请求频率窗口（毫秒，默认 60000） */
+  windowMs?: number;
+  /** 连续 ID 差值阈值（检测扫描，默认 3） */
+  scanThreshold?: number;
+  /** 快速连续操作最小间隔（毫秒，默认 500） */
+  rapidFireIntervalMs?: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AntiAbuseService
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export class AntiAbuseService {
+  readonly name = "anti-abuse";
+  readonly version = "0.1.0";
+
+  private config: Required<AntiAbuseConfig>;
+
+  // 内存存储
+  private resourceIps = new Map<string, Set<string>>();
+  private ipRequests = new Map<string, number[]>();
+  private lastAccessByIp = new Map<string, number>();
+  private lastResourceIdByIp = new Map<string, string>();
+  private events: AbuseEvent[] = [];
+
+  constructor(config: AntiAbuseConfig = {}) {
+    this.config = {
+      maxIpsPerResource: config.maxIpsPerResource ?? 5,
+      maxRequestsPerIp: config.maxRequestsPerIp ?? 30,
+      windowMs: config.windowMs ?? 60_000,
+      scanThreshold: config.scanThreshold ?? 3,
+      rapidFireIntervalMs: config.rapidFireIntervalMs ?? 500,
+    };
+  }
+
+  /**
+   * 记录一次资源访问，返回检测到的异常事件列表
+   */
+  record(resourceId: string, ipHash: string): AbuseEvent[] {
+    const now = Date.now();
+    const detected: AbuseEvent[] = [];
+
+    // 1. 多 IP 访问检测
+    if (!this.resourceIps.has(resourceId)) {
+      this.resourceIps.set(resourceId, new Set());
+    }
+    const ips = this.resourceIps.get(resourceId)!;
+    ips.add(ipHash);
+    if (ips.size > this.config.maxIpsPerResource) {
+      detected.push({
+        type: "multi_ip_access",
+        resourceId,
+        ipHash,
+        timestamp: now,
+        detail: `${ips.size} different IPs accessed this resource (limit: ${this.config.maxIpsPerResource})`,
+      });
+    }
+
+    // 2. 高频请求检测
+    if (!this.ipRequests.has(ipHash)) {
+      this.ipRequests.set(ipHash, []);
+    }
+    const timestamps = this.ipRequests.get(ipHash)!;
+    const windowStart = now - this.config.windowMs;
+    const validTimestamps = timestamps.filter((ts) => ts > windowStart);
+    validTimestamps.push(now);
+    this.ipRequests.set(ipHash, validTimestamps);
+
+    if (validTimestamps.length > this.config.maxRequestsPerIp) {
+      detected.push({
+        type: "high_frequency",
+        resourceId,
+        ipHash,
+        timestamp: now,
+        detail: `${validTimestamps.length} requests in ${this.config.windowMs}ms (limit: ${this.config.maxRequestsPerIp})`,
+      });
+    }
+
+    // 3. 凭证扫描检测
+    const lastId = this.lastResourceIdByIp.get(ipHash);
+    if (lastId) {
+      const idDiff = this.parseNumericId(resourceId) - this.parseNumericId(lastId);
+      if (idDiff > 0 && idDiff <= this.config.scanThreshold) {
+        detected.push({
+          type: "token_scan",
+          resourceId,
+          ipHash,
+          timestamp: now,
+          detail: `Sequential ID access: ${lastId} → ${resourceId} (diff: ${idDiff})`,
+        });
+      }
+    }
+    this.lastResourceIdByIp.set(ipHash, resourceId);
+
+    // 4. 快速连续操作检测
+    const lastAccess = this.lastAccessByIp.get(ipHash);
+    if (lastAccess && now - lastAccess < this.config.rapidFireIntervalMs) {
+      detected.push({
+        type: "rapid_fire",
+        resourceId,
+        ipHash,
+        timestamp: now,
+        detail: `Rapid access: ${now - lastAccess}ms (min: ${this.config.rapidFireIntervalMs}ms)`,
+      });
+    }
+    this.lastAccessByIp.set(ipHash, now);
+
+    // 记录事件
+    for (const event of detected) {
+      this.events.push(event);
+    }
+
+    return detected;
+  }
+
+  /**
+   * 获取最近的异常事件
+   */
+  getEvents(limit = 50): AbuseEvent[] {
+    return this.events.slice(-limit);
+  }
+
+  /**
+   * 检查某个 IP 是否可疑
+   */
+  isSuspicious(ipHash: string): boolean {
+    return this.events.some((e) => e.ipHash === ipHash);
+  }
+
+  /**
+   * 清理过期数据
+   */
+  cleanup(): void {
+    const cutoff = Date.now() - this.config.windowMs * 2;
+    for (const [ip, timestamps] of this.ipRequests) {
+      const valid = timestamps.filter((ts) => ts > cutoff);
+      if (valid.length === 0) this.ipRequests.delete(ip);
+      else this.ipRequests.set(ip, valid);
+    }
+    this.events = this.events.filter((e) => e.timestamp > cutoff);
+  }
+
+  private parseNumericId(id: string): number {
+    const match = id.match(/(\d+)$/);
+    return match ? parseInt(match[1]) : 0;
+  }
+}

package/features/anti-abuse/tests/index.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { AntiAbuseService } from "../index";
+
+describe("AntiAbuseService", () => {
+  it("正常访问无异常", () => {
+    const svc = new AntiAbuseService();
+    const events = svc.record("token-abc-123", "ip-hash-1");
+    expect(events).toEqual([]);
+  });
+
+  it("高频请求检测", () => {
+    const svc = new AntiAbuseService({ maxRequestsPerIp: 3, windowMs: 60000 });
+    let events: any[] = [];
+    for (let i = 0; i < 5; i++) {
+      events = svc.record(`token-${i}`, "same-ip");
+    }
+    expect(events.some((e) => e.type === "high_frequency")).toBe(true);
+  });
+
+  it("多 IP 访问检测", () => {
+    const svc = new AntiAbuseService({ maxIpsPerResource: 2 });
+    svc.record("token-shared", "ip-1");
+    svc.record("token-shared", "ip-2");
+    const events = svc.record("token-shared", "ip-3");
+    expect(events.some((e) => e.type === "multi_ip_access")).toBe(true);
+  });
+
+  it("快速连续操作检测", () => {
+    const svc = new AntiAbuseService({ rapidFireIntervalMs: 1000 });
+    svc.record("token-a", "fast-ip");
+    // 立即再次访问
+    const events = svc.record("token-b", "fast-ip");
+    expect(events.some((e) => e.type === "rapid_fire")).toBe(true);
+  });
+
+  it("isSuspicious 检测", () => {
+    const svc = new AntiAbuseService({ maxRequestsPerIp: 1 });
+    svc.record("t-1", "bad-ip");
+    svc.record("t-2", "bad-ip"); // 触发 high_frequency
+    expect(svc.isSuspicious("bad-ip")).toBe(true);
+    expect(svc.isSuspicious("clean-ip")).toBe(false);
+  });
+
+  it("cleanup 清理过期数据", () => {
+    const svc = new AntiAbuseService({ windowMs: 1 });
+    svc.record("t-1", "ip-1");
+    svc.cleanup();
+    expect(svc.getEvents()).toEqual([]);
+  });
+});