@dangao/bun-server 1.7.0 → 1.8.0

package/src/security/guards/execution-context.ts

@@ -0,0 +1,152 @@
+import 'reflect-metadata';
+import type { ServerWebSocket } from 'bun';
+import type { Context } from '../../core/context';
+import type { ResponseBuilder } from '../../request/response';
+import type { Constructor } from '../../core/types';
+import type {
+  ExecutionContext,
+  HttpArgumentsHost,
+  WsArgumentsHost,
+} from './types';
+
+/**
+ * HTTP 参数主机实现
+ */
+class HttpArgumentsHostImpl implements HttpArgumentsHost {
+  public constructor(
+    private readonly ctx: Context,
+    private readonly responseBuilder?: ResponseBuilder,
+  ) {}
+
+  /**
+   * 获取请求上下文
+   */
+  public getRequest(): Context {
+    return this.ctx;
+  }
+
+  /**
+   * 获取响应构建器
+   */
+  public getResponse(): ResponseBuilder | undefined {
+    return this.responseBuilder;
+  }
+}
+
+/**
+ * WebSocket 参数主机实现
+ */
+class WsArgumentsHostImpl implements WsArgumentsHost {
+  public constructor(
+    private readonly client: ServerWebSocket<unknown>,
+    private readonly data: unknown,
+  ) {}
+
+  /**
+   * 获取 WebSocket 客户端
+   */
+  public getClient(): ServerWebSocket<unknown> {
+    return this.client;
+  }
+
+  /**
+   * 获取消息数据
+   */
+  public getData(): unknown {
+    return this.data;
+  }
+}
+
+/**
+ * 执行上下文实现
+ */
+export class ExecutionContextImpl implements ExecutionContext {
+  private readonly httpHost: HttpArgumentsHost;
+  private wsHost?: WsArgumentsHost;
+
+  public constructor(
+    private readonly ctx: Context,
+    private readonly controllerClass: Constructor<unknown>,
+    private readonly methodName: string,
+    private readonly handler: Function,
+    private readonly args: unknown[] = [],
+    responseBuilder?: ResponseBuilder,
+  ) {
+    this.httpHost = new HttpArgumentsHostImpl(ctx, responseBuilder);
+  }
+
+  /**
+   * 设置 WebSocket 上下文
+   * @param client - WebSocket 客户端
+   * @param data - 消息数据
+   */
+  public setWsContext(client: ServerWebSocket<unknown>, data: unknown): void {
+    this.wsHost = new WsArgumentsHostImpl(client, data);
+  }
+
+  /**
+   * 获取 HTTP 上下文
+   */
+  public switchToHttp(): HttpArgumentsHost {
+    return this.httpHost;
+  }
+
+  /**
+   * 获取 WebSocket 上下文
+   */
+  public switchToWs(): WsArgumentsHost {
+    if (!this.wsHost) {
+      throw new Error('WebSocket context is not available');
+    }
+    return this.wsHost;
+  }
+
+  /**
+   * 获取当前处理的控制器类
+   */
+  public getClass(): Constructor<unknown> {
+    return this.controllerClass;
+  }
+
+  /**
+   * 获取当前处理的方法
+   */
+  public getHandler(): Function {
+    return this.handler;
+  }
+
+  /**
+   * 获取方法名
+   */
+  public getMethodName(): string {
+    return this.methodName;
+  }
+
+  /**
+   * 获取方法或类的元数据
+   * @param key - 元数据键
+   * @returns 元数据值
+   */
+  public getMetadata<T>(key: string | symbol): T | undefined {
+    // 先尝试从方法获取
+    const methodMetadata = Reflect.getMetadata(
+      key,
+      this.controllerClass.prototype,
+      this.methodName,
+    );
+    if (methodMetadata !== undefined) {
+      return methodMetadata as T;
+    }
+
+    // 如果方法没有，尝试从类获取
+    return Reflect.getMetadata(key, this.controllerClass) as T | undefined;
+  }
+
+  /**
+   * 获取请求参数
+   */
+  public getArgs(): unknown[] {
+    return this.args;
+  }
+}
+

package/src/security/guards/guard-registry.ts

