@onebots/core 1.0.0 → 1.0.5

package/lib/middleware/token-validator.js

@@ -0,0 +1,198 @@
+/**
+ * 访问令牌验证中间件
+ * 支持多种令牌格式和验证方式
+ */
+import { createLogger } from '../logger.js';
+import { logInvalidToken, logAuthFailure } from './security-audit.js';
+import crypto from 'crypto';
+const logger = createLogger('TokenValidator');
+/**
+ * 创建令牌验证中间件
+ */
+export function createTokenValidator(config = {}) {
+    const { tokenName = 'access_token', fromHeader = true, fromQuery = true, validator, required = true, errorMessage = 'Invalid or missing access token', } = config;
+    return async (ctx, next) => {
+        // 从多个位置提取令牌
+        let token;
+        if (fromHeader) {
+            // 从 Authorization header 获取
+            const authHeader = ctx.get('authorization');
+            if (authHeader) {
+                // 支持 Bearer token 格式
+                const match = authHeader.match(/^Bearer\s+(.+)$/i);
+                if (match) {
+                    token = match[1];
+                }
+                else {
+                    token = authHeader;
+                }
+            }
+        }
+        if (!token && fromQuery) {
+            // 从 query 参数获取
+            token = ctx.query[tokenName];
+        }
+        // 检查令牌是否存在
+        if (!token) {
+            if (required) {
+                logInvalidToken(ctx);
+                ctx.status = 401;
+                ctx.body = {
+                    error: 'Unauthorized',
+                    message: errorMessage,
+                };
+                return;
+            }
+            else {
+                // 可选令牌，继续执行
+                return next();
+            }
+        }
+        // 验证令牌
+        let isValid = true;
+        if (validator) {
+            try {
+                isValid = await validator(token, ctx);
+            }
+            catch (error) {
+                logger.error('Token validation error', {
+                    error: error.message,
+                    path: ctx.path,
+                });
+                isValid = false;
+            }
+        }
+        else {
+            // 默认验证：检查令牌不为空
+            isValid = token.length > 0;
+        }
+        if (!isValid) {
+            logInvalidToken(ctx, token);
+            ctx.status = 401;
+            ctx.body = {
+                error: 'Unauthorized',
+                message: errorMessage,
+            };
+            return;
+        }
+        // 将令牌存储到 context 中，供后续使用
+        ctx.state.token = token;
+        await next();
+    };
+}
+/**
+ * 创建基于配置的令牌验证器
+ * 从配置中读取 access_token 列表进行验证
+ */
+export function createConfigTokenValidator(expectedTokens) {
+    const tokenSet = new Set(expectedTokens.filter(Boolean));
+    return createTokenValidator({
+        validator: (token) => {
+            return tokenSet.has(token);
+        },
+    });
+}
+/**
+ * HMAC 签名验证
+ */
+export function createHMACValidator(secret, algorithm = 'sha256') {
+    return async (ctx, next) => {
+        const signature = ctx.get('x-signature') || ctx.query.signature;
+        if (!signature) {
+            logAuthFailure(ctx, 'Missing signature');
+            ctx.status = 401;
+            ctx.body = {
+                error: 'Unauthorized',
+                message: 'Missing signature',
+            };
+            return;
+        }
+        // 获取请求体
+        const body = ctx.request.body || ctx.request.rawBody || '';
+        const bodyString = typeof body === 'string' ? body : JSON.stringify(body);
+        // 计算 HMAC
+        const hmac = crypto.createHmac(algorithm, secret);
+        hmac.update(bodyString);
+        const expectedSignature = hmac.digest('hex');
+        // 使用时间安全比较
+        const isValid = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+        if (!isValid) {
+            logAuthFailure(ctx, 'Invalid signature');
+            ctx.status = 401;
+            ctx.body = {
+                error: 'Unauthorized',
+                message: 'Invalid signature',
+            };
+            return;
+        }
+        await next();
+    };
+}
+/**
+ * 创建带令牌管理的验证器
+ * 支持令牌过期检查和自动刷新
+ */
+export function createManagedTokenValidator(tokenManager, config = {}) {
+    const baseValidator = createTokenValidator(config);
+    return async (ctx, next) => {
+        const token = ctx.get('authorization')?.replace(/^Bearer\s+/i, '') ||
+            ctx.query[config.tokenName || 'access_token'];
+        if (!token) {
+            if (config.required !== false) {
+                logInvalidToken(ctx);
+                ctx.status = 401;
+                ctx.body = {
+                    error: 'Unauthorized',
+                    message: config.errorMessage || 'Invalid or missing access token',
+                };
+                return;
+            }
+            return next();
+        }
+        // 验证令牌
+        const validation = tokenManager.validateToken(token);
+        if (!validation.valid) {
+            if (validation.expired) {
+                logInvalidToken(ctx, token);
+                ctx.status = 401;
+                ctx.body = {
+                    error: 'Unauthorized',
+                    message: 'Token expired',
+                    code: 'TOKEN_EXPIRED',
+                };
+                return;
+            }
+            else {
+                logInvalidToken(ctx, token);
+                ctx.status = 401;
+                ctx.body = {
+                    error: 'Unauthorized',
+                    message: config.errorMessage || 'Invalid access token',
+                };
+                return;
+            }
+        }
+        // 将令牌信息存储到 context
+        ctx.state.token = token;
+        ctx.state.tokenInfo = validation.info;
+        await next();
+    };
+}
+/**
+ * 组合多个验证器
+ */
+export function combineValidators(...validators) {
+    return async (ctx, next) => {
+        for (const validator of validators) {
+            await validator(ctx, async () => {
+                // 空函数，用于链式调用
+            });
+            // 如果验证失败，响应已设置，直接返回
+            if (ctx.status === 401) {
+                return;
+            }
+        }
+        // 所有验证通过，继续执行
+        await next();
+    };
+}

