@digitaldefiance/ecies-lib 4.4.2 → 4.4.3

package/src/interfaces/id-provider.ts

@@ -0,0 +1,152 @@
+/**
+ * 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/{index.d.ts → index.ts}

@@ -12,4 +12,3 @@ export type * from './member-with-mnemonic';
 export * from './pbkdf2-config';
 export * from './pbkdf2-consts';
 export * from './pbkdf2-result';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/invariant.ts

@@ -0,0 +1,60 @@
+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})`;
+  }
+}

package/src/interfaces/library-error.ts

@@ -0,0 +1,23 @@
+/**
+ * Standardized error interface for Digital Defiance libraries
+ * Ensures consistent error handling across the ecosystem
+ */
+export interface LibraryError extends Error {
+  /** The library that generated this error */
+  readonly library: string;
+  /** Unique error code for programmatic handling */
+  readonly errorCode: string;
+  /** HTTP-style status code */
+  readonly statusCode: number;
+}
+
+/**
+ * Interface for resources that can be disposed
+ * Ensures consistent memory management across libraries
+ */
+export interface DisposableResource {
+  /** Dispose of the resource and clean up memory */
+  dispose(): void;
+  /** Whether the resource has been disposed */
+  readonly isDisposed: boolean;
+}

package/src/interfaces/{member-storage.d.ts → member-storage.ts}

@@ -1,21 +1,22 @@
 import type { MemberType } from '../enumerations/member-type';
+
 /**
  * Storage format for member data - all serializable types
  */
 export interface IMemberStorageData {
-    id: string;
-    type: MemberType;
-    name: string;
-    email: string;
-    publicKey: string;
-    creatorId: string;
-    dateCreated: string;
-    dateUpdated: string;
+  id: string;
+  type: MemberType;
+  name: string;
+  email: string;
+  publicKey: string; // base64
+  creatorId: string;
+  dateCreated: string; // ISO string
+  dateUpdated: string; // ISO string
 }
+
 /**
  * Extended storage format for test member data
  */
 export interface ITestMemberStorageData extends IMemberStorageData {
-    mnemonic?: string;
+  mnemonic?: string;
 }
-//# sourceMappingURL=member-storage.d.ts.map

package/src/interfaces/{member-with-mnemonic.d.ts → member-with-mnemonic.ts}

@@ -1,7 +1,7 @@
 import type { SecureString } from '../secure-string';
 import type { IMember } from './member';
+
 export interface IMemberWithMnemonic {
-    member: IMember;
-    mnemonic: SecureString;
+  member: IMember;
+  mnemonic: SecureString;
 }
-//# sourceMappingURL=member-with-mnemonic.d.ts.map

package/src/interfaces/member.ts

@@ -0,0 +1,84 @@
+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';
+
+/**
+ * Interface representing a member with cryptographic capabilities.
+ * This interface defines the contract for member operations without
+ * referencing concrete class implementations.
+ */
+export interface IMember {
+  // Required properties
+  readonly id: Uint8Array;
+  readonly type: MemberType;
+  readonly name: string;
+  readonly email: EmailString;
+  readonly publicKey: Uint8Array;
+  readonly creatorId: Uint8Array;
+  readonly dateCreated: Date;
+  readonly dateUpdated: Date;
+
+  // Optional private data properties
+  readonly privateKey: SecureBuffer | undefined;
+  readonly wallet: Wallet;
+
+  // State properties
+  readonly hasPrivateKey: boolean;
+
+  // Key management methods
+  unloadPrivateKey(): void;
+  unloadWallet(): void;
+  unloadWalletAndPrivateKey(): void;
+  loadWallet(mnemonic: SecureString, eciesParams?: IECIESConstants): void;
+  loadPrivateKey(privateKey: SecureBuffer): void;
+
+  // Cryptographic methods
+  sign(data: Uint8Array): SignatureUint8Array;
+  signData(data: Uint8Array): SignatureUint8Array;
+  verify(signature: SignatureUint8Array, data: Uint8Array): boolean;
+  verifySignature(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKey: Uint8Array,
+  ): boolean;
+
+  // Encryption/Decryption methods
+  encryptDataStream(
+    source: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>,
+    options?: {
+      recipientPublicKey?: Uint8Array;
+      onProgress?: (progress: {
+        bytesProcessed: number;
+        chunksProcessed: number;
+      }) => void;
+      signal?: AbortSignal;
+    },
+  ): AsyncGenerator<IEncryptedChunk, void, unknown>;
+
+  decryptDataStream(
+    source: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>,
+    options?: {
+      onProgress?: (progress: {
+        bytesProcessed: number;
+        chunksProcessed: number;
+      }) => void;
+      signal?: AbortSignal;
+    },
+  ): AsyncGenerator<Uint8Array, void, unknown>;
+
+  encryptData(
+    data: string | Uint8Array,
+    recipientPublicKey?: Uint8Array,
+  ): Promise<Uint8Array>;
+
+  decryptData(encryptedData: Uint8Array): Promise<Uint8Array>;
+
+  // Serialization methods
+  toJson(): string;
+  dispose(): void;
+}

