@digitaldefiance/ecies-lib 4.4.11 → 4.4.14

package/src/interfaces/configuration-provenance.ts

@@ -1,54 +0,0 @@
-import type { DeepPartial } from '../types/deep-partial';
-import type { IConstants } from './constants';
-
-/**
- * Provenance information for a configuration.
- * Tracks who created it, when, and what modifications were made.
- */
-export interface IConfigurationProvenance {
-  /**
-   * The base configuration key this was derived from
-   */
-  readonly baseConfigKey: string;
-
-  /**
-   * Overrides applied to the base configuration
-   */
-  readonly overrides: DeepPartial<IConstants>;
-
-  /**
-   * When this configuration was created
-   */
-  readonly timestamp: Date;
-
-  /**
-   * Source of the configuration
-   * - 'default': The built-in Constants
-   * - 'runtime': Created via createRuntimeConfiguration
-   * - 'custom': User-provided full configuration
-   */
-  readonly source: 'default' | 'runtime' | 'custom';
-
-  /**
-   * SHA-256 checksum of the final configuration
-   * Useful for verifying configuration hasn't been tampered with
-   */
-  readonly checksum: string;
-
-  /**
-   * Optional description or notes about this configuration
-   */
-  readonly description?: string;
-
-  /**
-   * Stack trace showing where the configuration was created
-   * Useful for debugging unexpected configurations
-   */
-  readonly creationStack?: string;
-}
-
-// Re-export utility functions from lib
-export {
-  calculateConfigChecksum,
-  captureCreationStack,
-} from '../lib/configuration-provenance-utils';

package/src/interfaces/constants.ts

@@ -1,75 +0,0 @@
-import type { Pbkdf2Profiles } from '../pbkdf2-profiles';
-import type { IChecksumConsts } from './checksum-consts';
-import type { IECIESConstants } from './ecies-consts';
-import type { IIdProvider } from './id-provider';
-import type { IPBkdf2Consts } from './pbkdf2-consts';
-
-export interface IConstants {
-  UINT8_SIZE: number;
-  UINT16_SIZE: number;
-  UINT16_MAX: number;
-  UINT32_SIZE: number;
-  UINT32_MAX: number;
-  UINT64_SIZE: number;
-  UINT64_MAX: bigint;
-  HEX_RADIX: number;
-
-  /**
-   * The length of user IDs in the system.
-   * This is dynamically determined by the configured ID provider.
-   * @deprecated Use idProvider.byteLength instead for direct access
-   */
-  MEMBER_ID_LENGTH: number;
-
-  /**
-   * The length of a raw object ID (not the hex string representation).
-   * Standard MongoDB ObjectID is 12 bytes.
-   * @deprecated Use idProvider.byteLength instead for direct access
-   */
-  OBJECT_ID_LENGTH: number;
-
-  /**
-   * ID provider for recipient identification in multi-recipient encryption.
-   * This determines the format and size of recipient IDs used throughout the system.
-   *
-   * Default: ObjectIdProvider (12 bytes, MongoDB compatible)
-   *
-   * @example
-   * ```typescript
-   * import { GuidV4Provider } from './lib/id-providers';
-   *
-   * // Use GUIDs instead of ObjectIDs
-   * const config = createRuntimeConfiguration({
-   *   idProvider: new GuidV4Provider()
-   * });
-   * ```
-   */
-  idProvider: IIdProvider;
-
-  CHECKSUM: IChecksumConsts;
-  ECIES: IECIESConstants;
-  PBKDF2: IPBkdf2Consts;
-  PBKDF2_PROFILES: Pbkdf2Profiles;
-
-  /**
-   * Number of rounds for bcrypt hashing. Higher values increase security but also consume more CPU resources.
-   */
-  BcryptRounds: number;
-  /**
-   * Minimum password length
-   */
-  PasswordMinLength: number;
-  /**
-   * The regular expression for valid passwords.
-   */
-  PasswordRegex: RegExp;
-  /**
-   * The regular expression for valid mnemonic phrases.
-   * BIP39
-   */
-  MnemonicRegex: RegExp;
-  /**
-   * The regular expression for valid HMAC keys.
-   */
-  MnemonicHmacRegex: RegExp;
-}

package/src/interfaces/ecies-config.ts

@@ -1,8 +0,0 @@
-export interface IECIESConfig {
-  curveName: string;
-  primaryKeyDerivationPath: string;
-  mnemonicStrength: number;
-  symmetricAlgorithm: string;
-  symmetricKeyBits: number;
-  symmetricKeyMode: string;
-}

package/src/interfaces/ecies-consts.ts