package/lib/registry.d.ts

@@ -2,6 +2,7 @@ import { Protocol } from "./protocol.js";
 import { Adapter } from "./adapter.js";
 import { BaseApp } from "./base-app.js";
 import { Account } from "./account.js";
+import type { Schema } from "./config-validator.js";
 /**
  * Protocol Registry
  * Manages registration and retrieval of protocol implementations
@@ -9,6 +10,7 @@ import { Account } from "./account.js";
 export declare class ProtocolRegistry {
     private static protocols;
     private static metadata;
+    private static schemas;
     /**
      * Register a protocol implementation
      * @param name Protocol name (e.g., 'onebot', 'milky', 'satori')
@@ -17,6 +19,18 @@ export declare class ProtocolRegistry {
      * @param metadata Optional protocol metadata
      */
     static register(name: string, version: string, factory: Protocol.Factory, metadata?: Partial<Protocol.Metadata>): void;
+    /**
+     * Register a protocol config schema (key format: name.version)
+     */
+    static registerSchema(key: string, schema: Schema): void;
+    /**
+     * Get a protocol config schema by key
+     */
+    static getSchema(key: string): Schema | undefined;
+    /**
+     * Get all protocol config schemas
+     */
+    static getAllSchemas(): Record<string, Schema>;
     /**
      * Get a protocol factory
      * @param name Protocol name
@@ -63,6 +77,7 @@ export declare class ProtocolRegistry {
 export declare class AdapterRegistry {
     private static adapters;
     private static metadata;
+    private static schemas;
     /**
      * Register an adapter implementation
      * @param name Adapter name/platform (e.g., 'wechat', 'dingtalk', 'qq')
@@ -70,6 +85,18 @@ export declare class AdapterRegistry {
      * @param metadata Optional adapter metadata
      */
     static register(name: string, factory: Adapter.Factory, metadata?: Partial<Adapter.Metadata>): void;