@@ -0,0 +1,164 @@
+import type { Container } from '../../di/container';
+import type { Constructor } from '../../core/types';
+import type {
+  CanActivate,
+  GuardType,
+  ExecutionContext,
+} from './types';
+import { getGuardsMetadata } from './decorators';
+import { ForbiddenException } from '../../error/http-exception';
+import { ErrorCode } from '../../error/error-codes';
+
+/**
+ * 守卫注册表
+ * 管理全局守卫和执行守卫链
+ */
+export class GuardRegistry {
+  /**
+   * 全局守卫列表
+   */
+  private globalGuards: GuardType[] = [];
+
+  /**
+   * 守卫实例缓存（用于缓存从 DI 容器解析的守卫实例）
+   */
+  private guardInstances = new Map<Constructor<CanActivate>, CanActivate>();
+
+  /**
+   * 注册全局守卫
+   * @param guards - 守卫类或实例
+   */
+  public addGlobalGuards(...guards: GuardType[]): void {
+    this.globalGuards.push(...guards);
+  }
+
+  /**
+   * 获取全局守卫
+   * @returns 全局守卫列表
+   */
+  public getGlobalGuards(): GuardType[] {
+    return [...this.globalGuards];
+  }
+
+  /**
+   * 清除所有全局守卫
+   */
+  public clearGlobalGuards(): void {
+    this.globalGuards = [];
+    this.guardInstances.clear();
+  }
+
+  /**
+   * 解析守卫实例
+   * @param guard - 守卫类或实例
+   * @param container - DI 容器
+   * @returns 守卫实例
+   */
+  private resolveGuard(guard: GuardType, container: Container): CanActivate {
+    // 如果已经是实例，直接返回
+    if (typeof guard !== 'function') {
+      return guard;
+    }
+
+    // 检查缓存
+    const cached = this.guardInstances.get(guard as Constructor<CanActivate>);
+    if (cached) {
+      return cached;
+    }
+
+    // 尝试从 DI 容器解析
+    try {
+      if (container.isRegistered(guard)) {
+        const instance = container.resolve<CanActivate>(guard);
+        this.guardInstances.set(guard as Constructor<CanActivate>, instance);
+        return instance;
+      }
+    } catch {
+      // 如果容器解析失败，继续尝试手动实例化
+    }
+
+    // 手动实例化（不支持依赖注入）
+    const GuardClass = guard as Constructor<CanActivate>;
+    const instance = new GuardClass();
+    this.guardInstances.set(guard as Constructor<CanActivate>, instance);
+    return instance;
+  }
+
+  /**
+   * 获取控制器级别的守卫
+   * @param controllerClass - 控制器类
+   * @returns 守卫列表
+   */
+  public getControllerGuards(controllerClass: Constructor<unknown>): GuardType[] {
+    return getGuardsMetadata(controllerClass);
+  }
+
+  /**
+   * 获取方法级别的守卫
+   * @param controllerClass - 控制器类
+   * @param methodName - 方法名
+   * @returns 守卫列表
+   */
+  public getMethodGuards(
+    controllerClass: Constructor<unknown>,
+    methodName: string,
+  ): GuardType[] {
+    return getGuardsMetadata(controllerClass.prototype, methodName);
+  }
+
+  /**
+   * 收集所有守卫（全局 + 控制器 + 方法）
+   * @param controllerClass - 控制器类
+   * @param methodName - 方法名
+   * @returns 按顺序排列的守卫列表
+   */
+  public collectGuards(
+    controllerClass: Constructor<unknown>,
+    methodName: string,
+  ): GuardType[] {
+    const globalGuards = this.getGlobalGuards();
+    const controllerGuards = this.getControllerGuards(controllerClass);
+    const methodGuards = this.getMethodGuards(controllerClass, methodName);
+
+    // 执行顺序：全局 -> 控制器 -> 方法
+    return [...globalGuards, ...controllerGuards, ...methodGuards];
+  }
+
+  /**
+   * 执行守卫链
+   * @param context - 执行上下文
+   * @param container - DI 容器
+   * @returns 是否允许访问
+   * @throws ForbiddenException 如果守卫拒绝访问
+   */
+  public async executeGuards(
+    context: ExecutionContext,
+    container: Container,
+  ): Promise<boolean> {
+    const controllerClass = context.getClass();
+    const methodName = context.getMethodName();
+    const guards = this.collectGuards(controllerClass, methodName);
+
+    if (guards.length === 0) {
+      return true;
+    }
+
+    for (const guard of guards) {
+      const guardInstance = this.resolveGuard(guard, container);
+      const result = await guardInstance.canActivate(context);
+
+      if (!result) {
+        // 获取守卫名称用于错误消息
+        const guardName = typeof guard === 'function' ? guard.name : guard.constructor.name;
+        throw new ForbiddenException(
+          `Access denied by guard: ${guardName}`,
+          { guard: guardName },
+          ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+        );
+      }
+    }
+
+    return true;
+  }
+}
+

