@digitaldefiance/ecies-lib 4.4.13 → 4.4.15

package/src/errors/disposed.ts

@@ -1,36 +0,0 @@
-import { TranslatableGenericError } from '@digitaldefiance/i18n-lib';
-import { EciesComponentId } from '../i18n-setup';
-import { EciesStringKey } from '../enumerations';
-
-/**
- * Error thrown when operations are attempted on disposed objects.
- * Uses TranslatableGenericError for simple i18n support since there's only one error type.
- * 
- * @example
- * ```typescript
- * throw new DisposedError();
- * throw new DisposedError('fr'); // French
- * ```
- */
-export class DisposedError extends TranslatableGenericError<EciesStringKey> {
-  /**
-   * Creates a new DisposedError instance.
-   * 
-   * @param language - Optional language code for error message localization.
-   * @param instanceKey - Optional i18n engine instance key (defaults to ecies engine).
-   */
-  constructor(language?: string, instanceKey: string = 'ecies') {
-    super(
-      EciesComponentId,
-      EciesStringKey.Error_DisposedError_ObjectDisposed,
-      undefined,
-      language,
-      undefined,
-      instanceKey
-    );
-    this.name = 'DisposedError';
-    
-    // Maintains proper prototype chain for instanceof checks
-    Object.setPrototypeOf(this, DisposedError.prototype);
-  }
-}

package/src/errors/ecies.ts

@@ -1,153 +0,0 @@
-import {
-  buildReasonMap,
-  HandleableErrorOptions,
-  TypedHandleableError,
-} from '@digitaldefiance/i18n-lib';
-import { ECIESErrorTypeEnum } from '../enumerations/ecies-error-type';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-/**
- * Context information captured when an error occurs.
- * This provides debugging information beyond just the error message.
- */
-export interface IErrorContext {
-  /**
-   * The operation that was being performed when the error occurred
-   * e.g., 'encryptChunk', 'decryptStream', 'validateRecipientId'
-   */
-  operation: string;
-
-  /**
-   * Stack trace from when the error was created
-   */
-  stackTrace: string;
-
-  /**
-   * Relevant configuration values (sanitized to remove sensitive data)
-   */
-  config?: Partial<{
-    idProviderName: string;
-    idProviderByteLength: number;
-    memberIdLength: number;
-    recipientIdSize: number;
-    curveName: string;
-  }>;
-
-  /**
-   * Timestamp when error occurred
-   */
-  timestamp: Date;
-
-  /**
-   * Additional metadata specific to the error
-   */
-  metadata?: Record<string, unknown>;
-}
-
-export class ECIESError extends TypedHandleableError<
-  typeof ECIESErrorTypeEnum,
-  EciesStringKey
-> {
-  /**
-   * Rich context information for debugging
-   */
-  public readonly context?: IErrorContext;
-
-  constructor(
-    type: ECIESErrorTypeEnum,
-    options?: HandleableErrorOptions,
-    language?: string,
-    otherVars?: Record<string, string | number>,
-    context?: Partial<IErrorContext>,
-  ) {
-    let source: Error;
-    if (
-      options &&
-      typeof options === 'object' &&
-      'cause' in options &&
-      options.cause instanceof Error
-    ) {
-      source = options.cause;
-    } else {
-      source = new Error();
-    }
-    super(
-      EciesComponentId,
-      type,
-      buildReasonMap<typeof ECIESErrorTypeEnum, EciesStringKey>(
-        ECIESErrorTypeEnum,
-        ['Error', 'ECIESError'],
-      ),
-      source,
-      options,
-      language,
-      otherVars,
-    );
-    this.name = 'ECIESError';
-
-    // Capture context if provided
-    if (context) {
-      this.context = {
-        operation: context.operation ?? 'unknown',
-        stackTrace:
-          context.stackTrace ?? new Error().stack ?? 'stack unavailable',
-        config: context.config,
-        timestamp: context.timestamp ?? new Date(),
-        metadata: context.metadata,
-      };
-    }
-  }
-
-  /**
-   * Serialize error to JSON including context
-   */
-  override toJSON(): Record<string, unknown> {
-    return {
-      name: this.name,
-      message: this.message,
-      type: this.type,
-      context: this.context,
-      cause:
-        this.cause instanceof Error
-          ? {
-              name: this.cause.name,
-              message: this.cause.message,
-            }
-          : undefined,
-    };
-  }
-
-  /**
-   * Get a detailed error report including all context
-   */
-  getDetailedReport(): string {
-    const parts = [`${this.name}: ${this.message}`, `Type: ${this.type}`];
-
-    if (this.context) {
-      parts.push(`Operation: ${this.context.operation}`);
-      parts.push(`Timestamp: ${this.context.timestamp.toISOString()}`);
-
-      if (this.context.config) {
-        parts.push('Configuration:');
-        Object.entries(this.context.config).forEach(([key, value]) => {
-          parts.push(`  ${key}: ${value}`);
-        });
-      }
-
-      if (this.context.metadata) {
-        parts.push('Metadata:');
-        Object.entries(this.context.metadata).forEach(([key, value]) => {
-          parts.push(`  ${key}: ${JSON.stringify(value)}`);
-        });
-      }
-
-      if (this.context.stackTrace) {
-        parts.push('\nStack Trace:');
-        parts.push(this.context.stackTrace);
-      }
-    }
-
-    return parts.join('\n');
-  }
-}