+    /**
+     * Register an adapter config schema
+     */
+    static registerSchema(name: string, schema: Schema): void;
+    /**
+     * Get an adapter config schema
+     */
+    static getSchema(name: string): Schema | undefined;
+    /**
+     * Get all adapter config schemas
+     */
+    static getAllSchemas(): Record<string, Schema>;
     /**
      * Get an adapter factory
      * @param name Adapter name/platform

package/lib/registry.js

@@ -7,6 +7,7 @@ import { Adapter } from "./adapter.js";
 export class ProtocolRegistry {
     static protocols = new Map();
     static metadata = new Map();
+    static schemas = new Map();
     /**
      * Register a protocol implementation
      * @param name Protocol name (e.g., 'onebot', 'milky', 'satori')
@@ -36,6 +37,24 @@ export class ProtocolRegistry {
             }
         }
     }
+    /**
+     * Register a protocol config schema (key format: name.version)
+     */
+    static registerSchema(key, schema) {
+        this.schemas.set(key, schema);
+    }
+    /**
+     * Get a protocol config schema by key
+     */
+    static getSchema(key) {
+        return this.schemas.get(key);
+    }
+    /**
+     * Get all protocol config schemas
+     */
+    static getAllSchemas() {
+        return Object.fromEntries(this.schemas.entries());
+    }
     /**
      * Get a protocol factory
      * @param name Protocol name
@@ -122,6 +141,7 @@ export class ProtocolRegistry {
     static clear() {
         this.protocols.clear();
         this.metadata.clear();
+        this.schemas.clear();
     }
 }
 /**
@@ -131,6 +151,7 @@ export class ProtocolRegistry {
 export class AdapterRegistry {
     static adapters = new Map();
     static metadata = new Map();
+    static schemas = new Map();
     /**
      * Register an adapter implementation
      * @param name Adapter name/platform (e.g., 'wechat', 'dingtalk', 'qq')
@@ -151,6 +172,24 @@ export class AdapterRegistry {
             });
         }
     }
+    /**
+     * Register an adapter config schema
+     */
+    static registerSchema(name, schema) {
+        this.schemas.set(name, schema);
+    }
+    /**
+     * Get an adapter config schema
+     */
+    static getSchema(name) {
+        return this.schemas.get(name);
+    }
+    /**
+     * Get all adapter config schemas
+     */
+    static getAllSchemas() {
+        return Object.fromEntries(this.schemas.entries());
+    }
     /**
      * Get an adapter factory
      * @param name Adapter name/platform
@@ -208,5 +247,6 @@ export class AdapterRegistry {
     static clear() {
         this.adapters.clear();
         this.metadata.clear();
+        this.schemas.clear();
     }
 }

package/lib/timestamp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 统一时间戳工具：各平台有的返回 Unix **秒**、有的返回 **毫秒**，CommonEvent 等统一用 **毫秒**。
+ */
+/** 启发式阈值：大于等于该值视为已是毫秒（约对应 2001-09-09 之后的毫秒时间戳） */
+export declare const UNIX_TIMESTAMP_MS_MIN = 10000000000;
+/**
+ * 平台明确给出 **Unix 秒**（如微信公众号 CreateTime、飞书 create_time）时，转为事件用的 **毫秒**。
+ *
+ * @param seconds - 秒级时间戳（number / 数字字符串）
+ * @param options.fallbackMs - 空值、非有限数或 ≤0 时使用的毫秒时间，默认 `Date.now()`
+ */
+export declare function unixSecondsToEventMs(seconds: unknown, options?: {
+    fallbackMs?: number;
+}): number;
+/**
+ * 平台明确给出 **Unix 毫秒** 时，校验并取整；无效时使用 fallback。
+ */
+export declare function unixMillisToEventMs(ms: unknown, options?: {
+    fallbackMs?: number;
+}): number;
+/**
+ * 不确定单位时使用：**大于等于 {@link UNIX_TIMESTAMP_MS_MIN} 视为毫秒**，否则视为秒。
+ * 适用于部分文档不清或中间层混传的场景。
+ */
+export declare function coerceUnixToEventMs(value: unknown, options?: {
+    fallbackMs?: number;
+}): number;
+/**
+ * 需要 **Unix 秒** 的字段（如部分协议里的 message `time`）时使用。
+ *
+ * @param seconds - 秒级时间戳
+ * @param options.fallbackSec - 无效时的秒级时间，默认当前 `Date.now()/1000` 取整
+ */
+export declare function toUnixSeconds(seconds: unknown, options?: {
+    fallbackSec?: number;
+}): number;
+/**
+ * 平台返回 **ISO 8601 字符串**或其它 `Date` 可解析格式（如 QQ 开放消息 `timestamp`）时，转为事件用的 **毫秒**。
+ */
+export declare function dateLikeToEventMs(value: unknown, options?: {
+    fallbackMs?: number;
+}): number;

package/lib/timestamp.js

@@ -0,0 +1,72 @@
+/**
+ * 统一时间戳工具：各平台有的返回 Unix **秒**、有的返回 **毫秒**，CommonEvent 等统一用 **毫秒**。
+ */
+/** 启发式阈值：大于等于该值视为已是毫秒（约对应 2001-09-09 之后的毫秒时间戳） */
+export const UNIX_TIMESTAMP_MS_MIN = 10_000_000_000;
+/**
+ * 平台明确给出 **Unix 秒**（如微信公众号 CreateTime、飞书 create_time）时，转为事件用的 **毫秒**。
+ *
+ * @param seconds - 秒级时间戳（number / 数字字符串）
+ * @param options.fallbackMs - 空值、非有限数或 ≤0 时使用的毫秒时间，默认 `Date.now()`
+ */
+export function unixSecondsToEventMs(seconds, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (seconds == null || seconds === "")
+        return fallback;
+    const n = typeof seconds === "string" ? parseFloat(seconds) : Number(seconds);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n * 1000);
+}
+/**
+ * 平台明确给出 **Unix 毫秒** 时，校验并取整；无效时使用 fallback。
+ */
+export function unixMillisToEventMs(ms, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (ms == null || ms === "")
+        return fallback;
+    const n = typeof ms === "string" ? parseFloat(ms) : Number(ms);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n);
+}
+/**
+ * 不确定单位时使用：**大于等于 {@link UNIX_TIMESTAMP_MS_MIN} 视为毫秒**，否则视为秒。
+ * 适用于部分文档不清或中间层混传的场景。
+ */
+export function coerceUnixToEventMs(value, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (value == null || value === "")
+        return fallback;
+    const n = typeof value === "string" ? parseFloat(value) : Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    if (n >= UNIX_TIMESTAMP_MS_MIN)
+        return Math.floor(n);
+    return Math.floor(n * 1000);
+}
+/**
+ * 需要 **Unix 秒** 的字段（如部分协议里的 message `time`）时使用。
+ *
+ * @param seconds - 秒级时间戳
+ * @param options.fallbackSec - 无效时的秒级时间，默认当前 `Date.now()/1000` 取整
+ */
+export function toUnixSeconds(seconds, options) {
+    const fallback = options?.fallbackSec ?? Math.floor(Date.now() / 1000);
+    if (seconds == null || seconds === "")
+        return fallback;
+    const n = typeof seconds === "string" ? parseFloat(seconds) : Number(seconds);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n);
+}
+/**
+ * 平台返回 **ISO 8601 字符串**或其它 `Date` 可解析格式（如 QQ 开放消息 `timestamp`）时，转为事件用的 **毫秒**。
+ */
+export function dateLikeToEventMs(value, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (value == null || value === "")
+        return fallback;
+    const t = new Date(value).getTime();
+    return Number.isFinite(t) ? t : fallback;
+}

