@bananalink-sdk/protocol 1.2.7

package/src/crypto/errors.ts

@@ -0,0 +1,114 @@
+import type { CryptoProviderType, PlatformDetectionResult } from '../types/crypto-provider';
+
+/**
+ * Base class for all crypto-related errors
+ * Provides structured context for better debugging
+ */
+export class CryptoError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'CryptoError';
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Thrown when a requested crypto provider is not available in the current environment
+ * Includes diagnostic information to help developers understand why and what alternatives exist
+ */
+export class CryptoProviderUnavailableError extends CryptoError {
+  constructor(
+    message: string,
+    context: {
+      requestedProvider?: CryptoProviderType;
+      availableProviders: CryptoProviderType[];
+      platform?: PlatformDetectionResult;
+      recommendations: string[];
+    }
+  ) {
+    super(message, 'PROVIDER_UNAVAILABLE', context);
+    this.name = 'CryptoProviderUnavailableError';
+  }
+
+  /**
+   * Format a developer-friendly error message with context
+   * Includes available alternatives and actionable recommendations
+   */
+  toDevMessage(): string {
+    // Guard against undefined context (defensive programming)
+    if (!this.context) {
+      return this.message;
+    }
+
+    const ctx = this.context as {
+      requestedProvider?: CryptoProviderType;
+      availableProviders: CryptoProviderType[];
+      platform?: PlatformDetectionResult;
+      recommendations: string[];
+    };
+
+    const lines: string[] = [
+      this.message,
+      '',
+      'Available providers:',
+      ...ctx.availableProviders.map(p => `  - ${p}`),
+    ];
+
+    if (ctx.recommendations.length > 0) {
+      lines.push('', 'Recommendations:');
+      lines.push(...ctx.recommendations.map(r => `  - ${r}`));
+    }
+
+    // Add platform information if available
+    if (ctx.platform) {
+      const platformType = ctx.platform.isNode
+        ? 'Node.js'
+        : ctx.platform.isBrowser
+          ? 'Browser'
+          : ctx.platform.isReactNative
+            ? 'React Native'
+            : 'Unknown';
+
+      lines.push('', `Platform: ${platformType}`);
+
+      if (ctx.platform.platform) {
+        lines.push(`OS: ${ctx.platform.platform}`);
+      }
+
+      if (ctx.platform.userAgent) {
+        const ua = ctx.platform.userAgent;
+        // Only truncate if longer than 100 characters
+        const truncated = ua.length > 100 ? `${ua.substring(0, 100)}...` : ua;
+        lines.push(`User Agent: ${truncated}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Thrown when a specific cryptographic operation is not supported by the provider
+ */
+export class CryptoCapabilityMissingError extends CryptoError {
+  constructor(
+    operation: string,
+    provider: string,
+    reason: string
+  ) {
+    super(
+      `Crypto operation '${operation}' is not available in provider '${provider}': ${reason}`,
+      'CAPABILITY_MISSING',
+      { operation, provider, reason }
+    );
+    this.name = 'CryptoCapabilityMissingError';
+  }
+}

package/src/crypto/index.ts

@@ -0,0 +1,89 @@
+/**
+ * BananaLink Crypto Module
+ *
+ * Provides environment-agnostic cryptographic utilities for the BananaLink protocol including:
+ * - ECDHE key exchange (Web Crypto API + Noble fallback)
+ * - AES-256-GCM encryption/decryption
+ * - Session security management
+ * - Crypto payload handling
+ * - Pluggable crypto providers for different environments
+ */
+
+// Core crypto functionality
+export { SessionSecurity } from './session-security';
+export { CryptoPayloadHandler } from './payload-handler';
+
+// Crypto context management
+export { CryptoContext, type CryptoContextConfig } from './context';
+
+// Utility functions
+export { randomBytes, arrayBufferToBase64, base64ToArrayBuffer, stringToArrayBuffer, arrayBufferToString, generateNonce, generateUUID } from './utils';
+
+// Provider system
+export type {
+  CryptoProvider,
+  CryptoKeyLike,
+  ProviderKeyPair,
+  CryptoProviderType,
+} from '../types/crypto-provider';
+
+// Error classes
+export {
+  CryptoError,
+  CryptoProviderUnavailableError,
+  CryptoCapabilityMissingError,
+} from './errors';
+
+// Provider registry functions (for managing providers)
+export {
+  createCryptoProvider,
+  isCryptoProviderRegistered,
+  getRegisteredCryptoProviders,
+  registerCryptoProvider,
+  getCryptoProviderFactory,
+  clearCryptoProviderRegistry,
+  type CryptoProviderFactory,
+} from './providers';
+
+// Compliance wrapper (doesn't self-register, safe to export)
+export { ComplianceCryptoProvider, DefaultComplianceAuditor } from './providers/compliance-provider';
+
+// Note: Provider classes should be imported from specific subpaths for explicit loading:
+// - '@bananalink-sdk/protocol/crypto/provider/webcrypto' for WebCryptoProvider
+// - '@bananalink-sdk/protocol/crypto/provider/node' for NodeCryptoProvider
+// - '@bananalink-sdk/protocol/crypto/provider/noble' for NobleCryptoProvider
+// - '@bananalink-sdk/protocol/crypto/provider/quickcrypto' for QuickCryptoProvider
+// - '@bananalink-sdk/protocol/crypto/provider/compliance' for ComplianceCryptoProvider
+
+// Runtime types
+export type {
+  EncryptionAlgorithm,
+  EncryptedMessage,
+  SessionKeys,
+  CryptoConfig,
+  CreatePayloadOptions,
+} from './types';
+
+// Compliance types
+export type {
+  ComplianceEventType,
+  ComplianceAuditEvent,
+  ComplianceAuditor,
+  KeyUsageRestrictions,
+  ComplianceConfig,
+} from './providers/compliance-provider';
+
+// Diagnostics utilities
+export {
+  testProvider,
+  benchmarkProvider,
+  diagnoseEnvironment,
+  compareProviders,
+} from './diagnostics';
+
+export type {
+  OperationTestResult,
+  ProviderTestResult,
+  ProviderBenchmark,
+  EnvironmentDiagnostics,
+} from './diagnostics';

package/src/crypto/payload-handler.ts

@@ -0,0 +1,102 @@
+import type { CreatePayloadOptions } from './types';
+import type { CryptoPayload } from '../types/crypto';
+import { randomBytes, arrayBufferToBase64, base64ToArrayBuffer } from './utils';
+
+/**
+ * Parses a raw uncompressed P-256 public key.
+ * The key should be 65 bytes: [0x04, 32-byte X, 32-byte Y]
+ */
+function parsePublicKey(publicKey: ArrayBuffer): { x: ArrayBuffer; y: ArrayBuffer } {
+  if (publicKey.byteLength !== 65 || new Uint8Array(publicKey)[0] !== 4) {
+    throw new Error('Invalid P-256 public key format');
+  }
+  const x = publicKey.slice(1, 33);
+  const y = publicKey.slice(33, 65);
+  return { x, y };
+}
+
+export class CryptoPayloadHandler {
+  static createPayload(options: CreatePayloadOptions): CryptoPayload {
+    if (options.encAlgo === 'plaintext') {
+      return {
+        version: '1.0',
+        encryption: {
+          algorithm: 'plaintext',
+        },
+        parameters: {
+          timestamp: new Date().toISOString(),
+          sessionId: options.sessionId,
+        },
+      };
+    }
+
+    if (options.encAlgo === 'AES-GCM') {
+      const iv = randomBytes(12);
+      const salt = randomBytes(32);
+      const publicKeyRaw = base64ToArrayBuffer(options.publicKeyB64);
+      const { x, y } = parsePublicKey(publicKeyRaw);
+
+      return {
+        version: '1.0',
+        keyExchange: {
+          algorithm: 'ECDH',
+          namedCurve: 'P-256',
+        },
+        encryption: {
+          algorithm: 'AES-GCM',
+          keyLength: 256,
+          tagLength: 128,
+        },
+        publicKey: {
+          kty: 'EC',
+          crv: 'P-256',
+          x: arrayBufferToBase64(x),
+          y: arrayBufferToBase64(y),
+          use: 'enc',
+          key_ops: ['deriveKey'],
+        },
+        parameters: {
+          iv: arrayBufferToBase64(iv.buffer),
+          timestamp: new Date().toISOString(),
+          sessionId: options.sessionId,
+        },
+        derivation: {
+          algorithm: 'HKDF',
+          hash: 'SHA-256',
+          info: 'message-exchange-v1',
+          salt: arrayBufferToBase64(salt.buffer),
+        },
+      };
+    }
+
+    // This part should be unreachable with TypeScript's type checking
+    throw new Error('Invalid encryption algorithm specified.');
+  }
+
+  /**
+   * Validate crypto payload format
+   */
+  static validatePayload(payload: CryptoPayload): boolean {
+    try {
+      if (payload.version !== '1.0') {
+        return false;
+      }
+
+      if (!payload.parameters?.sessionId || !payload.parameters?.timestamp) {
+        return false;
+      }
+
+      if (payload.encryption?.algorithm === 'AES-GCM') {
+        return !!(payload.keyExchange && payload.publicKey && payload.derivation);
+      }
+
+      if (payload.encryption?.algorithm === 'plaintext') {
+        return true;
+      }
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+}