@noony-serverless/core/build/middlewares/guards/registry/PermissionRegistry.d.ts

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

/**
 * Permission Registry
 *
 * Central registry for managing available permissions in the system.
 * Supports wildcard pattern expansion, permission discovery, and
 * category-based organization for efficient permission management.
 *
 * Key Features:
 * - Permission registration and discovery
 * - Wildcard pattern expansion ("admin.*" -> ["admin.users", "admin.roles"])
 * - Category-based organization
 * - Thread-safe operations with caching
 * - Auto-discovery from codebase annotations
 * - Permission hierarchy validation
 *
 * @author Noony Framework Team
 * @version 1.0.0
 */
/**
 * Permission metadata for rich permission information
 */
export interface PermissionMetadata {
    /** Permission string (e.g., "admin.users.create") */
    permission: string;
    /** Human-readable description */
    description: string;
    /** Permission category (e.g., "admin", "user", "content") */
    category: string;
    /** Sub-category (e.g., "users", "roles") */
    subCategory?: string;
    /** Action (e.g., "create", "read", "update", "delete") */
    action?: string;
    /** Risk level for security analysis */
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    /** Whether this permission requires additional validation */
    requiresValidation: boolean;
    /** Related permissions that are commonly used together */
    relatedPermissions?: string[];
    /** When this permission was registered */
    registeredAt: Date;
}
/**
 * Permission registry interface for wildcard expansion and management
 */
export interface PermissionRegistry {
    /**
     * Register a permission with metadata
     */
    registerPermission(metadata: PermissionMetadata): void;
    /**
     * Register multiple permissions at once
     */
    registerPermissions(permissions: PermissionMetadata[]): void;
    /**
     * Get all permissions matching a wildcard pattern
     */
    getMatchingPermissions(wildcardPattern: string): string[];
    /**
     * Get all permissions in a category
     */
    getCategoryPermissions(category: string): string[];
    /**
     * Check if a permission exists in the registry
     */
    hasPermission(permission: string): boolean;
    /**
     * Get permission metadata
     */
    getPermissionMetadata(permission: string): PermissionMetadata | null;
    /**
     * Get all registered permissions
     */
    getAllPermissions(): string[];
    /**
     * Get all categories
     */
    getAllCategories(): string[];
    /**
     * Get registry statistics
     */
    getStats(): PermissionRegistryStats;
}
/**
 * Registry statistics for monitoring
 */
export interface PermissionRegistryStats {
    totalPermissions: number;
    totalCategories: number;
    permissionsByCategory: Record<string, number>;
    riskLevelDistribution: Record<string, number>;
    registrationTimeline: Date[];
}
/**
 * Default permission registry implementation
 *
 * Thread-safe in-memory registry with caching for pattern matching.
 * In production, this could be backed by a database or external service.
 */
export declare class DefaultPermissionRegistry implements PermissionRegistry {
    private readonly permissions;
    private readonly categoryIndex;
    private readonly patternCache;
    private stats;
    constructor();
    /**
     * Register a permission with metadata
     */
    registerPermission(metadata: PermissionMetadata): void;
    /**
     * Register multiple permissions at once
     */
    registerPermissions(permissions: PermissionMetadata[]): void;
    /**
     * Get all permissions matching a wildcard pattern
     */
    getMatchingPermissions(wildcardPattern: string): string[];
    /**
     * Get all permissions in a category
     */
    getCategoryPermissions(category: string): string[];
    /**
     * Check if a permission exists in the registry
     */
    hasPermission(permission: string): boolean;
    /**
     * Get permission metadata
     */
    getPermissionMetadata(permission: string): PermissionMetadata | null;
    /**
     * Get all registered permissions
     */
    getAllPermissions(): string[];
    /**
     * Get all categories
     */
    getAllCategories(): string[];
    /**
     * Get registry statistics
     */
    getStats(): PermissionRegistryStats;
    /**
     * Get performance statistics
     */
    getPerformanceStats(): {
        totalLookups: number;
        averagePatternMatchingTimeUs: number;
        cacheHitRate: number;
        cacheSize: number;
    };
    /**
     * Clear the pattern cache
     */
    clearCache(): void;
    /**
     * Initialize common system permissions
     */
    private initializeSystemPermissions;
    /**
     * Validate permission format (2-3 levels with alphanumeric + dots)
     */
    private isValidPermissionFormat;
    /**
     * Extract category from permission string
     */
    private extractCategory;
    /**
     * Convert wildcard pattern to regex
     */
    private wildcardToRegex;
}
/**
 * Factory for creating permission registries
 */
export declare class PermissionRegistryFactory {
    /**
     * Create a default permission registry with system permissions
     */
    static createDefault(): DefaultPermissionRegistry;
    /**
     * Create an empty permission registry
     */
    static createEmpty(): DefaultPermissionRegistry;
    /**
     * Create a registry from a permission definition file
     */
    static createFromDefinitions(definitions: PermissionMetadata[]): DefaultPermissionRegistry;
}
//# sourceMappingURL=PermissionRegistry.d.ts.map