@digitaldefiance/ecies-lib 4.4.2 → 4.4.4

package/src/{index.js → index.ts}

@@ -8,26 +8,44 @@
  * - Result pattern
  * - i18n 2.0 integration
  */
+
 // Core v2 exports
 export * from './builders';
 export * from './core';
 export * from './lib';
+
 // i18n v2
-export { EciesComponentId, EciesI18nEngineKey, getEciesI18nEngine, getEciesTranslation, resetEciesI18nEngine, safeEciesTranslation, } from './i18n-setup';
+export {
+  EciesComponentId,
+  EciesI18nEngineKey,
+  getEciesI18nEngine,
+  getEciesTranslation,
+  resetEciesI18nEngine,
+  safeEciesTranslation,
+} from './i18n-setup';
+
 // Re-export existing types and enums (unchanged)
 export { EciesStringKey } from './enumerations/ecies-string-key';
 export { MemberType } from './enumerations/member-type';
 export { Pbkdf2ProfileEnum } from './enumerations/pbkdf2-profile';
+
 // Re-export value objects (unchanged)
 export { EmailString } from './email-string';
 export { SecureBuffer } from './secure-buffer';
 export { SecureString } from './secure-string';
+
 // Re-export constants (unchanged)
 export { Constants, ConstantsRegistry } from './constants';
+export type { IConstants } from './interfaces';
 // Also export specific interfaces, types, and enums that are needed
 export { ECIES, OBJECT_ID_LENGTH, UINT32_MAX, UINT64_SIZE } from './constants';
 export { EciesCipherSuiteEnum } from './enumerations/ecies-cipher-suite';
-export { EciesEncryptionTypeEnum, EciesEncryptionTypeMap, } from './enumerations/ecies-encryption-type';
+export {
+  EciesEncryptionTypeEnum,
+  EciesEncryptionTypeMap,
+  type EciesEncryptionType,
+} from './enumerations/ecies-encryption-type';
+
 // Export utility functions from utils module (moved from enumerations for circular dependency fix)
 export { ECIESErrorTypeEnum } from './enumerations/ecies-error-type';
 export { EciesVersionEnum } from './enumerations/ecies-version';
@@ -36,21 +54,55 @@ export { LengthEncodingType } from './enumerations/length-encoding-type';
 export { MemberErrorType } from './enumerations/member-error-type';
 export { Pbkdf2ErrorType } from './enumerations/pbkdf2-error-type';
 export { ECIESError } from './errors/ecies';
-export { getLengthEncodingTypeForLength, getLengthEncodingTypeFromValue, getLengthForLengthType, } from './utils';
-export { encryptionTypeEnumToType, encryptionTypeToString, ensureEciesEncryptionTypeEnum, validateEciesEncryptionTypeEnum, } from './utils/encryption-type-utils';
+export type {
+  IECIESConfig,
+  IECIESConstants,
+  IMemberStorageData,
+  IPBkdf2Consts,
+  IPbkdf2Config,
+} from './interfaces';
+export type { HexString } from './types';
+export {
+  getLengthEncodingTypeForLength,
+  getLengthEncodingTypeFromValue,
+  getLengthForLengthType,
+} from './utils';
+export {
+  encryptionTypeEnumToType,
+  encryptionTypeToString,
+  ensureEciesEncryptionTypeEnum,
+  validateEciesEncryptionTypeEnum,
+} from './utils/encryption-type-utils';
+
 // ID Provider system
 export { BaseIdProvider } from './interfaces/id-provider';
+export type { IIdProvider } from './interfaces/id-provider';
 export * from './lib/id-providers';
 export { ObjectIdProvider } from './lib/id-providers/objectid-provider';
+
 // Invariant validation system
 export { BaseInvariant } from './interfaces/invariant';
+export type { IInvariant } from './interfaces/invariant';
 export { InvariantValidator } from './lib/invariant-validator';
 export * from './lib/invariants';
+
 // Configuration helpers
-export { clearRuntimeConfigurations, createRuntimeConfiguration, getRuntimeConfiguration, registerRuntimeConfiguration, unregisterRuntimeConfiguration, } from './constants';
-export { calculateConfigChecksum, captureCreationStack, } from './interfaces/configuration-provenance';
+export {
+  clearRuntimeConfigurations,
+  createRuntimeConfiguration,
+  getRuntimeConfiguration,
+  registerRuntimeConfiguration,
+  unregisterRuntimeConfiguration,
+} from './constants';
+export {
+  calculateConfigChecksum,
+  captureCreationStack,
+} from './interfaces/configuration-provenance';
+export type { IConfigurationProvenance } from './interfaces/configuration-provenance';
+
 // Note: Existing services will be re-exported once migrated to v2
 // For now, import from main index.ts for backward compatibility
+
 export * from './constants';
 export * from './email-string';
 export * from './enumerations';
@@ -59,6 +111,7 @@ export * from './i18n-setup';
 export * from './interfaces';
 export * from './interfaces/encrypted-chunk';
 export { ENCRYPTION_STATE_VERSION } from './interfaces/encryption-state';
+export type { IEncryptionState } from './interfaces/encryption-state';
 export * from './interfaces/stream-config';
 export * from './interfaces/stream-header';
 export * from './interfaces/stream-progress';
@@ -73,11 +126,15 @@ export { ChunkProcessor } from './services/chunk-processor';
 export { EciesCryptoCore } from './services/ecies/crypto-core';
 export { ECIESService } from './services/ecies/service';
 export { EncryptionStream } from './services/encryption-stream';
+export type {
+  IDecryptStreamOptions,
+  IEncryptStreamOptions,
+} from './services/encryption-stream';
 export { PasswordLoginService } from './services/password-login';
 export { Pbkdf2Service } from './services/pbkdf2';
 export { ProgressTracker } from './services/progress-tracker';
 export { ResumableEncryption } from './services/resumable-encryption';
+export type { IResumableOptions } from './services/resumable-encryption';
 export * from './types';
 export * from './utils';
 export { hexToUint8Array, uint8ArrayToHex } from './utils';
-//# sourceMappingURL=index.js.map

package/src/interfaces/checksum-config.ts

@@ -0,0 +1,4 @@
+export interface IChecksumConfig {
+  algorithm: string;
+  encoding: 'hex' | 'base64';
+}

package/src/interfaces/checksum-consts.ts

@@ -0,0 +1,13 @@
+export interface IChecksumConsts {
+  /** Default hash bits for SHA3 */
+  SHA3_DEFAULT_HASH_BITS: number;
+
+  /** Length of a SHA3 checksum buffer in bytes */
+  SHA3_BUFFER_LENGTH: number;
+
+  /** Algorithm name for checksums */
+  ALGORITHM: string;
+
+  /** Encoding for checksums */
+  ENCODING: 'hex' | 'base64';
+}

package/src/interfaces/configuration-provenance.ts

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,75 @@
+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

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

package/src/interfaces/ecies-consts.ts

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,64 @@
+/**
+ * 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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,77 @@
+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

@@ -0,0 +1,86 @@
+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;
+}