@digitaldefiance/ecies-lib 4.4.2 → 4.4.4

package/src/services/pbkdf2.ts

@@ -0,0 +1,169 @@
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { Constants } from '../constants';
+import { Pbkdf2ErrorType } from '../enumerations/pbkdf2-error-type';
+import { Pbkdf2ProfileEnum } from '../enumerations/pbkdf2-profile';
+import { Pbkdf2Error } from '../errors/pbkdf2';
+import { IPbkdf2Config } from '../interfaces/pbkdf2-config';
+import { IPbkdf2Result } from '../interfaces/pbkdf2-result';
+import { IECIESConstants } from '../interfaces/ecies-consts';
+import { IPBkdf2Consts } from '../interfaces/pbkdf2-consts';
+
+/**
+ * Service for handling PBKDF2 (Password-Based Key Derivation Function 2) operations.
+ * This service provides functionality for:
+ * - Generating secure key derivation configurations
+ * - Deriving cryptographic keys from passwords
+ * - Managing salt and iteration parameters
+ * - Both synchronous and asynchronous key derivation
+ */
+export class Pbkdf2Service {
+  protected readonly profiles: Record<string, IPbkdf2Config>;
+  protected readonly eciesConsts: IECIESConstants;
+  protected readonly pbkdf2Consts: IPBkdf2Consts;
+  
+  constructor(
+    profiles: Record<string, IPbkdf2Config> = Constants.PBKDF2_PROFILES,
+    eciesParams: IECIESConstants = Constants.ECIES,
+    pbkdf2Params: IPBkdf2Consts = Constants.PBKDF2,
+  ) {
+    this.profiles = profiles;
+    this.eciesConsts = eciesParams;
+    this.pbkdf2Consts = pbkdf2Params;
+  }
+  /**
+   * Get a predefined configuration profile for common use cases
+   * @param profile The name of the profile to use
+   * @returns Configuration object for the specified profile
+   */
+  public getProfileConfig(
+    profile: string,
+  ): IPbkdf2Config {
+    const profileConfig = this.profiles[profile];
+    if (!profileConfig) {
+      throw new Pbkdf2Error(Pbkdf2ErrorType.InvalidProfile);
+    }
+    return {
+      hashBytes: profileConfig.hashBytes,
+      saltBytes: profileConfig.saltBytes,
+      iterations: profileConfig.iterations,
+      algorithm: profileConfig.algorithm,
+    };
+  }
+
+  /**
+   * Generate an options object for pbkdf2
+   * @param iterations Optional number of iterations (defaults to Pbkdf2IterationsPerSecond)
+   * @param saltBytes Optional salt size in bytes (defaults to PBKDF2.SALT_BYTES)
+   * @param hashBytes Optional hash size in bytes (defaults to ECIES.SYMMETRIC.KEY_SIZE)
+   * @param algorithm Optional hash algorithm (defaults to PBKDF2.ALGORITHM)
+   * @returns Configuration object for PBKDF2
+   */
+  public getConfig(
+    iterations?: number,
+    saltBytes?: number,
+    hashBytes?: number,
+    algorithm?: string,
+  ): IPbkdf2Config {
+    // larger numbers mean better security, less
+    return {
+      // size of the generated hash
+      hashBytes: hashBytes ?? this.eciesConsts.SYMMETRIC.KEY_SIZE,
+      // larger salt means hashed passwords are more resistant to rainbow table, but
+      // you get diminishing returns pretty fast
+      saltBytes: saltBytes ?? this.pbkdf2Consts.SALT_BYTES,
+      // more iterations means an attacker has to take longer to brute force an
+      // individual password, so larger is better. however, larger also means longer
+      // to hash the password. tune so that hashing the password takes about a
+      // second
+      iterations: iterations ?? this.pbkdf2Consts.ITERATIONS_PER_SECOND,
+      // hash algorithm
+      algorithm: algorithm ?? this.pbkdf2Consts.ALGORITHM,
+    };
+  }
+
+  /**
+   * Given a password, use pbkdf2 to generate an appropriately sized key for AES encryption
+   * @param password The password to derive a key from
+   * @param salt Optional salt (will be randomly generated if not provided)
+   * @param iterations Optional number of iterations
+   * @param saltBytes Optional salt size in bytes
+   * @param keySize Optional key size in bytes
+   * @param algorithm Optional hash algorithm
+   * @returns Object containing the derived key, salt, and iteration count
+   */
+  public async deriveKeyFromPasswordAsync(
+    password: Uint8Array,
+    salt?: Uint8Array,
+    iterations?: number,
+    saltBytes?: number,
+    keySize?: number,
+    algorithm?: string,
+  ): Promise<IPbkdf2Result> {
+    const config = this.getConfig(
+      iterations,
+      saltBytes,
+      keySize,
+      algorithm,
+    );
+    const saltBytes_ =
+      salt ?? crypto.getRandomValues(new Uint8Array(config.saltBytes));
+
+    if (saltBytes_.length !== config.saltBytes) {
+      throw new Pbkdf2Error(Pbkdf2ErrorType.InvalidSaltLength);
+    }
+
+    const keyMaterial = await crypto.subtle.importKey(
+      'raw',
+      new Uint8Array(password),
+      'PBKDF2',
+      false,
+      ['deriveBits'],
+    );
+
+    const keyArray = await crypto.subtle.deriveBits(
+      {
+        name: 'PBKDF2',
+        salt: new Uint8Array(saltBytes_),
+        iterations: config.iterations,
+        hash: config.algorithm,
+      },
+      keyMaterial,
+      config.hashBytes * 8,
+    );
+
+    const keyBytes = new Uint8Array(keyArray);
+
+    if (keyBytes.length !== config.hashBytes) {
+      throw new Pbkdf2Error(Pbkdf2ErrorType.InvalidHashLength);
+    }
+
+    return {
+      salt: saltBytes_,
+      hash: keyBytes,
+      iterations: config.iterations,
+    };
+  }
+
+  /**
+   * Derive a key using a predefined configuration profile
+   * @param password The password to derive a key from
+   * @param profile The configuration profile to use
+   * @param salt Optional salt (will be randomly generated if not provided)
+   * @returns Object containing the derived key, salt, and iteration count
+   */
+  public async deriveKeyFromPasswordWithProfileAsync(
+    password: Uint8Array,
+    profile: Pbkdf2ProfileEnum,
+    salt?: Uint8Array,
+  ): Promise<IPbkdf2Result> {
+    const config = this.getProfileConfig(profile);
+    return await this.deriveKeyFromPasswordAsync(
+      password,
+      salt,
+      config.iterations,
+      config.saltBytes,
+      config.hashBytes,
+      config.algorithm,
+    );
+  }
+}

