@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/utils/RateLimiter.d.ts

@@ -0,0 +1,253 @@
+/**
+ * RateLimiter - Prevents excessive API/RPC calls
+ *
+ * SECURITY FIX (M-4): Rate limiting to prevent:
+ * - API rate limit exhaustion
+ * - Self-inflicted DoS
+ * - Excessive RPC costs
+ *
+ * @module utils/RateLimiter
+ */
+/**
+ * Rate limiter configuration
+ */
+export interface RateLimiterConfig {
+    /** Maximum requests per window */
+    maxRequests: number;
+    /** Time window in milliseconds */
+    windowMs: number;
+    /** Optional: Burst allowance (extra requests allowed briefly) */
+    burstAllowance?: number;
+}
+/**
+ * Rate limiter result
+ */
+export interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Remaining requests in current window */
+    remaining: number;
+    /** Time until window resets (ms) */
+    resetIn: number;
+    /** Suggested retry delay if not allowed */
+    retryAfter?: number;
+}
+/**
+ * Simple sliding window rate limiter
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({ maxRequests: 10, windowMs: 1000 });
+ *
+ * const result = limiter.tryAcquire();
+ * if (!result.allowed) {
+ *   console.log(`Rate limited. Retry after ${result.retryAfter}ms`);
+ * }
+ * ```
+ */
+export declare class RateLimiter {
+    private timestamps;
+    private readonly config;
+    constructor(config: RateLimiterConfig);
+    /**
+     * Try to acquire a rate limit slot
+     *
+     * @returns Rate limit result
+     */
+    tryAcquire(): RateLimitResult;
+    /**
+     * Wait until rate limit allows request
+     *
+     * @returns Promise that resolves when request is allowed
+     */
+    acquire(): Promise<void>;
+    /**
+     * Get current rate limit status
+     */
+    getStatus(): {
+        used: number;
+        remaining: number;
+        resetIn: number;
+    };
+    /**
+     * Reset the rate limiter
+     */
+    reset(): void;
+}
+/**
+ * Circuit breaker states
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time to wait before trying again (ms) */
+    recoveryTimeout: number;
+    /** Number of successes in half-open needed to close circuit */
+    successThreshold?: number;
+    /** SECURITY FIX (MEDIUM-5): Timeout for half-open test (ms). If no result reported, auto-reset. Default: 30000 */
+    halfOpenTestTimeout?: number;
+}
+/**
+ * Circuit breaker result
+ */
+export interface CircuitBreakerResult {
+    /** Whether the operation is allowed */
+    allowed: boolean;
+    /** Current circuit state */
+    state: CircuitState;
+    /** Number of consecutive failures */
+    failures: number;
+}
+/**
+ * Circuit Breaker - Prevents cascading failures
+ *
+ * SECURITY FIX (M-5): Circuit breaker to:
+ * - Prevent repeated calls to failing services
+ * - Allow systems to recover
+ * - Provide graceful degradation
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped, requests fail fast
+ * - HALF-OPEN: Testing if service recovered
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   recoveryTimeout: 30000
+ * });
+ *
+ * async function callService() {
+ *   const result = breaker.canExecute();
+ *   if (!result.allowed) {
+ *     throw new Error(`Circuit open. Try again later.`);
+ *   }
+ *
+ *   try {
+ *     const response = await riskyOperation();
+ *     breaker.recordSuccess();
+ *     return response;
+ *   } catch (error) {
+ *     breaker.recordFailure();
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private readonly config;
+    private halfOpenTestInProgress;
+    private halfOpenTestStartTime;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Check if operation can be executed
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): In half-open state, only allow ONE request
+     * at a time to prevent overwhelming a recovering service.
+     */
+    canExecute(): CircuitBreakerResult;
+    /**
+     * Record a successful operation
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): Clears test-in-progress flag
+     * SECURITY FIX (MEDIUM-5): Clears test start time
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed operation
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): Clears test-in-progress flag
+     * SECURITY FIX (MEDIUM-5): Clears test start time
+     */
+    recordFailure(): void;
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Get detailed status
+     */
+    getStatus(): {
+        state: CircuitState;
+        failures: number;
+        timeSinceLastFailure: number;
+        recoveryTimeRemaining: number;
+    };
+    /**
+     * Manually reset the circuit breaker
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): Also clears test-in-progress flag
+     * SECURITY FIX (MEDIUM-5): Also clears test start time
+     */
+    reset(): void;
+    /**
+     * Execute a function with circuit breaker protection
+     *
+     * @param fn - Async function to execute
+     * @returns Function result or throws if circuit is open
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Combined rate limiter and circuit breaker for API protection
+ *
+ * @example
+ * ```typescript
+ * const protector = new APIProtector({
+ *   rateLimiter: { maxRequests: 100, windowMs: 60000 },
+ *   circuitBreaker: { failureThreshold: 5, recoveryTimeout: 30000 }
+ * });
+ *
+ * const result = await protector.execute(async () => {
+ *   return await apiCall();
+ * });
+ * ```
+ */
+export declare class APIProtector {
+    private readonly rateLimiter;
+    private readonly circuitBreaker;
+    constructor(config: {
+        rateLimiter: RateLimiterConfig;
+        circuitBreaker: CircuitBreakerConfig;
+    });
+    /**
+     * Check if operation is allowed (both rate limit and circuit)
+     */
+    canExecute(): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Execute with both rate limiting and circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get combined status
+     */
+    getStatus(): {
+        rateLimiter: ReturnType<RateLimiter['getStatus']>;
+        circuitBreaker: ReturnType<CircuitBreaker['getStatus']>;
+    };
+    /**
+     * Record success (for circuit breaker)
+     */
+    recordSuccess(): void;
+    /**
+     * Record failure (for circuit breaker)
+     */
+    recordFailure(): void;
+    /**
+     * Reset both protections
+     */
+    reset(): void;
+}
+//# sourceMappingURL=RateLimiter.d.ts.map

