@dotdo/postgres 0.1.0

package/src/worker/auth-rate-limiter.ts

@@ -0,0 +1,448 @@
+/**
+ * Authentication Rate Limiter Module
+ *
+ * Provides rate limiting specifically for authentication failures to prevent
+ * brute force and credential stuffing attacks.
+ *
+ * Features:
+ * - Sliding window rate limiting per token prefix
+ * - Exponential backoff for repeated failures
+ * - Memory-bounded storage with LRU-style eviction
+ * - Lazy cleanup to work well with Cloudflare Workers
+ *
+ * @module @dotdo/postgres/worker/auth-rate-limiter
+ *
+ * @example
+ * ```typescript
+ * import { AuthRateLimiter } from './auth-rate-limiter'
+ *
+ * const rateLimiter = new AuthRateLimiter()
+ *
+ * // Check if request should be rate limited
+ * if (rateLimiter.isRateLimited(tokenPrefix)) {
+ *   return new Response('Too many attempts', { status: 429 })
+ * }
+ *
+ * // Record a failure after failed authentication
+ * rateLimiter.recordFailure(tokenPrefix)
+ * ```
+ */
+
+// ============================================================================
+// Configuration Constants
+// ============================================================================
+
+/**
+ * Default configuration for authentication rate limiting.
+ * These values balance security with usability.
+ */
+export interface AuthRateLimiterConfig {
+  /**
+   * Time window for rate limiting in milliseconds.
+   * @default 60000 (1 minute)
+   */
+  windowMs: number
+
+  /**
+   * Maximum authentication failures allowed per rate limit window.
+   * @default 10
+   */
+  maxFailures: number
+
+  /**
+   * Maximum number of rate limit entries to store in memory.
+   * Prevents memory exhaustion attacks.
+   * @default 10000
+   */
+  maxEntries: number
+
+  /**
+   * Interval for cleaning up expired rate limit entries in milliseconds.
+   * @default 300000 (5 minutes)
+   */
+  cleanupIntervalMs: number
+
+  /**
+   * Number of token characters used for rate limit key generation.
+   * @default 20
+   */
+  keyLength: number
+
+  /**
+   * Prefix for rate limit tracking keys.
+   * @default 'token:'
+   */
+  keyPrefix: string
+
+  /**
+   * Maximum exponential backoff power (caps at 2^maxBackoffPower seconds).
+   * @default 10 (caps at ~17 minutes)
+   */
+  maxBackoffPower: number
+}
+
+/**
+ * Default rate limiter configuration.
+ */
+export const DEFAULT_AUTH_RATE_LIMITER_CONFIG: Readonly<AuthRateLimiterConfig> = {
+  windowMs: 60000,
+  maxFailures: 10,
+  maxEntries: 10000,
+  cleanupIntervalMs: 300000,
+  keyLength: 20,
+  keyPrefix: 'token:',
+  maxBackoffPower: 10,
+} as const
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Tracks authentication failures within a sliding time window.
+ */
+export interface RateLimitEntry {
+  /** Number of failures in the current window */
+  count: number
+  /** Timestamp when the current window started */
+  windowStart: number
+  /** Timestamp of last failure attempt (for exponential backoff) */
+  lastAttempt: number
+}
+
+/**
+ * Statistics about the rate limiter state.
+ */
+export interface RateLimiterStats {
+  /** Current number of tracked entries */
+  size: number
+  /** Maximum allowed entries */
+  maxSize: number
+  /** Timestamp of last cleanup operation */
+  lastCleanupTime: number
+  /** Number of entries removed in last cleanup */
+  lastCleanupCount: number
+}
+
+// ============================================================================
+// AuthRateLimiter Class
+// ============================================================================
+
+/**
+ * Rate limiter for authentication failures.
+ *
+ * Implements a sliding window algorithm with exponential backoff to prevent
+ * brute force and credential stuffing attacks.
+ *
+ * @security This is a simple in-memory rate limiter. In production with
+ *           multiple Workers, consider using Durable Objects or external
+ *           storage for distributed rate limiting.
+ *
+ * Memory bounds:
+ * - Max entries: configurable (default 10,000)
+ * - Periodic cleanup: configurable (default every 5 minutes)
+ * - LRU-style eviction when at capacity
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = new AuthRateLimiter({
+ *   windowMs: 60000,     // 1 minute window
+ *   maxFailures: 5,      // 5 failures per window
+ *   maxEntries: 5000,    // Max 5000 tracked keys
+ * })
+ *
+ * // Generate key from token
+ * const key = rateLimiter.generateKey(token)
+ *
+ * // Check before processing authentication
+ * if (rateLimiter.isRateLimited(key)) {
+ *   return { error: 'RATE_LIMITED' }
+ * }
+ *
+ * // After failed authentication
+ * const isValid = await validateCredentials(...)
+ * if (!isValid) {
+ *   rateLimiter.recordFailure(key)
+ * }
+ * ```
+ */
+export class AuthRateLimiter {
+  private readonly config: AuthRateLimiterConfig
+  private readonly entries: Map<string, RateLimitEntry>
+  private lastCleanupTime: number
+  private lastCleanupCount: number
+
+  /**
+   * Creates a new AuthRateLimiter instance.
+   *
+   * @param config - Optional configuration overrides
+   */
+  constructor(config: Partial<AuthRateLimiterConfig> = {}) {
+    this.config = { ...DEFAULT_AUTH_RATE_LIMITER_CONFIG, ...config }
+    this.entries = new Map()
+    this.lastCleanupTime = Date.now()
+    this.lastCleanupCount = 0
+  }
+
+  /**
+   * Generates a rate limit key from a token.
+   *
+   * Uses the token prefix to identify unique tokens without storing
+   * full tokens in memory for rate limiting.
+   *
+   * @param token - The full authentication token
+   * @returns The rate limit key
+   */
+  generateKey(token: string): string {
+    return this.config.keyPrefix + token.slice(0, this.config.keyLength)
+  }
+
+  /**
+   * Checks if a request should be rate limited based on prior failures.
+   *
+   * Uses a sliding window algorithm with exponential backoff:
+   * 1. If no entry exists or window expired, allow the request
+   * 2. Check if enough time has passed since the last failure (exponential backoff)
+   * 3. If not enough time has passed, rate limit
+   * 4. Check if failure count exceeds threshold
+   *
+   * NOTE: This method only CHECKS the rate limit state, it does NOT increment
+   * the failure count. Call recordFailure() to record a failure.
+   *
+   * @param key - Rate limit key (from generateKey)
+   * @returns true if the request should be rate limited, false otherwise
+   *
+   * @security Prevents brute force attacks by limiting authentication attempts.
+   *           Attack vector: Attacker tries many passwords/tokens in rapid succession.
+   *           Mitigation: After failures, exponential backoff is applied (2^N seconds).
+   */
+  isRateLimited(key: string): boolean {
+    const now = Date.now()
+
+    // Lazy cleanup: run periodically during normal operations
+    // This avoids needing a timer which doesn't work well in Workers
+    if (now - this.lastCleanupTime > this.config.cleanupIntervalMs) {
+      this.cleanup()
+    }
+
+    const entry = this.entries.get(key)
+
+    // No prior failures for this key
+    if (!entry) {
+      return false
+    }
+
+    // Window expired - reset and allow
+    if (now - entry.windowStart > this.config.windowMs) {
+      this.entries.delete(key)
+      return false
+    }
+
+    // SECURITY: Exponential backoff - require increasing delays between attempts
+    const requiredDelay = this.calculateExponentialBackoff(entry.count)
+    if (now - entry.lastAttempt < requiredDelay) {
+      // Not enough time has passed since last attempt - rate limited
+      return true
+    }
+
+    // Check if failure count exceeds threshold
+    return entry.count >= this.config.maxFailures
+  }
+
+  /**
+   * Records an authentication failure for rate limiting purposes.
+   *
+   * @param key - Rate limit key (from generateKey)
+   *
+   * @security Only call this when authentication actually fails. Do not call
+   *           on successful authentications or when rate limiting has already
+   *           blocked the request.
+   */
+  recordFailure(key: string): void {
+    const now = Date.now()
+
+    // Check if we need to evict before adding a new entry
+    if (!this.entries.has(key) && this.entries.size >= this.config.maxEntries) {
+      this.evictOldestEntries()
+    }
+
+    const entry = this.entries.get(key)
+
+    if (!entry || now - entry.windowStart > this.config.windowMs) {
+      // Start a new window
+      this.entries.set(key, { count: 1, windowStart: now, lastAttempt: now })
+      return
+    }
+
+    // Increment failure count in existing window
+    entry.count++
+    entry.lastAttempt = now
+  }
+
+  /**
+   * Returns current rate limiter statistics for monitoring.
+   *
+   * @returns Statistics about the current rate limiter state
+   */
+  getStats(): RateLimiterStats {
+    return {
+      size: this.entries.size,
+      maxSize: this.config.maxEntries,
+      lastCleanupTime: this.lastCleanupTime,
+      lastCleanupCount: this.lastCleanupCount,
+    }
+  }
+
+  /**
+   * Clears all rate limit state.
+   *
+   * @security In production, this should never be exposed to external callers.
+   *           Only intended for testing or administrative use.
+   */
+  clear(): void {
+    this.entries.clear()
+    this.lastCleanupTime = Date.now()
+    this.lastCleanupCount = 0
+  }
+
+  /**
+   * Gets the entry for a specific key (for testing/debugging).
+   *
+   * @param key - Rate limit key
+   * @returns The entry if it exists, undefined otherwise
+   */
+  getEntry(key: string): RateLimitEntry | undefined {
+    return this.entries.get(key)
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Calculates exponential backoff delay based on failure count.
+   *
+   * @security Exponential backoff makes brute force attacks increasingly expensive.
+   *           After N failures, attacker must wait 2^N seconds before the next attempt.
+   *
+   * @param failureCount - Number of consecutive failures
+   * @returns Required delay in milliseconds before next attempt is allowed
+   */
+  private calculateExponentialBackoff(failureCount: number): number {
+    // Cap at configured power to prevent integer overflow
+    const cappedCount = Math.min(failureCount, this.config.maxBackoffPower)
+    return Math.pow(2, cappedCount) * 1000
+  }
+
+  /**
+   * Performs cleanup of expired rate limit entries.
+   *
+   * @security This prevents memory leaks from accumulated expired entries.
+   *           Uses lazy cleanup during normal operations instead of a timer
+   *           to work better with Cloudflare Workers' event-driven model.
+   *
+   * @returns Number of entries removed
+   */
+  private cleanup(): number {
+    const now = Date.now()
+    let removed = 0
+
+    // Remove entries older than the rate limit window
+    for (const [key, entry] of this.entries) {
+      if (now - entry.windowStart > this.config.windowMs) {
+        this.entries.delete(key)
+        removed++
+      }
+    }
+
+    this.lastCleanupTime = now
+    this.lastCleanupCount = removed
+    return removed
+  }
+
+  /**
+   * Evicts oldest entries when rate limiter is at capacity.
+   * Uses Map iteration order (insertion order) for LRU-like eviction.
+   *
+   * @security Prevents memory exhaustion from attackers creating many unique
+   *           rate limit keys. Evicts 10% of entries to amortize eviction cost.
+   */
+  private evictOldestEntries(): void {
+    // Evict 10% of max entries to amortize eviction overhead
+    const evictCount = Math.ceil(this.config.maxEntries / 10)
+    let evicted = 0
+
+    for (const key of this.entries.keys()) {
+      if (evicted >= evictCount) break
+      this.entries.delete(key)
+      evicted++
+    }
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Creates a new AuthRateLimiter instance with the given configuration.
+ *
+ * @param config - Optional configuration overrides
+ * @returns A new AuthRateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * import { createAuthRateLimiter } from './auth-rate-limiter'
+ *
+ * const rateLimiter = createAuthRateLimiter({
+ *   windowMs: 30000,   // 30 second window
+ *   maxFailures: 5,    // 5 failures per window
+ * })
+ * ```
+ */
+export function createAuthRateLimiter(
+  config: Partial<AuthRateLimiterConfig> = {}
+): AuthRateLimiter {
+  return new AuthRateLimiter(config)
+}
+
+// ============================================================================
+// Default Instance (for backwards compatibility)
+// ============================================================================
+
+/**
+ * Default rate limiter instance for module-level use.
+ *
+ * @deprecated Prefer creating instances with createAuthRateLimiter() for better
+ *             testability and isolation. This is provided for backwards compatibility.
+ *
+ * @internal
+ */
+let defaultRateLimiter: AuthRateLimiter | null = null
+
+/**
+ * Gets or creates the default rate limiter instance.
+ *
+ * @returns The default AuthRateLimiter instance
+ *
+ * @internal
+ */
+export function getDefaultRateLimiter(): AuthRateLimiter {
+  if (!defaultRateLimiter) {
+    defaultRateLimiter = new AuthRateLimiter()
+  }
+  return defaultRateLimiter
+}
+
+/**
+ * Resets the default rate limiter instance.
+ * Primarily for testing purposes.
+ *
+ * @internal
+ */
+export function resetDefaultRateLimiter(): void {
+  if (defaultRateLimiter) {
+    defaultRateLimiter.clear()
+  }
+  defaultRateLimiter = null
+}