@noony-serverless/core 0.1.0 → 0.1.1

package/build/middlewares/guards/RouteGuards.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Route Guards Facade
+ *
+ * Main entry point for the guard system providing a clean, NestJS-inspired API
+ * for protecting routes with authentication and authorization. This facade
+ * orchestrates all guard components to provide three distinct protection methods
+ * optimized for different use cases.
+ *
+ * Three Protection Methods:
+ * 1. `requirePermissions()` - Simple permission list checks (fastest)
+ * 2. `requireWildcardPermissions()` - Hierarchical wildcard patterns
+ * 3. `requireComplexPermissions()` - Boolean expression evaluation
+ *
+ * Key Features:
+ * - Automatic resolver selection for optimal performance
+ * - Intelligent caching strategies per protection method
+ * - Conservative security approach with automatic cache invalidation
+ * - Built-in authentication with cached user context loading
+ * - Comprehensive monitoring and audit trails
+ * - Framework-agnostic middleware integration
+ *
+ * Usage Examples:
+ * ```typescript
+ * // Simple permissions (fastest)
+ * .use(RouteGuards.requirePermissions(['user:read', 'user:update']))
+ *
+ * // Wildcard patterns (hierarchical)
+ * .use(RouteGuards.requireWildcardPermissions(['admin.*', 'org.reports.*']))
+ *
+ * // Complex expressions (boolean logic)
+ * .use(RouteGuards.requireComplexPermissions({
+ *   or: [
+ *     { permission: 'admin.users' },
+ *     { and: [
+ *       { permission: 'moderator.content' },
+ *       { permission: 'org.reports.view' }
+ *     ]}
+ *   ]
+ * }))
+ * ```
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+import { BaseMiddleware } from '../../core/handler';
+import { GuardConfiguration, GuardEnvironmentProfile } from './config/GuardConfiguration';
+import { CacheAdapter } from './cache/CacheAdapter';
+import { FastUserContextService, UserPermissionSource } from './services/FastUserContextService';
+import { ConservativeCacheInvalidation } from './cache/ConservativeCacheInvalidation';
+import { FastAuthGuard, AuthGuardConfig, TokenValidator } from './guards/FastAuthGuard';
+import { PermissionGuardFactory } from './guards/PermissionGuardFactory';
+import { PermissionRegistry } from './registry/PermissionRegistry';
+import { PermissionExpression } from './resolvers/PermissionResolver';
+/**
+ * Route guard configuration for the facade
+ */
+export interface RouteGuardOptions {
+    /** Enable authentication requirement (default: true) */
+    requireAuth?: boolean;
+    /** Enable permission result caching (default: true) */
+    cacheResults?: boolean;
+    /** Enable detailed audit logging (default: false) */
+    auditTrail?: boolean;
+    /** Custom error message for access denials */
+    errorMessage?: string;
+    /** Cache TTL in milliseconds (overrides global config) */
+    cacheTtlMs?: number;
+}
+/**
+ * Guard system statistics
+ */
+export interface GuardSystemStats {
+    authentication: Record<string, unknown>;
+    userContextService: Record<string, unknown>;
+    permissionGuardFactory: Record<string, unknown>;
+    cacheInvalidation: Record<string, unknown>;
+    cacheAdapter: Record<string, unknown>;
+    systemHealth: {
+        totalGuardChecks: number;
+        averageResponseTime: number;
+        errorRate: number;
+        cacheEfficiency: number;
+        uptime: number;
+    };
+}
+/**
+ * Route Guards Facade Implementation
+ *
+ * This class provides the main API for the guard system and handles
+ * the orchestration of all guard components. It follows the facade pattern
+ * to simplify the complex underlying guard architecture.
+ */
+export declare class RouteGuards {
+    private static instance;
+    private static isConfigured;
+    private readonly _config;
+    private readonly cache;
+    private readonly userContextService;
+    private readonly cacheInvalidation;
+    private readonly authGuard;
+    private readonly guardFactory;
+    private readonly _permissionRegistry;
+    private systemStartTime;
+    private totalGuardChecks;
+    private totalErrors;
+    private totalResponseTime;
+    constructor(config: GuardConfiguration, cache: CacheAdapter, userContextService: FastUserContextService, cacheInvalidation: ConservativeCacheInvalidation, authGuard: FastAuthGuard, guardFactory: PermissionGuardFactory, permissionRegistry: PermissionRegistry);
+    /**
+     * Configure the guard system with environment-specific settings
+     *
+     * This method must be called once before using any guard methods.
+     * It sets up all guard components with optimal configurations for
+     * the target environment (development, production, serverless).
+     *
+     * @param profile - Environment profile with guard configurations
+     * @param permissionSource - User permission data source
+     * @param tokenValidator - JWT token validation service
+     * @param authConfig - Authentication guard configuration
+     * @returns Promise resolving when configuration is complete
+     */
+    static configure(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, tokenValidator: TokenValidator, authConfig: AuthGuardConfig): Promise<void>;
+    /**
+     * Get the configured RouteGuards instance
+     *
+     * @returns Configured RouteGuards instance
+     * @throws Error if not configured
+     */
+    static getInstance(): RouteGuards;
+    /**
+     * Create middleware for simple permission list checks
+     *
+     * This is the fastest protection method using direct O(1) set membership
+     * checks. Ideal for high-traffic endpoints with straightforward permission
+     * requirements.
+     *
+     * Performance: ~0.1ms cached, ~1-2ms uncached
+     *
+     * @param permissions - Array of required permissions (OR logic)
+     * @param options - Optional guard configuration
+     * @returns Middleware instance for permission checking
+     */
+    static requirePermissions(permissions: string[], options?: RouteGuardOptions): BaseMiddleware;
+    /**
+     * Create middleware for wildcard permission pattern checks
+     *
+     * Supports hierarchical permission patterns with wildcards for flexible
+     * permission management. Uses configurable pre-expansion or on-demand
+     * matching strategies.
+     *
+     * Performance: ~0.2ms cached (pre-expansion), ~2-5ms cached (on-demand)
+     *
+     * @param wildcardPatterns - Array of wildcard patterns
+     * @param options - Optional guard configuration
+     * @returns Middleware instance for wildcard permission checking
+     */
+    static requireWildcardPermissions(wildcardPatterns: string[], options?: RouteGuardOptions): BaseMiddleware;
+    /**
+     * Create middleware for complex boolean expression checks
+     *
+     * Supports advanced permission logic with AND, OR, and NOT operations.
+     * Includes expression caching and complexity tracking for performance
+     * optimization.
+     *
+     * Performance: ~0.5ms cached, ~5-15ms uncached (depends on complexity)
+     *
+     * @param expression - Permission expression with boolean logic
+     * @param options - Optional guard configuration
+     * @returns Middleware instance for expression permission checking
+     */
+    static requireComplexPermissions(expression: PermissionExpression, options?: RouteGuardOptions): BaseMiddleware;
+    /**
+     * Create middleware with automatic resolver selection
+     *
+     * Analyzes permission requirements and automatically selects the optimal
+     * resolution strategy for best performance. Useful when you want the
+     * system to choose the best approach.
+     *
+     * @param permissions - Any type of permission requirement
+     * @param options - Optional guard configuration
+     * @returns Optimally configured middleware instance
+     */
+    static requireAny(permissions: string[] | PermissionExpression, options?: RouteGuardOptions): BaseMiddleware;
+    /**
+     * Get authentication-only middleware
+     *
+     * Provides user authentication without permission checking.
+     * Useful for endpoints that only need to verify user identity.
+     *
+     * @param options - Optional guard configuration
+     * @returns Authentication-only middleware
+     */
+    static requireAuth(_options?: RouteGuardOptions): BaseMiddleware;
+    /**
+     * Invalidate user permissions cache
+     *
+     * Use when user permissions change to ensure fresh permission checks.
+     * Implements conservative invalidation strategy for security.
+     *
+     * @param userId - User ID to invalidate
+     * @param reason - Reason for invalidation (for audit)
+     * @returns Promise resolving when invalidation is complete
+     */
+    static invalidateUserPermissions(userId: string, reason: string): Promise<void>;
+    /**
+     * System-wide cache invalidation
+     *
+     * Nuclear option for clearing all permission-related caches.
+     * Use for major system updates or security incidents.
+     *
+     * @param reason - Reason for system-wide invalidation
+     * @returns Promise resolving when invalidation is complete
+     */
+    static invalidateAllPermissions(reason: string): Promise<void>;
+    /**
+     * Emergency security invalidation
+     *
+     * Immediate cache clearing for security incidents.
+     * Bypasses backup creation for maximum speed.
+     *
+     * @param reason - Security incident description
+     * @returns Promise resolving when emergency invalidation is complete
+     */
+    static emergencyInvalidation(reason: string): Promise<void>;
+    /**
+     * Get comprehensive system statistics
+     *
+     * @returns Complete guard system performance and health metrics
+     */
+    static getSystemStats(): GuardSystemStats;
+    /**
+     * Reset all system statistics
+     */
+    static resetSystemStats(): void;
+    /**
+     * Health check for the guard system
+     *
+     * @returns Health status with key metrics
+     */
+    static healthCheck(): Promise<{
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        details: Record<string, unknown>;
+        timestamp: string;
+    }>;
+    private createPlainPermissionGuard;
+    private createWildcardPermissionGuard;
+    private createExpressionPermissionGuard;
+    private createAutoPermissionGuard;
+    private wrapGuardWithStats;
+    private trackGuardCreation;
+    private getSystemStats;
+    private resetSystemStats;
+    private performHealthCheck;
+    private getHealthRecommendations;
+}
+//# sourceMappingURL=RouteGuards.d.ts.map