@noony-serverless/core/build/middlewares/guards/cache/ConservativeCacheInvalidation.d.ts

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

/**
 * Conservative Cache Invalidation Service
 *
 * Implements a security-first approach to cache invalidation for permission systems.
 * When in doubt about data freshness or permission changes, this service errs on the
 * side of security by clearing broader cache segments rather than risking stale data.
 *
 * Security Principles:
 * - Invalidate broadly rather than narrowly when permissions change
 * - Clear dependent caches proactively to prevent inconsistencies
 * - Use time-based invalidation as backup for missed updates
 * - Log all invalidation events for audit trails
 * - Provide rollback capabilities for accidental cache clears
 *
 * Use Cases:
 * - User permission changes (role assignments, direct permissions)
 * - System-wide permission updates (new permissions, policy changes)
 * - Security incidents requiring immediate cache clearing
 * - Scheduled maintenance and cache refresh operations
 * - Development and testing environment resets
 *
 * @author Noony Framework Team
 * @version 1.0.0
 */
import { CacheAdapter } from './CacheAdapter';
/**
 * Cache invalidation event for audit logging
 */
export interface CacheInvalidationEvent {
    eventId: string;
    type: InvalidationType;
    scope: InvalidationScope;
    patterns: string[];
    affectedKeys?: string[];
    reason: string;
    userId?: string;
    timestamp: string;
    restorable: boolean;
    performance: {
        keysCleared: number;
        executionTimeMs: number;
    };
}
/**
 * Types of cache invalidation operations
 */
export declare enum InvalidationType {
    USER_PERMISSION_CHANGE = "user_permission_change",
    ROLE_ASSIGNMENT_CHANGE = "role_assignment_change",
    SYSTEM_PERMISSION_UPDATE = "system_permission_update",
    SECURITY_INCIDENT = "security_incident",
    SCHEDULED_REFRESH = "scheduled_refresh",
    MANUAL_CLEAR = "manual_clear",
    DEVELOPMENT_RESET = "development_reset"
}
/**
 * Scope of cache invalidation
 */
export declare enum InvalidationScope {
    SINGLE_USER = "single_user",
    MULTIPLE_USERS = "multiple_users",
    ROLE_BASED = "role_based",
    SYSTEM_WIDE = "system_wide",
    PERMISSION_SPECIFIC = "permission_specific"
}
/**
 * Conservative Cache Invalidation Implementation
 */
export declare class ConservativeCacheInvalidation {
    private readonly cache;
    private readonly auditLog;
    private readonly backups;
    private readonly maxAuditLogSize;
    private readonly maxBackupAge;
    private invalidationCount;
    private totalKeysCleared;
    private totalExecutionTimeMs;
    constructor(cache: CacheAdapter);
    /**
     * Invalidate cache for specific user permission changes
     *
     * Conservative approach: Clears all permission-related caches for the user
     * and any cached data that might depend on their permissions.
     *
     * @param userId - User whose permissions changed
     * @param reason - Reason for invalidation
     * @param createBackup - Whether to create restoration backup
     * @returns Invalidation event details
     */
    invalidateUserPermissions(userId: string, reason: string, createBackup?: boolean): Promise<CacheInvalidationEvent>;
    /**
     * Invalidate cache for role-based permission changes
     *
     * Conservative approach: Clears caches for all users with the affected roles
     * plus any system-level permission caches that might be affected.
     *
     * @param roles - Roles whose permissions changed
     * @param reason - Reason for invalidation
     * @param createBackup - Whether to create restoration backup
     * @returns Invalidation event details
     */
    invalidateRolePermissions(roles: string[], reason: string, createBackup?: boolean): Promise<CacheInvalidationEvent>;
    /**
     * System-wide cache invalidation
     *
     * Nuclear option: Clears all permission-related caches across the system.
     * Used for major system updates, security incidents, or when unsure about
     * the scope of changes.
     *
     * @param reason - Reason for system-wide invalidation
     * @param createBackup - Whether to create restoration backup
     * @returns Invalidation event details
     */
    invalidateSystemWide(reason: string, createBackup?: boolean): Promise<CacheInvalidationEvent>;
    /**
     * Emergency security invalidation
     *
     * Immediate cache clearing for security incidents.
     * Bypasses backup creation for speed and clears everything.
     *
     * @param reason - Security incident description
     * @returns Invalidation event details
     */
    emergencySecurityInvalidation(reason: string): Promise<CacheInvalidationEvent>;
    /**
     * Restore cache from backup
     *
     * Attempts to restore previously backed up cache data.
     * Use with caution - only restore if you're certain the data is safe.
     *
     * @param backupId - ID of the backup to restore
     * @returns Restoration success status
     */
    restoreFromBackup(backupId: string): Promise<boolean>;
    /**
     * Get invalidation audit log
     */
    getAuditLog(): CacheInvalidationEvent[];
    /**
     * Get available backups
     */
    getAvailableBackups(): Array<{
        backupId: string;
        timestamp: string;
        scope: InvalidationScope;
        totalEntries: number;
        sizeBytes: number;
        ageHours: number;
    }>;
    /**
     * Get invalidation statistics
     */
    getStats(): {
        invalidationCount: number;
        totalKeysCleared: number;
        averageExecutionTimeMs: number;
        totalExecutionTimeMs: number;
        auditLogSize: number;
        backupsAvailable: number;
        oldestBackupAge: number;
    };
    /**
     * Clear patterns from cache
     */
    private clearCachesByPatterns;
    /**
     * Create backup of cache data
     */
    private createBackup;
    /**
     * Record audit event
     */
    private recordAuditEvent;
    /**
     * Update performance metrics
     */
    private updatePerformanceMetrics;
    /**
     * Generate unique event ID
     */
    private generateEventId;
    /**
     * Clean up old backups
     */
    private cleanupOldBackups;
    /**
     * Get age of oldest backup in hours
     */
    private getOldestBackupAge;
}
//# sourceMappingURL=ConservativeCacheInvalidation.d.ts.map