@digitaldefiance/ecies-lib 4.4.2 → 4.4.4

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

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

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

@@ -1,30 +1,31 @@
 /**
  * ID Providers for recipient identification in multi-recipient encryption.
- *
+ * 
  * The library supports multiple ID formats to accommodate different use cases:
  * - ObjectID: MongoDB/BSON ObjectID (12 bytes)
  * - GUIDv4: RFC 4122 v4 GUID (16 bytes, base64 serialization)
  * - UUID: RFC 4122 v4 UUID (16 bytes, standard format with dashes)
  * - Legacy32Byte: Backward compatible 32-byte IDs (deprecated)
  * - Custom: User-defined byte length and validation
- *
+ * 
  * @example
  * ```typescript
  * import { ObjectIdProvider, GuidV4Provider } from './lib/id-providers';
- *
+ * 
  * // Use MongoDB ObjectIDs (12 bytes)
  * const objectIdProvider = new ObjectIdProvider();
  * const id = objectIdProvider.generate();
- *
+ * 
  * // Use GUIDs (16 bytes)
  * const guidProvider = new GuidV4Provider();
  * const guid = guidProvider.generate();
  * ```
  */
+
 export { ObjectIdProvider } from './objectid-provider';
 export { GuidV4Provider } from './guidv4-provider';
 export { UuidProvider } from './uuid-provider';
 export { CustomIdProvider } from './custom-provider';
+
 export type { IIdProvider } from '../../interfaces/id-provider';
 export { BaseIdProvider } from '../../interfaces/id-provider';
-//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -1,6 +1,6 @@
 /**
  * Library exports for v2 architecture
  */
+
 export * from './crypto-container';
-export * from './guid';
-//# sourceMappingURL=index.js.map
+export * from './guid';

package/src/lib/invariant-validator.ts

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