@@ -1,74 +0,0 @@
-import { CipherGCMTypes } from 'crypto';
-export interface IECIESConstants {
-  /** The elliptic curve to use for all ECDSA operations */
-  CURVE_NAME: string;
-
-  /** The primary key derivation path for HD wallets */
-  PRIMARY_KEY_DERIVATION_PATH: string;
-
-  SYMMETRIC_ALGORITHM_CONFIGURATION: CipherGCMTypes;
-
-  /** Length of ECDSA signatures in bytes */
-  SIGNATURE_SIZE: number;
-
-  /** Length of raw public keys in bytes (without 0x04 prefix) */
-  RAW_PUBLIC_KEY_LENGTH: number;
-
-  /** Length of public keys in bytes (with 0x04 prefix) */
-  PUBLIC_KEY_LENGTH: number;
-
-  PUBLIC_KEY_MAGIC: number;
-
-  /** Mnemonic strength in bits. This will produce a 32-bit key for ECDSA */
-  MNEMONIC_STRENGTH: number;
-
-  /** Symmetric encryption algorithm configuration */
-  SYMMETRIC: {
-    ALGORITHM: string;
-    MODE: string;
-    KEY_BITS: number;
-    KEY_SIZE: number; // KEY_BITS / 8
-  };
-
-  IV_SIZE: number;
-  AUTH_TAG_SIZE: number;
-  MAX_RAW_DATA_SIZE: number; // 2^53 - 1 (max safe integer for JS)
-
-  VERSION_SIZE: number;
-  CIPHER_SUITE_SIZE: number;
-  ENCRYPTION_TYPE_SIZE: number;
-
-  /**
-   * Message encrypts without data length or crc
-   */
-  SIMPLE: {
-    FIXED_OVERHEAD_SIZE: number; // type (1) + public key (65) + IV (16) + auth tag (16)
-    DATA_LENGTH_SIZE: number;
-  };
-
-  /**
-   * Message encrypts like single but with data Length and crc
-   */
-  SINGLE: {
-    FIXED_OVERHEAD_SIZE: number; // type (1) + public key (65) + IV (16) + auth tag (16) + data length (8) + crc16 (2)
-    DATA_LENGTH_SIZE: number;
-  };
-
-  /**
-   * Message encrypts for multiple recipients
-   */
-  MULTIPLE: {
-    FIXED_OVERHEAD_SIZE: number;
-    ENCRYPTED_KEY_SIZE: number;
-    MAX_RECIPIENTS: number;
-    RECIPIENT_ID_SIZE: number;
-    RECIPIENT_COUNT_SIZE: number;
-    DATA_LENGTH_SIZE: number;
-  };
-
-  ENCRYPTION_TYPE: {
-    SIMPLE: number;
-    SINGLE: number;
-    MULTIPLE: number;
-  };
-}

package/src/interfaces/ecies-file-service.ts

@@ -1,6 +0,0 @@
-export interface IEciesFileService {
-  encryptFile(file: File, recipientPublicKey: Uint8Array): Promise<Uint8Array>;
-  decryptFile(encryptedData: Uint8Array): Promise<Uint8Array>;
-  downloadEncryptedFile(encryptedData: Uint8Array, filename: string): void;
-  downloadDecryptedFile(decryptedData: Uint8Array, filename: string): void;
-}

package/src/interfaces/encrypted-chunk.ts

@@ -1,64 +0,0 @@
-/**
- * Metadata for an encrypted chunk
- */
-export interface IChunkMetadata {
-  /** Original size before encryption */
-  originalSize: number;
-  /** Size after encryption */
-  encryptedSize: number;
-  /** Timestamp when chunk was encrypted */
-  timestamp: number;
-  /** Optional SHA-256 checksum of original data */
-  checksum?: Uint8Array;
-}
-
-/**
- * Represents a single encrypted chunk in a stream
- */
-export interface IEncryptedChunk {
-  /** Chunk sequence number (0-based) */
-  index: number;
-  /** Encrypted chunk data */
-  data: Uint8Array;
-  /** Whether this is the final chunk */
-  isLast: boolean;
-  /** Chunk metadata */
-  metadata?: IChunkMetadata;
-}
-
-/**
- * Chunk header structure (32 bytes fixed)
- */
-export interface IChunkHeader {
-  /** Magic bytes: 0x45434945 ("ECIE") */
-  magic: number;
-  /** Version: 0x0001 */
-  version: number;
-  /** Chunk index */
-  index: number;
-  /** Original size */
-  originalSize: number;
-  /** Encrypted size */
-  encryptedSize: number;
-  /** Flags (bit 0: isLast, bit 1: hasChecksum) */
-  flags: number;
-}
-
-/**
- * Constants for chunk format
- */
-export const CHUNK_CONSTANTS: {
-  readonly MAGIC: 0x45434945;
-  readonly VERSION: 0x0001;
-  readonly HEADER_SIZE: 32;
-  readonly FLAG_IS_LAST: 0x01;
-  readonly FLAG_HAS_CHECKSUM: 0x02;
-  readonly CHECKSUM_SIZE: 32;
-} = {
-  MAGIC: 0x45434945, // "ECIE"
-  VERSION: 0x0001,
-  HEADER_SIZE: 32,
-  FLAG_IS_LAST: 0x01,
-  FLAG_HAS_CHECKSUM: 0x02,
-  CHECKSUM_SIZE: 32, // SHA-256
-} as const;

