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

package/dist/index.d.ts

@@ -1,7 +1,5 @@
-import { DynamicModule, Type, CanActivate, ExecutionContext, NestMiddleware, HttpException, ExceptionFilter, ArgumentsHost } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
+import { DynamicModule, Type, HttpException } from '@nestjs/common';
 import { PureAbility } from '@casl/ability';
-import { Request, Response, NextFunction } from 'express';
 
 /**
  * 用户角色
@@ -38,7 +36,6 @@ interface UserPermissionData {
     /** 用户角色列表 */
     roles: string[];
     /** 用户权限点位列表 */
-    permissions: Permission[];
     /** 数据获取时间 */
     fetchedAt: Date;
 }
@@ -82,28 +79,33 @@ type Action = 'create' | 'read' | 'update' | 'delete' | 'manage' | string;
  */
 type Subject = string | object;
 /**
- * 缓存配置
+ * 获取用户角色数据
  */
-interface CacheConfig {
-    /** 缓存过期时间（秒），默认 300 秒 */
-    ttl?: number;
-    /** 最大缓存数量，默认 1000 */
-    max?: number;
-    /** 是否启用缓存，默认 true */
-    enabled?: boolean;
+interface UserRolesDTO {
+    /** 基础 URL */
+    baseUrl: string;
+    /** 用户ID */
+    userId: string;
+    /** 应用ID */
+    appId: string;
+    /** cookies 字符串 */
+    cookies: Record<string, string>;
+    /** CSRF 令牌 */
+    csrfToken: string;
+}
+interface UserContext {
+    userId?: string;
+    tenantId?: number;
+    appId?: string;
+    userRoles?: string[];
+    baseUrl?: string;
+    cookies?: Record<string, string>;
+    csrfToken?: string;
 }
 /**
  * 权限 API 配置
  */
 interface PermissionApiConfig {
-    /** 权限 API 基础 URL */
-    baseUrl: string;
-    /** API 认证 Token（可选） */
-    apiToken?: string;
-    /** 权限的端点路径 */
-    endpoint: string;
-    /** 自定义请求头 */
-    headers?: Record<string, string>;
     /** 请求超时时间（毫秒），默认 5000 */
     timeout?: number;
 }
@@ -113,23 +115,12 @@ interface PermissionApiConfig {
 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;
@@ -192,337 +183,6 @@ type CheckRoleRequirement = RoleRequirement;
  */
 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>;
-}
-
 /**
  * 权限拒绝异常类型
  */
@@ -533,8 +193,6 @@ declare enum PermissionDeniedType {
     ROLE_REQUIRED = "ROLE_REQUIRED",
     /** 缺少权限 */
     PERMISSION_REQUIRED = "PERMISSION_REQUIRED",
-    /** 环境不满足 */
-    ENVIRONMENT_REQUIRED = "ENVIRONMENT_REQUIRED",
     /** 权限配置查询失败 */
     PERMISSION_CONFIG_QUERY_FAILED = "PERMISSION_CONFIG_QUERY_FAILED"
 }
@@ -558,7 +216,7 @@ interface PermissionDeniedDetails {
     /** 环境要求（如果适用） */
     environmentRequirement?: string;
     /** 额外信息 */
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * 权限拒绝异常
@@ -583,91 +241,65 @@ declare class PermissionDeniedException extends HttpException {
         actions: string[];
         subject: string;
     }>, or?: boolean, customMessage?: string): PermissionDeniedException;
-    /**
-     * 创建环境不满足异常
-     */
-    static environmentRequired(requirement: string, message?: string): PermissionDeniedException;
 }
 
 /**
- * AuthZPaas 异常过滤器
- * 确保权限错误信息能够正确返回给客户端
+ * 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 AuthZPaasExceptionFilter implements ExceptionFilter {
-    catch(exception: PermissionDeniedException, host: ArgumentsHost): void;
+declare class AbilityFactory {
+    /**
+     * 为用户创建 Ability
+     */
+    createForUser(permissionData: UserPermissionData): AppAbility;
 }
 
 /**
- * 权限数据 DTO
+ * 常量
  */
-declare class PermissionDto {
-    sub: string;
-    actions: string[];
-    id?: string;
-    name?: string;
-    conditions?: Record<string, unknown>;
-}
+/** 匿名用户 ID */
+declare const ANONYMOUS_USER_ID = "anonymous_user_id";
 /**
- * 权限查询响应
+ * 依赖注入 Token
  */
-declare class PermissionResponse {
-    userId?: string;
-    roles: string[];
-    permissions: Permission[];
-    fetchedAt: Date;
-}
+/** 权限 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 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;
-    }>;
-}
+/** 需要的角色元数据键 */
+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";
 
-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 };
+export { ANONYMOUS_USER_ID, AUTHZPAAS_MODULE_OPTIONS, AbilityFactory, type Action, type AppAbility, AuthZPaasModule, type AuthZPaasModuleOptions, type AuthorizationContext, CACHE_CONFIG_TOKEN, CanRole, type CheckRoleRequirement, DEFAULT_LOGIN_PATH, ENABLE_MOCK_ROLE_KEY, ENVIRONMENT_KEY, type EnvironmentContext, MOCK_ROLES_COOKIE_KEY, NEED_LOGIN_KEY, PERMISSIONS_KEY, PERMISSION_API_CONFIG_TOKEN, type Permission, type PermissionApiConfig, type PermissionDeniedDetails, PermissionDeniedException, PermissionDeniedType, ROLES_KEY, ROLE_SUBJECT, type RoleRequirement, type Subject, type UserContext, type UserPermissionData, type UserRole, type UserRolesDTO };