package/src/security/guards/index.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './decorators';
+export * from './execution-context';
+export * from './guard-registry';
+export * from './reflector';
+export * from './builtin';
+

package/src/security/guards/reflector.ts

@@ -0,0 +1,99 @@
+import 'reflect-metadata';
+import type { Constructor } from '../../core/types';
+
+/**
+ * Reflector 工具类
+ * 用于获取类和方法的元数据
+ */
+export class Reflector {
+  /**
+   * 获取元数据
+   * 优先从方法获取，如果方法没有则从类获取
+   * 
+   * @param metadataKey - 元数据键
+   * @param target - 目标类或方法
+   * @returns 元数据值
+   */
+  public get<T>(
+    metadataKey: string | symbol,
+    target: Function | Object,
+  ): T | undefined {
+    return Reflect.getMetadata(metadataKey, target) as T | undefined;
+  }
+
+  /**
+   * 从类获取元数据
+   * @param metadataKey - 元数据键
+   * @param target - 目标类
+   * @returns 元数据值
+   */
+  public getFromClass<T>(
+    metadataKey: string | symbol,
+    target: Constructor<unknown>,
+  ): T | undefined {
+    return Reflect.getMetadata(metadataKey, target) as T | undefined;
+  }
+
+  /**
+   * 从方法获取元数据
+   * @param metadataKey - 元数据键
+   * @param target - 目标类原型
+   * @param propertyKey - 方法名
+   * @returns 元数据值
+   */
+  public getFromMethod<T>(
+    metadataKey: string | symbol,
+    target: Object,
+    propertyKey: string | symbol,
+  ): T | undefined {
+    return Reflect.getMetadata(metadataKey, target, propertyKey) as T | undefined;
+  }
+
+  /**
+   * 获取元数据（支持合并类和方法的元数据）
+   * 对于数组类型，将类和方法的元数据合并
+   * 
+   * @param metadataKey - 元数据键
+   * @param target - 目标类
+   * @param propertyKey - 方法名
+   * @returns 合并后的元数据值
+   */
+  public getAllAndMerge<T extends unknown[]>(
+    metadataKey: string | symbol,
+    target: Constructor<unknown>,
+    propertyKey: string | symbol,
+  ): T {
+    const classMetadata = this.getFromClass<T>(metadataKey, target) || ([] as unknown as T);
+    const methodMetadata = this.getFromMethod<T>(metadataKey, target.prototype, propertyKey) || ([] as unknown as T);
+
+    // 合并数组
+    return [...classMetadata, ...methodMetadata] as T;
+  }
+
+  /**
+   * 获取元数据（方法优先）
+   * 如果方法有元数据则返回方法的，否则返回类的
+   * 
+   * @param metadataKey - 元数据键
+   * @param target - 目标类
+   * @param propertyKey - 方法名
+   * @returns 元数据值
+   */
+  public getAllAndOverride<T>(
+    metadataKey: string | symbol,
+    target: Constructor<unknown>,
+    propertyKey: string | symbol,
+  ): T | undefined {
+    const methodMetadata = this.getFromMethod<T>(metadataKey, target.prototype, propertyKey);
+    if (methodMetadata !== undefined) {
+      return methodMetadata;
+    }
+    return this.getFromClass<T>(metadataKey, target);
+  }
+}
+
+/**
+ * Reflector Token
+ */
+export const REFLECTOR_TOKEN = Symbol('@dangao/bun-server:reflector');
+

