@noony-serverless/core 0.1.1 → 0.2.0

package/build/middlewares/guards/RouteGuards.js

@@ -20,24 +20,128 @@
  * - Comprehensive monitoring and audit trails
  * - Framework-agnostic middleware integration
  *
- * Usage Examples:
+ * @example
+ * Complete guard system setup:
  * ```typescript
- * // Simple permissions (fastest)
- * .use(RouteGuards.requirePermissions(['user:read', 'user:update']))
+ * import { RouteGuards, GuardSetup } from '@noony-serverless/core';
  *
- * // Wildcard patterns (hierarchical)
- * .use(RouteGuards.requireWildcardPermissions(['admin.*', 'org.reports.*']))
+ * // Define user permission source
+ * const userPermissionSource = {
+ *   async getUserPermissions(userId: string): Promise<string[]> {
+ *     const user = await getUserFromDatabase(userId);
+ *     return user.permissions;
+ *   }
+ * };
  *
- * // Complex expressions (boolean logic)
- * .use(RouteGuards.requireComplexPermissions({
- *   or: [
- *     { permission: 'admin.users' },
- *     { and: [
- *       { permission: 'moderator.content' },
- *       { permission: 'org.reports.view' }
- *     ]}
- *   ]
- * }))
+ * // Define token validator
+ * const tokenValidator = {
+ *   async validateToken(token: string) {
+ *     try {
+ *       const decoded = jwt.verify(token, process.env.JWT_SECRET);
+ *       return { valid: true, decoded };
+ *     } catch (error) {
+ *       return { valid: false, error: error.message };
+ *     }
+ *   },
+ *   extractUserId: (decoded: unknown) => (decoded as any).sub,
+ *   isTokenExpired: (decoded: unknown) => (decoded as any).exp < Date.now() / 1000
+ * };
+ *
+ * // Configure guard system
+ * await RouteGuards.configure(
+ *   GuardSetup.production(),
+ *   userPermissionSource,
+ *   tokenValidator,
+ *   {
+ *     tokenHeader: 'authorization',
+ *     tokenPrefix: 'Bearer ',
+ *     requireEmailVerification: true,
+ *     allowInactiveUsers: false
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * Simple permission checks (fastest - ~0.1ms cached):
+ * ```typescript
+ * import { Handler, RouteGuards } from '@noony-serverless/core';
+ *
+ * const userManagementHandler = new Handler()
+ *   .use(RouteGuards.requirePermissions(['user:read', 'user:update']))
+ *   .handle(async (context) => {
+ *     // User has either 'user:read' OR 'user:update' permission
+ *     const users = await getUsers();
+ *     return { success: true, users };
+ *   });
+ * ```
+ *
+ * @example
+ * Wildcard permission patterns (hierarchical - ~0.2ms cached):
+ * ```typescript
+ * const adminHandler = new Handler()
+ *   .use(RouteGuards.requireWildcardPermissions(['admin.*', 'org.reports.*']))
+ *   .handle(async (context) => {
+ *     // User has any permission starting with 'admin.' OR 'org.reports.'
+ *     const adminData = await getAdminDashboard();
+ *     return { success: true, data: adminData };
+ *   });
+ * ```
+ *
+ * @example
+ * Complex boolean expressions (~0.5ms cached):
+ * ```typescript
+ * const complexAccessHandler = new Handler()
+ *   .use(RouteGuards.requireComplexPermissions({
+ *     or: [
+ *       { permission: 'admin.users' },
+ *       { and: [
+ *         { permission: 'moderator.content' },
+ *         { permission: 'org.reports.view' }
+ *       ]}
+ *     ]
+ *   }))
+ *   .handle(async (context) => {
+ *     // User has 'admin.users' OR ('moderator.content' AND 'org.reports.view')
+ *     return { success: true, accessGranted: true };
+ *   });
+ * ```
+ *
+ * @example
+ * Authentication-only (no permissions):
+ * ```typescript
+ * const profileHandler = new Handler()
+ *   .use(RouteGuards.requireAuth())
+ *   .handle(async (context) => {
+ *     // Only checks if user is authenticated
+ *     const profile = await getUserProfile(context.user.id);
+ *     return { success: true, profile };
+ *   });
+ * ```
+ *
+ * @example
+ * Cache invalidation for security:
+ * ```typescript
+ * // Invalidate specific user when permissions change
+ * await RouteGuards.invalidateUserPermissions('user-123', 'Permission update');
+ *
+ * // System-wide invalidation for major updates
+ * await RouteGuards.invalidateAllPermissions('System update deployed');
+ *
+ * // Emergency invalidation for security incidents
+ * await RouteGuards.emergencyInvalidation('Security breach detected');
+ * ```
+ *
+ * @example
+ * Monitoring and health checks:
+ * ```typescript
+ * // Get comprehensive system statistics
+ * const stats = RouteGuards.getSystemStats();
+ * console.log('Guard system performance:', stats.systemHealth);
+ *
+ * // Perform health check
+ * const health = await RouteGuards.healthCheck();
+ * console.log('System status:', health.status);
+ * console.log('Recommendations:', health.details.recommendations);
  * ```
  *
  * @author Noony Framework Team
@@ -64,6 +168,50 @@ const ConservativeCacheInvalidation_1 = require("./cache/ConservativeCacheInvali
 const FastAuthGuard_1 = require("./guards/FastAuthGuard");
 const PermissionGuardFactory_1 = require("./guards/PermissionGuardFactory");
 const PermissionRegistry_1 = require("./registry/PermissionRegistry");
+const CustomTokenVerificationPortAdapter_1 = require("./adapters/CustomTokenVerificationPortAdapter");
+/**
+ * Helper function to check if a token validator is a CustomTokenVerificationPort
+ */
+function isCustomTokenVerificationPort(validator) {
+    return (typeof validator === 'object' &&
+        'verifyToken' in validator &&
+        !('validateToken' in validator));
+}
+/**
+ * Convert any token validator to the TokenValidator interface expected by RouteGuards.
+ * Automatically wraps CustomTokenVerificationPort implementations with an adapter.
+ */
+function normalizeTokenValidator(validator) {
+    if (isCustomTokenVerificationPort(validator)) {
+        // For CustomTokenVerificationPort, we create a generic adapter
+        // We use a basic configuration that tries to extract common fields
+        return new CustomTokenVerificationPortAdapter_1.CustomTokenVerificationPortAdapter(validator, {
+            userIdExtractor: (user) => {
+                // Try to extract user ID from common field names
+                if (user && typeof user === 'object') {
+                    const userObj = user;
+                    return String(userObj.sub ||
+                        userObj.id ||
+                        userObj.userId ||
+                        userObj.user_id ||
+                        'unknown');
+                }
+                return 'unknown';
+            },
+            expirationExtractor: (user) => {
+                // Try to extract expiration from common field names
+                if (user && typeof user === 'object') {
+                    const userObj = user;
+                    const exp = userObj.exp || userObj.expiresAt || userObj.expires_at;
+                    return typeof exp === 'number' ? exp : undefined;
+                }
+                return undefined;
+            },
+        });
+    }
+    // Already a TokenValidator, return as-is
+    return validator;
+}
 /**
  * Route Guards Facade Implementation
  *
@@ -107,9 +255,58 @@ let RouteGuards = class RouteGuards {
      *
      * @param profile - Environment profile with guard configurations
      * @param permissionSource - User permission data source
-     * @param tokenValidator - JWT token validation service
+     * @param tokenValidator - Token validation service (supports both TokenValidator and CustomTokenVerificationPort)
      * @param authConfig - Authentication guard configuration
      * @returns Promise resolving when configuration is complete
+     *
+     * @example
+     * Using with CustomTokenVerificationPort from AuthenticationMiddleware:
+     * ```typescript
+     * import { CustomTokenVerificationPort } from '@/middlewares/authenticationMiddleware';
+     * import { RouteGuards, GuardSetup } from '@/middlewares/guards';
+     *
+     * // Same token verifier used across the framework
+     * const tokenVerifier: CustomTokenVerificationPort<User> = {
+     *   async verifyToken(token: string): Promise<User> {
+     *     const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload;
+     *     return {
+     *       id: payload.sub,
+     *       email: payload.email,
+     *       roles: payload.roles || [],
+     *       sub: payload.sub,
+     *       exp: payload.exp
+     *     };
+     *   }
+     * };
+     *
+     * // Configure RouteGuards with the same verifier
+     * await RouteGuards.configure(
+     *   GuardSetup.production(),
+     *   userPermissionSource,
+     *   tokenVerifier, // Automatically wrapped with adapter
+     *   authConfig
+     * );
+     * ```
+     *
+     * @example
+     * Traditional usage with TokenValidator (backward compatible):
+     * ```typescript
+     * const tokenValidator: TokenValidator = {
+     *   async validateToken(token: string) {
+     *     // Your existing validation logic
+     *     return { valid: true, decoded: userPayload };
+     *   },
+     *   extractUserId: (decoded) => decoded.sub,
+     *   isTokenExpired: (decoded) => decoded.exp < Date.now() / 1000
+     * };
+     *
+     * await RouteGuards.configure(
+     *   GuardSetup.production(),
+     *   userPermissionSource,
+     *   tokenValidator, // Works as before
+     *   authConfig
+     * );
+     * ```
      */
     static async configure(profile, permissionSource, tokenValidator, authConfig) {
         if (RouteGuards_1.isConfigured) {
@@ -119,20 +316,30 @@ let RouteGuards = class RouteGuards {
         try {
             // Create guard configuration
             const config = GuardConfiguration_1.GuardConfiguration.fromEnvironmentProfile(profile);
-            // Select cache adapter based on environment
+            // Get effective cache type considering environment variable override
+            // Environment variable NOONY_GUARD_CACHE_ENABLE takes precedence for security
+            const effectiveCacheType = GuardConfiguration_1.GuardConfiguration.getEffectiveCacheType(profile.cacheType);
+            // Select cache adapter based on effective cache type
             let cache;
-            if (profile.cacheType === 'memory') {
+            if (effectiveCacheType === 'memory') {
                 cache = new MemoryCacheAdapter_1.MemoryCacheAdapter({
                     maxSize: config.cache.maxEntries || 1000,
                     defaultTTL: config.cache.defaultTtlMs || 15 * 60 * 1000,
                     name: 'guard-memory-cache',
                 });
             }
-            else if (profile.cacheType === 'none') {
+            else if (effectiveCacheType === 'none') {
                 cache = new NoopCacheAdapter_1.NoopCacheAdapter();
+                // Log cache status for debugging
+                if (!GuardConfiguration_1.GuardConfiguration.isCachingEnabled()) {
+                    console.log(`🚫 Guard caching disabled by environment variable NOONY_GUARD_CACHE_ENABLE`);
+                }
+                else {
+                    console.log(`🚫 Guard caching disabled by configuration (cacheType: 'none')`);
+                }
             }
             else {
-                // Default to memory cache
+                // Default to memory cache (redis support would go here)
                 cache = new MemoryCacheAdapter_1.MemoryCacheAdapter({
                     maxSize: 1000,
                     defaultTTL: 15 * 60 * 1000,
@@ -145,8 +352,10 @@ let RouteGuards = class RouteGuards {
             const userContextService = new FastUserContextService_1.FastUserContextService(cache, config, permissionSource, permissionRegistry);
             // Create cache invalidation service
             const cacheInvalidation = new ConservativeCacheInvalidation_1.ConservativeCacheInvalidation(cache);
+            // Normalize token validator to ensure compatibility
+            const normalizedTokenValidator = normalizeTokenValidator(tokenValidator);
             // Create authentication guard
-            const authGuard = new FastAuthGuard_1.FastAuthGuard(cache, config, authConfig, userContextService, cacheInvalidation, tokenValidator);
+            const authGuard = new FastAuthGuard_1.FastAuthGuard(cache, config, authConfig, userContextService, cacheInvalidation, normalizedTokenValidator);
             // Create permission guard factory
             const guardFactory = new PermissionGuardFactory_1.PermissionGuardFactory(userContextService, config, cache);
             // Register services with TypeDI container
@@ -165,6 +374,8 @@ let RouteGuards = class RouteGuards {
             console.log('✅ RouteGuards configured successfully', {
                 environment: profile.environment,
                 cacheType: profile.cacheType,
+                effectiveCacheType: effectiveCacheType,
+                cachingEnabled: GuardConfiguration_1.GuardConfiguration.isCachingEnabled(),
                 permissionStrategy: config.security.permissionResolutionStrategy,
                 timestamp: new Date().toISOString(),
             });
@@ -333,6 +544,192 @@ let RouteGuards = class RouteGuards {
         const instance = RouteGuards_1.getInstance();
         return instance.performHealthCheck();
     }
+    /**
+     * Factory method: Configure RouteGuards with CustomTokenVerificationPort for JWT tokens.
+     * Provides a streamlined setup for JWT-based authentication with common field extraction.
+     *
+     * @example
+     * Quick JWT setup with CustomTokenVerificationPort:
+     * ```typescript
+     * import { CustomTokenVerificationPort } from '@/middlewares/authenticationMiddleware';
+     *
+     * interface JWTUser {
+     *   sub: string;
+     *   email: string;
+     *   roles: string[];
+     *   exp: number;
+     * }
+     *
+     * const jwtVerifier: CustomTokenVerificationPort<JWTUser> = {
+     *   async verifyToken(token: string): Promise<JWTUser> {
+     *     const payload = jwt.verify(token, process.env.JWT_SECRET!) as any;
+     *     return {
+     *       sub: payload.sub,
+     *       email: payload.email,
+     *       roles: payload.roles || [],
+     *       exp: payload.exp
+     *     };
+     *   }
+     * };
+     *
+     * // One-line setup for JWT authentication
+     * await RouteGuards.configureWithJWT(
+     *   GuardSetup.production(),
+     *   userPermissionSource,
+     *   jwtVerifier,
+     *   {
+     *     tokenHeader: 'authorization',
+     *     tokenPrefix: 'Bearer ',
+     *     requireEmailVerification: true
+     *   }
+     * );
+     * ```
+     */
+    static async configureWithJWT(profile, permissionSource, jwtVerifier, authConfig) {
+        // Create a properly typed adapter for JWT tokens
+        const tokenValidator = CustomTokenVerificationPortAdapter_1.TokenVerificationAdapterFactory.forJWT(jwtVerifier);
+        await RouteGuards_1.configure(profile, permissionSource, tokenValidator, authConfig);
+    }
+    /**
+     * Factory method: Configure RouteGuards with CustomTokenVerificationPort for API keys.
+     * Provides setup for API key-based authentication with flexible field mapping.
+     *
+     * @example
+     * API key authentication setup:
+     * ```typescript
+     * interface APIKeyUser {
+     *   keyId: string;
+     *   permissions: string[];
+     *   organization: string;
+     *   expiresAt?: number;
+     *   isActive: boolean;
+     * }
+     *
+     * const apiKeyVerifier: CustomTokenVerificationPort<APIKeyUser> = {
+     *   async verifyToken(token: string): Promise<APIKeyUser> {
+     *     const keyData = await validateAPIKeyInDatabase(token);
+     *     if (!keyData || !keyData.isActive) {
+     *       throw new Error('Invalid or inactive API key');
+     *     }
+     *     return keyData;
+     *   }
+     * };
+     *
+     * await RouteGuards.configureWithAPIKey(
+     *   GuardSetup.production(),
+     *   userPermissionSource,
+     *   apiKeyVerifier,
+     *   {
+     *     tokenHeader: 'x-api-key',
+     *     tokenPrefix: '',
+     *     allowInactiveUsers: false
+     *   },
+     *   'keyId',
+     *   'expiresAt'
+     * );
+     * ```
+     */
+    static async configureWithAPIKey(profile, permissionSource, apiKeyVerifier, authConfig, userIdField, expirationField) {
+        // Create a properly configured adapter for API keys
+        const tokenValidator = CustomTokenVerificationPortAdapter_1.TokenVerificationAdapterFactory.forAPIKey(apiKeyVerifier, userIdField, expirationField);
+        await RouteGuards_1.configure(profile, permissionSource, tokenValidator, authConfig);
+    }
+    /**
+     * Factory method: Configure RouteGuards with CustomTokenVerificationPort for OAuth tokens.
+     * Provides setup for OAuth-based authentication with scope validation.
+     *
+     * @example
+     * OAuth token authentication with scope requirements:
+     * ```typescript
+     * interface OAuthUser {
+     *   sub: string;
+     *   email: string;
+     *   scope: string[];
+     *   exp: number;
+     *   client_id: string;
+     * }
+     *
+     * const oauthVerifier: CustomTokenVerificationPort<OAuthUser> = {
+     *   async verifyToken(token: string): Promise<OAuthUser> {
+     *     const response = await fetch(`${OAUTH_INTROSPECT_URL}`, {
+     *       method: 'POST',
+     *       headers: { 'Authorization': `Bearer ${token}` },
+     *       body: new URLSearchParams({ token })
+     *     });
+     *
+     *     const tokenInfo = await response.json();
+     *     if (!tokenInfo.active) {
+     *       throw new Error('Token is not active');
+     *     }
+     *
+     *     return tokenInfo as OAuthUser;
+     *   }
+     * };
+     *
+     * await RouteGuards.configureWithOAuth(
+     *   GuardSetup.production(),
+     *   userPermissionSource,
+     *   oauthVerifier,
+     *   {
+     *     tokenHeader: 'authorization',
+     *     tokenPrefix: 'Bearer ',
+     *     requireEmailVerification: false
+     *   },
+     *   ['read:profile', 'write:data'] // Required OAuth scopes
+     * );
+     * ```
+     */
+    static async configureWithOAuth(profile, permissionSource, oauthVerifier, authConfig, requiredScopes) {
+        // Create a properly configured adapter for OAuth tokens
+        const tokenValidator = CustomTokenVerificationPortAdapter_1.TokenVerificationAdapterFactory.forOAuth(oauthVerifier, requiredScopes);
+        await RouteGuards_1.configure(profile, permissionSource, tokenValidator, authConfig);
+    }
+    /**
+     * Factory method: Configure RouteGuards with a custom CustomTokenVerificationPort adapter.
+     * Provides maximum flexibility for custom token validation scenarios.
+     *
+     * @example
+     * Custom token validation with business-specific logic:
+     * ```typescript
+     * interface CustomUser {
+     *   userId: string;
+     *   tenantId: string;
+     *   roles: string[];
+     *   sessionExpiry: number;
+     *   isVerified: boolean;
+     * }
+     *
+     * const customVerifier: CustomTokenVerificationPort<CustomUser> = {
+     *   async verifyToken(token: string): Promise<CustomUser> {
+     *     // Your custom verification logic
+     *     return await verifyCustomToken(token);
+     *   }
+     * };
+     *
+     * await RouteGuards.configureWithCustom(
+     *   GuardSetup.production(),
+     *   userPermissionSource,
+     *   customVerifier,
+     *   {
+     *     tokenHeader: 'x-auth-token',
+     *     tokenPrefix: 'Custom ',
+     *     customValidation: async (token, user) => {
+     *       return user.isVerified && user.tenantId === 'valid-tenant';
+     *     }
+     *   },
+     *   {
+     *     userIdExtractor: (user) => user.userId,
+     *     expirationExtractor: (user) => user.sessionExpiry,
+     *     additionalValidation: (user) => user.isVerified
+     *   }
+     * );
+     * ```
+     */
+    static async configureWithCustom(profile, permissionSource, customVerifier, authConfig, adapterConfig) {
+        // Create a custom configured adapter
+        const tokenValidator = CustomTokenVerificationPortAdapter_1.TokenVerificationAdapterFactory.custom(customVerifier, adapterConfig);
+        await RouteGuards_1.configure(profile, permissionSource, tokenValidator, authConfig);
+    }
     // Private implementation methods
     createPlainPermissionGuard(permissions, options) {
         this.trackGuardCreation();