claude-autopm 1.31.0 → 2.1.0

package/lib/utils/CircuitBreaker.js

@@ -0,0 +1,165 @@
+/**
+ * Circuit Breaker Implementation
+ *
+ * Implements the circuit breaker pattern to prevent cascading failures
+ * and allow systems to recover from transient faults.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Too many failures, reject requests immediately
+ * - HALF_OPEN: Testing recovery, allow limited requests
+ *
+ * State Transitions:
+ * CLOSED → OPEN: After failureThreshold consecutive failures
+ * OPEN → HALF_OPEN: After timeout expires
+ * HALF_OPEN → CLOSED: After successThreshold consecutive successes
+ * HALF_OPEN → OPEN: On any failure
+ *
+ * @example
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,    // Open after 5 consecutive failures
+ *   successThreshold: 2,    // Close after 2 consecutive successes
+ *   timeout: 60000,         // Wait 60s before trying again
+ *   halfOpenTimeout: 30000  // (unused, for future extensions)
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await apiCall();
+ *   });
+ * } catch (error) {
+ *   if (error.message === 'Circuit breaker is OPEN') {
+ *     // Circuit is open, service unavailable
+ *   }
+ * }
+ */
+
+/**
+ * Circuit breaker states
+ * @enum {string}
+ */
+const States = {
+  CLOSED: 'CLOSED',      // Normal operation
+  OPEN: 'OPEN',          // Failing, reject immediately
+  HALF_OPEN: 'HALF_OPEN' // Testing if recovered
+};
+
+/**
+ * Circuit Breaker class
+ */
+class CircuitBreaker {
+  /**
+   * Create a circuit breaker
+   *
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.failureThreshold=5] - Number of consecutive failures before opening
+   * @param {number} [options.successThreshold=2] - Number of consecutive successes to close from half-open
+   * @param {number} [options.timeout=60000] - Time in ms to wait before transitioning from OPEN to HALF_OPEN
+   * @param {number} [options.halfOpenTimeout=30000] - Reserved for future use
+   */
+  constructor(options = {}) {
+    // Configuration with defaults
+    this.failureThreshold = options.failureThreshold || 5;
+    this.successThreshold = options.successThreshold || 2;
+    this.timeout = options.timeout !== undefined ? options.timeout : 60000;
+    this.halfOpenTimeout = options.halfOpenTimeout || 30000;
+
+    // State tracking
+    this.state = States.CLOSED;
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.nextAttempt = Date.now(); // Time when we can retry after OPEN
+  }
+
+  /**
+   * Execute a function with circuit breaker protection
+   *
+   * @param {Function} fn - Async function to execute
+   * @returns {Promise<*>} Result of the function
+   * @throws {Error} Circuit breaker error or function error
+   */
+  async execute(fn) {
+    // Check if circuit is OPEN
+    if (this.state === States.OPEN) {
+      if (Date.now() < this.nextAttempt) {
+        // Still within timeout period, reject immediately
+        throw new Error('Circuit breaker is OPEN');
+      }
+      // Timeout expired, transition to HALF_OPEN
+      this.state = States.HALF_OPEN;
+    }
+
+    // Execute the function
+    try {
+      const result = await fn();
+      this._onSuccess();
+      return result;
+    } catch (error) {
+      this._onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Handle successful execution
+   * @private
+   */
+  _onSuccess() {
+    // Reset failure count on any success
+    this.failureCount = 0;
+
+    if (this.state === States.HALF_OPEN) {
+      // In HALF_OPEN state, count successes
+      this.successCount++;
+
+      // If we've reached the success threshold, close the circuit
+      if (this.successCount >= this.successThreshold) {
+        this.state = States.CLOSED;
+        this.successCount = 0;
+      }
+    }
+    // In CLOSED state, success count is not tracked (stays 0)
+  }
+
+  /**
+   * Handle failed execution
+   * @private
+   */
+  _onFailure() {
+    // Reset success count on any failure
+    this.successCount = 0;
+
+    // Increment failure count (only in CLOSED or HALF_OPEN)
+    if (this.state !== States.OPEN) {
+      this.failureCount++;
+    }
+
+    // Check if we should open the circuit
+    if (this.failureCount >= this.failureThreshold) {
+      this.state = States.OPEN;
+      this.nextAttempt = Date.now() + this.timeout;
+    }
+  }
+
+  /**
+   * Reset circuit breaker to initial state
+   * Useful for manual recovery or testing
+   */
+  reset() {
+    this.state = States.CLOSED;
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.nextAttempt = Date.now();
+  }
+
+  /**
+   * Get current circuit breaker state
+   *
+   * @returns {string} Current state (CLOSED, OPEN, or HALF_OPEN)
+   */
+  getState() {
+    return this.state;
+  }
+}
+
+module.exports = { CircuitBreaker, States };

package/lib/utils/Encryption.js

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Encryption utility for secure API key storage
+ * Implements AES-256-CBC encryption with PBKDF2 key derivation
+ *
+ * Based on Context7 documentation patterns:
+ * - node-config: Hierarchical configuration patterns
+ * - Node.js crypto: AES-256-CBC, PBKDF2, scrypt for encryption
+ *
+ * @example
+ * const encryption = new Encryption();
+ * const encrypted = encryption.encrypt('my-api-key', 'password');
+ * const decrypted = encryption.decrypt(encrypted, 'password');
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Encryption utility class for API keys and sensitive data
+ */
+class Encryption {
+  constructor() {
+    // Algorithm configuration
+    this.algorithm = 'aes-256-cbc';
+    this.keyLength = 32; // 256 bits
+    this.ivLength = 16; // 128 bits
+    this.saltLength = 32; // 256 bits
+    this.iterations = 100000; // PBKDF2 iterations
+    this.digest = 'sha512';
+  }
+
+  /**
+   * Generate cryptographically secure random salt
+   *
+   * @returns {Buffer} Random salt buffer (32 bytes)
+   */
+  generateSalt() {
+    return crypto.randomBytes(this.saltLength);
+  }
+
+  /**
+   * Generate cryptographically secure random IV
+   *
+   * @returns {Buffer} Random IV buffer (16 bytes)
+   */
+  generateIV() {
+    return crypto.randomBytes(this.ivLength);
+  }
+
+  /**
+   * Derive encryption key from password using PBKDF2
+   *
+   * @param {string} password - Master password
+   * @param {Buffer} salt - Salt for key derivation
+   * @returns {Buffer} Derived key (32 bytes)
+   * @throws {Error} If password or salt is invalid
+   */
+  deriveKey(password, salt) {
+    // Validate inputs
+    if (!password || typeof password !== 'string' || password.length === 0) {
+      throw new Error('Password is required');
+    }
+
+    if (!Buffer.isBuffer(salt)) {
+      throw new Error('Salt must be a Buffer');
+    }
+
+    // Derive key using PBKDF2
+    return crypto.pbkdf2Sync(
+      password,
+      salt,
+      this.iterations,
+      this.keyLength,
+      this.digest
+    );
+  }
+
+  /**
+   * Encrypt plaintext using AES-256-CBC
+   *
+   * @param {string} plaintext - Data to encrypt
+   * @param {string} password - Master password
+   * @returns {Object} Encrypted data object
+   * @returns {string} returns.encrypted - Base64-encoded encrypted data
+   * @returns {string} returns.iv - Base64-encoded IV
+   * @returns {string} returns.salt - Base64-encoded salt
+   * @returns {string} returns.algorithm - Encryption algorithm used
+   * @throws {Error} If plaintext or password is invalid
+   *
+   * @example
+   * const result = encryption.encrypt('my-api-key', 'password');
+   * // {
+   * //   encrypted: 'base64string',
+   * //   iv: 'base64string',
+   * //   salt: 'base64string',
+   * //   algorithm: 'aes-256-cbc'
+   * // }
+   */
+  encrypt(plaintext, password) {
+    // Validate inputs
+    if (plaintext === null || plaintext === undefined) {
+      throw new Error('Plaintext is required');
+    }
+
+    if (!password || typeof password !== 'string' || password.length === 0) {
+      throw new Error('Password is required');
+    }
+
+    // Convert plaintext to string if needed
+    const plaintextStr = String(plaintext);
+
+    // Generate random salt and IV
+    const salt = this.generateSalt();
+    const iv = this.generateIV();
+
+    // Derive key from password
+    const key = this.deriveKey(password, salt);
+
+    // Create cipher
+    const cipher = crypto.createCipheriv(this.algorithm, key, iv);
+
+    // Encrypt data
+    let encrypted = cipher.update(plaintextStr, 'utf8', 'base64');
+    encrypted += cipher.final('base64');
+
+    // Return encrypted data object
+    return {
+      encrypted,
+      iv: iv.toString('base64'),
+      salt: salt.toString('base64'),
+      algorithm: this.algorithm
+    };
+  }
+
+  /**
+   * Decrypt encrypted data using AES-256-CBC
+   *
+   * @param {Object} encryptedData - Encrypted data object from encrypt()
+   * @param {string} encryptedData.encrypted - Base64-encoded encrypted data
+   * @param {string} encryptedData.iv - Base64-encoded IV
+   * @param {string} encryptedData.salt - Base64-encoded salt
+   * @param {string} encryptedData.algorithm - Encryption algorithm
+   * @param {string} password - Master password
+   * @returns {string} Decrypted plaintext
+   * @throws {Error} If data is invalid or password is wrong
+   *
+   * @example
+   * const decrypted = encryption.decrypt(encryptedData, 'password');
+   */
+  decrypt(encryptedData, password) {
+    // Validate inputs
+    if (!encryptedData || typeof encryptedData !== 'object') {
+      throw new Error('Encrypted data must be an object');
+    }
+
+    if (!encryptedData.encrypted) {
+      throw new Error('Encrypted data is required');
+    }
+
+    if (!encryptedData.iv) {
+      throw new Error('IV is required');
+    }
+
+    if (!encryptedData.salt) {
+      throw new Error('Salt is required');
+    }
+
+    if (!encryptedData.algorithm || encryptedData.algorithm !== this.algorithm) {
+      throw new Error('Invalid algorithm');
+    }
+
+    if (!password || typeof password !== 'string' || password.length === 0) {
+      throw new Error('Password is required');
+    }
+
+    try {
+      // Parse base64-encoded values
+      const salt = Buffer.from(encryptedData.salt, 'base64');
+      const iv = Buffer.from(encryptedData.iv, 'base64');
+
+      // Derive key from password
+      const key = this.deriveKey(password, salt);
+
+      // Create decipher
+      const decipher = crypto.createDecipheriv(this.algorithm, key, iv);
+
+      // Decrypt data
+      let decrypted = decipher.update(encryptedData.encrypted, 'base64', 'utf8');
+      decrypted += decipher.final('utf8');
+
+      return decrypted;
+    } catch (error) {
+      // Don't leak password in error messages
+      if (error.message.includes('bad decrypt')) {
+        throw new Error('Decryption failed - wrong password or corrupted data');
+      }
+      throw error;
+    }
+  }
+}
+
+module.exports = Encryption;

package/lib/utils/RateLimiter.js

@@ -0,0 +1,241 @@
+/**
+ * RateLimiter
+ *
+ * Token Bucket Algorithm implementation for rate limiting.
+ *
+ * Features:
+ * - Token bucket with configurable capacity
+ * - Multiple time windows (second, minute, hour, day)
+ * - Burst support (bucket size > rate)
+ * - Async wait or immediate failure modes
+ * - In-memory storage (no dependencies)
+ * - High precision (millisecond accuracy)
+ *
+ * Usage:
+ *   const limiter = new RateLimiter({
+ *     tokensPerInterval: 60,
+ *     interval: 'minute',
+ *     bucketSize: 100  // Allow burst
+ *   });
+ *
+ *   // Async - waits if needed
+ *   await limiter.removeTokens(1);
+ *
+ *   // Sync - immediate response
+ *   if (limiter.tryRemoveTokens(1)) {
+ *     // proceed
+ *   }
+ *
+ *   // fireImmediately mode for HTTP 429
+ *   const limiter2 = new RateLimiter({
+ *     tokensPerInterval: 100,
+ *     interval: 'hour',
+ *     fireImmediately: true
+ *   });
+ *
+ *   const remaining = await limiter2.removeTokens(1);
+ *   if (remaining < 0) {
+ *     res.status(429).send('Rate limit exceeded');
+ *   }
+ */
+
+class RateLimiter {
+  /**
+   * Create a new RateLimiter
+   *
+   * @param {Object} options - Configuration options
+   * @param {number} options.tokensPerInterval - Number of tokens to add per interval (default: 60)
+   * @param {string|number} options.interval - Time interval ('second', 'minute', 'hour', 'day') or milliseconds (default: 'minute')
+   * @param {number} options.bucketSize - Maximum tokens in bucket (default: tokensPerInterval)
+   * @param {boolean} options.fireImmediately - Don't wait, return negative on exceeded (default: false)
+   */
+  constructor(options = {}) {
+    // Validate and set tokensPerInterval
+    this.tokensPerInterval = options.tokensPerInterval !== undefined
+      ? options.tokensPerInterval
+      : 60;
+
+    if (typeof this.tokensPerInterval !== 'number' || this.tokensPerInterval <= 0) {
+      throw new Error('tokensPerInterval must be greater than 0');
+    }
+
+    // Parse and validate interval
+    this.interval = this._parseInterval(
+      options.interval !== undefined ? options.interval : 'minute'
+    );
+
+    if (typeof this.interval !== 'number' || this.interval <= 0) {
+      throw new Error('interval must be greater than 0');
+    }
+
+    // Validate and set bucket size
+    this.bucketSize = options.bucketSize !== undefined
+      ? options.bucketSize
+      : this.tokensPerInterval;
+
+    if (typeof this.bucketSize !== 'number' || this.bucketSize <= 0) {
+      throw new Error('bucketSize must be greater than 0');
+    }
+
+    // Set fireImmediately mode
+    this.fireImmediately = options.fireImmediately === true;
+
+    // Initialize token bucket
+    this.tokens = this.bucketSize;
+    this.lastRefill = Date.now();
+  }
+
+  /**
+   * Remove tokens from the bucket (async)
+   *
+   * Waits if insufficient tokens (unless fireImmediately=true)
+   *
+   * @param {number} count - Number of tokens to remove (default: 1)
+   * @returns {Promise<number>} Remaining tokens after removal
+   * @throws {Error} If count exceeds bucket size
+   */
+  async removeTokens(count = 1) {
+    // fireImmediately mode: allow any count, can go negative
+    if (!this.fireImmediately && count > this.bucketSize) {
+      throw new Error(`Requested ${count} tokens exceeds bucket size ${this.bucketSize}`);
+    }
+
+    // Refill tokens based on time passed
+    this._refill();
+
+    // fireImmediately mode: return immediately, even if negative
+    if (this.fireImmediately) {
+      this.tokens -= count;
+      return this.tokens;
+    }
+
+    // Wait mode: wait until sufficient tokens available
+    while (this.tokens < count) {
+      const tokensNeeded = count - this.tokens;
+      const timeToWait = (tokensNeeded / this.tokensPerInterval) * this.interval;
+
+      await this._delay(timeToWait);
+      this._refill();
+    }
+
+    this.tokens -= count;
+    return this.tokens;
+  }
+
+  /**
+   * Try to remove tokens (sync, non-blocking)
+   *
+   * Returns immediately without waiting
+   *
+   * @param {number} count - Number of tokens to remove (default: 1)
+   * @returns {boolean} True if tokens were removed, false if insufficient
+   */
+  tryRemoveTokens(count = 1) {
+    this._refill();
+
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get current number of tokens available
+   *
+   * @returns {number} Available tokens
+   */
+  getTokensRemaining() {
+    return this.tokens;
+  }
+
+  /**
+   * Reset the rate limiter to initial state
+   *
+   * Refills bucket to capacity and resets timer
+   */
+  reset() {
+    this.tokens = this.bucketSize;
+    this.lastRefill = Date.now();
+  }
+
+  /**
+   * Refill tokens based on time passed
+   *
+   * Uses token bucket algorithm:
+   * - Calculate time since last refill
+   * - Add tokens proportional to time passed
+   * - Cap at bucket size
+   *
+   * @private
+   */
+  _refill() {
+    const now = Date.now();
+    const timePassed = now - this.lastRefill;
+
+    if (timePassed <= 0) {
+      return; // No time passed, no refill
+    }
+
+    // Calculate tokens to add based on time passed
+    const tokensToAdd = (timePassed / this.interval) * this.tokensPerInterval;
+
+    // Add tokens up to bucket size
+    this.tokens = Math.min(this.bucketSize, this.tokens + tokensToAdd);
+
+    // Update last refill time
+    this.lastRefill = now;
+  }
+
+  /**
+   * Parse interval string to milliseconds
+   *
+   * Supports: 'second', 'minute', 'hour', 'day' (case insensitive, with/without 's')
+   * Also accepts numeric milliseconds
+   *
+   * @param {string|number} interval - Interval to parse
+   * @returns {number} Interval in milliseconds
+   * @throws {Error} If interval is invalid
+   * @private
+   */
+  _parseInterval(interval) {
+    // If already a number, return as-is
+    if (typeof interval === 'number') {
+      return interval;
+    }
+
+    // String parsing (case insensitive)
+    if (typeof interval === 'string') {
+      const normalized = interval.toLowerCase().replace(/s$/, ''); // Remove trailing 's'
+
+      switch (normalized) {
+        case 'second':
+          return 1000;
+        case 'minute':
+          return 60000;
+        case 'hour':
+          return 3600000;
+        case 'day':
+          return 86400000;
+        default:
+          throw new Error(`Invalid interval: ${interval}`);
+      }
+    }
+
+    throw new Error(`Invalid interval: ${interval}`);
+  }
+
+  /**
+   * Delay execution for specified milliseconds
+   *
+   * @param {number} ms - Milliseconds to delay
+   * @returns {Promise<void>}
+   * @private
+   */
+  _delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = RateLimiter;