@morojs/moro 1.6.1 → 1.6.2

package/src/core/middleware/built-in/jwt-helpers.ts

@@ -0,0 +1,243 @@
+/**
+ * JWT Error Handling Utilities for Custom Middleware
+ *
+ * This module provides utilities to help users handle JWT errors gracefully
+ * in their custom authentication middleware.
+ */
+
+import { resolveUserPackage } from '../../utilities/package-utils.js';
+
+export interface JWTVerificationResult {
+  success: boolean;
+  payload?: any;
+  error?: {
+    type: 'expired' | 'invalid' | 'malformed' | 'missing_secret' | 'unknown';
+    message: string;
+    expiredAt?: Date;
+    date?: Date;
+  };
+}
+
+/**
+ * Safely verify a JWT token with proper error handling
+ *
+ * @param token - The JWT token to verify
+ * @param secret - The secret key for verification
+ * @param options - Additional JWT verification options
+ * @returns JWTVerificationResult with success status and payload or error details
+ */
+export async function safeVerifyJWT(
+  token: string,
+  secret: string,
+  options: any = {}
+): Promise<JWTVerificationResult> {
+  // Check if jsonwebtoken is available
+  let jwt: any;
+  try {
+    const jwtPath = resolveUserPackage('jsonwebtoken');
+    jwt = await import(jwtPath);
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        type: 'missing_secret',
+        message:
+          'JWT verification requires the "jsonwebtoken" package. ' +
+          'Please install it with: npm install jsonwebtoken @types/jsonwebtoken',
+      },
+    };
+  }
+
+  if (!secret) {
+    return {
+      success: false,
+      error: {
+        type: 'missing_secret',
+        message:
+          'JWT verification requires a secret. ' +
+          'Please provide a secret for token verification.',
+      },
+    };
+  }
+
+  try {
+    const payload = jwt.verify(token, secret, options);
+    return {
+      success: true,
+      payload,
+    };
+  } catch (error: any) {
+    // Handle specific JWT errors gracefully
+    if (error.name === 'TokenExpiredError') {
+      return {
+        success: false,
+        error: {
+          type: 'expired',
+          message: 'JWT token has expired',
+          expiredAt: error.expiredAt,
+        },
+      };
+    } else if (error.name === 'JsonWebTokenError') {
+      return {
+        success: false,
+        error: {
+          type: 'invalid',
+          message: 'Invalid JWT token format or signature',
+        },
+      };
+    } else if (error.name === 'NotBeforeError') {
+      return {
+        success: false,
+        error: {
+          type: 'malformed',
+          message: 'JWT token is not active yet',
+          date: error.date,
+        },
+      };
+    } else {
+      return {
+        success: false,
+        error: {
+          type: 'unknown',
+          message: `JWT verification failed: ${error.message}`,
+        },
+      };
+    }
+  }
+}
+
+/**
+ * Extract JWT token from Authorization header
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The JWT token or null if not found/invalid format
+ */
+export function extractJWTFromHeader(authHeader: string | undefined): string | null {
+  if (!authHeader) {
+    return null;
+  }
+
+  if (!authHeader.startsWith('Bearer ')) {
+    return null;
+  }
+
+  const token = authHeader.substring(7);
+  return token.trim() || null;
+}
+
+/**
+ * Create a standardized auth middleware error response
+ *
+ * @param error - The JWT verification error
+ * @returns Standardized error response object
+ */
+export function createAuthErrorResponse(error: JWTVerificationResult['error']) {
+  if (!error) {
+    return {
+      success: false,
+      error: 'Authentication failed',
+      message: 'Unknown authentication error',
+    };
+  }
+
+  switch (error.type) {
+    case 'expired':
+      return {
+        success: false,
+        error: 'Token expired',
+        message: 'Your session has expired. Please sign in again.',
+        expiredAt: error.expiredAt,
+      };
+
+    case 'invalid':
+      return {
+        success: false,
+        error: 'Invalid token',
+        message: 'The provided authentication token is invalid.',
+      };
+
+    case 'malformed':
+      return {
+        success: false,
+        error: 'Token not ready',
+        message: 'The authentication token is not yet valid.',
+        availableAt: error.date,
+      };
+
+    case 'missing_secret':
+      return {
+        success: false,
+        error: 'Configuration error',
+        message: 'Authentication service is not properly configured.',
+      };
+
+    default:
+      return {
+        success: false,
+        error: 'Authentication failed',
+        message: error.message || 'Authentication verification failed.',
+      };
+  }
+}
+
+/**
+ * Example usage for custom middleware with elegant error handling:
+ *
+ * ```typescript
+ * import { safeVerifyJWT, extractJWTFromHeader, createAuthErrorResponse } from '@morojs/moro';
+ *
+ * const authMiddleware = async (req: any, res: any, next: any) => {
+ *   const token = extractJWTFromHeader(req.headers.authorization);
+ *
+ *   if (!token) {
+ *     return res.status(401).json({
+ *       success: false,
+ *       error: 'Missing token',
+ *       message: 'Authorization header with Bearer token is required'
+ *     });
+ *   }
+ *
+ *   const result = safeVerifyJWT(token, process.env.JWT_SECRET!);
+ *
+ *   if (!result.success) {
+ *     // This provides elegant, user-friendly error messages instead of stack traces
+ *     const errorResponse = createAuthErrorResponse(result.error);
+ *     return res.status(401).json(errorResponse);
+ *   }
+ *
+ *   // Token is valid - attach user info to request
+ *   req.user = result.payload;
+ *   req.auth = {
+ *     user: result.payload,
+ *     isAuthenticated: true,
+ *     token
+ *   };
+ *
+ *   next();
+ * };
+ * ```
+ *
+ * Benefits of using safeVerifyJWT vs raw jsonwebtoken.verify():
+ *
+ * ❌ Raw approach (shows ugly error messages to users):
+ * ```typescript
+ * try {
+ *   const decoded = jwt.verify(token, secret);
+ *   req.user = decoded;
+ * } catch (error) {
+ *   // This exposes technical details and stack traces to users:
+ *   // "Invalid token: TokenExpiredError: jwt expired at /node_modules/jsonwebtoken/verify.js:190:21..."
+ *   throw error; // BAD - exposes internal details
+ * }
+ * ```
+ *
+ * ✅ Safe approach (shows clean, user-friendly messages):
+ * ```typescript
+ * const result = safeVerifyJWT(token, secret);
+ * if (!result.success) {
+ *   // This returns clean messages like:
+ *   // { "error": "Token expired", "message": "Your session has expired. Please sign in again." }
+ *   return res.status(401).json(createAuthErrorResponse(result.error));
+ * }
+ * ```
+ */

