@noony-serverless/core 0.1.0 → 0.1.5

package/build/middlewares/guards/resolvers/WildcardPermissionResolver.js

@@ -0,0 +1,377 @@
+"use strict";
+/**
+ * Wildcard Permission Resolver
+ *
+ * Configurable permission resolver supporting hierarchical wildcard patterns
+ * with two distinct strategies for optimal performance in different scenarios:
+ *
+ * 1. PRE_EXPANSION Strategy:
+ *    - Expand wildcards at user context load time
+ *    - Store expanded permissions in user context
+ *    - Runtime: O(1) set membership checks (fastest)
+ *    - Memory: Higher usage due to expanded permission sets
+ *    - Best for: Production environments with predictable permission sets
+ *
+ * 2. ON_DEMAND Strategy:
+ *    - Pattern matching at permission check time
+ *    - Cache pattern matching results
+ *    - Runtime: Pattern matching cost with caching benefits
+ *    - Memory: Lower usage, only caches results
+ *    - Best for: Development, dynamic permissions, memory-constrained environments
+ *
+ * Supported Patterns:
+ * - 2 levels: "admin.users", "org.reports"
+ * - 3 levels: "admin.users.create", "org.reports.view"
+ * - Wildcards: "admin.*", "org.reports.*"
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WildcardPermissionResolver = void 0;
+const PermissionResolver_1 = require("./PermissionResolver");
+const CacheAdapter_1 = require("../cache/CacheAdapter");
+const GuardConfiguration_1 = require("../config/GuardConfiguration");
+/**
+ * Wildcard permission resolver with configurable resolution strategies
+ */
+class WildcardPermissionResolver extends PermissionResolver_1.PermissionResolver {
+    strategy;
+    permissionRegistry;
+    cache;
+    maxPatternDepth;
+    // Performance tracking
+    checkCount = 0;
+    totalResolutionTimeUs = 0;
+    cacheHits = 0;
+    cacheMisses = 0;
+    constructor(strategy, permissionRegistry, cache, maxPatternDepth = 3) {
+        super();
+        this.strategy = strategy;
+        this.permissionRegistry = permissionRegistry;
+        this.cache = cache;
+        this.maxPatternDepth = maxPatternDepth;
+        if (maxPatternDepth < 2 || maxPatternDepth > 3) {
+            throw new Error('Max pattern depth must be 2 or 3');
+        }
+    }
+    /**
+     * Check if user permissions satisfy wildcard patterns
+     *
+     * @param userPermissions - Set of user's permissions (may be pre-expanded)
+     * @param wildcardPatterns - Array of wildcard patterns to check
+     * @returns Promise resolving to true if user matches any pattern
+     */
+    async check(userPermissions, wildcardPatterns) {
+        const startTime = process.hrtime.bigint();
+        try {
+            // Validate inputs
+            if (!userPermissions || userPermissions.size === 0) {
+                return false;
+            }
+            if (!wildcardPatterns || wildcardPatterns.length === 0) {
+                return false;
+            }
+            // Validate patterns
+            for (const pattern of wildcardPatterns) {
+                if (!this.isValidWildcardPattern(pattern)) {
+                    throw new Error(`Invalid wildcard pattern: ${pattern}`);
+                }
+            }
+            // Route to appropriate strategy
+            if (this.strategy === GuardConfiguration_1.PermissionResolutionStrategy.PRE_EXPANSION) {
+                return await this.checkPreExpanded(userPermissions, wildcardPatterns);
+            }
+            else {
+                return await this.checkOnDemand(userPermissions, wildcardPatterns);
+            }
+        }
+        finally {
+            // Track performance metrics
+            const endTime = process.hrtime.bigint();
+            const resolutionTimeUs = Number(endTime - startTime) / 1000;
+            this.checkCount++;
+            this.totalResolutionTimeUs += resolutionTimeUs;
+        }
+    }
+    /**
+     * Pre-expansion strategy: O(1) set membership checks
+     *
+     * Assumes user permissions have been pre-expanded to include all
+     * concrete permissions that match wildcard patterns in their roles.
+     * This provides the fastest runtime performance.
+     */
+    async checkPreExpanded(userPermissions, wildcardPatterns) {
+        // For pre-expanded permissions, we check both:
+        // 1. Exact pattern matches (if user was granted the wildcard directly)
+        // 2. Concrete permission matches (if user has specific permissions)
+        for (const pattern of wildcardPatterns) {
+            // Check if user has the wildcard permission directly
+            if (userPermissions.has(pattern)) {
+                return true;
+            }
+            // If it's a wildcard pattern, check for any matching concrete permissions
+            if (pattern.includes('*')) {
+                const concretePermissions = this.permissionRegistry.getMatchingPermissions(pattern);
+                for (const concretePermission of concretePermissions) {
+                    if (userPermissions.has(concretePermission)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * On-demand strategy: Pattern matching with caching
+     *
+     * Performs pattern matching at runtime but caches results to avoid
+     * repeated pattern matching for the same user/pattern combinations.
+     */
+    async checkOnDemand(userPermissions, wildcardPatterns) {
+        // Create cache key for this specific check
+        const userPermissionArray = Array.from(userPermissions).sort();
+        const cacheKey = CacheAdapter_1.CacheKeyBuilder.wildcardPattern(wildcardPatterns, userPermissionArray);
+        // Check cache first
+        const cachedResult = await this.cache.get(cacheKey);
+        if (cachedResult !== null) {
+            this.cacheHits++;
+            return cachedResult;
+        }
+        this.cacheMisses++;
+        // Perform pattern matching
+        let result = false;
+        for (const pattern of wildcardPatterns) {
+            if (this.matchesAnyUserPermission(userPermissions, pattern)) {
+                result = true;
+                break; // Short-circuit on first match
+            }
+        }
+        // Cache the result for 1 minute (configurable)
+        await this.cache.set(cacheKey, result, 60 * 1000);
+        return result;
+    }
+    /**
+     * Check if any user permission matches the given pattern
+     */
+    matchesAnyUserPermission(userPermissions, pattern) {
+        // Direct exact match
+        if (userPermissions.has(pattern)) {
+            return true;
+        }
+        // If not a wildcard pattern, no further matching needed
+        if (!pattern.includes('*')) {
+            return false;
+        }
+        // Pattern matching for wildcard
+        for (const userPermission of userPermissions) {
+            if (PermissionResolver_1.PermissionUtils.matchesWildcard(userPermission, pattern)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Expand wildcard patterns to concrete permissions
+     *
+     * Used by the user context service when pre-expansion strategy is enabled.
+     * Converts wildcard patterns to all matching concrete permissions.
+     *
+     * @param patterns - Array of wildcard patterns
+     * @returns Set of concrete permissions
+     */
+    async expandWildcardPatterns(patterns) {
+        const expandedPermissions = new Set();
+        for (const pattern of patterns) {
+            if (!this.isValidWildcardPattern(pattern)) {
+                throw new Error(`Invalid wildcard pattern: ${pattern}`);
+            }
+            if (pattern.includes('*')) {
+                // Expand wildcard to concrete permissions
+                const concretePermissions = this.permissionRegistry.getMatchingPermissions(pattern);
+                concretePermissions.forEach((permission) => expandedPermissions.add(permission));
+            }
+            else {
+                // Add concrete permission as-is
+                expandedPermissions.add(pattern);
+            }
+        }
+        return expandedPermissions;
+    }
+    /**
+     * Check permissions with detailed result information
+     */
+    async checkWithResult(userPermissions, wildcardPatterns) {
+        const startTime = process.hrtime.bigint();
+        const cached = false;
+        const matchedPermissions = [];
+        try {
+            // Validate inputs
+            if (!userPermissions || userPermissions.size === 0) {
+                return {
+                    allowed: false,
+                    resolverType: this.getType(),
+                    resolutionTimeUs: 0,
+                    cached: false,
+                    reason: 'User has no permissions',
+                };
+            }
+            if (!wildcardPatterns || wildcardPatterns.length === 0) {
+                return {
+                    allowed: false,
+                    resolverType: this.getType(),
+                    resolutionTimeUs: 0,
+                    cached: false,
+                    reason: 'No patterns specified',
+                };
+            }
+            // Find all matching patterns/permissions
+            for (const pattern of wildcardPatterns) {
+                if (!this.isValidWildcardPattern(pattern)) {
+                    throw new Error(`Invalid wildcard pattern: ${pattern}`);
+                }
+                if (this.strategy === GuardConfiguration_1.PermissionResolutionStrategy.PRE_EXPANSION) {
+                    // Check pre-expanded permissions
+                    if (userPermissions.has(pattern)) {
+                        matchedPermissions.push(pattern);
+                    }
+                    else if (pattern.includes('*')) {
+                        const concretePermissions = this.permissionRegistry.getMatchingPermissions(pattern);
+                        for (const concretePermission of concretePermissions) {
+                            if (userPermissions.has(concretePermission)) {
+                                matchedPermissions.push(concretePermission);
+                            }
+                        }
+                    }
+                }
+                else {
+                    // On-demand pattern matching
+                    if (this.matchesAnyUserPermission(userPermissions, pattern)) {
+                        matchedPermissions.push(pattern);
+                    }
+                }
+            }
+            const allowed = matchedPermissions.length > 0;
+            const endTime = process.hrtime.bigint();
+            const resolutionTimeUs = Number(endTime - startTime) / 1000;
+            return {
+                allowed,
+                resolverType: this.getType(),
+                resolutionTimeUs,
+                cached,
+                reason: allowed
+                    ? undefined
+                    : `No matching patterns: ${wildcardPatterns.join(', ')}`,
+                matchedPermissions: allowed ? matchedPermissions : undefined,
+            };
+        }
+        catch (error) {
+            const endTime = process.hrtime.bigint();
+            const resolutionTimeUs = Number(endTime - startTime) / 1000;
+            return {
+                allowed: false,
+                resolverType: this.getType(),
+                resolutionTimeUs,
+                cached,
+                reason: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Validate wildcard pattern format
+     */
+    isValidWildcardPattern(pattern) {
+        if (!pattern || typeof pattern !== 'string') {
+            return false;
+        }
+        // Check basic permission format first
+        if (!PermissionResolver_1.PermissionUtils.isValidPermission(pattern)) {
+            return false;
+        }
+        // Count depth levels
+        const parts = pattern.split('.');
+        if (parts.length < 2 || parts.length > this.maxPatternDepth) {
+            return false;
+        }
+        // If contains wildcard, it should be at the end
+        if (pattern.includes('*')) {
+            if (!pattern.endsWith('*') ||
+                pattern.indexOf('*') !== pattern.length - 1) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Get resolver type for identification
+     */
+    getType() {
+        return PermissionResolver_1.PermissionResolverType.WILDCARD;
+    }
+    /**
+     * Get performance characteristics for monitoring
+     */
+    getPerformanceCharacteristics() {
+        const isPreExpansion = this.strategy === GuardConfiguration_1.PermissionResolutionStrategy.PRE_EXPANSION;
+        return {
+            timeComplexity: isPreExpansion
+                ? 'O(1) per pattern'
+                : 'O(n*m) with caching',
+            memoryUsage: isPreExpansion ? 'high' : 'medium',
+            cacheUtilization: isPreExpansion ? 'none' : 'high',
+            recommendedFor: isPreExpansion
+                ? [
+                    'Production environments',
+                    'Predictable permission sets',
+                    'Maximum performance',
+                ]
+                : [
+                    'Development environments',
+                    'Dynamic permissions',
+                    'Memory-constrained scenarios',
+                ],
+        };
+    }
+    /**
+     * Get performance statistics
+     */
+    getStats() {
+        const totalCacheRequests = this.cacheHits + this.cacheMisses;
+        return {
+            strategy: this.strategy,
+            checkCount: this.checkCount,
+            averageResolutionTimeUs: this.checkCount > 0 ? this.totalResolutionTimeUs / this.checkCount : 0,
+            totalResolutionTimeUs: this.totalResolutionTimeUs,
+            cacheHitRate: totalCacheRequests > 0
+                ? (this.cacheHits / totalCacheRequests) * 100
+                : 0,
+            cacheHits: this.cacheHits,
+            cacheMisses: this.cacheMisses,
+        };
+    }
+    /**
+     * Reset performance statistics
+     */
+    resetStats() {
+        this.checkCount = 0;
+        this.totalResolutionTimeUs = 0;
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+    }
+    /**
+     * Get resolver name for debugging
+     */
+    getName() {
+        return `WildcardPermissionResolver(${this.strategy})`;
+    }
+    /**
+     * Check if this resolver can handle the given requirement type
+     */
+    canHandle(requirement) {
+        return (Array.isArray(requirement) &&
+            requirement.length > 0 &&
+            requirement.every((item) => typeof item === 'string' && this.isValidWildcardPattern(item)));
+    }
+}
+exports.WildcardPermissionResolver = WildcardPermissionResolver;
+//# sourceMappingURL=WildcardPermissionResolver.js.map

package/build/middlewares/guards/services/FastUserContextService.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Fast User Context Service
+ *
+ * High-performance user context management with configurable permission resolution.
+ * This service orchestrates the permission resolution strategies, manages caching,
+ * and provides sub-millisecond user permission checks for serverless environments.
+ *
+ * Key Features:
+ * - Configurable permission resolution (pre-expansion vs on-demand)
+ * - Multi-layer caching (L1 memory + L2 distributed)
+ * - Conservative cache invalidation for security
+ * - Permission expansion and validation
+ * - Performance monitoring and metrics
+ * - TypeDI integration for dependency injection
+ *
+ * Architecture:
+ * - Uses strategy pattern for different resolution approaches
+ * - Implements repository pattern for user context storage
+ * - Follows single responsibility principle with focused methods
+ * - Provides comprehensive error handling and logging
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+import { CacheAdapter } from '../cache/CacheAdapter';
+import { GuardConfiguration, PermissionResolutionStrategy } from '../config/GuardConfiguration';
+import { PermissionRegistry } from '../registry/PermissionRegistry';
+import { PermissionResolverType, PermissionCheckResult } from '../resolvers/PermissionResolver';
+/**
+ * User context with cached permissions and metadata
+ */
+export interface UserContext {
+    userId: string;
+    permissions: Set<string>;
+    roles: string[];
+    metadata: Record<string, any>;
+    expandedPermissions?: Set<string>;
+    lastUpdated: string;
+    expiresAt?: string;
+}
+/**
+ * User permission source for loading raw user data
+ */
+export interface UserPermissionSource {
+    /**
+     * Load user's basic information and permissions
+     */
+    getUserPermissions(userId: string): Promise<{
+        permissions: string[];
+        roles: string[];
+        metadata?: Record<string, any>;
+    } | null>;
+    /**
+     * Get role-based permissions for expansion
+     */
+    getRolePermissions(roles: string[]): Promise<string[]>;
+    /**
+     * Check if user context needs refresh
+     */
+    isUserContextStale(userId: string, lastUpdated: string): Promise<boolean>;
+}
+/**
+ * Permission check options
+ */
+export interface PermissionCheckOptions {
+    resolverType?: PermissionResolverType;
+    useCache?: boolean;
+    trackMetrics?: boolean;
+    auditTrail?: boolean;
+}
+/**
+ * Fast User Context Service Implementation
+ */
+export declare class FastUserContextService {
+    private readonly cache;
+    private readonly config;
+    private readonly permissionSource;
+    private readonly _permissionRegistry;
+    private readonly plainResolver;
+    private readonly wildcardResolver;
+    private readonly expressionResolver;
+    private contextLoads;
+    private cacheHits;
+    private cacheMisses;
+    private permissionChecks;
+    private totalResolutionTimeUs;
+    constructor(cache: CacheAdapter, config: GuardConfiguration, permissionSource: UserPermissionSource, permissionRegistry: PermissionRegistry);
+    /**
+     * Get or load user context with permissions
+     *
+     * This is the primary method for retrieving user contexts with caching.
+     * It handles both pre-expansion and on-demand permission strategies.
+     *
+     * @param userId - Unique user identifier
+     * @param forceRefresh - Skip cache and force reload
+     * @returns User context with permissions or null if user not found
+     */
+    getUserContext(userId: string, forceRefresh?: boolean): Promise<UserContext | null>;
+    /**
+     * Check user permission using appropriate resolver
+     *
+     * Routes permission checks to the optimal resolver based on requirement type.
+     * Provides detailed results including performance metrics and cache status.
+     *
+     * @param userId - User identifier
+     * @param requirement - Permission requirement (string[], wildcard pattern, or expression)
+     * @param options - Check options
+     * @returns Detailed permission check result
+     */
+    checkPermission(userId: string, requirement: any, options?: PermissionCheckOptions): Promise<PermissionCheckResult>;
+    /**
+     * Batch check multiple permissions for a user
+     *
+     * Optimized for checking multiple permissions at once.
+     * Uses the same user context for all checks to minimize overhead.
+     *
+     * @param userId - User identifier
+     * @param requirements - Array of permission requirements
+     * @param options - Check options
+     * @returns Array of permission check results
+     */
+    checkPermissions(userId: string, requirements: Array<{
+        requirement: any;
+        resolverType?: PermissionResolverType;
+    }>, options?: PermissionCheckOptions): Promise<PermissionCheckResult[]>;
+    /**
+     * Invalidate user context cache
+     *
+     * Removes user context from cache when permissions change.
+     * Uses conservative approach by also clearing related cached data.
+     *
+     * @param userId - User identifier
+     * @param clearRelated - Also clear permission-related caches
+     */
+    invalidateUserContext(userId: string, clearRelated?: boolean): Promise<void>;
+    /**
+     * Pre-expand wildcard permissions for user context
+     *
+     * Used when pre-expansion strategy is enabled to convert
+     * wildcard permissions to concrete permission sets.
+     *
+     * @param permissions - Raw permissions from user/roles
+     * @returns Expanded permission set
+     */
+    expandPermissions(permissions: string[]): Promise<Set<string>>;
+    /**
+     * Get service performance statistics
+     */
+    getStats(): {
+        contextLoads: number;
+        permissionChecks: number;
+        cacheHitRate: number;
+        cacheHits: number;
+        cacheMisses: number;
+        averageResolutionTimeUs: number;
+        totalResolutionTimeUs: number;
+        resolverStats: {
+            plain: {
+                checkCount: number;
+                averageResolutionTimeUs: number;
+                totalResolutionTimeUs: number;
+            };
+            wildcard: {
+                strategy: PermissionResolutionStrategy;
+                checkCount: number;
+                averageResolutionTimeUs: number;
+                totalResolutionTimeUs: number;
+                cacheHitRate: number;
+                cacheHits: number;
+                cacheMisses: number;
+            };
+            expression: {
+                checkCount: number;
+                averageResolutionTimeUs: number;
+                totalResolutionTimeUs: number;
+                cacheHitRate: number;
+                cacheHits: number;
+                cacheMisses: number;
+                complexityDistribution: {
+                    simple: number;
+                    moderate: number;
+                    complex: number;
+                };
+            };
+        };
+    };
+    /**
+     * Reset performance statistics
+     */
+    resetStats(): void;
+    /**
+     * Load user context from cache
+     */
+    private loadFromCache;
+    /**
+     * Save user context to cache
+     */
+    private saveToCache;
+    /**
+     * Build user context from raw user data
+     */
+    private buildUserContext;
+    /**
+     * Select appropriate permission resolver
+     */
+    private selectResolver;
+    /**
+     * Get resolver by type
+     */
+    private getResolverByType;
+    /**
+     * Record audit trail for permission checks
+     */
+    private recordAuditTrail;
+}
+//# sourceMappingURL=FastUserContextService.d.ts.map