@noony-serverless/core 0.1.5 → 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/bodyValidationMiddleware.d.ts

@@ -23,20 +23,21 @@ import { z } from 'zod';
  *
  * type UserRequest = z.infer<typeof userSchema>;
  *
- * async function handleCreateUser(context: Context<UserRequest, AuthenticatedUser>) {
+ * async function handleCreateUser(context: Context<UserRequest>) {
  *   const user = context.req.validatedBody!; // Fully typed
+ *   const authenticatedUser = context.user; // User type inferred from auth middleware
  *   return { success: true, user: { id: '123', ...user } };
  * }
  *
- * const createUserHandler = new Handler<UserRequest, AuthenticatedUser>()
- *   .use(new BodyValidationMiddleware<UserRequest, AuthenticatedUser>(userSchema))
+ * const createUserHandler = new Handler<UserRequest>()
+ *   .use(new BodyValidationMiddleware<UserRequest>(userSchema))
  *   .handle(handleCreateUser);
  * ```
  */
-export declare class BodyValidationMiddleware<T = unknown, U = unknown> implements BaseMiddleware<T, U> {
+export declare class BodyValidationMiddleware<T = unknown> implements BaseMiddleware<T> {
     private readonly schema;
     constructor(schema: z.ZodSchema<T>);
-    before(context: Context<T, U>): Promise<void>;
+    before(context: Context<T>): Promise<void>;
 }
 /**
  * Factory function that creates a body validation middleware with Zod schema validation.
@@ -59,18 +60,19 @@ export declare class BodyValidationMiddleware<T = unknown, U = unknown> implemen
  *
  * type LoginRequest = z.infer<typeof loginSchema>;
  *
- * async function handleLogin(context: Context<LoginRequest, AuthenticatedUser>) {
+ * async function handleLogin(context: Context<LoginRequest>) {
  *   const credentials = context.req.parsedBody as LoginRequest;
  *   const token = await authenticate(credentials.username, credentials.password);
+ *   const authenticatedUser = context.user; // User type from auth middleware
  *   return { success: true, token };
  * }
  *
- * const loginHandler = new Handler<LoginRequest, AuthenticatedUser>()
- *   .use(bodyValidatorMiddleware<LoginRequest, AuthenticatedUser>(loginSchema))
+ * const loginHandler = new Handler<LoginRequest>()
+ *   .use(bodyValidatorMiddleware<LoginRequest>(loginSchema))
  *   .handle(handleLogin);
  * ```
  */
-export declare const bodyValidatorMiddleware: <T, U = unknown>(schema: z.ZodType<T>) => {
-    before: (context: Context<T, U>) => Promise<void>;
+export declare const bodyValidatorMiddleware: <T>(schema: z.ZodType<T>) => {
+    before: (context: Context<T>) => Promise<void>;
 };
 //# sourceMappingURL=bodyValidationMiddleware.d.ts.map

package/build/middlewares/bodyValidationMiddleware.js

@@ -9,7 +9,7 @@ const validateBody = async (schema, data) => {
     }
     catch (error) {
         if (error instanceof zod_1.z.ZodError) {
-            throw new errors_1.ValidationError('Validation error', error.errors);
+            throw new errors_1.ValidationError('Validation error', error.issues);
         }
         throw error;
     }
@@ -36,13 +36,14 @@ const validateBody = async (schema, data) => {
  *
  * type UserRequest = z.infer<typeof userSchema>;
  *
- * async function handleCreateUser(context: Context<UserRequest, AuthenticatedUser>) {
+ * async function handleCreateUser(context: Context<UserRequest>) {
  *   const user = context.req.validatedBody!; // Fully typed
+ *   const authenticatedUser = context.user; // User type inferred from auth middleware
  *   return { success: true, user: { id: '123', ...user } };
  * }
  *
- * const createUserHandler = new Handler<UserRequest, AuthenticatedUser>()
- *   .use(new BodyValidationMiddleware<UserRequest, AuthenticatedUser>(userSchema))
+ * const createUserHandler = new Handler<UserRequest>()
+ *   .use(new BodyValidationMiddleware<UserRequest>(userSchema))
  *   .handle(handleCreateUser);
  * ```
  */
@@ -77,18 +78,19 @@ exports.BodyValidationMiddleware = BodyValidationMiddleware;
  *
  * type LoginRequest = z.infer<typeof loginSchema>;
  *
- * async function handleLogin(context: Context<LoginRequest, AuthenticatedUser>) {
+ * async function handleLogin(context: Context<LoginRequest>) {
  *   const credentials = context.req.parsedBody as LoginRequest;
  *   const token = await authenticate(credentials.username, credentials.password);
+ *   const authenticatedUser = context.user; // User type from auth middleware
  *   return { success: true, token };
  * }
  *
- * const loginHandler = new Handler<LoginRequest, AuthenticatedUser>()
- *   .use(bodyValidatorMiddleware<LoginRequest, AuthenticatedUser>(loginSchema))
+ * const loginHandler = new Handler<LoginRequest>()
+ *   .use(bodyValidatorMiddleware<LoginRequest>(loginSchema))
  *   .handle(handleLogin);
  * ```
  */
-// Modified to fix type instantiation error
+// Simplified factory function for body validation middleware
 const bodyValidatorMiddleware = (schema) => ({
     before: async (context) => {
         context.req.parsedBody = await validateBody(schema, context.req.body);

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

@@ -42,8 +42,8 @@
  *       return { valid: false, error: error.message };
  *     }
  *   },
- *   extractUserId: (decoded: any) => decoded.sub,
- *   isTokenExpired: (decoded: any) => decoded.exp < Date.now() / 1000
+ *   extractUserId: (decoded: unknown) => (decoded as any).sub,
+ *   isTokenExpired: (decoded: unknown) => (decoded as any).exp < Date.now() / 1000
  * };
  *
  * // Configure guard system
@@ -155,6 +155,13 @@ 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.
  * Provides fine-grained control over guard behavior for specific endpoints.
@@ -334,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
      *
@@ -461,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;