@morojs/moro 1.5.11 → 1.5.12

package/dist/core/middleware/built-in/index.d.ts

@@ -13,6 +13,7 @@ export { session } from './session';
 export { cache } from './cache';
 export { cdn } from './cdn';
 export { requireAuth, requireRole, requirePermission, requireAdmin, guestOnly, optionalAuth, withAuth, protectedRoute, authUtils, authResponses, sessionHelpers, } from './auth-helpers';
+export { safeVerifyJWT, extractJWTFromHeader, createAuthErrorResponse, type JWTVerificationResult, } from './jwt-helpers';
 export { extendedProviders, enterpriseProviders, createCustomOAuthProvider, createCustomOIDCProvider, } from './auth-providers';
 export declare const builtInMiddleware: {
     auth: (options: import("../../..").AuthOptions) => import("..").MiddlewareInterface;

package/dist/core/middleware/built-in/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.simpleMiddleware = exports.builtInMiddleware = exports.createCustomOIDCProvider = exports.createCustomOAuthProvider = exports.enterpriseProviders = exports.extendedProviders = exports.sessionHelpers = exports.authResponses = exports.authUtils = exports.protectedRoute = exports.withAuth = exports.optionalAuth = exports.guestOnly = exports.requireAdmin = exports.requirePermission = exports.requireRole = exports.requireAuth = exports.cdn = exports.cache = exports.session = exports.sse = exports.csp = exports.csrf = exports.cookie = exports.errorTracker = exports.performanceMonitor = exports.requestLogger = exports.validation = exports.cors = exports.rateLimit = exports.auth = void 0;
+exports.simpleMiddleware = exports.builtInMiddleware = exports.createCustomOIDCProvider = exports.createCustomOAuthProvider = exports.enterpriseProviders = exports.extendedProviders = exports.createAuthErrorResponse = exports.extractJWTFromHeader = exports.safeVerifyJWT = exports.sessionHelpers = exports.authResponses = exports.authUtils = exports.protectedRoute = exports.withAuth = exports.optionalAuth = exports.guestOnly = exports.requireAdmin = exports.requirePermission = exports.requireRole = exports.requireAuth = exports.cdn = exports.cache = exports.session = exports.sse = exports.csp = exports.csrf = exports.cookie = exports.errorTracker = exports.performanceMonitor = exports.requestLogger = exports.validation = exports.cors = exports.rateLimit = exports.auth = void 0;
 // Built-in Middleware Exports
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "auth", { enumerable: true, get: function () { return auth_1.auth; } });
@@ -45,6 +45,11 @@ Object.defineProperty(exports, "protectedRoute", { enumerable: true, get: functi
 Object.defineProperty(exports, "authUtils", { enumerable: true, get: function () { return auth_helpers_1.authUtils; } });
 Object.defineProperty(exports, "authResponses", { enumerable: true, get: function () { return auth_helpers_1.authResponses; } });
 Object.defineProperty(exports, "sessionHelpers", { enumerable: true, get: function () { return auth_helpers_1.sessionHelpers; } });
+// JWT Utilities for Custom Middleware
+var jwt_helpers_1 = require("./jwt-helpers");
+Object.defineProperty(exports, "safeVerifyJWT", { enumerable: true, get: function () { return jwt_helpers_1.safeVerifyJWT; } });
+Object.defineProperty(exports, "extractJWTFromHeader", { enumerable: true, get: function () { return jwt_helpers_1.extractJWTFromHeader; } });
+Object.defineProperty(exports, "createAuthErrorResponse", { enumerable: true, get: function () { return jwt_helpers_1.createAuthErrorResponse; } });
 var auth_providers_1 = require("./auth-providers");
 Object.defineProperty(exports, "extendedProviders", { enumerable: true, get: function () { return auth_providers_1.extendedProviders; } });
 Object.defineProperty(exports, "enterpriseProviders", { enumerable: true, get: function () { return auth_providers_1.enterpriseProviders; } });

package/dist/core/middleware/built-in/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/middleware/built-in/index.ts"],"names":[],"mappings":";;;AAAA,8BAA8B;AAC9B,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAClB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,6DAA2D;AAAlD,yHAAA,kBAAkB,OAAA;AAC3B,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAErB,6CAA6C;AAC7C,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AACZ,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AACZ,qCAAoC;AAA3B,kGAAA,OAAO,OAAA;AAEhB,gCAAgC;AAChC,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AACd,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AAEZ,sCAAsC;AACtC,+CAYwB;AAXtB,2GAAA,WAAW,OAAA;AACX,2GAAA,WAAW,OAAA;AACX,iHAAA,iBAAiB,OAAA;AACjB,4GAAA,YAAY,OAAA;AACZ,yGAAA,SAAS,OAAA;AACT,4GAAA,YAAY,OAAA;AACZ,wGAAA,QAAQ,OAAA;AACR,8GAAA,cAAc,OAAA;AACd,yGAAA,SAAS,OAAA;AACT,6GAAA,aAAa,OAAA;AACb,8GAAA,cAAc,OAAA;AAGhB,mDAK0B;AAJxB,mHAAA,iBAAiB,OAAA;AACjB,qHAAA,mBAAmB,OAAA;AACnB,2HAAA,yBAAyB,OAAA;AACzB,0HAAA,wBAAwB,OAAA;AAG1B,yBAAyB;AACzB,iCAA8B;AAC9B,6CAAyC;AACzC,iCAA8B;AAC9B,6CAA0C;AAC1C,qDAAiD;AACjD,+DAA2D;AAC3D,mDAA+C;AAC/C,qCAAkC;AAClC,iCAA8B;AAC9B,+BAA4B;AAC5B,+BAA4B;AAC5B,uCAAoC;AACpC,mCAAgC;AAChC,+BAA4B;AAEf,QAAA,iBAAiB,GAAG;IAC/B,IAAI,EAAJ,WAAI;IACJ,SAAS,EAAT,sBAAS;IACT,IAAI,EAAJ,WAAI;IACJ,UAAU,EAAV,uBAAU;IACV,sBAAsB;IACtB,MAAM,EAAN,eAAM;IACN,IAAI,EAAJ,WAAI;IACJ,GAAG,EAAH,SAAG;IACH,GAAG,EAAH,SAAG;IACH,OAAO,EAAP,iBAAO;IACP,gCAAgC;IAChC,KAAK,EAAL,aAAK;IACL,GAAG,EAAH,SAAG;CACJ,CAAC;AAEW,QAAA,gBAAgB,GAAG;IAC9B,aAAa,EAAb,8BAAa;IACb,kBAAkB,EAAlB,wCAAkB;IAClB,YAAY,EAAZ,4BAAY;CACb,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/middleware/built-in/index.ts"],"names":[],"mappings":";;;AAAA,8BAA8B;AAC9B,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAClB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,6DAA2D;AAAlD,yHAAA,kBAAkB,OAAA;AAC3B,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAErB,6CAA6C;AAC7C,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AACZ,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AACZ,qCAAoC;AAA3B,kGAAA,OAAO,OAAA;AAEhB,gCAAgC;AAChC,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AACd,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AAEZ,sCAAsC;AACtC,+CAYwB;AAXtB,2GAAA,WAAW,OAAA;AACX,2GAAA,WAAW,OAAA;AACX,iHAAA,iBAAiB,OAAA;AACjB,4GAAA,YAAY,OAAA;AACZ,yGAAA,SAAS,OAAA;AACT,4GAAA,YAAY,OAAA;AACZ,wGAAA,QAAQ,OAAA;AACR,8GAAA,cAAc,OAAA;AACd,yGAAA,SAAS,OAAA;AACT,6GAAA,aAAa,OAAA;AACb,8GAAA,cAAc,OAAA;AAGhB,sCAAsC;AACtC,6CAKuB;AAJrB,4GAAA,aAAa,OAAA;AACb,mHAAA,oBAAoB,OAAA;AACpB,sHAAA,uBAAuB,OAAA;AAIzB,mDAK0B;AAJxB,mHAAA,iBAAiB,OAAA;AACjB,qHAAA,mBAAmB,OAAA;AACnB,2HAAA,yBAAyB,OAAA;AACzB,0HAAA,wBAAwB,OAAA;AAG1B,yBAAyB;AACzB,iCAA8B;AAC9B,6CAAyC;AACzC,iCAA8B;AAC9B,6CAA0C;AAC1C,qDAAiD;AACjD,+DAA2D;AAC3D,mDAA+C;AAC/C,qCAAkC;AAClC,iCAA8B;AAC9B,+BAA4B;AAC5B,+BAA4B;AAC5B,uCAAoC;AACpC,mCAAgC;AAChC,+BAA4B;AAEf,QAAA,iBAAiB,GAAG;IAC/B,IAAI,EAAJ,WAAI;IACJ,SAAS,EAAT,sBAAS;IACT,IAAI,EAAJ,WAAI;IACJ,UAAU,EAAV,uBAAU;IACV,sBAAsB;IACtB,MAAM,EAAN,eAAM;IACN,IAAI,EAAJ,WAAI;IACJ,GAAG,EAAH,SAAG;IACH,GAAG,EAAH,SAAG;IACH,OAAO,EAAP,iBAAO;IACP,gCAAgC;IAChC,KAAK,EAAL,aAAK;IACL,GAAG,EAAH,SAAG;CACJ,CAAC;AAEW,QAAA,gBAAgB,GAAG;IAC9B,aAAa,EAAb,8BAAa;IACb,kBAAkB,EAAlB,wCAAkB;IAClB,YAAY,EAAZ,4BAAY;CACb,CAAC"}

package/dist/core/middleware/built-in/jwt-helpers.d.ts

@@ -0,0 +1,93 @@
+/**
+ * JWT Error Handling Utilities for Custom Middleware
+ *
+ * This module provides utilities to help users handle JWT errors gracefully
+ * in their custom authentication middleware.
+ */
+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 declare function safeVerifyJWT(token: string, secret: string, options?: any): JWTVerificationResult;
+/**
+ * Extract JWT token from Authorization header
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The JWT token or null if not found/invalid format
+ */
+export declare function extractJWTFromHeader(authHeader: string | undefined): string | null;
+/**
+ * Create a standardized auth middleware error response
+ *
+ * @param error - The JWT verification error
+ * @returns Standardized error response object
+ */
+export declare function createAuthErrorResponse(error: JWTVerificationResult['error']): {
+    success: boolean;
+    error: string;
+    message: string;
+    expiredAt?: undefined;
+    availableAt?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    message: string;
+    expiredAt: Date | undefined;
+    availableAt?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    message: string;
+    availableAt: Date | undefined;
+    expiredAt?: undefined;
+};
+/**
+ * Example usage for custom middleware:
+ *
+ * ```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) {
+ *     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();
+ * };
+ * ```
+ */

package/dist/core/middleware/built-in/jwt-helpers.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * JWT Error Handling Utilities for Custom Middleware
+ *
+ * This module provides utilities to help users handle JWT errors gracefully
+ * in their custom authentication middleware.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeVerifyJWT = safeVerifyJWT;
+exports.extractJWTFromHeader = extractJWTFromHeader;
+exports.createAuthErrorResponse = createAuthErrorResponse;
+/**
+ * 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
+ */
+function safeVerifyJWT(token, secret, options = {}) {
+    // Check if jsonwebtoken is available
+    let jwt;
+    try {
+        jwt = require('jsonwebtoken');
+    }
+    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) {
+        // 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
+ */
+function extractJWTFromHeader(authHeader) {
+    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
+ */
+function createAuthErrorResponse(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:
+ *
+ * ```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) {
+ *     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();
+ * };
+ * ```
+ */
+//# sourceMappingURL=jwt-helpers.js.map

package/dist/core/middleware/built-in/jwt-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-helpers.js","sourceRoot":"","sources":["../../../../src/core/middleware/built-in/jwt-helpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morojs/moro",
-  "version": "1.5.11",
+  "version": "1.5.12",
   "description": "High-performance Node.js framework with intelligent routing, automatic middleware ordering, enterprise authentication (Auth.js), type-safe validation, and functional architecture",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -33,6 +33,14 @@ export {
   sessionHelpers,
 } from './auth-helpers';
 
+// JWT Utilities for Custom Middleware
+export {
+  safeVerifyJWT,
+  extractJWTFromHeader,
+  createAuthErrorResponse,
+  type JWTVerificationResult,
+} from './jwt-helpers';
+
 export {
   extendedProviders,
   enterpriseProviders,

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

@@ -0,0 +1,215 @@
+/**
+ * JWT Error Handling Utilities for Custom Middleware
+ *
+ * This module provides utilities to help users handle JWT errors gracefully
+ * in their custom authentication middleware.
+ */
+
+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 function safeVerifyJWT(
+  token: string,
+  secret: string,
+  options: any = {}
+): JWTVerificationResult {
+  // Check if jsonwebtoken is available
+  let jwt: any;
+  try {
+    jwt = require('jsonwebtoken');
+  } 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:
+ *
+ * ```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) {
+ *     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();
+ * };
+ * ```
+ */