@noony-serverless/core 0.1.0 → 0.1.1

package/build/middlewares/guards/cache/MemoryCacheAdapter.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Memory Cache Adapter with LRU Eviction
+ *
+ * High-performance in-memory cache implementation using Least Recently Used (LRU)
+ * eviction strategy. Optimized for single-instance deployments where sub-millisecond
+ * cache lookups are critical for authentication performance.
+ *
+ * Features:
+ * - O(1) get/set operations using Map and doubly-linked list
+ * - TTL support with lazy expiration checking
+ * - Configurable size limits with automatic eviction
+ * - Pattern-based deletion for cache invalidation
+ * - Performance metrics for monitoring
+ * - Memory usage tracking
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCacheAdapter = void 0;
+/**
+ * Memory cache adapter with LRU eviction policy
+ *
+ * Uses a combination of Map for O(1) key lookups and a doubly-linked list
+ * for O(1) LRU operations. TTL is implemented with lazy expiration checking
+ * to avoid timer overhead.
+ */
+class MemoryCacheAdapter {
+    cache = new Map();
+    maxSize;
+    defaultTTL;
+    name;
+    // Doubly-linked list for LRU tracking
+    head;
+    tail;
+    // Performance metrics
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+        startTime: Date.now(),
+    };
+    constructor(config) {
+        this.maxSize = config.maxSize;
+        this.defaultTTL = config.defaultTTL;
+        this.name = config.name || 'memory-cache';
+        // Validate configuration
+        if (this.maxSize <= 0) {
+            throw new Error('Cache maxSize must be greater than 0');
+        }
+        if (this.defaultTTL <= 0) {
+            throw new Error('Cache defaultTTL must be greater than 0');
+        }
+    }
+    /**
+     * Retrieve a value from cache
+     *
+     * @param key - Cache key to retrieve
+     * @returns Promise resolving to cached value or null if not found/expired
+     */
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            return null;
+        }
+        // Check expiration (lazy expiration)
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.removeEntry(entry);
+            this.stats.misses++;
+            return null;
+        }
+        // Move to head (mark as recently used)
+        this.moveToHead(entry);
+        this.stats.hits++;
+        return entry.value;
+    }
+    /**
+     * Store a value in cache with optional TTL
+     *
+     * @param key - Cache key to store under
+     * @param value - Value to cache
+     * @param ttlMs - Time to live in milliseconds (defaults to defaultTTL)
+     */
+    async set(key, value, ttlMs) {
+        const ttl = ttlMs ?? this.defaultTTL;
+        const expiresAt = ttl > 0 ? Date.now() + ttl : undefined;
+        // Check if key already exists
+        const existingEntry = this.cache.get(key);
+        if (existingEntry) {
+            // Update existing entry
+            existingEntry.value = value;
+            existingEntry.expiresAt = expiresAt;
+            this.moveToHead(existingEntry);
+            return;
+        }
+        // Create new entry
+        const entry = {
+            key,
+            value,
+            expiresAt,
+        };
+        // Add to cache and linked list
+        this.cache.set(key, entry);
+        this.addToHead(entry);
+        // Evict oldest entry if cache is full
+        if (this.cache.size > this.maxSize) {
+            this.evictTail();
+        }
+    }
+    /**
+     * Delete a specific cache entry
+     *
+     * @param key - Cache key to delete
+     */
+    async delete(key) {
+        const entry = this.cache.get(key);
+        if (entry) {
+            this.removeEntry(entry);
+        }
+    }
+    /**
+     * Delete multiple cache entries matching a pattern
+     *
+     * Supports simple wildcard patterns:
+     * - "user:*" matches all keys starting with "user:"
+     * - "*:123" matches all keys ending with ":123"
+     * - "*pattern*" matches all keys containing "pattern"
+     *
+     * @param pattern - Pattern to match keys
+     */
+    async deletePattern(pattern) {
+        const regex = this.patternToRegex(pattern);
+        const keysToDelete = [];
+        // Collect matching keys
+        for (const key of this.cache.keys()) {
+            if (regex.test(key)) {
+                keysToDelete.push(key);
+            }
+        }
+        // Delete matching entries
+        for (const key of keysToDelete) {
+            await this.delete(key);
+        }
+    }
+    /**
+     * Clear all cache entries
+     */
+    async flush() {
+        this.cache.clear();
+        this.head = undefined;
+        this.tail = undefined;
+        this.stats.evictions += this.cache.size;
+    }
+    /**
+     * Get cache statistics for monitoring
+     *
+     * @returns Cache statistics including hit rate and memory usage
+     */
+    async getStats() {
+        const totalRequests = this.stats.hits + this.stats.misses;
+        const hitRate = totalRequests > 0 ? (this.stats.hits / totalRequests) * 100 : 0;
+        // Estimate memory usage (rough approximation)
+        let memoryUsage = 0;
+        for (const entry of this.cache.values()) {
+            memoryUsage += this.estimateEntrySize(entry);
+        }
+        return {
+            totalEntries: this.cache.size,
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            hitRate: Math.round(hitRate * 100) / 100, // Round to 2 decimal places
+            memoryUsage,
+            uptime: Date.now() - this.stats.startTime,
+        };
+    }
+    /**
+     * Get cache name for debugging
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Get current cache size
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if cache is at maximum capacity
+     */
+    isFull() {
+        return this.cache.size >= this.maxSize;
+    }
+    // === Private LRU Implementation Methods ===
+    /**
+     * Add entry to head of linked list (most recently used)
+     */
+    addToHead(entry) {
+        entry.prev = undefined;
+        entry.next = this.head;
+        if (this.head) {
+            this.head.prev = entry;
+        }
+        this.head = entry;
+        if (!this.tail) {
+            this.tail = entry;
+        }
+    }
+    /**
+     * Move existing entry to head of linked list
+     */
+    moveToHead(entry) {
+        // Remove from current position
+        this.removeFromList(entry);
+        // Add to head
+        this.addToHead(entry);
+    }
+    /**
+     * Remove entry from linked list (but not from cache)
+     */
+    removeFromList(entry) {
+        if (entry.prev) {
+            entry.prev.next = entry.next;
+        }
+        else {
+            // This was the head
+            this.head = entry.next;
+        }
+        if (entry.next) {
+            entry.next.prev = entry.prev;
+        }
+        else {
+            // This was the tail
+            this.tail = entry.prev;
+        }
+    }
+    /**
+     * Remove entry from both cache and linked list
+     */
+    removeEntry(entry) {
+        this.cache.delete(entry.key);
+        this.removeFromList(entry);
+    }
+    /**
+     * Evict least recently used entry (tail)
+     */
+    evictTail() {
+        if (this.tail) {
+            this.removeEntry(this.tail);
+            this.stats.evictions++;
+        }
+    }
+    /**
+     * Convert glob pattern to regular expression
+     */
+    patternToRegex(pattern) {
+        // Convert * to placeholder first to avoid escaping issues
+        const withPlaceholder = pattern.replace(/\*/g, '__WILDCARD__');
+        // Escape special regex characters
+        const escaped = withPlaceholder.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        // Convert placeholder to regex equivalent
+        const regexPattern = escaped.replace(/__WILDCARD__/g, '.*');
+        return new RegExp(`^${regexPattern}$`);
+    }
+    /**
+     * Estimate memory usage of a cache entry (rough approximation)
+     */
+    estimateEntrySize(entry) {
+        let size = 0;
+        // Key size (2 bytes per character for UTF-16)
+        size += entry.key.length * 2;
+        // Value size estimation
+        if (typeof entry.value === 'string') {
+            size += entry.value.length * 2;
+        }
+        else if (typeof entry.value === 'number') {
+            size += 8;
+        }
+        else if (typeof entry.value === 'boolean') {
+            size += 1;
+        }
+        else if (entry.value && typeof entry.value === 'object') {
+            // JSON string length as approximation
+            size += JSON.stringify(entry.value).length * 2;
+        }
+        // Overhead for entry object and pointers
+        size += 64;
+        return size;
+    }
+}
+exports.MemoryCacheAdapter = MemoryCacheAdapter;
+//# sourceMappingURL=MemoryCacheAdapter.js.map

