@agirails/sdk 2.0.1-beta → 2.0.2

package/src/utils/ReceivedNonceTracker.ts

@@ -228,6 +228,10 @@ export class InMemoryReceivedNonceTracker implements IReceivedNonceTracker {
  * - Reject duplicate nonces (replay attack)
  * - Allows non-sequential nonces (nonce gaps are OK)
  *
+ * SECURITY FIX (NEW-H-2): Max size enforcement to prevent memory exhaustion
+ * SECURITY FIX (HIGH-2): Global total entries limit to prevent DoS via many sender combinations
+ * SECURITY FIX (H-2): Rate limiting per sender to prevent flood attacks
+ *
  * Trade-off:
  * - Higher memory usage (stores every nonce)
  * - More flexible (allows out-of-order delivery)
@@ -237,8 +241,94 @@ export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
   // Map: sender -> messageType -> Set of used nonces
   private usedNonces: Map<string, Map<string, Set<string>>> = new Map();
 
+  // SECURITY FIX (NEW-H-2): Maximum entries per sender+messageType
+  private readonly maxSizePerType: number;
+
+  // SECURITY FIX (HIGH-2): Global limit across ALL sender+messageType combinations
+  private readonly maxTotalEntries: number;
+  private totalEntries: number = 0;
+
+  // SECURITY FIX (H-2): Rate limiting per sender
+  // Map: sender -> { count: number, windowStart: number }
+  private rateLimitState: Map<string, { count: number; windowStart: number }> = new Map();
+  private readonly maxNoncesPerMinute: number;
+  private readonly rateLimitWindowMs: number = 60000; // 1 minute window
+
+  /**
+   * Create set-based tracker with optional max size
+   * @param maxSizePerType - Maximum nonces per sender+messageType (default: 10,000)
+   * @param maxTotalEntries - Maximum total nonces across all combinations (default: 100,000)
+   * @param maxNoncesPerMinute - Maximum nonces per sender per minute (default: 100)
+   */
+  constructor(
+    maxSizePerType: number = 10000,
+    maxTotalEntries: number = 100000,
+    maxNoncesPerMinute: number = 100
+  ) {
+    if (maxSizePerType <= 0) {
+      throw new Error('maxSizePerType must be positive');
+    }
+    if (maxTotalEntries <= 0) {
+      throw new Error('maxTotalEntries must be positive');
+    }
+    if (maxNoncesPerMinute <= 0) {
+      throw new Error('maxNoncesPerMinute must be positive');
+    }
+    this.maxSizePerType = maxSizePerType;
+    this.maxTotalEntries = maxTotalEntries;
+    this.maxNoncesPerMinute = maxNoncesPerMinute;
+  }
+
+  /**
+   * SECURITY FIX (H-2): Check rate limit for sender
+   * @param sender - Sender DID
+   * @returns true if rate limit exceeded
+   */
+  private checkRateLimit(sender: string): boolean {
+    const now = Date.now();
+    const state = this.rateLimitState.get(sender);
+
+    if (!state) {
+      // First nonce from this sender
+      this.rateLimitState.set(sender, { count: 1, windowStart: now });
+      return false; // Not rate limited
+    }
+
+    // Check if window expired (reset counter)
+    if (now - state.windowStart >= this.rateLimitWindowMs) {
+      state.count = 1;
+      state.windowStart = now;
+      return false; // Not rate limited
+    }
+
+    // Increment counter
+    state.count++;
+
+    // Check if rate limit exceeded
+    return state.count > this.maxNoncesPerMinute;
+  }
+
+  /**
+   * SECURITY FIX (H-2): Periodic cleanup of rate limit state
+   * Removes expired rate limit entries (older than 5 minutes)
+   */
+  private cleanupRateLimitState(): void {
+    const now = Date.now();
+    const expiryThreshold = 5 * 60 * 1000; // 5 minutes
+
+    for (const [sender, state] of this.rateLimitState.entries()) {
+      if (now - state.windowStart > expiryThreshold) {
+        this.rateLimitState.delete(sender);
+      }
+    }
+  }
+
   /**
    * Validate and record a received nonce
+   *
+   * SECURITY FIX (NEW-H-2): Automatic cleanup when max size reached
+   * SECURITY FIX (HIGH-2): Global limit check to prevent DoS
+   * SECURITY FIX (H-2): Rate limiting per sender (max 100 nonces/minute)
    */
   validateAndRecord(sender: string, messageType: string, nonce: string): NonceValidationResult {
     // Validate nonce format
@@ -250,6 +340,34 @@ export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
       };
     }
 
