@noony-serverless/core 0.1.0 → 0.1.5

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

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Permission Resolution System
+ *
+ * Base interfaces and types for the three distinct permission resolution strategies:
+ * - PlainPermissionResolver: Direct O(1) set membership checks
+ * - WildcardPermissionResolver: Pattern matching with configurable strategies
+ * - ExpressionPermissionResolver: Complex AND/OR/NOT expression evaluation
+ *
+ * Each resolver operates independently and cannot be combined on a single endpoint,
+ * ensuring clear performance characteristics and simplified reasoning.
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionUtils = exports.PermissionResolverType = exports.PermissionResolver = void 0;
+/**
+ * Base interface for all permission resolvers
+ *
+ * Each resolver implements this interface with specific logic for handling
+ * different types of permission requirements. The generic type T represents
+ * the specific requirement format for each resolver.
+ */
+class PermissionResolver {
+}
+exports.PermissionResolver = PermissionResolver;
+/**
+ * Permission resolver types for identification
+ */
+var PermissionResolverType;
+(function (PermissionResolverType) {
+    PermissionResolverType["PLAIN"] = "plain";
+    PermissionResolverType["WILDCARD"] = "wildcard";
+    PermissionResolverType["EXPRESSION"] = "expression";
+})(PermissionResolverType || (exports.PermissionResolverType = PermissionResolverType = {}));
+/**
+ * Utility functions for working with permissions
+ */
+class PermissionUtils {
+    /**
+     * Convert array of permissions to Set for O(1) lookups
+     *
+     * @param permissions - Array of permission strings
+     * @returns Set of permissions for fast membership testing
+     */
+    static arrayToSet(permissions) {
+        return new Set(permissions);
+    }
+    /**
+     * Validate permission string format
+     *
+     * Ensures permissions follow expected naming conventions:
+     * - 2-3 levels separated by dots
+     * - Only alphanumeric characters, dots, and hyphens
+     * - No leading/trailing dots
+     *
+     * @param permission - Permission string to validate
+     * @returns true if valid, false otherwise
+     */
+    static isValidPermission(permission) {
+        if (!permission || typeof permission !== 'string') {
+            return false;
+        }
+        // Check for valid format: 2-3 levels, alphanumeric + dots + hyphens
+        const validPattern = /^[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+){1,2}$/;
+        // Check for wildcard format: ends with .* for wildcards
+        const wildcardPattern = /^[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)*\.\*$/;
+        return validPattern.test(permission) || wildcardPattern.test(permission);
+    }
+    /**
+     * Extract base permission from wildcard pattern
+     *
+     * @param wildcardPermission - Wildcard permission like "admin.*"
+     * @returns Base permission like "admin"
+     */
+    static extractWildcardBase(wildcardPermission) {
+        if (wildcardPermission.endsWith('.*')) {
+            return wildcardPermission.slice(0, -2);
+        }
+        return wildcardPermission;
+    }
+    /**
+     * Check if a permission matches a wildcard pattern
+     *
+     * @param permission - Specific permission to test
+     * @param wildcardPattern - Wildcard pattern to match against
+     * @returns true if permission matches the pattern
+     */
+    static matchesWildcard(permission, wildcardPattern) {
+        if (!wildcardPattern.includes('*')) {
+            return permission === wildcardPattern;
+        }
+        // Convert wildcard pattern to regex
+        // "admin.*" becomes /^admin\.[^.]+$/
+        // "admin.users.*" becomes /^admin\.users\.[^.]+$/
+        const regexPattern = wildcardPattern
+            .replace(/\./g, '\\.') // Escape dots
+            .replace(/\*/g, '[^.]+'); // Replace * with non-dot characters
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(permission);
+    }
+    /**
+     * Validate permission expression structure
+     *
+     * Ensures expressions follow the 2-level nesting limit and contain
+     * valid permission strings.
+     *
+     * @param expression - Permission expression to validate
+     * @param depth - Current nesting depth (internal use)
+     * @returns true if valid, false otherwise
+     */
+    static isValidExpression(expression, depth = 0) {
+        if (depth > 2) {
+            return false; // Exceeds maximum nesting depth
+        }
+        // Must have exactly one operation type
+        const operationCount = [
+            expression.and ? 1 : 0,
+            expression.or ? 1 : 0,
+            expression.not ? 1 : 0,
+            expression.permission ? 1 : 0,
+        ].reduce((sum, count) => sum + count, 0);
+        if (operationCount !== 1) {
+            return false; // Must have exactly one operation
+        }
+        // Validate leaf permission
+        if (expression.permission) {
+            return this.isValidPermission(expression.permission);
+        }
+        // Validate AND operation
+        if (expression.and) {
+            if (!Array.isArray(expression.and) || expression.and.length === 0) {
+                return false;
+            }
+            return expression.and.every((subExpr) => this.isValidExpression(subExpr, depth + 1));
+        }
+        // Validate OR operation
+        if (expression.or) {
+            if (!Array.isArray(expression.or) || expression.or.length === 0) {
+                return false;
+            }
+            return expression.or.every((subExpr) => this.isValidExpression(subExpr, depth + 1));
+        }
+        // Validate NOT operation
+        if (expression.not) {
+            return this.isValidExpression(expression.not, depth + 1);
+        }
+        return false;
+    }
+    /**
+     * Generate a stable hash for caching permission expressions
+     *
+     * @param expression - Permission expression to hash
+     * @returns Stable string hash for cache keys
+     */
+    static hashExpression(expression) {
+        // Sort keys to ensure consistent serialization
+        const sortedJson = JSON.stringify(expression, Object.keys(expression).sort());
+        return this.simpleHash(sortedJson);
+    }
+    /**
+     * Simple hash function for string data (not cryptographically secure)
+     */
+    static simpleHash(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        return hash.toString(36);
+    }
+}
+exports.PermissionUtils = PermissionUtils;
+//# sourceMappingURL=PermissionResolver.js.map

