@dangao/bun-server 1.7.1 → 1.8.0

package/src/security/guards/builtin/roles-guard.ts

@@ -0,0 +1,165 @@
+import { Injectable, Inject } from '../../../di/decorators';
+import type { CanActivate, ExecutionContext } from '../types';
+import { ROLES_METADATA_KEY } from '../types';
+import { SecurityContextHolder } from '../../context';
+import { ForbiddenException } from '../../../error/http-exception';
+import { ErrorCode } from '../../../error/error-codes';
+import { Reflector, REFLECTOR_TOKEN } from '../reflector';
+
+/**
+ * 角色守卫
+ * 检查用户是否具有所需角色
+ * 
+ * @example
+ * @Controller('/api/admin')
+ * @UseGuards(AuthGuard, RolesGuard)
+ * class AdminController {
+ *   @GET('/dashboard')
+ *   @Roles('admin')
+ *   dashboard() {
+ *     // 只有 admin 角色才能访问
+ *   }
+ * 
+ *   @GET('/super')
+ *   @Roles('admin', 'superadmin')
+ *   superAdmin() {
+ *     // admin 或 superadmin 角色可以访问
+ *   }
+ * }
+ */
+@Injectable()
+export class RolesGuard implements CanActivate {
+  private readonly reflector: Reflector;
+
+  public constructor(
+    @Inject(REFLECTOR_TOKEN) reflector?: Reflector,
+  ) {
+    this.reflector = reflector || new Reflector();
+  }
+
+  /**
+   * 判断是否允许访问
+   * @param context - 执行上下文
+   * @returns 如果用户具有所需角色则返回 true
+   */
+  public canActivate(context: ExecutionContext): boolean {
+    // 获取方法和类上定义的角色
+    const requiredRoles = this.reflector.getAllAndMerge<string[]>(
+      ROLES_METADATA_KEY,
+      context.getClass(),
+      context.getMethodName(),
+    );
+
+    // 如果没有定义角色要求，则允许访问
+    if (!requiredRoles || requiredRoles.length === 0) {
+      return true;
+    }
+
+    // 获取当前用户的角色
+    const securityContext = SecurityContextHolder.getContext();
+    const authentication = securityContext.authentication;
+
+    if (!authentication || !authentication.authenticated) {
+      throw new ForbiddenException(
+        'Access denied: authentication required for role check',
+        { requiredRoles },
+        ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+      );
+    }
+
+    const userRoles = authentication.authorities || [];
+
+    // 检查用户是否具有任一所需角色
+    const hasRole = requiredRoles.some((role) => userRoles.includes(role));
+
+    if (!hasRole) {
+      throw new ForbiddenException(
+        `Access denied: required roles [${requiredRoles.join(', ')}], but user has [${userRoles.join(', ')}]`,
+        { requiredRoles, userRoles },
+        ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+      );
+    }
+
+    return true;
+  }
+}
+
+/**
+ * 创建自定义角色守卫
+ * 支持自定义角色验证逻辑
+ * 
+ * @example
+ * const CustomRolesGuard = createRolesGuard({
+ *   // 所有角色都必须匹配
+ *   matchAll: true,
+ *   // 自定义角色获取逻辑
+ *   getRoles: (context) => {
+ *     const user = context.switchToHttp().getRequest().auth?.user;
+ *     return user?.roles || [];
+ *   },
+ * });
+ */
+export interface RolesGuardOptions {
+  /**
+   * 是否需要匹配所有角色
+   * @default false (只需匹配其中一个)
+   */
+  matchAll?: boolean;
+
+  /**
+   * 自定义获取用户角色的函数
+   */
+  getRoles?: (context: ExecutionContext) => string[];
+}
+
+/**
+ * 创建自定义角色守卫工厂
+ * @param options - 配置选项
+ * @returns 自定义角色守卫类
+ */
+export function createRolesGuard(options: RolesGuardOptions = {}): new () => CanActivate {
+  const { matchAll = false, getRoles } = options;
+
+  @Injectable()
+  class CustomRolesGuard implements CanActivate {
+    private readonly reflector = new Reflector();
+
+    public canActivate(context: ExecutionContext): boolean {
+      const requiredRoles = this.reflector.getAllAndMerge<string[]>(
+        ROLES_METADATA_KEY,
+        context.getClass(),
+        context.getMethodName(),
+      );
+
+      if (!requiredRoles || requiredRoles.length === 0) {
+        return true;
+      }
+
+      let userRoles: string[];
+
+      if (getRoles) {
+        userRoles = getRoles(context);
+      } else {
+        const securityContext = SecurityContextHolder.getContext();
+        userRoles = securityContext.authentication?.authorities || [];
+      }
+
+      const hasRole = matchAll
+        ? requiredRoles.every((role) => userRoles.includes(role))
+        : requiredRoles.some((role) => userRoles.includes(role));
+
+      if (!hasRole) {
+        throw new ForbiddenException(
+          `Access denied: required roles [${requiredRoles.join(', ')}], user has [${userRoles.join(', ')}]`,
+          { requiredRoles, userRoles, matchAll },
+          ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+        );
+      }
+
+      return true;
+    }
+  }
+
+  return CustomRolesGuard;
+}
+

