@digitaldefiance/ecies-lib 4.4.11 → 4.4.14

package/src/lib/id-providers/custom-provider.ts

@@ -1,109 +0,0 @@
-import { BaseIdProvider } from '../../interfaces/id-provider';
-import { randomBytes } from 'crypto';
-import { IdProviderError } from '../../errors/id-provider';
-import { IdProviderErrorType } from '../../enumerations/id-provider-error-type';
-
-/**
- * Custom ID provider that accepts any fixed byte length.
- * 
- * Use this when you need a non-standard ID size or custom validation logic.
- * For standard formats, prefer ObjectIdProvider, GuidV4Provider, or UuidProvider.
- * 
- * Example:
- * ```typescript
- * // 20-byte SHA-1 hash as recipient ID
- * const provider = new CustomIdProvider(20, 'SHA1Hash');
- * ```
- */
-export class CustomIdProvider extends BaseIdProvider {
-  readonly byteLength: number;
-  readonly name: string;
-
-  constructor(byteLength: number, name = 'Custom') {
-    super();
-
-    if (!Number.isInteger(byteLength) || byteLength < 1 || byteLength > 255) {
-      throw new IdProviderError(
-        IdProviderErrorType.InvalidByteLengthParameter,
-        undefined,
-        undefined,
-        { value: byteLength }
-      );
-    }
-
-    this.byteLength = byteLength;
-    this.name = name;
-  }
-
-  /**
-   * Generate a new random ID of the specified byte length.
-   */
-  generate(): Uint8Array {
-    return randomBytes(this.byteLength);
-  }
-
-  /**
-   * Validate an ID buffer.
-   * Only checks length - override this method for custom validation.
-   */
-  validate(id: Uint8Array): boolean {
-    return id.length === this.byteLength;
-  }
-
-  /**
-   * Serialize to hexadecimal string.
-   */
-  serialize(id: Uint8Array): string {
-    this.validateLength(id, `${this.name}.serialize`);
-    
-    return Array.from(id)
-      .map(b => b.toString(16).padStart(2, '0'))
-      .join('');
-  }
-
-  /**
-   * Deserialize a hexadecimal string to buffer.
-   */
-  deserialize(str: string): Uint8Array {
-    if (typeof str !== 'string') {
-      throw new IdProviderError(IdProviderErrorType.InputMustBeString);
-    }
-
-    const expectedLength = this.byteLength * 2;
-    if (str.length !== expectedLength) {
-      throw new IdProviderError(
-        IdProviderErrorType.InvalidStringLength,
-        undefined,
-        undefined,
-        { expected: expectedLength, actual: str.length }
-      );
-    }
-
-    if (!/^[0-9a-fA-F]+$/.test(str)) {
-      throw new IdProviderError(IdProviderErrorType.InvalidCharacters);
-    }
-
-    const buffer = new Uint8Array(this.byteLength);
-    for (let i = 0; i < this.byteLength; i++) {
-      buffer[i] = parseInt(str.substr(i * 2, 2), 16);
-    }
-
-    return buffer;
-  }
-
-  /**
-   * Convert an ID of unknown type to a string representation.
-   * Delegates to base implementation.
-   */
-  override idToString(id: unknown): string {
-    return super.idToString(id);
-  }
-
-  /**
-   * Convert a string representation of an ID back to an ID buffer.
-   * Delegates to deserialize.
-   */
-  override idFromString(str: string): Uint8Array {
-    return this.deserialize(str);
-  }
-}

package/src/lib/id-providers/guidv4-provider.ts

