@bananalink-sdk/protocol 1.2.7

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

@@ -0,0 +1,364 @@
+import type { Logger } from '@bananalink-sdk/logger';
+import type { CryptoProvider, CryptoKeyLike, ProviderKeyPair } from '../../types/crypto-provider';
+import { registerCryptoProvider } from './registry';
+
+/**
+ * WebCrypto CryptoKey wrapper to implement CryptoKeyLike interface
+ */
+class WebCryptoKeyWrapper implements CryptoKeyLike {
+  constructor(private readonly cryptoKey: CryptoKey) {}
+
+  get type(): 'public' | 'private' | 'secret' {
+    return this.cryptoKey.type as 'public' | 'private' | 'secret';
+  }
+
+  get algorithm(): string {
+    if (typeof this.cryptoKey.algorithm === 'string') {
+      return this.cryptoKey.algorithm;
+    }
+    return this.cryptoKey.algorithm.name;
+  }
+
+  get extractable(): boolean {
+    return this.cryptoKey.extractable;
+  }
+
+  get usages(): readonly string[] {
+    return this.cryptoKey.usages;
+  }
+
+  get nativeKey(): CryptoKey {
+    return this.cryptoKey;
+  }
+}
+
+/**
+ * Helper function to unwrap CryptoKeyLike to native CryptoKey
+ */
+function unwrapCryptoKey(keyLike: CryptoKeyLike): CryptoKey {
+  if (keyLike instanceof WebCryptoKeyWrapper) {
+    return keyLike.nativeKey;
+  }
+  // For backward compatibility, assume it's already a CryptoKey
+  return keyLike as unknown as CryptoKey;
+}
+
+/**
+ * Web Crypto API implementation of CryptoProvider
+ * Works in browsers and Node.js environments with Web Crypto support
+ */
+export class WebCryptoProvider implements CryptoProvider {
+  public readonly name = 'WebCrypto';
+  private readonly logger?: Logger;
+
+  public get isAvailable(): boolean {
+    return typeof crypto !== 'undefined' && typeof crypto.subtle !== 'undefined';
+  }
+
+  constructor(logger?: Logger) {
+    if (!this.isAvailable) {
+      throw new Error('Web Crypto API not available in this environment');
+    }
+    this.logger = logger?.child({ component: 'WebCryptoProvider' });
+  }
+
+  /**
+   * Generate ECDH P-256 key pair
+   */
+  async generateKeyPair(): Promise<ProviderKeyPair> {
+    this.logger?.debug('Generating ECDH P-256 key pair');
+
+    const keyPair = await crypto.subtle.generateKey(
+      {
+        name: 'ECDH',
+        namedCurve: 'P-256',
+      },
+      true, // extractable
+      ['deriveKey']
+    );
+
+    this.logger?.debug('Key pair generation completed');
+    return {
+      publicKey: new WebCryptoKeyWrapper(keyPair.publicKey),
+      privateKey: new WebCryptoKeyWrapper(keyPair.privateKey),
+    };
+  }
+
+  /**
+   * Export public key to ArrayBuffer (raw format)
+   */
+  async exportPublicKey(publicKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    return crypto.subtle.exportKey('raw', unwrapCryptoKey(publicKey));
+  }
+
+  /**
+   * Export private key to ArrayBuffer (raw format)
+   */
+  async exportPrivateKey(privateKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    // WebCrypto doesn't support 'raw' export for ECDH private keys
+    // Use JWK export and extract the d-value (32 bytes)
+    const jwk = await crypto.subtle.exportKey('jwk', unwrapCryptoKey(privateKey));
+    const dValue = new Uint8Array(Buffer.from(jwk.d as string, 'base64url'));
+    return dValue.buffer.slice(dValue.byteOffset, dValue.byteOffset + dValue.byteLength);
+  }
+
+  /**
+   * Import public key from ArrayBuffer (raw format)
+   */
+  async importPublicKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const keyBytes = new Uint8Array(keyData);
+
+    this.logger?.debug('importPublicKey called', {
+      keyLength: keyBytes.length,
+      keyBytesFirst20: Array.from(keyBytes.slice(0, 20)).map(b => b.toString(16).padStart(2, '0')).join(' ')
+    });
+
+    try {
+      const cryptoKey = await crypto.subtle.importKey(
+        'raw',
+        keyData,
+        {
+          name: 'ECDH',
+          namedCurve: 'P-256',
+        },
+        true,
+        []
+      );
+
+      this.logger?.debug('Public key import successful');
+      return new WebCryptoKeyWrapper(cryptoKey);
+    } 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)
+   */
+  async importPrivateKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    this.logger?.debug('Importing private key', {
+      keyLength: keyData.byteLength
+    });
+
+    try {
+      const cryptoKey = await crypto.subtle.importKey(
+        'raw',
+        keyData,
+        {
+          name: 'ECDH',
+          namedCurve: 'P-256',
+        },
+        true,
+        ['deriveKey']
+      );
+
+      this.logger?.debug('Private key import successful');
+      return new WebCryptoKeyWrapper(cryptoKey);
+    } catch (error) {
+      this.logger?.error('Private 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 private key: ${String(error)}`);
+    }
+  }
+
+  /**
+   * Derive shared secret from ECDH key agreement
+   */
+  async deriveSharedSecret(privateKey: CryptoKeyLike, publicKey: CryptoKeyLike): Promise<CryptoKeyLike> {
+    this.logger?.debug('Deriving shared secret using ECDH');
+
+    try {
+      const derivedKey = await crypto.subtle.deriveKey(
+        {
+          name: 'ECDH',
+          public: unwrapCryptoKey(publicKey),
+        },
+        unwrapCryptoKey(privateKey),
+        {
+          name: 'AES-GCM',
+          length: 256,
+        },
+        true,
+        ['encrypt', 'decrypt']
+      );
+
+      this.logger?.debug('Shared secret derivation completed');
+      return new WebCryptoKeyWrapper(derivedKey);
+    } 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
+   */
+  async deriveEncryptionKey(sharedSecret: CryptoKeyLike, salt: ArrayBuffer, info: ArrayBuffer): Promise<CryptoKeyLike> {
+    // Import shared secret as HKDF base key
+    const baseKey = await crypto.subtle.importKey(
+      'raw',
+      await crypto.subtle.exportKey('raw', unwrapCryptoKey(sharedSecret)),
+      { name: 'HKDF' },
+      false,
+      ['deriveKey']
+    );
+
+    // Derive encryption key using HKDF
+    const derivedKey = await crypto.subtle.deriveKey(
+      {
+        name: 'HKDF',
+        salt: salt,
+        info: info,
+        hash: 'SHA-256',
+      },
+      baseKey,
+      { name: 'AES-GCM', length: 256 },
+      true,
+      ['encrypt', 'decrypt']
+    );
+    return new WebCryptoKeyWrapper(derivedKey);
+  }
+
+  /**
+   * Generate random bytes
+   */
+  randomBytes(length: number): ArrayBuffer {
+    const buffer = new ArrayBuffer(length);
+    const view = new Uint8Array(buffer);
+    crypto.getRandomValues(view);
+    return buffer;
+  }
+
+  /**
+   * Encrypt data using AES-GCM
+   */
+  async encrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    this.logger?.debug('Encrypting data with AES-GCM', {
+      dataSize: data.byteLength,
+      ivSize: iv.byteLength
+    });
+
+    try {
+      const ciphertext = await crypto.subtle.encrypt(
+        {
+          name: 'AES-GCM',
+          iv: iv,
+          tagLength: 128, // 128-bit tag
+        },
+        unwrapCryptoKey(key),
+        data
+      );
+
+      this.logger?.debug('Encryption completed', {
+        ciphertextSize: ciphertext.byteLength
+      });
+      return ciphertext;
+    } 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
+   */
+  async decrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    this.logger?.debug('Decrypting data with AES-GCM', {
+      dataSize: data.byteLength,
+      ivSize: iv.byteLength
+    });
+
+    try {
+      const plaintext = await crypto.subtle.decrypt(
+        {
+          name: 'AES-GCM',
+          iv: iv,
+          tagLength: 128, // 128-bit tag
+        },
+        unwrapCryptoKey(key),
+        data
+      );
+
+      this.logger?.debug('Decryption completed', {
+        plaintextSize: plaintext.byteLength
+      });
+      return plaintext;
+    } 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
+   */
+  async generateHMAC(key: CryptoKeyLike, data: ArrayBuffer): Promise<ArrayBuffer> {
+    // Convert AES key to HMAC key
+    const hmacKey = await crypto.subtle.importKey(
+      'raw',
+      await crypto.subtle.exportKey('raw', unwrapCryptoKey(key)),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    );
+
+    return crypto.subtle.sign('HMAC', hmacKey, data);
+  }
+
+  /**
+   * Verify HMAC-SHA256
+   */
+  async verifyHMAC(key: CryptoKeyLike, data: ArrayBuffer, mac: ArrayBuffer): Promise<boolean> {
+    // Convert AES key to HMAC key
+    const hmacKey = await crypto.subtle.importKey(
+      'raw',
+      await crypto.subtle.exportKey('raw', unwrapCryptoKey(key)),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['verify']
+    );
+
+    return crypto.subtle.verify('HMAC', hmacKey, mac, data);
+  }
+}
+
+/**
+ * Self-register WebCrypto provider on import
+ * This allows the provider to be available when explicitly imported
+ */
+registerCryptoProvider('webcrypto', () => new WebCryptoProvider());
+
+// TypeScript module augmentation to track this provider is available
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace BananaLink {
+    interface RegisteredCryptoProviders {
+      webcrypto: true;
+    }
+  }
+}