package/src/errors/guid.ts

@@ -1,130 +0,0 @@
-import {
-  buildReasonMap,
-  TypedHandleableError,
-} from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations';
-import { GuidBrandType } from '../enumerations/guid-brand-type';
-import { GuidErrorType } from '../enumerations/guid-error-type';
-import { EciesComponentId } from '../i18n-setup';
-import { RawGuidBuffer } from '../types';
-
-/**
- * Error class for handling GUID-related errors.
- * Provides detailed error information including the error type, optional brand, length, and GUID value.
- *
- * @example
- * ```typescript
- * throw new GuidError(GuidErrorType.InvalidGuid);
- * throw new GuidError(GuidErrorType.InvalidGuidUnknownLength, undefined, 17);
- * throw new GuidError(GuidErrorType.InvalidGuidWithDetails, undefined, undefined, buffer);
- * ```
- */
-export class GuidError extends TypedHandleableError<
-  typeof GuidErrorType,
-  EciesStringKey
-> {
-  /**
-   * Reason map cache to avoid rebuilding on every error instantiation.
-   * This improves performance in scenarios where many errors are created.
-   */
-  private static readonly REASON_MAP = buildReasonMap<
-    typeof GuidErrorType,
-    EciesStringKey
-  >(
-    GuidErrorType,
-    ['Error', 'GuidError'],
-    new Set([
-      GuidErrorType.InvalidGuidWithDetails,
-      GuidErrorType.InvalidGuidUnknownBrand,
-      GuidErrorType.InvalidGuidUnknownLength,
-    ]),
-  );
-
-  /**
-   * Creates a new GuidError instance.
-   *
-   * @param type - The type of GUID error that occurred.
-   * @param brand - Optional GUID brand type (for brand-related errors).
-   * @param length - Optional length value (for length-related errors).
-   * @param guid - Optional GUID buffer (for errors involving specific GUID values).
-   * @param language - Optional language code for error message localization.
-   *
-   * @throws {Error} If guid parameter is provided but is not a Buffer.
-   */
-  constructor(
-    type: GuidErrorType,
-    public readonly brand?: GuidBrandType,
-    public readonly length?: number,
-    public readonly guid?: RawGuidBuffer | Buffer,
-    language?: string,
-  ) {
-    // Build template parameters only for the values that are provided
-    const templateParams: Record<string, string> = {};
-
-    if (brand !== undefined) {
-      templateParams.BRAND = String(brand);
-    }
-
-    if (length !== undefined) {
-      templateParams.LENGTH = String(length);
-    }
-
-    if (guid !== undefined) {
-      // Defensive check to ensure guid is a Buffer
-      if (!Buffer.isBuffer(guid)) {
-        throw new Error('GuidError: guid parameter must be a Buffer');
-      }
-      templateParams.GUID = guid.toString('hex');
-    }
-
-    super(
-      EciesComponentId,
-      type,
-      GuidError.REASON_MAP,
-      new Error(), // source error
-      undefined, // options
-      language,
-      templateParams,
-    );
-    this.name = 'GuidError';
-
-    // Maintains proper prototype chain for instanceof checks
-    Object.setPrototypeOf(this, GuidError.prototype);
-  }
-
-  /**
-   * Returns a string representation of the error with all relevant details.
-   * @returns A detailed error string.
-   */
-  public override toString(): string {
-    const parts = [`${this.name}: ${this.message}`];
-
-    if (this.brand !== undefined) {
-      parts.push(`Brand: ${this.brand}`);
-    }
-
-    if (this.length !== undefined) {
-      parts.push(`Length: ${this.length}`);
-    }
-
-    if (this.guid !== undefined) {
-      parts.push(`GUID: ${this.guid.toString('hex')}`);
-    }
-
-    return parts.join(' | ');
-  }
-
-  /**
-   * Serializes the error to JSON including all custom properties.
-   * @returns JSON representation of the error.
-   */
-  public override toJSON(): Record<string, unknown> {
-    const baseJson = super.toJSON();
-    return {
-      ...baseJson,
-      brand: this.brand,
-      length: this.length,
-      guid: this.guid ? this.guid.toString('hex') : undefined,
-    };
-  }
-}