package/lib/utils.d.ts

@@ -11,8 +11,9 @@ export declare function omit<T, K extends keyof T>(source: T, keys?: Iterable<K>
  * 将驼峰命名替换为下划线分割命名
  * @param name
  * @returns
- * @todo 是否应该改名 ToUnderLine()？
  */
+export declare function toUnderLine(name: string): string;
+/** @deprecated Use {@link toUnderLine} instead. */
 export declare function toLine<T extends string>(name: T): string;
 export interface Class<T = any> {
     new (...args: any[]): T;

package/lib/utils.js

@@ -64,25 +64,14 @@ export function transformObj(obj, callback) {
 }
 // 深拷贝
 export function deepClone(obj) {
-    if (typeof obj !== "object")
-        return obj;
-    if (!obj)
+    try {
+        return structuredClone(obj);
+    }
+    catch {
+        // structuredClone does not support all types (e.g. functions, DOM nodes).
+        // Return the original reference as a best-effort fallback.
         return obj;
-    //判断拷贝的obj是对象还是数组
-    if (Array.isArray(obj))
-        return obj.map(item => deepClone(item));
-    const objClone = {};
-    for (const key in obj) {
-        if (obj.hasOwnProperty(key)) {
-            if (obj[key] && typeof obj[key] === "object") {
-                objClone[key] = deepClone(obj[key]);
-            }
-            else {
-                objClone[key] = obj[key];
-            }
-        }
     }
-    return objClone;
 }
 export function pick(source, keys, forced) {
     if (!keys)
@@ -107,11 +96,14 @@ export function omit(source, keys) {
  * 将驼峰命名替换为下划线分割命名
  * @param name
  * @returns
- * @todo 是否应该改名 ToUnderLine()？
  */
-export function toLine(name) {
+export function toUnderLine(name) {
     return name.replace(/([A-Z])/g, "_$1").toLowerCase();
 }
+/** @deprecated Use {@link toUnderLine} instead. */
+export function toLine(name) {
+    return toUnderLine(name);
+}
 export function Mixin(base, ...classes) {
     classes.forEach(ctr => {
         Object.getOwnPropertyNames(ctr.prototype).forEach(name => {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@onebots/core",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "IMHelper 核心抽象层，提供适配器、协议、账号等基础接口和类型",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "exports": {
     ".": {
@@ -30,15 +30,17 @@
   "license": "MIT",
   "devDependencies": {
     "@types/koa": "^3.0.1",
-    "@types/node": "^22.7.3",
-    "@types/koa-basic-auth": "^2.0.6",
     "@types/koa__router": "^12.0.5",
+    "@types/koa-basic-auth": "^2.0.6",
+    "@types/koa-static": "^4.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.0.0",
     "@types/ws": "^8.5.3",
     "tsc-alias": "latest",
     "tsconfig-paths": "latest",
     "tsx": "latest",
-    "typescript": "latest",
-    "web-wechat": "latest"
+    "typescript": "5.9.3",
+    "wechat": "latest"
   },
   "files": [
     "/lib/**/*.js",
@@ -50,10 +52,15 @@
     "koa": "^3.1.1",
     "koa-basic-auth": "^4.0.0",
     "koa-body": "^7.0.0",
+    "koa-static": "^5.0.0",
     "log4js": "^6.5.2",
     "reflect-metadata": "^0.1.13",
     "ws": "^8.16.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lc-cn/onebots.git"
+  },
   "scripts": {
     "start": "node .",
     "build": "rm -f *.tsbuildinfo && tsc --project tsconfig.json && tsc-alias -p tsconfig.json",