@noony-serverless/core 0.1.1 → 0.2.0

package/build/middlewares/SecurityMiddleware.js

@@ -0,0 +1,307 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSecurityMiddleware = exports.SecurityMiddleware = void 0;
+const core_1 = require("../core");
+/**
+ * Consolidated SecurityMiddleware that combines authentication, security headers, and audit logging.
+ *
+ * This middleware replaces the need for separate:
+ * - AuthenticationMiddleware
+ * - SecurityHeadersMiddleware
+ * - SecurityAuditMiddleware
+ *
+ * @example
+ * Basic security with authentication and headers:
+ * ```typescript
+ * const handler = new Handler()
+ *   .use(new SecurityMiddleware({
+ *     authentication: {
+ *       tokenVerifier: {
+ *         verifyToken: async (token) => jwt.verify(token, secret)
+ *       },
+ *       extractToken: (req) => req.headers.authorization?.replace('Bearer ', '')
+ *     },
+ *     headers: {
+ *       contentSecurityPolicy: "default-src 'self'",
+ *       xFrameOptions: 'DENY',
+ *       strictTransportSecurity: 'max-age=31536000; includeSubDomains'
+ *     },
+ *     audit: {
+ *       logFailedAuth: true,
+ *       trackSuspiciousIPs: true
+ *     }
+ *   }))
+ *   .handle(async (context) => {
+ *     // context.user is populated if authentication succeeds
+ *     const user = context.user;
+ *     return { message: `Hello ${user?.name}` };
+ *   });
+ * ```
+ *
+ * @example
+ * Advanced security with custom auditing:
+ * ```typescript
+ * const handler = new Handler()
+ *   .use(new SecurityMiddleware({
+ *     authentication: {
+ *       tokenVerifier: customTokenVerifier,
+ *       skipPaths: ['/health', '/metrics'],
+ *       onAuthFailure: async (error, context) => {
+ *         await logSecurityEvent('auth_failure', {
+ *           ip: context.req.ip,
+ *           error: error.message
+ *         });
+ *       }
+ *     },
+ *     audit: {
+ *       customAuditor: async (event, context) => {
+ *         await sendToSecuritySystem(event);
+ *       },
+ *       alertThresholds: {
+ *         failedAttempts: 5,
+ *         timeWindowMs: 300000 // 5 minutes
+ *       }
+ *     }
+ *   }));
+ * ```
+ */
+class SecurityMiddleware {
+    config;
+    failedAttempts = new Map();
+    constructor(config = {}) {
+        this.config = {
+            authentication: {},
+            headers: {
+                xFrameOptions: 'DENY',
+                xContentTypeOptions: 'nosniff',
+                xXssProtection: '1; mode=block',
+                referrerPolicy: 'strict-origin-when-cross-origin',
+                ...config.headers,
+            },
+            audit: {
+                logFailedAuth: true,
+                trackSuspiciousIPs: false,
+                enableMetrics: true,
+                ...config.audit,
+            },
+            ...config,
+        };
+    }
+    async before(context) {
+        // 1. Set security headers first (always apply)
+        await this.setSecurityHeaders(context);
+        // 2. Perform authentication if configured
+        if (this.config.authentication?.tokenVerifier) {
+            await this.authenticateRequest(context);
+        }
+    }
+    async after(context) {
+        // Audit successful operations if enabled
+        if (this.config.audit?.logSuccessfulAuth && context.user) {
+            await this.auditSecurityEvent({
+                type: 'AUTH_SUCCESS',
+                ip: context.req.ip,
+                userAgent: context.req.userAgent,
+                path: context.req.path,
+                timestamp: new Date(),
+                details: { userId: context.user?.id },
+            }, context);
+        }
+    }
+    async onError(error, context) {
+        // Audit authentication failures
+        if (error instanceof core_1.AuthenticationError &&
+            this.config.audit?.logFailedAuth) {
+            const ip = context.req.ip || 'unknown';
+            // Track failed attempts for suspicious IP detection
+            if (this.config.audit?.trackSuspiciousIPs) {
+                await this.trackFailedAttempt(ip, context);
+            }
+            await this.auditSecurityEvent({
+                type: 'AUTH_FAILURE',
+                ip,
+                userAgent: context.req.userAgent,
+                path: context.req.path,
+                timestamp: new Date(),
+                details: { error: error.message },
+            }, context);
+            // Custom auth failure handler
+            if (this.config.authentication?.onAuthFailure) {
+                await this.config.authentication.onAuthFailure(error, context);
+            }
+        }
+    }
+    async setSecurityHeaders(context) {
+        const headers = this.config.headers;
+        if (headers.contentSecurityPolicy) {
+            context.res.header('Content-Security-Policy', headers.contentSecurityPolicy);
+        }
+        if (headers.xFrameOptions) {
+            context.res.header('X-Frame-Options', headers.xFrameOptions);
+        }
+        if (headers.strictTransportSecurity) {
+            context.res.header('Strict-Transport-Security', headers.strictTransportSecurity);
+        }
+        if (headers.xContentTypeOptions) {
+            context.res.header('X-Content-Type-Options', headers.xContentTypeOptions);
+        }
+        if (headers.xXssProtection) {
+            context.res.header('X-XSS-Protection', headers.xXssProtection);
+        }
+        if (headers.referrerPolicy) {
+            context.res.header('Referrer-Policy', headers.referrerPolicy);
+        }
+        if (headers.permissionsPolicy) {
+            context.res.header('Permissions-Policy', headers.permissionsPolicy);
+        }
+        // Apply custom headers
+        if (headers.customHeaders) {
+            Object.entries(headers.customHeaders).forEach(([name, value]) => {
+                context.res.header(name, value);
+            });
+        }
+    }
+    async authenticateRequest(context) {
+        const authConfig = this.config.authentication;
+        // Skip authentication for specified paths
+        if (authConfig.skipPaths?.some((path) => context.req.path?.startsWith(path))) {
+            return;
+        }
+        // Extract token
+        const token = authConfig.extractToken
+            ? authConfig.extractToken(context.req)
+            : this.extractTokenFromHeader(context.req);
+        if (!token) {
+            if (!authConfig.optional) {
+                throw new core_1.AuthenticationError('No authentication token provided');
+            }
+            return;
+        }
+        try {
+            // Verify token using the provided verifier
+            const user = await authConfig.tokenVerifier.verifyToken(token);
+            context.user = user;
+        }
+        catch (error) {
+            throw new core_1.AuthenticationError('Invalid authentication token');
+        }
+    }
+    extractTokenFromHeader(req) {
+        const authHeader = req.headers?.authorization || req.headers?.Authorization;
+        if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
+            return authHeader.substring(7);
+        }
+        return null;
+    }
+    async trackFailedAttempt(ip, context) {
+        const now = Date.now();
+        const threshold = this.config.audit?.alertThresholds?.failedAttempts || 5;
+        const timeWindow = this.config.audit?.alertThresholds?.timeWindowMs || 300000; // 5 minutes
+        const existing = this.failedAttempts.get(ip);
+        if (!existing) {
+            this.failedAttempts.set(ip, { count: 1, firstAttempt: now });
+            return;
+        }
+        // Reset if outside time window
+        if (now - existing.firstAttempt > timeWindow) {
+            this.failedAttempts.set(ip, { count: 1, firstAttempt: now });
+            return;
+        }
+        // Increment count
+        existing.count++;
+        // Check if threshold exceeded
+        if (existing.count >= threshold) {
+            await this.auditSecurityEvent({
+                type: 'THRESHOLD_EXCEEDED',
+                ip,
+                userAgent: context.req.userAgent,
+                path: context.req.path,
+                timestamp: new Date(),
+                details: {
+                    failedAttempts: existing.count,
+                    timeWindowMs: timeWindow,
+                    firstAttemptTime: new Date(existing.firstAttempt),
+                },
+            }, context);
+            // Optionally reset counter or keep tracking
+            this.failedAttempts.delete(ip);
+        }
+    }
+    async auditSecurityEvent(event, context) {
+        // Use custom auditor if provided
+        if (this.config.audit?.customAuditor) {
+            await this.config.audit.customAuditor(event, context);
+            return;
+        }
+        // Default logging
+        const logLevel = event.type.includes('FAILURE') || event.type.includes('EXCEEDED')
+            ? 'warn'
+            : 'info';
+        console[logLevel]('[SecurityMiddleware]', {
+            type: event.type,
+            ip: event.ip,
+            path: event.path,
+            timestamp: event.timestamp.toISOString(),
+            userAgent: event.userAgent,
+            details: event.details,
+        });
+        // Store in business data for downstream processing
+        if (!context.businessData.has('securityEvents')) {
+            context.businessData.set('securityEvents', []);
+        }
+        context.businessData.get('securityEvents').push(event);
+    }
+}
+exports.SecurityMiddleware = SecurityMiddleware;
+/**
+ * Factory function for creating SecurityMiddleware with common configurations
+ */
+exports.createSecurityMiddleware = {
+    /**
+     * Basic security setup with common headers and JWT authentication
+     */
+    basic: (tokenVerifier) => new SecurityMiddleware({
+        authentication: { tokenVerifier },
+        headers: {
+            contentSecurityPolicy: "default-src 'self'",
+            xFrameOptions: 'DENY',
+            strictTransportSecurity: 'max-age=31536000',
+        },
+        audit: { logFailedAuth: true },
+    }),
+    /**
+     * Advanced security with audit tracking and suspicious IP monitoring
+     */
+    advanced: (tokenVerifier) => new SecurityMiddleware({
+        authentication: { tokenVerifier },
+        headers: {
+            contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline'",
+            xFrameOptions: 'DENY',
+            strictTransportSecurity: 'max-age=31536000; includeSubDomains',
+            referrerPolicy: 'strict-origin-when-cross-origin',
+            permissionsPolicy: 'geolocation=(), microphone=(), camera=()',
+        },
+        audit: {
+            logFailedAuth: true,
+            logSuccessfulAuth: true,
+            trackSuspiciousIPs: true,
+            alertThresholds: {
+                failedAttempts: 5,
+                timeWindowMs: 300000,
+            },
+        },
+    }),
+    /**
+     * Headers only - no authentication
+     */
+    headersOnly: () => new SecurityMiddleware({
+        headers: {
+            contentSecurityPolicy: "default-src 'self'",
+            xFrameOptions: 'DENY',
+            xContentTypeOptions: 'nosniff',
+            xXssProtection: '1; mode=block',
+            referrerPolicy: 'strict-origin-when-cross-origin',
+        },
+    }),
+};
+//# sourceMappingURL=SecurityMiddleware.js.map