package/src/errors/id-provider.ts

@@ -1,40 +0,0 @@
-import { IdProviderErrorType } from '../enumerations/id-provider-error-type';
-import { HandleableErrorOptions, TypedHandleableError, buildReasonMap } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-/**
- * Error class for ID provider operations.
- * Provides i18n support for errors during ID generation, validation, serialization, and deserialization.
- */
-export class IdProviderError extends TypedHandleableError<typeof IdProviderErrorType, EciesStringKey> {
-  /**
-   * Reason map cache to avoid rebuilding on every error instantiation.
-   */
-  private static readonly REASON_MAP = buildReasonMap<typeof IdProviderErrorType, EciesStringKey>(
-    IdProviderErrorType,
-    ['Error', 'IdProviderError']
-  );
-
-  /**
-   * Creates a new IdProviderError instance.
-   * 
-   * @param type - The type of ID provider error that occurred.
-   * @param options - Optional error handling options.
-   * @param language - Optional language code for error message localization.
-   * @param templateParams - Optional parameters for error message templates.
-   */
-  constructor(
-    type: IdProviderErrorType,
-    options?: HandleableErrorOptions,
-    language?: string,
-    templateParams?: Record<string, string | number>
-  ) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    super(EciesComponentId, type, IdProviderError.REASON_MAP, source, options, language, templateParams);
-    this.name = 'IdProviderError';
-    
-    // Maintains proper prototype chain for instanceof checks
-    Object.setPrototypeOf(this, IdProviderError.prototype);
-  }
-}

package/src/errors/invalid-email.ts

@@ -1,23 +0,0 @@
-import { InvalidEmailErrorType } from '../enumerations/invalid-email-type';
-import { buildReasonMap, HandleableErrorOptions, TypedHandleableError } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-export class InvalidEmailError extends TypedHandleableError<typeof InvalidEmailErrorType, EciesStringKey> {
-  public readonly email?: string;
-  constructor(type: InvalidEmailErrorType, email?: string, options?: HandleableErrorOptions, language?: string) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    super(
-      EciesComponentId,
-      type,
-      buildReasonMap<typeof InvalidEmailErrorType, EciesStringKey>(InvalidEmailErrorType, ['Error', 'InvalidEmailError']),
-      source,
-      { statusCode: 422, ...options },
-      language, {
-        email: email ?? ''
-      }
-    );
-    this.email = email;
-    this.name = 'InvalidEmailError';
-  }
-}

package/src/errors/length.ts

@@ -1,19 +0,0 @@
-import { LengthErrorType } from '../enumerations/length-error-type';
-import { buildReasonMap, HandleableErrorOptions, TypedHandleableError } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-export class LengthError extends TypedHandleableError<typeof LengthErrorType, EciesStringKey> {
-  constructor(type: LengthErrorType, options?: HandleableErrorOptions, language?: string) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    super(
-      EciesComponentId,
-      type,
-      buildReasonMap<typeof LengthErrorType, EciesStringKey>(LengthErrorType, ['Error', 'LengthError']),
-      source,
-      options,
-      language
-    );
-    this.name = 'LengthError';
-  }
-}

