@digitaldefiance/ecies-lib 4.4.11 → 4.4.14

package/src/services/chunk-processor.ts

@@ -1,188 +0,0 @@
-import { sha256 } from '@noble/hashes/sha2.js';
-import { IECIESConstants } from '../interfaces/ecies-consts';
-import { Constants } from '../constants';
-import {
-  IChunkHeader,
-  IEncryptedChunk,
-  CHUNK_CONSTANTS,
-} from '../interfaces/encrypted-chunk';
-import { ECIESService } from './ecies/service';
-import { getEciesI18nEngine, EciesComponentId } from '../i18n-setup';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-
-/**
- * Processes chunks for streaming encryption/decryption
- */
-export class ChunkProcessor {
-  constructor(
-    private readonly ecies: ECIESService,
-    private readonly eciesConsts: IECIESConstants = Constants.ECIES
-  ) {}
-
-  /**
-   * Build chunk header
-   */
-  buildChunkHeader(header: IChunkHeader): Uint8Array {
-    const buffer = new Uint8Array(CHUNK_CONSTANTS.HEADER_SIZE);
-    const view = new DataView(buffer.buffer);
-
-    view.setUint32(0, header.magic, false);
-    view.setUint16(4, header.version, false);
-    view.setUint32(6, header.index, false);
-    view.setUint32(10, header.originalSize, false);
-    view.setUint32(14, header.encryptedSize, false);
-    view.setUint16(18, header.flags, false);
-    // Bytes 20-31: reserved (zeros)
-
-    return buffer;
-  }
-
-  /**
-   * Parse chunk header
-   */
-  parseChunkHeader(data: Uint8Array): IChunkHeader {
-    const engine = getEciesI18nEngine();
-    if (data.length < CHUNK_CONSTANTS.HEADER_SIZE) {
-      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Chunk_DataTooShortForHeader));
-    }
-
-    const view = new DataView(data.buffer, data.byteOffset);
-
-    const magic = view.getUint32(0, false);
-    if (magic !== CHUNK_CONSTANTS.MAGIC) {
-      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Chunk_InvalidMagicBytes));
-    }
-
-    const version = view.getUint16(4, false);
-    if (version !== CHUNK_CONSTANTS.VERSION) {
-      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Chunk_UnsupportedVersion));
-    }
-
-    return {
-      magic,
-      version,
-      index: view.getUint32(6, false),
-      originalSize: view.getUint32(10, false),
-      encryptedSize: view.getUint32(14, false),
-      flags: view.getUint16(18, false),
-    };
-  }
-
-  /**
-   * Encrypt a single chunk
-   */
-  async encryptChunk(
-    data: Uint8Array,
-    publicKey: Uint8Array,
-    index: number,
-    isLast: boolean,
-    includeChecksum: boolean
-  ): Promise<IEncryptedChunk> {
-    // Encrypt data
-    const encrypted = await this.ecies.encryptSimpleOrSingle(
-      false,
-      publicKey,
-      data
-    );
-
-    // Calculate checksum if requested
-    const checksum = includeChecksum ? sha256(data) : undefined;
-
-    // Build header
-    let flags = 0;
-    if (isLast) flags |= CHUNK_CONSTANTS.FLAG_IS_LAST;
-    if (includeChecksum) flags |= CHUNK_CONSTANTS.FLAG_HAS_CHECKSUM;
-
-    const header = this.buildChunkHeader({
-      magic: CHUNK_CONSTANTS.MAGIC,
-      version: CHUNK_CONSTANTS.VERSION,
-      index,
-      originalSize: data.length,
-      encryptedSize: encrypted.length,
-      flags,
-    });
-
-    // Combine: header + encrypted + optional checksum
-    const parts = [header, encrypted];
-    if (checksum) {
-      parts.push(checksum);
-    }
-
-    const totalLength = parts.reduce((sum, part) => sum + part.length, 0);
-    const result = new Uint8Array(totalLength);
-    let offset = 0;
-    for (const part of parts) {
-      result.set(part, offset);
-      offset += part.length;
-    }
-
-    return {
-      index,
-      data: result,
-      isLast,
-      metadata: {
-        originalSize: data.length,
-        encryptedSize: encrypted.length,
-        timestamp: Date.now(),
-        checksum,
-      },
-    };
-  }
-
-  /**
-   * Decrypt a single chunk
-   */
-  async decryptChunk(
-    chunkData: Uint8Array,
-    privateKey: Uint8Array
-  ): Promise<{ data: Uint8Array; header: IChunkHeader }> {
-    // Parse header
-    const header = this.parseChunkHeader(chunkData);
-
-    // Extract encrypted data
-    const hasChecksum = (header.flags & CHUNK_CONSTANTS.FLAG_HAS_CHECKSUM) !== 0;
-    const encryptedStart = CHUNK_CONSTANTS.HEADER_SIZE;
-    const encryptedEnd = hasChecksum
-      ? chunkData.length - CHUNK_CONSTANTS.CHECKSUM_SIZE
-      : chunkData.length;
-
-    const encrypted = chunkData.slice(encryptedStart, encryptedEnd);
-
-    // Validate encrypted size matches header
-    if (encrypted.length !== header.encryptedSize) {
-      const engine = getEciesI18nEngine();
-      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Chunk_EncryptedSizeMismatchTemplate, { expectedSize: header.encryptedSize, actualSize: encrypted.length }));
-    }
-
-    // Decrypt
-    const decrypted = await this.ecies.decryptSimpleOrSingleWithHeader(
-      false,
-      privateKey,
-      encrypted
-    );
-
-    // Verify checksum if present
-    if (hasChecksum) {
-      const storedChecksum = chunkData.slice(-CHUNK_CONSTANTS.CHECKSUM_SIZE);
-      const computedChecksum = sha256(decrypted);
-
-      // Constant-time comparison to prevent timing attacks
-      let diff = 0;
-      for (let i = 0; i < CHUNK_CONSTANTS.CHECKSUM_SIZE; i++) {
-        diff |= storedChecksum[i] ^ computedChecksum[i];
-      }
-      if (diff !== 0) {
-        const engine = getEciesI18nEngine();
-        throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Chunk_ChecksumMismatch));
-      }
-    }
-
-    // Verify size
-    if (decrypted.length !== header.originalSize) {
-      const engine = getEciesI18nEngine();
-      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Chunk_DecryptedSizeMismatch));
-    }
-
-    return { data: decrypted, header };
-  }
-}