package/src/security/guards/types.ts

@@ -0,0 +1,144 @@
+import type { Context } from '../../core/context';
+import type { ResponseBuilder } from '../../request/response';
+import type { Constructor } from '../../core/types';
+import type { ServerWebSocket } from 'bun';
+
+/**
+ * 守卫接口
+ * 守卫用于决定请求是否可以继续执行
+ */
+export interface CanActivate {
+  /**
+   * 判断是否允许访问
+   * @param context - 执行上下文
+   * @returns 是否允许访问，可以是同步或异步的布尔值
+   */
+  canActivate(context: ExecutionContext): boolean | Promise<boolean>;
+}
+
+/**
+ * HTTP 参数主机接口
+ * 提供 HTTP 请求相关的上下文信息
+ */
+export interface HttpArgumentsHost {
+  /**
+   * 获取请求上下文
+   * @returns Context 对象
+   */
+  getRequest(): Context;
+
+  /**
+   * 获取响应构建器
+   * @returns ResponseBuilder 对象（可能为 undefined）
+   */
+  getResponse(): ResponseBuilder | undefined;
+}
+
+/**
+ * WebSocket 参数主机接口
+ * 提供 WebSocket 连接相关的上下文信息
+ */
+export interface WsArgumentsHost {
+  /**
+   * 获取 WebSocket 客户端
+   * @returns WebSocket 连接对象
+   */
+  getClient(): ServerWebSocket<unknown>;
+
+  /**
+   * 获取消息数据
+   * @returns 消息数据
+   */
+  getData(): unknown;
+}
+
+/**
+ * 执行上下文接口
+ * 提供请求处理过程中的上下文信息
+ */
+export interface ExecutionContext {
+  /**
+   * 获取 HTTP 上下文
+   * @returns HTTP 参数主机
+   */
+  switchToHttp(): HttpArgumentsHost;
+
+  /**
+   * 获取 WebSocket 上下文
+   * @returns WebSocket 参数主机
+   */
+  switchToWs(): WsArgumentsHost;
+
+  /**
+   * 获取当前处理的控制器类
+   * @returns 控制器类构造函数
+   */
+  getClass(): Constructor<unknown>;
+
+  /**
+   * 获取当前处理的方法
+   * @returns 方法函数
+   */
+  getHandler(): Function;
+
+  /**
+   * 获取方法名
+   * @returns 方法名字符串
+   */
+  getMethodName(): string;
+
+  /**
+   * 获取方法或类的元数据
+   * @param key - 元数据键
+   * @returns 元数据值，如果不存在则返回 undefined
+   */
+  getMetadata<T>(key: string | symbol): T | undefined;
+
+  /**
+   * 获取请求参数
+   * @returns 请求参数数组
+   */
+  getArgs(): unknown[];
+}
+
+/**
+ * 守卫类型：可以是守卫类构造函数或守卫实例
+ */
+export type GuardType = Constructor<CanActivate> | CanActivate;
+
+/**
+ * 守卫元数据
+ */
+export interface GuardMetadata {
+  /**
+   * 守卫列表
+   */
+  guards: GuardType[];
+}
+
+/**
+ * 守卫配置选项
+ */
+export interface GuardOptions {
+  /**
+   * 是否跳过全局守卫
+   * @default false
+   */
+  skipGlobalGuards?: boolean;
+}
+
+/**
+ * 守卫元数据键
+ */
+export const GUARDS_METADATA_KEY = Symbol('@dangao/bun-server:guards');
+
+/**
+ * 守卫注册表 Token
+ */
+export const GUARD_REGISTRY_TOKEN = Symbol('@dangao/bun-server:guard-registry');
+
+/**
+ * Roles 元数据键
+ */
+export const ROLES_METADATA_KEY = Symbol('@dangao/bun-server:roles');
+

package/src/security/index.ts

@@ -5,4 +5,5 @@ export * from './access-decision-manager';
 export * from './filter';
 export * from './providers';
 export * from './security-module';
+export * from './guards';
 

package/src/security/security-module.ts