package/build/middlewares/authenticationMiddleware.d.ts

@@ -1,8 +1,107 @@
 import { BaseMiddleware } from '../core/handler';
 import { Context } from '../core/core';
+/**
+ * Interface for custom token verification implementations.
+ * Allows integration with various authentication providers (JWT, OAuth, custom tokens).
+ *
+ * @template T - The type of user data returned after successful token verification
+ *
+ * @example
+ * JWT token verification:
+ * ```typescript
+ * import jwt from 'jsonwebtoken';
+ * import { CustomTokenVerificationPort } from '@noony-serverless/core';
+ *
+ * interface User {
+ *   id: string;
+ *   email: string;
+ *   roles: string[];
+ * }
+ *
+ * class JWTVerificationPort implements CustomTokenVerificationPort<User> {
+ *   constructor(private secret: string) {}
+ *
+ *   async verifyToken(token: string): Promise<User> {
+ *     try {
+ *       const payload = jwt.verify(token, this.secret) as any;
+ *       return {
+ *         id: payload.sub,
+ *         email: payload.email,
+ *         roles: payload.roles || []
+ *       };
+ *     } catch (error) {
+ *       throw new Error('Invalid token');
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Custom API token verification:
+ * ```typescript
+ * class APIKeyVerificationPort implements CustomTokenVerificationPort<{ apiKey: string; permissions: string[] }> {
+ *   async verifyToken(token: string): Promise<{ apiKey: string; permissions: string[] }> {
+ *     const apiKey = await this.validateAPIKey(token);
+ *     if (!apiKey) {
+ *       throw new Error('Invalid API key');
+ *     }
+ *     return {
+ *       apiKey: token,
+ *       permissions: apiKey.permissions
+ *     };
+ *   }
+ *
+ *   private async validateAPIKey(key: string) {
+ *     // Validate against database or external service
+ *     return { permissions: ['read', 'write'] };
+ *   }
+ * }
+ * ```
+ */
 export interface CustomTokenVerificationPort<T> {
     verifyToken(token: string): Promise<T>;
 }