package/src/services/progress-tracker.ts

@@ -0,0 +1,128 @@
+import { EciesStringKey } from '../enumerations/ecies-string-key';
+import { EciesComponentId, getEciesI18nEngine } from '../i18n-setup';
+import { IStreamProgress } from '../interfaces/stream-progress';
+
+/**
+ * Tracks progress for streaming operations
+ */
+export class ProgressTracker {
+  private startTime: number;
+  private lastUpdateTime: number;
+  private bytesProcessed: number = 0;
+  private chunksProcessed: number = 0;
+  private recentThroughputs: number[] = [];
+  private readonly maxThroughputSamples = 5;
+
+  constructor(private readonly totalBytes?: number) {
+    this.startTime = Date.now();
+    this.lastUpdateTime = this.startTime;
+  }
+
+  /**
+   * Update progress with new chunk
+   */
+  update(chunkBytes: number): IStreamProgress {
+    // Validate input
+    if (chunkBytes < 0) {
+      const engine = getEciesI18nEngine();
+      throw new Error(
+        engine.translate(
+          EciesComponentId,
+          EciesStringKey.Error_Progress_ChunkBytesCannotBeNegative,
+        ),
+      );
+    }
+
+    this.bytesProcessed += chunkBytes;
+    this.chunksProcessed++;
+
+    const now = Date.now();
+    const elapsedTime = Math.max(0, now - this.startTime);
+    const timeSinceLastUpdate = Math.max(0, now - this.lastUpdateTime);
+
+    // Calculate instantaneous throughput (use elapsed time if same millisecond)
+    const timeWindow =
+      timeSinceLastUpdate > 0 ? timeSinceLastUpdate : Math.max(1, elapsedTime);
+    if (chunkBytes > 0 && timeWindow > 0) {
+      const instantThroughput = (chunkBytes / timeWindow) * 1000;
+      // Guard against unrealistic throughput (>10GB/s)
+      if (
+        isFinite(instantThroughput) &&
+        instantThroughput < 10 * 1024 * 1024 * 1024
+      ) {
+        this.recentThroughputs.push(instantThroughput);
+        if (this.recentThroughputs.length > this.maxThroughputSamples) {
+          this.recentThroughputs.shift();
+        }
+      }
+    }
+
+    this.lastUpdateTime = now;
+
+    // Calculate average throughput
+    const throughput =
+      this.recentThroughputs.length > 0
+        ? this.recentThroughputs.reduce((a, b) => a + b, 0) /
+          this.recentThroughputs.length
+        : 0;
+
+    // Calculate ETA (guard against negative)
+    let estimatedTimeRemaining: number | undefined;
+    if (
+      this.totalBytes &&
+      throughput > 0 &&
+      this.bytesProcessed < this.totalBytes
+    ) {
+      const remainingBytes = this.totalBytes - this.bytesProcessed;
+      estimatedTimeRemaining = Math.max(0, remainingBytes / throughput);
+    }
+
+    return {
+      bytesProcessed: this.bytesProcessed,
+      totalBytes: this.totalBytes,
+      chunksProcessed: this.chunksProcessed,
+      percentComplete: this.totalBytes
+        ? Math.min(100, (this.bytesProcessed / this.totalBytes) * 100)
+        : undefined,
+      throughputBytesPerSec: throughput,
+      estimatedTimeRemaining,
+      startTime: this.startTime,
+      elapsedTime,
+    };
+  }
+
+  /**
+   * Get current progress without update
+   */
+  getProgress(): IStreamProgress {
+    const elapsedTime = Math.max(0, Date.now() - this.startTime);
+    const throughput =
+      this.recentThroughputs.length > 0
+        ? this.recentThroughputs.reduce((a, b) => a + b, 0) /
+          this.recentThroughputs.length
+        : 0;
+
+    let estimatedTimeRemaining: number | undefined;
+    if (
+      this.totalBytes &&
+      throughput > 0 &&
+      this.bytesProcessed < this.totalBytes
+    ) {
+      const remainingBytes = this.totalBytes - this.bytesProcessed;
+      estimatedTimeRemaining = Math.max(0, remainingBytes / throughput);
+    }
+
+    return {
+      bytesProcessed: this.bytesProcessed,
+      totalBytes: this.totalBytes,
+      chunksProcessed: this.chunksProcessed,
+      percentComplete: this.totalBytes
+        ? Math.min(100, (this.bytesProcessed / this.totalBytes) * 100)
+        : undefined,
+      throughputBytesPerSec: throughput,
+      estimatedTimeRemaining,
+      startTime: this.startTime,
+      elapsedTime,
+    };
+  }
+}