package/src/core/middleware/built-in/performance-monitor.ts

@@ -1,5 +1,5 @@
 // Performance monitoring middleware
-import { createFrameworkLogger } from '../../logger';
+import { createFrameworkLogger } from '../../logger/index.js';
 
 const logger = createFrameworkLogger('PerformanceMonitor');
 

package/src/core/middleware/built-in/rate-limit.ts

@@ -1,6 +1,6 @@
 // Rate Limiting Middleware
-import { MiddlewareInterface, HookContext } from '../../../types/hooks';
-import { createFrameworkLogger } from '../../logger';
+import { MiddlewareInterface, HookContext } from '../../../types/hooks.js';
+import { createFrameworkLogger } from '../../logger/index.js';
 
 const logger = createFrameworkLogger('RateLimitMiddleware');
 

package/src/core/middleware/built-in/request-logger.ts

@@ -1,5 +1,7 @@
 // Simple request logging middleware
-import { logger } from '../../logger';
+import { createFrameworkLogger } from '../../logger/index.js';
+
+const logger = createFrameworkLogger('RequestLogger');
 
 export const requestLogger = async (context: any): Promise<void> => {
   const startTime = Date.now();

package/src/core/middleware/built-in/session.ts

@@ -1,10 +1,11 @@
 // Session Middleware
-import { MiddlewareInterface, HookContext } from '../../../types/hooks';
-import { createFrameworkLogger } from '../../logger';
-import { CacheAdapter } from '../../../types/cache';
-import { MemoryCacheAdapter } from './adapters/cache/memory';
-import { RedisCacheAdapter } from './adapters/cache/redis';
-import { FileCacheAdapter } from './adapters/cache/file';
+import crypto from 'crypto';
+import { MiddlewareInterface, HookContext } from '../../../types/hooks.js';
+import { createFrameworkLogger } from '../../logger/index.js';
+import { CacheAdapter } from '../../../types/cache.js';
+import { MemoryCacheAdapter } from './adapters/cache/memory.js';
+import { RedisCacheAdapter } from './adapters/cache/redis.js';
+import { FileCacheAdapter } from './adapters/cache/file.js';
 
 const logger = createFrameworkLogger('SessionMiddleware');
 
@@ -157,7 +158,6 @@ class Session {
       return this.options.genid();
     }
 
-    const crypto = require('crypto');
     return crypto.randomBytes(24).toString('hex');
   }
 
