@digitaldefiance/node-ecies-lib 4.4.2 → 4.4.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Digital Defiance, Jessica Mulein, All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@digitaldefiance/node-ecies-lib",
-  "version": "4.4.2",
+  "version": "4.4.5",
   "description": "Digital Defiance Node ECIES Library",
+  "homepage": "https://github.com/Digital-Defiance/node-ecies-lib",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digital-Defiance/node-ecies-lib.git"
+  },
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "exports": {
@@ -48,8 +53,8 @@
   "license": "MIT",
   "packageManager": "yarn@4.10.3",
   "dependencies": {
-    "@digitaldefiance/ecies-lib": "4.4.2",
-    "@digitaldefiance/i18n-lib": "3.8.0",
+    "@digitaldefiance/ecies-lib": "4.4.7",
+    "@digitaldefiance/i18n-lib": "3.8.2",
     "@ethereumjs/wallet": "^10.0.0",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.1",
@@ -59,13 +64,12 @@
     "ts-brand": "^0.2.0"
   },
   "devDependencies": {
-    "@digitaldefiance/express-suite-test-utils": "1.0.11",
+    "@digitaldefiance/express-suite-test-utils": "1.0.12",
     "@typescript-eslint/eslint-plugin": "^8.48.0",
     "@typescript-eslint/parser": "^8.48.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.4",
     "fast-check": "^4.3.0",
     "madge": "^8.0.0"
-  },
-  "type": "commonjs"
-}
+  }
+}

package/src/builders/ecies-builder.ts

@@ -0,0 +1,27 @@
+import { ECIESService } from '../services/ecies';
+import { IECIESConstants, IECIESConfig } from '@digitaldefiance/ecies-lib';
+import { Constants } from '../constants';
+
+export class ECIESBuilder {
+  private serviceConfig: Partial<IECIESConfig> = {};
+  private eciesConsts: Partial<IECIESConstants> = {};
+
+  static create(): ECIESBuilder {
+    return new ECIESBuilder();
+  }
+
+  withServiceConfig(config: Partial<IECIESConfig>): this {
+    this.serviceConfig = { ...this.serviceConfig, ...config };
+    return this;
+  }
+
+  withConstants(constants: Partial<IECIESConstants>): this {
+    this.eciesConsts = { ...this.eciesConsts, ...constants };
+    return this;
+  }
+
+  build(): ECIESService {
+    const finalConstants = { ...Constants.ECIES, ...this.eciesConsts };
+    return new ECIESService(this.serviceConfig, finalConstants);
+  }
+}

package/src/builders/{index.d.ts → index.ts}

@@ -1,3 +1,2 @@
 export * from './ecies-builder';
 export * from './member-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/builders/member-builder.ts