package/src/services/resumable-encryption.ts

@@ -0,0 +1,135 @@
+import { IEncryptionState, ENCRYPTION_STATE_VERSION } from '../interfaces/encryption-state';
+import { IEncryptedChunk } from '../interfaces/encrypted-chunk';
+import { EncryptionStream } from './encryption-stream';
+import { IEncryptStreamOptions } from './encryption-stream';
+import { uint8ArrayToHex, hexToUint8Array } from '../utils';
+import { EciesEncryptionTypeEnum } from '../enumerations/ecies-encryption-type';
+import { getEciesI18nEngine, EciesComponentId } from '../i18n-setup';
+import { EciesStringKey } from '../enumerations/ecies-string-key';
+
+
+export interface IResumableOptions extends IEncryptStreamOptions {
+  autoSaveInterval?: number;
+  onStateSaved?: (state: IEncryptionState) => void | Promise<void>;
+}
+
+export class ResumableEncryption {
+  private state: IEncryptionState | null = null;
+
+  constructor(
+    private readonly stream: EncryptionStream,
+    initialState?: IEncryptionState
+  ) {
+    if (initialState) {
+      this.validateState(initialState);
+      this.state = initialState;
+    }
+  }
+
+  async *encrypt(
+    source: AsyncIterable<Uint8Array>,
+    publicKey: Uint8Array,
+    options: IResumableOptions = {}
+  ): AsyncGenerator<IEncryptedChunk, void, unknown> {
+    const engine = getEciesI18nEngine();
+    const autoSaveInterval = options.autoSaveInterval ?? 10;
+    if (autoSaveInterval <= 0) {
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_AutoSaveIntervalMustBePositive));
+    }
+
+    const publicKeyHex = uint8ArrayToHex(publicKey);
+    if (this.state) {
+      if (this.state.publicKey !== publicKeyHex) {
+        throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_PublicKeyMismatch));
+      }
+      if (this.state.chunkSize !== (options.chunkSize ?? 1024 * 1024)) {
+        throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_ChunkSizeMismatch));
+      }
+      if (this.state.includeChecksums !== (options.includeChecksums ?? false)) {
+        throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_IncludeChecksumsMismatch));
+      }
+    }
+
+    const startIndex = this.state?.chunkIndex ?? 0;
+
+    let chunkIndex = 0;
+    for await (const chunk of this.stream.encryptStream(source, publicKey, options)) {
+      if (chunkIndex < startIndex) {
+        chunkIndex++;
+        continue;
+      }
+
+      yield chunk;
+
+      this.state = {
+        version: ENCRYPTION_STATE_VERSION,
+        chunkIndex: chunk.index + 1,
+        bytesProcessed: (this.state?.bytesProcessed ?? 0) + (chunk.metadata?.originalSize ?? 0),
+        publicKey: publicKeyHex,
+        encryptionType: EciesEncryptionTypeEnum.Single,
+        chunkSize: options.chunkSize ?? 1024 * 1024,
+        includeChecksums: options.includeChecksums ?? false,
+        timestamp: Date.now(),
+      };
+
+      if (options.onStateSaved && (chunk.index + 1) % autoSaveInterval === 0) {
+        await options.onStateSaved({ ...this.state });
+      }
+
+      chunkIndex++;
+    }
+  }
+
+  saveState(): IEncryptionState {
+    if (!this.state) {
+      const engine = getEciesI18nEngine();
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_NoStateToSave));
+    }
+    const state = { ...this.state };
+    // Add HMAC for integrity
+    state.hmac = this.calculateStateHMAC(state);
+    return state;
+  }
+
+  private calculateStateHMAC(state: IEncryptionState): string {
+    const data = `${state.version}|${state.chunkIndex}|${state.bytesProcessed}|${state.publicKey}|${state.chunkSize}|${state.includeChecksums}|${state.timestamp}`;
+    const hash = new Uint8Array(32);
+    // Simple hash for integrity check (not cryptographic HMAC)
+    const bytes = new TextEncoder().encode(data);
+    for (let i = 0; i < bytes.length; i++) {
+      hash[i % 32] ^= bytes[i];
+    }
+    return uint8ArrayToHex(hash);
+  }
+
+  static resume(
+    stream: EncryptionStream,
+    state: IEncryptionState
+  ): ResumableEncryption {
+    return new ResumableEncryption(stream, state);
+  }
+
+  private validateState(state: IEncryptionState): void {
+    const engine = getEciesI18nEngine();
+    if (state.version !== ENCRYPTION_STATE_VERSION) {
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_UnsupportedStateVersionTemplate, { version: state.version }));
+    }
+    if (state.chunkIndex < 0) {
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_InvalidChunkIndex));
+    }
+    const age = Date.now() - state.timestamp;
+    if (age > 24 * 60 * 60 * 1000) {
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_StateTooOld));
+    }
+    if (!state.publicKey || state.publicKey.length === 0) {
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_InvalidPublicKeyInState));
+    }
+    // Verify HMAC if present
+    if (state.hmac) {
+      const expectedHMAC = this.calculateStateHMAC(state);
+      if (state.hmac !== expectedHMAC) {
+        throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_Resumable_StateIntegrityCheckFailed));
+      }
+    }
+  }
+}