package/src/interfaces/encryption-state.ts

@@ -1,19 +0,0 @@
-import type { EciesEncryptionTypeEnum } from '../enumerations/ecies-encryption-type';
-
-/**
- * Serializable encryption state for resumption
- */
-export interface IEncryptionState {
-  version: number;
-  chunkIndex: number;
-  bytesProcessed: number;
-  totalBytes?: number;
-  publicKey: string; // hex
-  encryptionType: EciesEncryptionTypeEnum;
-  chunkSize: number;
-  includeChecksums: boolean;
-  timestamp: number;
-  hmac?: string; // hex SHA-256 HMAC for integrity
-}
-
-export const ENCRYPTION_STATE_VERSION: number = 1;

package/src/interfaces/frontend-member-operational.ts

@@ -1,77 +0,0 @@
-import type { Wallet } from '@ethereumjs/wallet';
-import type { EmailString } from '../email-string';
-import type MemberType from '../enumerations/member-type';
-import type { SecureBuffer } from '../secure-buffer';
-import type { SecureString } from '../secure-string';
-import type { SignatureUint8Array } from '../types';
-import type { IECIESConstants } from './ecies-consts';
-import type { IEncryptedChunk } from './encrypted-chunk';
-import type { ProgressCallback } from './stream-progress';
-
-/**
- * Operational interface for member - defines getters and methods
- */
-export interface IFrontendMemberOperational<
-  TID = Uint8Array,
-  TData = Uint8Array,
-  TSignature = SignatureUint8Array,
-> {
-  // Required getters
-  get id(): TID;
-  get type(): MemberType;
-  get name(): string;
-  get email(): EmailString;
-  get publicKey(): Uint8Array;
-  get creatorId(): TID;
-  get dateCreated(): Date;
-  get dateUpdated(): Date;
-
-  // Optional private data getters
-  get privateKey(): SecureBuffer | undefined;
-  get wallet(): Wallet | undefined;
-
-  // State getters
-  get hasPrivateKey(): boolean;
-
-  // Methods
-  sign(data: TData): TSignature;
-  verify(signature: TSignature, data: TData): boolean;
-  encryptData(
-    data: string | TData,
-    recipientPublicKey?: Uint8Array,
-  ): Promise<TData>;
-  decryptData(encryptedData: TData): Promise<TData>;
-  toJson(): string;
-  dispose(): void;
-
-  // Streaming methods
-  encryptDataStream(
-    source: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>,
-    options?: {
-      recipientPublicKey?: Uint8Array;
-      onProgress?: ProgressCallback;
-      signal?: AbortSignal;
-    },
-  ): AsyncGenerator<IEncryptedChunk, void, unknown>;
-
-  decryptDataStream(
-    source: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>,
-    options?: {
-      onProgress?: ProgressCallback;
-      signal?: AbortSignal;
-    },
-  ): AsyncGenerator<Uint8Array, void, unknown>;
-
-  // Private key management
-  loadWallet(mnemonic: SecureString, eciesParams?: IECIESConstants): void;
-  unloadPrivateKey(): void;
-  unloadWallet(): void;
-  unloadWalletAndPrivateKey(): void;
-}
-
-/**
- * Extended operational interface for test members
- */
-export interface ITestMemberOperational extends IFrontendMemberOperational {
-  get mnemonic(): SecureString | undefined;
-}

package/src/interfaces/guid.ts