@@ -0,0 +1,158 @@
+import {
+  EmailString,
+  MemberType,
+  SecureString,
+} from '@digitaldefiance/ecies-lib';
+import {
+  NodeEciesComponentId,
+  NodeEciesStringKey,
+} from '../i18n/ecies-i18n-factory';
+import { getNodeEciesI18nEngine } from '../i18n/node-ecies-i18n-setup';
+import { IBackendMemberWithMnemonic } from '../interfaces/member-with-mnemonic';
+import { Member } from '../member';
+import { ECIESService } from '../services/ecies';
+
+export class MemberBuilder {
+  private eciesService?: ECIESService;
+  private type?: MemberType;
+  private name?: string;
+  private email?: EmailString;
+  private mnemonic?: SecureString;
+  private createdBy?: Buffer;
+
+  static create(): MemberBuilder {
+    return new MemberBuilder();
+  }
+
+  withEciesService(service: ECIESService): this {
+    this.eciesService = service;
+    return this;
+  }
+
+  withType(type: MemberType): this {
+    this.type = type;
+    return this;
+  }
+
+  withName(name: string): this {
+    this.name = name;
+    return this;
+  }
+
+  withEmail(email: string | EmailString): this {
+    this.email = typeof email === 'string' ? new EmailString(email) : email;
+    return this;
+  }
+
+  withMnemonic(mnemonic: SecureString): this {
+    this.mnemonic = mnemonic;
+    return this;
+  }
+
+  withCreatedBy(creatorId: Buffer): this {
+    this.createdBy = creatorId;
+    return this;
+  }
+
+  generateMnemonic(): this {
+    if (!this.eciesService) {
+      const engine = getNodeEciesI18nEngine();
+      throw new Error(
+        engine.translate(
+          NodeEciesComponentId,
+          NodeEciesStringKey.Error_Builder_ECIESServiceMustBeSetBeforeGeneratingMnemonic
+        )
+      );
+    }
+    this.mnemonic = this.eciesService.generateNewMnemonic();
+    return this;
+  }
+
+  build(): IBackendMemberWithMnemonic {
+    const engine = getNodeEciesI18nEngine();
+    if (!this.eciesService) {
+      throw new Error(
+        engine.translate(
+          NodeEciesComponentId,
+          NodeEciesStringKey.Error_Builder_ECIESServiceIsRequired
+        )
+      );
+    }
+    if (!this.type || !this.name || !this.email) {
+      throw new Error(
+        engine.translate(
+          NodeEciesComponentId,
+          NodeEciesStringKey.Error_Builder_TypeNameAndEmailAreRequired
+        )
+      );
+    }
+
+    return Member.newMember(
+      this.eciesService,
+      this.type,
+      this.name,
+      this.email,
+      this.mnemonic,
+      this.createdBy
+    );
+  }
+
+  /**
+   * Convenience factory method to create a new member with default ECIESService
+   * @param type - The member type
+   * @param name - The member name
+   * @param email - The member email
+   * @param forceMnemonic - Optional mnemonic to use instead of generating a new one
+   * @param createdBy - Optional creator ID
+   * @returns Member with mnemonic
+   */
+  static newMember(
+    type: MemberType,
+    name: string,
+    email: EmailString | string,
+    forceMnemonic?: SecureString,
+    createdBy?: Buffer
+  ): IBackendMemberWithMnemonic {
+    const service = new ECIESService();
+    const emailObj = typeof email === 'string' ? new EmailString(email) : email;
+
+    return Member.newMember(
+      service,
+      type,
+      name,
+      emailObj,
+      forceMnemonic,
+      createdBy
+    );
+  }
+
+  /**
+   * Convenience factory method to create a member from JSON with default ECIESService
+   * @param json - JSON string representation of member
+   * @returns Member instance
+   */
+  static fromJson(json: string): Member {
+    const service = new ECIESService();
+    return Member.fromJson(json, service);
+  }
+
+  /**
+   * Convenience factory method to create a member from mnemonic with default ECIESService
+   * @param mnemonic - The mnemonic to use
+   * @param memberType - Optional member type (defaults to MemberType.User)
+   * @param name - Optional member name (defaults to 'Test User')
+   * @param email - Optional member email (defaults to 'test@example.com')
+   * @returns Member instance
+   */
+  static fromMnemonic(
+    mnemonic: SecureString,
+    memberType = MemberType.User,
+    name = 'Test User',
+    email: EmailString | string = 'test@example.com'
+  ): Member {
+    const service = new ECIESService();
+    const emailObj = typeof email === 'string' ? new EmailString(email) : email;
+
+    return Member.fromMnemonic(mnemonic, service, memberType, name, emailObj);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,251 @@
+import type {
+  IConstants as IBaseConstants,
+  IPBkdf2Consts,
+} from '@digitaldefiance/ecies-lib';
+import {
+  Constants as BaseConstants,
+  OBJECT_ID_LENGTH,
+  ObjectIdProvider,
+  registerRuntimeConfiguration,
+} from '@digitaldefiance/ecies-lib';
+import { CipherGCMTypes } from 'crypto';
+import { Pbkdf2ProfileEnum as NodePbkdf2ProfileEnum } from './enumerations/pbkdf2-profile';
+import {
+  getNodeEciesI18nEngine,
+  NodeEciesComponentId,
+  NodeEciesStringKey,
+} from './i18n';
+import type { IChecksumConsts } from './interfaces/checksum-consts';
+import type { IConstants } from './interfaces/constants';
+import type { IEncryptionConsts } from './interfaces/encryption-consts';
+import type { IKeyringConsts } from './interfaces/keyring-consts';
+import type { PbkdfProfiles } from './interfaces/pbkdf-profiles';
+import type { IWrappedKeyConsts } from './interfaces/wrapped-key-consts';
+
+/**
+ * Constants for checksum operations
+ * These values are critical for data integrity and MUST NOT be changed
+ * in an already established system as it will break all existing checksums.
+ */
+export const NODE_RUNTIME_CONFIGURATION_KEY = Symbol.for(
+  'digitaldefiance.node.ecies.defaults'
+);
+
+/**
+ * Node runtime configuration type (extends base IConstants)
+ */
+export type NodeRuntimeConfiguration = IBaseConstants;
+
+/**
+ * Overrides for node runtime configuration
+ */
+export type NodeRuntimeOverrides = Parameters<
+  typeof registerRuntimeConfiguration
+>[1];
+
+export const NODE_DEFAULTS_OVERRIDES: NodeRuntimeOverrides = Object.freeze({
+  PBKDF2: {
+    ALGORITHM: 'sha256',
+  },
+});
+
+let runtimeDefaults: NodeRuntimeConfiguration = registerRuntimeConfiguration(
+  NODE_RUNTIME_CONFIGURATION_KEY,
+  NODE_DEFAULTS_OVERRIDES
+);
+
+export function getNodeRuntimeConfiguration(): NodeRuntimeConfiguration {
+  return runtimeDefaults;
+}
+
+export function registerNodeRuntimeConfiguration(
+  configOrOverrides?: NodeRuntimeOverrides | NodeRuntimeConfiguration,
+  options?: Parameters<typeof registerRuntimeConfiguration>[2]
+): NodeRuntimeConfiguration {
+  // Register configuration through ecies-lib's system
+  // This handles auto-sync of idProvider -> MEMBER_ID_LENGTH and ECIES.MULTIPLE.RECIPIENT_ID_SIZE
+  runtimeDefaults = registerRuntimeConfiguration(
+    NODE_RUNTIME_CONFIGURATION_KEY,
+    configOrOverrides,
+    options
+  );
+
+  // Note: ENCRYPTION.RECIPIENT_ID_SIZE is set at module initialization
+  // and uses DEFAULT_ID_PROVIDER.byteLength. For runtime configurations with
+  // different providers, code should reference config.ECIES.MULTIPLE.RECIPIENT_ID_SIZE
+  // which is auto-synced by ecies-lib's createRuntimeConfiguration.
+
+  // Validate Node-specific invariants (base ecies-lib invariants already validated)
+  // Note: Validation temporarily disabled for configs without ENCRYPTION property
+  // as runtimeDefaults doesn't include node-specific constants
+  // InvariantValidator.validateAll(runtimeDefaults as IConstants);
+
+  return runtimeDefaults;
+}
+
+export const CHECKSUM: IChecksumConsts = runtimeDefaults.CHECKSUM;
+
+export const KEYRING: IKeyringConsts = Object.freeze({
+  ALGORITHM: 'aes' as const,
+  KEY_BITS: 256 as const,
+  MODE: 'gcm' as const,
+} as const);
+
+export const PBKDF2: IPBkdf2Consts = runtimeDefaults.PBKDF2;
+
+export const PBKDF2_PROFILES: PbkdfProfiles = Object.freeze({
+  // Align browser password profile with high security expectations (sha512, 64-byte salt/hash, 2M iterations)
+  [NodePbkdf2ProfileEnum.BROWSER_PASSWORD]: Object.freeze({
+    saltBytes: 64,
+    iterations: 2000000,
+    algorithm: 'sha512',
+    hashBytes: 64,
+  }),
+  // High security profile (sha512, 64-byte salt/hash, 2M iterations)
+  [NodePbkdf2ProfileEnum.HIGH_SECURITY]: Object.freeze({
+    saltBytes: 64,
+    iterations: 2000000,
+    algorithm: 'sha512',
+    hashBytes: 64,
+  }),
+  // Fast test profile (small salt and iterations for speed)
+  [NodePbkdf2ProfileEnum.TEST_FAST]: Object.freeze({
+    saltBytes: 16,
+    iterations: 1000, // Minimum required by PBKDF2 validation
+    algorithm: 'sha256',
+    hashBytes: 32,
+  }),
+  [NodePbkdf2ProfileEnum.USER_LOGIN]: Object.freeze({
+    saltBytes: 32,
+    iterations: 1304000,
+    algorithm: 'sha256',
+    hashBytes: 32,
+  }),
+  [NodePbkdf2ProfileEnum.KEY_WRAPPING]: Object.freeze({
+    saltBytes: 32,
+    iterations: 100000,
+    algorithm: 'sha256',
+    hashBytes: 32,
+  }),
+  [NodePbkdf2ProfileEnum.BACKUP_CODES]: Object.freeze({
+    saltBytes: 32,
+    iterations: 1304000,
+    algorithm: 'sha256',
+    hashBytes: 32,
+  }),
+} as const);
+
+export const WRAPPED_KEY: IWrappedKeyConsts = Object.freeze({
+  SALT_SIZE: PBKDF2.SALT_BYTES, // Use PBKDF2 standard salt size
+  IV_SIZE: 16 as const,
+  MASTER_KEY_SIZE: 32 as const,
+  MIN_ITERATIONS: 100000 as const, // Keep lower for key-wrapping operations
+} as const);
+
+export const KEYRING_ALGORITHM_CONFIGURATION =
+  `${KEYRING.ALGORITHM}-${KEYRING.KEY_BITS}-${KEYRING.MODE}` as CipherGCMTypes;
+
+/**
+ * Default ID provider instance (singleton).
+ * Uses MongoDB ObjectID format (12 bytes).
+ */
+const DEFAULT_ID_PROVIDER = new ObjectIdProvider();
+
+/**
+ * Constants for encrypted data
+ */
+export const ENCRYPTION: IEncryptionConsts = Object.freeze({
+  ENCRYPTION_TYPE_SIZE: 1 as const,
+  RECIPIENT_ID_SIZE: DEFAULT_ID_PROVIDER.byteLength,
+} as const);
+
+export const Constants: IConstants = Object.freeze({
+  ...BaseConstants,
+  ECIES: {
+    ...BaseConstants.ECIES,
+    // Override public key length for compressed keys
+    PUBLIC_KEY_LENGTH: 33,
+    // Override IV size for AES-GCM (standard is 12 bytes)
+    IV_SIZE: 12,
+    SINGLE: {
+      ...BaseConstants.ECIES.SINGLE,
+      FIXED_OVERHEAD_SIZE: 72,
+    },
+    SIMPLE: {
+      ...BaseConstants.ECIES.SIMPLE,
+      FIXED_OVERHEAD_SIZE: 64,
+    },
+    MULTIPLE: {
+      ...BaseConstants.ECIES.MULTIPLE,
+      ENCRYPTED_KEY_SIZE: 60,
+    },
+  },
+  // Node-specific overrides and additions
+  /**
+   * PBKDF2 constants (Node.js crypto implementation)
+   */
+  PBKDF2: PBKDF2,
+  /**
+   * PBKDF2 configuration profiles
+   */
+  PBKDF2_PROFILES: PBKDF2_PROFILES,
+  /**
+   * Key Wrapping Service constants
+   */
+  WRAPPED_KEY: WRAPPED_KEY,
+  /**
+   * Checksum constants used for data integrity
+   */
+  CHECKSUM: CHECKSUM,
+  /**
+   * Keyring constants used for key management
+   */
+  KEYRING: KEYRING,
+  /**
+   * Encryption constants used for encrypted data
+   */
+  ENCRYPTION: ENCRYPTION,
+  /**
+   * Algorithm configuration string for keyring operations
+   */
+  KEYRING_ALGORITHM_CONFIGURATION: KEYRING_ALGORITHM_CONFIGURATION,
+} as const);
+
+/**
+ * Safe translation helper for early initialization
+ * During module initialization, i18n may not be fully available.
+ * This function attempts to use i18n but falls back to a basic error message.
+ *
+ * @param key - The translation key
+ * @param fallback - The fallback message if i18n is not available
+ * @returns The translated message or fallback
+ */
+function safeTranslate(key: NodeEciesStringKey, fallback: string): string {
+  try {
+    const engine = getNodeEciesI18nEngine();
+    return engine.translate(NodeEciesComponentId, key);
+  } catch {
+    return fallback;
+  }
+}
+
+// Validate checksum constants during module initialization
+// Use safeTranslate to handle the case where i18n is not yet fully initialized
+if (
+  CHECKSUM.SHA3_BUFFER_LENGTH !== CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8 ||
+  CHECKSUM.SHA3_BUFFER_LENGTH !== CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8
+) {
+  throw new Error(
+    safeTranslate(
+      NodeEciesStringKey.Error_InvalidChecksumConstants,
+      'Invalid checksum constants: SHA3_BUFFER_LENGTH must equal SHA3_DEFAULT_HASH_BITS / 8'
+    )
+  );
+}
+
+if (OBJECT_ID_LENGTH !== 12) {
+  console.warn(
+    'ObjectID length may have changed, breaking encryption',
+    OBJECT_ID_LENGTH
+  );
+}

package/src/core/errors/crypto-error.ts

@@ -0,0 +1,10 @@
+export class CryptoError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly metadata?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'CryptoError';
+  }
+}