package/build/middlewares/guards/resolvers/PlainPermissionResolver.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Plain Permission Resolver
+ *
+ * Fastest permission resolver using direct O(1) set membership checks.
+ * Optimized for high-performance scenarios where sub-millisecond permission
+ * checks are critical. No pattern matching or complex logic - just pure
+ * set-based lookups for maximum speed.
+ *
+ * Use Cases:
+ * - High-traffic API endpoints requiring maximum performance
+ * - Simple permission models without wildcards or expressions
+ * - Scenarios where all required permissions are known at compile time
+ * - Serverless functions with strict latency requirements
+ *
+ * Performance Characteristics:
+ * - Time Complexity: O(1) for permission lookup
+ * - Space Complexity: O(n) where n is the number of user permissions
+ * - Cache Utilization: None (no caching needed due to speed)
+ * - Memory Footprint: Minimal (uses JavaScript Set)
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+import { PermissionResolver, PermissionResolverType, PerformanceCharacteristics, PermissionCheckResult } from './PermissionResolver';
+/**
+ * Plain permission resolver for direct O(1) permission checks
+ *
+ * This resolver performs the simplest and fastest permission checks by
+ * using JavaScript Set's has() method for O(1) membership testing.
+ * It checks if the user has ANY of the required permissions (OR logic).
+ */
+export declare class PlainPermissionResolver extends PermissionResolver<string[]> {
+    private checkCount;
+    private totalResolutionTimeUs;
+    /**
+     * Check if user has any of the required permissions
+     *
+     * Uses OR logic: user needs only ONE of the required permissions
+     * to pass the check. This is the most common permission pattern.
+     *
+     * @param userPermissions - Set of user's permissions for O(1) lookup
+     * @param requiredPermissions - Array of required permissions (OR logic)
+     * @returns Promise resolving to true if user has any required permission
+     */
+    check(userPermissions: Set<string>, requiredPermissions: string[]): Promise<boolean>;
+    /**
+     * Check permissions with detailed result information
+     *
+     * Provides additional metadata about the permission check for
+     * debugging, monitoring, and audit purposes.
+     *
+     * @param userPermissions - Set of user's permissions
+     * @param requiredPermissions - Array of required permissions
+     * @returns Detailed permission check result
+     */
+    checkWithResult(userPermissions: Set<string>, requiredPermissions: string[]): Promise<PermissionCheckResult>;
+    /**
+     * Check if user has ALL required permissions (AND logic)
+     *
+     * Alternative method for scenarios requiring ALL permissions
+     * instead of ANY permission. Less commonly used but available
+     * for completeness.
+     *
+     * @param userPermissions - Set of user's permissions
+     * @param requiredPermissions - Array of ALL required permissions
+     * @returns Promise resolving to true if user has ALL permissions
+     */
+    checkAllRequired(userPermissions: Set<string>, requiredPermissions: string[]): Promise<boolean>;
+    /**
+     * Get resolver type for identification
+     */
+    getType(): PermissionResolverType;
+    /**
+     * Get performance characteristics for monitoring
+     */
+    getPerformanceCharacteristics(): PerformanceCharacteristics;
+    /**
+     * Get performance statistics for monitoring
+     */
+    getStats(): {
+        checkCount: number;
+        averageResolutionTimeUs: number;
+        totalResolutionTimeUs: number;
+    };
+    /**
+     * Reset performance statistics
+     */
+    resetStats(): void;
+    /**
+     * Get resolver name for debugging
+     */
+    getName(): string;
+    /**
+     * Check if this resolver can handle the given requirement type
+     *
+     * @param requirement - The requirement to check
+     * @returns true if this resolver can handle the requirement
+     */
+    canHandle(requirement: any): requirement is string[];
+}
+//# sourceMappingURL=PlainPermissionResolver.d.ts.map

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

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Plain Permission Resolver
+ *
+ * Fastest permission resolver using direct O(1) set membership checks.
+ * Optimized for high-performance scenarios where sub-millisecond permission
+ * checks are critical. No pattern matching or complex logic - just pure
+ * set-based lookups for maximum speed.
+ *
+ * Use Cases:
+ * - High-traffic API endpoints requiring maximum performance
+ * - Simple permission models without wildcards or expressions
+ * - Scenarios where all required permissions are known at compile time
+ * - Serverless functions with strict latency requirements
+ *
+ * Performance Characteristics:
+ * - Time Complexity: O(1) for permission lookup
+ * - Space Complexity: O(n) where n is the number of user permissions
+ * - Cache Utilization: None (no caching needed due to speed)
+ * - Memory Footprint: Minimal (uses JavaScript Set)
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlainPermissionResolver = void 0;
+const PermissionResolver_1 = require("./PermissionResolver");
+/**
+ * Plain permission resolver for direct O(1) permission checks
+ *
+ * This resolver performs the simplest and fastest permission checks by
+ * using JavaScript Set's has() method for O(1) membership testing.
+ * It checks if the user has ANY of the required permissions (OR logic).
+ */
+class PlainPermissionResolver extends PermissionResolver_1.PermissionResolver {
+    checkCount = 0;
+    totalResolutionTimeUs = 0;
+    /**
+     * Check if user has any of the required permissions
+     *
+     * Uses OR logic: user needs only ONE of the required permissions
+     * to pass the check. This is the most common permission pattern.
+     *
+     * @param userPermissions - Set of user's permissions for O(1) lookup
+     * @param requiredPermissions - Array of required permissions (OR logic)
+     * @returns Promise resolving to true if user has any required permission
+     */
+    async check(userPermissions, requiredPermissions) {
+        const startTime = process.hrtime.bigint();
+        try {
+            // Validate inputs
+            if (!userPermissions || userPermissions.size === 0) {
+                return false;
+            }
+            if (!requiredPermissions || requiredPermissions.length === 0) {
+                return false; // No permissions required means access denied
+            }
+            // Validate permission format
+            for (const permission of requiredPermissions) {
+                if (!PermissionResolver_1.PermissionUtils.isValidPermission(permission)) {
+                    throw new Error(`Invalid permission format: ${permission}`);
+                }
+            }
+            // O(1) set membership check for each required permission
+            // Return true as soon as we find a match (short-circuit OR)
+            for (const requiredPermission of requiredPermissions) {
+                if (userPermissions.has(requiredPermission)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        finally {
+            // Track performance metrics
+            const endTime = process.hrtime.bigint();
+            const resolutionTimeUs = Number(endTime - startTime) / 1000; // Convert to microseconds
+            this.checkCount++;
+            this.totalResolutionTimeUs += resolutionTimeUs;
+        }
+    }
+    /**
+     * Check permissions with detailed result information
+     *
+     * Provides additional metadata about the permission check for
+     * debugging, monitoring, and audit purposes.
+     *
+     * @param userPermissions - Set of user's permissions
+     * @param requiredPermissions - Array of required permissions
+     * @returns Detailed permission check result
+     */
+    async checkWithResult(userPermissions, requiredPermissions) {
+        const startTime = process.hrtime.bigint();
+        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 (!requiredPermissions || requiredPermissions.length === 0) {
+                return {
+                    allowed: false,
+                    resolverType: this.getType(),
+                    resolutionTimeUs: 0,
+                    cached: false,
+                    reason: 'No permissions specified',
+                };
+            }
+            // Find all matching permissions (not just the first one)
+            for (const requiredPermission of requiredPermissions) {
+                if (!PermissionResolver_1.PermissionUtils.isValidPermission(requiredPermission)) {
+                    throw new Error(`Invalid permission format: ${requiredPermission}`);
+                }
+                if (userPermissions.has(requiredPermission)) {
+                    matchedPermissions.push(requiredPermission);
+                }
+            }
+            const allowed = matchedPermissions.length > 0;
+            const endTime = process.hrtime.bigint();
+            const resolutionTimeUs = Number(endTime - startTime) / 1000;
+            return {
+                allowed,
+                resolverType: this.getType(),
+                resolutionTimeUs,
+                cached: false, // Plain resolver doesn't use caching
+                reason: allowed
+                    ? undefined
+                    : `Missing required permissions: ${requiredPermissions.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: false,
+                reason: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Check if user has ALL required permissions (AND logic)
+     *
+     * Alternative method for scenarios requiring ALL permissions
+     * instead of ANY permission. Less commonly used but available
+     * for completeness.
+     *
+     * @param userPermissions - Set of user's permissions
+     * @param requiredPermissions - Array of ALL required permissions
+     * @returns Promise resolving to true if user has ALL permissions
+     */
+    async checkAllRequired(userPermissions, requiredPermissions) {
+        const startTime = process.hrtime.bigint();
+        try {
+            // Validate inputs
+            if (!userPermissions || userPermissions.size === 0) {
+                return false;
+            }
+            if (!requiredPermissions || requiredPermissions.length === 0) {
+                return true; // No permissions required means access allowed
+            }
+            // Check that user has ALL required permissions
+            for (const requiredPermission of requiredPermissions) {
+                if (!PermissionResolver_1.PermissionUtils.isValidPermission(requiredPermission)) {
+                    throw new Error(`Invalid permission format: ${requiredPermission}`);
+                }
+                if (!userPermissions.has(requiredPermission)) {
+                    return false; // Missing at least one required permission
+                }
+            }
+            return true;
+        }
+        finally {
+            // Track performance metrics
+            const endTime = process.hrtime.bigint();
+            const resolutionTimeUs = Number(endTime - startTime) / 1000;
+            this.checkCount++;
+            this.totalResolutionTimeUs += resolutionTimeUs;
+        }
+    }
+    /**
+     * Get resolver type for identification
+     */
+    getType() {
+        return PermissionResolver_1.PermissionResolverType.PLAIN;
+    }
+    /**
+     * Get performance characteristics for monitoring
+     */
+    getPerformanceCharacteristics() {
+        return {
+            timeComplexity: 'O(1) per permission check',
+            memoryUsage: 'low',
+            cacheUtilization: 'none',
+            recommendedFor: [
+                'High-traffic API endpoints',
+                'Sub-millisecond permission checks',
+                'Simple permission models',
+                'Serverless functions',
+                'Performance-critical paths',
+            ],
+        };
+    }
+    /**
+     * Get performance statistics for monitoring
+     */
+    getStats() {
+        return {
+            checkCount: this.checkCount,
+            averageResolutionTimeUs: this.checkCount > 0 ? this.totalResolutionTimeUs / this.checkCount : 0,
+            totalResolutionTimeUs: this.totalResolutionTimeUs,
+        };
+    }
+    /**
+     * Reset performance statistics
+     */
+    resetStats() {
+        this.checkCount = 0;
+        this.totalResolutionTimeUs = 0;
+    }
+    /**
+     * Get resolver name for debugging
+     */
+    getName() {
+        return 'PlainPermissionResolver';
+    }
+    /**
+     * Check if this resolver can handle the given requirement type
+     *
+     * @param requirement - The requirement to check
+     * @returns true if this resolver can handle the requirement
+     */
+    canHandle(requirement) {
+        return (Array.isArray(requirement) &&
+            requirement.length > 0 &&
+            requirement.every((item) => typeof item === 'string'));
+    }
+}
+exports.PlainPermissionResolver = PlainPermissionResolver;
+//# sourceMappingURL=PlainPermissionResolver.js.map

package/build/middlewares/guards/resolvers/WildcardPermissionResolver.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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
+ */
+import { PermissionResolver, PermissionResolverType, PerformanceCharacteristics, PermissionCheckResult } from './PermissionResolver';
+import { CacheAdapter } from '../cache/CacheAdapter';
+import { PermissionResolutionStrategy } from '../config/GuardConfiguration';
+/**
+ * Permission registry interface for wildcard expansion
+ */
+export interface PermissionRegistry {
+    /**
+     * Get all permissions matching a wildcard pattern
+     *
+     * @param wildcardPattern - Pattern like "admin.*"
+     * @returns Array of concrete permissions matching the pattern
+     */
+    getMatchingPermissions(wildcardPattern: string): string[];
+    /**
+     * Get all available permissions in a category
+     *
+     * @param category - Permission category like "admin"
+     * @returns Array of permissions in that category
+     */
+    getCategoryPermissions(category: string): string[];
+    /**
+     * Check if a permission exists in the registry
+     */
+    hasPermission(permission: string): boolean;
+}
+/**
+ * Wildcard permission resolver with configurable resolution strategies
+ */
+export declare class WildcardPermissionResolver extends PermissionResolver<string[]> {
+    private readonly strategy;
+    private readonly permissionRegistry;
+    private readonly cache;
+    private readonly maxPatternDepth;
+    private checkCount;
+    private totalResolutionTimeUs;
+    private cacheHits;
+    private cacheMisses;
+    constructor(strategy: PermissionResolutionStrategy, permissionRegistry: PermissionRegistry, cache: CacheAdapter, maxPatternDepth?: number);
+    /**
+     * 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
+     */
+    check(userPermissions: Set<string>, wildcardPatterns: string[]): Promise<boolean>;
+    /**
+     * 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.
+     */
+    private checkPreExpanded;
+    /**
+     * 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.
+     */
+    private checkOnDemand;
+    /**
+     * Check if any user permission matches the given pattern
+     */
+    private matchesAnyUserPermission;
+    /**
+     * 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
+     */
+    expandWildcardPatterns(patterns: string[]): Promise<Set<string>>;
+    /**
+     * Check permissions with detailed result information
+     */
+    checkWithResult(userPermissions: Set<string>, wildcardPatterns: string[]): Promise<PermissionCheckResult>;
+    /**
+     * Validate wildcard pattern format
+     */
+    private isValidWildcardPattern;
+    /**
+     * Get resolver type for identification
+     */
+    getType(): PermissionResolverType;
+    /**
+     * Get performance characteristics for monitoring
+     */
+    getPerformanceCharacteristics(): PerformanceCharacteristics;
+    /**
+     * Get performance statistics
+     */
+    getStats(): {
+        strategy: PermissionResolutionStrategy;
+        checkCount: number;
+        averageResolutionTimeUs: number;
+        totalResolutionTimeUs: number;
+        cacheHitRate: number;
+        cacheHits: number;
+        cacheMisses: number;
+    };
+    /**
+     * Reset performance statistics
+     */
+    resetStats(): void;
+    /**
+     * Get resolver name for debugging
+     */
+    getName(): string;
+    /**
+     * Check if this resolver can handle the given requirement type
+     */
+    canHandle(requirement: any): requirement is string[];
+}
+//# sourceMappingURL=WildcardPermissionResolver.d.ts.map