package/src/services/ecies/README.md

@@ -1,147 +0,0 @@
-# Browser-Compatible ECIES Service
-
-This directory contains a web-based implementation of the ECIES (Elliptic Curve Integrated Encryption Scheme) service that mirrors the functionality of the server-side implementation but uses browser-compatible libraries.
-
-## Overview
-
-The browser ECIES service provides the same cryptographic functionality as the server-side version, including:
-
-- **Mnemonic generation and wallet derivation** using BIP39/BIP32
-- **ECDH key exchange** using secp256k1 curve
-- **AES-GCM encryption** using Web Crypto API
-- **ECDSA signatures** using secp256k1
-- **Single and simple recipient encryption modes**
-- **CRC16 validation** for data integrity
-
-## Dependencies
-
-The service uses the following browser-compatible libraries:
-
-- `@scure/bip39` - BIP39 mnemonic generation and validation
-- `@scure/bip32` - BIP32 hierarchical deterministic key derivation
-- `@noble/curves` - Elliptic curve cryptography (secp256k1)
-- `@noble/hashes` - Cryptographic hash functions
-- Web Crypto API - Native browser AES-GCM encryption
-
-## Architecture
-
-### Core Components
-
-1. **`crypto-core.ts`** - Core cryptographic operations (key generation, ECDH)
-2. **`single-recipient.ts`** - Single recipient encryption/decryption
-3. **`signature.ts`** - ECDSA signature operations
-4. **`service.ts`** - Main service that integrates all components
-5. **`utils.ts`** - Utility functions (CRC16, hex conversion, etc.)
-6. **`constants.ts`** - Cryptographic constants matching server-side
-7. **`interfaces.ts`** - TypeScript interfaces
-
-### Encryption Modes
-
-- **Simple Mode**: Basic encryption without CRC or length prefix
-- **Single Mode**: Encryption with data length and CRC16 validation
-- **Multiple Mode**: Multi-recipient encryption (planned for future implementation)
-
-## Usage
-
-### Basic Example
-
-```typescript
-import { ECIESService } from './services/ecies';
-
-// Create service instance
-const ecies = new ECIESService();
-
-// Generate mnemonic and derive keys
-const mnemonic = ecies.generateNewMnemonic();
-const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(mnemonic);
-
-// Encrypt a message
-const message = new TextEncoder().encode('Hello, World!');
-const encrypted = await ecies.encryptSimpleOrSingle(false, publicKey, message);
-
-// Decrypt the message
-const decrypted = await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, encrypted);
-const result = new TextDecoder().decode(decrypted);
-```
-
-### Wallet Derivation
-
-```typescript
-// Generate new mnemonic
-const mnemonic = ecies.generateNewMnemonic();
-
-// Derive wallet from mnemonic
-const wallet = ecies.walletAndSeedFromMnemonic(mnemonic);
-console.log('Seed:', wallet.seed);
-console.log('Private Key:', wallet.privateKey);
-console.log('Public Key:', wallet.publicKey);
-```
-
-### Digital Signatures
-
-```typescript
-// Sign a message
-const message = new TextEncoder().encode('Message to sign');
-const signature = ecies.signMessage(privateKey, message);
-
-// Verify signature
-const isValid = ecies.verifyMessage(publicKey, message, signature);
-```
-
-### Simple vs Single Mode
-
-```typescript
-// Simple mode (no CRC, smaller overhead)
-const simpleEncrypted = await ecies.encryptSimpleOrSingle(true, publicKey, message);
-const simpleDecrypted = await ecies.decryptSimpleOrSingleWithHeader(true, privateKey, simpleEncrypted);
-
-// Single mode (with CRC and length validation)
-const singleEncrypted = await ecies.encryptSimpleOrSingle(false, publicKey, message);
-const singleDecrypted = await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, singleEncrypted);
-```
-
-## Compatibility
-
-This implementation is designed to be fully compatible with the server-side ECIES service:
-
-- Uses the same cryptographic constants and algorithms
-- Produces identical encrypted output format
-- Supports the same key derivation paths
-- Implements the same CRC16 algorithm for data integrity
-
-## Security Considerations
-
-- All cryptographic operations use well-established, audited libraries
-- Private keys are handled as Uint8Array and should be properly secured
-- The Web Crypto API provides secure random number generation
-- ECDH shared secrets are properly derived using secp256k1
-
-## Testing
-
-Run the examples to test the functionality:
-
-```typescript
-import { runAllExamples } from './services/ecies/example';
-
-// Run all examples in browser console
-runAllExamples();
-```
-
-## Future Enhancements
-
-- Multi-recipient encryption support
-- Key caching and management
-- Integration with browser storage APIs
-- Performance optimizations for large messages
-
-## Error Handling
-
-The service throws descriptive errors for:
-
-- Invalid mnemonics
-- Malformed public/private keys
-- Encryption/decryption failures
-- CRC validation errors
-- Invalid encryption types
-
-Always wrap cryptographic operations in try-catch blocks for proper error handling.

