@digitaldefiance/ecies-lib 1.1.24 → 1.1.26

package/src/secure-string.ts

@@ -1,229 +0,0 @@
-import { SecureStorageErrorType } from './enumerations/secure-storage-error-type';
-import { DisposedError } from './errors/disposed';
-import { SecureStorageError } from './errors/secure-storage';
-import { GuidV4 } from './guid';
-import { getEciesI18nEngine } from './i18n-setup';
-import { XorService } from './services/xor';
-import { FullHexGuid, RawGuidUint8Array } from './types';
-import { uint8ArrayToHex } from './utils';
-
-/**
- * A secure string buffer is a buffer whose intent is to prevent the raw password from being stored in memory.
- */
-export class SecureString {
-  private _disposed: boolean = false;
-  private readonly _isNull: boolean;
-  private readonly _id: GuidV4;
-  private readonly _length: number;
-  private readonly _obfuscatedValue: Uint8Array;
-  private readonly _key: Uint8Array;
-  private readonly _obfuscatedChecksum: Uint8Array;
-  private _disposedAt?: string;
-  constructor(data?: string | Uint8Array | null) {
-    this._id = GuidV4.new();
-    // only treat null/undefined as null, empty strings/arrays are valid empty data
-    if (data === null || data === undefined) {
-      this._isNull = true;
-      this._length = 0;
-      this._obfuscatedValue = new Uint8Array(0);
-      this._key = new Uint8Array(0);
-      this._obfuscatedChecksum = new Uint8Array(0);
-      return;
-    }
-    this._isNull = false;
-    this._key = this.idUint8Array;
-    const dataAsUint8Array =
-      typeof data === 'string'
-        ? new TextEncoder().encode(data)
-        : (data as Uint8Array);
-    // Store the byte length, not the character length
-    this._length = dataAsUint8Array.length;
-    this._obfuscatedValue = this.obfuscateData(dataAsUint8Array);
-    this._obfuscatedChecksum =
-      this.createSimpleObfuscatedChecksum(dataAsUint8Array);
-  }
-  private assertNotDisposed(): void {
-    if (this._disposed) {
-      const e = new DisposedError();
-      try {
-        (e as any).disposedAt = this._disposedAt;
-      } catch {
-        // ignore if Error object is sealed/frozen
-      }
-      throw e;
-    }
-  }
-  public dispose(): void {
-    const err = new DisposedError();
-    if (typeof (Error as any).captureStackTrace === 'function') {
-      (Error as any).captureStackTrace(err, this.dispose);
-    }
-    this._disposedAt = err.stack ?? 'stack unavailable';
-    this._obfuscatedValue.fill(0);
-    this._key.fill(0);
-    this._obfuscatedChecksum.fill(0);
-    this._disposed = true;
-  }
-  public get disposedAtStack(): string | undefined {
-    return this._disposedAt;
-  }
-  public get id(): FullHexGuid {
-    this.assertNotDisposed();
-    return this._id.asFullHexGuid;
-  }
-  public get idUint8Array(): RawGuidUint8Array {
-    this.assertNotDisposed();
-    return this._id.asRawGuidUint8Array;
-  }
-  public get originalLength(): number {
-    this.assertNotDisposed();
-    return this._length;
-  }
-  public get valueAsUint8Array(): Uint8Array {
-    this.assertNotDisposed();
-    if (this._isNull) {
-      return new Uint8Array(0);
-    }
-    try {
-      const deobfuscatedResult = this.deobfuscateData(this._obfuscatedValue);
-      if (deobfuscatedResult.length !== this._length) {
-        throw new SecureStorageError(
-          SecureStorageErrorType.DecryptedValueLengthMismatch,
-          getEciesI18nEngine() as any,
-        );
-      }
-
-      // Validate checksum
-      const expectedChecksum = this.createSimpleChecksum(deobfuscatedResult);
-      const storedChecksum = new TextDecoder().decode(
-        this.deobfuscateData(this._obfuscatedChecksum),
-      );
-
-      const expectedBytes = new TextEncoder().encode(expectedChecksum);
-      const storedBytes = new TextEncoder().encode(storedChecksum);
-      if (!this.timingSafeEqual(expectedBytes, storedBytes)) {
-        throw new SecureStorageError(
-          SecureStorageErrorType.DecryptedValueChecksumMismatch,
-          getEciesI18nEngine() as any,
-        );
-      }
-
-      return deobfuscatedResult;
-    } catch (error) {
-      // If it's already a SecureStorageError, re-throw it
-      if (error instanceof SecureStorageError) {
-        throw error;
-      }
-      // Convert any other error to SecureStorageError
-      throw new SecureStorageError(
-        SecureStorageErrorType.DecryptedValueChecksumMismatch,
-        getEciesI18nEngine() as any,
-      );
-    }
-  }
-  public get value(): string | null {
-    this.assertNotDisposed();
-    if (this._isNull) {
-      return null;
-    }
-    return new TextDecoder().decode(this.valueAsUint8Array);
-  }
-  public get notNullValue(): string {
-    this.assertNotDisposed();
-    if (this._isNull) {
-      throw new SecureStorageError(
-        SecureStorageErrorType.ValueIsNull,
-        getEciesI18nEngine() as any,
-      );
-    }
-    return new TextDecoder().decode(this.valueAsUint8Array);
-  }
-  public get valueAsHexString(): string {
-    this.assertNotDisposed();
-    return uint8ArrayToHex(this.valueAsUint8Array);
-  }
-  public get valueAsBase64String(): string {
-    this.assertNotDisposed();
-    return btoa(String.fromCharCode(...this.valueAsUint8Array));
-  }
-  public get hasValue(): boolean {
-    this.assertNotDisposed();
-    return !this._isNull && this._length > 0;
-  }
-  public get checksum(): string {
-    this.assertNotDisposed();
-    const deobfuscatedChecksum = new TextDecoder().decode(
-      this.deobfuscateData(this._obfuscatedChecksum),
-    );
-    return deobfuscatedChecksum;
-  }
-  public get length(): number {
-    this.assertNotDisposed();
-    return this._length;
-  }
-  private async generateChecksum(data: string | Uint8Array): Promise<string> {
-    const dataBytes =
-      typeof data === 'string' ? new TextEncoder().encode(data) : data;
-    const hashArray = await crypto.subtle.digest(
-      'SHA-256',
-      new Uint8Array(dataBytes),
-    );
-    return uint8ArrayToHex(new Uint8Array(hashArray));
-  }
-  private createSimpleChecksum(data: Uint8Array): string {
-    let hash = 0;
-    for (let i = 0; i < data.length; i++) {
-      hash = ((hash << 5) - hash + data[i]) & 0xffffffff;
-    }
-    return hash.toString(16);
-  }
-
-  private createSimpleObfuscatedChecksum(
-    data: string | Uint8Array,
-  ): Uint8Array {
-    const dataBytes =
-      typeof data === 'string' ? new TextEncoder().encode(data) : data;
-    const checksum = this.createSimpleChecksum(dataBytes);
-    return this.obfuscateData(new TextEncoder().encode(checksum));
-  }
-
-  private async createObfuscatedChecksum(
-    data: string | Uint8Array,
-  ): Promise<Uint8Array> {
-    const checksum = await this.generateChecksum(data);
-    const result = this.obfuscateData(new TextEncoder().encode(checksum));
-    return result;
-  }
-  private async validateChecksum(
-    data: string | Uint8Array,
-    checksum: string,
-  ): Promise<boolean> {
-    const generatedChecksum = await this.generateChecksum(data);
-    return generatedChecksum === checksum;
-  }
-
-  private timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
-    if (a.length !== b.length) {
-      return false;
-    }
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-      result |= a[i] ^ b[i];
-    }
-    return result === 0;
-  }
-  private async validateObfuscatedChecksum(
-    data: string | Uint8Array,
-  ): Promise<boolean> {
-    const deobfuscatedChecksum = new TextDecoder().decode(
-      this.deobfuscateData(this._obfuscatedChecksum),
-    );
-    return this.validateChecksum(data, deobfuscatedChecksum);
-  }
-  private obfuscateData(data: Uint8Array): Uint8Array {
-    return XorService.xor(data, this._key);
-  }
-  private deobfuscateData(data: Uint8Array): Uint8Array {
-    return XorService.xor(data, this._key);
-  }
-}