package/src/errors/member.ts

@@ -1,20 +0,0 @@
-import { MemberErrorType } from '../enumerations/member-error-type';
-import { buildReasonMap, HandleableErrorOptions, TypedHandleableError } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-export class MemberError extends TypedHandleableError<typeof MemberErrorType, EciesStringKey> {
-
-  constructor(type: MemberErrorType, options?: HandleableErrorOptions, language?: string) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    super(
-      EciesComponentId,
-      type,
-      buildReasonMap<typeof MemberErrorType, EciesStringKey>(MemberErrorType, ['Error', 'MemberError']),
-      source,
-      options,
-      language
-    );
-    this.name = 'MemberError';
-  }
-}

package/src/errors/pbkdf2.ts

@@ -1,20 +0,0 @@
-import { Pbkdf2ErrorType } from '../enumerations/pbkdf2-error-type';
-import { buildReasonMap, HandleableErrorOptions, TypedHandleableError } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-export class Pbkdf2Error extends TypedHandleableError<typeof Pbkdf2ErrorType, EciesStringKey> {
-
-  constructor(type: Pbkdf2ErrorType, options?: HandleableErrorOptions, language?: string) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    super(
-      EciesComponentId,
-      type,
-      buildReasonMap<typeof Pbkdf2ErrorType, EciesStringKey>(Pbkdf2ErrorType, ['Error', 'Pbkdf2Error']),
-      source,
-      options,
-      language
-    );
-    this.name = 'Pbkdf2Error';
-  }
-}

package/src/errors/secure-storage.ts

@@ -1,17 +0,0 @@
-import { SecureStorageErrorType } from '../enumerations/secure-storage-error-type';
-import { buildReasonMap, HandleableErrorOptions, TypedHandleableError } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { EciesComponentId } from '../i18n-setup';
-
-export class SecureStorageError extends TypedHandleableError<typeof SecureStorageErrorType, EciesStringKey> {
-  constructor(type: SecureStorageErrorType, options?: HandleableErrorOptions, language?: string) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    const reasonMap = buildReasonMap<typeof SecureStorageErrorType, EciesStringKey>(
-      SecureStorageErrorType,
-      ['Error', 'SecureStorageError']
-    );
-    
-    super(EciesComponentId, type, reasonMap, source, options, language);
-    this.name = 'SecureStorageError';
-  }
-}

package/src/errors/simple-ecies.ts

@@ -1,21 +0,0 @@
-import { buildReasonMap, HandleableErrorOptions, TypedHandleableError } from '@digitaldefiance/i18n-lib';
-import { ECIESErrorTypeEnum, EciesStringKey } from '../enumerations';
-import { EciesComponentId } from '../i18n-setup';
-
-export class SimpleECIESError extends TypedHandleableError<typeof ECIESErrorTypeEnum, EciesStringKey> {
-  constructor(
-    type: ECIESErrorTypeEnum,
-    options?: HandleableErrorOptions,
-    language?: string,
-    otherVars?: Record<string, string | number>
-  ) {
-    const source = options?.cause instanceof Error ? options.cause : new Error();
-    const reasonMap = buildReasonMap<typeof ECIESErrorTypeEnum, EciesStringKey>(
-      ECIESErrorTypeEnum,
-      ['Error', 'ECIESError']
-    );
-
-    super(EciesComponentId, type, reasonMap, source, options, language, otherVars);
-    this.name = 'SimpleECIESError';
-  }
-}

package/src/errors/simple-test-error.ts

@@ -1,6 +0,0 @@
-export class SimpleTestError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'SimpleTestError';
-  }
-}

package/src/i18n-setup.ts