package/src/services/ecies/crypto-core.ts

@@ -1,292 +0,0 @@
-import { Wallet } from '@ethereumjs/wallet';
-import { HDKey } from '@scure/bip32';
-import {
-  generateMnemonic,
-  mnemonicToSeedSync,
-  validateMnemonic,
-} from '@scure/bip39';
-import { wordlist } from '@scure/bip39/wordlists/english';
-import { Constants } from '../../constants';
-import { IECIESConfig } from '../../interfaces/ecies-config';
-import { SecureString } from '../../secure-string';
-import { ISimpleKeyPair, IWalletSeed } from './interfaces';
-
-import { secp256k1 } from '@noble/curves/secp256k1.js';
-import { hkdf } from '@noble/hashes/hkdf.js';
-import { sha256 } from '@noble/hashes/sha2.js';
-import { EciesStringKey } from '../../enumerations';
-import { EciesComponentId, getEciesI18nEngine } from '../../i18n-setup';
-import { IECIESConstants } from '../../interfaces/ecies-consts';
-
-/**
- * Browser-compatible crypto core for ECIES operations
- * Uses @scure libraries for browser compatibility
- */
-export class EciesCryptoCore {
-  protected readonly _config: IECIESConfig;
-  protected readonly _eciesConsts: IECIESConstants;
-
-  constructor(
-    config: IECIESConfig,
-    eciesParams: IECIESConstants = Constants.ECIES,
-  ) {
-    this._config = config;
-    this._eciesConsts = eciesParams;
-  }
-
-  public get config(): IECIESConfig {
-    return this._config;
-  }
-
-  /**
-   * Validates and normalizes a public key for ECIES operations
-   */
-  public normalizePublicKey(publicKey: Uint8Array): Uint8Array {
-    if (!publicKey) {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(
-          EciesComponentId,
-          EciesStringKey.Error_ECIESError_ReceivedNullOrUndefinedPublicKey,
-        ),
-      );
-    }
-
-    const keyLength = publicKey.length;
-    let normalizedKey: Uint8Array;
-
-    // Compressed key (33 bytes) - 0x02 or 0x03 prefix
-    if (keyLength === 33 && (publicKey[0] === 0x02 || publicKey[0] === 0x03)) {
-      normalizedKey = publicKey;
-    }
-    // Uncompressed key (65 bytes) - 0x04 prefix
-    // We accept this for backward compatibility with existing keys
-    else if (keyLength === 65 && publicKey[0] === 0x04) {
-      normalizedKey = publicKey;
-    }
-    // Raw key without prefix (64 bytes) - add the 0x04 prefix
-    // Legacy support
-    else if (keyLength === 64) {
-      normalizedKey = new Uint8Array(65);
-      normalizedKey[0] = 0x04;
-      normalizedKey.set(publicKey, 1);
-    } else {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(
-          EciesComponentId,
-          EciesStringKey.Error_ECIESError_InvalidPublicKeyFormatOrLengthTemplate,
-          { keyLength },
-        ),
-      );
-    }
-
-    // Basic validation: check it's not all zeros
-    let allZeros = true;
-    for (let i = 1; i < normalizedKey.length; i++) {
-      // Skip first byte (prefix)
-      if (normalizedKey[i] !== 0) {
-        allZeros = false;
-        break;
-      }
-    }
-    if (allZeros) {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(
-          EciesComponentId,
-          EciesStringKey.Error_ECIESError_InvalidPublicKeyNotOnCurve,
-        ),
-      );
-    }
-
-    return normalizedKey;
-  }
-
-  /**
-   * Generate a new mnemonic
-   */
-  public generateNewMnemonic(): SecureString {
-    return new SecureString(
-      generateMnemonic(wordlist, this._config.mnemonicStrength),
-    );
-  }
-
-  /**
-   * Generate wallet and seed from mnemonic
-   */
-  public walletAndSeedFromMnemonic(mnemonic: SecureString): IWalletSeed {
-    if (!mnemonic || !validateMnemonic(mnemonic.value ?? '', wordlist)) {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(
-          EciesComponentId,
-          EciesStringKey.Error_ECIESError_InvalidMnemonic,
-        ),
-      );
-    }
-
-    const seed = mnemonicToSeedSync(mnemonic.value ?? '');
-    const hdKey = HDKey.fromMasterSeed(seed);
-    const derivedKey = hdKey.derive(this._config.primaryKeyDerivationPath);
-
-    if (!derivedKey.privateKey) {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(
-          EciesComponentId,
-          EciesStringKey.Error_ECIESError_FailedToDervivePrivateKey,
-        ),
-      );
-    }
-
-    const privateKey = derivedKey.privateKey;
-
-    const wallet = new Wallet(privateKey);
-
-    return {
-      wallet,
-      seed,
-    };
-  }
-
-  /**
-   * Create a simple key pair from a seed
-   */
-  public seedToSimpleKeyPair(seed: Uint8Array): ISimpleKeyPair {
-    const hdKey = HDKey.fromMasterSeed(seed);
-    const derivedKey = hdKey.derive(this._config.primaryKeyDerivationPath);
-
-    if (!derivedKey.privateKey) {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(
-          EciesComponentId,
-          EciesStringKey.Error_ECIESError_FailedToDervivePrivateKey,
-        ),
-      );
-    }
-
-    const privateKey = derivedKey.privateKey;
-    const publicKey = secp256k1.getPublicKey(privateKey, true); // compressed
-
-    return {
-      privateKey,
-      publicKey,
-    };
-  }
-
-  /**
-   * Create a simple key pair from a mnemonic
-   */
-  public mnemonicToSimpleKeyPair(mnemonic: SecureString): ISimpleKeyPair {
-    const { seed } = this.walletAndSeedFromMnemonic(mnemonic);
-    return this.seedToSimpleKeyPair(seed);
-  }
-
-  /**
-   * Generate a random private key
-   */
-  public generatePrivateKey(): Uint8Array {
-    return secp256k1.utils.randomSecretKey();
-  }
-
-  /**
-   * Get public key from private key
-   */
-  public getPublicKey(privateKey: Uint8Array): Uint8Array {
-    const publicKeyPoint = secp256k1.getPublicKey(privateKey, true); // compressed
-    return publicKeyPoint;
-  }
-
-  /**
-   * Generate ephemeral key pair for ECIES
-   */
-  public async generateEphemeralKeyPair(): Promise<ISimpleKeyPair> {
-    const privateKey = this.generatePrivateKey();
-    const publicKey = this.getPublicKey(privateKey);
-    return { privateKey, publicKey };
-  }
-
-  /**
-   * Compute ECDH shared secret
-   */
-  public computeSharedSecret(
-    privateKey: Uint8Array,
-    publicKey: Uint8Array,
-  ): Uint8Array {
-    // Normalize the public key to ensure it has the correct format
-    const normalizedPublicKey = this.normalizePublicKey(publicKey);
-
-    // Use uncompressed shared secret to match Node.js ECDH behavior
-    // Node.js ECDH.computeSecret() returns the x-coordinate of the shared point
-    const sharedSecret = secp256k1.getSharedSecret(
-      privateKey,
-      normalizedPublicKey,
-      false,
-    );
-    // Return only the x-coordinate (first 32 bytes after the 0x04 prefix)
-    return sharedSecret.slice(1, 33);
-  }
-
-  /**
-   * Derive a symmetric key from a shared secret using HKDF
-   * @param sharedSecret The shared secret (ECDH output)
-   * @param salt Optional salt
-   * @param info Optional context info
-   * @param length Length of the output key (default 32 for AES-256)
-   */
-  public deriveSharedKey(
-    sharedSecret: Uint8Array,
-    salt: Uint8Array = new Uint8Array(0),
-    info: Uint8Array = new Uint8Array(0),
-    length: number = 32,
-  ): Uint8Array {
-    return hkdf(sha256, sharedSecret, salt, info, length);
-  }
-
-  /**
-   * Sign a message using ECDSA
-   * @param privateKey The private key to sign with
-   * @param message The message to sign
-   */
-  public sign(privateKey: Uint8Array, message: Uint8Array): Uint8Array {
-    const hash = sha256(message);
-    const signature = secp256k1.sign(hash, privateKey);
-    if (signature instanceof Uint8Array) {
-      return signature;
-    }
-    // Check if signature has toCompactRawBytes method
-    if (
-      signature &&
-      typeof signature === 'object' &&
-      'toCompactRawBytes' in signature
-    ) {
-      const sig = signature as { toCompactRawBytes: () => Uint8Array };
-      if (typeof sig.toCompactRawBytes === 'function') {
-        return sig.toCompactRawBytes();
-      }
-    }
-    // Fallback or error
-    throw new Error('Unknown signature format');
-  }
-
-  /**
-   * Verify a signature using ECDSA
-   * @param publicKey The public key to verify with
-   * @param message The message that was signed
-   * @param signature The signature to verify
-   */
-  public verify(
-    publicKey: Uint8Array,
-    message: Uint8Array,
-    signature: Uint8Array,
-  ): boolean {
-    const hash = sha256(message);
-    try {
-      return secp256k1.verify(signature, hash, publicKey);
-    } catch (e) {
-      return false;
-    }
-  }
-}