package/build/middlewares/guards/cache/NoopCacheAdapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * No-Operation Cache Adapter
+ *
+ * A cache adapter implementation that doesn't actually cache anything.
+ * Useful for testing scenarios, disabled caching configurations, or
+ * development environments where cache behavior needs to be bypassed.
+ *
+ * All operations return immediately without storing or retrieving data,
+ * ensuring that the guard system can operate without caching when needed.
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+import { CacheAdapter, CacheStats } from './CacheAdapter';
+/**
+ * No-operation cache adapter that doesn't cache anything
+ *
+ * This implementation provides the CacheAdapter interface but performs
+ * no actual caching operations. All get operations return null, all set
+ * operations are ignored, and all delete operations are no-ops.
+ *
+ * Useful for:
+ * - Testing scenarios where caching should be disabled
+ * - Development environments with live data
+ * - Troubleshooting cache-related issues
+ * - Performance baseline measurements
+ */
+export declare class NoopCacheAdapter implements CacheAdapter {
+    private readonly startTime;
+    private readonly name;
+    private stats;
+    constructor(name?: string);
+    /**
+     * Always returns null (no caching)
+     *
+     * @param key - Cache key to retrieve (ignored)
+     * @returns Promise resolving to null
+     */
+    get<T>(_key: string): Promise<T | null>;
+    /**
+     * Does nothing (no caching)
+     *
+     * @param key - Cache key to store under (ignored)
+     * @param value - Value to cache (ignored)
+     * @param ttlMs - Time to live in milliseconds (ignored)
+     */
+    set<T>(_key: string, _value: T, _ttlMs?: number): Promise<void>;
+    /**
+     * Does nothing (no caching)
+     *
+     * @param key - Cache key to delete (ignored)
+     */
+    delete(_key: string): Promise<void>;
+    /**
+     * Does nothing (no caching)
+     *
+     * @param pattern - Pattern to match keys (ignored)
+     */
+    deletePattern(_pattern: string): Promise<void>;
+    /**
+     * Does nothing (no caching)
+     */
+    flush(): Promise<void>;
+    /**
+     * Get statistics for monitoring
+     *
+     * Returns statistics about operations performed, even though
+     * no actual caching occurs. This helps with monitoring and
+     * understanding system behavior.
+     *
+     * @returns Cache statistics with 0% hit rate
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Get adapter name for debugging
+     */
+    getName(): string;
+    /**
+     * Get operation statistics for debugging
+     */
+    getOperationStats(): {
+        gets: number;
+        sets: number;
+        deletes: number;
+        flushes: number;
+    };
+    /**
+     * Check if this is a no-op cache adapter
+     *
+     * Utility method for other components to detect when
+     * caching is disabled and adjust behavior accordingly.
+     */
+    isNoop(): boolean;
+}
+//# sourceMappingURL=NoopCacheAdapter.d.ts.map