package/src/core/{index.d.ts → index.ts}

@@ -1,3 +1,2 @@
 export * from './errors/crypto-error';
 export * from './types/result';
-//# sourceMappingURL=index.d.ts.map

package/src/core/types/result.ts

@@ -0,0 +1,3 @@
+export type Result<T, E = Error> = 
+  | { success: true; data: T }
+  | { success: false; error: E };

package/src/enumerations/index.ts

@@ -0,0 +1,2 @@
+export * from './pbkdf2-profile';
+

package/src/enumerations/pbkdf2-profile.ts

@@ -0,0 +1,8 @@
+export enum Pbkdf2ProfileEnum {
+  USER_LOGIN = 'USER_LOGIN',
+  KEY_WRAPPING = 'KEY_WRAPPING',
+  BACKUP_CODES = 'BACKUP_CODES',
+  HIGH_SECURITY = 'HIGH_SECURITY',
+  BROWSER_PASSWORD = 'BROWSER_PASSWORD',
+  TEST_FAST = 'TEST_FAST',
+}

package/src/i18n/ecies-i18n-factory.ts

@@ -0,0 +1,111 @@
+import {
+  ComponentDefinition,
+  ComponentRegistration,
+  createCoreI18nEngine,
+  PluginI18nEngine,
+  LanguageCodes,
+  CoreLanguageCode,
+  RegistryConfig,
+  EngineConfig,
+} from '@digitaldefiance/i18n-lib';
+import { getEciesI18nEngine } from '@digitaldefiance/ecies-lib';
+
+import { NodeEciesStringKey, NodeEciesComponentId } from './node-keys';
+
+// Import translations
+import { englishTranslations } from './translations/en-US';
+
+export { NodeEciesStringKey, NodeEciesComponentId };
+import { britishEnglishTranslations } from './translations/en-GB';
+import { frenchTranslations, germanTranslations, japaneseTranslations, mandarinTranslations, spanishTranslations, ukrainianTranslations } from './translations';
+
+/**
+ * Component definition for Node ECIES strings
+ */
+export function createNodeEciesComponentDefinition(): ComponentDefinition<NodeEciesStringKey> {
+  const NodeEciesComponent: ComponentDefinition<NodeEciesStringKey> = {
+    id: NodeEciesComponentId,
+    name: 'Node ECIES Library Strings',
+    stringKeys: Object.values(NodeEciesStringKey),
+  };
+  return NodeEciesComponent;
+};
+
+export function createNodeEciesComponentRegistration(): ComponentRegistration<NodeEciesStringKey, string> {
+  const component = createNodeEciesComponentDefinition();
+  
+  return {
+    component,
+    strings: {
+      [LanguageCodes.EN_US]: englishTranslations,
+      [LanguageCodes.EN_GB]: britishEnglishTranslations,
+      [LanguageCodes.FR]: frenchTranslations,
+      [LanguageCodes.ES]: spanishTranslations,
+      [LanguageCodes.DE]: germanTranslations,
+      [LanguageCodes.ZH_CN]: mandarinTranslations,
+      [LanguageCodes.JA]: japaneseTranslations,
+      [LanguageCodes.UK]: ukrainianTranslations,
+    },
+  };
+}
+
+/**
+ * Singleton instance of the ECIES I18n engine
+ */
+let eciesI18nEngineInstance: PluginI18nEngine<CoreLanguageCode> | null = null;
+
+/**
+ * Create or get the ECIES I18n engine with proper component registration
+ * This replaces the legacy getEciesI18nEngine() function
+ */
+export function getEciesPluginI18nEngine(config?: Partial<RegistryConfig<string>>): PluginI18nEngine<CoreLanguageCode> {
+  if (!eciesI18nEngineInstance) {
+    // Create core engine with system strings
+    eciesI18nEngineInstance = createCoreI18nEngine(
+      NodeEciesComponentId,
+      config,
+    ) as PluginI18nEngine<CoreLanguageCode>;
+
+    const result = eciesI18nEngineInstance.registerComponent(createNodeEciesComponentRegistration());
+    if (!result.isValid) {
+      console.warn(
+        'Node ECIES component registration incomplete:',
+        result.missingKeys,
+      );
+    }
+  }
+
+  return eciesI18nEngineInstance!;
+}
+
+/**
+ * Reset the engine instance (useful for testing)
+ */
+export function resetEciesPluginI18nEngine(): void {
+  eciesI18nEngineInstance = null;
+}
+
+/**
+ * Get a translation from the Node ECIES component
+ */
+export function getNodeEciesTranslation(
+  key: NodeEciesStringKey,
+  variables?: Record<string, string | number>,
+  language?: CoreLanguageCode,
+): string {
+  // Import here to avoid circular dependency
+  const { getNodeEciesI18nEngine } = require('../i18n/node-ecies-i18n-setup');
+  const engine = getNodeEciesI18nEngine();
+  return engine.translate(NodeEciesComponentId, key, variables, language);
+}
+
+/**
+ * Get the ECIES PluginI18nEngine for use in node-ecies services
+ * Uses the base ecies-lib's engine which has all EciesStringKey translations
+ * Cast to any to handle cross-package type compatibility
+ */
+export function createEciesTranslationEngine(config?: EngineConfig): any {
+  return getEciesI18nEngine(config);
+}
+
+

package/src/i18n/{index.d.ts → index.ts}

@@ -1,3 +1,5 @@
+// V2 i18n exports
 export * from './node-ecies-i18n-setup';
+
+// Legacy exports (deprecated)
 export * from './ecies-i18n-factory';
-//# sourceMappingURL=index.d.ts.map