@noony-serverless/core 0.1.1 → 0.2.0

package/build/middlewares/errorHandlerMiddleware.js

@@ -2,6 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.errorHandler = exports.ErrorHandlerMiddleware = void 0;
 const core_1 = require("../core");
+/**
+ * Handles errors thrown during request processing and sends an appropriate JSON response.
+ *
+ * - Logs error details including message, stack, request ID, user agent, and IP.
+ * - For `HttpError` instances, responds with the error message, and optionally details and code based on environment and error type.
+ * - For other errors, responds with a generic message in production, and includes stack trace in development.
+ *
+ * @param error - The error object thrown during request processing.
+ * @param context - The request context containing request and response objects.
+ * @returns A promise that resolves when the error response has been sent.
+ */
 const handleError = async (error, context) => {
     const isDevelopment = process.env.NODE_ENV === 'development' || process.env.DEBUG === 'true';
     core_1.logger.error('Error processing request', {
@@ -49,12 +60,106 @@ const handleError = async (error, context) => {
         context.res.status(500).json(responsePayload);
     }
 };
+/**
+ * Middleware class for handling errors in the application.
+ * Implements the `BaseMiddleware` interface and provides an asynchronous
+ * `onError` method that delegates error handling to the `handleError` function.
+ *
+ * @remarks
+ * This middleware should be registered to catch and process errors that occur
+ * during request handling.
+ *
+ * @method onError
+ * @param error - The error object that was thrown.
+ * @param context - The context in which the error occurred.
+ * @returns A promise that resolves when error handling is complete.
+ *
+ * @example
+ * Basic handler with error handling:
+ * ```typescript
+ * import { Handler, ErrorHandlerMiddleware, HttpError } from '@noony-serverless/core';
+ *
+ * const createUserHandler = new Handler()
+ *   .use(new ErrorHandlerMiddleware())
+ *   .handle(async (request, context) => {
+ *     if (!request.body?.email) {
+ *       throw new HttpError(400, 'Email is required', 'MISSING_EMAIL');
+ *     }
+ *
+ *     return {
+ *       success: true,
+ *       data: { id: 'user-123', email: request.body.email }
+ *     };
+ *   });
+ * ```
+ *
+ * @example
+ * Google Cloud Functions integration:
+ * ```typescript
+ * import { http } from '@google-cloud/functions-framework';
+ * import { Handler, ErrorHandlerMiddleware } from '@noony-serverless/core';
+ *
+ * const orderHandler = new Handler()
+ *   .use(new ErrorHandlerMiddleware())
+ *   .handle(async (request, context) => {
+ *     // Handler logic that might throw errors
+ *     return { success: true, data: processedOrder };
+ *   });
+ *
+ * export const processOrder = http('processOrder', (req, res) => {
+ *   return orderHandler.execute(req, res);
+ * });
+ * ```
+ */
 class ErrorHandlerMiddleware {
     async onError(error, context) {
         await handleError(error, context);
     }
 }
 exports.ErrorHandlerMiddleware = ErrorHandlerMiddleware;
+/**
+ * Creates an error handling middleware for processing errors in the application.
+ *
+ * @returns {BaseMiddleware} An object implementing the `onError` method to handle errors.
+ *
+ * @remarks
+ * The middleware's `onError` method asynchronously delegates error handling to the `handleError` function,
+ * passing the error and context objects.
+ *
+ * @example
+ * Basic usage with factory function:
+ * ```typescript
+ * import { Handler, errorHandler, HttpError } from '@noony-serverless/core';
+ *
+ * const loginHandler = new Handler()
+ *   .use(errorHandler())
+ *   .handle(async (request, context) => {
+ *     const { username, password } = request.body || {};
+ *
+ *     if (!username || !password) {
+ *       throw new HttpError(400, 'Credentials required', 'MISSING_CREDENTIALS');
+ *     }
+ *
+ *     const user = await authenticateUser(username, password);
+ *     return { success: true, data: { token: generateToken(user) } };
+ *   });
+ * ```
+ *
+ * @example
+ * Multiple middleware chain:
+ * ```typescript
+ * import { Handler, errorHandler, BodyParserMiddleware } from '@noony-serverless/core';
+ *
+ * const secureHandler = new Handler()
+ *   .use(new BodyParserMiddleware())
+ *   .use(new AuthenticationMiddleware())
+ *   .use(errorHandler()) // Should be last to catch all errors
+ *   .handle(async (request, context) => {
+ *     // Handler logic
+ *     return { success: true, data: result };
+ *   });
+ * ```
+ */
 const errorHandler = () => ({
     onError: async (error, context) => {
         await handleError(error, context);

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

@@ -19,24 +19,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']))
- *
- * // 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' }
- *     ]}
- *   ]
- * }))
+ * import { RouteGuards, GuardSetup } from '@noony-serverless/core';
+ *
+ * // Define user permission source
+ * const userPermissionSource = {
+ *   async getUserPermissions(userId: string): Promise<string[]> {
+ *     const user = await getUserFromDatabase(userId);
+ *     return user.permissions;
+ *   }
+ * };
+ *
+ * // 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
@@ -51,8 +155,67 @@ import { FastAuthGuard, AuthGuardConfig, TokenValidator } from './guards/FastAut
 import { PermissionGuardFactory } from './guards/PermissionGuardFactory';
 import { PermissionRegistry } from './registry/PermissionRegistry';
 import { PermissionExpression } from './resolvers/PermissionResolver';
