@bananalink-sdk/protocol 1.2.7

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

@@ -0,0 +1,483 @@
+import type { Logger } from '@bananalink-sdk/logger';
+import type { CryptoProvider, CryptoKeyLike, ProviderKeyPair } from '../../types/crypto-provider';
+import { NobleCryptoProvider } from './noble-provider';
+import { registerCryptoProvider } from './registry';
+
+// Global require function type for React Native environments
+type RequireFunction = (id: string) => unknown;
+type GlobalWithRequire = typeof globalThis & {
+  require?: RequireFunction;
+};
+
+/**
+ * Type guard to check if a key has a data property (from Noble provider)
+ */
+function hasKeyData(key: CryptoKeyLike): key is CryptoKeyLike & { data: Uint8Array } {
+  return 'data' in key && key.data instanceof Uint8Array;
+}
+
+// Type definitions for react-native-quick-crypto Node.js-like API
+interface QuickCryptoHash {
+  update(data: Uint8Array): void;
+  digest(): Uint8Array;
+}
+
+interface QuickCryptoCipher {
+  update(data: Uint8Array): Uint8Array;
+  final(): Uint8Array;
+  getAuthTag?(): Uint8Array;
+}
+
+interface QuickCryptoDecipher {
+  update(data: Uint8Array): Uint8Array;
+  final(): Uint8Array;
+  setAuthTag?(authTag: Uint8Array): void;
+}
+
+interface QuickCrypto {
+  randomBytes(size: number): Uint8Array;
+  createHash(algorithm: string): QuickCryptoHash;
+  createHmac(algorithm: string, key: Uint8Array): QuickCryptoHash;
+  createCipheriv(algorithm: string, key: Uint8Array, iv: Uint8Array): QuickCryptoCipher;
+  createDecipheriv(algorithm: string, key: Uint8Array, iv: Uint8Array): QuickCryptoDecipher;
+}
+
+/**
+ * QuickCrypto key wrapper to implement CryptoKeyLike interface
+ */
+class QuickCryptoKey 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[] = []
+  ) {}
+}
+
+/**
+ * Check if react-native-quick-crypto is available
+ */
+function isQuickCryptoAvailable(): boolean {
+  try {
+    // Use globalThis.require for React Native compatibility
+    const global = globalThis as GlobalWithRequire;
+    if (!global.require) return false;
+
+    const quickCrypto = global.require('react-native-quick-crypto') as QuickCrypto | undefined;
+    if (!quickCrypto) return false;
+
+    return (
+      typeof quickCrypto.randomBytes === 'function' &&
+      typeof quickCrypto.createHash === 'function' &&
+      typeof quickCrypto.createHmac === 'function' &&
+      typeof quickCrypto.createCipheriv === 'function'
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * React Native QuickCrypto implementation of CryptoProvider
+ * Hybrid approach: uses Noble for ECDH operations and QuickCrypto for AES/HMAC/hashing
+ * This provides optimal performance while maintaining full compatibility
+ */
+export class QuickCryptoProvider implements CryptoProvider {
+  public readonly name = 'QuickCrypto';
+  public readonly isAvailable: boolean;
+
+  private readonly logger?: Logger;
+  private readonly quickCrypto?: QuickCrypto;
+  private readonly nobleProvider: NobleCryptoProvider;
+
+  constructor(logger?: Logger) {
+    this.logger = logger?.child({ component: 'QuickCryptoProvider' });
+    this.isAvailable = isQuickCryptoAvailable();
+
+    if (this.isAvailable) {
+      try {
+        const global = globalThis as GlobalWithRequire;
+        this.quickCrypto = global.require?.('react-native-quick-crypto') as QuickCrypto | undefined;
+        if (this.quickCrypto) {
+          this.logger?.debug('QuickCrypto initialized successfully');
+        } else {
+          this.logger?.warn('QuickCrypto require returned undefined');
+          // Mark as unavailable if we can't actually use it
+          (this as { isAvailable: boolean }).isAvailable = false;
+        }
+      } catch (error) {
+        this.logger?.error('Failed to initialize QuickCrypto', {
+          error: {
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined
+          }
+        });
+        // Mark as unavailable if we can't actually use it
+        (this as { isAvailable: boolean }).isAvailable = false;
+      }
+    }
+
+    // Always initialize Noble provider as fallback for ECDH operations
+    this.nobleProvider = new NobleCryptoProvider(logger);
+  }
+
+  /**
+   * Generate ECDH P-256 key pair using Noble (QuickCrypto doesn't support P-256 ECDH)
+   */
+  async generateKeyPair(): Promise<ProviderKeyPair> {
+    this.logger?.debug('Generating ECDH P-256 key pair using Noble (fallback)');
+
+    // Use Noble for key generation as QuickCrypto doesn't support P-256 ECDH
+    const nobleKeyPair = await this.nobleProvider.generateKeyPair();
+
+    // Wrap in QuickCryptoKey for consistency
+    if (!hasKeyData(nobleKeyPair.privateKey) || !hasKeyData(nobleKeyPair.publicKey)) {
+      throw new Error('Noble keys missing required data property');
+    }
+
+    return {
+      privateKey: new QuickCryptoKey(
+        nobleKeyPair.privateKey.data,
+        'private',
+        'ECDH-P256',
+        true,
+        ['deriveKey']
+      ),
+      publicKey: new QuickCryptoKey(
+        nobleKeyPair.publicKey.data,
+        'public',
+        'ECDH-P256',
+        true,
+        []
+      )
+    };
+  }
+
+  /**
+   * Export public key to ArrayBuffer (delegate to Noble)
+   */
+  exportPublicKey(publicKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    return this.nobleProvider.exportPublicKey(publicKey);
+  }
+
+  /**
+   * Export private key to ArrayBuffer (delegate to Noble)
+   */
+  exportPrivateKey(privateKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    return this.nobleProvider.exportPrivateKey(privateKey);
+  }
+
+  /**
+   * Import public key from ArrayBuffer (delegate to Noble)
+   */
+  async importPublicKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const nobleKey = await this.nobleProvider.importPublicKey(keyData);
+
+    if (!hasKeyData(nobleKey)) {
+      throw new Error('Noble public key missing required data property');
+    }
+
+    // Wrap in QuickCryptoKey for consistency
+    return new QuickCryptoKey(
+      nobleKey.data,
+      'public',
+      'ECDH-P256',
+      true,
+      []
+    );
+  }
+
+  /**
+   * Import private key from ArrayBuffer (delegate to Noble)
+   */
+  async importPrivateKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const nobleKey = await this.nobleProvider.importPrivateKey(keyData);
+
+    if (!hasKeyData(nobleKey)) {
+      throw new Error('Noble private key missing required data property');
+    }
+
+    // Wrap in QuickCryptoKey for consistency
+    return new QuickCryptoKey(
+      nobleKey.data,
+      'private',
+      'ECDH-P256',
+      true,
+      ['deriveKey']
+    );
+  }
+
+  /**
+   * Derive shared secret from ECDH key agreement (delegate to Noble)
+   */
+  async deriveSharedSecret(privateKey: CryptoKeyLike, publicKey: CryptoKeyLike): Promise<CryptoKeyLike> {
+    this.logger?.debug('Deriving shared secret using Noble (fallback)');
+
+    const sharedSecret = await this.nobleProvider.deriveSharedSecret(privateKey, publicKey);
+
+    if (!hasKeyData(sharedSecret)) {
+      throw new Error('Noble shared secret missing required data property');
+    }
+
+    // Wrap in QuickCryptoKey for consistency
+    return new QuickCryptoKey(
+      sharedSecret.data,
+      'secret',
+      'AES-GCM',
+      true,
+      ['encrypt', 'decrypt']
+    );
+  }
+
+  /**
+   * Derive AES-GCM key from shared secret using HKDF (delegate to Noble)
+   */
+  async deriveEncryptionKey(sharedSecret: CryptoKeyLike, salt: ArrayBuffer, info: ArrayBuffer): Promise<CryptoKeyLike> {
+    const encryptionKey = await this.nobleProvider.deriveEncryptionKey(sharedSecret, salt, info);
+
+    if (!hasKeyData(encryptionKey)) {
+      throw new Error('Noble encryption key missing required data property');
+    }
+
+    // Wrap in QuickCryptoKey for consistency
+    return new QuickCryptoKey(
+      encryptionKey.data,
+      'secret',
+      'AES-GCM',
+      true,
+      ['encrypt', 'decrypt']
+    );
+  }
+
+  /**
+   * Generate random bytes using QuickCrypto (58x faster than crypto-browserify)
+   */
+  randomBytes(length: number): ArrayBuffer {
+    if (!this.quickCrypto || !this.isAvailable) {
+      this.logger?.debug('QuickCrypto not available, falling back to Noble for randomBytes');
+      return this.nobleProvider.randomBytes(length);
+    }
+
+    try {
+      const bytes = this.quickCrypto.randomBytes(length);
+      return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    } catch (error) {
+      this.logger?.error('QuickCrypto randomBytes failed, falling back to Noble', {
+        error: {
+          message: error instanceof Error ? error.message : String(error)
+        }
+      });
+      return this.nobleProvider.randomBytes(length);
+    }
+  }
+
+  /**
+   * Encrypt data using AES-GCM with QuickCrypto (much faster than Noble)
+   */
+  async encrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    if (!this.quickCrypto || !this.isAvailable) {
+      this.logger?.debug('QuickCrypto not available, falling back to Noble for encryption');
+      return this.nobleProvider.encrypt(key, data, iv);
+    }
+
+    this.logger?.debug('Encrypting data with AES-GCM using QuickCrypto', {
+      dataSize: data.byteLength,
+      ivSize: iv.byteLength
+    });
+
+    const secretKey = key as QuickCryptoKey;
+
+    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 {
+      // Use QuickCrypto's Node.js-compatible AES-GCM implementation
+      const cipher = this.quickCrypto.createCipheriv('aes-256-gcm', secretKey.data, new Uint8Array(iv));
+
+      const encrypted = cipher.update(new Uint8Array(data));
+      const final = cipher.final();
+
+      // Get authentication tag (GCM mode)
+      const authTag = cipher.getAuthTag?.() || new Uint8Array(16);
+
+      // Combine encrypted data + auth tag (standard AES-GCM format)
+      const result = new Uint8Array(encrypted.length + final.length + authTag.length);
+      result.set(encrypted, 0);
+      result.set(final, encrypted.length);
+      result.set(authTag, encrypted.length + final.length);
+
+      this.logger?.debug('Encryption completed using QuickCrypto', {
+        ciphertextSize: result.byteLength
+      });
+
+      return result.buffer.slice(result.byteOffset, result.byteOffset + result.byteLength);
+    } catch (error) {
+      this.logger?.error('QuickCrypto encryption failed, falling back to Noble', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      return this.nobleProvider.encrypt(key, data, iv);
+    }
+  }
+
+  /**
+   * Decrypt data using AES-GCM with QuickCrypto (much faster than Noble)
+   */
+  async decrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    if (!this.quickCrypto || !this.isAvailable) {
+      this.logger?.debug('QuickCrypto not available, falling back to Noble for decryption');
+      return this.nobleProvider.decrypt(key, data, iv);
+    }
+
+    this.logger?.debug('Decrypting data with AES-GCM using QuickCrypto', {
+      dataSize: data.byteLength,
+      ivSize: iv.byteLength
+    });
+
+    const secretKey = key as QuickCryptoKey;
+
+    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 dataBytes = new Uint8Array(data);
+
+      // Extract auth tag from end of data (last 16 bytes for GCM)
+      const authTagLength = 16;
+      if (dataBytes.length < authTagLength) {
+        throw new Error('Data too short to contain auth tag');
+      }
+
+      const ciphertext = dataBytes.slice(0, -authTagLength);
+      const authTag = dataBytes.slice(-authTagLength);
+
+      const decipher = this.quickCrypto.createDecipheriv('aes-256-gcm', secretKey.data, new Uint8Array(iv));
+
+      // Set auth tag for verification
+      decipher.setAuthTag?.(authTag);
+
+      const decrypted = decipher.update(ciphertext);
+      const final = decipher.final();
+
+      // Combine decrypted chunks
+      const result = new Uint8Array(decrypted.length + final.length);
+      result.set(decrypted, 0);
+      result.set(final, decrypted.length);
+
+      this.logger?.debug('Decryption completed using QuickCrypto', {
+        plaintextSize: result.byteLength
+      });
+
+      return result.buffer.slice(result.byteOffset, result.byteOffset + result.byteLength);
+    } catch (error) {
+      this.logger?.error('QuickCrypto decryption failed, falling back to Noble', {
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined
+        }
+      });
+      return this.nobleProvider.decrypt(key, data, iv);
+    }
+  }
+
+  /**
+   * Generate HMAC-SHA256 using QuickCrypto (faster than Noble)
+   */
+  async generateHMAC(key: CryptoKeyLike, data: ArrayBuffer): Promise<ArrayBuffer> {
+    if (!this.quickCrypto || !this.isAvailable) {
+      this.logger?.debug('QuickCrypto not available, falling back to Noble for HMAC');
+      return this.nobleProvider.generateHMAC(key, data);
+    }
+
+    const secretKey = key as QuickCryptoKey;
+
+    if (secretKey.type !== 'secret') {
+      throw new Error('Expected secret key');
+    }
+
+    try {
+      const hmac = this.quickCrypto.createHmac('sha256', secretKey.data);
+      hmac.update(new Uint8Array(data));
+      const mac = hmac.digest();
+
+      return mac.buffer.slice(mac.byteOffset, mac.byteOffset + mac.byteLength);
+    } catch (error) {
+      this.logger?.error('QuickCrypto HMAC failed, falling back to Noble', {
+        error: {
+          message: error instanceof Error ? error.message : String(error)
+        }
+      });
+      return this.nobleProvider.generateHMAC(key, data);
+    }
+  }
+
+  /**
+   * Verify HMAC-SHA256 using QuickCrypto (faster than Noble)
+   */
+  async verifyHMAC(key: CryptoKeyLike, data: ArrayBuffer, mac: ArrayBuffer): Promise<boolean> {
+    if (!this.quickCrypto || !this.isAvailable) {
+      this.logger?.debug('QuickCrypto not available, falling back to Noble for HMAC verification');
+      return this.nobleProvider.verifyHMAC(key, data, mac);
+    }
+
+    try {
+      const expectedMac = await this.generateHMAC(key, data);
+      const providedMac = new Uint8Array(mac);
+      const expectedMacBytes = new Uint8Array(expectedMac);
+
+      // Constant-time comparison
+      if (expectedMacBytes.length !== providedMac.length) {
+        return false;
+      }
+
+      let result = 0;
+      for (let i = 0; i < expectedMacBytes.length; i++) {
+        result |= expectedMacBytes[i] ^ providedMac[i];
+      }
+
+      return result === 0;
+    } catch (error) {
+      this.logger?.error('QuickCrypto HMAC verification failed, falling back to Noble', {
+        error: {
+          message: error instanceof Error ? error.message : String(error)
+        }
+      });
+      return this.nobleProvider.verifyHMAC(key, data, mac);
+    }
+  }
+}
+
+/**
+ * Self-register QuickCrypto provider on import
+ * This allows the provider to be available when explicitly imported
+ *
+ * Note: QuickCrypto depends on Noble for ECDH operations, so we auto-register
+ * Noble as well to ensure all required functionality is available.
+ */
+// Auto-register noble as a dependency (QuickCrypto delegates ECDH to Noble)
+import './noble-provider';
+
+registerCryptoProvider('quickcrypto', (logger) => new QuickCryptoProvider(logger));
+
+// TypeScript module augmentation to track this provider is available
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace BananaLink {
+    interface RegisteredCryptoProviders {
+      quickcrypto: true;
+    }
+  }
+}

