@noony-serverless/core 0.1.5 → 0.2.1

package/build/middlewares/guards/adapters/CustomTokenVerificationPortAdapter.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * CustomTokenVerificationPort Adapter
+ *
+ * Bridges the CustomTokenVerificationPort interface from AuthenticationMiddleware
+ * to the RouteGuards TokenValidator interface, enabling code reuse and unified
+ * token validation across the entire Noony Framework.
+ *
+ * Key Features:
+ * - Seamless integration between authentication systems
+ * - Maintains type safety through generics
+ * - Supports any token validation implementation (JWT, OAuth, API keys, etc.)
+ * - Preserves all existing RouteGuards functionality
+ * - Zero-overhead abstraction with full performance
+ *
+ * Benefits:
+ * - One authentication interface to implement and maintain
+ * - Consistent patterns across AuthenticationMiddleware and RouteGuards
+ * - Backward compatibility with existing RouteGuards implementations
+ * - Simplified setup for authentication workflows
+ *
+ * @example
+ * Bridge a JWT verification port to RouteGuards:
+ * ```typescript
+ * import { CustomTokenVerificationPort } from '@/middlewares/authenticationMiddleware';
+ * import { CustomTokenVerificationPortAdapter } from '@/middlewares/guards/adapters';
+ *
+ * // Define your user type
+ * interface User {
+ *   id: string;
+ *   email: string;
+ *   roles: string[];
+ *   sub: string;  // JWT subject
+ *   exp: number;  // JWT expiration
+ *   iat: number;  // Issued at
+ * }
+ *
+ * // Implement token verification once
+ * const jwtVerifier: 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 || [],
+ *       sub: payload.sub,
+ *       exp: payload.exp,
+ *       iat: payload.iat
+ *     };
+ *   }
+ * };
+ *
+ * // Create adapter for RouteGuards
+ * const tokenValidator = new CustomTokenVerificationPortAdapter(
+ *   jwtVerifier,
+ *   {
+ *     userIdExtractor: (user: User) => user.id,
+ *     expirationExtractor: (user: User) => user.exp
+ *   }
+ * );
+ *
+ * // Use with RouteGuards
+ * await RouteGuards.configure(
+ *   GuardSetup.production(),
+ *   userPermissionSource,
+ *   tokenValidator, // Works seamlessly!
+ *   authConfig
+ * );
+ * ```
+ *
+ * @example
+ * API key verification with custom user structure:
+ * ```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 validateAPIKey(token);
+ *     if (!keyData || !keyData.isActive) {
+ *       throw new Error('Invalid or inactive API key');
+ *     }
+ *     return keyData;
+ *   }
+ * };
+ *
+ * // Adapter with custom extractors
+ * const apiTokenValidator = new CustomTokenVerificationPortAdapter(
+ *   apiKeyVerifier,
+ *   {
+ *     userIdExtractor: (user: APIKeyUser) => user.keyId,
+ *     expirationExtractor: (user: APIKeyUser) => user.expiresAt,
+ *     additionalValidation: (user: APIKeyUser) => user.isActive
+ *   }
+ * );
+ *
+ * // Seamlessly works with RouteGuards
+ * await RouteGuards.configure(
+ *   GuardSetup.production(),
+ *   userPermissionSource,
+ *   apiTokenValidator,
+ *   authConfig
+ * );
+ * ```
+ *
+ * @example
+ * OAuth token verification:
+ * ```typescript
+ * interface OAuthUser {
+ *   sub: string;        // OAuth subject
+ *   email: string;
+ *   scope: string[];    // OAuth scopes
+ *   exp: number;
+ *   client_id: string;
+ * }
+ *
+ * const oauthVerifier: CustomTokenVerificationPort<OAuthUser> = {
+ *   async verifyToken(token: string): Promise<OAuthUser> {
+ *     // Validate with OAuth provider
+ *     const response = await fetch(`${OAUTH_INTROSPECT_URL}`, {
+ *       method: 'POST',
+ *       headers: { 'Authorization': `Bearer ${token}` }
+ *     });
+ *
+ *     const tokenInfo = await response.json();
+ *     if (!tokenInfo.active) {
+ *       throw new Error('Token is not active');
+ *     }
+ *
+ *     return tokenInfo as OAuthUser;
+ *   }
+ * };
+ *
+ * const oauthTokenValidator = new CustomTokenVerificationPortAdapter(
+ *   oauthVerifier,
+ *   {
+ *     userIdExtractor: (user: OAuthUser) => user.sub,
+ *     expirationExtractor: (user: OAuthUser) => user.exp
+ *   }
+ * );
+ * ```
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenVerificationAdapterFactory = exports.CustomTokenVerificationPortAdapter = void 0;
+/**
+ * Adapter class that bridges CustomTokenVerificationPort to TokenValidator.
+ * Enables seamless integration between AuthenticationMiddleware and RouteGuards
+ * while maintaining full type safety and performance.
+ *
+ * @template T - The user type returned by the CustomTokenVerificationPort
+ */
+class CustomTokenVerificationPortAdapter {
+    verificationPort;
+    config;
+    constructor(verificationPort, config) {
+        this.verificationPort = verificationPort;
+        this.config = config;
+    }
+    /**
+     * Validate and decode token using the wrapped CustomTokenVerificationPort.
+     *
+     * @param token - JWT token string to validate
+     * @returns Validation result with decoded user data
+     */
+    async validateToken(token) {
+        try {
+            // Use the wrapped verification port to verify the token
+            const user = await this.verificationPort.verifyToken(token);
+            // Run additional validation if configured
+            if (this.config.additionalValidation) {
+                const additionalValid = await this.config.additionalValidation(user);
+                if (!additionalValid) {
+                    return {
+                        valid: false,
+                        error: this.config.errorMessage || 'Additional validation failed',
+                    };
+                }
+            }
+            return {
+                valid: true,
+                decoded: user,
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: this.config.errorMessage ||
+                    (error instanceof Error ? error.message : 'Token validation failed'),
+            };
+        }
+    }
+    /**
+     * Extract user ID from the decoded token/user data.
+     * Uses the configured userIdExtractor function.
+     *
+     * @param decoded - Decoded user data from validateToken
+     * @returns User ID string
+     */
+    extractUserId(decoded) {
+        return this.config.userIdExtractor(decoded);
+    }
+    /**
+     * Check if the token is expired based on the decoded data.
+     * Uses the configured expirationExtractor if available.
+     *
+     * @param decoded - Decoded user data from validateToken
+     * @returns true if token is expired, false otherwise
+     */
+    isTokenExpired(decoded) {
+        if (!this.config.expirationExtractor) {
+            // If no expiration extractor is configured, assume token is valid
+            return false;
+        }
+        const expirationTime = this.config.expirationExtractor(decoded);
+        if (!expirationTime) {
+            // If no expiration time is available, assume token is valid
+            return false;
+        }
+        // Compare with current time (convert to seconds)
+        const currentTime = Math.floor(Date.now() / 1000);
+        return expirationTime <= currentTime;
+    }
+}
+exports.CustomTokenVerificationPortAdapter = CustomTokenVerificationPortAdapter;
+/**
+ * Helper factory functions for common token verification scenarios.
+ * Provides pre-configured adapters for standard authentication patterns.
+ */
+class TokenVerificationAdapterFactory {
+    /**
+     * Create adapter for standard JWT tokens with common claims.
+     * Assumes the user object has 'sub' for user ID and 'exp' for expiration.
+     *
+     * @param verificationPort - JWT token verification port
+     * @returns Configured adapter for JWT tokens
+     */
+    static forJWT(verificationPort) {
+        return new CustomTokenVerificationPortAdapter(verificationPort, {
+            userIdExtractor: (user) => user.sub,
+            expirationExtractor: (user) => user.exp,
+        });
+    }
+    /**
+     * Create adapter for API key tokens with custom ID and expiration fields.
+     *
+     * @param verificationPort - API key verification port
+     * @param userIdField - Field name for user/key ID (e.g., 'keyId', 'apiKeyId')
+     * @param expirationField - Optional field name for expiration (e.g., 'expiresAt', 'exp')
+     * @returns Configured adapter for API key tokens
+     */
+    static forAPIKey(verificationPort, userIdField, expirationField) {
+        return new CustomTokenVerificationPortAdapter(verificationPort, {
+            userIdExtractor: (user) => String(user[userIdField]),
+            expirationExtractor: expirationField
+                ? (user) => user[expirationField]
+                : undefined,
+        });
+    }
+    /**
+     * Create adapter for OAuth tokens with standard OAuth claims.
+     *
+     * @param verificationPort - OAuth token verification port
+     * @param additionalScopes - Optional required OAuth scopes
+     * @returns Configured adapter for OAuth tokens
+     */
+    static forOAuth(verificationPort, additionalScopes) {
+        return new CustomTokenVerificationPortAdapter(verificationPort, {
+            userIdExtractor: (user) => user.sub,
+            expirationExtractor: (user) => user.exp,
+            additionalValidation: additionalScopes
+                ? (user) => {
+                    if (!user.scope || !Array.isArray(user.scope)) {
+                        return false;
+                    }
+                    return additionalScopes.every((requiredScope) => user.scope.includes(requiredScope));
+                }
+                : undefined,
+        });
+    }
+    /**
+     * Create adapter with custom configuration.
+     * Use this for non-standard token structures or complex validation logic.
+     *
+     * @param verificationPort - Token verification port
+     * @param config - Custom adapter configuration
+     * @returns Configured adapter with custom settings
+     */
+    static custom(verificationPort, config) {
+        return new CustomTokenVerificationPortAdapter(verificationPort, config);
+    }
+}
+exports.TokenVerificationAdapterFactory = TokenVerificationAdapterFactory;
+//# sourceMappingURL=CustomTokenVerificationPortAdapter.js.map

