befly 3.2.1 → 3.3.1

package/{utils → lib}/jwt.ts

@@ -1,6 +1,6 @@
 /**
- * JWT 工具类 - TypeScript 版本
- * 提供JWT token的签名、验证和解码功能以及应用层的便捷接口
+ * JWT 工具类 - Befly 项目专用
+ * 直接集成环境变量，提供开箱即用的 JWT 功能
  */
 
 import { createHmac } from 'crypto';
@@ -96,36 +96,22 @@ export class Jwt {
     /**
      * 签名 JWT token
      * @param payload - JWT载荷数据
-     * @param options - 签名选项
+     * @param options - 签名选项（自动使用 Env.JWT_SECRET）
      * @returns JWT token字符串
      */
-    static sign(payload: JwtPayload, options: JwtSignOptions): string;
-    static sign(payload: JwtPayload, secret: string, expiresIn: string | number): string;
-    static sign(payload: JwtPayload, optionsOrSecret: JwtSignOptions | string = {}, expiresIn?: string | number): string {
+    static sign(payload: JwtPayload, options?: JwtSignOptions): string {
         if (!payload || typeof payload !== 'object') {
             throw new Error('载荷必须是非空对象');
         }
 
-        // 支持两种调用方式
-        let options: JwtSignOptions;
-        if (typeof optionsOrSecret === 'string') {
-            // sign(payload, secret, expiresIn) 形式
-            options = {
-                secret: optionsOrSecret,
-                expiresIn: expiresIn
-            };
-        } else {
-            // sign(payload, options) 形式
-            options = optionsOrSecret;
-        }
-
-        const secret = options.secret || Env.JWT_SECRET;
-        const algorithm = (options.algorithm || Env.JWT_ALGORITHM || 'HS256') as JwtAlgorithm;
-
+        const secret = options?.secret || Env.JWT_SECRET;
         if (!secret) {
-            throw new Error('JWT密钥是必需的');
+            throw new Error('JWT密钥未配置');
         }
 
+        const opts = options || {};
+        const algorithm = (opts.algorithm || Env.JWT_ALGORITHM || 'HS256') as JwtAlgorithm;
+
         const now = Math.floor(Date.now() / 1000);
 
         // 创建 header
@@ -139,17 +125,22 @@ export class Jwt {
         // 创建 payload
         const jwtPayload: JwtPayload = { ...payload, iat: now };
 
-        if (options.expiresIn || Env.JWT_EXPIRES_IN) {
-            const expSeconds = Jwt.parseExpiration(options.expiresIn || Env.JWT_EXPIRES_IN);
+        if (opts.expiresIn) {
+            const expSeconds = Jwt.parseExpiration(opts.expiresIn);
+            jwtPayload.exp = now + expSeconds;
+        } else {
+            // 使用默认过期时间
+            const defaultExpiry = Env.JWT_EXPIRES_IN || '7d';
+            const expSeconds = Jwt.parseExpiration(defaultExpiry);
             jwtPayload.exp = now + expSeconds;
         }
-        if (options.issuer) jwtPayload.iss = options.issuer;
-        if (options.audience) jwtPayload.aud = options.audience;
-        if (options.subject) jwtPayload.sub = options.subject;
-        if (options.notBefore) {
-            jwtPayload.nbf = typeof options.notBefore === 'number' ? options.notBefore : now + Jwt.parseExpiration(options.notBefore);
+        if (opts.issuer) jwtPayload.iss = opts.issuer;
+        if (opts.audience) jwtPayload.aud = opts.audience;
+        if (opts.subject) jwtPayload.sub = opts.subject;
+        if (opts.notBefore) {
+            jwtPayload.nbf = typeof opts.notBefore === 'number' ? opts.notBefore : now + Jwt.parseExpiration(opts.notBefore);
         }
-        if (options.jwtId) jwtPayload.jti = options.jwtId;
+        if (opts.jwtId) jwtPayload.jti = opts.jwtId;
 
         const encodedPayload = Jwt.base64UrlEncode(JSON.stringify(jwtPayload));
 
@@ -163,31 +154,21 @@ export class Jwt {
     /**
      * 验证 JWT token
      * @param token - JWT token字符串
-     * @param options - 验证选项
+     * @param options - 验证选项（自动使用 Env.JWT_SECRET）
      * @returns 解码后的载荷数据
      */
-    static verify(token: string, options: JwtVerifyOptions): JwtPayload;
-    static verify(token: string, secret: string): JwtPayload;
-    static verify(token: string, optionsOrSecret: JwtVerifyOptions | string = {}): JwtPayload {
+    static verify(token: string, options?: JwtVerifyOptions): JwtPayload {
         if (!token || typeof token !== 'string') {
             throw new Error('Token必须是非空字符串');
         }
 
-        // 支持两种调用方式
-        let options: JwtVerifyOptions;
-        if (typeof optionsOrSecret === 'string') {
-            // verify(token, secret) 形式
-            options = { secret: optionsOrSecret };
-        } else {
-            // verify(token, options) 形式
-            options = optionsOrSecret;
-        }
-
-        const secret = options.secret || Env.JWT_SECRET;
+        const secret = options?.secret || Env.JWT_SECRET;
         if (!secret) {
-            throw new Error('JWT密钥是必需的');
+            throw new Error('JWT密钥未配置');
         }
 
+        const opts = options || {};
+
         const parts = token.split('.');
         if (parts.length !== 3) {
             throw new Error('JWT格式无效');
@@ -215,24 +196,24 @@ export class Jwt {
             // 验证时间
             const now = Math.floor(Date.now() / 1000);
 
-            if (!options.ignoreExpiration && payload.exp && payload.exp < now) {
+            if (!opts.ignoreExpiration && payload.exp && payload.exp < now) {
                 throw new Error('Token已过期 (expired)');
             }
-            if (!options.ignoreNotBefore && payload.nbf && payload.nbf > now) {
+            if (!opts.ignoreNotBefore && payload.nbf && payload.nbf > now) {
                 throw new Error('Token尚未生效');
             }
 
             // 验证 issuer、audience、subject
-            if (options.issuer && payload.iss !== options.issuer) {
+            if (opts.issuer && payload.iss !== opts.issuer) {
                 throw new Error('Token发行者无效');
             }
-            if (options.audience) {
+            if (opts.audience) {
                 const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
-                if (!audiences.includes(options.audience)) {
+                if (!audiences.includes(opts.audience)) {
                     throw new Error('Token受众无效');
                 }
             }
-            if (options.subject && payload.sub !== options.subject) {
+            if (opts.subject && payload.sub !== opts.subject) {
                 throw new Error('Token主题无效');
             }
 
@@ -298,68 +279,146 @@ export class Jwt {
         return this.getTimeToExpiry(token) <= 0;
     }
 
-    // ==================== 应用层便捷方法 ====================
+    /**
+     * 检查 token 是否即将过期
+     * @param token - JWT token字符串
+     * @param thresholdSeconds - 过期阈值(秒)，默认300秒(5分钟)
+     * @returns 是否即将过期
+     */
+    static isNearExpiry(token: string, thresholdSeconds: number = 300): boolean {
+        const timeToExpiry = this.getTimeToExpiry(token);
+        return timeToExpiry > 0 && timeToExpiry <= thresholdSeconds;
+    }
+
+    /**
+     * 检查载荷是否包含特定角色
+     * @param payload - JWT载荷
+     * @param role - 要检查的角色
+     * @returns 是否包含该角色
+     */
+    static hasRole(payload: JwtPayload, role: string): boolean {
+        if (!payload) return false;
+        if (payload.role === role) return true;
+        if (Array.isArray(payload.roles) && payload.roles.includes(role)) return true;
+        return false;
+    }
+
+    /**
+     * 检查载荷是否包含任意一个角色
+     * @param payload - JWT载荷
+     * @param roles - 要检查的角色列表
+     * @returns 是否包含任意一个角色
+     */
+    static hasAnyRole(payload: JwtPayload, roles: string[]): boolean {
+        if (!payload) return false;
+        return roles.some((role) => this.hasRole(payload, role));
+    }
+
+    /**
+     * 检查载荷是否包含特定权限
+     * @param payload - JWT载荷
+     * @param permission - 要检查的权限
+     * @returns 是否包含该权限
+     */
+    static hasPermission(payload: JwtPayload, permission: string): boolean {
+        if (!payload || !payload.permissions) return false;
+        return Array.isArray(payload.permissions) && payload.permissions.includes(permission);
+    }
+
+    /**
+     * 检查载荷是否包含所有权限
+     * @param payload - JWT载荷
+     * @param permissions - 要检查的权限列表
+     * @returns 是否包含所有权限
+     */
+    static hasAllPermissions(payload: JwtPayload, permissions: string[]): boolean {
+        if (!payload || !payload.permissions) return false;
+        return permissions.every((permission) => this.hasPermission(payload, permission));
+    }
+
+    // ==================== 便捷方法（自动使用环境变量） ====================
+
+    /**
+     * 创建用户 token（快捷方法）
+     */
+    static create(payload: JwtPayload): string {
+        return this.sign(payload);
+    }
+
+    /**
+     * 检查 token（快捷方法）
+     */
+    static check(token: string): JwtPayload {
+        return this.verify(token);
+    }
+
+    /**
+     * 解析 token（快捷方法，不验证签名）
+     */
+    static parse(token: string): JwtPayload {
+        return this.decode(token);
+    }
 
     /**
      * 签名用户认证 token
      */
-    static signUserToken(userInfo: JwtPayload, options: JwtSignOptions = {}): string {
+    static signUserToken(userInfo: JwtPayload, options?: JwtSignOptions): string {
         return this.sign(userInfo, options);
     }
 
     /**
      * 签名 API 访问 token
      */
-    static signAPIToken(payload: JwtPayload, options: JwtSignOptions = {}): string {
+    static signAPIToken(payload: JwtPayload, options?: JwtSignOptions): string {
         return this.sign(payload, { audience: 'api', expiresIn: '1h', ...options });
     }
 
     /**
      * 签名刷新 token
      */
-    static signRefreshToken(payload: JwtPayload, options: JwtSignOptions = {}): string {
+    static signRefreshToken(payload: JwtPayload, options?: JwtSignOptions): string {
         return this.sign(payload, { audience: 'refresh', expiresIn: '30d', ...options });
     }
 
     /**
      * 签名临时 token (用于重置密码等)
      */
-    static signTempToken(payload: JwtPayload, options: JwtSignOptions = {}): string {
+    static signTempToken(payload: JwtPayload, options?: JwtSignOptions): string {
         return this.sign(payload, { audience: 'temporary', expiresIn: '15m', ...options });
     }
 
     /**
      * 验证用户认证 token
      */
-    static verifyUserToken(token: string, options: JwtVerifyOptions = {}): JwtPayload {
+    static verifyUserToken(token: string, options?: JwtVerifyOptions): JwtPayload {
         return this.verify(token, options);
     }
 
     /**
      * 验证 API 访问 token
      */
-    static verifyAPIToken(token: string, options: JwtVerifyOptions = {}): JwtPayload {
+    static verifyAPIToken(token: string, options?: JwtVerifyOptions): JwtPayload {
         return this.verify(token, { audience: 'api', ...options });
     }
 
     /**
      * 验证刷新 token
      */
-    static verifyRefreshToken(token: string, options: JwtVerifyOptions = {}): JwtPayload {
+    static verifyRefreshToken(token: string, options?: JwtVerifyOptions): JwtPayload {
         return this.verify(token, { audience: 'refresh', ...options });
     }
 
     /**
      * 验证临时 token
      */
-    static verifyTempToken(token: string, options: JwtVerifyOptions = {}): JwtPayload {
+    static verifyTempToken(token: string, options?: JwtVerifyOptions): JwtPayload {
         return this.verify(token, { audience: 'temporary', ...options });
     }
 
     /**
      * 验证 token 并检查权限
      */
-    static verifyWithPermissions(token: string, requiredPermissions: string | string[], options: JwtVerifyOptions = {}): JwtPayload {
+    static verifyWithPermissions(token: string, requiredPermissions: string | string[], options?: JwtVerifyOptions): JwtPayload {
         const payload = this.verify(token, options);
 
         if (!payload.permissions) {
@@ -379,7 +438,7 @@ export class Jwt {
     /**
      * 验证 token 并检查角色
      */
-    static verifyWithRoles(token: string, requiredRoles: string | string[], options: JwtVerifyOptions = {}): JwtPayload {
+    static verifyWithRoles(token: string, requiredRoles: string | string[], options?: JwtVerifyOptions): JwtPayload {
         const payload = this.verify(token, options);
 
         if (!payload.role && !payload.roles) {
@@ -401,93 +460,7 @@ export class Jwt {
     /**
      * 软验证 token (忽略过期时间)
      */
-    static verifySoft(token: string, options: JwtVerifyOptions = {}): JwtPayload {
+    static verifySoft(token: string, options?: JwtVerifyOptions): JwtPayload {
         return this.verify(token, { ignoreExpiration: true, ...options });
     }
-
-    /**
-     * 检查 token 是否即将过期
-     * @param token - JWT token字符串
-     * @param thresholdSeconds - 过期阈值(秒)，默认300秒(5分钟)
-     * @returns 是否即将过期
-     */
-    static isNearExpiry(token: string, thresholdSeconds: number = 300): boolean {
-        const timeToExpiry = this.getTimeToExpiry(token);
-        return timeToExpiry > 0 && timeToExpiry <= thresholdSeconds;
-    }
-
-    // ==================== 便捷静态方法 ====================
-
-    /**
-     * 创建 token（使用默认配置）
-     * @param payload - 载荷数据
-     * @returns JWT token字符串
-     */
-    static create(payload: JwtPayload): string {
-        return this.sign(payload, Env.JWT_SECRET, Env.JWT_EXPIRES_IN || '7d');
-    }
-
-    /**
-     * 验证 token（使用默认配置）
-     * @param token - JWT token字符串
-     * @returns 解码后的载荷数据
-     */
-    static check(token: string): JwtPayload {
-        return this.verify(token, { secret: Env.JWT_SECRET });
-    }
-
-    /**
-     * 解析 token（不验证签名，使用 decode）
-     * @param token - JWT token字符串
-     * @returns 解码后的载荷数据
-     */
-    static parse(token: string): JwtPayload {
-        return this.decode(token);
-    }
-
-    /**
-     * 检查载荷是否包含特定角色
-     * @param payload - JWT载荷
-     * @param role - 要检查的角色
-     * @returns 是否包含该角色
-     */
-    static hasRole(payload: JwtPayload, role: string): boolean {
-        if (!payload) return false;
-        if (payload.role === role) return true;
-        if (Array.isArray(payload.roles) && payload.roles.includes(role)) return true;
-        return false;
-    }
-
-    /**
-     * 检查载荷是否包含任意一个角色
-     * @param payload - JWT载荷
-     * @param roles - 要检查的角色列表
-     * @returns 是否包含任意一个角色
-     */
-    static hasAnyRole(payload: JwtPayload, roles: string[]): boolean {
-        if (!payload) return false;
-        return roles.some((role) => this.hasRole(payload, role));
-    }
-
-    /**
-     * 检查载荷是否包含特定权限
-     * @param payload - JWT载荷
-     * @param permission - 要检查的权限
-     * @returns 是否包含该权限
-     */
-    static hasPermission(payload: JwtPayload, permission: string): boolean {
-        if (!payload || !payload.permissions) return false;
-        return Array.isArray(payload.permissions) && payload.permissions.includes(permission);
-    }
-
-    /**
-     * 检查载荷是否包含所有权限
-     * @param payload - JWT载荷
-     * @param permissions - 要检查的权限列表
-     * @returns 是否包含所有权限
-     */
-    static hasAllPermissions(payload: JwtPayload, permissions: string[]): boolean {
-        if (!payload || !payload.permissions) return false;
-        return permissions.every((permission) => this.hasPermission(payload, permission));
-    }
 }

package/{utils → lib}/logger.ts

@@ -1,12 +1,11 @@
 /**
- * 日志系统 - TypeScript 版本
- * 提供分级日志记录和文件管理功能
+ * 日志系统 - Befly 项目专用
+ * 直接集成环境变量，提供开箱即用的日志功能
  */
 
-import path from 'path';
+import { join } from 'pathe';
 import { appendFile, stat } from 'node:fs/promises';
-import { formatDate } from './index.js';
-import { Colors } from './colors.js';
+import chalk from 'chalk';
 import { Env } from '../config/env.js';
 import type { LogLevel } from '../types/common.js';
 
@@ -15,15 +14,31 @@ import type { LogLevel } from '../types/common.js';
  */
 type LogMessage = string | number | boolean | null | undefined | Record<string, any> | any[];
 
+/**
+ * 格式化日期时间
+ */
+function formatDate(): string {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const hours = String(now.getHours()).padStart(2, '0');
+    const minutes = String(now.getMinutes()).padStart(2, '0');
+    const seconds = String(now.getSeconds()).padStart(2, '0');
+    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
 /**
  * 日志器类
  */
 export class Logger {
-    /** 日志目录 */
-    static logDir: string = Env.LOG_DIR || 'logs';
-
-    /** 单个日志文件最大大小（字节） */
-    static maxFileSize: number = Env.LOG_MAX_SIZE || 50 * 1024 * 1024; // 50MB
+    /** 日志配置（直接使用 Env） */
+    private static readonly config = {
+        logDir: Env.LOG_DIR || 'logs',
+        maxFileSize: Env.LOG_MAX_SIZE || 50 * 1024 * 1024,
+        enableDebug: Env.LOG_DEBUG === 1,
+        toConsole: Env.LOG_TO_CONSOLE === 1
+    };
 
     /** 当前使用的日志文件缓存 */
     private static currentFiles: Map<string, string> = new Map();
@@ -34,16 +49,16 @@ export class Logger {
      * @param message - 日志消息
      */
     static async log(level: LogLevel, message: LogMessage): Promise<void> {
-        // debug 日志特殊处理：仅当 LOG_DEBUG=1 时才记录
-        if (level === 'debug' && Env.LOG_DEBUG !== 1) return;
+        // debug 日志特殊处理：仅当 enableDebug 为 true 时才记录
+        if (level === 'debug' && !this.config.enableDebug) return;
 
         // 格式化消息
         const timestamp = formatDate();
         const colorMap = {
-            info: Colors.greenBright,
-            debug: Colors.cyanBright,
-            warn: Colors.yellowBright,
-            error: Colors.redBright
+            info: chalk.greenBright,
+            debug: chalk.cyanBright,
+            warn: chalk.yellowBright,
+            error: chalk.redBright
         };
 
         // 处理消息内容
@@ -59,7 +74,7 @@ export class Logger {
         const coloredMessage = `[${timestamp}] ${coloredLevelStr} - ${content}`;
 
         // 控制台输出
-        if (Env.LOG_TO_CONSOLE === 1) {
+        if (this.config.toConsole) {
             console.log(coloredMessage);
         }
 
@@ -69,6 +84,14 @@ export class Logger {
         await this.writeToFile(plainMessage, level);
     }
 
+    /**
+     * 记录成功日志（使用 info 级别）
+     * @param message - 日志消息
+     */
+    static async success(message: LogMessage): Promise<void> {
+        await this.log('info', message);
+    }
+
     /**
      * 写入日志文件
      * @param message - 格式化后的消息
@@ -85,7 +108,7 @@ export class Logger {
             if (currentLogFile) {
                 try {
                     const stats = await stat(currentLogFile);
-                    if (stats.size >= this.maxFileSize) {
+                    if (stats.size >= this.config.maxFileSize) {
                         this.currentFiles.delete(prefix);
                         currentLogFile = undefined;
                     }
@@ -98,7 +121,7 @@ export class Logger {
             // 查找或创建新文件
             if (!currentLogFile) {
                 const glob = new Bun.Glob(`${prefix}.*.log`);
-                const files = await Array.fromAsync(glob.scan(this.logDir));
+                const files = await Array.fromAsync(glob.scan(this.config.logDir));
 
                 // 按索引排序并查找可用文件
                 const getIndex = (f: string) => parseInt(f.match(/\.(\d+)\.log$/)?.[1] || '0');
@@ -106,10 +129,10 @@ export class Logger {
 
                 let foundFile = false;
                 for (let i = files.length - 1; i >= 0; i--) {
-                    const filePath = path.join(this.logDir, files[i]);
+                    const filePath = join(this.config.logDir, files[i]);
                     try {
                         const stats = await stat(filePath);
-                        if (stats.size < this.maxFileSize) {
+                        if (stats.size < this.config.maxFileSize) {
                             currentLogFile = filePath;
                             foundFile = true;
                             break;
@@ -119,10 +142,10 @@ export class Logger {
                     }
                 }
 
-                // 没有可用文件，创建新文件
+                // 没有可用文件,创建新文件
                 if (!foundFile) {
                     const maxIndex = files.length > 0 ? Math.max(...files.map(getIndex)) : -1;
-                    currentLogFile = path.join(this.logDir, `${prefix}.${maxIndex + 1}.log`);
+                    currentLogFile = join(this.config.logDir, `${prefix}.${maxIndex + 1}.log`);
                 }
 
                 this.currentFiles.set(prefix, currentLogFile);
@@ -175,7 +198,7 @@ export class Logger {
 
     /**
      * 记录调试日志
-     * 受 LOG_DEBUG 环境变量控制，仅当 LOG_DEBUG=1 时才记录
+     * 受 enableDebug 配置控制，仅当 enableDebug=true 时才记录
      * @param message - 日志消息
      */
     static async debug(message: LogMessage): Promise<void> {