+import { CustomTokenVerificationPort } from '../authenticationMiddleware';
+import { TokenVerificationAdapterFactory } from './adapters/CustomTokenVerificationPortAdapter';
+/**
+ * Union type supporting both RouteGuards TokenValidator and AuthenticationMiddleware CustomTokenVerificationPort.
+ * This enables seamless integration between the two authentication systems.
+ */
+export type AnyTokenValidator = TokenValidator | CustomTokenVerificationPort<unknown>;
 /**
- * Route guard configuration for the facade
+ * Route guard configuration for the facade.
+ * Provides fine-grained control over guard behavior for specific endpoints.
+ *
+ * @example
+ * Basic guard options:
+ * ```typescript
+ * const options: RouteGuardOptions = {
+ *   requireAuth: true,
+ *   cacheResults: true,
+ *   auditTrail: false,
+ *   errorMessage: 'Access denied to this resource'
+ * };
+ *
+ * const handler = new Handler()
+ *   .use(RouteGuards.requirePermissions(['admin:read'], options))
+ *   .handle(async (context) => {
+ *     return { success: true, data: 'admin data' };
+ *   });
+ * ```
+ *
+ * @example
+ * High-security endpoint with audit trail:
+ * ```typescript
+ * const secureOptions: RouteGuardOptions = {
+ *   requireAuth: true,
+ *   cacheResults: false, // Always check fresh permissions
+ *   auditTrail: true,    // Enable detailed logging
+ *   errorMessage: 'Unauthorized access to sensitive data',
+ *   cacheTtlMs: 30000    // Short cache TTL for security
+ * };
+ *
+ * const sensitiveHandler = new Handler()
+ *   .use(RouteGuards.requirePermissions(['sensitive:access'], secureOptions))
+ *   .handle(async (context) => {
+ *     return { success: true, data: 'sensitive information' };
+ *   });
+ * ```
+ *
+ * @example
+ * Public endpoint with authentication check only:
+ * ```typescript
+ * const publicOptions: RouteGuardOptions = {
+ *   requireAuth: false,  // Allow unauthenticated access
+ *   cacheResults: true,
+ *   auditTrail: false
+ * };
+ *
+ * const publicHandler = new Handler()
+ *   .use(RouteGuards.requirePermissions(['public:read'], publicOptions))
+ *   .handle(async (context) => {
+ *     return { success: true, data: 'public data' };
+ *   });
+ * ```
  */
 export interface RouteGuardOptions {
     /** Enable authentication requirement (default: true) */
@@ -67,7 +230,71 @@ export interface RouteGuardOptions {
     cacheTtlMs?: number;
 }
 /**
- * Guard system statistics
+ * Guard system statistics for monitoring and performance analysis.
+ * Provides comprehensive metrics about all guard system components.
+ *
+ * @example
+ * Monitoring guard system performance:
+ * ```typescript
+ * const stats = RouteGuards.getSystemStats();
+ *
+ * console.log('System Health:', {
+ *   totalChecks: stats.systemHealth.totalGuardChecks,
+ *   avgResponseTime: stats.systemHealth.averageResponseTime,
+ *   errorRate: stats.systemHealth.errorRate,
+ *   cacheEfficiency: stats.systemHealth.cacheEfficiency,
+ *   uptime: Math.round(stats.systemHealth.uptime / 1000) + 's'
+ * });
+ *
+ * console.log('Cache Performance:', {
+ *   adapter: stats.cacheAdapter.name,
+ *   stats: stats.cacheAdapter.stats
+ * });
+ * ```
+ *
+ * @example
+ * Setting up monitoring alerts:
+ * ```typescript
+ * setInterval(async () => {
+ *   const stats = RouteGuards.getSystemStats();
+ *   const health = await RouteGuards.healthCheck();
+ *
+ *   if (health.status === 'unhealthy') {
+ *     await sendAlert('Guard system unhealthy', {
+ *       status: health.status,
+ *       errorRate: stats.systemHealth.errorRate,
+ *       avgResponseTime: stats.systemHealth.averageResponseTime,
+ *       recommendations: health.details.recommendations
+ *     });
+ *   }
+ *
+ *   if (stats.systemHealth.cacheEfficiency < 50) {
+ *     await sendAlert('Low cache efficiency detected', {
+ *       efficiency: stats.systemHealth.cacheEfficiency,
+ *       totalChecks: stats.systemHealth.totalGuardChecks
+ *     });
+ *   }
+ * }, 60000); // Check every minute
+ * ```
+ *
+ * @example
+ * Performance optimization based on stats:
+ * ```typescript
+ * const stats = RouteGuards.getSystemStats();
+ *
+ * if (stats.systemHealth.averageResponseTime > 10) {
+ *   console.warn('Slow guard performance detected');
+ *   console.log('Consider:');
+ *   console.log('- Increasing cache TTL values');
+ *   console.log('- Optimizing permission source queries');
+ *   console.log('- Using simpler permission patterns');
+ * }
+ *
+ * if (stats.systemHealth.errorRate > 2) {
+ *   console.error('High error rate in guard system');
+ *   console.log('Check authentication service health');
+ * }
+ * ```
  */
 export interface GuardSystemStats {
     authentication: Record<string, unknown>;
@@ -114,11 +341,60 @@ export declare 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 configure(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, tokenValidator: TokenValidator, authConfig: AuthGuardConfig): Promise<void>;
+    static configure(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, tokenValidator: AnyTokenValidator, authConfig: AuthGuardConfig): Promise<void>;
     /**
      * Get the configured RouteGuards instance
      *
@@ -241,6 +517,185 @@ export declare class RouteGuards {
         details: Record<string, unknown>;
         timestamp: string;
     }>;
+    /**
+     * 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 configureWithJWT<T extends {
+        sub: string;
+        exp?: number;
+    }>(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, jwtVerifier: CustomTokenVerificationPort<T>, authConfig: AuthGuardConfig): Promise<void>;
+    /**
+     * 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 configureWithAPIKey<T extends Record<string, unknown>>(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, apiKeyVerifier: CustomTokenVerificationPort<T>, authConfig: AuthGuardConfig, userIdField: keyof T, expirationField?: keyof T): Promise<void>;
+    /**
+     * 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 configureWithOAuth<T extends {
+        sub: string;
+        exp?: number;
+        scope?: string[];
+    }>(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, oauthVerifier: CustomTokenVerificationPort<T>, authConfig: AuthGuardConfig, requiredScopes?: string[]): Promise<void>;
+    /**
+     * 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 configureWithCustom<T>(profile: GuardEnvironmentProfile, permissionSource: UserPermissionSource, customVerifier: CustomTokenVerificationPort<T>, authConfig: AuthGuardConfig, adapterConfig: Omit<Parameters<typeof TokenVerificationAdapterFactory.custom<T>>[1], 'userIdExtractor'> & {
+        userIdExtractor: (user: T) => string;
+    }): Promise<void>;
     private createPlainPermissionGuard;
     private createWildcardPermissionGuard;
     private createExpressionPermissionGuard;