@bananalink-sdk/protocol 1.2.7

package/src/crypto/providers/factory.ts

@@ -0,0 +1,204 @@
+import type { Logger } from '@bananalink-sdk/logger';
+import type { CryptoProvider, CryptoProviderType } from '../../types/crypto-provider';
+import { CryptoProviderUnavailableError } from '../errors';
+import { detectPlatform } from '../utils';
+import {
+  getCryptoProviderFactory,
+  getRegisteredCryptoProviders
+} from './registry';
+
+/**
+ * Generate context-appropriate recommendations for unavailable providers
+ */
+function generateRecommendations(
+  requestedProvider: CryptoProviderType,
+  platform: ReturnType<typeof detectPlatform>
+): string[] {
+  const recommendations: string[] = [];
+
+  // Provider-specific recommendations
+  if (requestedProvider === 'webcrypto') {
+    recommendations.push("WebCrypto requires a browser or Node.js 15+ environment");
+    if (platform.isNode) {
+      recommendations.push("Try 'node' provider for Node.js");
+    }
+  } else if (requestedProvider === 'node') {
+    recommendations.push("Node crypto requires Node.js environment");
+    if (platform.isBrowser) {
+      recommendations.push("Try 'webcrypto' provider for browsers");
+    }
+  } else if (requestedProvider === 'quickcrypto') {
+    recommendations.push("QuickCrypto requires React Native environment");
+    if (!platform.isReactNative) {
+      if (platform.isNode) {
+        recommendations.push("Try 'node' provider for Node.js");
+      } else if (platform.isBrowser) {
+        recommendations.push("Try 'webcrypto' provider for browsers");
+      }
+    }
+  }
+
+  // Universal fallback
+  recommendations.push("'noble' provider works in all environments as a fallback");
+  recommendations.push(`Import the provider: import '@bananalink-sdk/protocol/crypto/provider/${requestedProvider}'`);
+
+  return recommendations;
+}
+
+/**
+ * Create a crypto provider based on type
+ *
+ * This factory function uses the global registry to instantiate providers.
+ * Providers must be explicitly imported before they can be used.
+ *
+ * @param preferredProvider - Optional preferred provider type
+ * @param logger - Optional logger for debug output
+ * @param strict - If true, throw error if preferred provider unavailable
+ * @returns The created crypto provider instance
+ *
+ * @example
+ * ```typescript
+ * // Import providers to make them available
+ * import '@bananalink-sdk/protocol/crypto/provider/noble';
+ * import '@bananalink-sdk/protocol/crypto/provider/webcrypto';
+ *
+ * // Create provider
+ * const provider = createCryptoProvider('noble');
+ * ```
+ */
+export function createCryptoProvider(
+  preferredProvider?: CryptoProviderType,
+  logger?: Logger,
+  strict?: boolean
+): CryptoProvider {
+  const registeredProviders = getRegisteredCryptoProviders();
+
+  logger?.debug('Creating crypto provider', {
+    preferredProvider,
+    strict,
+    registeredProviders
+  });
+
+  // Determine which provider to use
+  let providerType: CryptoProviderType | undefined = preferredProvider;
+
+  // Strict validation: If no provider specified, require exactly one registered
+  if (!providerType) {
+    if (registeredProviders.length === 0) {
+      throw new CryptoProviderUnavailableError(
+        'No crypto providers are registered. Did you forget to import a provider?',
+        {
+          availableProviders: [],
+          recommendations: [
+            "Import at least one crypto provider, e.g.: import '@bananalink-sdk/protocol/crypto/provider/noble'",
+            "Noble provider is recommended as a universal fallback"
+          ]
+        }
+      );
+    } else if (registeredProviders.length === 1) {
+      // Auto-select the single registered provider
+      providerType = registeredProviders[0];
+      logger?.debug(`Auto-selected '${providerType}' provider (only one registered)`);
+    } else {
+      // Multiple registered - require explicit selection
+      throw new CryptoProviderUnavailableError(
+        `Multiple crypto providers registered: ${registeredProviders.join(', ')}. ` +
+        `Either import only one provider OR explicitly set cryptoProvider.type. ` +
+        `Example: cryptoProvider: { type: '${registeredProviders[0]}' }`,
+        {
+          availableProviders: registeredProviders,
+          recommendations: [
+            `Import only one crypto provider, or specify which one to use`,
+            `Registered providers: ${registeredProviders.join(', ')}`,
+            `Set cryptoProvider.type to one of the registered providers`
+          ]
+        }
+      );
+    }
+  }
+
+  // Try to create the provider
+  try {
+    const factory = getCryptoProviderFactory(providerType);
+    const provider = factory(logger);
+
+    logger?.info(`Using ${provider.name} crypto provider`, {
+      providerType,
+      isAvailable: provider.isAvailable
+    });
+
+    return provider;
+  } catch (error) {
+    // If strict mode AND user explicitly requested a specific provider, throw immediately
+    const userRequestedSpecificProvider = preferredProvider !== undefined;
+    if (strict && userRequestedSpecificProvider) {
+      // If already a CryptoProviderUnavailableError, re-throw as-is
+      if (error instanceof CryptoProviderUnavailableError) {
+        throw error;
+      }
+
+      // Wrap generic errors with full context
+      const platform = detectPlatform();
+      const availableProviders = getRegisteredCryptoProviders();
+      const recommendations = generateRecommendations(providerType, platform);
+
+      throw new CryptoProviderUnavailableError(
+        `Strict mode: Crypto provider '${providerType}' failed to initialize: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          requestedProvider: providerType,
+          availableProviders,
+          platform,
+          recommendations,
+        }
+      );
+    }
+
+    // Try fallback to any available provider
+    logger?.warn(`Failed to create '${providerType}' provider, trying fallback`, {
+      error: error instanceof Error ? { message: error.message } : { message: String(error) }
+    });
+
+    // Try each registered provider as fallback
+    for (const fallbackType of registeredProviders) {
+      if (fallbackType === providerType) continue; // Skip the one that failed
+
+      try {
+        const factory = getCryptoProviderFactory(fallbackType);
+        const provider = factory(logger);
+
+        logger?.info(`Using ${provider.name} crypto provider (fallback)`, {
+          originalType: providerType,
+          fallbackType
+        });
+
+        return provider;
+      } catch (fallbackError) {
+        logger?.debug(`Fallback to '${fallbackType}' failed`, {
+          error: fallbackError instanceof Error ? { message: fallbackError.message } : { message: String(fallbackError) }
+        });
+      }
+    }
+
+    // If we get here, no providers worked
+    const platform = detectPlatform();
+    const recommendations = generateRecommendations(providerType, platform);
+
+    throw new CryptoProviderUnavailableError(
+      `Failed to create any crypto provider. Requested: '${providerType}'`,
+      {
+        requestedProvider: providerType,
+        availableProviders: registeredProviders,
+        platform,
+        recommendations,
+      }
+    );
+  }
+}
+
+/**
+ * Export registry functions for advanced usage
+ */
+export {
+  isCryptoProviderRegistered,
+  getRegisteredCryptoProviders
+} from './registry';

package/src/crypto/providers/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Crypto providers for environment-agnostic cryptographic operations
+ */
+
+// Types
+export type {
+  CryptoProvider,
+  CryptoKeyLike,
+  ProviderKeyPair,
+  ProviderDetectionResult,
+  CryptoProviderType,
+  PlatformDetectionResult
+} from '../../types/crypto-provider';
+
+// Compliance types
+export type {
+  ComplianceEventType,
+  ComplianceAuditEvent,
+  ComplianceAuditor,
+  KeyUsageRestrictions,
+  ComplianceConfig
+} from './compliance-provider';
+
+// Factory functions
+export {
+  createCryptoProvider,
+  isCryptoProviderRegistered,
+  getRegisteredCryptoProviders,
+} from './factory';
+
+// Registry functions (for advanced usage)
+export {
+  registerCryptoProvider,
+  getCryptoProviderFactory,
+  clearCryptoProviderRegistry,
+  type CryptoProviderFactory
+} from './registry';
+
+// Note: Provider implementations should be imported from specific subpaths for explicit loading:
+// - './webcrypto-provider' for WebCryptoProvider
+// - './node-provider' for NodeCryptoProvider
+// - './noble-provider' for NobleCryptoProvider
+// - './quickcrypto-provider' for QuickCryptoProvider
+// - './compliance-provider' for ComplianceCryptoProvider and DefaultComplianceAuditor

package/src/crypto/providers/noble-provider.ts

@@ -0,0 +1,392 @@
+import { p256 } from '@noble/curves/nist.js';
+import { gcm } from '@noble/ciphers/aes.js';
+import { randomBytes as nobleRandomBytes } from '@noble/ciphers/utils.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import type { Logger } from '@bananalink-sdk/logger';
+import type { CryptoProvider, CryptoKeyLike, ProviderKeyPair } from '../../types/crypto-provider';
+import { registerCryptoProvider } from './registry';
+
+/**
+ * Noble library implementation of CryptoKeyLike
+ */
+class NobleKey implements CryptoKeyLike {
+  constructor(
+    public readonly data: Uint8Array,
+    public readonly type: 'public' | 'private' | 'secret',
+    public readonly algorithm: string,
+    public readonly extractable: boolean = true,
+    public readonly usages: readonly string[] = []
+  ) {}
+}
+
+/**
+ * Noble cryptography implementation of CryptoProvider
+ * Pure JavaScript implementation that works in all environments
+ */
+export class NobleCryptoProvider implements CryptoProvider {
+  public readonly name = 'Noble';
+  public readonly isAvailable = true; // Noble libraries work everywhere
+  private readonly logger?: Logger;
+
+  constructor(logger?: Logger) {
+    this.logger = logger?.child({ component: 'NobleCryptoProvider' });
+  }
+
+  /**
+   * Generate ECDH P-256 key pair
+   */
+  generateKeyPair(): Promise<ProviderKeyPair> {
+    this.logger?.debug('Generating ECDH P-256 key pair using Noble');
+
+    try {
+      const privateKeyBytes = p256.utils.randomSecretKey();
+      // Generate uncompressed public key to match WebCrypto format (65 bytes)
+      const publicKeyUncompressed = p256.getPublicKey(privateKeyBytes, false); // false = uncompressed
+
+      this.logger?.debug('Key pair generation completed', {
+        publicKeyLength: publicKeyUncompressed.length
+      });
+
+      return Promise.resolve({
+        privateKey: new NobleKey(privateKeyBytes, 'private', 'ECDH-P256', true, ['deriveKey']),
+        publicKey: new NobleKey(publicKeyUncompressed, 'public', 'ECDH-P256', true, []),
+      });
+    } catch (error) {
+      this.logger?.error('Key pair generation failed', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Export public key to ArrayBuffer (raw format)
+   */
+  exportPublicKey(publicKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    const nobleKey = publicKey as NobleKey;
+    if (nobleKey.type !== 'public') {
+      throw new Error('Expected public key');
+    }
+    return Promise.resolve(nobleKey.data.buffer.slice(nobleKey.data.byteOffset, nobleKey.data.byteOffset + nobleKey.data.byteLength));
+  }
+
+  /**
+   * Export private key to ArrayBuffer (raw format)
+   */
+  exportPrivateKey(privateKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    const nobleKey = privateKey as NobleKey;
+    if (nobleKey.type !== 'private') {
+      throw new Error('Expected private key');
+    }
+    return Promise.resolve(nobleKey.data.buffer.slice(nobleKey.data.byteOffset, nobleKey.data.byteOffset + nobleKey.data.byteLength));
+  }
+
+  /**
+   * Import public key from ArrayBuffer (raw format)
+   */
+  importPublicKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const keyBytes = new Uint8Array(keyData);
+
+    // Debug logging
+    this.logger?.debug('importPublicKey called', {
+      keyLength: keyBytes.length,
+      keyBytesFirst20: Array.from(keyBytes.slice(0, 20)).map(b => b.toString(16).padStart(2, '0')).join(' '),
+      keyBytesHex: Array.from(keyBytes).map(b => b.toString(16).padStart(2, '0')).join('')
+    });
+
+    // Validate public key using Noble's validation
+    try {
+      let processedKeyBytes: Uint8Array;
+
+      // Handle different key formats
+      if (keyBytes.length === 65) {
+        // Already in uncompressed format (0x04 + 32 + 32)
+        this.logger?.debug('Processing 65-byte key', {
+          firstByte: `0x${keyBytes[0].toString(16)}`
+        });
+        if (keyBytes[0] !== 0x04) {
+          throw new Error(`Expected uncompressed key (0x04 prefix), got 0x${keyBytes[0].toString(16)}`);
+        }
+        processedKeyBytes = keyBytes;
+      } else if (keyBytes.length === 64) {
+        // Raw format (32 + 32) - needs 0x04 prefix for Noble
+        // This is the WebCrypto export format
+        this.logger?.debug('Processing 64-byte key', {
+          action: 'adding 0x04 prefix'
+        });
+        processedKeyBytes = new Uint8Array(65);
+        processedKeyBytes[0] = 0x04; // Uncompressed point indicator
+        processedKeyBytes.set(keyBytes, 1); // Copy the 64 bytes after the prefix
+      } else {
+        throw new Error(`Invalid key length: expected 64 or 65 bytes, got ${keyBytes.length} bytes`);
+      }
+
+      this.logger?.debug('Key processing completed', {
+        processedLength: processedKeyBytes.length,
+        processedFirst20: Array.from(processedKeyBytes.slice(0, 20)).map(b => b.toString(16).padStart(2, '0')).join(' ')
+      });
+
+      // Validate using Noble's validation
+      const isValid = p256.utils.isValidPublicKey(processedKeyBytes, false); // false = allow uncompressed
+      this.logger?.debug('Noble key validation completed', {
+        isValid
+      });
+
+      if (!isValid) {
+        // Try additional debugging
+        this.logger?.debug('Key validation failed, trying alternative approaches', {
+          originalValidation: false
+        });
+
+        // Try with compressed format check
+        const isValidCompressed = p256.utils.isValidPublicKey(processedKeyBytes, true);
+        this.logger?.debug('Alternative validation attempted', {
+          compressedFormatValid: isValidCompressed
+        });
+
+        throw new Error('Key failed Noble validation');
+      }
+
+      return Promise.resolve(new NobleKey(processedKeyBytes, 'public', 'ECDH-P256', true, []));
+    } catch (error) {
+      this.logger?.error('Public key import failed', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      throw new Error(`Invalid P-256 public key: ${String(error)}`);
+    }
+  }
+
+  /**
+   * Import private key from ArrayBuffer (raw format)
+   */
+  importPrivateKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const keyBytes = new Uint8Array(keyData);
+
+    // Validate private key (Noble will throw if invalid)
+    try {
+      if (!p256.utils.isValidSecretKey(keyBytes)) {
+        throw new Error('Invalid secret key');
+      }
+    } catch (error) {
+      throw new Error(`Invalid P-256 private key: ${String(error)}`);
+    }
+
+    return Promise.resolve(new NobleKey(keyBytes, 'private', 'ECDH-P256', true, ['deriveKey']));
+  }
+
+  /**
+   * Derive shared secret from ECDH key agreement
+   */
+  deriveSharedSecret(privateKey: CryptoKeyLike, publicKey: CryptoKeyLike): Promise<CryptoKeyLike> {
+    this.logger?.debug('Deriving shared secret using ECDH with Noble');
+
+    const privKey = privateKey as NobleKey;
+    const pubKey = publicKey as NobleKey;
+
+    if (privKey.type !== 'private') {
+      const error = new Error('Expected private key');
+      this.logger?.error('Shared secret derivation failed - invalid private key type', {
+        actualType: privKey.type
+      });
+      throw error;
+    }
+    if (pubKey.type !== 'public') {
+      const error = new Error('Expected public key');
+      this.logger?.error('Shared secret derivation failed - invalid public key type', {
+        actualType: pubKey.type
+      });
+      throw error;
+    }
+
+    try {
+      // Perform ECDH key agreement - return x-coordinate only to match WebCrypto
+      const sharedSecret = p256.getSharedSecret(privKey.data, pubKey.data, false); // uncompressed
+      // Extract only the x-coordinate (32 bytes) to match WebCrypto behavior
+      const xCoordinate = sharedSecret.slice(1, 33); // Skip 0x04 prefix, take next 32 bytes
+
+      this.logger?.debug('Shared secret derivation completed', {
+        sharedSecretLength: xCoordinate.length
+      });
+
+      return Promise.resolve(new NobleKey(xCoordinate, 'secret', 'AES-GCM', true, ['encrypt', 'decrypt']));
+    } catch (error) {
+      this.logger?.error('Shared secret derivation failed', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Derive AES-GCM key from shared secret using HKDF
+   */
+  deriveEncryptionKey(sharedSecret: CryptoKeyLike, salt: ArrayBuffer, info: ArrayBuffer): Promise<CryptoKeyLike> {
+    const secretKey = sharedSecret as NobleKey;
+
+    if (secretKey.type !== 'secret') {
+      throw new Error('Expected secret key');
+    }
+
+    // Perform HKDF with SHA-256
+    const derivedKey = hkdf(sha256, secretKey.data, new Uint8Array(salt), new Uint8Array(info), 32); // 32 bytes = 256 bits
+
+    return Promise.resolve(new NobleKey(derivedKey, 'secret', 'AES-GCM', true, ['encrypt', 'decrypt']));
+  }
+
+  /**
+   * Generate random bytes
+   */
+  randomBytes(length: number): ArrayBuffer {
+    const bytes = nobleRandomBytes(length);
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  }
+
+  /**
+   * Encrypt data using AES-GCM
+   */
+  encrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    this.logger?.debug('Encrypting data with AES-GCM using Noble', {
+      dataSize: data.byteLength,
+      ivSize: iv.byteLength
+    });
+
+    const secretKey = key as NobleKey;
+
+    if (secretKey.type !== 'secret') {
+      const error = new Error('Expected secret key');
+      this.logger?.error('Encryption failed - invalid key type', {
+        actualType: secretKey.type
+      });
+      throw error;
+    }
+
+    try {
+      const aesGcm = gcm(secretKey.data, new Uint8Array(iv));
+      const ciphertext = aesGcm.encrypt(new Uint8Array(data));
+
+      this.logger?.debug('Encryption completed', {
+        ciphertextSize: ciphertext.byteLength
+      });
+
+      return Promise.resolve(ciphertext.buffer.slice(ciphertext.byteOffset, ciphertext.byteOffset + ciphertext.byteLength));
+    } catch (error) {
+      this.logger?.error('Encryption failed', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Decrypt data using AES-GCM
+   */
+  decrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    this.logger?.debug('Decrypting data with AES-GCM using Noble', {
+      dataSize: data.byteLength,
+      ivSize: iv.byteLength
+    });
+
+    const secretKey = key as NobleKey;
+
+    if (secretKey.type !== 'secret') {
+      const error = new Error('Expected secret key');
+      this.logger?.error('Decryption failed - invalid key type', {
+        actualType: secretKey.type
+      });
+      throw error;
+    }
+
+    try {
+      const aesGcm = gcm(secretKey.data, new Uint8Array(iv));
+      const plaintext = aesGcm.decrypt(new Uint8Array(data));
+
+      this.logger?.debug('Decryption completed', {
+        plaintextSize: plaintext.byteLength
+      });
+
+      return Promise.resolve(plaintext.buffer.slice(plaintext.byteOffset, plaintext.byteOffset + plaintext.byteLength));
+    } catch (error) {
+      this.logger?.error('Decryption failed', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Generate HMAC-SHA256
+   */
+  generateHMAC(key: CryptoKeyLike, data: ArrayBuffer): Promise<ArrayBuffer> {
+    const secretKey = key as NobleKey;
+
+    if (secretKey.type !== 'secret') {
+      throw new Error('Expected secret key');
+    }
+
+    const mac = hmac(sha256, secretKey.data, new Uint8Array(data));
+    return Promise.resolve(mac.buffer.slice(mac.byteOffset, mac.byteOffset + mac.byteLength));
+  }
+
+  /**
+   * Verify HMAC-SHA256
+   */
+  verifyHMAC(key: CryptoKeyLike, data: ArrayBuffer, mac: ArrayBuffer): Promise<boolean> {
+    const secretKey = key as NobleKey;
+
+    if (secretKey.type !== 'secret') {
+      throw new Error('Expected secret key');
+    }
+
+    try {
+      const expectedMac = hmac(sha256, secretKey.data, new Uint8Array(data));
+      const providedMac = new Uint8Array(mac);
+
+      // Constant-time comparison
+      if (expectedMac.length !== providedMac.length) {
+        return Promise.resolve(false);
+      }
+
+      let result = 0;
+      for (let i = 0; i < expectedMac.length; i++) {
+        result |= expectedMac[i] ^ providedMac[i];
+      }
+
+      return Promise.resolve(result === 0);
+    } catch {
+      return Promise.resolve(false);
+    }
+  }
+}
+
+/**
+ * Self-register Noble provider on import
+ * This allows the provider to be available when explicitly imported
+ */
+registerCryptoProvider('noble', (logger) => new NobleCryptoProvider(logger));
+
+// TypeScript module augmentation to track this provider is available
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace BananaLink {
+    interface RegisteredCryptoProviders {
+      noble: true;
+    }
+  }
+}