@onebots/core 1.0.0 → 1.0.4

package/lib/__tests__/integration.test.js

@@ -15,8 +15,8 @@ describe('Integration Tests', () => {
             const validated = ConfigValidator.validateWithDefaults(config, BaseAppConfigSchema);
             expect(validated.port).toBe(6727);
             expect(validated.database).toBe('onebots.db');
-            expect(validated.username).toBe('admin');
-            expect(validated.password).toBe('123456');
+            expect(validated.username).toBeUndefined();
+            expect(validated.password).toBeUndefined();
             expect(validated.log_level).toBe('info');
         });
         it('should throw ValidationError on invalid config', () => {

package/lib/account.d.ts

@@ -36,7 +36,10 @@ export declare class Account<P extends keyof Adapter.Configs = keyof Adapter.Con
     stop(force?: boolean): Promise<void>;
     getGroupList(): Promise<Adapter.GroupInfo[]>;
     getFriendList(): Promise<Adapter.FriendInfo[]>;
-    dispatch(commonEvent: CommonEvent.Base): Promise<void>;
+    /**
+     * 将通用事件同步派发到本账号绑定的各协议（协议内自行 catch，避免一次失败阻断其它协议）
+     */
+    dispatch(commonEvent: CommonEvent.Base): void;
 }
 export declare enum AccountStatus {
     Pending = "pending",// 上线中

package/lib/account.js

@@ -85,9 +85,11 @@ export class Account extends EventEmitter {
     getFriendList() {
         return this.adapter.getFriendList(this.account_id);
     }
-    async dispatch(commonEvent) {
+    /**
+     * 将通用事件同步派发到本账号绑定的各协议（协议内自行 catch，避免一次失败阻断其它协议）
+     */
+    dispatch(commonEvent) {
         this.logger.debug(`Dispatching event: ${commonEvent.type} to ${this.protocols.length} protocol(s)`);
-        // Each protocol instance formats the common event to its own standard
         for (const protocol of this.protocols) {
             this.logger.debug(`Dispatching to protocol: ${protocol.name}/${protocol.version}`);
             protocol.dispatch(commonEvent);

package/lib/adapter.d.ts

@@ -24,7 +24,18 @@ export declare abstract class Adapter<C = any, T extends keyof Adapter.Configs =
     get tableName(): string;
     protected constructor(app: I, platform: T);
     createId(id: string | number): CommonTypes.Id;
-    resolveId(id: string | number): CommonTypes.Id;
+    /**
+     * 将 string / number / 已是框架层的 Id 归一到当前适配器的 Id。
+     * - 已带有 string+number 的 Id：原样返回（避免被当成 string 键查错）。
+     * - string / number：查 id_map，无则 createId。
+     */
+    resolveId(id: string | number | CommonTypes.Id): CommonTypes.Id;
+    /**
+     * 将协议传入的 scene_id / user_id 归一为 CommonTypes.Id。
+     * - 事件侧经 createId 上报的 Id：直接可用，.string / .source 存平台原始标识。
+     * - Milky 等若传入 JSON 原始 string/number：需 resolveId 查表或建档，才能与 passiveReply 等场景用的 openid 一致。
+     */
+    protected coerceId(value: CommonTypes.Id | string | number): CommonTypes.Id;
     /**
      * 1. 发送消息
      * OneBot V11: send_private_msg, send_group_msg, send_msg
@@ -493,6 +504,15 @@ export declare abstract class Adapter<C = any, T extends keyof Adapter.Configs =
     };
     setOnline(uin: string): Promise<void>;
     setOffline(uin: string): Promise<void>;
+    /**
+     * Web 验证提交 - 可选实现。支持 Web 端完成登录验证的适配器实现此方法，
+     * 根据 type 将 data 转交给平台 Bot（如 submitSlider / submitSmsCode）。
+     */
+    submitVerification?(accountId: string, type: string, data: Record<string, unknown>): void | Promise<void>;
+    /**
+     * 请求发送短信验证码 - 可选实现。设备锁带手机号时，用户选择短信验证前需先调用此方法。
+     */
+    requestSmsCode?(accountId: string): void | Promise<void>;
     /**
      * 创建账号 - 必须由平台适配器实现
      */
@@ -508,6 +528,51 @@ export type AdapterClient<T extends Adapter = Adapter> = T extends Adapter<infer
 export declare namespace Adapter {
     interface Configs extends Record<string, any> {
     }
+    /**
+     * 验证请求的展示块（Web 按 type 通用渲染，适配器按需组合）
+     */
+    type VerificationBlock = {
+        type: 'image';
+        base64: string;
+        alt?: string;
+    } | {
+        type: 'link';
+        url: string;
+        label?: string;
+    } | {
+        type: 'text';
+        content: string;
+    } | {
+        type: 'input';
+        key: string;
+        placeholder?: string;
+        maxLength?: number;
+        secret?: boolean;
+    };
+    /**
+     * 验证请求的展示配置（全平台通用，由适配器提供）
+     */
+    interface VerificationRequestOptions {
+        blocks?: VerificationBlock[];
+    }
+    /**
+     * 统一登录验证请求（适配器 emit('verification:request', payload) 时使用）
+     * hint、options 由适配器提供，Web 仅做通用展示；onApprove/onReject 由前端绑定。
+     */
+    interface VerificationRequest {
+        platform: string;
+        account_id: string;
+        type: string;
+        /** 说明文案，由适配器提供，适用于全平台 */
+        hint: string;
+        /** 展示配置（链接、图片、输入框等），由适配器提供 */
+        options?: VerificationRequestOptions;
+        /** 为 true 时 Web 显示「发送验证码」按钮，需配合 requestSmsCode 使用 */
+        requestSmsAvailable?: boolean;
+        /** 扩展数据，可选 */
+        data?: Record<string, unknown>;
+        request_id?: string;
+    }
     interface SendMessageParams {
         scene_type: CommonTypes.Scene;
         scene_id: CommonTypes.Id;
@@ -552,6 +617,7 @@ export declare namespace Adapter {
         sender_name: string;
         scene_name: string;
     }
+    /** 单条消息详情（getMessage 等）；time 为 **Unix 秒**，与 OneBot 等协议常见约定一致 */
     interface MessageInfo {
         message_id: CommonTypes.Id;
         time: number;

package/lib/adapter.js

@@ -36,6 +36,9 @@ export class Adapter extends EventEmitter {
     // ID 管理方法
     // ============================================
     createId(id) {
+        if (id === undefined || id === null) {
+            throw new Error('createId: id 不能为 undefined 或 null');
+        }
         if (typeof id === "number")
             return { string: id.toString(), number: id, source: id };
         const [existData] = this.db.select('*').from(this.tableName).where({
@@ -57,13 +60,37 @@ export class Adapter extends EventEmitter {
         this.db.insert(this.tableName).values(newId).run();
         return newId;
     }
+    /**
+     * 将 string / number / 已是框架层的 Id 归一到当前适配器的 Id。
+     * - 已带有 string+number 的 Id：原样返回（避免被当成 string 键查错）。
+     * - string / number：查 id_map，无则 createId。
+     */
     resolveId(id) {
-        const [dbRecord] = this.db.select('*').from(this.tableName).where({
-            [typeof id === "number" ? "number" : "string"]: id
-        }).run();
+        if (typeof id === "object" &&
+            id !== null &&
+            typeof id.string === "string" &&
+            typeof id.number === "number") {
+            return id;
+        }
+        const primitive = id;
+        const [dbRecord] = this.db
+            .select("*")
+            .from(this.tableName)
+            .where({
+            [typeof primitive === "number" ? "number" : "string"]: primitive,
+        })
+            .run();
         if (dbRecord)
             return dbRecord;
-        return this.createId(id);
+        return this.createId(primitive);
+    }
+    /**
+     * 将协议传入的 scene_id / user_id 归一为 CommonTypes.Id。
+     * - 事件侧经 createId 上报的 Id：直接可用，.string / .source 存平台原始标识。
+     * - Milky 等若传入 JSON 原始 string/number：需 resolveId 查表或建档，才能与 passiveReply 等场景用的 openid 一致。
+     */
+    coerceId(value) {
+        return this.resolveId(value);
     }
     // ============================================
     // 消息相关方法 (Message - 7个)

package/lib/base-app.d.ts

@@ -64,6 +64,14 @@ export declare class BaseApp extends Koa {
      * 设置健康检查端点
      */
     private setupHealthEndpoints;
+    /**
+     * 解析 public_static_dir：相对路径基于配置文件目录（configDir），禁止相对路径穿越出 configDir；绝对路径按原样使用
+     */
+    private resolvePublicStaticDirectory;
+    /**
+     * 管理端 API：当前解析后的站点根静态目录（未配置或无效时为 null）
+     */
+    getPublicStaticRoot(): string | null;
     get adapterConfigs(): Map<string, Account.Config[]>;
     private initAdapters;
     addAccount<P extends keyof Adapter.Configs>(config: Account.Config<P>): void;
@@ -71,6 +79,10 @@ export declare class BaseApp extends Koa {
     removeAccount(p: string, uin: string, force?: boolean): void;
     get accounts(): Account<string | number, any>[];
     findOrCreateAdapter<P extends keyof Adapter.Configs>(platform: P): Adapter<any, string | number, BaseApp>;
+    /**
+     * 适配器首次创建后的钩子，子类可覆写以订阅该适配器事件（如 verification:request）
+     */
+    protected onAdapterCreated(_adapter: Adapter): void;
     start(): Promise<void>;
     reload(config: BaseApp.Config): Promise<void>;
     stop(): Promise<void>;
@@ -86,7 +98,11 @@ export declare namespace BaseApp {
         timeout?: number;
         username?: string;
         password?: string;
+        /** 管理端 Bearer 鉴权码，配置后可使用 Authorization: Bearer <access_token> 访问 API，无需用户名密码 */
+        access_token?: string;
         log_level?: LogLevel;
+        /** 站点根静态目录，相对配置文件所在目录（configDir）或绝对路径；用于企业微信等可信域名校验文件 */
+        public_static_dir?: string;
         general?: Protocol.Configs;
     } & KoaOptions & AdapterConfig;
     const defaultConfig: Config;

package/lib/base-app.js

@@ -1,12 +1,13 @@
 import Koa from "koa";
 import * as os from "os";
 import "reflect-metadata";
+import * as fs from "fs";
 import { writeFileSync } from "fs";
 import log4js from "log4js";
 import { createServer } from "http";
 import yaml from "js-yaml";
 import KoaBody from "koa-body";
-import basicAuth from "koa-basic-auth";
+import koaStatic from "koa-static";
 const { configure, connectLogger, getLogger } = log4js;
 import { deepClone, deepMerge } from "./utils.js";
 import { Router } from "./router.js";
@@ -14,11 +15,15 @@ import * as path from "path";
 import process from "process";
 import { SqliteDB } from "./db.js";
 import pkg from "../package.json" with { type: "json" };
-import { AdapterRegistry, ProtocolRegistry } from "./registry.js";
+import { AdapterRegistry } from "./registry.js";
 import { ConfigValidator, BaseAppConfigSchema } from "./config-validator.js";
 import { LifecycleManager } from "./lifecycle.js";
 import { ErrorHandler, ConfigError } from "./errors.js";
 import { createLogger } from "./logger.js";
+import { initSecurityAudit, securityAudit, closeSecurityAudit } from "./middleware/security-audit.js";
+import { defaultRateLimit } from "./middleware/rate-limit.js";
+import { metricsCollector } from "./middleware/metrics-collector.js";
+import { metrics } from "./metrics.js";
 export { configure, yaml, connectLogger };
 export class BaseApp extends Koa {
     config;
@@ -102,24 +107,33 @@ export class BaseApp extends Koa {
                 this.httpServer.close(() => resolve());
             });
         });
+        // 初始化安全审计日志
+        initSecurityAudit(path.join(BaseApp.dataDir, 'audit'));
         // 注册健康检查端点（无需认证）
         this.setupHealthEndpoints();
-        this.use(KoaBody())
-            .use(async (ctx, next) => {
-            // 健康检查端点跳过认证
-            if (ctx.path === '/health' || ctx.path === '/ready' || ctx.path === '/metrics') {
-                return next();
-            }
-            // 检查是否是协议路径格式: /{platform}/{accountId}/{protocol}/{version}/...
-            const pathParts = ctx.path?.split("/").filter(p => p) || [];
-            const [_platform, _accountId, protocol, version] = pathParts;
-            if (ProtocolRegistry.has(protocol, version)) {
-                return next();
-            }
-            return await basicAuth({
-                name: this.config.username,
-                pass: this.config.password,
-            })(ctx, next);
+        // 用户配置的站点根静态目录（需在 Router 等功能路由之前，便于 GET /xxx.txt 等直出）
+        const publicStaticDir = this.resolvePublicStaticDirectory();
+        if (publicStaticDir) {
+            this.enhancedLogger.info('已启用站点根静态目录', { dir: publicStaticDir });
+            this.use(koaStatic(publicStaticDir));
+        }
+        // 中间件链（multipart：管理端上传站点静态文件等）
+        this.use(KoaBody({
+            multipart: true,
+            formidable: {
+                maxFileSize: 2 * 1024 * 1024,
+                keepExtensions: true,
+            },
+        }))
+            // 性能指标收集（最早执行，以便记录所有请求）
+            .use(metricsCollector())
+            // 安全审计日志
+            .use(securityAudit())
+            // 速率限制（在认证之前，防止暴力破解）
+            .use(defaultRateLimit)
+            .use(async (_ctx, next) => {
+            // 本层不做鉴权。管理端鉴权仅针对 /api（由 onebots 应用层负责）；各平台对外 API（如 /{platform}/{accountId}/onebot/v11/...）由各自协议/适配器单独鉴权。
+            return next();
         })
             .use(this.router.routes())
             .use(this.router.allowedMethods());
@@ -189,33 +203,33 @@ export class BaseApp extends Koa {
                 },
             };
         });
-        // /metrics - 简单的 Prometheus 格式指标
+        // /metrics - Prometheus 格式指标
         this.router.get('/metrics', (ctx) => {
-            const metrics = [];
-            const now = Date.now();
+            const metricLines = [];
             // 基础指标
-            metrics.push(`# HELP onebots_info OneBots application info`);
-            metrics.push(`# TYPE onebots_info gauge`);
-            metrics.push(`onebots_info{version="${pkg.version}"} 1`);
-            metrics.push(`# HELP onebots_uptime_seconds Application uptime in seconds`);
-            metrics.push(`# TYPE onebots_uptime_seconds gauge`);
-            metrics.push(`onebots_uptime_seconds ${process.uptime()}`);
-            metrics.push(`# HELP onebots_started Whether the application is started`);
-            metrics.push(`# TYPE onebots_started gauge`);
-            metrics.push(`onebots_started ${this.isStarted ? 1 : 0}`);
+            metricLines.push(`# HELP onebots_info OneBots application info`);
+            metricLines.push(`# TYPE onebots_info gauge`);
+            metricLines.push(`onebots_info{version="${pkg.version}"} 1`);
+            metricLines.push(`# HELP onebots_uptime_seconds Application uptime in seconds`);
+            metricLines.push(`# TYPE onebots_uptime_seconds gauge`);
+            metricLines.push(`onebots_uptime_seconds ${process.uptime()}`);
+            metricLines.push(`# HELP onebots_started Whether the application is started`);
+            metricLines.push(`# TYPE onebots_started gauge`);
+            metricLines.push(`onebots_started ${this.isStarted ? 1 : 0}`);
             // 内存使用
             const memUsage = process.memoryUsage();
-            metrics.push(`# HELP onebots_memory_bytes Memory usage in bytes`);
-            metrics.push(`# TYPE onebots_memory_bytes gauge`);
-            metrics.push(`onebots_memory_bytes{type="rss"} ${memUsage.rss}`);
-            metrics.push(`onebots_memory_bytes{type="heapTotal"} ${memUsage.heapTotal}`);
-            metrics.push(`onebots_memory_bytes{type="heapUsed"} ${memUsage.heapUsed}`);
+            metricLines.push(`# HELP onebots_memory_bytes Memory usage in bytes`);
+            metricLines.push(`# TYPE onebots_memory_bytes gauge`);
+            metricLines.push(`onebots_memory_bytes{type="rss"} ${memUsage.rss}`);
+            metricLines.push(`onebots_memory_bytes{type="heapTotal"} ${memUsage.heapTotal}`);
+            metricLines.push(`onebots_memory_bytes{type="heapUsed"} ${memUsage.heapUsed}`);
+            metricLines.push(`onebots_memory_bytes{type="external"} ${memUsage.external}`);
             // 适配器和账号指标
-            metrics.push(`# HELP onebots_adapters_total Total number of adapters`);
-            metrics.push(`# TYPE onebots_adapters_total gauge`);
-            metrics.push(`onebots_adapters_total ${this.adapters.size}`);
-            metrics.push(`# HELP onebots_accounts_total Total accounts by platform and status`);
-            metrics.push(`# TYPE onebots_accounts_total gauge`);
+            metricLines.push(`# HELP onebots_adapters_total Total number of adapters`);
+            metricLines.push(`# TYPE onebots_adapters_total gauge`);
+            metricLines.push(`onebots_adapters_total ${this.adapters.size}`);
+            metricLines.push(`# HELP onebots_accounts_total Total accounts by platform and status`);
+            metricLines.push(`# TYPE onebots_accounts_total gauge`);
             for (const [platform, adapter] of this.adapters) {
                 let online = 0;
                 let offline = 0;
@@ -225,13 +239,69 @@ export class BaseApp extends Koa {
                     else
                         offline++;
                 }
-                metrics.push(`onebots_accounts_total{platform="${platform}",status="online"} ${online}`);
-                metrics.push(`onebots_accounts_total{platform="${platform}",status="offline"} ${offline}`);
+                metricLines.push(`onebots_accounts_total{platform="${platform}",status="online"} ${online}`);
+                metricLines.push(`onebots_accounts_total{platform="${platform}",status="offline"} ${offline}`);
+            }
+            // 添加性能指标
+            const prometheusMetrics = metrics.exportPrometheus();
+            if (prometheusMetrics.trim()) {
+                metricLines.push('\n# Performance metrics');
+                metricLines.push(prometheusMetrics);
             }
             ctx.type = 'text/plain; charset=utf-8';
-            ctx.body = metrics.join('\n') + '\n';
+            ctx.body = metricLines.join('\n') + '\n';
         });
     }
+    /**
+     * 解析 public_static_dir：相对路径基于配置文件目录（configDir），禁止相对路径穿越出 configDir；绝对路径按原样使用
+     */
+    resolvePublicStaticDirectory() {
+        const raw = this.config.public_static_dir;
+        if (raw == null || String(raw).trim() === '')
+            return null;
+        const trimmed = String(raw).trim();
+        const configDirResolved = path.resolve(BaseApp.configDir);
+        const abs = path.isAbsolute(trimmed)
+            ? path.resolve(trimmed)
+            : path.resolve(configDirResolved, trimmed);
+        if (!path.isAbsolute(trimmed)) {
+            const rel = path.relative(configDirResolved, abs);
+            // 禁止 `.`、等价空相对路径，避免整个配置目录被当作静态站点根
+            if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+                this.enhancedLogger.warn('public_static_dir 必须为配置目录下的子目录（不能为 . 或路径穿越），已忽略', {
+                    configured: trimmed,
+                    resolved: abs,
+                    configDir: configDirResolved,
+                });
+                return null;
+            }
+        }
+        let st;
+        try {
+            st = fs.statSync(abs);
+        }
+        catch {
+            try {
+                fs.mkdirSync(abs, { recursive: true });
+                st = fs.statSync(abs);
+            }
+            catch (e) {
+                this.enhancedLogger.warn('public_static_dir 无法创建或访问，静态托管已跳过', { abs, error: e });
+                return null;
+            }
+        }
+        if (!st.isDirectory()) {
+            this.enhancedLogger.warn('public_static_dir 不是目录，已忽略', { abs });
+            return null;
+        }
+        return abs;
+    }
+    /**
+     * 管理端 API：当前解析后的站点根静态目录（未配置或无效时为 null）
+     */
+    getPublicStaticRoot() {
+        return this.resolvePublicStaticDirectory();
+    }
     get adapterConfigs() {
         const map = new Map();
         Object.keys(this.config).forEach(key => {
@@ -311,8 +381,13 @@ export class BaseApp extends Koa {
             return this.adapters.get(platform);
         const adapter = AdapterRegistry.create(`${platform}`, this);
         this.adapters.set(platform, adapter);
+        this.onAdapterCreated(adapter);
         return adapter;
     }
+    /**
+     * 适配器首次创建后的钩子，子类可覆写以订阅该适配器事件（如 verification:request）
+     */
+    onAdapterCreated(_adapter) { }
     async start() {
         const stopTimer = this.enhancedLogger.start('Application start');
         try {
@@ -371,6 +446,8 @@ export class BaseApp extends Koa {
             this.adapters.clear();
             // 清理资源
             await this.lifecycle.cleanup();
+            // 关闭安全审计日志
+            closeSecurityAudit();
             this.emit("close");
             this.isStarted = false;
             stopTimer();
@@ -387,8 +464,6 @@ export class BaseApp extends Koa {
     BaseApp.defaultConfig = {
         port: 6727,
         database: "onebots.db",
-        username: "admin",
-        password: "123456",
         timeout: 30,
         general: {},
         log_level: "info",

package/lib/circuit-breaker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 熔断器模式实现
+ * 防止级联故障，提高系统稳定性
+ */
+export declare enum CircuitState {
+    /** 关闭状态：正常处理请求 */
+    CLOSED = "CLOSED",
+    /** 开启状态：拒绝所有请求 */
+    OPEN = "OPEN",
+    /** 半开状态：尝试恢复，允许部分请求通过 */
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerOptions {
+    /** 失败阈值：连续失败多少次后开启熔断 */
+    failureThreshold?: number;
+    /** 成功阈值：半开状态下成功多少次后关闭熔断 */
+    successThreshold?: number;
+    /** 超时时间：开启状态持续多久后进入半开状态（毫秒） */
+    timeout?: number;
+    /** 监控窗口大小（毫秒） */
+    monitoringPeriod?: number;
+    /** 最小请求数：在监控窗口内至少需要多少请求才触发熔断 */
+    minimumRequests?: number;
+    /** 错误率阈值：错误率超过多少时开启熔断（0-1） */
+    errorRateThreshold?: number;
+}
+/**
+ * 熔断器类
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private records;
+    private options;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * 执行函数，带熔断保护
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 成功回调
+     */
+    private onSuccess;
+    /**
+     * 失败回调
+     */
+    private onFailure;
+    /**
+     * 判断是否应该开启熔断
+     */
+    private shouldOpen;
+    /**
+     * 获取错误率
+     */
+    private getErrorRate;
+    /**
+     * 获取最近的请求记录
+     */
+    private getRecentRequests;
+    /**
+     * 清理过期记录
+     */
+    private cleanupOldRecords;
+    /**
+     * 获取当前状态
+     */
+    getState(): CircuitState;
+    /**
+     * 获取统计信息
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        errorRate: number;
+        totalRequests: number;
+    };
+    /**
+     * 手动重置熔断器
+     */
+    reset(): void;
+}
+/**
+ * 熔断器开启错误
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    constructor(message: string);
+}
+/**
+ * 创建带熔断器的函数包装器
+ */
+export declare function withCircuitBreaker<T extends (...args: any[]) => Promise<any>>(fn: T, breaker: CircuitBreaker): T;