@@ -1,141 +0,0 @@
-import { BaseIdProvider } from '../../interfaces/id-provider';
-import { GuidV4 } from '../guid';
-import { IdProviderError } from '../../errors/id-provider';
-import { IdProviderErrorType } from '../../enumerations/id-provider-error-type';
-
-/**
- * ID provider for GUIDv4 (16 bytes raw, 24 bytes base64).
- * 
- * Uses the GuidV4 class which provides RFC 4122 compliant v4 GUIDs.
- * The raw binary representation is 16 bytes (128 bits).
- * 
- * Serialization uses base64 for compactness (24 characters vs 36 for hex with dashes).
- */
-export class GuidV4Provider extends BaseIdProvider {
-  readonly byteLength = 16;
-  readonly name = 'GUIDv4';
-
-  /**
-   * Generate a new random GUIDv4.
-   */
-  generate(): Uint8Array {
-    const guid = GuidV4.generate();
-    return guid.asRawGuidBufferUnsafe;
-  }
-
-  /**
-   * Validate a GUID buffer.
-   * Checks length and RFC 4122 v4 compliance.
-   */
-  validate(id: Uint8Array): boolean {
-    if (id.length !== this.byteLength) {
-      return false;
-    }
-
-    try {
-      // Convert to GuidV4 and validate
-      const guid = new GuidV4(Buffer.from(id));
-      return guid.isValidV4();
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Serialize GUID to base64 string (24 characters).
-   */
-  serialize(id: Uint8Array): string {
-    this.validateLength(id, 'GuidV4Provider.serialize');
-    
-    try {
-      const guid = new GuidV4(Buffer.from(id));
-      return guid.asBase64Guid;
-    } catch (error) {
-      throw new IdProviderError(
-        IdProviderErrorType.InvalidGuidBuffer,
-        { cause: error instanceof Error ? error : undefined },
-        undefined,
-        { message: error instanceof Error ? error.message : String(error) }
-      );
-    }
-  }
-
-  /**
-   * Deserialize a base64 or hex GUID string to buffer.
-   * Accepts multiple formats: base64 (24 chars), short hex (32 chars), full hex (36 chars).
-   */
-  deserialize(str: string): Uint8Array {
-    if (typeof str !== 'string') {
-      throw new IdProviderError(IdProviderErrorType.InputMustBeString);
-    }
-
-    try {
-      const guid = GuidV4.parse(str);
-      return guid.asRawGuidBufferUnsafe;
-    } catch (error) {
-      throw new IdProviderError(
-        IdProviderErrorType.ParseFailed,
-        { cause: error instanceof Error ? error : undefined },
-        undefined,
-        { input: str, message: error instanceof Error ? error.message : String(error) }
-      );
-    }
-  }
-
-  /**
-   * Create a GUID from a namespace and name (v5 - SHA-1 based).
-   * Useful for deterministic GUIDs.
-   */
-  fromNamespace(namespace: string, name: string): Uint8Array {
-    const guid = GuidV4.v5(name, namespace);
-    return guid.asRawGuidBufferUnsafe;
-  }
-
-  /**
-   * Get the GUID version from a buffer.
-   * Should return 4 for valid v4 GUIDs.
-   */
-  getVersion(id: Uint8Array): number | undefined {
-    this.validateLength(id, 'GuidV4Provider.getVersion');
-    
-    try {
-      const guid = new GuidV4(Buffer.from(id));
-      return guid.getVersion();
-    } catch {
-      return undefined;
-    }
-  }
-
-  /**
-   * Check if a GUID is the empty/nil GUID (all zeros).
-   */
-  isEmpty(id: Uint8Array): boolean {
-    this.validateLength(id, 'GuidV4Provider.isEmpty');
-    
-    try {
-      const guid = new GuidV4(Buffer.from(id));
-      return guid.isEmpty();
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Convert an ID of unknown type to a string representation.
-   * Handles Uint8Array, GuidV4 instances, and falls back to String().
-   */
-  override idToString(id: unknown): string {
-    if (id instanceof GuidV4) {
-      return id.asBase64Guid;
-    }
-    return super.idToString(id);
-  }
-
-  /**
-   * Convert a string representation of an ID back to an ID buffer.
-   * Delegates to deserialize.
-   */
-  override idFromString(str: string): Uint8Array {
-    return this.deserialize(str);
-  }
-}

package/src/lib/id-providers/objectid-provider.ts

@@ -1,125 +0,0 @@
-import { BaseIdProvider } from '../../interfaces/id-provider';
-import { ObjectId } from 'bson';
-import { IdProviderError } from '../../errors/id-provider';
-import { IdProviderErrorType } from '../../enumerations/id-provider-error-type';
-
-/**
- * ID provider for MongoDB/BSON ObjectIDs (12 bytes).
- * 
- * Format: 4-byte timestamp + 5-byte random + 3-byte counter
- * This matches the MongoDB ObjectID specification.
- * 
- * @see https://docs.mongodb.com/manual/reference/method/ObjectId/
- */
-export class ObjectIdProvider extends BaseIdProvider {
-  readonly byteLength = 12;
-  readonly name = 'ObjectID';
-
-  constructor() {
-    super();
-  }
-
-  /**
-   * Generate a new MongoDB-style ObjectID.
-   * Format: [timestamp:4][random:5][counter:3]
-   */
-  generate(): Uint8Array {
-    const buffer = new Uint8Array(12);
-    const objectId = new ObjectId();
-    
-    if (typeof objectId.id === 'string') {
-      const hex = objectId.id as string;
-      for (let i = 0; i < 12; i++) {
-        buffer[i] = parseInt(hex.substring(i * 2, (i * 2) + 2), 16);
-      }
-    } else {
-      buffer.set(objectId.id, 0);
-    }
-    
-    return buffer;
-  }
-
-  /**
-   * Validate an ObjectID buffer.
-   * Checks length and ensures it's not all zeros (invalid ObjectID).
-   */
-  validate(id: Uint8Array): boolean {
-    if (id.length !== this.byteLength) {
-      return false;
-    }
-
-    // Check if all bytes are zero (invalid ObjectID)
-    let allZeros = true;
-    for (let i = 0; i < id.length; i++) {
-      if (id[i] !== 0) {
-        allZeros = false;
-        break;
-      }
-    }
-
-    return !allZeros;
-  }
-
-  /**
-   * Serialize ObjectID to 24-character hex string (MongoDB standard).
-   */
-  serialize(id: Uint8Array): string {
-    this.validateLength(id, 'ObjectIdProvider.serialize');
-    
-    return Array.from(id)
-      .map(b => b.toString(16).padStart(2, '0'))
-      .join('');
-  }
-
-  /**
-   * Deserialize a 24-character hex string to ObjectID buffer.
-   */
-  deserialize(str: string): Uint8Array {
-    if (typeof str !== 'string') {
-      throw new IdProviderError(IdProviderErrorType.InputMustBeString);
-    }
-
-    if (str.length !== 24) {
-      throw new IdProviderError(
-        IdProviderErrorType.InvalidStringLength,
-        undefined,
-        undefined,
-        { expected: 24, actual: str.length }
-      );
-    }
-
-    if (!/^[0-9a-fA-F]{24}$/.test(str)) {
-      throw new IdProviderError(IdProviderErrorType.InvalidCharacters);
-    }
-
-    const buffer = new Uint8Array(12);
-    for (let i = 0; i < 12; i++) {
-      buffer[i] = parseInt(str.substr(i * 2, 2), 16);
-    }
-
-    if (!this.validate(buffer)) {
-      throw new IdProviderError(IdProviderErrorType.InvalidDeserializedId);
-    }
-
-    return buffer;
-  }
-
-  /**
-   * Convert an ID of unknown type to a string representation.
-   * Handles Uint8Array, ObjectId instances, and falls back to String().
-   */
-  override idToString(id: unknown): string {
-    if (id instanceof ObjectId) {
-      return id.toHexString();
-    }
-    return super.idToString(id);
-  }
-
-  /**
-   * Convert a string representation of an ID back to an ID buffer.
-   * Delegates to deserialize.
-   */
-  override idFromString(str: string): Uint8Array {
-    return this.deserialize(str);
-  }
-}

package/src/lib/id-providers/uuid-provider.ts

@@ -1,133 +0,0 @@
-import { BaseIdProvider } from '../../interfaces/id-provider';
-import { v4 as uuidv4, validate as uuidValidate, parse as uuidParse } from 'uuid';
-import { IdProviderError } from '../../errors/id-provider';
-import { IdProviderErrorType } from '../../enumerations/id-provider-error-type';
-
-/**
- * ID provider for standard RFC 4122 UUIDs (16 bytes).
- * 
- * Uses the 'uuid' npm package for UUID generation and validation.
- * Serialization uses the standard UUID format with dashes (36 characters).
- * 
- * This is functionally similar to GuidV4Provider but uses standard UUID
- * string formatting (with dashes) instead of base64.
- */
-export class UuidProvider extends BaseIdProvider {
-  readonly byteLength = 16;
-  readonly name = 'UUID';
-
-  /**
-   * Generate a new random UUIDv4.
-   */
-  generate(): Uint8Array {
-    const buffer = new Uint8Array(16);
-    uuidv4(undefined, buffer);
-    return buffer;
-  }
-
-  /**
-   * Validate a UUID buffer.
-   * Checks length and RFC 4122 compliance.
-   */
-  validate(id: Uint8Array): boolean {
-    if (id.length !== this.byteLength) {
-      return false;
-    }
-
-    try {
-      // Convert to string and validate
-      const str = this.serialize(id);
-      return uuidValidate(str);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Serialize UUID to standard format with dashes (36 characters).
-   * Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-   */
-  serialize(id: Uint8Array): string {
-    this.validateLength(id, 'UuidProvider.serialize');
-    
-    const hex = Array.from(id)
-      .map(b => b.toString(16).padStart(2, '0'))
-      .join('');
-    
-    // Insert dashes at proper positions
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-  }
-
-  /**
-   * Deserialize a UUID string (with or without dashes) to buffer.
-   */
-  deserialize(str: string): Uint8Array {
-    if (typeof str !== 'string') {
-      throw new IdProviderError(IdProviderErrorType.InputMustBeString);
-    }
-
-    // Validate format
-    if (!uuidValidate(str)) {
-      throw new IdProviderError(
-        IdProviderErrorType.InvalidUuidFormat,
-        undefined,
-        undefined,
-        { input: str }
-      );
-    }
-
-    try {
-      const buffer = uuidParse(str);
-      return buffer;
-    } catch (error) {
-      throw new IdProviderError(
-        IdProviderErrorType.ParseFailed,
-        { cause: error instanceof Error ? error : undefined },
-        undefined,
-        { input: str, message: error instanceof Error ? error.message : String(error) }
-      );
-    }
-  }
-
-  /**
-   * Extract the version from a UUID buffer.
-   * Should return 4 for v4 UUIDs.
-   */
-  getVersion(id: Uint8Array): number | undefined {
-    this.validateLength(id, 'UuidProvider.getVersion');
-    
-    // Version is in the most significant 4 bits of byte 6
-    const versionByte = id[6];
-    return (versionByte >> 4) & 0x0F;
-  }
-
-  /**
-   * Check if a UUID is the nil UUID (all zeros).
-   */
-  isNil(id: Uint8Array): boolean {
-    this.validateLength(id, 'UuidProvider.isNil');
-    
-    for (let i = 0; i < id.length; i++) {
-      if (id[i] !== 0) {
-        return false;
-      }
-    }
-    return true;
-  }
-
-  /**
-   * Convert an ID of unknown type to a string representation.
-   * Delegates to base implementation.
-   */
-  override idToString(id: unknown): string {
-    return super.idToString(id);
-  }
-
-  /**
-   * Convert a string representation of an ID back to an ID buffer.
-   * Delegates to deserialize.
-   */
-  override idFromString(str: string): Uint8Array {
-    return this.deserialize(str);
-  }
-}

package/src/lib/invariant-validator.ts

@@ -1,133 +0,0 @@
-import { IConstants } from '../interfaces/constants';
-import { IInvariant } from '../interfaces/invariant';
-import {
-  RecipientIdConsistencyInvariant,
-  Pbkdf2ProfilesValidityInvariant,
-  EncryptionAlgorithmConsistencyInvariant,
-} from './invariants';
-import { EciesComponentId, getEciesI18nEngine } from '../i18n-setup';
-import { EciesStringKey } from '../enumerations/ecies-string-key';
-import { TranslatableGenericError } from '@digitaldefiance/i18n-lib';
-
-/**
- * Validates all configuration invariants.
- * 
- * This class maintains a registry of all invariants and validates them
- * whenever a configuration is created or modified.
- * 
- * Adding new invariants is easy - just:
- * 1. Create a class implementing IInvariant
- * 2. Add it to the DEFAULT_INVARIANTS array
- * 3. Tests will automatically validate it
- */
-export class InvariantValidator {
-  /**
-   * Default invariants that are always checked
-   */
-  private static readonly DEFAULT_INVARIANTS: IInvariant[] = [
-    new RecipientIdConsistencyInvariant(),
-    new Pbkdf2ProfilesValidityInvariant(),
-    new EncryptionAlgorithmConsistencyInvariant(),
-  ];
-
-  /**
-   * Custom invariants registered at runtime
-   */
-  private static customInvariants: IInvariant[] = [];
-
-  /**
-   * Register a custom invariant to be checked alongside default invariants
-   */
-  static registerInvariant(invariant: IInvariant): void {
-    this.customInvariants.push(invariant);
-  }
-
-  /**
-   * Clear all custom invariants (useful for testing)
-   */
-  static clearCustomInvariants(): void {
-    this.customInvariants = [];
-  }
-
-  /**
-   * Get all invariants (default + custom)
-   */
-  static getAllInvariants(): readonly IInvariant[] {
-    return [...this.DEFAULT_INVARIANTS, ...this.customInvariants];
-  }
-
-  /**
-   * Validate all invariants for a given configuration
-   * 
-   * @param config The configuration to validate
-   * @throws Error if any invariant fails
-   */
-  static validateAll(config: IConstants): void {
-    const allInvariants = this.getAllInvariants();
-    const failures: string[] = [];
-
-    for (const invariant of allInvariants) {
-      if (!invariant.check(config)) {
-        failures.push(invariant.errorMessage(config));
-      }
-    }
-
-    if (failures.length > 0) {
-      const engine = getEciesI18nEngine();
-      throw TranslatableGenericError.withEngine(
-        engine,
-        EciesComponentId,
-        EciesStringKey.Error_Invariant_ConfigurationValidationFailedMultipleTemplate,
-        { count: failures.length, failures: failures.join('\n\n') },
-        undefined,
-        { invariantCount: failures.length }
-      );
-    }
-  }
-
-  /**
-   * Check a single invariant
-   * 
-   * @param config The configuration to validate
-   * @param invariantName Name of the invariant to check
-   * @returns true if invariant passes, false otherwise
-   */
-  static checkInvariant(config: IConstants, invariantName: string): boolean {
-    const invariant = this.getAllInvariants().find(i => i.name === invariantName);
-    if (!invariant) {
-      const engine = getEciesI18nEngine();
-      throw TranslatableGenericError.withEngine(
-        engine,
-        EciesComponentId,
-        EciesStringKey.Error_Invariant_UnknownInvariantTemplate,
-        { name: invariantName },
-        undefined,
-        { invariantName }
-      );
-    }
-    return invariant.check(config);
-  }
-
-  /**
-   * Get failure details for a specific invariant
-   * 
-   * @param config The configuration to validate
-   * @param invariantName Name of the invariant to check
-   * @returns Error message if invariant fails, null if it passes
-   */
-  static getFailureDetails(config: IConstants, invariantName: string): string | null {
-    const invariant = this.getAllInvariants().find(i => i.name === invariantName);
-    if (!invariant) {
-      const engine = getEciesI18nEngine();
-      throw TranslatableGenericError.withEngine(
-        engine,
-        EciesComponentId,
-        EciesStringKey.Error_Invariant_UnknownInvariantTemplate,
-        { name: invariantName },
-        undefined,
-        { invariantName }
-      );
-    }
-    return invariant.check(config) ? null : invariant.errorMessage(config);
-  }
-}

package/src/lib/invariants/encryption-algorithm-consistency.ts

@@ -1,73 +0,0 @@
-import { IConstants } from '../../interfaces/constants';
-import { BaseInvariant } from '../../interfaces/invariant';
-
-/**
- * Validates that encryption algorithm parameters are consistent.
- * 
- * Checks:
- * - Symmetric key size matches the algorithm (AES-256 = 32 bytes)
- * - Curve name is supported
- * - Key derivation path is valid
- */
-export class EncryptionAlgorithmConsistencyInvariant extends BaseInvariant {
-  private static readonly SUPPORTED_CURVES = [
-    'secp256k1',
-    'p256',
-    'p384',
-    'p521',
-  ];
-
-  constructor() {
-    super(
-      'EncryptionAlgorithmConsistency',
-      'Encryption algorithm parameters must be consistent'
-    );
-  }
-
-  check(config: IConstants): boolean {
-    // AES-256 requires 32-byte keys
-    if (config.ECIES.SYMMETRIC.KEY_SIZE !== 32) {
-      return false;
-    }
-
-    // Check curve is supported
-    if (!EncryptionAlgorithmConsistencyInvariant.SUPPORTED_CURVES.includes(
-      config.ECIES.CURVE_NAME
-    )) {
-      return false;
-    }
-
-    // Key derivation path should be valid BIP32 path
-    if (!config.ECIES.PRIMARY_KEY_DERIVATION_PATH.startsWith('m/')) {
-      return false;
-    }
-
-    return true;
-  }
-
-  errorMessage(config: IConstants): string {
-    const issues: string[] = [];
-
-    if (config.ECIES.SYMMETRIC.KEY_SIZE !== 32) {
-      issues.push(
-        `SYMMETRIC.KEY_SIZE (${config.ECIES.SYMMETRIC.KEY_SIZE}) must be 32 for AES-256`
-      );
-    }
-
-    if (!EncryptionAlgorithmConsistencyInvariant.SUPPORTED_CURVES.includes(
-      config.ECIES.CURVE_NAME
-    )) {
-      issues.push(
-        `CURVE_NAME (${config.ECIES.CURVE_NAME}) must be one of: ${EncryptionAlgorithmConsistencyInvariant.SUPPORTED_CURVES.join(', ')}`
-      );
-    }
-
-    if (!config.ECIES.PRIMARY_KEY_DERIVATION_PATH.startsWith('m/')) {
-      issues.push(
-        `PRIMARY_KEY_DERIVATION_PATH (${config.ECIES.PRIMARY_KEY_DERIVATION_PATH}) must be a valid BIP32 path starting with 'm/'`
-      );
-    }
-
-    return `Invariant '${this.name}' failed:\n  ${issues.join('\n  ')}`;
-  }
-}