@@ -1,86 +0,0 @@
-import {
-  Base64Guid,
-  BigIntGuid,
-  // prettier-ignore
-  FullHexGuid,
-  RawGuidBuffer,
-  ShortHexGuid,
-} from '../types';
-
-export interface IGuidV4 {
-  /**
-   * Returns the GUID as a raw buffer.
-   */
-  get asRawGuidBuffer(): RawGuidBuffer;
-  /**
-   * Returns the GUID as a full hex string.
-   */
-  get asFullHexGuid(): FullHexGuid;
-  /**
-   * Returns the GUID as a Uint8Array.
-   */
-  get asUint8Array(): Uint8Array;
-  /**
-   * Returns the GUID as a short hex string.
-   */
-  get asShortHexGuid(): ShortHexGuid;
-  /**
-   * Returns the GUID as a BigInt.
-   */
-  get asBigIntGuid(): BigIntGuid;
-  /**
-   * Returns the GUID as a Base64 string.
-   */
-  get asBase64Guid(): Base64Guid;
-
-  /**
-   * Returns the GUID as a base64 string
-   */
-  serialize(): string;
-  /**
-   * Returns the GUID as a JSON string
-   */
-  toJson(): string;
-  /**
-   * Returns the GUID as a Base64 string
-   */
-  toString(): Base64Guid;
-  /**
-   * Compares this GUID to another GUID
-   * @param other The GUID to compare to (can be null/undefined)
-   * @param constantTime Use constant-time comparison to prevent timing attacks
-   */
-  equals(other: IGuidV4 | null | undefined, constantTime?: boolean): boolean;
-  /**
-   * Creates a new GuidV4 instance with the same value as this one.
-   * @returns A new GuidV4 instance with identical value
-   */
-  clone(): IGuidV4;
-  /**
-   * Returns the hash code for this GUID based on its buffer content.
-   * Useful for using GUIDs as Map/Set keys.
-   * @returns A numeric hash code
-   */
-  hashCode(): number;
-  /**
-   * Checks if this GUID is empty (all zeros).
-   * @returns True if the GUID is all zeros, false otherwise
-   */
-  isEmpty(): boolean;
-  /**
-   * Extracts the RFC 4122 version from the GUID.
-   * @returns The version number (1-5) or undefined
-   */
-  getVersion(): number | undefined;
-  /**
-   * Validates that this GUID is a proper v4 GUID according to RFC 4122.
-   * @returns True if valid v4 GUID or boundary value, false otherwise
-   */
-  isValidV4(): boolean;
-  /**
-   * Compares two GUIDs for ordering.
-   * @param other The other GUID to compare to
-   * @returns -1 if this < other, 0 if equal, 1 if this > other
-   */
-  compareTo(other: IGuidV4): number;
-}

package/src/interfaces/id-provider.ts