package/build/middlewares/guards/config/GuardConfiguration.d.ts

@@ -607,6 +607,56 @@ export declare class GuardConfiguration {
      * // defaultTtlMs must be at least 1000ms (1 second)
      * ```
      */
+    /**
+     * Check if caching is enabled via environment variable.
+     *
+     * Caching is disabled by default for security-first approach.
+     * Only enabled when NOONY_GUARD_CACHE_ENABLE is explicitly set to 'true'.
+     *
+     * @returns true if caching should be enabled, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Caching disabled (default)
+     * process.env.NOONY_GUARD_CACHE_ENABLE = undefined;
+     * console.log(GuardConfiguration.isCachingEnabled()); // false
+     *
+     * // Caching enabled
+     * process.env.NOONY_GUARD_CACHE_ENABLE = 'true';
+     * console.log(GuardConfiguration.isCachingEnabled()); // true
+     *
+     * // Caching disabled (any other value)
+     * process.env.NOONY_GUARD_CACHE_ENABLE = 'false';
+     * console.log(GuardConfiguration.isCachingEnabled()); // false
+     * ```
+     */
+    static isCachingEnabled(): boolean;
+    /**
+     * Get effective cache type considering environment variable override.
+     *
+     * Environment variable takes precedence for security:
+     * - If NOONY_GUARD_CACHE_ENABLE is not 'true', returns 'none'
+     * - Otherwise returns the specified cacheType
+     *
+     * @param cacheType - Configured cache type
+     * @returns Effective cache type after environment variable consideration
+     *
+     * @example
+     * ```typescript
+     * // Environment variable not set - caching disabled
+     * process.env.NOONY_GUARD_CACHE_ENABLE = undefined;
+     * console.log(GuardConfiguration.getEffectiveCacheType('memory')); // 'none'
+     * console.log(GuardConfiguration.getEffectiveCacheType('redis')); // 'none'
+     * console.log(GuardConfiguration.getEffectiveCacheType('none')); // 'none'
+     *
+     * // Environment variable enabled - respect cacheType
+     * process.env.NOONY_GUARD_CACHE_ENABLE = 'true';
+     * console.log(GuardConfiguration.getEffectiveCacheType('memory')); // 'memory'
+     * console.log(GuardConfiguration.getEffectiveCacheType('redis')); // 'redis'
+     * console.log(GuardConfiguration.getEffectiveCacheType('none')); // 'none'
+     * ```
+     */
+    static getEffectiveCacheType(cacheType: 'memory' | 'redis' | 'none'): 'memory' | 'redis' | 'none';
     validate(): void;
 }
 //# sourceMappingURL=GuardConfiguration.d.ts.map

