@dangao/bun-server 1.7.1 → 1.8.0

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

package/src/validation/class-validator.ts

@@ -0,0 +1,322 @@
+import 'reflect-metadata';
+import type { ValidationRuleDefinition, ClassValidationMetadata, ValidationOptions } from './types';
+import { ValidationError, type ValidationIssue } from './errors';
+
+const CLASS_VALIDATION_METADATA_KEY = Symbol('validation:class');
+const PROPERTY_VALIDATION_METADATA_KEY = Symbol('validation:property');
+const VALIDATE_CLASS_METADATA_KEY = Symbol('validation:validateClass');
+
+/**
+ * 标记类需要验证
+ * 应用此装饰器后，类的实例可以使用 validateObject 函数进行验证
+ */
+export function ValidateClass(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(VALIDATE_CLASS_METADATA_KEY, true, target);
+  };
+}
+
+/**
+ * 属性验证装饰器
+ * 用于 DTO 类的属性级别验证
+ *
+ * @example
+ * @ValidateClass()
+ * class CreateUserDto {
+ *   @Property(IsString(), MinLength(2))
+ *   name: string;
+ *
+ *   @Property(IsEmail())
+ *   email: string;
+ *
+ *   @Property(IsOptional(), IsNumber())
+ *   age?: number;
+ * }
+ */
+export function Property(...rules: ValidationRuleDefinition[]): PropertyDecorator {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'symbol') {
+      throw new Error('@Property decorator does not support symbol property keys');
+    }
+
+    // 获取或创建类级别的元数据数组
+    const existingMetadata: ClassValidationMetadata[] =
+      Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target.constructor) ?? [];
+
+    // 查找现有的属性元数据
+    let propertyMetadata = existingMetadata.find((m) => m.property === propertyKey);
+    if (!propertyMetadata) {
+      propertyMetadata = { property: propertyKey, rules: [] };
+      existingMetadata.push(propertyMetadata);
+    }
+
+    // 添加规则
+    propertyMetadata.rules.push(...rules);
+
+    // 保存元数据
+    Reflect.defineMetadata(CLASS_VALIDATION_METADATA_KEY, existingMetadata, target.constructor);
+  };
+}
+
+/**
+ * 获取类的验证元数据
+ */
+export function getClassValidationMetadata(target: new () => unknown): ClassValidationMetadata[] {
+  return Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target) ?? [];
+}
+
+/**
+ * 检查类是否标记为需要验证
+ */
+export function isValidateClass(target: new () => unknown): boolean {
+  return Reflect.getMetadata(VALIDATE_CLASS_METADATA_KEY, target) === true;
+}
+
+/**
+ * 验证单个值
+ */
+function validateValue(
+  value: unknown,
+  rules: ValidationRuleDefinition[],
+  property: string,
+  fullObject: unknown,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  let currentValue = value;
+  let shouldSkip = false;
+
+  for (const rule of rules) {
+    // 处理条件验证
+    if (rule.condition && !rule.condition(currentValue, fullObject)) {
+      shouldSkip = true;
+      break;
+    }
+
+    // 处理可选字段
+    if (rule.optional && (currentValue === undefined || currentValue === null)) {
+      shouldSkip = true;
+      break;
+    }
+
+    // 处理转换
+    if (rule.transform) {
+      currentValue = rule.transform(currentValue);
+    }
+
+    // 处理嵌套验证
+    if (rule.nested) {
+      if (rule.each && Array.isArray(currentValue)) {
+        // 数组嵌套验证
+        for (let i = 0; i < currentValue.length; i++) {
+          const item = currentValue[i];
+          if (typeof item === 'object' && item !== null && rule.nestedType) {
+            const nestedIssues = validateObjectInternal(item, rule.nestedType, `${property}[${i}]`);
+            issues.push(...nestedIssues);
+          }
+        }
+      } else if (typeof currentValue === 'object' && currentValue !== null && rule.nestedType) {
+        // 单个对象嵌套验证
+        const nestedIssues = validateObjectInternal(currentValue, rule.nestedType, property);
+        issues.push(...nestedIssues);
+      }
+      continue;
+    }
+
+    // 执行验证
+    const passed = rule.validate(currentValue, fullObject);
+    if (!passed) {
+      issues.push({
+        property,
+        rule: rule.name,
+        message: rule.message,
+        value: currentValue,
+      });
+    }
+  }
+
+  return shouldSkip ? [] : issues;
+}
+
+/**
+ * 内部验证函数
+ */
+function validateObjectInternal(
+  obj: unknown,
+  targetClass: new () => unknown,
+  prefix = '',
+): ValidationIssue[] {
+  const metadata = getClassValidationMetadata(targetClass);
+  const issues: ValidationIssue[] = [];
+
+  if (typeof obj !== 'object' || obj === null) {
+    issues.push({
+      property: prefix || 'root',
+      rule: 'isObject',
+      message: '必须是对象',
+      value: obj,
+    });
+    return issues;
+  }
+
+  const objRecord = obj as Record<string, unknown>;
+
+  for (const meta of metadata) {
+    const propertyPath = prefix ? `${prefix}.${meta.property}` : meta.property;
+    const value = objRecord[meta.property];
+    const propertyIssues = validateValue(value, meta.rules, propertyPath, obj);
+    issues.push(...propertyIssues);
+  }
+
+  return issues;
+}
+
+/**
+ * 验证对象
+ *
+ * @param obj - 要验证的对象
+ * @param targetClass - DTO 类
+ * @param options - 验证选项
+ * @throws {ValidationError} 验证失败时抛出
+ *
+ * @example
+ * @ValidateClass()
+ * class CreateUserDto {
+ *   @Property(IsString(), MinLength(2))
+ *   name: string;
+ *
+ *   @Property(IsEmail())
+ *   email: string;
+ * }
+ *
+ * const dto = { name: 'A', email: 'invalid' };
+ * validateObject(dto, CreateUserDto); // throws ValidationError
+ */
+export function validateObject<T>(
+  obj: unknown,
+  targetClass: new () => T,
+  options: ValidationOptions = {},
+): void {
+  const issues = validateObjectInternal(obj, targetClass);
+
+  if (options.stopAtFirstError && issues.length > 0) {
+    throw new ValidationError('Validation failed', [issues[0]]);
+  }
+
+  if (issues.length > 0) {
+    throw new ValidationError('Validation failed', issues);
+  }
+}
+
+/**
+ * 验证对象并返回验证结果（不抛出异常）
+ *
+ * @param obj - 要验证的对象
+ * @param targetClass - DTO 类
+ * @param options - 验证选项
+ * @returns 验证结果
+ */
+export function validateObjectSync<T>(
+  obj: unknown,
+  targetClass: new () => T,
+  options: ValidationOptions = {},
+): { valid: boolean; issues: ValidationIssue[] } {
+  const issues = validateObjectInternal(obj, targetClass);
+
+  if (options.stopAtFirstError && issues.length > 0) {
+    return { valid: false, issues: [issues[0]] };
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+/**
+ * 带嵌套类型的属性验证装饰器
+ * 用于嵌套对象验证
+ *
+ * @example
+ * @ValidateClass()
+ * class AddressDto {
+ *   @Property(IsString())
+ *   city: string;
+ * }
+ *
+ * @ValidateClass()
+ * class CreateUserDto {
+ *   @Property(IsString())
+ *   name: string;
+ *
+ *   @NestedProperty(AddressDto)
+ *   address: AddressDto;
+ * }
+ */
+export function NestedProperty<T>(nestedClass: new () => T): PropertyDecorator {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'symbol') {
+      throw new Error('@NestedProperty decorator does not support symbol property keys');
+    }
+
+    const existingMetadata: ClassValidationMetadata[] =
+      Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target.constructor) ?? [];
+
+    let propertyMetadata = existingMetadata.find((m) => m.property === propertyKey);
+    if (!propertyMetadata) {
+      propertyMetadata = { property: propertyKey, rules: [] };
+      existingMetadata.push(propertyMetadata);
+    }
+
+    propertyMetadata.rules.push({
+      name: 'validateNested',
+      message: '嵌套对象验证失败',
+      nested: true,
+      nestedType: nestedClass,
+      validate: (value) => typeof value === 'object' && value !== null && !Array.isArray(value),
+    });
+
+    Reflect.defineMetadata(CLASS_VALIDATION_METADATA_KEY, existingMetadata, target.constructor);
+  };
+}
+
+/**
+ * 数组嵌套属性验证装饰器
+ * 用于数组中每个元素的验证
+ *
+ * @example
+ * @ValidateClass()
+ * class ItemDto {
+ *   @Property(IsString())
+ *   name: string;
+ * }
+ *
+ * @ValidateClass()
+ * class OrderDto {
+ *   @ArrayNestedProperty(ItemDto)
+ *   items: ItemDto[];
+ * }
+ */
+export function ArrayNestedProperty<T>(nestedClass: new () => T): PropertyDecorator {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'symbol') {
+      throw new Error('@ArrayNestedProperty decorator does not support symbol property keys');
+    }
+
+    const existingMetadata: ClassValidationMetadata[] =
+      Reflect.getMetadata(CLASS_VALIDATION_METADATA_KEY, target.constructor) ?? [];
+
+    let propertyMetadata = existingMetadata.find((m) => m.property === propertyKey);
+    if (!propertyMetadata) {
+      propertyMetadata = { property: propertyKey, rules: [] };
+      existingMetadata.push(propertyMetadata);
+    }
+
+    propertyMetadata.rules.push({
+      name: 'validateNestedArray',
+      message: '数组元素验证失败',
+      nested: true,
+      nestedType: nestedClass,
+      each: true,
+      validate: (value) => Array.isArray(value),
+    });
+
+    Reflect.defineMetadata(CLASS_VALIDATION_METADATA_KEY, existingMetadata, target.constructor);
+  };
+}