@noony-serverless/core/build/middlewares/guards/resolvers/WildcardPermissionResolver.d.ts

A Middy base framework compatible with Firebase and GCP Cloud Functions with TypeScript

/**
 * 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