package/src/services/xor.ts

@@ -0,0 +1,65 @@
+/**
+ * A simple and fast XOR cipher for obfuscating data in memory for browser environments.
+ * This is not a substitute for strong cryptography but provides a lightweight way
+ * to prevent sensitive data from being stored in plaintext in memory.
+ */
+export class XorService {
+  /**
+   * Encrypts or decrypts data using a simple XOR cipher.
+   * The key is XORed with the data. The same function is used for
+   * both encryption and decryption.
+   *
+   * @param data The data to process.
+   * @param key The key to use for the XOR operation.
+   * @returns A new Uint8Array containing the result of the XOR operation.
+   */
+  public static xor(data: Uint8Array, key: Uint8Array): Uint8Array {
+    const result = new Uint8Array(data.length);
+    for (let i = 0; i < data.length; i++) {
+      result[i] = data[i] ^ key[i % key.length];
+    }
+    return result;
+  }
+
+  /**
+   * Generates a random key of a specified length.
+   * @param length The length of the key in bytes.
+   * @returns A Uint8Array containing the random key.
+   * @throws Error if crypto API is not available.
+   */
+  public static generateKey(length: number): Uint8Array {
+    const randomBytes = new Uint8Array(length);
+
+    // Check if running in a browser with crypto support
+    if (typeof window !== 'undefined' && window.crypto) {
+      window.crypto.getRandomValues(randomBytes);
+    } else if (typeof crypto !== 'undefined') {
+      // For environments where crypto is global (some newer JS runtimes)
+      crypto.getRandomValues(randomBytes);
+    } else {
+      throw new Error('Crypto API not available in this environment');
+    }
+
+    return randomBytes;
+  }
+
+  /**
+   * Helper method to convert a string to a Uint8Array.
+   * @param str The string to convert.
+   * @returns A Uint8Array representation of the string.
+   */
+  public static stringToBytes(str: string): Uint8Array {
+    const encoder = new TextEncoder();
+    return encoder.encode(str);
+  }
+
+  /**
+   * Helper method to convert a Uint8Array to a string.
+   * @param bytes The Uint8Array to convert.
+   * @returns A string representation of the Uint8Array.
+   */
+  public static bytesToString(bytes: Uint8Array): string {
+    const decoder = new TextDecoder();
+    return decoder.decode(bytes);
+  }
+}

package/src/test-mocks/index.ts

@@ -0,0 +1 @@
+export * from './mock-frontend-member';