@lark-apaas/nestjs-authzpaas 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,673 @@
+import { DynamicModule, Type, CanActivate, ExecutionContext, NestMiddleware, HttpException, ExceptionFilter, ArgumentsHost } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { PureAbility } from '@casl/ability';
+import { Request, Response, NextFunction } from 'express';
+
+/**
+ * 用户角色
+ */
+interface UserRole {
+    /** 角色ID */
+    id: string;
+    /** 角色名称 */
+    name: string;
+    /** 角色描述 */
+    description?: string;
+}
+/**
+ * 权限点位
+ */
+interface Permission {
+    /** 资源类型 */
+    sub: string;
+    /** 操作类型 */
+    actions: string[];
+    /** 权限ID */
+    id?: string;
+    /** 权限名称 */
+    name?: string;
+    /** 权限条件 */
+    conditions?: Record<string, unknown>;
+}
+/**
+ * 用户权限数据
+ */
+interface UserPermissionData {
+    /** 用户ID ,匿名用户时为空*/
+    userId?: string;
+    /** 用户角色列表 */
+    roles: string[];
+    /** 用户权限点位列表 */
+    permissions: Permission[];
+    /** 数据获取时间 */
+    fetchedAt: Date;
+}
+/**
+ * 环境信息
+ */
+interface EnvironmentContext {
+    /** 网络信息 */
+    network?: {
+        ip?: string;
+        region?: string;
+    };
+    /** 终端信息 */
+    device?: {
+        type?: 'mobile' | 'desktop' | 'tablet';
+        os?: string;
+        browser?: string;
+    };
+    /** 自定义环境变量 */
+    custom?: Record<string, unknown>;
+}
+/**
+ * 权限检查上下文
+ */
+interface AuthorizationContext {
+    /** 用户ID */
+    userId: string;
+    /** 用户权限数据 */
+    permissionData?: UserPermissionData;
+    /** 环境信息 */
+    environment?: EnvironmentContext;
+    /** 请求对象 */
+    request?: unknown;
+}
+/**
+ * CASL 动作类型
+ */
+type Action = 'create' | 'read' | 'update' | 'delete' | 'manage' | string;
+/**
+ * CASL 主体类型
+ */
+type Subject = string | object;
+/**
+ * 缓存配置
+ */
+interface CacheConfig {
+    /** 缓存过期时间（秒），默认 300 秒 */
+    ttl?: number;
+    /** 最大缓存数量，默认 1000 */
+    max?: number;
+    /** 是否启用缓存，默认 true */
+    enabled?: boolean;
+}
+/**
+ * 权限 API 配置
+ */
+interface PermissionApiConfig {
+    /** 权限 API 基础 URL */
+    baseUrl: string;
+    /** API 认证 Token（可选） */
+    apiToken?: string;
+    /** 权限的端点路径 */
+    endpoint: string;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+    /** 请求超时时间（毫秒），默认 5000 */
+    timeout?: number;
+}
+/**
+ * AuthZPaas 模块配置
+ */
+interface AuthZPaasModuleOptions {
+    /** 权限 API 配置 */
+    permissionApi?: PermissionApiConfig;
+    /** 缓存配置 */
+    cache?: CacheConfig;
+    /** 是否启用 mock 角色功能，默认 false */
+    enableMockRole?: boolean;
+    /** 是否总是需要登录，默认 true */
+    alwaysNeedLogin?: boolean;
+    /** 未登录时默认重定向的登录页路径（可被 @NeedLogin 覆盖），默认 '/login' */
+    loginPath?: string;
+    /** 是否全局模块，默认 true */
+    isGlobal?: boolean;
+}
+
+interface AuthZPaasModuleAsyncOptions {
+    imports?: Type<unknown>[];
+    inject?: (string | symbol | Type<unknown>)[];
+    useFactory: (...args: unknown[]) => Promise<AuthZPaasModuleOptions> | AuthZPaasModuleOptions;
+    isGlobal?: boolean;
+}
+declare class AuthZPaasModule {
+    static forRoot(options: AuthZPaasModuleOptions): DynamicModule;
+    /**
+     * 异步注册 AuthZPaas 模块（根模块）
+     * 用于需要从配置服务获取设置的场景
+     *
+     * @param options 异步配置选项
+     * @returns 动态模块
+     *
+     * @example
+     * ```typescript
+     * @Module({
+     *   imports: [
+     *     AuthZPaasModule.forRootAsync({
+     *       imports: [ConfigModule],
+     *       inject: [ConfigService],
+     *       useFactory: async (configService: ConfigService) => ({
+     *         permissionApi: {
+     *           baseUrl: configService.get('PERMISSION_API_URL'),
+     *           apiToken: configService.get('PERMISSION_API_TOKEN'),
+     *         },
+     *         cache: {
+     *           ttl: configService.get('CACHE_TTL', 300),
+     *           max: configService.get('CACHE_MAX', 1000),
+     *         },
+     *       }),
+     *     }),
+     *   ],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRootAsync(options: AuthZPaasModuleAsyncOptions): DynamicModule;
+}
+
+/**
+ * 角色要求配置
+ */
+interface RoleRequirement {
+    /** 需要的角色列表 */
+    roles: string[];
+    /** 是否需要所有角色（AND），默认 false（OR） */
+    and?: boolean;
+}
+type CheckRoleRequirement = RoleRequirement;
+/**
+ * 要求用户拥有指定角色
+ *
+ * @example
+ * ```typescript
+ * // 需要任一角色
+ * @CanRole(['admin', 'moderator'])
+ * async deleteUser() {}
+ *
+ * // 需要所有角色
+ * @CanRole(['admin', 'superuser'], true)
+ * async criticalOperation() {}
+ * ```
+ */
+declare const CanRole: (role: string[] | string, and?: boolean) => MethodDecorator;
+
+/**
+ * 权限要求配置
+ */
+interface PermissionRequirement {
+    /** 操作类型 */
+    actions: Action[];
+    /** 资源类型 */
+    subject: Subject;
+    /** 是否需要所有操作（AND），默认 true（AND） */
+    or?: boolean;
+}
+/**
+ * 要求用户拥有指定权限
+ *
+ * @example
+ * ```typescript
+ * // 通过 CASL 动作和资源检查（推荐使用）
+ * @CanPermission({ actions: ['create'], subject: 'User' })
+ * async createUser() {}
+ *
+ * @CanPermission({ actions: ['update'], subject: 'Article' })
+ * async updateArticle() {}
+ *
+ * @CanPermission({ actions: ['delete'], subject: 'Comment' })
+ * async deleteComment() {}
+ *
+ * // 注意：基于权限名称列表的检查方式暂不支持
+ * // permissions 参数暂时保留用于未来扩展
+ * ```
+ */
+declare const CanPermission: (permission: PermissionRequirement[] | PermissionRequirement, or?: boolean) => MethodDecorator;
+
+/**
+ * 网络要求
+ */
+interface NetworkRequirement {
+    /** 允许的 IP 地址列表（支持 CIDR） */
+    allowedIPs?: string[];
+    /** 禁止的 IP 地址列表 */
+    blockedIPs?: string[];
+    /** 允许的地区列表 */
+    allowedRegions?: string[];
+}
+/**
+ * 设备要求
+ */
+interface DeviceRequirement {
+    /** 允许的设备类型 */
+    types?: Array<'mobile' | 'desktop' | 'tablet'>;
+    /** 允许的操作系统 */
+    os?: string[];
+    /** 允许的浏览器 */
+    browsers?: string[];
+}
+/**
+ * 环境要求配置
+ */
+interface EnvironmentRequirement {
+    /** 网络要求 */
+    network?: NetworkRequirement;
+    /** 设备要求 */
+    device?: DeviceRequirement;
+    /** 自定义环境验证函数 */
+    custom?: (context: any) => boolean | Promise<boolean>;
+}
+/**
+ * 要求特定的环境条件
+ *
+ * @example
+ * ```typescript
+ * // 仅允许桌面端访问
+ * @CanEnv({ device: { types: ['desktop'] } })
+ * async adminPanel() {}
+ *
+ * // 限制 IP 访问
+ * @CanEnv({
+ *   network: {
+ *     allowedIPs: ['192.168.1.0/24', '10.0.0.1']
+ *   }
+ * })
+ * async internalAPI() {}
+ *
+ * // 自定义验证
+ * @CanEnv({
+ *   custom: (ctx) => ctx.headers['x-api-key'] === 'secret'
+ * })
+ * async secretEndpoint() {}
+ * ```
+ */
+declare const CanEnv: (requirement: EnvironmentRequirement) => MethodDecorator;
+
+/**
+ * 获取当前用户 ID
+ *
+ * @example
+ * ```typescript
+ * @Get('profile')
+ * getProfile(@UserId() userId: string) {
+ *   return { userId };
+ * }
+ * ```
+ */
+declare const UserId: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+declare const MockRoles: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+/**
+ * CASL Ability 类型
+ */
+type AppAbility = PureAbility<[Action, Subject]>;
+/**
+ * 角色检查的特殊 Subject
+ * 用于统一角色鉴权和权限点位鉴权
+ *
+ * 使用方式：
+ * - 权限点位鉴权：ability.can('read', 'Todo')
+ * - 角色鉴权：ability.can('admin', ROLE_SUBJECT) 或 ability.can('admin', '@role')
+ */
+declare const ROLE_SUBJECT = "@role";
+/**
+ * Ability 工厂
+ * 负责根据用户权限数据创建 CASL Ability 实例
+ *
+ * 统一了两种鉴权方式：
+ * 1. 基于角色的鉴权 - 角色名作为 action，'@role' 作为 subject
+ * 2. 基于权限点位的鉴权 - 标准的 action + subject 模式
+ */
+declare class AbilityFactory {
+    /**
+     * 为用户创建 Ability
+     */
+    createForUser(permissionData: UserPermissionData): AppAbility;
+}
+
+interface CheckPermissionsParams {
+    requirements: PermissionRequirement[];
+    or?: boolean;
+}
+/**
+ * 权限服务
+ * 内置权限获取和缓存逻辑，以及权限检查逻辑
+ */
+declare class PermissionService {
+    private readonly apiConfig;
+    private readonly abilityFactory;
+    private readonly logger;
+    private readonly cache;
+    private readonly pendingRequests;
+    constructor(apiConfig: PermissionApiConfig, cacheConfig: CacheConfig, abilityFactory: AbilityFactory);
+    /**
+     * 构建权限/Ability 缓存 key
+     * - 若存在模拟角色：按角色集合排序拼接 + 用户维度
+     * - 否则按 userId/匿名用户
+     */
+    private buildCacheKey;
+    /**
+     * 获取用户权限数据（带缓存）
+     */
+    getUserPermissions(userId?: string, mockRoles?: string[]): Promise<UserPermissionData | null>;
+    /**
+     * 从 API 获取权限数据
+     * 内置实现，用户无需配置
+     */
+    private fetchFromApi;
+    /**
+     * 基于模拟角色获取权限数据（不使用缓存）
+     * 该方法用于前端/守卫在检测到 mockRoles 时直接按角色获取权限
+     */
+    getPermissionsByMockRoles(userId: string | undefined, mockRoles: string[]): Promise<UserPermissionData>;
+    /**
+     * 获取用户的 Ability 实例（带缓存）
+     * @param userId 用户ID
+     * @returns CASL Ability 实例
+     */
+    private getUserAbility;
+    /**
+     * 清除用户权限缓存
+     */
+    clearUserCache(userId: string): void;
+    /**
+     * 清除所有缓存
+     */
+    clearAllCache(): void;
+    /**
+     * 获取缓存统计信息
+     */
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        enabled: boolean;
+    };
+    /**
+     * 检查角色要求
+     * 使用 CASL Ability 统一鉴权方式
+     * @param requirement 角色要求
+     * @param userId 用户ID,匿名用户时为空
+     * @returns 用户权限数据
+     * @throws PermissionDeniedException 当角色不满足时
+     */
+    checkRoles(requirement: RoleRequirement, userId?: string, mockRoles?: string[]): Promise<UserPermissionData>;
+    /**
+     * 检查权限要求
+     * @param requirements 权限要求列表
+     * @param userId 用户ID
+     * @returns 用户权限数据
+     * @throws PermissionDeniedException 当权限不满足时
+     */
+    checkPermissions(params: CheckPermissionsParams, userId?: string, mockRoles?: string[]): Promise<UserPermissionData>;
+    getAbility(userId: string): Promise<AppAbility>;
+}
+
+/**
+ * AuthZPaas 守卫
+ * 负责协调所有鉴权检查，具体检查逻辑委托给 PermissionService
+ */
+declare class AuthZPaasGuard implements CanActivate {
+    private reflector;
+    private permissionService;
+    private moduleOptions;
+    constructor(reflector: Reflector, permissionService: PermissionService, moduleOptions: AuthZPaasModuleOptions);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * 从请求中提取用户ID
+     * 子类可以重写此方法以适应不同的认证策略
+     */
+    protected extractUserId(request: {
+        userContext?: {
+            userId?: string;
+        };
+        cookies?: Record<string, string | undefined>;
+    }): string | undefined;
+    /**
+     * 从请求中提取环境上下文
+     */
+    protected extractEnvironmentContext(request: {
+        ip?: string;
+        connection?: {
+            remoteAddress?: string;
+        };
+        headers: Record<string, string | string[] | undefined>;
+        query?: Record<string, unknown>;
+    }): EnvironmentContext;
+    /**
+     * 检测设备类型
+     */
+    private detectDeviceType;
+    /**
+     * 检查角色要求
+     */
+    private checkRoleRequirement;
+    /**
+     * 检查权限要求
+     */
+    private checkPermissionRequirement;
+    /**
+     * 检查环境要求
+     */
+    private checkEnvironmentRequirement;
+    /**
+     * 检查网络要求
+     */
+    private checkNetworkRequirement;
+    /**
+     * 检查设备要求
+     */
+    private checkDeviceRequirement;
+    /**
+     * 检查 IP 是否匹配
+     * 简化版本，仅支持精确匹配
+     * 生产环境建议使用 ipaddr.js 等库
+     */
+    private checkIPMatch;
+}
+
+/**
+ * 常量
+ */
+/** 匿名用户 ID */
+declare const ANONYMOUS_USER_ID = "anonymous_user_id";
+/**
+ * 依赖注入 Token
+ */
+/** 权限 API 配置 Token */
+declare const PERMISSION_API_CONFIG_TOKEN: unique symbol;
+/** 缓存配置 Token */
+declare const CACHE_CONFIG_TOKEN: unique symbol;
+/** AuthZPaas 模块选项 Token */
+declare const AUTHZPAAS_MODULE_OPTIONS: unique symbol;
+/**
+ * 元数据键
+ */
+/** 需要的角色元数据键 */
+declare const ROLES_KEY = "authzpaas:roles";
+/** 需要的权限元数据键 */
+declare const PERMISSIONS_KEY = "authzpaas:permissions";
+/** 需要的环境元数据键 */
+declare const ENVIRONMENT_KEY = "authzpaas:environment";
+/** 需要登录元数据键 */
+declare const NEED_LOGIN_KEY = "authzpaas:needLogin";
+/** 模块选项：登录页路径默认值 */
+declare const DEFAULT_LOGIN_PATH = "/login";
+/** 角色模拟的 Cookie 键名 */
+declare const MOCK_ROLES_COOKIE_KEY = "mockRoles";
+declare const ENABLE_MOCK_ROLE_KEY = "__authzpaas_enableMockRole";
+
+interface UserContext {
+    userId?: string;
+    tenantId?: number;
+    appId?: string;
+    userRoles?: string[];
+}
+/**
+ * 扩展 Express Request 类型，添加用户权限相关字段
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            userContext: UserContext;
+            [ENABLE_MOCK_ROLE_KEY]?: boolean;
+        }
+    }
+}
+declare class RolesMiddleware implements NestMiddleware {
+    private readonly permissionService;
+    private readonly logger;
+    constructor(permissionService: PermissionService);
+    use(req: Request, _res: Response, next: NextFunction): Promise<void>;
+}
+
+/**
+ * 权限拒绝异常类型
+ */
+declare enum PermissionDeniedType {
+    /** 用户未认证 */
+    UNAUTHENTICATED = "UNAUTHENTICATED",
+    /** 缺少角色 */
+    ROLE_REQUIRED = "ROLE_REQUIRED",
+    /** 缺少权限 */
+    PERMISSION_REQUIRED = "PERMISSION_REQUIRED",
+    /** 环境不满足 */
+    ENVIRONMENT_REQUIRED = "ENVIRONMENT_REQUIRED",
+    /** 权限配置查询失败 */
+    PERMISSION_CONFIG_QUERY_FAILED = "PERMISSION_CONFIG_QUERY_FAILED"
+}
+/**
+ * 权限拒绝异常详情
+ */
+interface PermissionDeniedDetails {
+    /** 错误堆栈 */
+    cause?: Error;
+    /** 异常类型 */
+    type: PermissionDeniedType;
+    /** 错误消息 */
+    message: string;
+    /** 需要的角色（如果适用） */
+    requiredRoles?: string[];
+    /** 需要的权限（如果适用） */
+    requiredPermissions?: Array<{
+        actions: string[];
+        subject: string;
+    }>;
+    /** 环境要求（如果适用） */
+    environmentRequirement?: string;
+    /** 额外信息 */
+    metadata?: Record<string, any>;
+}
+/**
+ * 权限拒绝异常
+ * 专门用于 AuthZPaas 模块的权限检查失败场景
+ */
+declare class PermissionDeniedException extends HttpException {
+    readonly type: PermissionDeniedType;
+    readonly details: PermissionDeniedDetails;
+    constructor(details: PermissionDeniedDetails, httpStatusCode?: number);
+    /**
+     * 创建用户未认证异常
+     */
+    static unauthenticated(message?: string): PermissionDeniedException;
+    /**
+     * 创建角色不足异常
+     */
+    static roleRequired(requiredRoles: string[], and?: boolean): PermissionDeniedException;
+    /**
+     * 创建权限不足异常
+     */
+    static permissionRequired(requiredPermissions: Array<{
+        actions: string[];
+        subject: string;
+    }>, or?: boolean, customMessage?: string): PermissionDeniedException;
+    /**
+     * 创建环境不满足异常
+     */
+    static environmentRequired(requirement: string, message?: string): PermissionDeniedException;
+}
+
+/**
+ * AuthZPaas 异常过滤器
+ * 确保权限错误信息能够正确返回给客户端
+ */
+declare class AuthZPaasExceptionFilter implements ExceptionFilter {
+    catch(exception: PermissionDeniedException, host: ArgumentsHost): void;
+}
+
+/**
+ * 权限数据 DTO
+ */
+declare class PermissionDto {
+    sub: string;
+    actions: string[];
+    id?: string;
+    name?: string;
+    conditions?: Record<string, unknown>;
+}
+/**
+ * 权限查询响应
+ */
+declare class PermissionResponse {
+    userId?: string;
+    roles: string[];
+    permissions: Permission[];
+    fetchedAt: Date;
+}
+/**
+ * 权限控制器
+ * 提供权限查询接口，供前端客户端使用
+ */
+declare class PermissionController {
+    private readonly permissionService;
+    constructor(permissionService: PermissionService);
+    /**
+     * 获取当前用户的权限数据
+     *
+     * @param userId 当前用户ID（从请求上下文中获取）
+     * @returns 用户权限数据
+     *
+     * @example
+     * GET /api/permissions
+     *
+     * Response:
+     * {
+     *   "userId": "user123",
+     *   "roles": ["admin", "user"],
+     *   "permissions": [
+     *     { "sub": "task", "actions": ["create", "read", "update", "delete"] }
+     *   ],
+     *   "fetchedAt": "2025-10-14T00:00:00.000Z"
+     * }
+     */
+    getUserPermissions(userId: string, mockRoles: string[]): Promise<PermissionResponse>;
+    /**
+     * 开启角色模拟：将传入的 userId 写入 cookie，服务端优先使用该值请求权限
+     */
+    enableMock(res: Response, roles: string[]): Promise<{
+        success: boolean;
+        message: string;
+        roles?: undefined;
+    } | {
+        success: boolean;
+        roles: string[];
+        message?: undefined;
+    }>;
+    /**
+     * 关闭角色模拟：清除 cookie
+     */
+    disableMock(res: Response): Promise<{
+        success: boolean;
+    }>;
+    getMockRoles(mockRoles: string[] | undefined, userId: string): Promise<{
+        mocking: boolean;
+        roles: string[];
+        permissions: Permission[];
+        fetchedAt: Date;
+        userId: string;
+    }>;
+}
+
+export { ANONYMOUS_USER_ID, AUTHZPAAS_MODULE_OPTIONS, AbilityFactory, type Action, type AppAbility, AuthZPaasExceptionFilter, AuthZPaasGuard, AuthZPaasModule, type AuthZPaasModuleOptions, type AuthorizationContext, CACHE_CONFIG_TOKEN, type CacheConfig, CanEnv, CanPermission, CanRole, type CheckRoleRequirement, DEFAULT_LOGIN_PATH, type DeviceRequirement, ENABLE_MOCK_ROLE_KEY, ENVIRONMENT_KEY, type EnvironmentContext, type EnvironmentRequirement, MOCK_ROLES_COOKIE_KEY, MockRoles, NEED_LOGIN_KEY, type NetworkRequirement, PERMISSIONS_KEY, PERMISSION_API_CONFIG_TOKEN, type Permission, type PermissionApiConfig, PermissionController, type PermissionDeniedDetails, PermissionDeniedException, PermissionDeniedType, PermissionDto, type PermissionRequirement, PermissionResponse, PermissionService, ROLES_KEY, ROLE_SUBJECT, type RoleRequirement, RolesMiddleware, type Subject, type UserContext, UserId, type UserPermissionData, type UserRole };