@plyaz/auth 1.0.0

package/src/rbac/dynamic-roles.ts

@@ -0,0 +1,552 @@
+/**
+ * @fileoverview Dynamic roles manager for @plyaz/auth
+ * @module @plyaz/auth/rbac/dynamic-roles
+ * 
+ * @description
+ * Manages runtime role assignment and modification for role-based access control.
+ * Handles temporary roles, conditional role assignment, and role expiration.
+ * Enables flexible role management without requiring database schema changes.
+ * 
+ * @example
+ * ```typescript
+ * import { DynamicRoles } from '@plyaz/auth';
+ * 
+ * const dynamicRoles = new DynamicRoles();
+ * 
+ * // Assign temporary role
+ * await dynamicRoles.assignTemporaryRole(
+ *   userId, 
+ *   'campaign_moderator', 
+ *   { campaignId: '123' },
+ *   new Date(Date.now() + 24 * 60 * 60 * 1000) // 24 hours
+ * );
+ * ```
+ */
+
+import { NUMERIX } from '@plyaz/config';
+import { AUTH_EVENTS } from '@plyaz/types';
+
+/**
+ * Dynamic role assignment
+ */
+export interface DynamicRoleAssignment {
+  /** Assignment ID */
+  id: string;
+  /** User ID */
+  userId: string;
+  /** Role ID or name */
+  roleId: string;
+  /** Assignment conditions */
+  conditions?: Record<string, string>;
+  /** Assignment expiration */
+  expiresAt?: Date;
+  /** Assignment reason */
+  reason?: string;
+  /** Assigned by user ID */
+  assignedBy?: string;
+  /** Assignment metadata */
+  metadata?: Record<string, string>;
+  /** Created at */
+  createdAt: Date;
+  /** Is active */
+  isActive: boolean;
+}
+
+/**
+ * Role condition evaluator function
+ */
+export type RoleConditionEvaluator = (
+  userId: string,
+  conditions: Record<string, string>,
+  context?: Record<string, string>
+) => Promise<boolean>;
+
+/**
+ * Dynamic roles configuration
+ */
+export interface DynamicRolesConfig {
+  /** Enable role expiration */
+  enableExpiration: boolean;
+  /** Default role TTL in seconds */
+  defaultTTL: number;
+  /** Enable condition evaluation */
+  enableConditions: boolean;
+  /** Maximum assignments per user */
+  maxAssignmentsPerUser: number;
+  /** Enable audit logging */
+  enableAuditLog: boolean;
+}
+
+/**
+ * Dynamic roles manager implementation
+ * Manages runtime role assignments with conditions and expiration
+ */
+export class DynamicRoles {
+  private readonly config: DynamicRolesConfig;
+  private readonly assignments = new Map<string, DynamicRoleAssignment>();
+  private readonly userAssignments = new Map<string, Set<string>>();
+  private readonly conditionEvaluators = new Map<string, RoleConditionEvaluator>();
+  private cleanupTimer?: globalThis.NodeJS.Timeout;
+
+  constructor(config: Partial<DynamicRolesConfig> = {}) {
+    this.config = {
+      enableExpiration: true,
+      defaultTTL: 86400, // 24 hours
+      enableConditions: true,
+      maxAssignmentsPerUser: 50,
+      enableAuditLog: true,
+      ...config
+    };
+
+    // Start cleanup timer if expiration is enabled
+    if (this.config.enableExpiration) {
+      this.startCleanupTimer();
+    }
+  }
+
+  /**
+   * Assign role to user
+   * @param userId - User identifier
+   * @param roleId - Role identifier
+   * @param conditions - Assignment conditions
+   * @param expiresAt - Assignment expiration
+   * @param assignedBy - Assigning user ID
+   * @param reason - Assignment reason
+   * @returns Assignment ID
+   */
+  // eslint-disable-next-line max-params
+  async assignRole(
+    userId: string,
+    roleId: string,
+    conditions?: Record<string, string>,
+    expiresAt?: Date,
+    assignedBy?: string,
+    reason?: string
+  ): Promise<string> {
+    // Check assignment limits
+    await this.enforceAssignmentLimits(userId);
+
+    // Generate assignment ID
+    const assignmentId = this.generateAssignmentId();
+
+    // Create assignment
+    const assignment: DynamicRoleAssignment = {
+      id: assignmentId,
+      userId,
+      roleId,
+      conditions,
+      expiresAt: expiresAt ?? (this.config.enableExpiration ? 
+        new Date(Date.now() + this.config.defaultTTL * NUMERIX.THOUSAND) : undefined),
+      reason,
+      assignedBy,
+      createdAt: new Date(),
+      isActive: true
+    };
+
+    // Store assignment
+    this.assignments.set(assignmentId, assignment);
+
+    // Track user assignments
+    if (!this.userAssignments.has(userId)) {
+      this.userAssignments.set(userId, new Set());
+    }
+    this.userAssignments.get(userId)!.add(assignmentId);
+
+    // Emit event
+    if (this.config.enableAuditLog) {
+      this.emitRoleAssignedEvent(assignment);
+    }
+
+    return assignmentId;
+  }
+
+  /**
+   * Assign temporary role to user
+   * @param userId - User identifier
+   * @param roleId - Role identifier
+   * @param conditions - Assignment conditions
+   * @param duration - Duration in seconds
+   * @param assignedBy - Assigning user ID
+   * @param reason - Assignment reason
+   * @returns Assignment ID
+   */
+  // eslint-disable-next-line max-params
+  async assignTemporaryRole(
+    userId: string,
+    roleId: string,
+    conditions?: Record<string, string>,
+    duration: number = this.config.defaultTTL,
+    assignedBy?: string,
+    reason?: string
+  ): Promise<string> {
+    const expiresAt = new Date(Date.now() + duration * NUMERIX.THOUSAND);
+    
+    return await this.assignRole(
+      userId,
+      roleId,
+      conditions,
+      expiresAt,
+      assignedBy,
+      reason ?? 'Temporary assignment'
+    );
+  }
+
+  /**
+   * Revoke role assignment
+   * @param assignmentId - Assignment identifier
+   * @param revokedBy - Revoking user ID
+   * @param reason - Revocation reason
+   */
+  async revokeAssignment(
+    assignmentId: string,
+    revokedBy?: string,
+    reason?: string
+  ): Promise<void> {
+    const assignment = this.assignments.get(assignmentId);
+    
+    if (!assignment?.isActive) {
+      return;
+    }
+
+    // Deactivate assignment
+    assignment.isActive = false;
+    assignment.metadata = {
+      ...assignment.metadata,
+
+    };
+
+    // Remove from user assignments tracking
+    const userAssignmentSet = this.userAssignments.get(assignment.userId);
+    if (userAssignmentSet) {
+      userAssignmentSet.delete(assignmentId);
+      if (userAssignmentSet.size === 0) {
+        this.userAssignments.delete(assignment.userId);
+      }
+    }
+
+    // Emit event
+    if (this.config.enableAuditLog) {
+      this.emitRoleRevokedEvent(assignment, revokedBy, reason);
+    }
+  }
+
+  /**
+   * Revoke all role assignments for user
+   * @param userId - User identifier
+   * @param revokedBy - Revoking user ID
+   * @param reason - Revocation reason
+   */
+  async revokeAllUserAssignments(
+    userId: string,
+    revokedBy?: string,
+    reason?: string
+  ): Promise<void> {
+    const userAssignmentSet = this.userAssignments.get(userId);
+    
+    if (!userAssignmentSet) {
+      return;
+    }
+
+    const assignmentIds = Array.from(userAssignmentSet);
+    
+    for (const assignmentId of assignmentIds) {
+      await this.revokeAssignment(assignmentId, revokedBy, reason);
+    }
+  }
+
+  /**
+   * Get active roles for user
+   * @param userId - User identifier
+   * @param context - Evaluation context for conditions
+   * @returns Array of active role IDs
+   */
+  async getUserRoles(userId: string, context?: Record<string, string>): Promise<string[]> {
+    const userAssignmentSet = this.userAssignments.get(userId);
+    
+    if (!userAssignmentSet) {
+      return [];
+    }
+
+    const activeRoles: string[] = [];
+    const now = new Date();
+
+    for (const assignmentId of userAssignmentSet) {
+      const assignment = this.assignments.get(assignmentId);
+      
+      if (!assignment?.isActive) {
+        continue;
+      }
+
+      // Check expiration
+      if (assignment.expiresAt && assignment.expiresAt < now) {
+        await this.revokeAssignment(assignmentId, undefined, 'Expired');
+        continue;
+      }
+
+      // Check conditions
+      if (this.config.enableConditions && assignment.conditions) {
+        const conditionsMet = await this.evaluateConditions(
+          userId,
+          assignment.conditions,
+          context
+        );
+        
+        if (!conditionsMet) {
+          continue;
+        }
+      }
+
+      activeRoles.push(assignment.roleId);
+    }
+
+    return activeRoles;
+  }
+
+  /**
+   * Check if user has specific role
+   * @param userId - User identifier
+   * @param roleId - Role identifier
+   * @param context - Evaluation context for conditions
+   * @returns True if user has role
+   */
+  async hasRole(userId: string, roleId: string, context?: Record<string, string>): Promise<boolean> {
+    const userRoles = await this.getUserRoles(userId, context);
+    return userRoles.includes(roleId);
+  }
+
+  /**
+   * Get assignment details
+   * @param assignmentId - Assignment identifier
+   * @returns Assignment details or null
+   */
+  getAssignment(assignmentId: string): DynamicRoleAssignment | null {
+    return this.assignments.get(assignmentId) ?? null;
+  }
+
+  /**
+   * Get all assignments for user
+   * @param userId - User identifier
+   * @param includeInactive - Include inactive assignments
+   * @returns Array of assignments
+   */
+  getUserAssignments(userId: string, includeInactive = false): DynamicRoleAssignment[] {
+    const userAssignmentSet = this.userAssignments.get(userId);
+    
+    if (!userAssignmentSet) {
+      return [];
+    }
+
+    const assignments: DynamicRoleAssignment[] = [];
+
+    for (const assignmentId of userAssignmentSet) {
+      const assignment = this.assignments.get(assignmentId);
+      
+      if (assignment && (includeInactive || assignment.isActive)) {
+        assignments.push(assignment);
+      }
+    }
+
+    return assignments;
+  }
+
+  /**
+   * Register condition evaluator
+   * @param conditionType - Condition type name
+   * @param evaluator - Evaluator function
+   */
+  registerConditionEvaluator(conditionType: string, evaluator: RoleConditionEvaluator): void {
+    this.conditionEvaluators.set(conditionType, evaluator);
+  }
+
+  /**
+   * Extend assignment expiration
+   * @param assignmentId - Assignment identifier
+   * @param newExpiresAt - New expiration date
+   */
+  async extendAssignment(assignmentId: string, newExpiresAt: Date): Promise<void> {
+    const assignment = this.assignments.get(assignmentId);
+    
+    if (!assignment?.isActive) {
+      throw new Error('Assignment not found or inactive');
+    }
+
+    assignment.expiresAt = newExpiresAt;
+    assignment.metadata = {
+      ...assignment.metadata,
+      extendedAt: new Date().toString()
+    };
+  }
+
+  /**
+   * Clean up expired assignments
+   * @returns Number of cleaned assignments
+   */
+  async cleanupExpiredAssignments(): Promise<number> {
+    let cleanedCount = 0;
+    const now = new Date();
+    const expiredAssignments: string[] = [];
+
+    for (const [assignmentId, assignment] of this.assignments.entries()) {
+      if (assignment.isActive && assignment.expiresAt && assignment.expiresAt < now) {
+        expiredAssignments.push(assignmentId);
+      }
+    }
+
+    for (const assignmentId of expiredAssignments) {
+      await this.revokeAssignment(assignmentId, undefined, 'Expired');
+      cleanedCount++;
+    }
+
+    return cleanedCount;
+  }
+
+  /**
+   * Get assignment statistics
+   * @returns Assignment statistics
+   */
+  getStats(): {
+    totalAssignments: number;
+    activeAssignments: number;
+    expiredAssignments: number;
+    usersWithAssignments: number;
+  } {
+    let activeCount = 0;
+    let expiredCount = 0;
+    const now = new Date();
+
+    for (const assignment of this.assignments.values()) {
+      if (assignment.isActive) {
+        if (assignment.expiresAt && assignment.expiresAt < now) {
+          expiredCount++;
+        } else {
+          activeCount++;
+        }
+      }
+    }
+
+    return {
+      totalAssignments: this.assignments.size,
+      activeAssignments: activeCount,
+      expiredAssignments: expiredCount,
+      usersWithAssignments: this.userAssignments.size
+    };
+  }
+
+  /**
+   * Destroy dynamic roles manager
+   */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      globalThis.clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+
+    this.assignments.clear();
+    this.userAssignments.clear();
+    this.conditionEvaluators.clear();
+  }
+
+  /**
+   * Evaluate assignment conditions
+   * @param userId - User identifier
+   * @param conditions - Assignment conditions
+   * @param context - Evaluation context
+   * @returns True if conditions are met
+   * @private
+   */
+  private async evaluateConditions(
+    userId: string,
+    conditions: Record<string, string>,
+    context?: Record<string, string>
+  ): Promise<boolean> {
+    for (const [conditionType, conditionValue] of Object.entries(conditions)) {
+      const evaluator = this.conditionEvaluators.get(conditionType);
+      
+      if (evaluator) {
+        const result = await evaluator(userId, { [conditionType]: conditionValue }, context);
+        if (!result) {
+          return false;
+        }
+      } else {
+        // Default evaluation: simple equality check with context
+        if (context && context[conditionType] !== conditionValue) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Enforce assignment limits per user
+   * @param userId - User identifier
+   * @private
+   */
+  private async enforceAssignmentLimits(userId: string): Promise<void> {
+    const userAssignments = this.getUserAssignments(userId, false);
+    
+    if (userAssignments.length >= this.config.maxAssignmentsPerUser) {
+      throw new Error(`Maximum assignments per user exceeded: ${this.config.maxAssignmentsPerUser}`);
+    }
+  }
+
+  /**
+   * Generate unique assignment ID
+   * @returns Assignment identifier
+   * @private
+   */
+  private generateAssignmentId(): string {
+    return `dyn_${Date.now()}_${Math.random().toString(NUMERIX.THIRTY_SIX).substr(NUMERIX.TWO, NUMERIX.NINE)}`;
+  }
+
+  /**
+   * Start cleanup timer for expired assignments
+   * @private
+   */
+  private startCleanupTimer(): void {
+    // Run cleanup every 5 minutes
+    this.cleanupTimer = globalThis.setInterval(async () => {
+      await this.cleanupExpiredAssignments();
+    }, NUMERIX.FIVE * NUMERIX.SIXTY * NUMERIX.THOUSAND);
+  }
+
+  /**
+   * Emit role assigned event
+   * @param assignment - Role assignment
+   * @private
+   */
+  private emitRoleAssignedEvent(assignment: DynamicRoleAssignment): void {
+    // Mock event emission - in real implementation would use event system
+    globalThis.console.log(`Event: ${AUTH_EVENTS.ROLE_ASSIGNED}`, {
+      userId: assignment.userId,
+      roleId: assignment.roleId,
+      assignmentId: assignment.id,
+      assignedBy: assignment.assignedBy,
+      timestamp: assignment.createdAt
+    });
+  }
+
+  /**
+   * Emit role revoked event
+   * @param assignment - Role assignment
+   * @param revokedBy - Revoking user ID
+   * @param reason - Revocation reason
+   * @private
+   */
+  private emitRoleRevokedEvent(
+    assignment: DynamicRoleAssignment,
+    revokedBy?: string,
+    reason?: string
+  ): void {
+    // Mock event emission - in real implementation would use event system
+    globalThis.console.log(`Event: ${AUTH_EVENTS.ROLE_REVOKED}`, {
+      userId: assignment.userId,
+      roleId: assignment.roleId,
+      assignmentId: assignment.id,
+      revokedBy,
+      reason,
+      timestamp: new Date()
+    });
+  }
+}

package/src/rbac/index.ts

@@ -0,0 +1,4 @@
+export * from './role.manager';
+export * from './permission-checker';
+export * from './role-hierarchy';
+export * from './dynamic-roles';