package/dist/utils/RateLimiter.d.ts.map

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

package/dist/utils/RateLimiter.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * RateLimiter - Prevents excessive API/RPC calls
+ *
+ * SECURITY FIX (M-4): Rate limiting to prevent:
+ * - API rate limit exhaustion
+ * - Self-inflicted DoS
+ * - Excessive RPC costs
+ *
+ * @module utils/RateLimiter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIProtector = exports.CircuitBreaker = exports.RateLimiter = void 0;
+/**
+ * Simple sliding window rate limiter
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({ maxRequests: 10, windowMs: 1000 });
+ *
+ * const result = limiter.tryAcquire();
+ * if (!result.allowed) {
+ *   console.log(`Rate limited. Retry after ${result.retryAfter}ms`);
+ * }
+ * ```
+ */
+class RateLimiter {
+    constructor(config) {
+        this.timestamps = [];
+        this.config = {
+            maxRequests: config.maxRequests,
+            windowMs: config.windowMs,
+            burstAllowance: config.burstAllowance ?? 0,
+        };
+    }
+    /**
+     * Try to acquire a rate limit slot
+     *
+     * @returns Rate limit result
+     */
+    tryAcquire() {
+        const now = Date.now();
+        const windowStart = now - this.config.windowMs;
+        // Remove expired timestamps
+        this.timestamps = this.timestamps.filter((ts) => ts > windowStart);
+        const effectiveLimit = this.config.maxRequests + this.config.burstAllowance;
+        if (this.timestamps.length < effectiveLimit) {
+            this.timestamps.push(now);
+            return {
+                allowed: true,
+                remaining: effectiveLimit - this.timestamps.length,
+                resetIn: this.timestamps.length > 0
+                    ? this.timestamps[0] + this.config.windowMs - now
+                    : this.config.windowMs,
+            };
+        }
+        // Rate limited
+        const oldestTimestamp = this.timestamps[0];
+        const retryAfter = oldestTimestamp + this.config.windowMs - now;
+        return {
+            allowed: false,
+            remaining: 0,
+            resetIn: retryAfter,
+            retryAfter: Math.max(0, retryAfter),
+        };
+    }
+    /**
+     * Wait until rate limit allows request
+     *
+     * @returns Promise that resolves when request is allowed
+     */
+    async acquire() {
+        const result = this.tryAcquire();
+        if (result.allowed) {
+            return;
+        }
+        // Wait and retry
+        await new Promise((resolve) => setTimeout(resolve, result.retryAfter));
+        return this.acquire();
+    }
+    /**
+     * Get current rate limit status
+     */
+    getStatus() {
+        const now = Date.now();
+        const windowStart = now - this.config.windowMs;
+        // Clean up expired timestamps
+        this.timestamps = this.timestamps.filter((ts) => ts > windowStart);
+        const effectiveLimit = this.config.maxRequests + this.config.burstAllowance;
+        const used = this.timestamps.length;
+        const remaining = Math.max(0, effectiveLimit - used);
+        const resetIn = this.timestamps.length > 0
+            ? this.timestamps[0] + this.config.windowMs - now
+            : this.config.windowMs;
+        return { used, remaining, resetIn };
+    }
+    /**
+     * Reset the rate limiter
+     */
+    reset() {
+        this.timestamps = [];
+    }
+}
+exports.RateLimiter = RateLimiter;
+/**
+ * Circuit Breaker - Prevents cascading failures
+ *
+ * SECURITY FIX (M-5): Circuit breaker to:
+ * - Prevent repeated calls to failing services
+ * - Allow systems to recover
+ * - Provide graceful degradation
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped, requests fail fast
+ * - HALF-OPEN: Testing if service recovered
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   recoveryTimeout: 30000
+ * });
+ *
+ * async function callService() {
+ *   const result = breaker.canExecute();
+ *   if (!result.allowed) {
+ *     throw new Error(`Circuit open. Try again later.`);
+ *   }
+ *
+ *   try {
+ *     const response = await riskyOperation();
+ *     breaker.recordSuccess();
+ *     return response;
+ *   } catch (error) {
+ *     breaker.recordFailure();
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+class CircuitBreaker {
+    constructor(config) {
+        this.state = 'closed';
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureTime = 0;
+        // SECURITY FIX (CIRCUIT-HALFOPEN): Track if a test request is in progress
+        // Half-open state should only allow ONE request at a time to test service recovery
+        this.halfOpenTestInProgress = false;
+        // SECURITY FIX (MEDIUM-5): Track when half-open test started for timeout detection
+        this.halfOpenTestStartTime = 0;
+        this.config = {
+            failureThreshold: config.failureThreshold,
+            recoveryTimeout: config.recoveryTimeout,
+            successThreshold: config.successThreshold ?? 1,
+            // SECURITY FIX (MEDIUM-5): Default 30 second timeout for half-open tests
+            halfOpenTestTimeout: config.halfOpenTestTimeout ?? 30000,
+        };
+    }
+    /**
+     * Check if operation can be executed
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): In half-open state, only allow ONE request
+     * at a time to prevent overwhelming a recovering service.
+     */
+    canExecute() {
+        const now = Date.now();
+        switch (this.state) {
+            case 'closed':
+                return {
+                    allowed: true,
+                    state: this.state,
+                    failures: this.failures,
+                };
+            case 'open':
+                // Check if recovery timeout has passed
+                if (now - this.lastFailureTime >= this.config.recoveryTimeout) {
+                    this.state = 'half-open';
+                    this.successes = 0;
+                    // SECURITY FIX (HIGH-7): Removed duplicate assignment (was setting false then true)
+                    // SECURITY FIX (CIRCUIT-HALFOPEN): Mark test as in progress for first allowed request
+                    this.halfOpenTestInProgress = true;
+                    // SECURITY FIX (MEDIUM-5): Record when test started for timeout detection
+                    this.halfOpenTestStartTime = now;
+                    return {
+                        allowed: true,
+                        state: this.state,
+                        failures: this.failures,
+                    };
+                }
+                return {
+                    allowed: false,
+                    state: this.state,
+                    failures: this.failures,
+                };
+            case 'half-open':
+                // SECURITY FIX (MEDIUM-5): Check if test has timed out (caller never reported result)
+                // This prevents the circuit breaker from getting stuck if caller crashes/forgets to report
+                if (this.halfOpenTestInProgress && this.halfOpenTestStartTime > 0) {
+                    const testDuration = now - this.halfOpenTestStartTime;
+                    if (testDuration >= this.config.halfOpenTestTimeout) {
+                        // Timeout: reset the test flag and allow a new test
+                        this.halfOpenTestInProgress = false;
+                        this.halfOpenTestStartTime = 0;
+                    }
+                }
+                // SECURITY FIX (CIRCUIT-HALFOPEN): Only allow if no test is in progress
+                // This prevents multiple concurrent requests from overwhelming a recovering service
+                if (this.halfOpenTestInProgress) {
+                    return {
+                        allowed: false,
+                        state: this.state,
+                        failures: this.failures,
+                    };
+                }
+                // Mark test as in progress
+                this.halfOpenTestInProgress = true;
+                // SECURITY FIX (MEDIUM-5): Record when test started
+                this.halfOpenTestStartTime = now;
+                return {
+                    allowed: true,
+                    state: this.state,
+                    failures: this.failures,
+                };
+        }
+    }
+    /**
+     * Record a successful operation
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): Clears test-in-progress flag
+     * SECURITY FIX (MEDIUM-5): Clears test start time
+     */
+    recordSuccess() {
+        if (this.state === 'half-open') {
+            // SECURITY FIX (CIRCUIT-HALFOPEN): Clear test flag
+            this.halfOpenTestInProgress = false;
+            // SECURITY FIX (MEDIUM-5): Clear test start time
+            this.halfOpenTestStartTime = 0;
+            this.successes++;
+            if (this.successes >= this.config.successThreshold) {
+                this.state = 'closed';
+                this.failures = 0;
+                this.successes = 0;
+            }
+        }
+        else if (this.state === 'closed') {
+            // Reset failure count on success
+            this.failures = 0;
+        }
+    }
+    /**
+     * Record a failed operation
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): Clears test-in-progress flag
+     * SECURITY FIX (MEDIUM-5): Clears test start time
+     */
+    recordFailure() {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        if (this.state === 'half-open') {
+            // SECURITY FIX (CIRCUIT-HALFOPEN): Clear test flag before opening
+            this.halfOpenTestInProgress = false;
+            // SECURITY FIX (MEDIUM-5): Clear test start time
+            this.halfOpenTestStartTime = 0;
+            // Immediately open on failure in half-open state
+            this.state = 'open';
+        }
+        else if (this.state === 'closed' && this.failures >= this.config.failureThreshold) {
+            this.state = 'open';
+        }
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        // Check for automatic transition from open to half-open
+        if (this.state === 'open') {
+            const now = Date.now();
+            if (now - this.lastFailureTime >= this.config.recoveryTimeout) {
+                this.state = 'half-open';
+                this.successes = 0;
+            }
+        }
+        return this.state;
+    }
+    /**
+     * Get detailed status
+     */
+    getStatus() {
+        const now = Date.now();
+        const timeSinceLastFailure = this.lastFailureTime > 0
+            ? now - this.lastFailureTime
+            : 0;
+        const recoveryTimeRemaining = this.state === 'open'
+            ? Math.max(0, this.config.recoveryTimeout - timeSinceLastFailure)
+            : 0;
+        return {
+            state: this.getState(),
+            failures: this.failures,
+            timeSinceLastFailure,
+            recoveryTimeRemaining,
+        };
+    }
+    /**
+     * Manually reset the circuit breaker
+     *
+     * SECURITY FIX (CIRCUIT-HALFOPEN): Also clears test-in-progress flag
+     * SECURITY FIX (MEDIUM-5): Also clears test start time
+     */
+    reset() {
+        this.state = 'closed';
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureTime = 0;
+        this.halfOpenTestInProgress = false;
+        this.halfOpenTestStartTime = 0;
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     *
+     * @param fn - Async function to execute
+     * @returns Function result or throws if circuit is open
+     */
+    async execute(fn) {
+        const result = this.canExecute();
+        if (!result.allowed) {
+            throw new Error(`Circuit breaker is open (${this.failures} failures). ` +
+                `Recovery in ${this.getStatus().recoveryTimeRemaining}ms.`);
+        }
+        try {
+            const response = await fn();
+            this.recordSuccess();
+            return response;
+        }
+        catch (error) {
+            this.recordFailure();
+            throw error;
+        }
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+/**
+ * Combined rate limiter and circuit breaker for API protection
+ *
+ * @example
+ * ```typescript
+ * const protector = new APIProtector({
+ *   rateLimiter: { maxRequests: 100, windowMs: 60000 },
+ *   circuitBreaker: { failureThreshold: 5, recoveryTimeout: 30000 }
+ * });
+ *
+ * const result = await protector.execute(async () => {
+ *   return await apiCall();
+ * });
+ * ```
+ */
+class APIProtector {
+    constructor(config) {
+        this.rateLimiter = new RateLimiter(config.rateLimiter);
+        this.circuitBreaker = new CircuitBreaker(config.circuitBreaker);
+    }
+    /**
+     * Check if operation is allowed (both rate limit and circuit)
+     */
+    canExecute() {
+        // Check circuit breaker first
+        const circuitResult = this.circuitBreaker.canExecute();
+        if (!circuitResult.allowed) {
+            return {
+                allowed: false,
+                reason: `Circuit breaker open (${circuitResult.failures} failures)`,
+            };
+        }
+        // Check rate limiter
+        const rateResult = this.rateLimiter.tryAcquire();
+        if (!rateResult.allowed) {
+            return {
+                allowed: false,
+                reason: `Rate limited. Retry after ${rateResult.retryAfter}ms`,
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Execute with both rate limiting and circuit breaker protection
+     */
+    async execute(fn) {
+        // Wait for rate limit
+        await this.rateLimiter.acquire();
+        // Execute with circuit breaker
+        return this.circuitBreaker.execute(fn);
+    }
+    /**
+     * Get combined status
+     */
+    getStatus() {
+        return {
+            rateLimiter: this.rateLimiter.getStatus(),
+            circuitBreaker: this.circuitBreaker.getStatus(),
+        };
+    }
+    /**
+     * Record success (for circuit breaker)
+     */
+    recordSuccess() {
+        this.circuitBreaker.recordSuccess();
+    }
+    /**
+     * Record failure (for circuit breaker)
+     */
+    recordFailure() {
+        this.circuitBreaker.recordFailure();
+    }
+    /**
+     * Reset both protections
+     */
+    reset() {
+        this.rateLimiter.reset();
+        this.circuitBreaker.reset();
+    }
+}
+exports.APIProtector = APIProtector;
+//# sourceMappingURL=RateLimiter.js.map

package/dist/utils/RateLimiter.js.map

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