@bananalink-sdk/protocol 1.2.7

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

@@ -0,0 +1,579 @@
+import type { Logger } from '@bananalink-sdk/logger';
+import type { CryptoProvider, CryptoKeyLike, ProviderKeyPair } from '../../types/crypto-provider';
+
+/**
+ * Compliance audit event types
+ */
+export type ComplianceEventType =
+  | 'key_generation'
+  | 'key_import'
+  | 'key_export'
+  | 'key_derivation'
+  | 'encryption'
+  | 'decryption'
+  | 'hmac_generation'
+  | 'hmac_verification'
+  | 'random_generation';
+
+/**
+ * Compliance audit event
+ */
+export interface ComplianceAuditEvent {
+  eventType: ComplianceEventType;
+  timestamp: string;
+  sessionId?: string;
+  keyUsage?: readonly string[];
+  dataSize?: number;
+  algorithm?: string;
+  success: boolean;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Compliance audit logger interface
+ */
+export interface ComplianceAuditor {
+  logEvent(event: ComplianceAuditEvent): void;
+  getAuditLog(): ComplianceAuditEvent[];
+  clearAuditLog(): void;
+}
+
+/**
+ * Default compliance auditor implementation
+ */
+export class DefaultComplianceAuditor implements ComplianceAuditor {
+  private auditLog: ComplianceAuditEvent[] = [];
+  private readonly logger?: Logger;
+
+  constructor(logger?: Logger) {
+    this.logger = logger?.child({ component: 'ComplianceAuditor' });
+  }
+
+  logEvent(event: ComplianceAuditEvent): void {
+    this.auditLog.push(event);
+    this.logger?.info('Compliance audit event', {
+      eventType: event.eventType,
+      success: event.success,
+      sessionId: event.sessionId,
+      timestamp: event.timestamp
+    });
+  }
+
+  getAuditLog(): ComplianceAuditEvent[] {
+    return [...this.auditLog];
+  }
+
+  clearAuditLog(): void {
+    this.auditLog = [];
+    this.logger?.debug('Compliance audit log cleared');
+  }
+}
+
+/**
+ * Key usage restrictions for compliance
+ */
+export interface KeyUsageRestrictions {
+  allowKeyExport?: boolean;
+  allowKeyImport?: boolean;
+  requiredKeyUsages?: string[];
+  forbiddenKeyUsages?: string[];
+  maxDataSize?: number;
+  requireSessionId?: boolean;
+}
+
+/**
+ * Compliance configuration
+ */
+export interface ComplianceConfig {
+  enabled?: boolean;
+  auditor?: ComplianceAuditor;
+  keyRestrictions?: KeyUsageRestrictions;
+  sessionId?: string;
+  enableStrictMode?: boolean;
+  strictMode?: boolean;
+}
+
+/**
+ * Compliance wrapper for CryptoProvider implementations
+ * Provides audit logging, key usage restrictions, and regulatory compliance features
+ */
+export class ComplianceCryptoProvider implements CryptoProvider {
+  public readonly name: string;
+  public readonly isAvailable: boolean;
+
+  private readonly underlyingProvider: CryptoProvider;
+  private readonly config: ComplianceConfig;
+  private readonly auditor: ComplianceAuditor;
+  private readonly logger?: Logger;
+
+  constructor(
+    underlyingProvider: CryptoProvider,
+    config: ComplianceConfig = {},
+    logger?: Logger
+  ) {
+    this.underlyingProvider = underlyingProvider;
+    this.config = config;
+    this.auditor = config.auditor || new DefaultComplianceAuditor(logger);
+    this.logger = logger?.child({
+      component: 'ComplianceCryptoProvider',
+      underlyingProvider: underlyingProvider.name
+    });
+
+    this.name = `Compliance(${underlyingProvider.name})`;
+    this.isAvailable = underlyingProvider.isAvailable;
+  }
+
+  /**
+   * Create compliance audit event
+   */
+  private createAuditEvent(
+    eventType: ComplianceEventType,
+    success: boolean,
+    metadata: Record<string, unknown> = {},
+    error?: string
+  ): ComplianceAuditEvent {
+    return {
+      eventType,
+      timestamp: new Date().toISOString(),
+      sessionId: this.config.sessionId,
+      success,
+      error,
+      metadata,
+      ...metadata
+    };
+  }
+
+  /**
+   * Validate key usage restrictions
+   */
+  private validateKeyUsage(operation: string, keyUsages?: readonly string[], dataSize?: number): void {
+    const restrictions = this.config.keyRestrictions;
+    if (!restrictions) return;
+
+    if (restrictions.requireSessionId && !this.config.sessionId) {
+      throw new Error('Session ID required for compliance but not provided');
+    }
+
+    if (restrictions.maxDataSize && dataSize && dataSize > restrictions.maxDataSize) {
+      throw new Error(`Data size ${dataSize} exceeds maximum allowed ${restrictions.maxDataSize} bytes`);
+    }
+
+    if (keyUsages && restrictions.requiredKeyUsages) {
+      const hasRequiredUsage = restrictions.requiredKeyUsages.some(usage => keyUsages.includes(usage));
+      if (!hasRequiredUsage) {
+        throw new Error(`Key must have one of required usages: ${restrictions.requiredKeyUsages.join(', ')}`);
+      }
+    }
+
+    if (keyUsages && restrictions.forbiddenKeyUsages) {
+      const hasForbiddenUsage = restrictions.forbiddenKeyUsages.some(usage => keyUsages.includes(usage));
+      if (hasForbiddenUsage) {
+        throw new Error(`Key has forbidden usage. Forbidden: ${restrictions.forbiddenKeyUsages.join(', ')}`);
+      }
+    }
+
+    // Operation-specific restrictions
+    if (operation === 'export' && restrictions.allowKeyExport === false) {
+      throw new Error('Key export is forbidden by compliance policy');
+    }
+
+    if (operation === 'import' && restrictions.allowKeyImport === false) {
+      throw new Error('Key import is forbidden by compliance policy');
+    }
+  }
+
+  /**
+   * Generate ECDH P-256 key pair with compliance audit
+   */
+  async generateKeyPair(): Promise<ProviderKeyPair> {
+    const startTime = Date.now();
+
+    try {
+      this.logger?.debug('Generating key pair with compliance audit');
+
+      const keyPair = await this.underlyingProvider.generateKeyPair();
+
+      this.validateKeyUsage('generation', keyPair.privateKey.usages);
+
+      this.auditor.logEvent(this.createAuditEvent('key_generation', true, {
+        algorithm: keyPair.privateKey.algorithm,
+        keyUsage: keyPair.privateKey.usages,
+        duration: Date.now() - startTime
+      }));
+
+      return keyPair;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_generation', false, {
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Export public key with compliance audit
+   */
+  async exportPublicKey(publicKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('export', publicKey.usages);
+
+      const keyData = await this.underlyingProvider.exportPublicKey(publicKey);
+
+      this.auditor.logEvent(this.createAuditEvent('key_export', true, {
+        keyType: 'public',
+        algorithm: publicKey.algorithm,
+        keySize: keyData.byteLength,
+        duration: Date.now() - startTime
+      }));
+
+      return keyData;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_export', false, {
+        keyType: 'public',
+        algorithm: publicKey.algorithm,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Export private key with compliance audit
+   */
+  async exportPrivateKey(privateKey: CryptoKeyLike): Promise<ArrayBuffer> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('export', privateKey.usages);
+
+      // Extra security check for private key export
+      if (this.config.enableStrictMode) {
+        this.logger?.warn('Private key export in strict compliance mode', {
+          sessionId: this.config.sessionId,
+          algorithm: privateKey.algorithm
+        });
+      }
+
+      const keyData = await this.underlyingProvider.exportPrivateKey(privateKey);
+
+      this.auditor.logEvent(this.createAuditEvent('key_export', true, {
+        keyType: 'private',
+        algorithm: privateKey.algorithm,
+        keySize: keyData.byteLength,
+        strictMode: this.config.enableStrictMode,
+        duration: Date.now() - startTime
+      }));
+
+      return keyData;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_export', false, {
+        keyType: 'private',
+        algorithm: privateKey.algorithm,
+        strictMode: this.config.enableStrictMode,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Import public key with compliance audit
+   */
+  async importPublicKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('import');
+
+      const key = await this.underlyingProvider.importPublicKey(keyData);
+
+      this.auditor.logEvent(this.createAuditEvent('key_import', true, {
+        keyType: 'public',
+        algorithm: key.algorithm,
+        keySize: keyData.byteLength,
+        keyUsage: key.usages,
+        duration: Date.now() - startTime
+      }));
+
+      return key;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_import', false, {
+        keyType: 'public',
+        keySize: keyData.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Import private key with compliance audit
+   */
+  async importPrivateKey(keyData: ArrayBuffer): Promise<CryptoKeyLike> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('import');
+
+      const key = await this.underlyingProvider.importPrivateKey(keyData);
+
+      this.auditor.logEvent(this.createAuditEvent('key_import', true, {
+        keyType: 'private',
+        algorithm: key.algorithm,
+        keySize: keyData.byteLength,
+        keyUsage: key.usages,
+        duration: Date.now() - startTime
+      }));
+
+      return key;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_import', false, {
+        keyType: 'private',
+        keySize: keyData.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Derive shared secret with compliance audit
+   */
+  async deriveSharedSecret(privateKey: CryptoKeyLike, publicKey: CryptoKeyLike): Promise<CryptoKeyLike> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('derivation', privateKey.usages);
+
+      const sharedSecret = await this.underlyingProvider.deriveSharedSecret(privateKey, publicKey);
+
+      this.auditor.logEvent(this.createAuditEvent('key_derivation', true, {
+        operation: 'ECDH',
+        algorithm: privateKey.algorithm,
+        duration: Date.now() - startTime
+      }));
+
+      return sharedSecret;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_derivation', false, {
+        operation: 'ECDH',
+        algorithm: privateKey.algorithm,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Derive encryption key with compliance audit
+   */
+  async deriveEncryptionKey(sharedSecret: CryptoKeyLike, salt: ArrayBuffer, info: ArrayBuffer): Promise<CryptoKeyLike> {
+    const startTime = Date.now();
+
+    try {
+      const encryptionKey = await this.underlyingProvider.deriveEncryptionKey(sharedSecret, salt, info);
+
+      this.auditor.logEvent(this.createAuditEvent('key_derivation', true, {
+        operation: 'HKDF',
+        algorithm: 'HKDF-SHA256',
+        saltSize: salt.byteLength,
+        infoSize: info.byteLength,
+        duration: Date.now() - startTime
+      }));
+
+      return encryptionKey;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('key_derivation', false, {
+        operation: 'HKDF',
+        algorithm: 'HKDF-SHA256',
+        saltSize: salt.byteLength,
+        infoSize: info.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Generate random bytes with compliance audit
+   */
+  randomBytes(length: number): ArrayBuffer {
+    const startTime = Date.now();
+
+    try {
+      const randomData = this.underlyingProvider.randomBytes(length);
+
+      this.auditor.logEvent(this.createAuditEvent('random_generation', true, {
+        length,
+        duration: Date.now() - startTime
+      }));
+
+      return randomData;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('random_generation', false, {
+        length,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Encrypt data with compliance audit
+   */
+  async encrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('encryption', key.usages, data.byteLength);
+
+      const ciphertext = await this.underlyingProvider.encrypt(key, data, iv);
+
+      this.auditor.logEvent(this.createAuditEvent('encryption', true, {
+        algorithm: key.algorithm,
+        dataSize: data.byteLength,
+        ivSize: iv.byteLength,
+        ciphertextSize: ciphertext.byteLength,
+        duration: Date.now() - startTime
+      }));
+
+      return ciphertext;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('encryption', false, {
+        algorithm: key.algorithm,
+        dataSize: data.byteLength,
+        ivSize: iv.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Decrypt data with compliance audit
+   */
+  async decrypt(key: CryptoKeyLike, data: ArrayBuffer, iv: ArrayBuffer): Promise<ArrayBuffer> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('decryption', key.usages, data.byteLength);
+
+      const plaintext = await this.underlyingProvider.decrypt(key, data, iv);
+
+      this.auditor.logEvent(this.createAuditEvent('decryption', true, {
+        algorithm: key.algorithm,
+        dataSize: data.byteLength,
+        ivSize: iv.byteLength,
+        plaintextSize: plaintext.byteLength,
+        duration: Date.now() - startTime
+      }));
+
+      return plaintext;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('decryption', false, {
+        algorithm: key.algorithm,
+        dataSize: data.byteLength,
+        ivSize: iv.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Generate HMAC with compliance audit
+   */
+  async generateHMAC(key: CryptoKeyLike, data: ArrayBuffer): Promise<ArrayBuffer> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('hmac', key.usages, data.byteLength);
+
+      const mac = await this.underlyingProvider.generateHMAC(key, data);
+
+      this.auditor.logEvent(this.createAuditEvent('hmac_generation', true, {
+        algorithm: 'HMAC-SHA256',
+        dataSize: data.byteLength,
+        macSize: mac.byteLength,
+        duration: Date.now() - startTime
+      }));
+
+      return mac;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('hmac_generation', false, {
+        algorithm: 'HMAC-SHA256',
+        dataSize: data.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Verify HMAC with compliance audit
+   */
+  async verifyHMAC(key: CryptoKeyLike, data: ArrayBuffer, mac: ArrayBuffer): Promise<boolean> {
+    const startTime = Date.now();
+
+    try {
+      this.validateKeyUsage('hmac', key.usages, data.byteLength);
+
+      const isValid = await this.underlyingProvider.verifyHMAC(key, data, mac);
+
+      this.auditor.logEvent(this.createAuditEvent('hmac_verification', true, {
+        algorithm: 'HMAC-SHA256',
+        dataSize: data.byteLength,
+        macSize: mac.byteLength,
+        verified: isValid,
+        duration: Date.now() - startTime
+      }));
+
+      return isValid;
+    } catch (error) {
+      this.auditor.logEvent(this.createAuditEvent('hmac_verification', false, {
+        algorithm: 'HMAC-SHA256',
+        dataSize: data.byteLength,
+        macSize: mac.byteLength,
+        duration: Date.now() - startTime
+      }, error instanceof Error ? error.message : String(error)));
+
+      throw error;
+    }
+  }
+
+  /**
+   * Get compliance auditor for external access
+   */
+  getAuditor(): ComplianceAuditor {
+    return this.auditor;
+  }
+
+  /**
+   * Update compliance configuration
+   */
+  updateConfig(newConfig: Partial<ComplianceConfig>): void {
+    Object.assign(this.config, newConfig);
+    this.logger?.debug('Compliance configuration updated', newConfig);
+  }
+
+  /**
+   * Get underlying provider (for debugging/testing)
+   */
+  getUnderlyingProvider(): CryptoProvider {
+    return this.underlyingProvider;
+  }
+}