+/**
+ * Standard JWT payload interface with common claims.
+ * Extends the payload with custom properties as needed.
+ *
+ * @example
+ * Basic JWT payload usage:
+ * ```typescript
+ * import { JWTPayload } from '@noony-serverless/core';
+ *
+ * interface CustomJWTPayload extends JWTPayload {
+ *   userId: string;
+ *   email: string;
+ *   roles: string[];
+ * }
+ *
+ * const payload: CustomJWTPayload = {
+ *   sub: 'user-123',
+ *   exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
+ *   iat: Math.floor(Date.now() / 1000),
+ *   iss: 'my-app',
+ *   aud: 'my-app-users',
+ *   userId: 'user-123',
+ *   email: 'user@example.com',
+ *   roles: ['user', 'admin']
+ * };
+ * ```
+ *
+ * @example
+ * Token validation with custom claims:
+ * ```typescript
+ * function validateCustomClaims(payload: JWTPayload & { roles?: string[] }) {
+ *   if (!payload.roles || payload.roles.length === 0) {
+ *     throw new Error('User must have at least one role');
+ *   }
+ *
+ *   if (payload.exp && payload.exp < Date.now() / 1000) {
+ *     throw new Error('Token has expired');
+ *   }
+ * }
+ * ```
+ */
 export interface JWTPayload {
     exp?: number;
     iat?: number;
@@ -13,6 +112,70 @@ export interface JWTPayload {
     sub?: string;
     [key: string]: unknown;
 }
+/**
+ * Configuration options for authentication middleware.
+ * Provides comprehensive security controls and validation settings.
+ *
+ * @example
+ * Basic authentication options:
+ * ```typescript
+ * import { AuthenticationOptions } from '@noony-serverless/core';
+ *
+ * const basicOptions: AuthenticationOptions = {
+ *   maxTokenAge: 3600, // 1 hour
+ *   clockTolerance: 60, // 1 minute
+ *   requiredClaims: {
+ *     issuer: 'my-app',
+ *     audience: 'my-app-users'
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Advanced options with rate limiting and blacklisting:
+ * ```typescript
+ * const advancedOptions: AuthenticationOptions = {
+ *   maxTokenAge: 7200, // 2 hours
+ *   clockTolerance: 30,
+ *   rateLimiting: {
+ *     maxAttempts: 5,
+ *     windowMs: 15 * 60 * 1000 // 15 minutes
+ *   },
+ *   isTokenBlacklisted: async (tokenId) => {
+ *     // Check Redis or database for blacklisted tokens
+ *     return await redis.sismember('blacklisted_tokens', tokenId);
+ *   },
+ *   requiredClaims: {
+ *     issuer: 'secure-app',
+ *     audience: ['web-app', 'mobile-app']
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Production security configuration:
+ * ```typescript
+ * const productionOptions: AuthenticationOptions = {
+ *   maxTokenAge: 1800, // 30 minutes - short for security
+ *   clockTolerance: 10, // Tight tolerance
+ *   rateLimiting: {
+ *     maxAttempts: 3, // Strict rate limiting
+ *     windowMs: 30 * 60 * 1000 // 30 minutes lockout
+ *   },
+ *   isTokenBlacklisted: async (tokenId) => {
+ *     const result = await database.query(
+ *       'SELECT 1 FROM revoked_tokens WHERE jti = ?',
+ *       [tokenId]
+ *     );
+ *     return result.length > 0;
+ *   },
+ *   requiredClaims: {
+ *     issuer: 'production-auth-server',
+ *     audience: 'production-api'
+ *   }
+ * };
+ * ```
+ */
 export interface AuthenticationOptions {
     /**
      * Maximum token age in seconds (overrides exp claim validation)
@@ -42,11 +205,227 @@ export interface AuthenticationOptions {
         audience?: string | string[];
     };
 }
+/**
+ * Class-based authentication middleware with comprehensive security features.
+ * Provides JWT validation, rate limiting, token blacklisting, and security logging.
+ *
+ * @template T - The type of user data returned by the token verification port
+ *
+ * @example
+ * Basic JWT authentication:
+ * ```typescript
+ * import { Handler, AuthenticationMiddleware } from '@noony-serverless/core';
+ * import jwt from 'jsonwebtoken';
+ *
+ * interface User {
+ *   id: string;
+ *   email: string;
+ *   roles: string[];
+ * }
+ *
+ * class JWTVerifier implements CustomTokenVerificationPort<User> {
+ *   async verifyToken(token: string): Promise<User> {
+ *     const payload = jwt.verify(token, process.env.JWT_SECRET!) as any;
+ *     return {
+ *       id: payload.sub,
+ *       email: payload.email,
+ *       roles: payload.roles || []
+ *     };
+ *   }
+ * }
+ *
+ * const protectedHandler = new Handler()
+ *   .use(new AuthenticationMiddleware(new JWTVerifier()))
+ *   .handle(async (request, context) => {
+ *     const user = context.user as User;
+ *     return {
+ *       success: true,
+ *       data: { message: `Hello ${user.email}`, userId: user.id }
+ *     };
+ *   });
+ * ```
+ *
+ * @example
+ * Advanced authentication with security options:
+ * ```typescript
+ * const secureAuthMiddleware = new AuthenticationMiddleware(
+ *   new JWTVerifier(),
+ *   {
+ *     maxTokenAge: 1800, // 30 minutes
+ *     rateLimiting: {
+ *       maxAttempts: 5,
+ *       windowMs: 15 * 60 * 1000 // 15 minutes
+ *     },
+ *     isTokenBlacklisted: async (tokenId) => {
+ *       return await redis.sismember('revoked_tokens', tokenId);
+ *     },
+ *     requiredClaims: {
+ *       issuer: 'my-auth-server',
+ *       audience: 'my-api'
+ *     }
+ *   }
+ * );
+ *
+ * const secureHandler = new Handler()
+ *   .use(secureAuthMiddleware)
+ *   .handle(async (request, context) => {
+ *     // Only authenticated users reach here
+ *     return { success: true, data: 'Secure data' };
+ *   });
+ * ```
+ *
+ * @example
+ * Google Cloud Functions integration:
+ * ```typescript
+ * import { http } from '@google-cloud/functions-framework';
+ *
+ * const userProfileHandler = new Handler()
+ *   .use(new AuthenticationMiddleware(new JWTVerifier()))
+ *   .handle(async (request, context) => {
+ *     const user = context.user as User;
+ *     const profile = await getUserProfile(user.id);
+ *     return { success: true, data: profile };
+ *   });
+ *
+ * export const getUserProfile = http('getUserProfile', (req, res) => {
+ *   return userProfileHandler.execute(req, res);
+ * });
+ * ```
+ */
 export declare class AuthenticationMiddleware<T> implements BaseMiddleware {
     private tokenVerificationPort;
     private options;
     constructor(tokenVerificationPort: CustomTokenVerificationPort<T>, options?: AuthenticationOptions);
     before(context: Context): Promise<void>;
 }
+/**
+ * Factory function that creates an authentication middleware with token verification.
+ * Provides a functional approach for authentication setup.
+ *
+ * @template T - The type of user data returned by the token verification port
+ * @param tokenVerificationPort - The token verification implementation
+ * @param options - Authentication configuration options
+ * @returns A BaseMiddleware object with authentication logic
+ *
+ * @example
+ * Simple JWT authentication:
+ * ```typescript
+ * import { Handler, verifyAuthTokenMiddleware } from '@noony-serverless/core';
+ *
+ * class SimpleJWTVerifier implements CustomTokenVerificationPort<{ userId: string }> {
+ *   async verifyToken(token: string): Promise<{ userId: string }> {
+ *     // Simple token verification logic
+ *     if (token === 'valid-token') {
+ *       return { userId: 'user-123' };
+ *     }
+ *     throw new Error('Invalid token');
+ *   }
+ * }
+ *
+ * const handler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(new SimpleJWTVerifier()))
+ *   .handle(async (request, context) => {
+ *     const user = context.user as { userId: string };
+ *     return { success: true, userId: user.userId };
+ *   });
+ * ```
+ *
+ * @example
+ * API key authentication with rate limiting:
+ * ```typescript
+ * interface APIKeyUser {
+ *   keyId: string;
+ *   permissions: string[];
+ *   organization: string;
+ * }
+ *
+ * class APIKeyVerifier implements CustomTokenVerificationPort<APIKeyUser> {
+ *   async verifyToken(token: string): Promise<APIKeyUser> {
+ *     const keyData = await this.validateAPIKey(token);
+ *     if (!keyData) {
+ *       throw new Error('Invalid API key');
+ *     }
+ *     return keyData;
+ *   }
+ *
+ *   private async validateAPIKey(key: string): Promise<APIKeyUser | null> {
+ *     // Database lookup or external validation
+ *     return {
+ *       keyId: 'key-123',
+ *       permissions: ['read', 'write'],
+ *       organization: 'org-456'
+ *     };
+ *   }
+ * }
+ *
+ * const apiHandler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(
+ *     new APIKeyVerifier(),
+ *     {
+ *       rateLimiting: {
+ *         maxAttempts: 100,
+ *         windowMs: 60 * 1000 // 1 minute
+ *       }
+ *     }
+ *   ))
+ *   .handle(async (request, context) => {
+ *     const apiUser = context.user as APIKeyUser;
+ *     return {
+ *       success: true,
+ *       data: { organization: apiUser.organization }
+ *     };
+ *   });
+ * ```
+ *
+ * @example
+ * Express-style middleware chain:
+ * ```typescript
+ * import { Handler, verifyAuthTokenMiddleware, errorHandler } from '@noony-serverless/core';
+ *
+ * const authMiddleware = verifyAuthTokenMiddleware(
+ *   new JWTVerifier(),
+ *   {
+ *     maxTokenAge: 3600,
+ *     requiredClaims: {
+ *       issuer: 'my-app',
+ *       audience: 'api-users'
+ *     }
+ *   }
+ * );
+ *
+ * const protectedEndpoint = new Handler()
+ *   .use(authMiddleware)
+ *   .use(errorHandler())
+ *   .handle(async (request, context) => {
+ *     // Authenticated user available in context.user
+ *     return { success: true, data: 'Protected resource' };
+ *   });
+ * ```
+ *
+ * @example
+ * Multiple authentication strategies:
+ * ```typescript
+ * // Different handlers for different auth types
+ * const jwtHandler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(new JWTVerifier()))
+ *   .handle(jwtLogic);
+ *
+ * const apiKeyHandler = new Handler()
+ *   .use(verifyAuthTokenMiddleware(new APIKeyVerifier()))
+ *   .handle(apiKeyLogic);
+ *
+ * // Route based on authentication type
+ * export const handleRequest = (req: any, res: any) => {
+ *   const authHeader = req.headers.authorization;
+ *   if (authHeader?.startsWith('Bearer jwt.')) {
+ *     return jwtHandler.execute(req, res);
+ *   } else if (authHeader?.startsWith('Bearer ak_')) {
+ *     return apiKeyHandler.execute(req, res);
+ *   } else {
+ *     res.status(401).json({ error: 'Authentication required' });
+ *   }
+ * };
+ * ```
+ */
 export declare const verifyAuthTokenMiddleware: <T>(tokenVerificationPort: CustomTokenVerificationPort<T>, options?: AuthenticationOptions) => BaseMiddleware;
 //# sourceMappingURL=authenticationMiddleware.d.ts.map