package/src/crypto/providers/registry.ts

@@ -0,0 +1,129 @@
+/**
+ * Global registry for crypto providers
+ *
+ * This registry allows providers to self-register when imported,
+ * enabling explicit import patterns while maintaining the factory pattern
+ * internally within BananaLink and BananaWallet classes.
+ */
+
+import type { CryptoProvider, CryptoProviderType } from '../../types/crypto-provider';
+import type { Logger } from '@bananalink-sdk/logger';
+
+/**
+ * Factory function type for creating crypto provider instances
+ */
+export type CryptoProviderFactory = (logger?: Logger) => CryptoProvider;
+
+/**
+ * Global registry storing available crypto providers
+ */
+const cryptoProviders = new Map<CryptoProviderType, CryptoProviderFactory>();
+
+/**
+ * Register a crypto provider factory
+ * Called automatically when a provider module is imported
+ *
+ * This function is idempotent - calling it multiple times with the same type
+ * will only register the provider once.
+ *
+ * @param type - The provider type identifier
+ * @param factory - Factory function that creates provider instances
+ *
+ * @example
+ * ```typescript
+ * // In noble-provider.ts
+ * registerCryptoProvider('noble', (logger) => new NobleCryptoProvider(logger));
+ * ```
+ */
+export function registerCryptoProvider(
+  type: CryptoProviderType,
+  factory: CryptoProviderFactory
+): void {
+  // Skip if already registered (idempotent)
+  if (cryptoProviders.has(type)) {
+    return;
+  }
+  cryptoProviders.set(type, factory);
+}
+
+/**
+ * Get a registered crypto provider factory
+ *
+ * @param type - The provider type to retrieve
+ * @returns The provider factory function
+ * @throws Error if the provider is not registered
+ */
+export function getCryptoProviderFactory(type: CryptoProviderType): CryptoProviderFactory {
+  const factory = cryptoProviders.get(type);
+
+  if (!factory) {
+    const availableProviders = Array.from(cryptoProviders.keys()).join(', ');
+    const importHint = getImportHint(type);
+
+    throw new Error(
+      `Crypto provider '${type}' is not registered. ${importHint}\n` +
+      `Available providers: ${availableProviders || 'none'}\n` +
+      `Make sure to import the provider before using it.`
+    );
+  }
+
+  return factory;
+}
+
+/**
+ * Check if a crypto provider is registered
+ *
+ * @param type - The provider type to check
+ * @returns True if the provider is registered
+ */
+export function isCryptoProviderRegistered(type: CryptoProviderType): boolean {
+  return cryptoProviders.has(type);
+}
+
+/**
+ * Get all registered crypto provider types
+ *
+ * @returns Array of registered provider types
+ */
+export function getRegisteredCryptoProviders(): CryptoProviderType[] {
+  return Array.from(cryptoProviders.keys());
+}
+
+/**
+ * Clear all registered providers (useful for testing)
+ */
+export function clearCryptoProviderRegistry(): void {
+  cryptoProviders.clear();
+}
+
+/**
+ * Get import hint for a specific provider type
+ */
+function getImportHint(type: CryptoProviderType): string {
+  switch (type) {
+    case 'noble':
+      return "Did you forget to import '@bananalink-sdk/protocol/crypto/provider/noble'?";
+    case 'quickcrypto':
+      return "Did you forget to import '@bananalink-sdk/protocol/crypto/provider/quickcrypto'?";
+    case 'webcrypto':
+      return "Did you forget to import '@bananalink-sdk/protocol/crypto/provider/webcrypto'?";
+    case 'node':
+      return "Did you forget to import '@bananalink-sdk/protocol/crypto/provider/node'?";
+    default:
+      return `Did you forget to import the '${String(type)}' provider?`;
+  }
+}
+
+/**
+ * Type augmentation for registered providers
+ * This allows TypeScript to track which providers are available
+ */
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace BananaLink {
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    interface RegisteredCryptoProviders {
+      // This will be augmented by each provider module
+    }
+  }
+}