package/build/middlewares/guards/cache/NoopCacheAdapter.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * No-Operation Cache Adapter
+ *
+ * A cache adapter implementation that doesn't actually cache anything.
+ * Useful for testing scenarios, disabled caching configurations, or
+ * development environments where cache behavior needs to be bypassed.
+ *
+ * All operations return immediately without storing or retrieving data,
+ * ensuring that the guard system can operate without caching when needed.
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopCacheAdapter = void 0;
+/**
+ * No-operation cache adapter that doesn't cache anything
+ *
+ * This implementation provides the CacheAdapter interface but performs
+ * no actual caching operations. All get operations return null, all set
+ * operations are ignored, and all delete operations are no-ops.
+ *
+ * Useful for:
+ * - Testing scenarios where caching should be disabled
+ * - Development environments with live data
+ * - Troubleshooting cache-related issues
+ * - Performance baseline measurements
+ */
+class NoopCacheAdapter {
+    startTime = Date.now();
+    name;
+    // Track statistics even though we don't cache
+    stats = {
+        gets: 0,
+        sets: 0,
+        deletes: 0,
+        flushes: 0,
+    };
+    constructor(name = 'noop-cache') {
+        this.name = name;
+    }
+    /**
+     * Always returns null (no caching)
+     *
+     * @param key - Cache key to retrieve (ignored)
+     * @returns Promise resolving to null
+     */
+    async get(_key) {
+        this.stats.gets++;
+        return null;
+    }
+    /**
+     * Does nothing (no caching)
+     *
+     * @param key - Cache key to store under (ignored)
+     * @param value - Value to cache (ignored)
+     * @param ttlMs - Time to live in milliseconds (ignored)
+     */
+    async set(_key, _value, _ttlMs) {
+        this.stats.sets++;
+        // Intentionally do nothing
+    }
+    /**
+     * Does nothing (no caching)
+     *
+     * @param key - Cache key to delete (ignored)
+     */
+    async delete(_key) {
+        this.stats.deletes++;
+        // Intentionally do nothing
+    }
+    /**
+     * Does nothing (no caching)
+     *
+     * @param pattern - Pattern to match keys (ignored)
+     */
+    async deletePattern(_pattern) {
+        this.stats.deletes++;
+        // Intentionally do nothing
+    }
+    /**
+     * Does nothing (no caching)
+     */
+    async flush() {
+        this.stats.flushes++;
+        // Intentionally do nothing
+    }
+    /**
+     * Get statistics for monitoring
+     *
+     * Returns statistics about operations performed, even though
+     * no actual caching occurs. This helps with monitoring and
+     * understanding system behavior.
+     *
+     * @returns Cache statistics with 0% hit rate
+     */
+    async getStats() {
+        return {
+            totalEntries: 0, // Never stores anything
+            hits: 0, // Never hits (always returns null)
+            misses: this.stats.gets, // Every get is a miss
+            hitRate: 0, // Always 0% hit rate
+            memoryUsage: 0, // Uses no memory for caching
+            uptime: Date.now() - this.startTime,
+        };
+    }
+    /**
+     * Get adapter name for debugging
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Get operation statistics for debugging
+     */
+    getOperationStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Check if this is a no-op cache adapter
+     *
+     * Utility method for other components to detect when
+     * caching is disabled and adjust behavior accordingly.
+     */
+    isNoop() {
+        return true;
+    }
+}
+exports.NoopCacheAdapter = NoopCacheAdapter;
+//# sourceMappingURL=NoopCacheAdapter.js.map