package/src/interfaces/multi-recipient-chunk.ts

@@ -0,0 +1,61 @@
+/**
+ * Multi-recipient encrypted chunk format
+ *
+ * Structure:
+ * - Header (32 bytes): magic, version, recipientCount, chunkIndex, etc.
+ * - Recipient headers (variable): encrypted symmetric keys for each recipient
+ * - Encrypted data (variable): data encrypted with symmetric key
+ */
+
+/**
+ * Multi-recipient chunk header (32 bytes)
+ */
+export interface IMultiRecipientChunkHeader {
+  /** Magic bytes: 0x4D524543 ("MREC") */
+  magic: number;
+  /** Version: 0x0001 */
+  version: number;
+  /** Number of recipients */
+  recipientCount: number;
+  /** Chunk index */
+  chunkIndex: number;
+  /** Original data size */
+  originalSize: number;
+  /** Encrypted data size */
+  encryptedSize: number;
+  /** Flags (bit 0: isLast, bit 1: hasChecksum) */
+  flags: number;
+}
+
+/**
+ * Recipient header (variable size)
+ */
+export interface IRecipientHeader {
+  /** Recipient ID (size determined by ID provider) */
+  id: Uint8Array;
+  /** Encrypted symmetric key size (2 bytes) */
+  keySize: number;
+  /** Encrypted symmetric key (variable) */
+  encryptedKey: Uint8Array;
+}
+
+/**
+ * Multi-recipient encrypted chunk
+ */
+export interface IMultiRecipientChunk {
+  /** Chunk index */
+  index: number;
+  /** Complete chunk data (header + recipient headers + encrypted data) */
+  data: Uint8Array;
+  /** Whether this is the last chunk */
+  isLast: boolean;
+  /** Number of recipients */
+  recipientCount: number;
+}
+
+// Re-export interface (type-only), utility function and constant from lib
+export {
+  MULTI_RECIPIENT_CONSTANTS,
+  getMultiRecipientConstants,
+} from '../lib/multi-recipient-chunk-utils';
+export type { IMultiRecipientConstants } from '../lib/multi-recipient-chunk-utils';

package/src/interfaces/pbkdf2-config.ts

@@ -0,0 +1,6 @@
+export interface IPbkdf2Config {
+  hashBytes: number;
+  saltBytes: number;
+  iterations: number;
+  algorithm: string;
+}

package/src/interfaces/pbkdf2-consts.ts

@@ -0,0 +1,10 @@
+export interface IPBkdf2Consts {
+  /** Hash algorithm (sha512) */
+  ALGORITHM: string;
+
+  /** Number of bytes in a salt. */
+  SALT_BYTES: number;
+
+  /** Expected number of pbkdf2 iterations per second when hashing a password. */
+  ITERATIONS_PER_SECOND: number;
+}

package/src/interfaces/pbkdf2-result.ts

@@ -0,0 +1,5 @@
+export interface IPbkdf2Result {
+  salt: Uint8Array;
+  hash: Uint8Array;
+  iterations: number;
+}

package/src/interfaces/stream-config.ts

@@ -0,0 +1,17 @@
+/**
+ * Configuration for streaming encryption operations
+ */
+export interface IStreamConfig {
+  /** Chunk size in bytes (default: 1MB) */
+  chunkSize: number;
+  /** Whether to include checksums for each chunk */
+  includeChecksums: boolean;
+}
+
+/**
+ * Default streaming configuration
+ */
+export const DEFAULT_STREAM_CONFIG: IStreamConfig = {
+  chunkSize: 1024 * 1024, // 1MB
+  includeChecksums: false,
+};

package/src/interfaces/stream-header.ts

@@ -0,0 +1,34 @@
+import type { EciesEncryptionTypeEnum } from '../enumerations/ecies-encryption-type';
+
+/**
+ * Stream header structure (128 bytes fixed)
+ */
+export interface IStreamHeader {
+  /** Magic bytes: 0x45435354 ("ECST") */
+  magic: number;
+  /** Version: 0x0001 */
+  version: number;
+  /** Encryption type */
+  encryptionType: EciesEncryptionTypeEnum;
+  /** Chunk size in bytes */
+  chunkSize: number;
+  /** Total number of chunks (0 if unknown) */
+  totalChunks: number;
+  /** Total bytes to process (0 if unknown) */
+  totalBytes: number;
+  /** Timestamp when stream started */
+  timestamp: number;
+}
+
+/**
+ * Constants for stream header format
+ */
+export const STREAM_HEADER_CONSTANTS: {
+  readonly MAGIC: 0x45435354;
+  readonly VERSION: 0x0001;
+  readonly HEADER_SIZE: 128;
+} = {
+  MAGIC: 0x45435354, // "ECST"
+  VERSION: 0x0001,
+  HEADER_SIZE: 128,
+} as const;

