@plyaz/auth 1.0.0

package/src/rbac/permission-checker.ts

@@ -0,0 +1,464 @@
+/**
+ * @fileoverview Permission checker for @plyaz/auth
+ * @module @plyaz/auth/rbac/permission-checker
+ * 
+ * @description
+ * Provides permission validation logic for role-based access control.
+ * Handles permission checking with conditions, resource-based permissions,
+ * and hierarchical role inheritance. Used by guards and services to
+ * enforce authorization policies.
+ * 
+ * @example
+ * ```typescript
+ * import { PermissionChecker } from '@plyaz/auth';
+ * 
+ * const checker = new PermissionChecker();
+ * const hasPermission = await checker.checkPermission(
+ *   userId, 
+ *   'campaigns', 
+ *   'create',
+ *   { ownerId: userId }
+ * );
+ * ```
+ */
+
+import { NUMERIX } from "@plyaz/config";
+import type { Permission, PermissionCheckerConfig, PermissionCheckResult, PermissionContext, Role } from  "@plyaz/types";
+
+/**
+ * Permission checker implementation
+ * Validates user permissions with context and conditions
+ */
+// RoleRepository interface based on PermissionChecker usage
+export interface RoleRepository {
+  /**
+   * Get all roles assigned to a user
+   * @param userId - User identifier
+   * @returns Array of Role objects
+   */
+  getUserRoles(userId: string): Promise<Role[]>;
+
+  /**
+   * Get all permissions assigned to a role
+   * @param roleId - Role identifier
+   * @returns Array of Permission objects
+   */
+  getRolePermissions(roleId: string): Promise<Permission[]>;
+}
+
+
+// UserRepository interface based on PermissionChecker usage
+export interface UserRepository {
+  /**
+   * Get all roles assigned to a user
+   * @param userId - User identifier
+   * @returns Array of Role objects
+   */
+  getUserRoles(userId: string): Promise<Role[]>;
+}
+
+
+export class PermissionChecker {
+  private readonly config: PermissionCheckerConfig;
+  private readonly permissionCache = new Map<string, { result: PermissionCheckResult; expires: number }>();
+
+  constructor(
+    config: Partial<PermissionCheckerConfig> = {},
+    private userRepository?: UserRepository,
+    private roleRepository?:RoleRepository 
+  ) {
+    this.config = {
+      enableCaching: true,
+      cacheTTL: 300, // 5 minutes
+      enableAuditLog: true,
+      ...config
+    };
+  }
+
+  /**
+   * Check if user has permission for resource and action
+   * @param userId - User identifier
+   * @param resource - Resource name (e.g., 'campaigns', 'users')
+   * @param action - Action name (e.g., 'create', 'read', 'update', 'delete')
+   * @param context - Permission context for conditional checks
+   * @returns Permission check result
+   */
+  async checkPermission(
+    userId: string,
+    resource: string,
+    action: string,
+    context: PermissionContext = {}
+  ): Promise<PermissionCheckResult> {
+    // Check cache first
+    if (this.config.enableCaching) {
+      const cacheKey = this.getCacheKey(userId, resource, action, context);
+      const cached = this.permissionCache.get(cacheKey);
+      
+      if (cached && cached.expires > Date.now()) {
+        return cached.result;
+      }
+    }
+
+    // Get user permissions
+    const userPermissions = await this.getUserPermissions(userId);
+    
+    // Check direct permissions
+    const directResult = this.checkDirectPermission(userPermissions, resource, action, context);
+    
+    if (directResult.granted) {
+      return this.cacheAndReturn(userId, resource, action, context, directResult);
+    }
+
+    // Check role-based permissions
+    const roleResult = await this.checkRoleBasedPermission(userId, resource, action, context);
+    
+    if (roleResult.granted) {
+      return this.cacheAndReturn(userId, resource, action, context, roleResult);
+    }
+
+    // Check wildcard permissions
+    const wildcardResult = this.checkWildcardPermission(userPermissions, resource, action, context);
+    
+    if (wildcardResult.granted) {
+      return this.cacheAndReturn(userId, resource, action, context, wildcardResult);
+    }
+
+    // Permission denied
+    const deniedResult: PermissionCheckResult = {
+      granted: false,
+      reason: `No permission found for ${resource}:${action}`
+    };
+
+    return this.cacheAndReturn(userId, resource, action, context, deniedResult);
+  }
+
+  /**
+   * Check multiple permissions at once
+   * @param userId - User identifier
+   * @param permissions - Array of permission checks
+   * @returns Array of permission check results
+   */
+  async checkMultiplePermissions(
+    userId: string,
+    permissions: Array<{ resource: string; action: string; context?: PermissionContext }>
+  ): Promise<PermissionCheckResult[]> {
+    const results: PermissionCheckResult[] = [];
+    
+    for (const permission of permissions) {
+      const result = await this.checkPermission(
+        userId,
+        permission.resource,
+        permission.action,
+        permission.context ?? {}
+      );
+      results.push(result);
+    }
+    
+    return results;
+  }
+
+  /**
+   * Check if user has any of the specified permissions
+   * @param userId - User identifier
+   * @param permissions - Array of permission checks
+   * @returns True if user has at least one permission
+   */
+  async hasAnyPermission(
+    userId: string,
+    permissions: Array<{ resource: string; action: string; context?: PermissionContext }>
+  ): Promise<boolean> {
+    const results = await this.checkMultiplePermissions(userId, permissions);
+    return results.some(result => result.granted);
+  }
+
+  /**
+   * Check if user has all specified permissions
+   * @param userId - User identifier
+   * @param permissions - Array of permission checks
+   * @returns True if user has all permissions
+   */
+  async hasAllPermissions(
+    userId: string,
+    permissions: Array<{ resource: string; action: string; context?: PermissionContext }>
+  ): Promise<boolean> {
+    const results = await this.checkMultiplePermissions(userId, permissions);
+    return results.every(result => result.granted);
+  }
+
+  /**
+   * Get all permissions for a user
+   * @param userId - User identifier
+   * @returns Array of user permissions
+   */
+  async getUserPermissions(userId: string): Promise<Permission[]> {
+    if (!this.userRepository) {
+      throw new Error('UserRepository not configured');
+    }
+    
+  
+    const userRoles = await this.getUserRoles(userId);
+    const permissions: Permission[] = [];
+    
+    for (const role of userRoles) {
+      const rolePermissions = await this.getRolePermissions(role.id);
+      permissions.push(...rolePermissions);
+    }
+    
+    return permissions;
+  }
+
+  /**
+   * Clear permission cache for user
+   * @param userId - User identifier
+   */
+  clearUserCache(userId: string): void {
+    for (const [key] of this.permissionCache.entries()) {
+      if (key.startsWith(`${userId}:`)) {
+        this.permissionCache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all permission cache
+   */
+  clearAllCache(): void {
+    this.permissionCache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   * @returns Cache statistics
+   */
+  getCacheStats(): { size: number; hitRate: number } {
+    return {
+      size: this.permissionCache.size,
+      hitRate: 0
+    };
+  }
+
+  /**
+   * Check direct user permissions
+   * @param permissions - User permissions
+   * @param resource - Resource name
+   * @param action - Action name
+   * @param context - Permission context
+   * @returns Permission check result
+   * @private
+   */
+  private checkDirectPermission(
+    permissions: Permission[],
+    resource: string,
+    action: string,
+    context: PermissionContext
+  ): PermissionCheckResult {
+    for (const permission of permissions) {
+      if (permission.resource === resource && permission.action === action) {
+        // Check conditions if present
+        if (permission.conditions && Object.keys(permission.conditions).length > 0) {
+          const conditionsMet = this.evaluateConditions(permission.conditions, context);
+          
+          // eslint-disable-next-line max-depth
+          if (conditionsMet) {
+            return {
+              granted: true,
+              reason: 'Direct permission with conditions met',
+              matchedPermission: permission,
+              conditions: permission.conditions
+            };
+          }
+        } else {
+          return {
+            granted: true,
+            reason: 'Direct permission without conditions',
+            matchedPermission: permission
+          };
+        }
+      }
+    }
+
+    return {
+      granted: false,
+      reason: 'No direct permission found'
+    };
+  }
+
+  /**
+   * Check role-based permissions
+   * @param userId - User identifier
+   * @param resource - Resource name
+   * @param action - Action name
+   * @param context - Permission context
+   * @returns Permission check result
+   * @private
+   */
+  private async checkRoleBasedPermission(
+    userId: string,
+    resource: string,
+    action: string,
+    context: PermissionContext
+  ): Promise<PermissionCheckResult> {
+    if (!this.roleRepository) {
+      return { granted: false, reason: 'RoleRepository not configured' };
+    }
+    
+    const userRoles = await this.getUserRoles(userId);
+    
+    for (const role of userRoles) {
+      const rolePermissions = await this.getRolePermissions(role.id);
+      const result = this.checkDirectPermission(rolePermissions, resource, action, context);
+      
+      if (result.granted) {
+        return {
+          ...result,
+          reason: `Role-based permission from role: ${role.name}`
+        };
+      }
+    }
+
+    return {
+      granted: false,
+      reason: 'No role-based permission found'
+    };
+  }
+
+  /**
+   * Check wildcard permissions
+   * @param permissions - User permissions
+   * @param resource - Resource name
+   * @param action - Action name
+   * @param context - Permission context
+   * @returns Permission check result
+   * @private
+   */
+  private checkWildcardPermission(
+    permissions: Permission[],
+    resource: string,
+    action: string,
+    context: PermissionContext
+  ): PermissionCheckResult {
+    // Check for wildcard permissions like "campaigns:*" or "*:read"
+    for (const permission of permissions) {
+      const resourceMatch = permission.resource === '*' || permission.resource === resource;
+      const actionMatch = permission.action === '*' || permission.action === action;
+      
+      if (resourceMatch && actionMatch) {
+        // Check conditions if present
+        if (permission.conditions && Object.keys(permission.conditions).length > 0) {
+          const conditionsMet = this.evaluateConditions(permission.conditions, context);
+          
+          // eslint-disable-next-line max-depth
+          if (conditionsMet) {
+            return {
+              granted: true,
+              reason: 'Wildcard permission with conditions met',
+              matchedPermission: permission,
+              conditions: permission.conditions
+            };
+          }
+        } else {
+          return {
+            granted: true,
+            reason: 'Wildcard permission without conditions',
+            matchedPermission: permission
+          };
+        }
+      }
+    }
+
+    return {
+      granted: false,
+      reason: 'No wildcard permission found'
+    };
+  }
+
+  /**
+   * Evaluate permission conditions
+   * @param conditions - Permission conditions
+   * @param context - Permission context
+   * @returns True if conditions are met
+   * @private
+   */
+  private evaluateConditions(conditions: Record<string, unknown>, context: PermissionContext): boolean {
+    for (const [key, expectedValue] of Object.entries(conditions)) {
+      const contextValue = context[key];
+      
+      if (contextValue !== expectedValue) {
+        return false;
+      }
+    }
+    
+    return true;
+  }
+
+  /**
+   * Get user roles
+   * @param userId - User identifier
+   * @returns Array of user roles
+   * @private
+   */
+  private async getUserRoles(userId: string): Promise<Role[]> {
+    if (!this.userRepository) {
+      return [];
+    }
+    
+    return await this.userRepository.getUserRoles(userId);
+  }
+
+  /**
+   * Get role permissions
+   * @param roleId - Role identifier
+   * @returns Array of role permissions
+   * @private
+   */
+  private async getRolePermissions(roleId: string): Promise<Permission[]> {
+    if (!this.roleRepository) {
+      return [];
+    }
+    
+    return await this.roleRepository.getRolePermissions(roleId);
+  }
+
+  /**
+   * Generate cache key
+   * @param userId - User identifier
+   * @param resource - Resource name
+   * @param action - Action name
+   * @param context - Permission context
+   * @returns Cache key
+   * @private
+   */
+  private getCacheKey(userId: string, resource: string, action: string, context: PermissionContext): string {
+    const contextHash = JSON.stringify(context);
+    return `${userId}:${resource}:${action}:${contextHash}`;
+  }
+
+  /**
+   * Cache result and return
+   * @param userId - User identifier
+   * @param resource - Resource name
+   * @param action - Action name
+   * @param context - Permission context
+   * @param result - Permission check result
+   * @returns Permission check result
+   * @private
+   */
+  // eslint-disable-next-line max-params
+  private cacheAndReturn(
+    userId: string,
+    resource: string,
+    action: string,
+    context: PermissionContext,
+    result: PermissionCheckResult
+  ): PermissionCheckResult {
+    if (this.config.enableCaching) {
+      const cacheKey = this.getCacheKey(userId, resource, action, context);
+      this.permissionCache.set(cacheKey, {
+        result,
+        expires: Date.now() + this.config.cacheTTL * NUMERIX.THOUSAND
+      });
+    }
+
+    return result;
+  }
+}