package/build/middlewares/guards/config/GuardConfiguration.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Guard System Configuration
+ *
+ * Comprehensive configuration system for the high-performance guard system.
+ * Provides type-safe configuration for different deployment environments with
+ * configurable performance strategies and security policies.
+ *
+ * Key Features:
+ * - Permission resolution strategy configuration (pre-expansion vs on-demand)
+ * - Cache adapter injection for different environments
+ * - Performance profiles for development, staging, and production
+ * - Security policies with conservative cache invalidation
+ * - Bounded complexity limits for patterns and expressions
+ *
+ * @author Noony Framework Team
+ * @version 1.0.0
+ */
+/**
+ * Permission resolution strategies for wildcard permissions
+ *
+ * PRE_EXPANSION: Expand wildcards at user context load time
+ * - Pros: Faster runtime permission checks (O(1) set lookups)
+ * - Cons: Higher memory usage, requires permission registry
+ *
+ * ON_DEMAND: Match wildcards at permission check time
+ * - Pros: Lower memory usage, supports dynamic permissions
+ * - Cons: Pattern matching overhead per request
+ */
+export declare enum PermissionResolutionStrategy {
+    PRE_EXPANSION = "pre-expansion",
+    ON_DEMAND = "on-demand"
+}
+/**
+ * Cache invalidation strategies for security
+ */
+export declare enum CacheInvalidationStrategy {
+    FLUSH_ALL = "flush-all",
+    USER_SPECIFIC = "user-specific"
+}
+/**
+ * Performance monitoring levels
+ */
+export declare enum MonitoringLevel {
+    NONE = "none",
+    BASIC = "basic",
+    DETAILED = "detailed",
+    VERBOSE = "verbose"
+}
+/**
+ * Security configuration for the guard system
+ */
+export interface GuardSecurityConfig {
+    permissionResolutionStrategy: PermissionResolutionStrategy;
+    conservativeCacheInvalidation: boolean;
+    maxExpressionComplexity: number;
+    maxPatternDepth: number;
+    maxNestingDepth: number;
+}
+/**
+ * Cache configuration for the guard system
+ */
+export interface GuardCacheConfig {
+    maxEntries: number;
+    defaultTtlMs: number;
+    userContextTtlMs: number;
+    authTokenTtlMs: number;
+}
+/**
+ * Monitoring configuration for the guard system
+ */
+export interface GuardMonitoringConfig {
+    enablePerformanceTracking: boolean;
+    enableDetailedLogging: boolean;
+    logLevel: string;
+    metricsCollectionInterval: number;
+}
+/**
+ * Environment profile for guard system configuration
+ */
+export interface GuardEnvironmentProfile {
+    environment: string;
+    cacheType: 'memory' | 'redis' | 'none';
+    security: GuardSecurityConfig;
+    cache: GuardCacheConfig;
+    monitoring: GuardMonitoringConfig;
+}
+/**
+ * GuardConfiguration class implementation
+ */
+export declare class GuardConfiguration {
+    readonly security: GuardSecurityConfig;
+    readonly cache: GuardCacheConfig;
+    readonly monitoring: GuardMonitoringConfig;
+    constructor(security: GuardSecurityConfig, cache: GuardCacheConfig, monitoring: GuardMonitoringConfig);
+    /**
+     * Create GuardConfiguration from environment profile
+     */
+    static fromEnvironmentProfile(profile: GuardEnvironmentProfile): GuardConfiguration;
+    /**
+     * Create default development configuration
+     */
+    static development(): GuardConfiguration;
+    /**
+     * Create default production configuration
+     */
+    static production(): GuardConfiguration;
+    /**
+     * Validate configuration
+     */
+    validate(): void;
+}
+//# sourceMappingURL=GuardConfiguration.d.ts.map