@digitaldefiance/ecies-lib 4.4.1 → 4.4.3

package/src/enumerations/pbkdf2-profile.ts

@@ -0,0 +1,5 @@
+export enum Pbkdf2ProfileEnum {
+  BROWSER_PASSWORD = 'BROWSER_PASSWORD',
+  HIGH_SECURITY = 'HIGH_SECURITY',
+  TEST_FAST = 'TEST_FAST',
+}

package/src/enumerations/secure-storage-error-type.ts

@@ -0,0 +1,5 @@
+export enum SecureStorageErrorType {
+  DecryptedValueLengthMismatch = 'DecryptedValueLengthMismatch',
+  DecryptedValueChecksumMismatch = 'DecryptedValueChecksumMismatch',
+  ValueIsNull = 'ValueIsNull',
+}

package/src/errors/disposed.ts

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

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

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

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

@@ -8,4 +8,3 @@ export * from './length';
 export * from './member';
 export * from './pbkdf2';
 export * from './secure-storage';
-//# sourceMappingURL=index.d.ts.map

package/src/errors/invalid-email.ts

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

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

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

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

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

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

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

package/src/i18n-setup.ts

@@ -0,0 +1,130 @@
+/**
+ * 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}]`;
+  }
+}