package/src/interfaces/stream-progress.ts

@@ -0,0 +1,31 @@
+/**
+ * Progress information for streaming operations
+ */
+export interface IStreamProgress {
+  /** Total bytes processed so far */
+  bytesProcessed: number;
+  /** Total bytes to process (undefined for unknown-length streams) */
+  totalBytes?: number;
+  /** Number of chunks processed */
+  chunksProcessed: number;
+  /** Percentage complete (0-100, undefined if totalBytes unknown) */
+  percentComplete?: number;
+  /** Current throughput in bytes per second */
+  throughputBytesPerSec: number;
+  /** Estimated time remaining in seconds (undefined if totalBytes unknown) */
+  estimatedTimeRemaining?: number;
+  /** Timestamp when operation started */
+  startTime: number;
+  /** Elapsed time in milliseconds */
+  elapsedTime: number;
+}
+
+/**
+ * Callback function for progress updates
+ */
+export type ProgressCallback = (progress: IStreamProgress) => void | Promise<void>;
+
+/**
+ * Callback function for chunk completion
+ */
+export type ChunkCallback = (chunk: { index: number; size: number }) => void | Promise<void>;

package/src/lib/configuration-provenance-utils.ts

@@ -0,0 +1,26 @@
+import { createHash } from 'crypto';
+import type { IConstants } from '../interfaces/constants';
+
+/**
+ * Calculates a checksum for a configuration object.
+ * Uses SHA-256 of JSON representation.
+ */
+export function calculateConfigChecksum(config: IConstants): string {
+  // Create a stable JSON representation with BigInt support
+  const replacer = (_key: string, value: any) =>
+    typeof value === 'bigint' ? value.toString() : value;
+  const stable = JSON.stringify(config, replacer);
+  return createHash('sha256').update(stable).digest('hex');
+}
+
+/**
+ * Captures a stack trace for provenance tracking
+ */
+export function captureCreationStack(): string {
+  const stack = new Error().stack;
+  if (!stack) return 'stack unavailable';
+
+  // Remove the first two lines (Error message and this function)
+  const lines = stack.split('\n').slice(2);
+  return lines.join('\n');
+}

package/src/lib/crypto-container.ts

@@ -0,0 +1,64 @@
+/**
+ * Service Container for dependency injection
+ */
+
+import { I18nEngine } from '@digitaldefiance/i18n-lib';
+import { Constants } from '../constants';
+import { EciesStringKey } from '../enumerations/ecies-string-key';
+import { EciesComponentId, getEciesI18nEngine } from '../i18n-setup';
+import type { IConstants } from '../interfaces/constants';
+
+export enum CryptoServiceKey {
+  ECIES = 'ecies',
+  PBKDF2 = 'pbkdf2',
+  AES_GCM = 'aes-gcm',
+  PASSWORD_LOGIN = 'password-login',
+  FILE = 'file',
+  XOR = 'xor',
+}
+
+export class CryptoContainer {
+  private services = new Map<CryptoServiceKey, unknown>();
+  private config: IConstants;
+  private i18n: I18nEngine;
+
+  private constructor(config: IConstants, i18n: I18nEngine) {
+    this.config = config;
+    this.i18n = i18n;
+    this.initServices();
+  }
+
+  static create(
+    config: IConstants = Constants,
+    i18n?: I18nEngine,
+  ): CryptoContainer {
+    return new CryptoContainer(config, i18n || getEciesI18nEngine());
+  }
+
+  get<T>(key: CryptoServiceKey): T {
+    const service = this.services.get(key);
+    if (!service) {
+      throw new Error(
+        this.i18n.translate(
+          EciesComponentId,
+          EciesStringKey.Error_Container_ServiceNotFoundTemplate,
+          { service: key },
+        ),
+      );
+    }
+    return service as T;
+  }
+
+  private initServices(): void {
+    // Services will be lazily loaded to avoid circular dependencies
+    // Implementation will be added as services are migrated
+  }
+
+  getConfig(): IConstants {
+    return this.config;
+  }
+
+  getI18n(): I18nEngine {
+    return this.i18n;
+  }
+}