@plyaz/auth 1.0.0

package/src/rbac/role-hierarchy.ts

@@ -0,0 +1,545 @@
+/**
+ * @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();
+ * await hierarchy.addRole('admin', 100);
+ * await hierarchy.addRole('moderator', 50);
+ *
+ * const hasPermission = await hierarchy.checkInheritedPermission(
+ *   'admin', 'moderator'
+ * );
+ * ```
+ */
+
+import type { Role, RoleHierarchyConfig, RoleNode } from "@plyaz/types";
+
+// /**
+//  * Role hierarchy node
+//  */
+// export interface RoleNode {
+//   /** Role information */
+//   role: Role;
+//   /** Parent roles (higher hierarchy) */
+//   parents: Set<string>;
+//   /** Child roles (lower hierarchy) */
+//   children: Set<string>;
+//   /** Direct permissions */
+//   permissions: Set<string>;
+//   /** Inherited permissions (computed) */
+//   inheritedPermissions?: Set<string>;
+// }
+
+// /**
+//  * Role hierarchy configuration
+//  */
+// export interface RoleHierarchyConfig {
+//   /** Enable permission inheritance */
+//   enableInheritance: boolean;
+//   /** Maximum hierarchy depth */
+//   maxDepth: number;
+//   /** Enable circular dependency detection */
+//   detectCircular: boolean;
+//   /** Cache inherited permissions */
+//   cacheInheritance: boolean;
+// }
+
+/**
+ * Role hierarchy manager implementation
+ * Manages role relationships and permission inheritance
+ */
+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
+   * @param role - Role to add
+   * @returns Promise that resolves when role is added
+   */
+  async addRole(role: Role): Promise<void> {
+    const roleNode: RoleNode = {
+      role,
+      parents: new Set(),
+      children: new Set(),
+      permissions: new Set(),
+    };
+
+    this.roles.set(role.id, roleNode);
+
+    // Clear cache when hierarchy changes
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.clear();
+    }
+  }
+
+  /**
+   * Remove role from hierarchy
+   * @param roleId - Role identifier
+   * @returns Promise that resolves when role is removed
+   */
+  async removeRole(roleId: string): Promise<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
+   * @param childRoleId - Child role identifier
+   * @param parentRoleId - Parent role identifier
+   * @returns Promise that resolves when relationship is added
+   */
+  async addRoleRelationship(
+    childRoleId: string,
+    parentRoleId: string
+  ): Promise<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 &&
+      (await this.wouldCreateCircular(childRoleId, parentRoleId))
+    ) {
+      throw new Error("Adding relationship would create circular dependency");
+    }
+
+    // Check hierarchy depth
+    const depth = await this.calculateDepth(parentRoleId);
+    if (depth >= this.config.maxDepth) {
+      throw new Error("Maximum hierarchy depth exceeded");
+    }
+
+    // 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
+   * @param childRoleId - Child role identifier
+   * @param parentRoleId - Parent role identifier
+   * @returns Promise that resolves when relationship is removed
+   */
+  async removeRoleRelationship(
+    childRoleId: string,
+    parentRoleId: string
+  ): Promise<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();
+    }
+  }
+
+  /**
+   * Check if role inherits from another role
+   * @param roleId - Role identifier
+   * @param ancestorRoleId - Ancestor role identifier
+   * @returns True if role inherits from ancestor
+   */
+  async inheritsFrom(roleId: string, ancestorRoleId: string): Promise<boolean> {
+    if (roleId === ancestorRoleId) {
+      return true;
+    }
+
+    const ancestors = await this.getAncestors(roleId);
+    return ancestors.has(ancestorRoleId);
+  }
+
+  /**
+   * Get all ancestor roles (roles this role inherits from)
+   * @param roleId - Role identifier
+   * @returns Set of ancestor role IDs
+   */
+  async getAncestors(roleId: string): Promise<Set<string>> {
+    if (this.config.cacheInheritance) {
+      const cached = this.hierarchyCache.get(`ancestors:${roleId}`);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    const ancestors = new Set<string>();
+    const visited = new Set<string>();
+
+    await this.collectAncestors(roleId, ancestors, visited);
+
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.set(`ancestors:${roleId}`, ancestors);
+    }
+
+    return ancestors;
+  }
+
+  /**
+   * Get all descendant roles (roles that inherit from this role)
+   * @param roleId - Role identifier
+   * @returns Set of descendant role IDs
+   */
+  async getDescendants(roleId: string): Promise<Set<string>> {
+    if (this.config.cacheInheritance) {
+      const cached = this.hierarchyCache.get(`descendants:${roleId}`);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    const descendants = new Set<string>();
+    const visited = new Set<string>();
+
+    await this.collectDescendants(roleId, descendants, visited);
+
+    if (this.config.cacheInheritance) {
+      this.hierarchyCache.set(`descendants:${roleId}`, descendants);
+    }
+
+    return descendants;
+  }
+
+  /**
+   * Get effective permissions for role (including inherited)
+   * @param roleId - Role identifier
+   * @returns Set of permission IDs
+   */
+  async getEffectivePermissions(roleId: string): Promise<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 = await 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
+   * @returns Validation result with any issues found
+   */
+  async validateHierarchy(): Promise<{
+    valid: boolean;
+    issues: string[];
+  }> {
+    const issues: string[] = [];
+
+    // Check for circular dependencies
+    if (this.config.detectCircular) {
+      for (const roleId of this.roles.keys()) {
+        if (await this.hasCircularDependency(roleId)) {
+          issues.push(`Circular dependency detected involving role: ${roleId}`);
+        }
+      }
+    }
+
+    // Check hierarchy depth
+    for (const roleId of this.roles.keys()) {
+      const depth = await this.calculateDepth(roleId);
+      if (depth > this.config.maxDepth) {
+        issues.push(`Role ${roleId} exceeds maximum hierarchy depth: ${depth}`);
+      }
+    }
+
+    // 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
+   * @returns Hierarchy statistics
+   */
+  getStats(): {
+    totalRoles: number;
+    maxDepth: number;
+    rootRoles: number;
+    leafRoles: number;
+  } {
+    let maxDepth = 0;
+    let rootRoles = 0;
+    let leafRoles = 0;
+
+    for (const roleNode of this.roles.values()) {
+      if (roleNode.parents.size === 0) {
+        rootRoles++;
+      }
+
+      if (roleNode.children.size === 0) {
+        leafRoles++;
+      }
+    }
+
+    return {
+      totalRoles: this.roles.size,
+      maxDepth,
+      rootRoles,
+      leafRoles,
+    };
+  }
+
+  /**
+   * Collect ancestors recursively
+   * @param roleId - Role identifier
+   * @param ancestors - Set to collect ancestors
+   * @param visited - Set to track visited roles
+   * @private
+   */
+  private async collectAncestors(
+    roleId: string,
+    ancestors: Set<string>,
+    visited: Set<string>
+  ): Promise<void> {
+    if (visited.has(roleId)) {
+      return;
+    }
+
+    visited.add(roleId);
+    const roleNode = this.roles.get(roleId);
+
+    if (!roleNode) {
+      return;
+    }
+
+    for (const parentId of roleNode.parents) {
+      ancestors.add(parentId);
+      await this.collectAncestors(parentId, ancestors, visited);
+    }
+  }
+
+  /**
+   * Collect descendants recursively
+   * @param roleId - Role identifier
+   * @param descendants - Set to collect descendants
+   * @param visited - Set to track visited roles
+   * @private
+   */
+  private async collectDescendants(
+    roleId: string,
+    descendants: Set<string>,
+    visited: Set<string>
+  ): Promise<void> {
+    if (visited.has(roleId)) {
+      return;
+    }
+
+    visited.add(roleId);
+    const roleNode = this.roles.get(roleId);
+
+    if (!roleNode) {
+      return;
+    }
+
+    for (const childId of roleNode.children) {
+      descendants.add(childId);
+      await this.collectDescendants(childId, descendants, visited);
+    }
+  }
+
+  /**
+   * Check if adding relationship would create circular dependency
+   * @param childRoleId - Child role identifier
+   * @param parentRoleId - Parent role identifier
+   * @returns True if would create circular dependency
+   * @private
+   */
+  private async wouldCreateCircular(
+    childRoleId: string,
+    parentRoleId: string
+  ): Promise<boolean> {
+    // If parent inherits from child, adding this relationship would create a circle
+    return await this.inheritsFrom(parentRoleId, childRoleId);
+  }
+
+  /**
+   * Check for circular dependency starting from role
+   * @param roleId - Role identifier
+   * @returns True if circular dependency exists
+   * @private
+   */
+  private async hasCircularDependency(roleId: string): Promise<boolean> {
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    return await this.detectCircularRecursive(roleId, visited, recursionStack);
+  }
+
+  /**
+   * Detect circular dependency recursively
+   * @param roleId - Current role identifier
+   * @param visited - Set of visited roles
+   * @param recursionStack - Current recursion stack
+   * @returns True if circular dependency found
+   * @private
+   */
+  private async detectCircularRecursive(
+    roleId: string,
+    visited: Set<string>,
+    recursionStack: Set<string>
+  ): Promise<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 (
+          await 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
+   * @param roleId - Role identifier
+   * @returns Hierarchy depth
+   * @private
+   */
+  private async calculateDepth(roleId: string): Promise<number> {
+    const ancestors = await this.getAncestors(roleId);
+    return ancestors.size;
+  }
+
+  /**
+   * Build role tree recursively
+   * @param roleId - Role identifier
+   * @returns Role tree node
+   * @private
+   */
+}

package/src/rbac/role.manager.ts

@@ -0,0 +1,75 @@
+import type { RoleConfig, UserRepository } from '@plyaz/types';
+
+
+// export interface RoleConfig {
+//   hierarchyEnabled: boolean;
+//   cacheEnabled: boolean;
+//   cacheTTL: number;
+// }
+
+export class RoleManager {
+  private roleCache = new Map<string, { roles: string[]; expires: number }>();
+
+  constructor(
+    private userRepo: UserRepository,
+    private config: RoleConfig
+  ) {}
+
+  async assignRole(userId: string, role: string, assignedBy?: string): Promise<void> {
+    await this.userRepo.assignRole(userId, role, assignedBy);
+    this.invalidateCache(userId);
+  }
+
+  async removeRole(userId: string, role: string): Promise<void> {
+    await this.userRepo.removeRole(userId, role);
+    this.invalidateCache(userId);
+  }
+
+  async getUserRoles(userId: string): Promise<string[]> {
+    if (this.config.cacheEnabled) {
+      const cached = this.roleCache.get(userId);
+      if (cached && cached.expires > Date.now()) {
+        return cached.roles;
+      }
+    }
+
+    const roles = await this.userRepo.getUserRoles(userId);
+    
+    if (this.config.cacheEnabled) {
+      this.roleCache.set(userId, {
+        roles,
+        expires: Date.now() + this.config.cacheTTL
+      });
+    }
+
+    return roles;
+  }
+
+  async hasRole(userId: string, role: string): Promise<boolean> {
+    const roles = await this.getUserRoles(userId);
+    return roles.includes(role);
+  }
+
+  async hasAnyRole(userId: string, roles: string[]): Promise<boolean> {
+    const userRoles = await this.getUserRoles(userId);
+    return roles.some(role => userRoles.includes(role));
+  }
+
+  async hasPermission(userId: string, permission: string): Promise<boolean> {
+    const roles = await this.getUserRoles(userId);
+    return this.userRepo.checkPermission(roles, permission);
+  }
+
+  private invalidateCache(userId: string): void {
+    this.roleCache.delete(userId);
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [userId, data] of this.roleCache.entries()) {
+      if (data.expires < now) {
+        this.roleCache.delete(userId);
+      }
+    }
+  }
+}

package/src/security/csrf/csrf.protection.ts

@@ -0,0 +1,37 @@
+import { NUMERIX } from '@plyaz/config';
+import { randomBytes } from 'crypto';
+
+export class CSRFProtection {
+  private tokens = new Map<string, { token: string; expires: number }>();
+
+  generateToken(sessionId: string): string {
+    const thirtyTwo = 32;
+    const token = randomBytes(thirtyTwo).toString('hex');
+    const expires = Date.now() + (NUMERIX.SIXTY * NUMERIX.SIXTY * NUMERIX.THOUSAND); // 1 hour
+    
+    this.tokens.set(sessionId, { token, expires });
+    return token;
+  }
+
+  validateToken(sessionId: string, token: string): boolean {
+    const stored = this.tokens.get(sessionId);
+    if (!stored || stored.expires < Date.now()) {
+      this.tokens.delete(sessionId);
+      return false;
+    }
+    
+    return stored.token === token;
+  }
+
+  removeToken(sessionId: string): void {
+    this.tokens.delete(sessionId);
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [sessionId, data] of this.tokens.entries()) {
+      if (data.expires < now) {
+        this.tokens.delete(sessionId);
+      }
+    }
+  }}

package/src/security/index.ts

@@ -0,0 +1,3 @@
+export * from "./rate-limiting/auth.module";
+export * from "./rate-limiting/auth/auth.controller"
+export * from './csrf/csrf.protection';

package/src/security/rate-limiting/auth/auth.controller.ts

@@ -0,0 +1,12 @@
+
+import { Controller, UseGuards } from "@nestjs/common";
+import { RateLimiterGuard } from "../../../server/guards/custom-throttler.guard";
+
+
+@Controller("auth")
+export class AuthController {
+  @UseGuards(RateLimiterGuard)
+  testAuthEndPoint() : {message:string} {
+    return { message: 'Test endpoint works' };
+  }
+}