@@ -1,152 +0,0 @@
-/**
- * Interface for ID providers that supply recipient identifiers.
- * This allows the library to support various ID formats (ObjectID, GUID, UUID, custom).
- */
-export interface IIdProvider {
-  /**
-   * The fixed byte length of IDs produced by this provider.
-   * This determines the size of recipient ID fields in encrypted messages.
-   */
-  readonly byteLength: number;
-
-  /**
-   * A human-readable name for this ID provider type.
-   * Examples: 'ObjectID', 'GUIDv4', 'UUIDv4', 'Custom'
-   */
-  readonly name: string;
-
-  /**
-   * Generate a new random ID.
-   * @returns A newly generated ID as a Uint8Array of length `byteLength`
-   */
-  generate(): Uint8Array;
-
-  /**
-   * Validate that a given buffer is a properly formatted ID for this provider.
-   * This should check length, format constraints, and any version bits if applicable.
-   * @param id The ID buffer to validate
-   * @returns True if the ID is valid for this provider, false otherwise
-   */
-  validate(id: Uint8Array): boolean;
-
-  /**
-   * Serialize an ID buffer to a human-readable string representation.
-   * Examples: hex string, base64, ObjectID hex, UUID format with dashes
-   * @param id The ID buffer to serialize
-   * @returns A string representation of the ID
-   * @throws Error if the ID is invalid
-   */
-  serialize(id: Uint8Array): string;
-
-  /**
-   * Deserialize a string representation back to an ID buffer.
-   * This is the inverse of `serialize`.
-   * @param str The string representation of the ID
-   * @returns The ID as a Uint8Array of length `byteLength`
-   * @throws Error if the string is not a valid representation
-   */
-  deserialize(str: string): Uint8Array;
-
-  /**
-   * Compare two IDs for equality.
-   * Default implementation uses constant-time comparison.
-   * @param a First ID
-   * @param b Second ID
-   * @returns True if IDs are equal, false otherwise
-   */
-  equals(a: Uint8Array, b: Uint8Array): boolean;
-
-  /**
-   * Clone an ID buffer.
-   * Default implementation creates a defensive copy.
-   * @param id The ID to clone
-   * @returns A new Uint8Array with the same contents
-   */
-  clone(id: Uint8Array): Uint8Array;
-
-  /**
-   * Convert an ID of unknown type to a string representation.
-   * This is useful when dealing with generic IDs that might be Uint8Array, string, or other types.
-   * @param id The ID to convert
-   * @returns A string representation of the ID
-   */
-  idToString(id: unknown): string;
-
-  /**
-   * Convert a string representation of an ID back to an ID buffer.
-   * This is an alias for `deserialize` to provide symmetry with `idToString`.
-   * @param str The string representation of the ID
-   * @returns The ID as a Uint8Array of length `byteLength`
-   */
-  idFromString(str: string): Uint8Array;
-}
-
-/**
- * Base class for ID providers with common utility methods.
- */
-export abstract class BaseIdProvider implements IIdProvider {
-  abstract readonly byteLength: number;
-  abstract readonly name: string;
-
-  abstract generate(): Uint8Array;
-  abstract validate(id: Uint8Array): boolean;
-  abstract serialize(id: Uint8Array): string;
-  abstract deserialize(str: string): Uint8Array;
-
-  /**
-   * Convert an ID of unknown type to a string representation.
-   * Default implementation handles Uint8Array using serialize(), and falls back to String().
-   */
-  idToString(id: unknown): string {
-    if (id instanceof Uint8Array) {
-      return this.serialize(id);
-    }
-    return String(id);
-  }
-
-  /**
-   * Convert a string representation of an ID back to an ID buffer.
-   * Default implementation delegates to `deserialize`.
-   */
-  idFromString(str: string): Uint8Array {
-    return this.deserialize(str);
-  }
-
-  /**
-   * Constant-time comparison to prevent timing attacks.
-   */
-  equals(a: Uint8Array, b: Uint8Array): boolean {
-    if (a.length !== b.length) {
-      return false;
-    }
-
-    let diff = 0;
-    for (let i = 0; i < a.length; i++) {
-      diff |= a[i] ^ b[i];
-    }
-    return diff === 0;
-  }
-
-  /**
-   * Create a defensive copy of an ID.
-   */
-  clone(id: Uint8Array): Uint8Array {
-    return new Uint8Array(id);
-  }
-
-  /**
-   * Validate ID length matches expected byte length.
-   */
-  protected validateLength(id: Uint8Array, context: string): void {
-    if (id.length !== this.byteLength) {
-      const { IdProviderError } = require('../errors/id-provider');
-      const { IdProviderErrorType } = require('../enumerations/id-provider-error-type');
-      throw new IdProviderError(
-        IdProviderErrorType.InvalidLength,
-        undefined,
-        undefined,
-        { context, expected: this.byteLength, actual: id.length }
-      );
-    }
-  }
-}

package/src/interfaces/invariant.ts

@@ -1,60 +0,0 @@
-import type { IConstants } from './constants';
-
-/**
- * An invariant is a relationship between configuration values that must always hold true.
- * Unlike simple property validation, invariants check consistency across multiple related values.
- *
- * Example: MEMBER_ID_LENGTH must equal idProvider.byteLength
- *
- * Invariants help catch configuration errors that simple property validation would miss,
- * such as the 12 vs 32 byte discrepancy we encountered.
- */
-export interface IInvariant {
-  /**
-   * Unique name for this invariant (used in error messages)
-   */
-  readonly name: string;
-
-  /**
-   * Human-readable description of what this invariant validates
-   */
-  readonly description: string;
-
-  /**
-   * Check if the invariant holds for the given configuration
-   * @returns true if invariant is satisfied, false otherwise
-   */
-  check(config: IConstants): boolean;
-
-  /**
-   * Generate a detailed error message explaining why the invariant failed
-   * @param config The configuration that failed validation
-   * @returns Error message with actual vs expected values
-   */
-  errorMessage(config: IConstants): string;
-}
-
-/**
- * Base class for invariants with common utilities
- */
-export abstract class BaseInvariant implements IInvariant {
-  constructor(
-    public readonly name: string,
-    public readonly description: string,
-  ) {}
-
-  abstract check(config: IConstants): boolean;
-  abstract errorMessage(config: IConstants): string;
-
-  /**
-   * Helper to format error messages consistently
-   */
-  protected formatError(
-    property1: string,
-    value1: unknown,
-    property2: string,
-    value2: unknown,
-  ): string {
-    return `Invariant '${this.name}' failed: ${property1} (${value1}) must equal ${property2} (${value2})`;
-  }
-}