+    // SECURITY FIX (H-2): Rate limit check (BEFORE global limit to avoid unnecessary work)
+    if (this.checkRateLimit(sender)) {
+      return {
+        valid: false,
+        reason: `Rate limit exceeded for sender ${sender}: ` +
+                `Maximum ${this.maxNoncesPerMinute} nonces per minute allowed. ` +
+                `This may indicate a flood attack or misconfigured client. ` +
+                `Wait 1 minute before retrying.`,
+        receivedNonce: nonce
+      };
+    }
+
+    // SECURITY FIX (H-2): Periodic cleanup every 100 validations (amortized cost)
+    if (this.totalEntries % 100 === 0) {
+      this.cleanupRateLimitState();
+    }
+
+    // SECURITY FIX (HIGH-2): Check global limit BEFORE adding
+    if (this.totalEntries >= this.maxTotalEntries) {
+      return {
+        valid: false,
+        reason: `Global nonce tracker limit reached (${this.maxTotalEntries} entries). ` +
+                `This may indicate a DoS attack or need for cleanup. ` +
+                `Current usage: ${this.totalEntries} entries across ${this.getCombinationCount()} sender+type combinations.`,
+        receivedNonce: nonce
+      };
+    }
+
     // Get sender's nonce map
     let senderNonces = this.usedNonces.get(sender);
     if (!senderNonces) {
@@ -273,11 +391,53 @@ export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
       };
     }
 
+    // SECURITY FIX (NEW-H-2): Auto-cleanup if max size per type reached
+    if (usedSet.size >= this.maxSizePerType) {
+      // Keep only last 80% of entries (sorted by nonce value)
+      const keepCount = Math.floor(this.maxSizePerType * 0.8);
+      const sortedNonces = Array.from(usedSet).sort((a, b) => {
+        const aVal = BigInt(a);
+        const bVal = BigInt(b);
+        return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+      });
+      const removedCount = usedSet.size - keepCount;
+      usedSet = new Set(sortedNonces.slice(-keepCount));
+      senderNonces.set(messageType, usedSet);
+      // SECURITY FIX (HIGH-2): Update global counter
+      this.totalEntries -= removedCount;
+    }
+
     // Valid nonce - record it
     usedSet.add(nonce);
+    // SECURITY FIX (HIGH-2): Update global counter
+    this.totalEntries++;
     return { valid: true };
   }
 
+  /**
+   * Get number of sender+messageType combinations (for monitoring)
+   * SECURITY FIX (HIGH-2): Monitoring method
+   */
+  private getCombinationCount(): number {
+    let count = 0;
+    this.usedNonces.forEach(senderMap => {
+      count += senderMap.size;
+    });
+    return count;
+  }
+
+  /**
+   * Get memory usage statistics
+   * SECURITY FIX (HIGH-2): Monitoring method for DoS detection
+   */
+  getMemoryUsage(): { totalEntries: number; combinations: number; maxTotalEntries: number } {
+    return {
+      totalEntries: this.totalEntries,
+      combinations: this.getCombinationCount(),
+      maxTotalEntries: this.maxTotalEntries
+    };
+  }
+
   /**
    * Check if a nonce has been used
    */