package/src/services/aes-gcm.ts

@@ -1,177 +0,0 @@
-import { IECIESConstants } from '../interfaces/ecies-consts';
-import { Constants } from '../constants';
-import { EciesComponentId, getEciesI18nEngine } from '../i18n-setup';
-import { EciesStringKey } from '../enumerations';
-
-export abstract class AESGCMService {
-  public static readonly ALGORITHM_NAME = 'AES-GCM';
-  /**
-   * Encrypt data using AES-GCM
-   * @param data Data to encrypt
-   * @param key Key to use for encryption (must be 16, 24 or 32 bytes for AES)
-   * @returns Encrypted data
-   */
-  public static async encrypt(
-    data: Uint8Array,
-    key: Uint8Array,
-    authTag: boolean = false,
-    eciesParams: IECIESConstants = Constants.ECIES,
-  ): Promise<{ encrypted: Uint8Array; iv: Uint8Array; tag?: Uint8Array }> {
-    const cryptoKey = await crypto.subtle.importKey(
-      'raw',
-      new Uint8Array(key),
-      { name: AESGCMService.ALGORITHM_NAME },
-      false,
-      ['encrypt'],
-    );
-
-    const eciesConsts = eciesParams;
-    const iv = crypto.getRandomValues(new Uint8Array(eciesConsts.IV_SIZE));
-    const encryptedResult = await crypto.subtle.encrypt(
-      {
-        name: AESGCMService.ALGORITHM_NAME,
-        iv,
-        ...(authTag && { tagLength: eciesConsts.AUTH_TAG_SIZE * 8 }),
-      },
-      cryptoKey,
-      new Uint8Array(data),
-    );
-
-    const encryptedArray = new Uint8Array(encryptedResult);
-    if (!authTag) {
-      return { encrypted: encryptedArray, iv };
-    }
-    const authTagLengthBytes = eciesConsts.AUTH_TAG_SIZE;
-    const encryptedBytes = encryptedArray.slice(0, -authTagLengthBytes); // Remove auth tag
-    const authTagBytes = encryptedArray.slice(-authTagLengthBytes); // Last 16 bytes are auth tag
-
-    return { encrypted: encryptedBytes, iv, tag: authTagBytes };
-  }
-
-  /**
-   * Combine encrypted data and auth tag into a single Uint8Array
-   * @param encryptedData The encrypted data
-   * @param authTag The authentication tag
-   * @returns The combined Uint8Array
-   */
-  public static combineEncryptedDataAndTag(
-    encryptedData: Uint8Array,
-    authTag: Uint8Array,
-  ): Uint8Array {
-    const combined = new Uint8Array(encryptedData.length + authTag.length);
-    combined.set(encryptedData);
-    combined.set(authTag, encryptedData.length);
-    return combined;
-  }
-
-  /**
-   * Combine IV and encrypted data (with optional auth tag) into a single Uint8Array
-   * @param iv The initialization vector
-   * @param encryptedDataWithTag The encrypted data with auth tag already appended (if applicable)
-   * @returns The combined Uint8Array
-   */
-  public static combineIvAndEncryptedData(
-    iv: Uint8Array,
-    encryptedDataWithTag: Uint8Array,
-  ): Uint8Array {
-    const combined = new Uint8Array(iv.length + encryptedDataWithTag.length);
-    combined.set(iv);
-    combined.set(encryptedDataWithTag, iv.length);
-    return combined;
-  }
-
-  /**
-   * Combine IV, encrypted data and auth tag into a single Uint8Array
-   * @param iv The initialization vector
-   * @param encryptedData The encrypted data
-   * @param authTag The authentication tag
-   * @returns The combined Uint8Array
-   */
-  public static combineIvTagAndEncryptedData(
-    iv: Uint8Array,
-    encryptedData: Uint8Array,
-    authTag: Uint8Array,
-  ): Uint8Array {
-    const encryptedWithTag = AESGCMService.combineEncryptedDataAndTag(
-      encryptedData,
-      authTag,
-    );
-    return AESGCMService.combineIvAndEncryptedData(iv, encryptedWithTag);
-  }
-
-  /**
-   * Split combined encrypted data back into its components
-   * @param combinedData The combined data containing IV, encrypted data, and optionally auth tag
-   * @param hasAuthTag Whether the combined data includes an authentication tag
-   * @returns Object containing the split components
-   */
-  public static splitEncryptedData(
-    combinedData: Uint8Array,
-    hasAuthTag: boolean = true,
-    eciesParams: IECIESConstants = Constants.ECIES,
-  ): { iv: Uint8Array; encryptedDataWithTag: Uint8Array } {
-    const eciesConsts = eciesParams;
-    const ivLength = eciesConsts.IV_SIZE;
-    const tagLength = hasAuthTag ? eciesConsts.AUTH_TAG_SIZE : 0;
-
-    if (combinedData.length < ivLength + tagLength) {
-      const engine = getEciesI18nEngine();
-      throw new Error(
-        engine.translate(EciesComponentId, EciesStringKey.Error_ECIESError_CombinedDataTooShortForComponents),
-      );
-    }
-
-    const iv = combinedData.slice(0, ivLength);
-    const encryptedDataWithTag = combinedData.slice(ivLength);
-
-    return { iv, encryptedDataWithTag };
-  }
-
-  /**
-   * Decrypt data using AES-GCM
-   * @param iv The initialization vector
-   * @param encryptedData Data to decrypt (with auth tag appended if authTag is true)
-   * @param key Key to use for decryption (must be 16, 24 or 32 bytes for AES)
-   * @param authTag Whether the encrypted data includes an authentication tag
-   * @returns Decrypted data
-   */
-  public static async decrypt(
-    iv: Uint8Array,
-    encryptedData: Uint8Array,
-    key: Uint8Array,
-    authTag: boolean = false,
-    eciesParams: IECIESConstants = Constants.ECIES,
-  ): Promise<Uint8Array> {
-    const eciesConsts = eciesParams;
-    const cryptoKey = await crypto.subtle.importKey(
-      'raw',
-      new Uint8Array(key),
-      { name: AESGCMService.ALGORITHM_NAME },
-      false,
-      ['decrypt'],
-    );
-
-    if (!authTag) {
-      const decrypted = await crypto.subtle.decrypt(
-        { name: AESGCMService.ALGORITHM_NAME, iv: new Uint8Array(iv) },
-        cryptoKey,
-        new Uint8Array(encryptedData),
-      );
-
-      return new Uint8Array(decrypted);
-    }
-
-    // Decrypt with auth tag (already appended to encryptedData)
-    const decryptedResult = await crypto.subtle.decrypt(
-      {
-        name: AESGCMService.ALGORITHM_NAME,
-        iv: new Uint8Array(iv),
-        tagLength: eciesConsts.AUTH_TAG_SIZE * 8,
-      },
-      cryptoKey,
-      new Uint8Array(encryptedData),
-    );
-
-    return new Uint8Array(decryptedResult);
-  }
-}

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.