package/src/crypto/session-security.ts

@@ -0,0 +1,185 @@
+import type { Logger } from '@bananalink-sdk/logger';
+import type { SessionKeys, EncryptedMessage, CryptoConfig } from './types';
+import { arrayBufferToBase64, base64ToArrayBuffer, stringToArrayBuffer, arrayBufferToString } from './utils';
+import type { CryptoProvider, CryptoKeyLike, ProviderKeyPair } from './providers';
+import { createCryptoProvider } from './providers';
+
+const CRYPTO_CONFIG: CryptoConfig = {
+  algorithm: 'AES-GCM',
+  keyLength: 256,
+  ivLength: 12,
+  tagLength: 128, // tagLength is in bits for Web Crypto API (128 bits = 16 bytes)
+  curve: 'P-256',
+};
+
+export class SessionSecurity {
+  private keyPair?: ProviderKeyPair;
+  private sharedSecret?: CryptoKeyLike;
+  private sessionId: string;
+  private encryptionKey?: CryptoKeyLike; // For AES-GCM
+  private provider: CryptoProvider;
+
+  constructor(sessionId?: string, provider?: CryptoProvider, logger?: Logger) {
+    this.provider = provider || createCryptoProvider(undefined, logger);
+    this.sessionId = sessionId || this.generateSessionId();
+  }
+
+  /**
+   * Get the crypto provider used by this session
+   */
+  getCryptoProvider(): CryptoProvider {
+    return this.provider;
+  }
+
+  /**
+   * Establish a new session with ephemeral key generation
+   */
+  static async establishSession(sessionId?: string, provider?: CryptoProvider, logger?: Logger): Promise<SessionSecurity> {
+    const session = new SessionSecurity(sessionId, provider, logger);
+    await session.generateKeyPair();
+    return session;
+  }
+
+  /**
+   * Generate ECDH key pair for this session
+   */
+  private async generateKeyPair(): Promise<void> {
+    this.keyPair = await this.provider.generateKeyPair();
+  }
+
+  /**
+   * Get the public key for sharing (base64 encoded)
+   */
+  async getPublicKey(): Promise<string> {
+    if (!this.keyPair?.publicKey) {
+      throw new Error('Key pair not generated. Call generateKeyPair() first.');
+    }
+
+    const exported = await this.provider.exportPublicKey(this.keyPair.publicKey);
+    return arrayBufferToBase64(exported);
+  }
+
+  /**
+   * Derive shared secret from peer's public key
+   */
+  async deriveSharedSecret(peerPublicKeyBase64: string): Promise<void> {
+    if (!this.keyPair?.privateKey) {
+      throw new Error('Key pair not generated');
+    }
+
+    const peerPublicKeyBuffer = base64ToArrayBuffer(peerPublicKeyBase64);
+    const importedPeerKey = await this.provider.importPublicKey(peerPublicKeyBuffer);
+
+    this.sharedSecret = await this.provider.deriveSharedSecret(this.keyPair.privateKey, importedPeerKey);
+  }
+
+  /**
+   * Derives an encryption key from the shared secret using HKDF.
+   * @param salt - A non-secret random value.
+   * @param info - Context-specific information.
+   */
+  async deriveEncryptionKey(salt: ArrayBuffer, info: ArrayBuffer): Promise<void> {
+    if (!this.sharedSecret) {
+      throw new Error('Shared secret not derived yet.');
+    }
+
+    this.encryptionKey = await this.provider.deriveEncryptionKey(this.sharedSecret, salt, info);
+  }
+
+  /**
+   * Encrypt a message using the derived session key
+   */
+  async encrypt(message: Record<string, unknown>): Promise<EncryptedMessage> {
+    if (!this.encryptionKey) {
+      throw new Error('Encryption key not derived');
+    }
+
+    const iv = this.provider.randomBytes(CRYPTO_CONFIG.ivLength);
+    const plaintext = stringToArrayBuffer(JSON.stringify(message));
+
+    const ciphertext = await this.provider.encrypt(this.encryptionKey, plaintext, iv);
+
+    // Generate HMAC for authentication
+    const dataToSign = new Uint8Array([
+      ...new Uint8Array(iv),
+      ...new Uint8Array(ciphertext)
+    ]);
+
+    const macBuffer = await this.provider.generateHMAC(this.encryptionKey, dataToSign.buffer);
+
+    return {
+      iv: arrayBufferToBase64(iv),
+      ciphertext: arrayBufferToBase64(ciphertext),
+      mac: arrayBufferToBase64(macBuffer),
+    };
+  }
+
+  /**
+   * Decrypt a message using the derived session key
+   */
+  async decrypt(encryptedMessage: EncryptedMessage): Promise<Record<string, unknown>> {
+    if (!this.encryptionKey) {
+      throw new Error('Encryption key not derived');
+    }
+
+    const iv = base64ToArrayBuffer(encryptedMessage.iv);
+    const ciphertext = base64ToArrayBuffer(encryptedMessage.ciphertext);
+    const receivedMac = base64ToArrayBuffer(encryptedMessage.mac);
+
+    // Verify HMAC first
+    const dataToVerify = new Uint8Array([
+      ...new Uint8Array(iv),
+      ...new Uint8Array(ciphertext)
+    ]);
+
+    const isValidMac = await this.provider.verifyHMAC(this.encryptionKey, dataToVerify.buffer, receivedMac);
+    if (!isValidMac) {
+      throw new Error('Message authentication failed');
+    }
+
+    // Decrypt the message
+    const plaintextBuffer = await this.provider.decrypt(this.encryptionKey, ciphertext, iv);
+    const plaintextString = arrayBufferToString(plaintextBuffer);
+    return JSON.parse(plaintextString) as Record<string, unknown>;
+  }
+
+  /**
+   * Get session information
+   */
+  async getSessionKeys(): Promise<SessionKeys> {
+    if (!this.keyPair || !this.sharedSecret) {
+      throw new Error('Session not properly initialized');
+    }
+
+    return {
+      sessionId: this.sessionId,
+      publicKey: await this.getPublicKey(),
+      sharedSecret: this.sharedSecret, // We know it exists due to the check above
+    };
+  }
+
+  /**
+   * Generate a random session ID
+   */
+  private generateSessionId(): string {
+    const sessionBytes = this.provider.randomBytes(16); // 128 bits
+    return arrayBufferToBase64(sessionBytes);
+  }
+
+  /**
+   * Get provider information
+   */
+  getProviderInfo(): { name: string; isAvailable: boolean } {
+    return {
+      name: this.provider.name,
+      isAvailable: this.provider.isAvailable,
+    };
+  }
+
+  /**
+   * Check if session is ready for encryption/decryption
+   */
+  get isReady(): boolean {
+    return !!(this.keyPair && this.sharedSecret && this.encryptionKey);
+  }
+}

