@plyaz/auth 1.0.0

package/src/db/repositories/role.repository.ts

@@ -0,0 +1,519 @@
+/**
+ * @fileoverview Role hierarchy manager for @plyaz/auth
+ * @module @plyaz/auth/rbac/role-hierarchy
+ * 
+ * @description
+ * Manages role hierarchy and inheritance for role-based access control.
+ * Handles role precedence, permission inheritance, and hierarchical
+ * role validation. Enables complex organizational structures with
+ * inherited permissions and role-based delegation.
+ * 
+ * @example
+ * ```typescript
+ * import { RoleHierarchy } from '@plyaz/auth';
+ * 
+ * const hierarchy = new RoleHierarchy();
+ * hierarchy.addRole({ id: 'admin', name: 'Admin', permissions: ['*'] });
+ * hierarchy.addRole({ id: 'moderator', name: 'Moderator', permissions: ['read', 'write'] });
+ * hierarchy.addRoleRelationship('moderator', 'admin');
+ * 
+ * const hasAdminAccess = hierarchy.hasPermission('moderator', 'delete');
+ * console.log(hierarchy.getHierarchyTree());
+ * ```
+ */
+
+import type { Role, RoleHierarchyConfig, RoleNode } from "@plyaz/types";
+
+/**
+ * Role hierarchy manager implementation
+ * Manages role relationships and permission inheritance
+ */
+
+  interface AddRole extends Role {
+    permissions?:[]
+  }
+
+export class RoleHierarchy {
+  private readonly config: RoleHierarchyConfig;
+  private readonly roles = new Map<string, RoleNode>();
+  private readonly hierarchyCache = new Map<string, Set<string>>();
+
+  constructor(config: Partial<RoleHierarchyConfig> = {}) {
+    this.config = {
+      enableInheritance: true,
+      maxDepth: 10,
+      detectCircular: true,
+      cacheInheritance: true,
+      ...config
+    };
+  }
+
+  /**
+   * Add role to hierarchy
+   */
+
+  addRole(role: AddRole): void {
+    const roleNode: RoleNode = {
+      role,
+      parents: new Set(),
+      children: new Set(),
+      permissions: new Set(role.permissions ?? [])
+    };
+
+    this.roles.set(role.id, roleNode);
+    
+    // Clear cache when hierarchy changes
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.clear();
+    }
+  }
+
+  /**
+   * Remove role from hierarchy
+   */
+  removeRole(roleId: string): void {
+    const roleNode = this.roles.get(roleId);
+    
+    if (!roleNode) {
+      return;
+    }
+
+    // Remove from parent-child relationships
+    for (const parentId of roleNode.parents) {
+      const parent = this.roles.get(parentId);
+      if (parent) {
+        parent.children.delete(roleId);
+      }
+    }
+
+    for (const childId of roleNode.children) {
+      const child = this.roles.get(childId);
+      if (child) {
+        child.parents.delete(roleId);
+      }
+    }
+
+    this.roles.delete(roleId);
+    
+    // Clear cache when hierarchy changes
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.clear();
+    }
+  }
+
+  /**
+   * Add parent-child relationship between roles
+   */
+  addRoleRelationship(childRoleId: string, parentRoleId: string): void {
+    const childRole = this.roles.get(childRoleId);
+    const parentRole = this.roles.get(parentRoleId);
+
+    if (!childRole || !parentRole) {
+      throw new Error('Role not found');
+    }
+
+    // Check for circular dependencies
+    if (this.config.detectCircular && this.inheritsFrom(parentRoleId, childRoleId)) {
+      throw new Error('Adding relationship would create circular dependency');
+    }
+
+    // Check hierarchy depth
+    const depth = this.calculateDepth(parentRoleId);
+    if (depth >= this.config.maxDepth) {
+      throw new Error(`Maximum hierarchy depth exceeded: ${depth}/${this.config.maxDepth}`);
+    }
+
+    // Add relationship
+    childRole.parents.add(parentRoleId);
+    parentRole.children.add(childRoleId);
+
+    // Clear cache when hierarchy changes
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.clear();
+    }
+  }
+
+  /**
+   * Remove parent-child relationship between roles
+   */
+  removeRoleRelationship(childRoleId: string, parentRoleId: string): void {
+    const childRole = this.roles.get(childRoleId);
+    const parentRole = this.roles.get(parentRoleId);
+
+    if (childRole) {
+      childRole.parents.delete(parentRoleId);
+    }
+
+    if (parentRole) {
+      parentRole.children.delete(childRoleId);
+    }
+
+    // Clear cache when hierarchy changes
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.clear();
+    }
+  }
+
+  /**
+   * Add permission to role
+   */
+  addPermission(roleId: string, permission: string): void {
+    const roleNode = this.roles.get(roleId);
+    if (roleNode) {
+      roleNode.permissions.add(permission);
+      if (this.config.cacheInheritance) {
+        this.hierarchyCache.clear();
+      }
+    }
+  }
+
+  /**
+   * Remove permission from role
+   */
+  removePermission(roleId: string, permission: string): void {
+    const roleNode = this.roles.get(roleId);
+    if (roleNode) {
+      roleNode.permissions.delete(permission);
+      if (this.config.cacheInheritance) {
+        this.hierarchyCache.clear();
+      }
+    }
+  }
+
+  /**
+   * Check if role has specific permission (including inherited)
+   */
+  hasPermission(roleId: string, permission: string): boolean {
+    if (!this.config.enableInheritance) {
+      const roleNode = this.roles.get(roleId);
+      return roleNode ? roleNode.permissions.has(permission) : false;
+    }
+
+    return this.getEffectivePermissions(roleId).has(permission);
+  }
+
+  /**
+   * Check if role inherits from another role
+   */
+  inheritsFrom(roleId: string, ancestorRoleId: string): boolean {
+    if (roleId === ancestorRoleId) {
+      return true;
+    }
+
+    const ancestors = this.getAncestors(roleId);
+    return ancestors.has(ancestorRoleId);
+  }
+
+  /**
+   * Get all ancestor roles (roles this role inherits from)
+   */
+  getAncestors(roleId: string): Set<string> {
+    if (this.config.cacheInheritance) {
+      const cached = this.hierarchyCache.get(`ancestors:${roleId}`);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    const ancestors = this.collectAncestorsSync(roleId);
+
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.set(`ancestors:${roleId}`, ancestors);
+    }
+
+    return ancestors;
+  }
+
+  /**
+   * Get all descendant roles (roles that inherit from this role)
+   */
+  getDescendants(roleId: string): Set<string> {
+    if (this.config.cacheInheritance) {
+      const cached = this.hierarchyCache.get(`descendants:${roleId}`);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    const descendants = this.collectDescendantsSync(roleId);
+
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.set(`descendants:${roleId}`, descendants);
+    }
+
+    return descendants;
+  }
+
+  /**
+   * Get effective permissions for role (including inherited)
+   */
+  getEffectivePermissions(roleId: string): Set<string> {
+    if (!this.config.enableInheritance) {
+      const roleNode = this.roles.get(roleId);
+      return roleNode ? roleNode.permissions : new Set();
+    }
+
+    if (this.config.cacheInheritance) {
+      const cached = this.hierarchyCache.get(`permissions:${roleId}`);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    const effectivePermissions = new Set<string>();
+    const roleNode = this.roles.get(roleId);
+
+    if (!roleNode) {
+      return effectivePermissions;
+    }
+
+    // Add direct permissions
+    for (const permission of roleNode.permissions) {
+      effectivePermissions.add(permission);
+    }
+
+    // Add inherited permissions
+    const ancestors = this.getAncestors(roleId);
+    for (const ancestorId of ancestors) {
+      const ancestorNode = this.roles.get(ancestorId);
+      if (ancestorNode) {
+        for (const permission of ancestorNode.permissions) {
+          effectivePermissions.add(permission);
+        }
+      }
+    }
+
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.set(`permissions:${roleId}`, effectivePermissions);
+    }
+
+    return effectivePermissions;
+  }
+
+
+  /**
+   * Validate hierarchy integrity
+   */
+  validateHierarchy(): {
+    valid: boolean;
+    issues: string[];
+  } {
+    const issues: string[] = [];
+
+    // Check for circular dependencies
+    if (this.config.detectCircular) {
+      for (const roleId of this.roles.keys()) {
+        if (this.hasCircularDependency(roleId)) {
+          issues.push(`Circular dependency detected involving role: ${roleId}`);
+        }
+      }
+    }
+
+    // Check hierarchy depth
+    for (const roleId of this.roles.keys()) {
+      const depth = this.calculateDepth(roleId);
+      if (depth > this.config.maxDepth) {
+        issues.push(`Role ${roleId} exceeds maximum hierarchy depth: ${depth}/${this.config.maxDepth}`);
+      }
+    }
+
+    // Check for orphaned relationships
+    for (const [roleId, roleNode] of this.roles.entries()) {
+      for (const parentId of roleNode.parents) {
+        if (!this.roles.has(parentId)) {
+          issues.push(`Role ${roleId} references non-existent parent: ${parentId}`);
+        }
+      }
+
+      for (const childId of roleNode.children) {
+        if (!this.roles.has(childId)) {
+          issues.push(`Role ${roleId} references non-existent child: ${childId}`);
+        }
+      }
+    }
+
+    return {
+      valid: issues.length === 0,
+      issues
+    };
+  }
+
+  /**
+   * Clear hierarchy cache
+   */
+  clearCache(): void {
+    this.hierarchyCache.clear();
+  }
+
+  /**
+   * Get hierarchy statistics
+   */
+  getStats(): {
+    totalRoles: number;
+    maxDepth: number;
+    rootRoles: number;
+    leafRoles: number;
+    avgPermissions: number;
+  } {
+    let maxDepth = 0;
+    let rootRoles = 0;
+    let leafRoles = 0;
+    let totalPermissions = 0;
+
+    for (const [roleId, roleNode] of this.roles.entries()) {
+      if (roleNode.parents.size === 0) rootRoles++;
+      if (roleNode.children.size === 0) leafRoles++;
+      
+      const depth = this.calculateDepth(roleId);
+      maxDepth = Math.max(maxDepth, depth);
+      totalPermissions += roleNode.permissions.size;
+    }
+
+    return {
+      totalRoles: this.roles.size,
+      maxDepth,
+      rootRoles,
+      leafRoles,
+      avgPermissions: this.roles.size > 0 ? Math.round(totalPermissions / this.roles.size) : 0
+    };
+  }
+
+  // ==================== PRIVATE METHODS ====================
+
+  /**
+   * Collect ancestors iteratively (synchronous)
+   */
+  private collectAncestorsSync(roleId: string): Set<string> {
+    const ancestors = new Set<string>();
+    const stack: string[] = [];
+    const visited = new Set<string>();
+
+    const roleNode = this.roles.get(roleId);
+    if (!roleNode) return ancestors;
+
+    for (const parentId of roleNode.parents) {
+      stack.push(parentId);
+    }
+
+    while (stack.length > 0) {
+      const parentId = stack.pop()!;
+      if (visited.has(parentId)) continue;
+
+      visited.add(parentId);
+      ancestors.add(parentId);
+
+      const parentNode = this.roles.get(parentId);
+      if (parentNode) {
+        for (const grandparentId of parentNode.parents) {
+          stack.push(grandparentId);
+        }
+      }
+    }
+
+    return ancestors;
+  }
+
+  /**
+   * Collect descendants iteratively (synchronous)
+   */
+  private collectDescendantsSync(roleId: string): Set<string> {
+    const descendants = new Set<string>();
+    const stack: string[] = [];
+    const visited = new Set<string>();
+
+    const roleNode = this.roles.get(roleId);
+    if (!roleNode) return descendants;
+
+    for (const childId of roleNode.children) {
+      stack.push(childId);
+    }
+
+    while (stack.length > 0) {
+      const childId = stack.pop()!;
+      if (visited.has(childId)) continue;
+
+      visited.add(childId);
+      descendants.add(childId);
+
+      const childNode = this.roles.get(childId);
+      if (childNode) {
+        for (const grandchildId of childNode.children) {
+          stack.push(grandchildId);
+        }
+      }
+    }
+
+    return descendants;
+  }
+
+  /**
+   * Check for circular dependency starting from role
+   */
+  private hasCircularDependency(roleId: string): boolean {
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+    return this.detectCircularRecursive(roleId, visited, recursionStack);
+  }
+
+  /**
+   * Detect circular dependency recursively
+   */
+  private detectCircularRecursive(
+    roleId: string,
+    visited: Set<string>,
+    recursionStack: Set<string>
+  ): boolean {
+    visited.add(roleId);
+    recursionStack.add(roleId);
+
+    const roleNode = this.roles.get(roleId);
+    if (!roleNode) {
+      recursionStack.delete(roleId);
+      return false;
+    }
+
+    for (const parentId of roleNode.parents) {
+      if (!visited.has(parentId)) {
+        if (this.detectCircularRecursive(parentId, visited, recursionStack)) {
+          return true;
+        }
+      } else if (recursionStack.has(parentId)) {
+        return true; // Circular dependency found
+      }
+    }
+
+    recursionStack.delete(roleId);
+    return false;
+  }
+
+  /**
+   * Calculate hierarchy depth for role (synchronous)
+   */
+  private calculateDepth(roleId: string): number {
+    return this.collectAncestorsSync(roleId).size;
+  }
+
+  /**
+   * Build role tree recursively
+   */
+  private buildRoleTree(roleId: string): { role: Role; children: Record<string, unknown> } | null {
+    const roleNode = this.roles.get(roleId);
+    if (!roleNode) {
+      return null;
+    }
+
+    const tree: { role: Role; children: Record<string, unknown> } = {
+      role: roleNode.role,
+      children: {}
+    };
+
+    for (const childId of roleNode.children) {
+      const childTree = this.buildRoleTree(childId);
+      if (childTree) {
+        tree.children[childId] = childTree;
+      }
+    }
+
+    return tree;
+  }
+}