@vlian/infrastructure 0.9.10

package/dist/types/managers/PermissionManager/types.d.ts

@@ -0,0 +1,809 @@
+/**
+ * PermissionManager 类型定义
+ */
+import type { AppEventBus, Logger, MonitoringService, StateManagerInstance, AuthManager, EventMetadata, EventListenerOptions } from './types/framework';
+export type { AppEventBus, Logger, MonitoringService, StateManagerInstance, AuthManager, EventMetadata, EventListenerOptions, };
+/**
+ * 权限数据
+ */
+export interface PermissionData {
+    /**
+     * 权限标识数组
+     */
+    permissions: string[];
+    /**
+     * 角色标识数组
+     */
+    roles: string[];
+    /**
+     * 权限树结构（可选）
+     */
+    permissionTree?: PermissionTree;
+    /**
+     * 数据更新时间戳
+     */
+    updatedAt?: number;
+    /**
+     * 数据过期时间戳（可选）
+     */
+    expiresAt?: number;
+}
+/**
+ * 权限树节点
+ */
+export interface PermissionTreeNode {
+    /**
+     * 权限标识
+     */
+    permission: string;
+    /**
+     * 子权限节点
+     */
+    children?: PermissionTreeNode[];
+    /**
+     * 权限描述（可选）
+     */
+    description?: string;
+}
+/**
+ * 权限树结构
+ */
+export interface PermissionTree {
+    /**
+     * 根节点数组
+     */
+    roots: PermissionTreeNode[];
+}
+/**
+ * 权限树配置
+ */
+export interface PermissionTreeConfig {
+    /**
+     * 权限树数据
+     */
+    tree: PermissionTree;
+    /**
+     * 是否启用权限继承（默认：true）
+     */
+    enableInheritance?: boolean;
+    /**
+     * 权限路径分隔符（默认：':'）
+     */
+    pathSeparator?: string;
+}
+/**
+ * PermissionManager 配置选项
+ */
+export interface PermissionOptions {
+    /**
+     * AuthManager 实例（必需）
+     * 用于获取用户信息和权限数据
+     */
+    authManager: AuthManager<unknown>;
+    /**
+     * @vlian/framework StateManager 配置（可选）
+     * 用于权限数据状态管理，支持跨组件共享
+     * 如果不提供，使用内存存储（默认）
+     * 注意：不允许使用浏览器本地存储（localStorage/sessionStorage）
+     */
+    stateManager?: {
+        instance?: StateManagerInstance;
+        namespace?: string;
+    };
+    /**
+     * @vlian/framework AppEventBus 实例（可选）
+     * 如果不提供，内部会创建独立的事件总线
+     */
+    eventBus?: AppEventBus;
+    /**
+     * @vlian/framework Logger 实例（可选）
+     */
+    logger?: Logger;
+    /**
+     * @vlian/framework MonitoringService 实例（可选）
+     */
+    monitoring?: MonitoringService;
+    /**
+     * 权限数据提取函数（可选）
+     * 从用户信息中提取权限和角色
+     * 如果不提供，使用默认提取逻辑
+     */
+    permissionExtractor?: (userInfo: unknown) => PermissionData | null;
+    /**
+     * 权限数据获取函数（可选）
+     * 从 API 获取权限数据
+     * 如果不提供，只从用户信息中提取
+     */
+    permissionFetcher?: () => Promise<PermissionData>;
+    /**
+     * 存储策略（默认：'memory'）
+     * - 'memory': 内存存储（默认）
+     * - 'state': 使用 @vlian/framework 状态管理
+     */
+    storageStrategy?: 'memory' | 'state';
+    /**
+     * 是否启用缓存（默认：true）
+     */
+    enableCache?: boolean;
+    /**
+     * 缓存过期时间（毫秒，默认：无过期）
+     * 仅对内存缓存有效
+     */
+    cacheExpiry?: number;
+    /**
+     * 是否启用权限数据加密（默认：false）
+     * 启用后，权限数据会加密存储，获取时自动解密
+     */
+    enableEncryption?: boolean;
+    /**
+     * 加密函数（可选）
+     * 如果不提供，使用默认的 AES 加密
+     * @param data 待加密的数据
+     * @param key 加密密钥
+     * @returns 加密后的数据
+     */
+    encrypt?: (data: string, key: string) => string | Promise<string>;
+    /**
+     * 解密函数（可选）
+     * 如果不提供，使用默认的 AES 解密
+     * @param encryptedData 加密的数据
+     * @param key 解密密钥
+     * @returns 解密后的数据
+     */
+    decrypt?: (encryptedData: string, key: string) => string | Promise<string>;
+    /**
+     * 加密密钥（可选）
+     * 如果不提供，使用默认密钥（不推荐生产环境使用）
+     * 建议通过环境变量或密钥管理服务提供
+     */
+    encryptionKey?: string;
+    /**
+     * 是否启用权限树支持（默认：false）
+     */
+    enablePermissionTree?: boolean;
+    /**
+     * 权限树配置（可选）
+     * 如果提供，将用于权限继承检查
+     */
+    permissionTreeConfig?: PermissionTreeConfig;
+    /**
+     * 是否启用通配符匹配（默认：false）
+     * ⚠️ 安全警告：启用通配符匹配可能导致过度授权，建议谨慎使用
+     * 建议优先使用精确权限或权限树继承
+     */
+    enableWildcardMatch?: boolean;
+    /**
+     * 通配符匹配模式（默认：'direct'）
+     * - 'direct': 只匹配直接子权限（如 `user:*` 只匹配 `user:edit`，不匹配 `user:order:create`）
+     * - 'recursive': 递归匹配所有后代权限（如 `user:*` 匹配所有 `user:` 开头的权限）
+     * ⚠️ 安全警告：'recursive' 模式风险更高，可能导致过度授权
+     */
+    wildcardMatchMode?: 'direct' | 'recursive';
+    /**
+     * 允许的通配符模式（可选）
+     * 如果不提供，使用默认规则：
+     * - 允许：路径末尾通配符（如 `user:*`）
+     * - 禁止：全局通配符（`*`）
+     * - 禁止：路径开头通配符（`*:edit`）
+     * - 禁止：路径中间通配符（`user:*:delete`）
+     *
+     * 如果提供，将覆盖默认规则
+     * @example
+     * // 只允许特定格式的通配符
+     * allowedWildcardPatterns: [/^[a-z]+:\*$/] // 只允许 'module:*' 格式
+     */
+    allowedWildcardPatterns?: RegExp[];
+    /**
+     * 是否记录通配符权限使用日志（默认：true）
+     * 用于权限审计和安全监控
+     */
+    logWildcardUsage?: boolean;
+    /**
+     * 事件命名空间前缀（默认：'permission:'）
+     */
+    eventNamespace?: string;
+    /**
+     * 是否启用事件（默认：true）
+     */
+    enableEvents?: boolean;
+    /**
+     * 是否启用详细性能指标（默认：false）
+     */
+    enableDetailedMetrics?: boolean;
+    /**
+     * 性能指标收集器（可选）
+     */
+    metricsCollector?: (metrics: PerformanceMetrics) => void;
+    /**
+     * 并发控制策略（默认：'queue'）
+     * - 'queue': 串行队列机制，保证操作顺序执行，避免竞态条件（默认推荐）
+     * - 'version': 版本号机制，只应用最新操作，适合高并发场景
+     * - 'none': 无并发控制，直接执行（不推荐）
+     */
+    concurrencyStrategy?: 'queue' | 'version' | 'none';
+    /**
+     * 队列最大长度（默认：100）
+     * 当使用串行队列策略时，防止内存溢出
+     */
+    maxQueueSize?: number;
+    /**
+     * 操作超时时间（毫秒，默认：30000）
+     * 操作超过此时间会自动取消并拒绝
+     * 设置为 0 表示无超时限制
+     */
+    operationTimeout?: number;
+    /**
+     * 实例 ID（可选）
+     * 用于多实例场景下的隔离
+     */
+    instanceId?: string;
+    /**
+     * 是否启用开发模式（默认：自动检测）
+     */
+    devMode?: boolean;
+    /**
+     * 是否启用配置验证（默认：true）
+     */
+    validateConfig?: boolean;
+}
+/**
+ * 权限事件类型枚举
+ */
+export declare enum PermissionEventType {
+    PERMISSIONS_LOADED = "permission:loaded",// 权限数据加载完成
+    PERMISSIONS_UPDATED = "permission:updated",// 权限数据更新
+    PERMISSIONS_REFRESHED = "permission:refreshed",// 权限数据刷新
+    PERMISSION_CHECK = "permission:check",// 权限检查（用于监控）
+    CACHE_CLEARED = "permission:cache:cleared",// 缓存清除
+    PERMISSION_STATE_CHANGED = "permission:state:changed"
+}
+/**
+ * 环境类型
+ */
+export type Environment = 'browser' | 'node' | 'ssr' | 'worker' | 'unknown';
+/**
+ * 健康检查结果
+ */
+export interface HealthCheckResult {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    checks: {
+        storage: boolean;
+        eventBus: boolean;
+        permissionData: boolean;
+    };
+    details?: Record<string, unknown>;
+}
+/**
+ * 性能指标
+ */
+export interface PerformanceMetrics {
+    operation: string;
+    duration: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 配置验证结果
+ */
+export interface ConfigValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * 权限检查结果（增强版）
+ */
+export interface PermissionCheckResult {
+    /**
+     * 是否拥有权限
+     */
+    result: boolean;
+    /**
+     * 匹配类型
+     */
+    matchType: 'exact' | 'tree' | 'wildcard' | 'none';
+    /**
+     * 失败原因（当 result 为 false 时）
+     */
+    reason?: 'no_data' | 'denied' | 'expired' | 'rate_limited' | 'error';
+    /**
+     * 匹配的权限标识（如果有）
+     */
+    matchedPermission?: string;
+    /**
+     * 检查耗时（毫秒）
+     */
+    duration?: number;
+}
+/**
+ * 权限状态变化事件数据
+ */
+export interface PermissionStateChangeData {
+    /**
+     * 变化的权限列表
+     */
+    permissions: string[];
+    /**
+     * 变化的角色列表
+     */
+    roles: string[];
+    /**
+     * 变化类型
+     */
+    changeType: 'added' | 'removed' | 'updated';
+    /**
+     * 变化时间戳
+     */
+    timestamp: number;
+}
+/**
+ * 错误码枚举
+ */
+export declare enum PermissionErrorCode {
+    CONFIG_ERROR_001 = "PERMISSION_ERROR_001",// 缺少必需配置
+    CONFIG_ERROR_002 = "PERMISSION_ERROR_002",// 生产环境缺少加密密钥
+    CONFIG_ERROR_003 = "PERMISSION_ERROR_003",// 配置验证失败
+    DATA_ERROR_100 = "PERMISSION_ERROR_100",// 权限数据加载失败
+    DATA_ERROR_101 = "PERMISSION_ERROR_101",// 权限数据过期
+    DATA_ERROR_102 = "PERMISSION_ERROR_102",// 权限数据完整性校验失败
+    CHECK_ERROR_200 = "PERMISSION_ERROR_200",// 权限检查失败
+    CHECK_ERROR_201 = "PERMISSION_ERROR_201",// 权限检查被限流
+    STORAGE_ERROR_300 = "PERMISSION_ERROR_300",// 存储操作失败
+    STORAGE_ERROR_301 = "PERMISSION_ERROR_301",// 存储数据损坏
+    SECURITY_ERROR_400 = "PERMISSION_ERROR_400",// 安全策略违反
+    SECURITY_ERROR_401 = "PERMISSION_ERROR_401"
+}
+/**
+ * 权限错误类
+ */
+export declare class PermissionError extends Error {
+    code: PermissionErrorCode;
+    context?: Record<string, unknown> | undefined;
+    constructor(code: PermissionErrorCode, message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * 配置预设类型
+ */
+export type PermissionConfigPreset = 'production' | 'development' | 'minimal' | 'custom';
+/**
+ * 配置分组
+ */
+export interface PermissionConfigGroups {
+    storage?: {
+        strategy?: 'memory' | 'state';
+        enableCache?: boolean;
+        cacheExpiry?: number;
+    };
+    security?: {
+        enableEncryption?: boolean;
+        encryptionKey?: string;
+        enableWildcardMatch?: boolean;
+        requireEncryptionKey?: boolean;
+    };
+    performance?: {
+        enableDetailedMetrics?: boolean;
+        enableConcurrentCheck?: boolean;
+        cacheSizeLimit?: number;
+    };
+    events?: {
+        enableEvents?: boolean;
+        eventNamespace?: string;
+    };
+}
+/**
+ * 权限检查策略接口
+ */
+export interface PermissionCheckStrategy {
+    /**
+     * 检查权限
+     */
+    check(permission: string, permissionData: PermissionData | null, context?: Record<string, unknown>): PermissionCheckResult;
+    /**
+     * 策略名称
+     */
+    name: string;
+    /**
+     * 策略优先级（数字越大优先级越高）
+     */
+    priority?: number;
+}
+/**
+ * 权限检查中间件
+ */
+export interface PermissionCheckMiddleware {
+    /**
+     * 中间件名称
+     */
+    name: string;
+    /**
+     * 检查前执行
+     */
+    beforeCheck?(permission: string, context: Record<string, unknown>): void | Promise<void>;
+    /**
+     * 检查后执行
+     */
+    afterCheck?(permission: string, result: PermissionCheckResult, context: Record<string, unknown>): void | Promise<void>;
+    /**
+     * 中间件优先级（数字越大优先级越高）
+     */
+    priority?: number;
+}
+/**
+ * 权限插件接口
+ */
+export interface PermissionPlugin {
+    /**
+     * 插件名称
+     */
+    name: string;
+    /**
+     * 插件版本
+     */
+    version?: string;
+    /**
+     * 初始化钩子
+     */
+    onInit?(manager: unknown): void | Promise<void>;
+    /**
+     * 销毁钩子
+     */
+    onDestroy?(): void | Promise<void>;
+    /**
+     * 权限检查前钩子
+     */
+    beforePermissionCheck?(permission: string, context: Record<string, unknown>): void | Promise<void>;
+    /**
+     * 权限检查后钩子
+     */
+    afterPermissionCheck?(permission: string, result: PermissionCheckResult, context: Record<string, unknown>): void | Promise<void>;
+    /**
+     * 权限数据更新前钩子
+     */
+    beforePermissionUpdate?(permissions: string[], roles: string[]): void | Promise<void>;
+    /**
+     * 权限数据更新后钩子
+     */
+    afterPermissionUpdate?(permissions: string[], roles: string[]): void | Promise<void>;
+}
+/**
+ * 权限数据源
+ */
+export interface PermissionDataSource {
+    /**
+     * 数据源名称
+     */
+    name: string;
+    /**
+     * 优先级（数字越大优先级越高）
+     */
+    priority: number;
+    /**
+     * 获取权限数据
+     */
+    fetch(): Promise<PermissionData | null>;
+    /**
+     * 是否启用
+     */
+    enabled?: boolean;
+}
+/**
+ * 权限数据源合并策略
+ */
+export type DataSourceMergeStrategy = 'union' | 'intersection' | 'priority' | 'custom';
+/**
+ * 权限匹配器接口
+ */
+export interface PermissionMatcher {
+    /**
+     * 匹配器名称
+     */
+    name: string;
+    /**
+     * 检查是否匹配
+     */
+    match(permission: string, userPermission: string): boolean;
+    /**
+     * 匹配器优先级
+     */
+    priority?: number;
+}
+/**
+ * 缓存项（带过期时间）
+ */
+export interface CacheItem<T> {
+    value: T;
+    timestamp: number;
+    expiresAt?: number;
+}
+/**
+ * 性能统计信息
+ */
+export interface PerformanceStatistics {
+    /**
+     * 操作名称
+     */
+    operation: string;
+    /**
+     * 调用次数
+     */
+    count: number;
+    /**
+     * 总耗时（毫秒）
+     */
+    totalDuration: number;
+    /**
+     * 平均耗时（毫秒）
+     */
+    averageDuration: number;
+    /**
+     * 最小耗时（毫秒）
+     */
+    minDuration: number;
+    /**
+     * 最大耗时（毫秒）
+     */
+    maxDuration: number;
+    /**
+     * P95 耗时（毫秒）
+     */
+    p95Duration?: number;
+    /**
+     * P99 耗时（毫秒）
+     */
+    p99Duration?: number;
+    /**
+     * 缓存命中率（0-1）
+     */
+    cacheHitRate?: number;
+    /**
+     * 错误次数
+     */
+    errorCount: number;
+    /**
+     * 错误率（0-1）
+     */
+    errorRate: number;
+}
+/**
+ * 健康检查详细诊断信息
+ */
+export interface HealthCheckDiagnostics {
+    /**
+     * 存储状态
+     */
+    storage: {
+        available: boolean;
+        strategy: string;
+        size?: number;
+        error?: string;
+    };
+    /**
+     * 缓存状态
+     */
+    cache: {
+        enabled: boolean;
+        size: number;
+        hitRate?: number;
+        memoryUsage?: number;
+    };
+    /**
+     * 权限数据状态
+     */
+    permissionData: {
+        loaded: boolean;
+        permissionCount: number;
+        roleCount: number;
+        lastUpdated?: number;
+        expiresAt?: number;
+    };
+    /**
+     * 最近错误
+     */
+    recentErrors: Array<{
+        code: string;
+        message: string;
+        timestamp: number;
+    }>;
+    /**
+     * 性能指标
+     */
+    performance: {
+        averageCheckDuration: number;
+        totalChecks: number;
+        errorRate: number;
+    };
+}
+/**
+ * 审计日志条目
+ */
+export interface AuditLogEntry {
+    /**
+     * 日志 ID
+     */
+    id: string;
+    /**
+     * 操作类型
+     */
+    operation: 'check' | 'update' | 'refresh' | 'clear_cache' | 'error';
+    /**
+     * 操作目标（权限、角色等）
+     */
+    target?: string;
+    /**
+     * 操作结果
+     */
+    result: 'success' | 'failure' | 'denied';
+    /**
+     * 操作时间戳
+     */
+    timestamp: number;
+    /**
+     * 用户信息（如果有）
+     */
+    userId?: string;
+    /**
+     * 额外上下文
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * 权限变更历史条目
+ */
+export interface PermissionChangeHistory {
+    /**
+     * 变更 ID
+     */
+    id: string;
+    /**
+     * 变更类型
+     */
+    changeType: 'added' | 'removed' | 'updated';
+    /**
+     * 变更目标类型
+     */
+    targetType: 'permission' | 'role';
+    /**
+     * 变更目标标识
+     */
+    target: string;
+    /**
+     * 变更前值（如果是更新）
+     */
+    oldValue?: string[];
+    /**
+     * 变更后值
+     */
+    newValue: string[];
+    /**
+     * 变更时间戳
+     */
+    timestamp: number;
+    /**
+     * 变更原因
+     */
+    reason?: string;
+}
+/**
+ * 环境适配器接口
+ */
+export interface EnvironmentAdapter {
+    /**
+     * 环境类型
+     */
+    environment: Environment;
+    /**
+     * 是否支持
+     */
+    isSupported(): boolean;
+    /**
+     * 初始化
+     */
+    init?(): void | Promise<void>;
+    /**
+     * 序列化（用于跨线程/进程传递）
+     */
+    serialize?(data: unknown): string | Promise<string>;
+    /**
+     * 反序列化
+     */
+    deserialize?(data: string): unknown | Promise<unknown>;
+    /**
+     * 水合（SSR 场景）
+     */
+    hydrate?(data: PermissionData): void | Promise<void>;
+}
+/**
+ * 限流配置
+ */
+export interface RateLimitConfig {
+    /**
+     * 是否启用限流
+     */
+    enabled: boolean;
+    /**
+     * 时间窗口（毫秒）
+     */
+    windowMs: number;
+    /**
+     * 最大请求数
+     */
+    maxRequests: number;
+    /**
+     * 限流策略
+     */
+    strategy?: 'token_bucket' | 'sliding_window' | 'fixed_window';
+}
+/**
+ * 调试信息
+ */
+export interface DebugInfo {
+    /**
+     * 实例信息
+     */
+    instance: {
+        id: string;
+        environment: Environment;
+        isProduction: boolean;
+    };
+    /**
+     * 配置信息
+     */
+    config: {
+        storageStrategy: string;
+        enableCache: boolean;
+        enableEncryption: boolean;
+        enablePermissionTree: boolean;
+        enableWildcardMatch: boolean;
+        wildcardMatchMode?: 'direct' | 'recursive';
+    };
+    /**
+     * 权限数据状态
+     */
+    permissionData: {
+        loaded: boolean;
+        permissionCount: number;
+        roleCount: number;
+        lastUpdated?: number;
+    };
+    /**
+     * 缓存状态
+     */
+    cache: {
+        size: number;
+        hitRate?: number;
+    };
+    /**
+     * 性能统计
+     */
+    performance: PerformanceStatistics[];
+    /**
+     * 最近操作历史
+     */
+    recentOperations: Array<{
+        operation: string;
+        timestamp: number;
+        duration: number;
+        result: string;
+    }>;
+}
+/**
+ * 扩展权限选项（包含所有新功能）
+ */
+export interface ExtendedPermissionOptions extends PermissionOptions {
+    preset?: PermissionConfigPreset;
+    configGroups?: PermissionConfigGroups;
+    checkStrategies?: PermissionCheckStrategy[];
+    middlewares?: PermissionCheckMiddleware[];
+    plugins?: PermissionPlugin[];
+    dataSources?: PermissionDataSource[];
+    dataSourceMergeStrategy?: DataSourceMergeStrategy;
+    matchers?: PermissionMatcher[];
+    rateLimit?: RateLimitConfig;
+    enableAuditLog?: boolean;
+    auditLogMaxSize?: number;
+    enableChangeHistory?: boolean;
+    changeHistoryMaxSize?: number;
+    environmentAdapter?: EnvironmentAdapter;
+    enableConfigHotUpdate?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map