@vorionsys/security 1.0.0

package/dist/cognigate/types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Cognigate Types - Resource Limiting and Output Validation
+ *
+ * Type definitions for the Cognigate execution gateway's resource
+ * limiting and output validation capabilities.
+ *
+ * @packageDocumentation
+ * @module @vorion/cognigate/types
+ */
+import type { ID } from '../common/types.js';
+/**
+ * Resource limits for execution
+ */
+export interface ResourceLimits {
+    /** Maximum memory usage in MB */
+    maxMemoryMb: number;
+    /** Maximum CPU usage percentage */
+    maxCpuPercent: number;
+    /** Execution timeout in milliseconds */
+    timeoutMs: number;
+    /** Maximum number of network requests (optional) */
+    maxNetworkRequests?: number;
+    /** Maximum number of file system operations (optional) */
+    maxFileSystemOps?: number;
+}
+/**
+ * Resource usage metrics collected during execution
+ */
+export interface ResourceUsage {
+    /** Peak memory usage in MB */
+    memoryPeakMb: number;
+    /** CPU time consumed in milliseconds */
+    cpuTimeMs: number;
+    /** Wall clock time in milliseconds */
+    wallTimeMs: number;
+    /** Number of network requests made */
+    networkRequests: number;
+    /** Number of file system operations performed */
+    fileSystemOps: number;
+}
+/**
+ * Resource state provider interface for distributed resource tracking.
+ * Implementations use Redis for atomic operations across instances.
+ */
+export interface ResourceStateProvider {
+    /**
+     * Initialize execution tracking with limits and TTL
+     * @param executionId - Unique execution identifier
+     * @param limits - Resource limits to enforce
+     * @param ttlMs - Time-to-live for the execution record in milliseconds
+     */
+    initExecution(executionId: ID, limits: ResourceLimits, ttlMs: number): Promise<void>;
+    /**
+     * Record memory usage sample, updating peak if higher
+     * @param executionId - Unique execution identifier
+     * @param memoryMb - Current memory usage in MB
+     */
+    recordMemoryUsage(executionId: ID, memoryMb: number): Promise<void>;
+    /**
+     * Get peak memory usage for an execution
+     * @param executionId - Unique execution identifier
+     * @returns Peak memory in MB
+     */
+    getPeakMemory(executionId: ID): Promise<number>;
+    /**
+     * Atomically increment CPU time and return new total
+     * @param executionId - Unique execution identifier
+     * @param deltaMs - CPU time delta in milliseconds
+     * @returns New total CPU time in milliseconds
+     */
+    incrementCpuTime(executionId: ID, deltaMs: number): Promise<number>;
+    /**
+     * Get total CPU time for an execution
+     * @param executionId - Unique execution identifier
+     * @returns Total CPU time in milliseconds
+     */
+    getCpuTimeMs(executionId: ID): Promise<number>;
+    /**
+     * Atomically increment network request count and check limit
+     * @param executionId - Unique execution identifier
+     * @param limit - Maximum allowed requests
+     * @returns Object with allowed flag and current count
+     */
+    incrementNetworkRequests(executionId: ID, limit: number): Promise<{
+        allowed: boolean;
+        current: number;
+    }>;
+    /**
+     * Get current network request count
+     * @param executionId - Unique execution identifier
+     * @returns Current network request count
+     */
+    getNetworkRequestCount(executionId: ID): Promise<number>;
+    /**
+     * Atomically increment file system operation count and check limit
+     * @param executionId - Unique execution identifier
+     * @param limit - Maximum allowed operations
+     * @returns Object with allowed flag and current count
+     */
+    incrementFileSystemOps(executionId: ID, limit: number): Promise<{
+        allowed: boolean;
+        current: number;
+    }>;
+    /**
+     * Get current file system operation count
+     * @param executionId - Unique execution identifier
+     * @returns Current file system operation count
+     */
+    getFileSystemOpCount(executionId: ID): Promise<number>;
+    /**
+     * Check if execution should be terminated based on resource limits
+     * @param executionId - Unique execution identifier
+     * @param limits - Resource limits to check against
+     * @returns Termination decision with reason if applicable
+     */
+    shouldTerminate(executionId: ID, limits: ResourceLimits): Promise<{
+        terminate: boolean;
+        reason?: string;
+        violation?: string;
+    }>;
+    /**
+     * Clean up execution tracking and return final usage metrics
+     * @param executionId - Unique execution identifier
+     * @returns Final resource usage metrics
+     */
+    cleanupExecution(executionId: ID): Promise<ResourceUsage>;
+}
+/**
+ * Output validation mode
+ */
+export type OutputValidationMode = 'strict' | 'permissive';
+/**
+ * Output validation options
+ */
+export interface OutputValidationOptions {
+    /** Validation mode: strict (reject invalid) or permissive (log only) */
+    mode: OutputValidationMode;
+    /** Whether to sanitize PII from output */
+    sanitizePII: boolean;
+    /** Custom prohibited patterns */
+    prohibitedPatterns?: Array<{
+        type: 'regex' | 'keyword' | 'semantic';
+        pattern: string;
+        description: string;
+        severity?: 'low' | 'medium' | 'high' | 'critical';
+    }>;
+}
+/**
+ * Resource violation types
+ */
+export type ResourceViolationType = 'memory_exceeded' | 'cpu_exceeded' | 'timeout_exceeded' | 'network_limit_exceeded' | 'filesystem_limit_exceeded';
+/**
+ * Termination reason
+ */
+export interface TerminationReason {
+    /** Type of violation that caused termination */
+    violation: ResourceViolationType;
+    /** Human-readable reason */
+    reason: string;
+    /** Current value that exceeded limit */
+    currentValue: number;
+    /** Limit that was exceeded */
+    limit: number;
+    /** Timestamp when termination was triggered */
+    terminatedAt: string;
+}
+/**
+ * Execution state for tracking in-flight executions
+ */
+export interface ExecutionState {
+    /** Execution identifier */
+    executionId: ID;
+    /** Intent identifier */
+    intentId: ID;
+    /** Start time in ISO format */
+    startedAt: string;
+    /** Resource limits for this execution */
+    limits: ResourceLimits;
+    /** Whether execution has been terminated */
+    terminated: boolean;
+    /** Termination reason if terminated */
+    terminationReason?: TerminationReason;
+}
+/**
+ * Resource snapshot for atomic limit checking
+ */
+export interface ResourceSnapshot {
+    /** Peak memory usage in MB */
+    memoryPeakMb: number;
+    /** Total CPU time in milliseconds */
+    cpuTimeMs: number;
+    /** Wall clock time in milliseconds */
+    wallTimeMs: number;
+    /** Network request count */
+    networkRequests: number;
+    /** File system operation count */
+    fileSystemOps: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cognigate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cognigate/types.ts"],"names":[],"mappings":"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"}

package/dist/cognigate/types.js

@@ -0,0 +1,11 @@
+/**
+ * Cognigate Types - Resource Limiting and Output Validation
+ *
+ * Type definitions for the Cognigate execution gateway's resource
+ * limiting and output validation capabilities.
+ *
+ * @packageDocumentation
+ * @module @vorion/cognigate/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cognigate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cognigate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/common/adapters/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Adapter System for Redis Optionality
+ *
+ * This module exports all adapter interfaces and implementations,
+ * allowing Vorion to run with either Redis-backed or in-memory
+ * implementations of queues, caches, locks, sessions, and rate limiting.
+ *
+ * Usage:
+ * ```typescript
+ * import { getAdapterProvider } from './common/adapters';
+ *
+ * const provider = getAdapterProvider();
+ * const cache = provider.getCacheAdapter();
+ * await cache.set('key', 'value', 300);
+ * ```
+ *
+ * Or use convenience functions:
+ * ```typescript
+ * import { getCacheAdapter, getQueueAdapter } from './common/adapters';
+ *
+ * const cache = getCacheAdapter();
+ * const queue = getQueueAdapter('my-queue');
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { QueueJobOptions, JobCounts, Job, JobHandler, IQueueAdapter, ICacheAdapter, LockOptions, LockResult, ILockAdapter, Session, CreateSessionInput, ISessionStoreAdapter, RateLimitResult, IRateLimitAdapter, AdapterHealthStatus, AdapterProvider, } from './types.js';
+export { MemoryQueueAdapter, createMemoryQueueAdapter, } from './memory-queue.js';
+export { MemoryCacheAdapter, createMemoryCacheAdapter, getMemoryCacheAdapter, resetMemoryCacheAdapter, type MemoryCacheOptions, } from './memory-cache.js';
+export { MemoryLockAdapter, createMemoryLockAdapter, getMemoryLockAdapter, resetMemoryLockAdapter, } from './memory-lock.js';
+export { MemorySessionStoreAdapter, createMemorySessionStoreAdapter, getMemorySessionStoreAdapter, resetMemorySessionStoreAdapter, type MemorySessionStoreOptions, } from './memory-session.js';
+export { MemoryRateLimitAdapter, createMemoryRateLimitAdapter, getMemoryRateLimitAdapter, resetMemoryRateLimitAdapter, type MemoryRateLimitOptions, } from './memory-ratelimit.js';
+export { getAdapterProvider, createAdapterProvider, resetAdapterProvider, type AdapterProviderConfig, getQueueAdapter, getCacheAdapter, getLockAdapter, getSessionStoreAdapter, getRateLimitAdapter, } from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/common/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,YAAY,EAEV,eAAe,EACf,SAAS,EACT,GAAG,EACH,UAAU,EACV,aAAa,EAGb,aAAa,EAGb,WAAW,EACX,UAAU,EACV,YAAY,EAGZ,OAAO,EACP,kBAAkB,EAClB,oBAAoB,EAGpB,eAAe,EACf,iBAAiB,EAGjB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AAOpB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,4BAA4B,EAC5B,8BAA8B,EAC9B,KAAK,yBAAyB,GAC/B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,yBAAyB,EACzB,2BAA2B,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,qBAAqB,EAG1B,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,eAAe,CAAC"}

package/dist/common/adapters/index.js

@@ -0,0 +1,46 @@
+/**
+ * Adapter System for Redis Optionality
+ *
+ * This module exports all adapter interfaces and implementations,
+ * allowing Vorion to run with either Redis-backed or in-memory
+ * implementations of queues, caches, locks, sessions, and rate limiting.
+ *
+ * Usage:
+ * ```typescript
+ * import { getAdapterProvider } from './common/adapters';
+ *
+ * const provider = getAdapterProvider();
+ * const cache = provider.getCacheAdapter();
+ * await cache.set('key', 'value', 300);
+ * ```
+ *
+ * Or use convenience functions:
+ * ```typescript
+ * import { getCacheAdapter, getQueueAdapter } from './common/adapters';
+ *
+ * const cache = getCacheAdapter();
+ * const queue = getQueueAdapter('my-queue');
+ * ```
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// MEMORY IMPLEMENTATIONS
+// =============================================================================
+// Queue
+export { MemoryQueueAdapter, createMemoryQueueAdapter, } from './memory-queue.js';
+// Cache
+export { MemoryCacheAdapter, createMemoryCacheAdapter, getMemoryCacheAdapter, resetMemoryCacheAdapter, } from './memory-cache.js';
+// Lock
+export { MemoryLockAdapter, createMemoryLockAdapter, getMemoryLockAdapter, resetMemoryLockAdapter, } from './memory-lock.js';
+// Session
+export { MemorySessionStoreAdapter, createMemorySessionStoreAdapter, getMemorySessionStoreAdapter, resetMemorySessionStoreAdapter, } from './memory-session.js';
+// Rate Limit
+export { MemoryRateLimitAdapter, createMemoryRateLimitAdapter, getMemoryRateLimitAdapter, resetMemoryRateLimitAdapter, } from './memory-ratelimit.js';
+// =============================================================================
+// PROVIDER
+// =============================================================================
+export { getAdapterProvider, createAdapterProvider, resetAdapterProvider, 
+// Convenience functions
+getQueueAdapter, getCacheAdapter, getLockAdapter, getSessionStoreAdapter, getRateLimitAdapter, } from './provider.js';
+//# sourceMappingURL=index.js.map

package/dist/common/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAoCH,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF,QAAQ;AACR,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,QAAQ;AACR,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,GAExB,MAAM,mBAAmB,CAAC;AAE3B,OAAO;AACP,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,UAAU;AACV,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,4BAA4B,EAC5B,8BAA8B,GAE/B,MAAM,qBAAqB,CAAC;AAE7B,aAAa;AACb,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,yBAAyB,EACzB,2BAA2B,GAE5B,MAAM,uBAAuB,CAAC;AAE/B,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB;AAGpB,wBAAwB;AACxB,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,eAAe,CAAC"}

package/dist/common/adapters/memory-cache.d.ts

@@ -0,0 +1,91 @@
+/**
+ * In-Memory Cache Adapter
+ *
+ * Provides a cache implementation that runs entirely in memory,
+ * suitable for development, testing, or single-instance deployments.
+ *
+ * Features:
+ * - Key-value storage with Map
+ * - TTL tracking with automatic expiration
+ * - Background cleanup interval for expired entries
+ * - Pattern-based key listing (glob patterns)
+ *
+ * @packageDocumentation
+ */
+import type { ICacheAdapter } from './types.js';
+/**
+ * Configuration options for the memory cache
+ */
+export interface MemoryCacheOptions {
+    /** Interval for background cleanup of expired entries (ms) */
+    cleanupIntervalMs?: number;
+    /** Maximum number of entries (0 = unlimited) */
+    maxEntries?: number;
+}
+/**
+ * In-memory cache adapter implementation
+ */
+export declare class MemoryCacheAdapter implements ICacheAdapter {
+    private cache;
+    private cleanupTimer;
+    private readonly options;
+    constructor(options?: MemoryCacheOptions);
+    /**
+     * Get a value from cache
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a key from cache
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Check if a key exists in cache
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get keys matching a pattern
+     * Supports glob patterns: * (any characters), ? (single character)
+     */
+    keys(pattern: string): Promise<string[]>;
+    /**
+     * Clear all entries from cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of entries in cache
+     */
+    get size(): number;
+    /**
+     * Stop the background cleanup timer
+     */
+    stop(): void;
+    /**
+     * Start background cleanup of expired entries
+     */
+    private startCleanup;
+    /**
+     * Remove expired entries from cache
+     */
+    private cleanupExpired;
+    /**
+     * Convert glob pattern to regex
+     */
+    private patternToRegex;
+}
+/**
+ * Get the default memory cache instance
+ */
+export declare function getMemoryCacheAdapter(options?: MemoryCacheOptions): ICacheAdapter;
+/**
+ * Create a new memory cache instance (for testing or isolated usage)
+ */
+export declare function createMemoryCacheAdapter(options?: MemoryCacheOptions): MemoryCacheAdapter;
+/**
+ * Reset the default instance (for testing)
+ */
+export declare function resetMemoryCacheAdapter(): void;
+//# sourceMappingURL=memory-cache.d.ts.map

package/dist/common/adapters/memory-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../../../src/common/adapters/memory-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiBhD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;gBAE3C,OAAO,CAAC,EAAE,kBAAkB;IAexC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAgB5C;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvE;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB3C;;;OAGG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmB9C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,cAAc;CAWvB;AAOD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAKjF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,CAEzF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C"}

package/dist/common/adapters/memory-cache.js

@@ -0,0 +1,201 @@
+/**
+ * In-Memory Cache Adapter
+ *
+ * Provides a cache implementation that runs entirely in memory,
+ * suitable for development, testing, or single-instance deployments.
+ *
+ * Features:
+ * - Key-value storage with Map
+ * - TTL tracking with automatic expiration
+ * - Background cleanup interval for expired entries
+ * - Pattern-based key listing (glob patterns)
+ *
+ * @packageDocumentation
+ */
+import { createLogger } from '../logger.js';
+const logger = createLogger({ component: 'memory-cache' });
+/**
+ * Default cleanup interval in milliseconds (1 minute)
+ */
+const DEFAULT_CLEANUP_INTERVAL_MS = 60000;
+/**
+ * In-memory cache adapter implementation
+ */
+export class MemoryCacheAdapter {
+    cache = new Map();
+    cleanupTimer = null;
+    options;
+    constructor(options) {
+        this.options = {
+            cleanupIntervalMs: options?.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS,
+            maxEntries: options?.maxEntries ?? 0,
+        };
+        // Start background cleanup
+        this.startCleanup();
+        logger.debug({ cleanupIntervalMs: this.options.cleanupIntervalMs }, 'Memory cache created');
+    }
+    /**
+     * Get a value from cache
+     */
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check if expired
+        if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    /**
+     * Set a value in cache
+     */
+    async set(key, value, ttlSeconds) {
+        // Enforce max entries limit
+        if (this.options.maxEntries > 0 && this.cache.size >= this.options.maxEntries) {
+            // Evict oldest entry (LRU-like behavior)
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+        const expiresAt = ttlSeconds != null ? Date.now() + ttlSeconds * 1000 : null;
+        this.cache.set(key, {
+            value,
+            expiresAt,
+        });
+    }
+    /**
+     * Delete a key from cache
+     */
+    async del(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Check if a key exists in cache
+     */
+    async exists(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        // Check if expired
+        if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get keys matching a pattern
+     * Supports glob patterns: * (any characters), ? (single character)
+     */
+    async keys(pattern) {
+        const regex = this.patternToRegex(pattern);
+        const matchingKeys = [];
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            // Skip expired entries
+            if (entry.expiresAt !== null && entry.expiresAt <= now) {
+                continue;
+            }
+            if (regex.test(key)) {
+                matchingKeys.push(key);
+            }
+        }
+        return matchingKeys;
+    }
+    /**
+     * Clear all entries from cache
+     */
+    async clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of entries in cache
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Stop the background cleanup timer
+     */
+    stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    /**
+     * Start background cleanup of expired entries
+     */
+    startCleanup() {
+        if (this.options.cleanupIntervalMs <= 0) {
+            return;
+        }
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupExpired();
+        }, this.options.cleanupIntervalMs);
+        // Don't block process exit
+        this.cleanupTimer.unref();
+    }
+    /**
+     * Remove expired entries from cache
+     */
+    cleanupExpired() {
+        const now = Date.now();
+        let expiredCount = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiresAt !== null && entry.expiresAt <= now) {
+                this.cache.delete(key);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            logger.debug({ expiredCount }, 'Cleaned up expired cache entries');
+        }
+    }
+    /**
+     * Convert glob pattern to regex
+     */
+    patternToRegex(pattern) {
+        // Escape regex special characters except * and ?
+        const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        // Convert glob patterns to regex
+        const regexPattern = escaped
+            .replace(/\*/g, '.*') // * matches any characters
+            .replace(/\?/g, '.'); // ? matches single character
+        return new RegExp(`^${regexPattern}$`);
+    }
+}
+/**
+ * Singleton instance for default usage
+ */
+let defaultInstance = null;
+/**
+ * Get the default memory cache instance
+ */
+export function getMemoryCacheAdapter(options) {
+    if (!defaultInstance) {
+        defaultInstance = new MemoryCacheAdapter(options);
+    }
+    return defaultInstance;
+}
+/**
+ * Create a new memory cache instance (for testing or isolated usage)
+ */
+export function createMemoryCacheAdapter(options) {
+    return new MemoryCacheAdapter(options);
+}
+/**
+ * Reset the default instance (for testing)
+ */
+export function resetMemoryCacheAdapter() {
+    if (defaultInstance) {
+        defaultInstance.stop();
+        defaultInstance = null;
+    }
+}
+//# sourceMappingURL=memory-cache.js.map