package/src/security/guards/decorators.ts

@@ -0,0 +1,124 @@
+import 'reflect-metadata';
+import type { GuardType } from './types';
+import { GUARDS_METADATA_KEY, ROLES_METADATA_KEY } from './types';
+
+/**
+ * 守卫装饰器
+ * 可用于控制器或方法级别
+ * 
+ * @example
+ * // 控制器级别
+ * @Controller('/api/admin')
+ * @UseGuards(AuthGuard, RolesGuard)
+ * class AdminController {}
+ * 
+ * @example
+ * // 方法级别
+ * @GET('/profile')
+ * @UseGuards(AuthGuard)
+ * getProfile() {}
+ * 
+ * @param guards - 守卫类或守卫实例
+ * @returns 类或方法装饰器
+ */
+export function UseGuards(
+  ...guards: GuardType[]
+): ClassDecorator & MethodDecorator {
+  return (
+    target: Object | Function,
+    propertyKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ) => {
+    if (propertyKey !== undefined) {
+      // 方法装饰器
+      const existingGuards: GuardType[] =
+        Reflect.getMetadata(GUARDS_METADATA_KEY, target, propertyKey) || [];
+      Reflect.defineMetadata(
+        GUARDS_METADATA_KEY,
+        [...existingGuards, ...guards],
+        target,
+        propertyKey,
+      );
+    } else {
+      // 类装饰器
+      const existingGuards: GuardType[] =
+        Reflect.getMetadata(GUARDS_METADATA_KEY, target) || [];
+      Reflect.defineMetadata(
+        GUARDS_METADATA_KEY,
+        [...existingGuards, ...guards],
+        target,
+      );
+    }
+  };
+}
+
+/**
+ * 角色装饰器
+ * 用于标记需要特定角色的方法或控制器
+ * 
+ * @example
+ * @GET('/admin')
+ * @Roles('admin', 'superadmin')
+ * adminOnly() {}
+ * 
+ * @param roles - 允许访问的角色列表
+ * @returns 类或方法装饰器
+ */
+export function Roles(
+  ...roles: string[]
+): ClassDecorator & MethodDecorator {
+  return (
+    target: Object | Function,
+    propertyKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ) => {
+    if (propertyKey !== undefined) {
+      // 方法装饰器
+      Reflect.defineMetadata(ROLES_METADATA_KEY, roles, target, propertyKey);
+    } else {
+      // 类装饰器
+      Reflect.defineMetadata(ROLES_METADATA_KEY, roles, target);
+    }
+  };
+}
+
+/**
+ * 获取守卫元数据
+ * @param target - 目标对象（类或原型）
+ * @param propertyKey - 方法名（可选）
+ * @returns 守卫列表
+ */
+export function getGuardsMetadata(
+  target: Object | Function,
+  propertyKey?: string | symbol,
+): GuardType[] {
+  // 安全检查：确保 target 是有效的对象或函数
+  if (target === null || target === undefined) {
+    return [];
+  }
+  if (typeof target !== 'object' && typeof target !== 'function') {
+    return [];
+  }
+
+  if (propertyKey !== undefined) {
+    return Reflect.getMetadata(GUARDS_METADATA_KEY, target, propertyKey) || [];
+  }
+  return Reflect.getMetadata(GUARDS_METADATA_KEY, target) || [];
+}
+
+/**
+ * 获取角色元数据
+ * @param target - 目标对象（类或原型）
+ * @param propertyKey - 方法名（可选）
+ * @returns 角色列表
+ */
+export function getRolesMetadata(
+  target: Object | Function,
+  propertyKey?: string | symbol,
+): string[] {
+  if (propertyKey !== undefined) {
+    return Reflect.getMetadata(ROLES_METADATA_KEY, target, propertyKey) || [];
+  }
+  return Reflect.getMetadata(ROLES_METADATA_KEY, target) || [];
+}
+

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');
+