@bananalink-sdk/protocol 1.2.7

package/src/crypto/diagnostics.ts

@@ -0,0 +1,772 @@
+/**
+ * Crypto Provider Diagnostics
+ *
+ * Utilities for testing, benchmarking, and diagnosing crypto provider issues.
+ * These tools help developers understand provider availability and performance.
+ *
+ * @example
+ * ```typescript
+ * // Test if a provider actually works
+ * const result = await testProvider('webcrypto');
+ * if (result.success) {
+ *   console.log('WebCrypto is working!');
+ * } else {
+ *   console.error('WebCrypto failed:', result.error);
+ * }
+ *
+ * // Get detailed environment diagnostics
+ * const diag = await diagnoseEnvironment();
+ * console.log(diag.toMarkdown());
+ *
+ * // Benchmark providers
+ * const bench = await benchmarkProvider('webcrypto');
+ * console.log(`ECDH: ${bench.ecdh.avgMs}ms`);
+ * ```
+ */
+
+import type { Logger } from '@bananalink-sdk/logger';
+import type {
+  CryptoProvider,
+  CryptoProviderType,
+  PlatformDetectionResult,
+} from '../types/crypto-provider';
+import { getRegisteredCryptoProviders } from './providers';
+import { detectPlatform } from './utils';
+
+/**
+ * Result of testing a specific crypto operation
+ */
+export interface OperationTestResult {
+  /** Operation name */
+  operation: string;
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** Execution time in milliseconds */
+  durationMs?: number;
+  /** Error message if failed */
+  error?: string;
+  /** Additional details */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Result of testing a crypto provider
+ */
+export interface ProviderTestResult {
+  /** Provider type tested */
+  provider: CryptoProviderType;
+  /** Whether the provider is available */
+  available: boolean;
+  /** Overall success (all operations passed) */
+  success: boolean;
+  /** Individual operation test results */
+  operations: OperationTestResult[];
+  /** Total test duration in milliseconds */
+  totalDurationMs: number;
+  /** Error message if provider not available */
+  unavailableReason?: string;
+}
+
+/**
+ * Performance benchmark result for a provider
+ */
+export interface ProviderBenchmark {
+  /** Provider type tested */
+  provider: CryptoProviderType;
+  /** ECDH key generation benchmark */
+  ecdh: {
+    /** Average time in milliseconds */
+    avgMs: number;
+    /** Minimum time in milliseconds */
+    minMs: number;
+    /** Maximum time in milliseconds */
+    maxMs: number;
+    /** Number of iterations */
+    iterations: number;
+  };
+  /** Random bytes generation benchmark */
+  randomBytes: {
+    /** Average time in milliseconds */
+    avgMs: number;
+    /** Minimum time in milliseconds */
+    minMs: number;
+    /** Maximum time in milliseconds */
+    maxMs: number;
+    /** Number of iterations */
+    iterations: number;
+  };
+  /** AES-GCM encryption benchmark */
+  aesGcm: {
+    /** Average time in milliseconds */
+    avgMs: number;
+    /** Minimum time in milliseconds */
+    minMs: number;
+    /** Maximum time in milliseconds */
+    maxMs: number;
+    /** Number of iterations */
+    iterations: number;
+  };
+}
+
+/**
+ * Provider detection summary
+ */
+export interface ProviderDetection {
+  /** WebCrypto provider available */
+  webCrypto: boolean;
+  /** Node.js crypto provider available */
+  node: boolean;
+  /** Noble provider available (pure JS fallback) */
+  noble: boolean;
+  /** QuickCrypto provider available (React Native) */
+  quickCrypto: boolean;
+  /** Recommended provider for this environment */
+  recommended?: CryptoProviderType;
+  /** Detailed capability information */
+  capabilities: Record<CryptoProviderType, {
+    available: boolean;
+    tested: boolean;
+    success: boolean;
+  }>;
+  /** Provider-specific recommendations */
+  recommendations: string[];
+}
+
+/**
+ * Comprehensive environment diagnostics
+ */
+export interface EnvironmentDiagnostics {
+  /** Timestamp of diagnostics */
+  timestamp: string;
+  /** Platform detection information */
+  platform: PlatformDetectionResult;
+  /** Provider detection summary */
+  detection: ProviderDetection;
+  /** List of registered providers */
+  registeredProviders: CryptoProviderType[];
+  /** Provider test results */
+  providerTests: ProviderTestResult[];
+  /** Recommended provider (first successful test) */
+  recommendedProvider?: CryptoProviderType;
+  /** Warnings and recommendations */
+  warnings: string[];
+  /** Platform-specific recommendations */
+  recommendations: string[];
+  /** Convert to human-readable markdown */
+  toMarkdown(): string;
+  /** Convert to JSON string */
+  toJSON(): string;
+}
+
+/**
+ * Test a specific crypto provider with real operations
+ *
+ * @param providerType - The provider type to test
+ * @param logger - Optional logger for debug output
+ * @returns Test result with success status and operation details
+ *
+ * @example
+ * ```typescript
+ * const result = await testProvider('webcrypto');
+ * if (!result.success) {
+ *   console.error('Provider test failed:', result);
+ *   result.operations.forEach(op => {
+ *     if (!op.success) {
+ *       console.error(`  ${op.operation}: ${op.error}`);
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export async function testProvider(
+  providerType: CryptoProviderType,
+  logger?: Logger
+): Promise<ProviderTestResult> {
+  const startTime = performance.now();
+  const operations: OperationTestResult[] = [];
+
+  let provider: CryptoProvider;
+  try {
+    // Create the specific provider without fallback to test it directly
+    switch (providerType) {
+      case 'webcrypto':
+        provider = new (await import('./providers/webcrypto-provider')).WebCryptoProvider();
+        break;
+      case 'noble':
+        provider = new (await import('./providers/noble-provider')).NobleCryptoProvider(logger);
+        break;
+      case 'node':
+        provider = new (await import('./providers/node-provider')).NodeCryptoProvider(logger);
+        break;
+      case 'quickcrypto':
+        provider = new (await import('./providers/quickcrypto-provider')).QuickCryptoProvider(logger);
+        break;
+      default:
+        throw new Error(`Unknown provider type: ${String(providerType)}`);
+    }
+
+    if (!provider.isAvailable) {
+      return {
+        provider: providerType,
+        available: false,
+        success: false,
+        operations: [],
+        totalDurationMs: performance.now() - startTime,
+        unavailableReason: `Provider ${providerType} not available in this environment`,
+      };
+    }
+  } catch (error) {
+    return {
+      provider: providerType,
+      available: false,
+      success: false,
+      operations: [],
+      totalDurationMs: performance.now() - startTime,
+      unavailableReason: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  // Test 1: Random bytes generation
+  try {
+    const opStart = performance.now();
+    const bytes = provider.randomBytes(32);
+    const duration = performance.now() - opStart;
+
+    operations.push({
+      operation: 'randomBytes',
+      success: true,
+      durationMs: duration,
+      details: {
+        bytesLength: bytes.byteLength,
+      },
+    });
+  } catch (error) {
+    operations.push({
+      operation: 'randomBytes',
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  // Test 2: ECDH key pair generation
+  try {
+    const opStart = performance.now();
+    const keyPair = await provider.generateKeyPair();
+    const duration = performance.now() - opStart;
+
+    operations.push({
+      operation: 'generateKeyPair',
+      success: true,
+      durationMs: duration,
+      details: {
+        publicKeyType: keyPair.publicKey.type,
+        privateKeyType: keyPair.privateKey.type,
+      },
+    });
+  } catch (error) {
+    operations.push({
+      operation: 'generateKeyPair',
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  // Test 3: Key export/import
+  try {
+    const opStart = performance.now();
+    const keyPair = await provider.generateKeyPair();
+    const publicKeyData = await provider.exportPublicKey(keyPair.publicKey);
+    const importedPublicKey = await provider.importPublicKey(publicKeyData);
+    const duration = performance.now() - opStart;
+
+    operations.push({
+      operation: 'exportImportKey',
+      success: true,
+      durationMs: duration,
+      details: {
+        exportedKeySize: publicKeyData.byteLength,
+        importedKeyType: importedPublicKey.type,
+      },
+    });
+  } catch (error) {
+    operations.push({
+      operation: 'exportImportKey',
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  // Test 4: ECDH key agreement
+  try {
+    const opStart = performance.now();
+    const keyPair1 = await provider.generateKeyPair();
+    const keyPair2 = await provider.generateKeyPair();
+    // Derive shared secrets from both sides (just verify they can be derived)
+    await provider.deriveSharedSecret(keyPair1.privateKey, keyPair2.publicKey);
+    await provider.deriveSharedSecret(keyPair2.privateKey, keyPair1.publicKey);
+    const duration = performance.now() - opStart;
+
+    // Both shared secrets were derived successfully
+    operations.push({
+      operation: 'deriveSharedSecret',
+      success: true,
+      durationMs: duration,
+      details: {
+        sharedSecretsGenerated: 2,
+      },
+    });
+  } catch (error) {
+    operations.push({
+      operation: 'deriveSharedSecret',
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  // Test 5: AES-GCM encryption/decryption
+  try {
+    const opStart = performance.now();
+    const keyPair = await provider.generateKeyPair();
+    const sharedSecret = await provider.deriveSharedSecret(keyPair.privateKey, keyPair.publicKey);
+    const salt = provider.randomBytes(32);
+    const info = provider.randomBytes(32);
+    const encryptionKey = await provider.deriveEncryptionKey(sharedSecret, salt, info);
+
+    const plaintext = new TextEncoder().encode('Hello, World!');
+    const iv = provider.randomBytes(12);
+    const ciphertext = await provider.encrypt(encryptionKey, plaintext, iv);
+    const decrypted = await provider.decrypt(encryptionKey, ciphertext, iv);
+    const decryptedText = new TextDecoder().decode(decrypted);
+    const duration = performance.now() - opStart;
+
+    operations.push({
+      operation: 'aesGcmEncryptDecrypt',
+      success: decryptedText === 'Hello, World!',
+      durationMs: duration,
+      details: {
+        plaintextSize: plaintext.byteLength,
+        ciphertextSize: ciphertext.byteLength,
+        decryptedCorrectly: decryptedText === 'Hello, World!',
+      },
+    });
+  } catch (error) {
+    operations.push({
+      operation: 'aesGcmEncryptDecrypt',
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  const totalDuration = performance.now() - startTime;
+  const allSuccess = operations.every(op => op.success);
+
+  return {
+    provider: providerType,
+    available: true,
+    success: allSuccess,
+    operations,
+    totalDurationMs: totalDuration,
+  };
+}
+
+/**
+ * Benchmark a crypto provider's performance
+ *
+ * @param providerType - The provider type to benchmark
+ * @param iterations - Number of iterations for each operation (default: 10)
+ * @param logger - Optional logger for debug output
+ * @returns Benchmark results with timing statistics
+ *
+ * @example
+ * ```typescript
+ * const bench = await benchmarkProvider('noble', 20);
+ * console.log(`ECDH: ${bench.ecdh.avgMs}ms (min: ${bench.ecdh.minMs}ms, max: ${bench.ecdh.maxMs}ms)`);
+ * console.log(`Random: ${bench.randomBytes.avgMs}ms`);
+ * console.log(`AES-GCM: ${bench.aesGcm.avgMs}ms`);
+ * ```
+ */
+export async function benchmarkProvider(
+  providerType: CryptoProviderType,
+  iterations: number = 10,
+  logger?: Logger
+): Promise<ProviderBenchmark> {
+  // Create the specific provider without fallback to test it directly
+  let provider: CryptoProvider;
+  try {
+    switch (providerType) {
+      case 'webcrypto':
+        provider = new (await import('./providers/webcrypto-provider')).WebCryptoProvider();
+        break;
+      case 'noble':
+        provider = new (await import('./providers/noble-provider')).NobleCryptoProvider(logger);
+        break;
+      case 'node':
+        provider = new (await import('./providers/node-provider')).NodeCryptoProvider(logger);
+        break;
+      case 'quickcrypto':
+        provider = new (await import('./providers/quickcrypto-provider')).QuickCryptoProvider(logger);
+        break;
+      default:
+        throw new Error(`Unknown provider type: ${String(providerType)}`);
+    }
+  } catch (error) {
+    throw new Error(
+      `Provider ${providerType} failed to initialize: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  if (!provider.isAvailable) {
+    throw new Error(`Provider ${providerType} not available for benchmarking`);
+  }
+
+  // Benchmark ECDH key generation
+  const ecdhTimes: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    await provider.generateKeyPair();
+    ecdhTimes.push(performance.now() - start);
+  }
+
+  // Benchmark random bytes
+  const randomBytesTimes: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    provider.randomBytes(32);
+    randomBytesTimes.push(performance.now() - start);
+  }
+
+  // Benchmark AES-GCM
+  const aesGcmTimes: number[] = [];
+  // Prepare keys once
+  const keyPair = await provider.generateKeyPair();
+  const sharedSecret = await provider.deriveSharedSecret(keyPair.privateKey, keyPair.publicKey);
+  const salt = provider.randomBytes(32);
+  const info = provider.randomBytes(32);
+  const encryptionKey = await provider.deriveEncryptionKey(sharedSecret, salt, info);
+  const plaintext = provider.randomBytes(1024); // 1KB test data
+  const iv = provider.randomBytes(12);
+
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    await provider.encrypt(encryptionKey, plaintext, iv);
+    aesGcmTimes.push(performance.now() - start);
+  }
+
+  return {
+    provider: providerType,
+    ecdh: {
+      avgMs: ecdhTimes.reduce((a, b) => a + b, 0) / iterations,
+      minMs: Math.min(...ecdhTimes),
+      maxMs: Math.max(...ecdhTimes),
+      iterations,
+    },
+    randomBytes: {
+      avgMs: randomBytesTimes.reduce((a, b) => a + b, 0) / iterations,
+      minMs: Math.min(...randomBytesTimes),
+      maxMs: Math.max(...randomBytesTimes),
+      iterations,
+    },
+    aesGcm: {
+      avgMs: aesGcmTimes.reduce((a, b) => a + b, 0) / iterations,
+      minMs: Math.min(...aesGcmTimes),
+      maxMs: Math.max(...aesGcmTimes),
+      iterations,
+    },
+  };
+}
+
+/**
+ * Get comprehensive environment diagnostics
+ *
+ * @param logger - Optional logger for debug output
+ * @returns Complete diagnostics including registered providers, test results, and recommendations
+ *
+ * @example
+ * ```typescript
+ * const diag = await diagnoseEnvironment();
+ *
+ * // Print markdown report
+ * console.log(diag.toMarkdown());
+ *
+ * // Or access data programmatically
+ * console.log('Registered:', diag.registeredProviders);
+ * console.log('Recommended:', diag.recommendedProvider);
+ * diag.providerTests.forEach(test => {
+ *   console.log(`${test.provider}: ${test.success ? '✅' : '❌'}`);
+ * });
+ * ```
+ */
+export async function diagnoseEnvironment(logger?: Logger): Promise<EnvironmentDiagnostics> {
+  const platform = detectPlatform();
+  const registeredProviders = getRegisteredCryptoProviders();
+  const warnings: string[] = [];
+  const recommendations: string[] = [];
+
+  // Test all registered providers
+  const providerTests = await Promise.all(
+    registeredProviders.map(type => testProvider(type, logger))
+  );
+
+  // Find recommended provider (first successful test)
+  const recommendedProvider = providerTests.find(test => test.success && test.available)?.provider;
+
+  // Build provider detection summary
+  const capabilities: Record<CryptoProviderType, { available: boolean; tested: boolean; success: boolean }> = {
+    webcrypto: { available: false, tested: false, success: false },
+    node: { available: false, tested: false, success: false },
+    noble: { available: false, tested: false, success: false },
+    quickcrypto: { available: false, tested: false, success: false },
+  };
+
+  providerTests.forEach(test => {
+    capabilities[test.provider] = {
+      available: test.available,
+      tested: true,
+      success: test.success,
+    };
+  });
+
+  const detectionRecommendations: string[] = [];
+  if (!capabilities.noble.success) {
+    detectionRecommendations.push("Noble provider should always work as a fallback");
+  }
+  if (platform.isNode && !capabilities.node.tested) {
+    detectionRecommendations.push("Consider testing 'node' provider for optimal Node.js performance");
+  }
+  if (platform.isBrowser && !capabilities.webcrypto.tested) {
+    detectionRecommendations.push("Consider testing 'webcrypto' provider for browser environments");
+  }
+
+  const detection: ProviderDetection = {
+    webCrypto: capabilities.webcrypto.available && capabilities.webcrypto.success,
+    node: capabilities.node.available && capabilities.node.success,
+    noble: capabilities.noble.available && capabilities.noble.success,
+    quickCrypto: capabilities.quickcrypto.available && capabilities.quickcrypto.success,
+    recommended: recommendedProvider,
+    capabilities,
+    recommendations: detectionRecommendations,
+  };
+
+  // Generate warnings
+  providerTests.forEach(test => {
+    if (!test.success && test.available) {
+      warnings.push(`${test.provider} provider registered but failed operation tests`);
+    }
+  });
+
+  if (registeredProviders.length === 0) {
+    warnings.push('No crypto providers registered. Import at least one provider.');
+  }
+
+  if (!recommendedProvider) {
+    warnings.push('No working crypto provider found. All registered providers failed tests.');
+  }
+
+  // Generate platform-specific recommendations
+  if (platform.isNode) {
+    if (!registeredProviders.includes('node')) {
+      recommendations.push("Consider importing 'node' provider for optimal Node.js performance");
+    }
+    if (!recommendedProvider) {
+      recommendations.push("Import '@bananalink-sdk/protocol/crypto/provider/node' for Node.js");
+    }
+  } else if (platform.isBrowser) {
+    if (!registeredProviders.includes('webcrypto')) {
+      recommendations.push("Consider importing 'webcrypto' provider for browsers");
+    }
+    if (!recommendedProvider) {
+      recommendations.push("Import '@bananalink-sdk/protocol/crypto/provider/webcrypto' for browsers");
+    }
+  } else if (platform.isReactNative) {
+    if (!registeredProviders.includes('quickcrypto')) {
+      recommendations.push("Consider importing 'quickcrypto' provider for React Native");
+    }
+    if (!recommendedProvider) {
+      recommendations.push("Import '@bananalink-sdk/protocol/crypto/provider/quickcrypto' for React Native");
+    }
+  }
+
+  // Universal recommendation
+  if (!recommendedProvider || registeredProviders.length === 0) {
+    recommendations.push("Import '@bananalink-sdk/protocol/crypto/provider/noble' as a universal fallback");
+  }
+
+  const diagnostics: EnvironmentDiagnostics = {
+    timestamp: new Date().toISOString(),
+    platform,
+    detection,
+    registeredProviders,
+    providerTests,
+    recommendedProvider,
+    warnings,
+    recommendations,
+
+    toMarkdown(): string {
+      let md = '# Crypto Environment Diagnostics\n\n';
+      md += `**Generated:** ${this.timestamp}\n\n`;
+
+      // Platform section
+      md += '## Platform\n\n';
+      const platformType = this.platform.isNode
+        ? 'Node.js'
+        : this.platform.isBrowser
+          ? 'Browser'
+          : this.platform.isReactNative
+            ? 'React Native'
+            : 'Unknown';
+      md += `- **Type:** ${platformType}\n`;
+      if (this.platform.platform) {
+        md += `- **OS:** ${this.platform.platform}\n`;
+      }
+      if (this.platform.userAgent) {
+        // Truncate long user agents
+        const ua = this.platform.userAgent.length > 80
+          ? `${this.platform.userAgent.substring(0, 80)}...`
+          : this.platform.userAgent;
+        md += `- **User Agent:** ${ua}\n`;
+      }
+      md += '\n';
+
+      // Provider Detection section
+      md += '## Provider Detection\n\n';
+      md += `- **WebCrypto:** ${this.detection.webCrypto ? '✅' : '❌'}\n`;
+      md += `- **Node.js Crypto:** ${this.detection.node ? '✅' : '❌'}\n`;
+      md += `- **Noble (Pure JS):** ${this.detection.noble ? '✅' : '❌'}\n`;
+      md += `- **QuickCrypto (RN):** ${this.detection.quickCrypto ? '✅' : '❌'}\n`;
+      if (this.detection.recommended) {
+        md += `- **Recommended:** ${this.detection.recommended}\n`;
+      }
+      md += '\n';
+
+      // Capabilities section
+      md += '## Capabilities\n\n';
+      Object.entries(this.detection.capabilities).forEach(([provider, capability]) => {
+        const status = capability.tested
+          ? capability.success ? '✅ Available' : '❌ Failed'
+          : '⚪ Not Tested';
+        md += `- **${provider}:** ${status}\n`;
+      });
+      md += '\n';
+
+      // Registered providers section
+      md += '## Registered Providers\n\n';
+      if (this.registeredProviders.length === 0) {
+        md += 'No providers registered.\n\n';
+      } else {
+        this.registeredProviders.forEach(provider => {
+          md += `- ${provider}${provider === this.recommendedProvider ? ' (recommended)' : ''}\n`;
+        });
+        md += '\n';
+      }
+
+      // Provider tests section
+      md += '## Provider Tests\n\n';
+      if (this.providerTests.length === 0) {
+        md += 'No tests run (no providers registered).\n\n';
+      } else {
+        this.providerTests.forEach(test => {
+          md += `### ${test.provider}\n\n`;
+          md += `- **Available:** ${test.available ? '✅' : '❌'}\n`;
+          if (!test.available) {
+            md += `- **Reason:** ${test.unavailableReason}\n`;
+          } else {
+            md += `- **Overall Success:** ${test.success ? '✅' : '❌'}\n`;
+            md += `- **Total Duration:** ${test.totalDurationMs.toFixed(2)}ms\n\n`;
+            md += '**Operations:**\n\n';
+            test.operations.forEach(op => {
+              md += `- **${op.operation}:** ${op.success ? '✅' : '❌'}`;
+              if (op.durationMs) md += ` (${op.durationMs.toFixed(2)}ms)`;
+              if (op.error) md += ` - ${op.error}`;
+              md += '\n';
+            });
+          }
+          md += '\n';
+        });
+      }
+
+      // Recommendations section
+      md += '## Recommendations\n\n';
+      if (this.recommendedProvider) {
+        md += `- Recommended: Use '${this.recommendedProvider}' provider (passed all tests)\n`;
+      }
+      if (this.recommendations.length > 0) {
+        this.recommendations.forEach(rec => {
+          md += `- ${rec}\n`;
+        });
+      }
+      md += '\n';
+
+      // Warnings section
+      if (this.warnings.length > 0) {
+        md += '## Warnings\n\n';
+        this.warnings.forEach(warning => {
+          md += `⚠️ ${warning}\n\n`;
+        });
+      }
+
+      return md;
+    },
+
+    toJSON(): string {
+      return JSON.stringify(
+        {
+          timestamp: this.timestamp,
+          platform: this.platform,
+          detection: this.detection,
+          registeredProviders: this.registeredProviders,
+          providerTests: this.providerTests,
+          recommendedProvider: this.recommendedProvider,
+          warnings: this.warnings,
+          recommendations: this.recommendations,
+        },
+        null,
+        2
+      );
+    },
+  };
+
+  return diagnostics;
+}
+
+/**
+ * Compare performance of multiple providers
+ *
+ * @param providers - Array of provider types to compare
+ * @param iterations - Number of iterations for each benchmark (default: 10)
+ * @param logger - Optional logger for debug output
+ * @returns Array of benchmark results for comparison
+ *
+ * @example
+ * ```typescript
+ * const results = await compareProviders(['webcrypto', 'noble'], 20);
+ * results.forEach(result => {
+ *   console.log(`\n${result.provider}:`);
+ *   console.log(`  ECDH: ${result.ecdh.avgMs.toFixed(2)}ms`);
+ *   console.log(`  Random: ${result.randomBytes.avgMs.toFixed(2)}ms`);
+ *   console.log(`  AES: ${result.aesGcm.avgMs.toFixed(2)}ms`);
+ * });
+ * ```
+ */
+export async function compareProviders(
+  providers: CryptoProviderType[],
+  iterations: number = 10,
+  logger?: Logger
+): Promise<ProviderBenchmark[]> {
+  const results: ProviderBenchmark[] = [];
+
+  for (const provider of providers) {
+    try {
+      const benchmark = await benchmarkProvider(provider, iterations, logger);
+      results.push(benchmark);
+    } catch (error) {
+      logger?.warn(`Failed to benchmark ${provider}:`, {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        },
+      });
+    }
+  }
+
+  return results;
+}