package/src/crypto/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Crypto Runtime Types
+ *
+ * Type definitions for crypto operations and configuration used by implementations.
+ * These types are separate from the provider interface and describe data structures
+ * used during encryption, decryption, and key management.
+ *
+ * IMPORTANT: This file contains ONLY type definitions with zero runtime code.
+ */
+
+import type { CryptoKeyLike } from '../types/crypto-provider';
+
+/**
+ * Supported encryption algorithms
+ * - AES-GCM: AES-256 in Galois/Counter Mode with authentication
+ * - plaintext: No encryption (development/testing only)
+ */
+export type EncryptionAlgorithm = 'AES-GCM' | 'plaintext';
+
+/**
+ * Encrypted message structure
+ * Contains all components needed to decrypt and verify a message
+ */
+export interface EncryptedMessage {
+  /** Base64-encoded initialization vector (12 bytes for GCM) */
+  iv: string;
+  /** Base64-encoded ciphertext */
+  ciphertext: string;
+  /** Base64-encoded HMAC-SHA256 authentication code */
+  mac: string;
+}
+
+/**
+ * Asymmetric key pair structure
+ * Using CryptoKey for Web Crypto API compatibility
+ *
+ * Note: This is kept for backward compatibility with existing code.
+ * New code should use ProviderKeyPair from crypto-provider types.
+ */
+export interface KeyPair {
+  publicKey: CryptoKey;
+  privateKey: CryptoKey;
+}
+
+/**
+ * Session-specific encryption keys
+ * Manages shared secrets and public keys for a session
+ */
+export interface SessionKeys {
+  /** Shared secret derived from ECDH key exchange */
+  sharedSecret: CryptoKey | CryptoKeyLike;
+  /** Unique session identifier */
+  sessionId: string;
+  /** Base64-encoded public key for sharing with remote party */
+  publicKey: string;
+}
+
+/**
+ * Cryptographic algorithm configuration
+ * Defines the parameters for BananaLink's crypto implementation
+ */
+export interface CryptoConfig {
+  /** Encryption algorithm (always AES-GCM for production) */
+  algorithm: 'AES-GCM';
+  /** AES key length in bits */
+  keyLength: 256;
+  /** Initialization vector length in bytes (12 bytes for GCM) */
+  ivLength: 12;
+  /** Authentication tag length in bits (128 bits = 16 bytes) */
+  tagLength: 128;
+  /** Elliptic curve for ECDH key exchange */
+  curve: 'P-256';
+}
+
+/**
+ * Options for creating a crypto payload
+ * Supports both encrypted and plaintext modes
+ */
+export type CreatePayloadOptions =
+  | {
+      /** Plaintext mode (no encryption) */
+      encAlgo: 'plaintext';
+      /** Session identifier */
+      sessionId: string;
+    }
+  | {
+      /** Encrypted mode with AES-GCM */
+      encAlgo: 'AES-GCM';
+      /** Session identifier */
+      sessionId: string;
+      /** Base64-encoded remote public key for ECDH */
+      publicKeyB64: string;
+    };