@@ -327,6 +487,11 @@ export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
   reset(sender: string, messageType: string): void {
     const senderNonces = this.usedNonces.get(sender);
     if (senderNonces) {
+      const usedSet = senderNonces.get(messageType);
+      if (usedSet) {
+        // SECURITY FIX (HIGH-2): Update global counter
+        this.totalEntries -= usedSet.size;
+      }
       senderNonces.delete(messageType);
       if (senderNonces.size === 0) {
         this.usedNonces.delete(sender);
@@ -339,6 +504,8 @@ export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
    */
   clearAll(): void {
     this.usedNonces.clear();
+    // SECURITY FIX (HIGH-2): Reset global counter
+    this.totalEntries = 0;
   }
 
   /**
@@ -377,8 +544,11 @@ export class SetBasedReceivedNonceTracker implements IReceivedNonceTracker {
     });
 
     // Keep only the last N nonces
+    const removedCount = usedSet.size - keepLast;
     const toKeep = new Set(sortedNonces.slice(-keepLast));
     senderNonces.set(messageType, toKeep);
+    // SECURITY FIX (HIGH-2): Update global counter
+    this.totalEntries -= removedCount;
   }
 }
 

package/src/utils/SDKLifecycle.ts

@@ -0,0 +1,416 @@
+/**
+ * SDKLifecycle - Proper cleanup and resource management
+ *
+ * SECURITY FIX (M-8): Ensures proper cleanup on SDK shutdown:
+ * - Connection cleanup
+ * - Pending request handling
+ * - Memory release
+ * - Graceful shutdown
+ *
+ * @module utils/SDKLifecycle
+ */
+
+import { sdkLogger, Logger } from './Logger';
+
+/**
+ * Disposable resource interface
+ */
+export interface Disposable {
+  /** Cleanup method */
+  dispose(): Promise<void> | void;
+}
+
+/**
+ * Shutdown handler function
+ */
+export type ShutdownHandler = () => Promise<void> | void;
+
+/**
+ * Lifecycle event types
+ */
+export type LifecycleEvent =
+  | 'initializing'
+  | 'ready'
+  | 'shutting-down'
+  | 'shutdown'
+  | 'error';
+
+/**
+ * Lifecycle event listener
+ */
+export type LifecycleListener = (event: LifecycleEvent, data?: unknown) => void;
+
+/**
+ * SDK Lifecycle Manager
+ *
+ * Manages SDK initialization, shutdown, and resource cleanup.
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = new SDKLifecycle();
+ *
+ * // Register cleanup handlers
+ * lifecycle.onShutdown(async () => {
+ *   await closeConnections();
+ * });
+ *
+ * // Register disposable resources
+ * lifecycle.registerDisposable(myResource);
+ *
+ * // Later, initiate shutdown
+ * await lifecycle.shutdown();
+ * ```
+ */
+export class SDKLifecycle {
+  private state: LifecycleEvent = 'initializing';
+  private shutdownHandlers: ShutdownHandler[] = [];
+  private disposables: Disposable[] = [];
+  private listeners: LifecycleListener[] = [];
+  private shutdownPromise: Promise<void> | null = null;
+  private readonly logger: Logger;
+  private isShuttingDown = false;
+
+  // SECURITY FIX (NEW-HIGH-2): Store handler references for cleanup
+  private processHandlers: {
+    sigint?: () => void;
+    sigterm?: () => void;
+    uncaughtException?: (error: Error) => void;
+    unhandledRejection?: (reason: unknown) => void;
+  } = {};
+  private processHandlersRegistered = false;
+
+  constructor(logger?: Logger) {
+    this.logger = logger ?? sdkLogger.child('Lifecycle');
+
+    // Register process shutdown handlers
+    this.registerProcessHandlers();
+  }
+
+  /**
+   * Get current lifecycle state
+   */
+  getState(): LifecycleEvent {
+    return this.state;
+  }
+
+  /**
+   * Check if SDK is ready for operations
+   */
+  isReady(): boolean {
+    return this.state === 'ready';
+  }
+
+  /**
+   * Mark SDK as ready
+   */
+  markReady(): void {
+    this.state = 'ready';
+    this.emit('ready');
+    this.logger.info('SDK ready');
+  }
+
+  /**
+   * Register a shutdown handler
+   *
+   * @param handler - Function to call during shutdown
+   * @returns Unregister function
+   */
+  onShutdown(handler: ShutdownHandler): () => void {
+    this.shutdownHandlers.push(handler);
+
+    return () => {
+      const index = this.shutdownHandlers.indexOf(handler);
+      if (index > -1) {
+        this.shutdownHandlers.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Register a disposable resource
+   *
+   * @param disposable - Resource with dispose() method
+   * @returns Unregister function
+   */
+  registerDisposable(disposable: Disposable): () => void {
+    this.disposables.push(disposable);
+
+    return () => {
+      const index = this.disposables.indexOf(disposable);
+      if (index > -1) {
+        this.disposables.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Add lifecycle event listener
+   *
+   * @param listener - Event listener function
+   * @returns Unregister function
+   */
+  addListener(listener: LifecycleListener): () => void {
+    this.listeners.push(listener);
+
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index > -1) {
+        this.listeners.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Emit lifecycle event
+   */
+  private emit(event: LifecycleEvent, data?: unknown): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event, data);
+      } catch (error) {
+        this.logger.error('Lifecycle listener error', { event }, error as Error);
+      }
+    }
+  }
+
+  /**
+   * Initiate graceful shutdown
+   *
+   * @param timeout - Maximum time to wait for cleanup (ms)
+   * @returns Promise that resolves when shutdown is complete
+   */
+  async shutdown(timeout = 30000): Promise<void> {
+    // Prevent multiple shutdown calls
+    if (this.shutdownPromise) {
+      return this.shutdownPromise;
+    }
+
+    if (this.isShuttingDown) {
+      return;
+    }
+
+    this.isShuttingDown = true;
+    this.state = 'shutting-down';
+    this.emit('shutting-down');
+    this.logger.info('SDK shutting down...');
+
+    this.shutdownPromise = this.executeShutdown(timeout);
+    return this.shutdownPromise;
+  }
+
+  /**
+   * Execute shutdown sequence
+   */
+  private async executeShutdown(timeout: number): Promise<void> {
+    const startTime = Date.now();
+    const errors: Error[] = [];
+
+    // Create timeout promise
+    const timeoutPromise = new Promise<void>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Shutdown timed out after ${timeout}ms`));
+      }, timeout);
+    });
+
+    try {
+      // Run shutdown handlers first (in reverse order - LIFO)
+      const handlersPromise = (async () => {
+        for (let i = this.shutdownHandlers.length - 1; i >= 0; i--) {
+          try {
+            const elapsed = Date.now() - startTime;
+            if (elapsed >= timeout) {
+              this.logger.warn('Shutdown timeout reached, skipping remaining handlers');
+              break;
+            }
+
+            const handler = this.shutdownHandlers[i];
+            await handler();
+          } catch (error) {
+            this.logger.error('Shutdown handler error', {}, error as Error);
+            errors.push(error as Error);
+          }
+        }
+
+        // Dispose resources (in reverse order)
+        for (let i = this.disposables.length - 1; i >= 0; i--) {
+          try {
+            const elapsed = Date.now() - startTime;
+            if (elapsed >= timeout) {
+              this.logger.warn('Shutdown timeout reached, skipping remaining disposables');
+              break;
+            }
+
+            const disposable = this.disposables[i];
+            await disposable.dispose();
+          } catch (error) {
+            this.logger.error('Disposable cleanup error', {}, error as Error);
+            errors.push(error as Error);
+          }
+        }
+      })();
+
+      // Race against timeout
+      await Promise.race([handlersPromise, timeoutPromise]);
+
+    } catch (error) {
+      if ((error as Error).message.includes('timed out')) {
+        this.logger.warn('Shutdown timed out, forcing cleanup');
+      } else {
+        errors.push(error as Error);
+      }
+    }
+
+    // SECURITY FIX (NEW-HIGH-2): Remove process handlers to prevent memory leaks
+    this.unregisterProcessHandlers();
+
+    // Clear registrations
+    this.shutdownHandlers = [];
+    this.disposables = [];
+
+    this.state = 'shutdown';
+    this.emit('shutdown');
+    this.logger.info('SDK shutdown complete', { errors: errors.length });
+
+    if (errors.length > 0) {
+      this.logger.error('Shutdown completed with errors', {
+        errorCount: errors.length,
+        errors: errors.map((e) => e.message),
+      });
+    }
+  }
+
+  /**
+   * Register process-level shutdown handlers
+   *
+   * SECURITY FIX (NEW-HIGH-2): Store handler references for cleanup
+   * to prevent memory leaks when multiple SDKLifecycle instances are created.
+   */
+  private registerProcessHandlers(): void {
+    // Only register in Node.js environment
+    if (typeof process === 'undefined') {
+      return;
+    }
+
+    // SECURITY FIX (NEW-HIGH-2): Prevent duplicate registrations
+    if (this.processHandlersRegistered) {
+      return;
+    }
+
+    // SECURITY FIX (NEW-HIGH-2): Create named handlers we can remove later
+    this.processHandlers.sigint = () => {
+      this.logger.info('Received SIGINT, initiating shutdown');
+      this.shutdown().then(() => {
+        process.exit(0);
+      }).catch((error) => {
+        this.logger.error('Shutdown error', {}, error);
+        process.exit(1);
+      });
+    };
+
+    this.processHandlers.sigterm = () => {
+      this.logger.info('Received SIGTERM, initiating shutdown');
+      this.shutdown().then(() => {
+        process.exit(0);
+      }).catch((error) => {
+        this.logger.error('Shutdown error', {}, error);
+        process.exit(1);
+      });
+    };
+
+    this.processHandlers.uncaughtException = (error: Error) => {
+      this.logger.error('Uncaught exception', {}, error);
+      this.emit('error', error);
+      this.shutdown().finally(() => {
+        process.exit(1);
+      });
+    };
+
+    this.processHandlers.unhandledRejection = (reason: unknown) => {
+      const error = reason instanceof Error ? reason : new Error(String(reason));
+      this.logger.error('Unhandled rejection', {}, error);
+      this.emit('error', error);
+    };
+
+    // Handle termination signals
+    process.on('SIGINT', this.processHandlers.sigint);
+    process.on('SIGTERM', this.processHandlers.sigterm);
+
+    // Handle uncaught errors
+    process.on('uncaughtException', this.processHandlers.uncaughtException);
+    process.on('unhandledRejection', this.processHandlers.unhandledRejection);
+
+    this.processHandlersRegistered = true;
+  }
+
+  /**
+   * Unregister process-level shutdown handlers
+   *
+   * SECURITY FIX (NEW-HIGH-2): Remove handlers to prevent memory leaks
+   */
+  private unregisterProcessHandlers(): void {
+    if (typeof process === 'undefined' || !this.processHandlersRegistered) {
+      return;
+    }
+
+    if (this.processHandlers.sigint) {
+      process.removeListener('SIGINT', this.processHandlers.sigint);
+    }
+    if (this.processHandlers.sigterm) {
+      process.removeListener('SIGTERM', this.processHandlers.sigterm);
+    }
+    if (this.processHandlers.uncaughtException) {
+      process.removeListener('uncaughtException', this.processHandlers.uncaughtException);
+    }
+    if (this.processHandlers.unhandledRejection) {
+      process.removeListener('unhandledRejection', this.processHandlers.unhandledRejection);
+    }
+
+    this.processHandlers = {};
+    this.processHandlersRegistered = false;
+  }
+
+  /**
+   * Create a disposable wrapper for any cleanup function
+   */
+  static createDisposable(cleanup: () => Promise<void> | void): Disposable {
+    return {
+      dispose: cleanup,
+    };
+  }
+}
+
+/**
+ * Global SDK lifecycle manager instance
+ */
+export const sdkLifecycle = new SDKLifecycle();
+
+/**
+ * Convenience function to run cleanup on shutdown
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onShutdown(async () => {
+ *   await closeDatabase();
+ * });
+ *
+ * // Later, to remove the handler:
+ * cleanup();
+ * ```
+ */
+export function onShutdown(handler: ShutdownHandler): () => void {
+  return sdkLifecycle.onShutdown(handler);
+}
+
+/**
+ * Convenience function to register disposable
+ */
+export function registerDisposable(disposable: Disposable): () => void {
+  return sdkLifecycle.registerDisposable(disposable);
+}
+
+/**
+ * Convenience function to shutdown SDK
+ */
+export function shutdownSDK(timeout?: number): Promise<void> {
+  return sdkLifecycle.shutdown(timeout);
+}

package/src/utils/SecureNonce.ts

@@ -0,0 +1,78 @@
+/**
+ * SecureNonce - Cryptographically secure nonce generation
+ *
+ * SECURITY FIX (NEW-H-3): Provides secure random nonce generation
+ * to prevent weak randomness vulnerabilities in EIP-712 message signing.
+ *
+ * Reference: V7 Re-Audit NEW-H-3 (Weak Random Nonce Generation)
+ *
+ * @module utils/SecureNonce
+ */
+
+import { ethers } from 'ethers';
+
+/**
+ * Generate a cryptographically secure random nonce (bytes32)
+ *
+ * Uses ethers.js randomBytes() which:
+ * - Uses Node.js crypto.randomBytes() (CSPRNG)
+ * - Uses Web Crypto API in browsers (window.crypto.getRandomValues)
+ * - Guaranteed to be cryptographically secure
+ *
+ * @returns 32-byte hex string (0x...)
+ *
+ * @example
+ * ```typescript
+ * import { generateSecureNonce } from '@agirails/sdk';
+ *
+ * const nonce = generateSecureNonce();
+ * console.log(nonce); // 0x1234...abcd (64 hex chars)
+ * ```
+ */
+export function generateSecureNonce(): string {
+  return ethers.hexlify(ethers.randomBytes(32));
+}
+
+/**
+ * Validate nonce format (must be bytes32)
+ *
+ * @param nonce - Nonce to validate
+ * @returns true if valid bytes32 format
+ *
+ * @example
+ * ```typescript
+ * isValidNonce('0x' + '00'.repeat(32)); // true
+ * isValidNonce('0x1234'); // false (too short)
+ * isValidNonce('not-hex'); // false (invalid format)
+ * ```
+ */
+export function isValidNonce(nonce: string): boolean {
+  return /^0x[a-fA-F0-9]{64}$/.test(nonce);
+}
+
+/**
+ * Generate an array of secure nonces
+ *
+ * @param count - Number of nonces to generate
+ * @returns Array of bytes32 hex strings
+ *
+ * @example
+ * ```typescript
+ * const nonces = generateSecureNonces(10);
+ * console.log(nonces.length); // 10
+ * ```
+ */
+export function generateSecureNonces(count: number): string[] {
+  if (count <= 0) {
+    throw new Error('Count must be positive');
+  }
+  if (count > 10000) {
+    throw new Error('Count exceeds maximum allowed (10000)');
+  }
+
+  const nonces: string[] = [];
+  for (let i = 0; i < count; i++) {
+    nonces.push(generateSecureNonce());
+  }
+  return nonces;
+}