@@ -2,11 +2,15 @@ import { Module, MODULE_METADATA_KEY } from '../di/module';
 import { AuthenticationManager } from './authentication-manager';
 import { JwtAuthenticationProvider } from './providers/jwt-provider';
 import { OAuth2AuthenticationProvider } from './providers/oauth2-provider';
-import { createSecurityFilter } from './filter';
+import { createSecurityFilter, getGuardRegistry, registerReflector } from './filter';
 import { JWTUtil } from '../auth/jwt';
 import { OAuth2Service } from '../auth/oauth2';
 import { OAuth2Controller, OAUTH2_SERVICE_TOKEN, JWT_UTIL_TOKEN } from '../auth/controller';
 import type { JWTConfig, OAuth2Client, UserInfo } from '../auth/types';
+import type { GuardType } from './guards/types';
+import { GUARD_REGISTRY_TOKEN } from './guards/types';
+import { GuardRegistry } from './guards/guard-registry';
+import { Reflector, REFLECTOR_TOKEN } from './guards/reflector';
 
 /**
  * 安全模块配置
@@ -45,8 +49,17 @@ export interface SecurityModuleConfig {
    * @default false
    */
   defaultAuthRequired?: boolean;
+  /**
+   * 全局守卫列表
+   */
+  globalGuards?: GuardType[];
 }
 
+/**
+ * 内部存储：容器引用和守卫注册表
+ */
+let _guardRegistry: GuardRegistry | null = null;
+
 /**
  * 安全模块
  */
@@ -82,7 +95,23 @@ export class SecurityModule {
       new OAuth2AuthenticationProvider(oauth2Service, jwtUtil),
     );
 
-    // 创建安全过滤器
+    // 创建守卫注册表（每次 forRoot 都创建新实例，避免测试间污染）
+    const guardRegistry = new GuardRegistry();
+    // 清理旧的 registry（如果存在）
+    if (_guardRegistry) {
+      _guardRegistry.clearGlobalGuards();
+    }
+    _guardRegistry = guardRegistry;
+
+    // 添加全局守卫
+    if (config.globalGuards && config.globalGuards.length > 0) {
+      guardRegistry.addGlobalGuards(...config.globalGuards);
+    }
+
+    // 创建 Reflector
+    const reflector = new Reflector();
+
+    // 创建安全过滤器（暂时不传 container，将在模块注册时更新）
     const securityFilter = createSecurityFilter({
       authenticationManager,
       excludePaths: [
@@ -92,6 +121,7 @@ export class SecurityModule {
           : []),
       ],
       defaultAuthRequired: config.defaultAuthRequired ?? false,
+      guardRegistry,
     });
 
     const controllers: any[] = [];
@@ -117,6 +147,14 @@ export class SecurityModule {
         provide: AuthenticationManager,
         useValue: authenticationManager,
       },
+      {
+        provide: GUARD_REGISTRY_TOKEN,
+        useValue: guardRegistry,
+      },
+      {
+        provide: REFLECTOR_TOKEN,
+        useValue: reflector,
+      },
     );
 
     // 添加安全过滤器中间件
@@ -135,11 +173,43 @@ export class SecurityModule {
         JWT_UTIL_TOKEN,
         OAUTH2_SERVICE_TOKEN,
         AuthenticationManager,
+        GUARD_REGISTRY_TOKEN,
+        REFLECTOR_TOKEN,
       ],
     };
     Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, SecurityModule);
 
     return SecurityModule;
   }
+
+  /**
+   * 获取守卫注册表
+   * @returns 守卫注册表实例
+   */
+  public static getGuardRegistry(): GuardRegistry | null {
+    return _guardRegistry;
+  }
+
+  /**
+   * 添加全局守卫
+   * @param guards - 守卫类或实例
+   */
+  public static addGlobalGuards(...guards: GuardType[]): void {
+    if (_guardRegistry) {
+      _guardRegistry.addGlobalGuards(...guards);
+    }
+  }
+
+  /**
+   * 重置模块状态（主要用于测试）
+   */
+  public static reset(): void {
+    if (_guardRegistry) {
+      _guardRegistry.clearGlobalGuards();
+    }
+    _guardRegistry = null;
+    // 清除模块元数据
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, SecurityModule);
+  }
 }