@lark-apaas/nestjs-authzpaas 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { DynamicModule, Type, HttpException } from '@nestjs/common';
+import { DynamicModule, Type, CanActivate, ExecutionContext, HttpException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
 import { PureAbility } from '@casl/ability';
+import { PlatformHttpClient, RequestContextService, ObservableService } from '@lark-apaas/nestjs-common';
 
 /**
  * 用户角色
@@ -12,21 +14,6 @@ interface UserRole {
     /** 角色描述 */
     description?: string;
 }
-/**
- * 权限点位
- */
-interface Permission {
-    /** 资源类型 */
-    sub: string;
-    /** 操作类型 */
-    actions: string[];
-    /** 权限ID */
-    id?: string;
-    /** 权限名称 */
-    name?: string;
-    /** 权限条件 */
-    conditions?: Record<string, unknown>;
-}
 /**
  * 用户权限数据
  */
@@ -39,37 +26,6 @@ interface UserPermissionData {
     /** 数据获取时间 */
     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 动作类型
  */
@@ -78,29 +34,11 @@ type Action = 'create' | 'read' | 'update' | 'delete' | 'manage' | string;
  * CASL 主体类型
  */
 type Subject = string | object;
-/**
- * 获取用户角色数据
- */
-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 配置
@@ -163,8 +101,6 @@ declare class AuthZPaasModule {
 interface RoleRequirement {
     /** 需要的角色列表 */
     roles: string[];
-    /** 是否需要所有角色（AND），默认 false（OR） */
-    and?: boolean;
 }
 type CheckRoleRequirement = RoleRequirement;
 /**
@@ -172,16 +108,98 @@ type CheckRoleRequirement = RoleRequirement;
  *
  * @example
  * ```typescript
- * // 需要任一角色
- * @CanRole(['admin', 'moderator'])
+ * 单一角色
+ * @CanRole(['admin'])
  * async deleteUser() {}
  *
- * // 需要所有角色
- * @CanRole(['admin', 'superuser'], true)
+ * 任一角色
+ * @CanRole(['admin', 'editor'])
  * async criticalOperation() {}
  * ```
  */
-declare const CanRole: (role: string[] | string, and?: boolean) => MethodDecorator;
+declare const CanRole: (role: string[] | string) => MethodDecorator;
+
+/**
+ * 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;
+}
+
+/**
+ * 权限服务
+ * 内置权限获取和缓存逻辑，以及权限检查逻辑
+ */
+declare class PermissionService {
+    private readonly apiConfig;
+    private readonly abilityFactory;
+    private readonly client;
+    private readonly requestContextService;
+    constructor(apiConfig: PermissionApiConfig, abilityFactory: AbilityFactory, client: PlatformHttpClient, requestContextService: RequestContextService);
+    /**
+     * 获取用户权限数据
+     */
+    getUserPermissions({ laneId, }: {
+        laneId?: string;
+    }): Promise<UserPermissionData | null>;
+    /**
+     * 从 API 获取权限数据
+     * 内置实现，用户无需配置
+     */
+    private fetchFromApi;
+    /**
+     * 检查角色要求
+     * 使用 CASL Ability 统一鉴权方式
+     * @param requirement 角色要求
+     * @param laneId 环境ID
+     * @returns 用户权限检查结果，包含结果和详细信息
+     * @throws PermissionDeniedException 当权限数据获取失败时
+     */
+    checkRoles(requirement: RoleRequirement, laneId?: string): Promise<{
+        result: boolean;
+        details?: string;
+    }>;
+}
+
+/**
+ * AuthZPaas 守卫
+ * 负责协调所有鉴权检查，具体检查逻辑委托给 PermissionService
+ */
+declare class AuthZPaasGuard implements CanActivate {
+    private reflector;
+    private permissionService;
+    private obs;
+    constructor(reflector: Reflector, permissionService: PermissionService, obs: ObservableService);
+    private logger;
+    /**
+     * 验证角色要求是否有效
+     * @param requirements 角色要求
+     * @returns 是否有效
+     */
+    private isValidRoleRequirement;
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
 
 /**
  * 权限拒绝异常类型
@@ -233,7 +251,7 @@ declare class PermissionDeniedException extends HttpException {
     /**
      * 创建角色不足异常
      */
-    static roleRequired(requiredRoles: string[], and?: boolean): PermissionDeniedException;
+    static roleRequired(requiredRoles: string[]): PermissionDeniedException;
     /**
      * 创建权限不足异常
      */
@@ -243,34 +261,6 @@ declare class PermissionDeniedException extends HttpException {
     }>, or?: boolean, customMessage?: string): PermissionDeniedException;
 }
 
-/**
- * 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;
-}
-
 /**
  * 常量
  */
@@ -281,8 +271,6 @@ declare const ANONYMOUS_USER_ID = "anonymous_user_id";
  */
 /** 权限 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;
 /**
@@ -290,16 +278,5 @@ 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";
 
-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 };
+export { ANONYMOUS_USER_ID, AUTHZPAAS_MODULE_OPTIONS, AbilityFactory, type Action, type AppAbility, AuthZPaasGuard, AuthZPaasModule, type AuthZPaasModuleOptions, CanRole, type CheckRoleRequirement, PERMISSION_API_CONFIG_TOKEN, type PermissionApiConfig, type PermissionDeniedDetails, PermissionDeniedException, PermissionDeniedType, PermissionService, ROLES_KEY, ROLE_SUBJECT, type RoleRequirement, type Subject, type UserContext, type UserPermissionData, type UserRole };