@@ -229,7 +229,6 @@ export const session = (options: SessionOptions = {}): MiddlewareInterface => ({
       if (config.genid) {
         return config.genid();
       }
-      const crypto = require('crypto');
       return crypto.randomBytes(24).toString('hex');
     };
 

package/src/core/middleware/built-in/sse.ts

@@ -1,6 +1,6 @@
 // Server-Sent Events Middleware
-import { MiddlewareInterface, HookContext } from '../../../types/hooks';
-import { createFrameworkLogger } from '../../logger';
+import { MiddlewareInterface, HookContext } from '../../../types/hooks.js';
+import { createFrameworkLogger } from '../../logger/index.js';
 
 const logger = createFrameworkLogger('SSEMiddleware');
 
@@ -35,13 +35,15 @@ export const sse = (
       logger.debug('Setting up SSE connection', 'SSESetup');
 
       // Set SSE headers
-      res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        Connection: 'keep-alive',
-        'Access-Control-Allow-Origin': options.cors ? '*' : undefined,
-        'Access-Control-Allow-Headers': options.cors ? 'Cache-Control' : undefined,
-      });
+      if (!res.headersSent) {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+          'Access-Control-Allow-Origin': options.cors ? '*' : undefined,
+          'Access-Control-Allow-Headers': options.cors ? 'Cache-Control' : undefined,
+        });
+      }
 
       // Add SSE methods to response
       res.sendEvent = (data: any, event?: string, id?: string) => {

package/src/core/middleware/built-in/validation.ts

@@ -1,6 +1,6 @@
 // Validation Middleware
-import { MiddlewareInterface, HookContext } from '../../../types/hooks';
-import { createFrameworkLogger } from '../../logger';
+import { MiddlewareInterface, HookContext } from '../../../types/hooks.js';
+import { createFrameworkLogger } from '../../logger/index.js';
 
 const logger = createFrameworkLogger('ValidationMiddleware');
 

package/src/core/middleware/index.ts

@@ -1,17 +1,17 @@
 // Middleware System for Moro
 import { EventEmitter } from 'events';
-import { HookManager } from '../utilities';
+import { HookManager } from '../utilities/index.js';
 import {
   MiddlewareMetadata,
   MiddlewareContext,
   MiddlewareInterface,
   SimpleMiddlewareFunction,
   MoroMiddleware,
-} from '../../types/hooks';
-import { createFrameworkLogger } from '../logger';
+} from '../../types/hooks.js';
+import { createFrameworkLogger } from '../logger/index.js';
 
 // Export types needed by built-in middleware
-export type { MiddlewareInterface, MoroMiddleware } from '../../types/hooks';
+export type { MiddlewareInterface, MoroMiddleware } from '../../types/hooks.js';
 
 export class MiddlewareManager extends EventEmitter {
   private middleware = new Map<string, MiddlewareInterface>();
@@ -173,5 +173,5 @@ export class MiddlewareManager extends EventEmitter {
 }
 
 // Built-in middleware exports
-export { builtInMiddleware, simpleMiddleware } from './built-in';
-export * from './built-in';
+export { builtInMiddleware, simpleMiddleware } from './built-in/index.js';
+export * from './built-in/index.js';