@skillsmith/core 0.1.0

package/dist/src/security/RateLimiter.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Rate Limiter - SMI-730, SMI-1013
+ *
+ * Token bucket algorithm for rate limiting API endpoints and adapters.
+ * Prevents abuse and DoS attacks with configurable limits and windows.
+ *
+ * Features:
+ * - Token bucket algorithm for smooth rate limiting
+ * - Per-IP and per-user limits
+ * - Configurable limits and windows
+ * - In-memory storage (Redis-compatible interface)
+ * - Graceful degradation on errors
+ * - Request queue for waiting when rate limited (SMI-1013)
+ * - Configurable timeout for queued requests (SMI-1013)
+ */
+/**
+ * Rate limit metrics for monitoring and alerting
+ */
+export interface RateLimitMetrics {
+    /** Number of allowed requests */
+    allowed: number;
+    /** Number of blocked requests */
+    blocked: number;
+    /** Number of errors (storage failures, etc.) */
+    errors: number;
+    /** Last time metrics were reset */
+    lastReset: Date;
+    /** Last time metrics were updated */
+    lastUpdated: Date;
+}
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+    /** Maximum tokens in bucket (burst capacity) */
+    maxTokens: number;
+    /** Tokens refilled per second */
+    refillRate: number;
+    /** Window duration in milliseconds (for cleanup) */
+    windowMs: number;
+    /** Key prefix for storage */
+    keyPrefix?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Callback when rate limit is exceeded */
+    onLimitExceeded?: (key: string, metrics: RateLimitMetrics) => void;
+    /** Fail mode on storage errors: 'open' allows requests, 'closed' denies them (default: 'open') */
+    failMode?: 'open' | 'closed';
+    /** Enable request queuing when rate limited (SMI-1013, default: false) */
+    enableQueue?: boolean;
+    /** Maximum time to wait in queue in milliseconds (SMI-1013, default: 30000) */
+    queueTimeoutMs?: number;
+    /** Maximum number of requests that can wait in queue (SMI-1013, default: 100) */
+    maxQueueSize?: number;
+}
+/**
+ * Token bucket state
+ */
+interface TokenBucket {
+    /** Current number of tokens */
+    tokens: number;
+    /** Last refill timestamp */
+    lastRefill: number;
+    /** First request timestamp (for window tracking) */
+    firstRequest: number;
+}
+/**
+ * Rate limit result
+ */
+export interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Remaining tokens */
+    remaining: number;
+    /** Total tokens in bucket */
+    limit: number;
+    /** Milliseconds until bucket refills */
+    retryAfterMs?: number;
+    /** When the limit resets (ISO timestamp) */
+    resetAt?: string;
+    /** Current metrics for this key (optional) */
+    metrics?: RateLimitMetrics;
+    /** Whether the request waited in queue (SMI-1013) */
+    queued?: boolean;
+    /** Time spent waiting in queue in milliseconds (SMI-1013) */
+    queueWaitMs?: number;
+}
+/**
+ * Error thrown when queue timeout is exceeded (SMI-1013)
+ */
+export declare class RateLimitQueueTimeoutError extends Error {
+    readonly key: string;
+    readonly timeoutMs: number;
+    constructor(key: string, timeoutMs: number);
+}
+/**
+ * Error thrown when queue is full (SMI-1013)
+ */
+export declare class RateLimitQueueFullError extends Error {
+    readonly key: string;
+    readonly maxQueueSize: number;
+    constructor(key: string, maxQueueSize: number);
+}
+/**
+ * Storage interface for rate limit data
+ */
+export interface RateLimitStorage {
+    get(key: string): Promise<TokenBucket | null>;
+    set(key: string, value: TokenBucket, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear?(): Promise<void>;
+}
+/**
+ * In-memory storage implementation
+ */
+export declare class InMemoryRateLimitStorage implements RateLimitStorage {
+    private store;
+    private cleanupInterval;
+    constructor(cleanupIntervalMs?: number);
+    get(key: string): Promise<TokenBucket | null>;
+    set(key: string, value: TokenBucket, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Clean up expired entries
+     */
+    private cleanup;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+    /**
+     * Get storage stats (for testing/monitoring)
+     */
+    getStats(): {
+        size: number;
+        keys: string[];
+    };
+}
+/**
+ * Rate Limiter using Token Bucket Algorithm
+ *
+ * The token bucket algorithm allows for burst traffic while maintaining
+ * a steady long-term rate. Each request consumes a token from the bucket.
+ * Tokens are refilled at a constant rate.
+ *
+ * @example
+ * ```typescript
+ * // Create rate limiter: 100 requests per minute
+ * const limiter = new RateLimiter({
+ *   maxTokens: 100,
+ *   refillRate: 100 / 60, // ~1.67 tokens/sec
+ *   windowMs: 60000,
+ * })
+ *
+ * // Check if request is allowed
+ * const result = await limiter.checkLimit('user:123')
+ * if (result.allowed) {
+ *   // Process request
+ * } else {
+ *   // Return 429 Too Many Requests
+ *   // Retry after: result.retryAfterMs
+ * }
+ * ```
+ */
+export declare class RateLimiter {
+    private readonly config;
+    private readonly storage;
+    private readonly metrics;
+    /** Queue of waiting requests per key (SMI-1013) */
+    private readonly queues;
+    /** Timer for processing queues (SMI-1013) */
+    private queueProcessorInterval;
+    /** Timer for cleaning up stale metrics */
+    private metricsCleanupInterval;
+    /** Lock for atomic token operations (prevents TOCTOU race conditions) */
+    private readonly operationLocks;
+    /** Flag to prevent concurrent queue processing */
+    private isProcessingQueues;
+    constructor(config: RateLimitConfig, storage?: RateLimitStorage);
+    /**
+     * Start the queue processor that periodically checks for available tokens (SMI-1013)
+     */
+    private startQueueProcessor;
+    /**
+     * Start periodic cleanup of stale metrics
+     */
+    private startMetricsCleanup;
+    /**
+     * Clean up metrics older than METRICS_TTL_MS
+     */
+    private cleanupStaleMetrics;
+    /**
+     * Acquire a lock for atomic operations on a key
+     */
+    private acquireLock;
+    /**
+     * Process all queues and release waiting requests when tokens become available (SMI-1013)
+     * Uses a flag to prevent concurrent processing
+     */
+    private processQueues;
+    /**
+     * Try to consume a token without queuing (internal method)
+     */
+    private tryConsumeToken;
+    /**
+     * Update metrics for a key with bounds checking
+     */
+    private updateMetrics;
+    /**
+     * Check if a request is allowed under rate limit
+     *
+     * @param key - Unique identifier (e.g., 'ip:192.168.1.1' or 'user:123')
+     * @param cost - Number of tokens to consume (default: 1)
+     * @returns Rate limit result
+     */
+    checkLimit(key: string, cost?: number): Promise<RateLimitResult>;
+    /**
+     * Wait for a token to become available (SMI-1013)
+     *
+     * If tokens are available, consumes immediately.
+     * If not, queues the request and waits until tokens become available or timeout.
+     *
+     * @param key - Unique identifier (e.g., 'ip:192.168.1.1' or 'adapter:github')
+     * @param cost - Number of tokens to consume (default: 1)
+     * @returns Promise that resolves when token is available
+     * @throws RateLimitQueueTimeoutError if timeout is exceeded
+     * @throws RateLimitQueueFullError if queue is at capacity
+     *
+     * @example
+     * ```typescript
+     * const limiter = new RateLimiter({
+     *   maxTokens: 10,
+     *   refillRate: 1,
+     *   windowMs: 60000,
+     *   enableQueue: true,
+     *   queueTimeoutMs: 30000,
+     * })
+     *
+     * // Will wait up to 30s for token
+     * const result = await limiter.waitForToken('adapter:github')
+     * if (result.queued) {
+     *   console.log(`Waited ${result.queueWaitMs}ms in queue`)
+     * }
+     * ```
+     */
+    waitForToken(key: string, cost?: number): Promise<RateLimitResult>;
+    /**
+     * Get queue status for a key (SMI-1013)
+     *
+     * @param key - Optional key to get queue status for
+     * @returns Queue size and waiting requests info
+     */
+    getQueueStatus(key?: string): {
+        totalQueued: number;
+        queues: Map<string, number>;
+    } | number;
+    /**
+     * Clear queue for a key (SMI-1013)
+     *
+     * Rejects all waiting requests with a timeout error.
+     *
+     * @param key - Optional key to clear queue for (clears all if not specified)
+     */
+    clearQueue(key?: string): void;
+    /**
+     * Reset rate limit for a key (e.g., after authentication)
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Get current state for a key (for monitoring/debugging)
+     */
+    getState(key: string): Promise<TokenBucket | null>;
+    /**
+     * Get metrics for a specific key or all keys
+     *
+     * @param key - Optional key to get metrics for
+     * @returns Metrics for the key, or all metrics if no key specified
+     */
+    getMetrics(key?: string): Map<string, RateLimitMetrics> | RateLimitMetrics | undefined;
+    /**
+     * Reset metrics for a specific key or all keys
+     *
+     * @param key - Optional key to reset metrics for
+     */
+    resetMetrics(key?: string): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+/**
+ * Preset rate limit configurations
+ */
+export declare const RATE_LIMIT_PRESETS: {
+    /** Very strict: 10 requests per minute, fail-closed for high security */
+    readonly STRICT: {
+        readonly maxTokens: 10;
+        readonly refillRate: number;
+        readonly windowMs: 60000;
+        readonly failMode: "closed";
+    };
+    /** Standard: 30 requests per minute (default for adapters) */
+    readonly STANDARD: {
+        readonly maxTokens: 30;
+        readonly refillRate: number;
+        readonly windowMs: 60000;
+        readonly failMode: "open";
+    };
+    /** Relaxed: 60 requests per minute */
+    readonly RELAXED: {
+        readonly maxTokens: 60;
+        readonly refillRate: number;
+        readonly windowMs: 60000;
+        readonly failMode: "open";
+    };
+    /** Generous: 120 requests per minute */
+    readonly GENEROUS: {
+        readonly maxTokens: 120;
+        readonly refillRate: number;
+        readonly windowMs: 60000;
+        readonly failMode: "open";
+    };
+    /** High throughput: 300 requests per minute */
+    readonly HIGH_THROUGHPUT: {
+        readonly maxTokens: 300;
+        readonly refillRate: number;
+        readonly windowMs: 60000;
+        readonly failMode: "open";
+    };
+};
+/**
+ * Create a rate limiter from a preset
+ */
+export declare function createRateLimiterFromPreset(preset: keyof typeof RATE_LIMIT_PRESETS, storage?: RateLimitStorage): RateLimiter;
+export {};
+//# sourceMappingURL=RateLimiter.d.ts.map

package/dist/src/security/RateLimiter.d.ts.map

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