package/build/middlewares/guards/config/GuardConfiguration.js

@@ -312,6 +312,65 @@ class GuardConfiguration {
      * // defaultTtlMs must be at least 1000ms (1 second)
      * ```
      */
+    /**
+     * Check if caching is enabled via environment variable.
+     *
+     * Caching is disabled by default for security-first approach.
+     * Only enabled when NOONY_GUARD_CACHE_ENABLE is explicitly set to 'true'.
+     *
+     * @returns true if caching should be enabled, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Caching disabled (default)
+     * process.env.NOONY_GUARD_CACHE_ENABLE = undefined;
+     * console.log(GuardConfiguration.isCachingEnabled()); // false
+     *
+     * // Caching enabled
+     * process.env.NOONY_GUARD_CACHE_ENABLE = 'true';
+     * console.log(GuardConfiguration.isCachingEnabled()); // true
+     *
+     * // Caching disabled (any other value)
+     * process.env.NOONY_GUARD_CACHE_ENABLE = 'false';
+     * console.log(GuardConfiguration.isCachingEnabled()); // false
+     * ```
+     */
+    static isCachingEnabled() {
+        return process.env.NOONY_GUARD_CACHE_ENABLE === 'true';
+    }
+    /**
+     * Get effective cache type considering environment variable override.
+     *
+     * Environment variable takes precedence for security:
+     * - If NOONY_GUARD_CACHE_ENABLE is not 'true', returns 'none'
+     * - Otherwise returns the specified cacheType
+     *
+     * @param cacheType - Configured cache type
+     * @returns Effective cache type after environment variable consideration
+     *
+     * @example
+     * ```typescript
+     * // Environment variable not set - caching disabled
+     * process.env.NOONY_GUARD_CACHE_ENABLE = undefined;
+     * console.log(GuardConfiguration.getEffectiveCacheType('memory')); // 'none'
+     * console.log(GuardConfiguration.getEffectiveCacheType('redis')); // 'none'
+     * console.log(GuardConfiguration.getEffectiveCacheType('none')); // 'none'
+     *
+     * // Environment variable enabled - respect cacheType
+     * process.env.NOONY_GUARD_CACHE_ENABLE = 'true';
+     * console.log(GuardConfiguration.getEffectiveCacheType('memory')); // 'memory'
+     * console.log(GuardConfiguration.getEffectiveCacheType('redis')); // 'redis'
+     * console.log(GuardConfiguration.getEffectiveCacheType('none')); // 'none'
+     * ```
+     */
+    static getEffectiveCacheType(cacheType) {
+        // If caching is disabled by environment variable, always return 'none'
+        if (!GuardConfiguration.isCachingEnabled()) {
+            return 'none';
+        }
+        // Otherwise return the specified cache type
+        return cacheType;
+    }
     validate() {
         if (this.security.maxPatternDepth !== undefined &&
             (this.security.maxPatternDepth < 2 || this.security.maxPatternDepth > 3)) {

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

@@ -43,7 +43,7 @@ export interface AuthenticationResult {
     success: boolean;
     user?: UserContext;
     token?: {
-        decoded: any;
+        decoded: unknown;
         raw: string;
         expiresAt: string;
         issuer?: string;
@@ -63,7 +63,7 @@ export interface AuthGuardConfig {
     allowedIssuers?: string[];
     requireEmailVerification: boolean;
     allowInactiveUsers: boolean;
-    customValidation?: (token: any, user: UserContext) => Promise<boolean>;
+    customValidation?: (token: unknown, user: UserContext) => Promise<boolean>;
 }
 /**
  * Token validation service interface
@@ -74,17 +74,17 @@ export interface TokenValidator {
      */
     validateToken(token: string): Promise<{
         valid: boolean;
-        decoded?: any;
+        decoded?: unknown;
         error?: string;
     }>;
     /**
      * Extract user ID from decoded token
      */
-    extractUserId(decoded: any): string;
+    extractUserId(decoded: unknown): string;
     /**
      * Check if token is expired
      */
-    isTokenExpired(decoded: any): boolean;
+    isTokenExpired(decoded: unknown): boolean;
 }
 /**
  * Fast Authentication Guard Implementation

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

@@ -39,7 +39,7 @@ import { PermissionResolverType, PermissionCheckResult, PermissionExpression } f
  */
 export interface GuardConfig {
     requireAuth: boolean;
-    permissions: any;
+    permissions: string | string[] | PermissionExpression | Record<string, unknown>;
     resolverType?: PermissionResolverType;
     cacheResults: boolean;
     auditTrail: boolean;
@@ -141,7 +141,7 @@ export declare class PermissionGuardFactory {
      * @returns Composite permission guard instance
      */
     createCompositeGuard(requirements: Array<{
-        permissions: any;
+        permissions: string | string[] | PermissionExpression | Record<string, unknown>;
         resolverType: PermissionResolverType;
         required: boolean;
     }>, config?: Partial<GuardConfig>): BasePermissionGuard;
@@ -155,23 +155,15 @@ export declare class PermissionGuardFactory {
      * @param config - Optional guard configuration
      * @returns Optimally configured permission guard
      */
-    createAutoGuard(permissions: any, config?: Partial<GuardConfig>): BasePermissionGuard;
+    createAutoGuard(permissions: string | string[] | PermissionExpression | Record<string, unknown>, config?: Partial<GuardConfig>): BasePermissionGuard;
     /**
      * Get factory statistics
      */
     getStats(): {
         totalGuards: number;
         guardsByType: Record<string, number>;
-        individualGuardStats: {
-            guardType: string;
-            checkCount: number;
-            successCount: number;
-            failureCount: number;
-            successRate: number;
-            averageProcessingTimeUs: number;
-            totalProcessingTimeUs: number;
-        }[];
-        aggregatedStats: any;
+        individualGuardStats: Record<string, unknown>[];
+        aggregatedStats: Record<string, unknown>;
     };
     /**
      * Clear guard cache

package/build/middlewares/guards/guards/PermissionGuardFactory.js

@@ -531,10 +531,10 @@ let PermissionGuardFactory = class PermissionGuardFactory {
             };
         }
         const totals = guardStats.reduce((acc, stats) => ({
-            checkCount: acc.checkCount + stats.checkCount,
-            successCount: acc.successCount + stats.successCount,
-            failureCount: acc.failureCount + stats.failureCount,
-            totalProcessingTimeUs: acc.totalProcessingTimeUs + stats.totalProcessingTimeUs,
+            checkCount: acc.checkCount + (stats.checkCount || 0),
+            successCount: acc.successCount + (stats.successCount || 0),
+            failureCount: acc.failureCount + (stats.failureCount || 0),
+            totalProcessingTimeUs: acc.totalProcessingTimeUs + (stats.totalProcessingTimeUs || 0),
         }), {
             checkCount: 0,
             successCount: 0,

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

@@ -15,7 +15,7 @@
  * @author Noony Framework Team
  * @version 1.0.0
  */
-export { RouteGuards, RouteGuardOptions, GuardSystemStats, } from './RouteGuards';
+export { RouteGuards, RouteGuardOptions, GuardSystemStats, AnyTokenValidator, } from './RouteGuards';
 export { GuardConfiguration, GuardEnvironmentProfile, PermissionResolutionStrategy, GuardSecurityConfig, GuardCacheConfig, GuardMonitoringConfig, } from './config/GuardConfiguration';
 export { CacheAdapter, CacheStats, CacheKeyBuilder, } from './cache/CacheAdapter';
 export { MemoryCacheAdapter } from './cache/MemoryCacheAdapter';
@@ -29,6 +29,7 @@ export { PermissionRegistry } from './registry/PermissionRegistry';
 export { FastUserContextService, UserContext, UserPermissionSource, PermissionCheckOptions, } from './services/FastUserContextService';
 export { FastAuthGuard, AuthenticationResult, AuthGuardConfig, TokenValidator, } from './guards/FastAuthGuard';
 export { PermissionGuardFactory, GuardConfig, } from './guards/PermissionGuardFactory';
+export { CustomTokenVerificationPortAdapter, TokenVerificationAdapterFactory, AdapterConfig, } from './adapters/CustomTokenVerificationPortAdapter';
 export declare const GUARD_DEFAULTS: {
     readonly CACHE_TTL_MS: number;
     readonly AUTH_TOKEN_TTL_MS: number;
@@ -49,18 +50,59 @@ import { GuardEnvironmentProfile } from './config/GuardConfiguration';
 export declare class GuardSetup {
     /**
      * Development environment setup
+     *
+     * Note: Caching is disabled by default unless NOONY_GUARD_CACHE_ENABLE=true is set.
+     * Even with cacheType: 'memory', the environment variable takes precedence.
+     *
+     * @example
+     * ```bash
+     * # Caching disabled (default)
+     * npm run dev
+     *
+     * # Caching enabled
+     * NOONY_GUARD_CACHE_ENABLE=true npm run dev
+     * ```
      */
     static development(): GuardEnvironmentProfile;
     /**
      * Production environment setup
+     *
+     * Note: Caching is disabled by default unless NOONY_GUARD_CACHE_ENABLE=true is set.
+     * This provides a security-first approach where caching must be explicitly enabled.
+     *
+     * @example
+     * ```bash
+     * # Production with caching enabled (recommended)
+     * NOONY_GUARD_CACHE_ENABLE=true node dist/index.js
+     *
+     * # Production with caching disabled (debugging/troubleshooting)
+     * node dist/index.js
+     * ```
      */
     static production(): GuardEnvironmentProfile;
     /**
      * Serverless environment setup (optimized for cold starts)
+     *
+     * Note: Caching is disabled by default unless NOONY_GUARD_CACHE_ENABLE=true is set.
+     * For serverless environments, consider enabling caching to improve performance
+     * across warm invocations.
+     *
+     * @example
+     * ```bash
+     * # Serverless with caching enabled (recommended for warm starts)
+     * NOONY_GUARD_CACHE_ENABLE=true serverless deploy
+     *
+     * # Serverless with caching disabled (cold start optimization)
+     * serverless deploy
+     * ```
      */
     static serverless(): GuardEnvironmentProfile;
     /**
      * Testing environment setup
+     *
+     * Note: Uses cacheType: 'none' explicitly, so caching is always disabled
+     * regardless of NOONY_GUARD_CACHE_ENABLE environment variable.
+     * This ensures predictable test behavior.
      */
     static testing(): GuardEnvironmentProfile;
 }

package/build/middlewares/guards/index.js

@@ -17,7 +17,7 @@
  * @version 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GuardSetup = exports.PERMISSION_PATTERNS = exports.GUARD_DEFAULTS = exports.PermissionGuardFactory = exports.FastAuthGuard = exports.FastUserContextService = exports.ExpressionPermissionResolver = exports.WildcardPermissionResolver = exports.PlainPermissionResolver = exports.PermissionUtils = exports.PermissionResolverType = exports.PermissionResolver = exports.InvalidationScope = exports.InvalidationType = exports.ConservativeCacheInvalidation = exports.NoopCacheAdapter = exports.MemoryCacheAdapter = exports.CacheKeyBuilder = exports.PermissionResolutionStrategy = exports.GuardConfiguration = exports.RouteGuards = void 0;
+exports.GuardSetup = exports.PERMISSION_PATTERNS = exports.GUARD_DEFAULTS = exports.TokenVerificationAdapterFactory = exports.CustomTokenVerificationPortAdapter = exports.PermissionGuardFactory = exports.FastAuthGuard = exports.FastUserContextService = exports.ExpressionPermissionResolver = exports.WildcardPermissionResolver = exports.PlainPermissionResolver = exports.PermissionUtils = exports.PermissionResolverType = exports.PermissionResolver = exports.InvalidationScope = exports.InvalidationType = exports.ConservativeCacheInvalidation = exports.NoopCacheAdapter = exports.MemoryCacheAdapter = exports.CacheKeyBuilder = exports.PermissionResolutionStrategy = exports.GuardConfiguration = exports.RouteGuards = void 0;
 // Main facade - primary entry point
 var RouteGuards_1 = require("./RouteGuards");
 Object.defineProperty(exports, "RouteGuards", { enumerable: true, get: function () { return RouteGuards_1.RouteGuards; } });
@@ -55,6 +55,10 @@ var FastAuthGuard_1 = require("./guards/FastAuthGuard");
 Object.defineProperty(exports, "FastAuthGuard", { enumerable: true, get: function () { return FastAuthGuard_1.FastAuthGuard; } });
 var PermissionGuardFactory_1 = require("./guards/PermissionGuardFactory");
 Object.defineProperty(exports, "PermissionGuardFactory", { enumerable: true, get: function () { return PermissionGuardFactory_1.PermissionGuardFactory; } });
+// Token verification adapters for integration with AuthenticationMiddleware
+var CustomTokenVerificationPortAdapter_1 = require("./adapters/CustomTokenVerificationPortAdapter");
+Object.defineProperty(exports, "CustomTokenVerificationPortAdapter", { enumerable: true, get: function () { return CustomTokenVerificationPortAdapter_1.CustomTokenVerificationPortAdapter; } });
+Object.defineProperty(exports, "TokenVerificationAdapterFactory", { enumerable: true, get: function () { return CustomTokenVerificationPortAdapter_1.TokenVerificationAdapterFactory; } });
 // Utility types and constants
 exports.GUARD_DEFAULTS = {
     CACHE_TTL_MS: 15 * 60 * 1000, // 15 minutes
@@ -77,6 +81,18 @@ const GuardConfiguration_2 = require("./config/GuardConfiguration");
 class GuardSetup {
     /**
      * Development environment setup
+     *
+     * Note: Caching is disabled by default unless NOONY_GUARD_CACHE_ENABLE=true is set.
+     * Even with cacheType: 'memory', the environment variable takes precedence.
+     *
+     * @example
+     * ```bash
+     * # Caching disabled (default)
+     * npm run dev
+     *
+     * # Caching enabled
+     * NOONY_GUARD_CACHE_ENABLE=true npm run dev
+     * ```
      */
     static development() {
         return {
@@ -105,6 +121,18 @@ class GuardSetup {
     }
     /**
      * Production environment setup
+     *
+     * Note: Caching is disabled by default unless NOONY_GUARD_CACHE_ENABLE=true is set.
+     * This provides a security-first approach where caching must be explicitly enabled.
+     *
+     * @example
+     * ```bash
+     * # Production with caching enabled (recommended)
+     * NOONY_GUARD_CACHE_ENABLE=true node dist/index.js
+     *
+     * # Production with caching disabled (debugging/troubleshooting)
+     * node dist/index.js
+     * ```
      */
     static production() {
         return {
@@ -133,6 +161,19 @@ class GuardSetup {
     }
     /**
      * Serverless environment setup (optimized for cold starts)
+     *
+     * Note: Caching is disabled by default unless NOONY_GUARD_CACHE_ENABLE=true is set.
+     * For serverless environments, consider enabling caching to improve performance
+     * across warm invocations.
+     *
+     * @example
+     * ```bash
+     * # Serverless with caching enabled (recommended for warm starts)
+     * NOONY_GUARD_CACHE_ENABLE=true serverless deploy
+     *
+     * # Serverless with caching disabled (cold start optimization)
+     * serverless deploy
+     * ```
      */
     static serverless() {
         return {
@@ -161,6 +202,10 @@ class GuardSetup {
     }
     /**
      * Testing environment setup
+     *
+     * Note: Uses cacheType: 'none' explicitly, so caching is always disabled
+     * regardless of NOONY_GUARD_CACHE_ENABLE environment variable.
+     * This ensures predictable test behavior.
      */
     static testing() {
         return {