package/dist/common/adapters/memory-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.js","sourceRoot":"","sources":["../../../src/common/adapters/memory-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,CAAC;AAU3D;;GAEG;AACH,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAY1C;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACrB,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,YAAY,GAA0B,IAAI,CAAC;IAClC,OAAO,CAA+B;IAEvD,YAAY,OAA4B;QACtC,IAAI,CAAC,OAAO,GAAG;YACb,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,IAAI,2BAA2B;YAC5E,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,CAAC;SACrC,CAAC;QAEF,2BAA2B;QAC3B,IAAI,CAAC,YAAY,EAAE,CAAC;QAEpB,MAAM,CAAC,KAAK,CACV,EAAE,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,EACrD,sBAAsB,CACvB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mBAAmB;QACnB,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAC9D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,KAAU,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,UAAmB;QACrD,4BAA4B;QAC5B,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9E,yCAAyC;YACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,MAAM,SAAS,GAAG,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAE7E,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,KAAK,CAAC;QACf,CAAC;QAED,mBAAmB;QACnB,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAC9D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,OAAe;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,uBAAuB;YACvB,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBACvD,SAAS;YACX,CAAC;YAED,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;OAEG;IACK,YAAY;QAClB,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC;YACxC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;YACnC,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAEnC,2BAA2B;QAC3B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACK,cAAc;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBACvD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,YAAY,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QAED,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,EAAE,kCAAkC,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,OAAe;QACpC,iDAAiD;QACjD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;QAE7D,iCAAiC;QACjC,MAAM,YAAY,GAAG,OAAO;aACzB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,2BAA2B;aAChD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,6BAA6B;QAErD,OAAO,IAAI,MAAM,CAAC,IAAI,YAAY,GAAG,CAAC,CAAC;IACzC,CAAC;CACF;AAED;;GAEG;AACH,IAAI,eAAe,GAA8B,IAAI,CAAC;AAEtD;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA4B;IAChE,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,eAAe,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAA4B;IACnE,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,IAAI,eAAe,EAAE,CAAC;QACpB,eAAe,CAAC,IAAI,EAAE,CAAC;QACvB,eAAe,GAAG,IAAI,CAAC;IACzB,CAAC;AACH,CAAC"}