@@ -1,130 +0,0 @@
-/**
- * ECIES i18n Setup - v2.0 Architecture
- * Uses i18n-lib 2.0 patterns with runtime validation
- */
-
-import {
-  I18nEngine,
-  LanguageCodes,
-  createDefaultLanguages,
-  createCoreComponentRegistration,
-} from '@digitaldefiance/i18n-lib';
-import type { ComponentConfig, EngineConfig } from '@digitaldefiance/i18n-lib';
-import { EciesStringKey } from './enumerations/ecies-string-key';
-import { englishTranslations } from './translations/en-US';
-import { frenchTranslations } from './translations/fr';
-import { spanishTranslations } from './translations/es';
-import { germanTranslations } from './translations/de';
-import { mandarinChineseTranslations } from './translations/zh-cn';
-import { japaneseTranslations } from './translations/ja';
-import { ukrainianTranslations } from './translations/uk';
-
-export const EciesI18nEngineKey = 'DigitalDefiance.Ecies.I18nEngine' as const;
-export const EciesComponentId = 'ecies' as const;
-
-/**
- * Create ECIES component configuration with all translations
- * Note: Includes all 8 supported languages
- */
-export function createEciesComponentConfig(): ComponentConfig {
-  return {
-    id: EciesComponentId,
-    strings: {
-      [LanguageCodes.EN_US]: englishTranslations,
-      [LanguageCodes.EN_GB]: englishTranslations,
-      [LanguageCodes.FR]: frenchTranslations,
-      [LanguageCodes.ES]: spanishTranslations,
-      [LanguageCodes.DE]: germanTranslations,
-      [LanguageCodes.ZH_CN]: mandarinChineseTranslations,
-      [LanguageCodes.JA]: japaneseTranslations,
-      [LanguageCodes.UK]: ukrainianTranslations,
-    },
-  };
-}
-
-/**
- * Create ECIES i18n engine instance
- * Uses i18n 2.0 pattern with runtime validation
- * IMPORTANT: Uses 'default' as instance key so TypedHandleableError can find it
- */
-function createInstance(config?: EngineConfig): I18nEngine {
-  const engine = I18nEngine.registerIfNotExists('default', createDefaultLanguages(), config);
-
-  // Register core component first (required for error messages)
-  const coreReg = createCoreComponentRegistration();
-  engine.registerIfNotExists({
-    id: coreReg.component.id,
-    strings: coreReg.strings as Record<string, Record<string, string>>,
-  });
-  
-  // Register ECIES component with aliases
-  const eciesConfig = createEciesComponentConfig();
-  const result = engine.registerIfNotExists({
-    ...eciesConfig,
-    aliases: ['EciesStringKey']
-  });
-  
-  // Warn about missing translations (non-blocking)
-  if (!result.isValid && result.errors.length > 0) {
-    console.warn(
-      `ECIES component has ${result.errors.length} errors`,
-      result.errors.slice(0, 5) // Show first 5
-    );
-  }
-  
-  return engine;
-}
-
-/**
- * Lazy initialization with Proxy (like core-i18n.ts pattern)
- */
-let _eciesEngine: I18nEngine | undefined;
-
-export function getEciesI18nEngine(config?: EngineConfig): I18nEngine {
-  if (!_eciesEngine || !I18nEngine.hasInstance('default')) {
-    _eciesEngine = createInstance(config);
-  }
-  return _eciesEngine;
-}
-
-/**
- * Proxy for backward compatibility
- */
-export const eciesI18nEngine = new Proxy({} as I18nEngine, {
-  get(target, prop) {
-    return getEciesI18nEngine()[prop as keyof I18nEngine];
-  }
-});
-
-/**
- * Reset function for tests
- */
-export function resetEciesI18nEngine(): void {
-  _eciesEngine = undefined;
-}
-
-/**
- * Helper to translate ECIES strings
- */
-export function getEciesTranslation(
-  stringKey: EciesStringKey,
-  variables?: Record<string, string | number>,
-  language?: string,
-): string {
-  return getEciesI18nEngine().translate(EciesComponentId, stringKey, variables, language);
-}
-
-/**
- * Safe translation with fallback
- */
-export function safeEciesTranslation(
-  stringKey: EciesStringKey,
-  variables?: Record<string, string | number>,
-  language?: string,
-): string {
-  try {
-    return getEciesTranslation(stringKey, variables, language);
-  } catch {
-    return `[${stringKey}]`;
-  }
-}

package/src/interfaces/checksum-config.ts

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

package/src/interfaces/checksum-consts.ts

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