@digitaldefiance/node-ecies-lib 3.0.8 → 4.1.0

package/README.md

@@ -1,486 +1,272 @@
 # @digitaldefiance/node-ecies-lib
 
-A Node.js-specific implementation of the Digital Defiance ECIES (Elliptic Curve Integrated Encryption Scheme) library, providing secure encryption, decryption, and key management capabilities using Node.js crypto primitives. This package is designed to be binary compatible with the browser-based `@digitaldefiance/ecies-lib`, enabling seamless cross-platform cryptographic operations.
+[![npm version](https://badge.fury.io/js/%40digitaldefiance%2Fnode-ecies-lib.svg)](https://www.npmjs.com/package/@digitaldefiance/node-ecies-lib)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-220%2B%20passing-brightgreen)](https://github.com/Digital-Defiance/ecies-lib)
 
-Part of [Express Suite](https://github.com/Digital-Defiance/express-suite)
-
-## Features
-
-- **ECIES Encryption/Decryption**: Secure elliptic curve integrated encryption scheme using Node.js crypto primitives.
-- **Streaming Encryption**: Memory-efficient encryption for large files (<10MB RAM for any size) ✨ NEW in v3.0
-- **Multi-recipient Encryption**: Encrypt data for multiple recipients simultaneously with efficient handling.
-- **Multi-recipient Streaming**: Encrypt once for up to 65,535 recipients with shared symmetric key ✨ NEW in v3.0
-- **PBKDF2 Key Derivation**: Password-based key derivation with multiple configurable security profiles.
-- **Digital Signatures**: Sign and verify data using elliptic curve cryptography.
-- **Secure Memory Management**: Uses `SecureBuffer` and `SecureString` for sensitive data to ensure zeroization and protection.
-- **Runtime Configuration Registry**: Centralized, immutable constants with runtime override capabilities for advanced customization.
-- **Plugin-Based Internationalization (i18n)**: Full support for multi-language translations with type-safe, plugin-based architecture.
-- **Security Hardening**: 16 comprehensive security validations across all layers ✨ NEW in v3.0
-
-## Binary Compatibility
-
-This package is intended to be fully binary compatible with the browser-based `@digitaldefiance/ecies-lib`. This means:
-
-- Data encrypted in the browser can be decrypted in Node.js and vice versa.
-- Cryptographic primitives and data formats are consistent across environments.
-- Enables cross-platform secure communication and data handling.
-
-## Installation
-
-```bash
-npm install @digitaldefiance/node-ecies-lib
-```
-
-## Quick Start
-
-### v3.0 Streaming Encryption (NEW)
-
-```typescript
-import { ECIESService, Member, MemberType, EmailString } from '@digitaldefiance/node-ecies-lib';
-import { createReadStream } from 'fs';
+A Node.js-specific implementation of the Digital Defiance ECIES (Elliptic Curve Integrated Encryption Scheme) library, providing secure encryption, decryption, and key management capabilities using Node.js crypto primitives. This package is designed to be binary compatible with similarly numbered releases of the browser-based `@digitaldefiance/ecies-lib`, enabling seamless cross-platform cryptographic operations.
 
-const eciesService = new ECIESService();
-const { member, mnemonic } = Member.newMember(
-  eciesService,
-  MemberType.User,
-  'Alice',
-  new EmailString('alice@example.com')
-);
+Part of [Express Suite](https://github.com/Digital-Defiance/express-suite)
 
-// Stream encrypt large file with <10MB RAM
-const fileStream = createReadStream('large-file.bin');
-const chunks: Buffer[] = [];
+> Current Version: v4.1.0
 
-for await (const chunk of member.encryptDataStream(fileStream)) {
-  chunks.push(chunk.data);
-}
+This library implements a modern, enterprise-grade ECIES protocol (v4.0) featuring HKDF key derivation, AAD binding, and optimized multi-recipient encryption. It includes a pluggable ID provider system, memory-efficient streaming encryption, and comprehensive internationalization.
 
-// Stream decrypt
-const decryptedChunks: Buffer[] = [];
-for await (const chunk of member.decryptDataStream(chunks)) {
-  decryptedChunks.push(chunk);
-}
-```
+## Features
 
-### v2.0 Simplified API
+### 🛡️ Core Cryptography (Protocol v4.0)
 
-```typescript
-import { ECIESService, Member, MemberType, EmailString } from '@digitaldefiance/node-ecies-lib';
+- **Advanced ECIES**:
+  - **HKDF-SHA256**: Cryptographically robust key derivation (RFC 5869).
+  - **AAD Binding**: Strict binding of header metadata and recipient IDs to the encryption context to prevent tampering.
+  - **Shared Ephemeral Key**: Optimized multi-recipient encryption using a single ephemeral key pair, reducing payload size.
+  - **Compressed Keys**: Uses 33-byte compressed public keys for efficiency.
+- **Algorithms**:
+  - **Curve**: `secp256k1` for ECDH key exchange and ECDSA signatures.
+  - **Symmetric**: `AES-256-GCM` for authenticated symmetric encryption.
+  - **Hashing**: `SHA-256` and `SHA-512`.
+- **Modes**:
+  - **Simple**: Minimal overhead (no length prefix).
+  - **Single**: Includes data length prefix.
+  - **Multiple**: Efficient encryption for up to 65,535 recipients.
 
-// Initialize the ECIES service (automatic i18n setup)
-const eciesService = new ECIESService();
+### 🆔 Identity & Management
 
-// Create a new member
-const { member, mnemonic } = Member.newMember(
-  eciesService,
-  MemberType.User,
-  'Alice',
-  new EmailString('alice@example.com')
-);
+- **Pluggable ID Providers**:
+  - **Flexible IDs**: Support for `ObjectId` (12 bytes), `GUID`/`UUID` (16 bytes), or custom formats (1-255 bytes).
+  - **Auto-Sync**: Configuration automatically adapts all cryptographic constants to the selected ID provider.
+  - **Member System**: User abstraction with cryptographic operations, fully integrated with the configured ID provider.
+- **Key Management**:
+  - **BIP39**: Mnemonic phrase generation (12-24 words).
+  - **HD Wallets**: BIP32/BIP44 hierarchical deterministic derivation.
+  - **Secure Storage**: Memory-safe `SecureString` and `SecureBuffer` with XOR obfuscation and auto-zeroing.
 
-// Encrypt data
-const message = 'Hello, secure world!';
-const encrypted = member.encryptData(message);
+### 🚀 Advanced Capabilities
 
-// Decrypt data
-const decrypted = member.decryptData(encrypted);
-console.log(decrypted.toString()); // "Hello, secure world!"
-```
+- **Streaming Encryption**: Memory-efficient processing for large files (<10MB RAM usage for any file size).
+- **Internationalization (i18n)**: Automatic error translation in 8 languages (en-US, en-GB, fr, es, de, zh-CN, ja, uk).
+- **Runtime Configuration**: Injectable configuration profiles via `ConstantsRegistry` for dependency injection and testing.
+- **Cross-Platform**: Fully compatible with similarly numbered releases of `@digitaldefiance/ecies-lib` (browser).
 
-### v2.0 Builder Pattern
+## Compatibility
 
-```typescript
-import { ECIESBuilder, MemberBuilder, MemberType } from '@digitaldefiance/node-ecies-lib';
-
-// Build service with custom configuration and constants
-const eciesService = ECIESBuilder.create()
-  .withServiceConfig({ /* optional config */ })
-  .withConstants({ /* optional constants */ })
-  .build();
-
-// Build member with fluent API
-const { member, mnemonic } = MemberBuilder.create()
-  .withEciesService(eciesService)
-  .withType(MemberType.User)
-  .withName('Alice')
-  .withEmail('alice@example.com')
-  .generateMnemonic()  // Optional: auto-generate mnemonic
-  .build();
-
-// Or provide your own mnemonic
-const { member: member2, mnemonic: mnemonic2 } = MemberBuilder.create()
-  .withEciesService(eciesService)
-  .withType(MemberType.User)
-  .withName('Bob')
-  .withEmail('bob@example.com')
-  .withMnemonic(existingMnemonic)
-  .build();
-```
+**Important Note**: This library is **NOT** binary compatible with previous major versions (v1.x, v2.x, v3.x) due to the protocol upgrade to v4.0 (HKDF, AAD binding).
 
-## Core Components
+However, it is designed to be **strictly binary compatible** with the browser-based `@digitaldefiance/ecies-lib` of the **same version number**. This ensures that data encrypted in a Node.js environment (using this library) can be decrypted in a browser environment (using `ecies-lib`), and vice versa, provided both are running compatible versions (e.g., v4.x).
 
-### ECIESService
+This cross-platform interoperability is verified through extensive E2E testing suites.
 
-The main service class providing encryption, decryption, key management, and mnemonic generation.
-
-**v2.0 Constructor:**
-```typescript
-constructor(config?: Partial<IECIESConfig>, eciesParams?: IECIESConstants)
-```
+## Installation
 
-- `config`: Optional partial configuration (curveName, symmetricAlgorithm, etc.)
-- `eciesParams`: Optional ECIES constants (defaults to `Constants.ECIES`)
-- Automatic i18n engine initialization
-
-**Key Methods:**
-- `generateNewMnemonic(): SecureString`: Generates a new mnemonic phrase compliant with BIP39 for secure key generation.
-- `walletAndSeedFromMnemonic(mnemonic: SecureString): { wallet: Wallet; seed: Buffer }`: Derives an Ethereum wallet instance and raw seed buffer from a mnemonic.
-- `encryptSimpleOrSingle(simple: boolean, publicKey: Buffer, data: Buffer): Buffer`: Encrypts data in simple (headerless) or single-recipient (with header) ECIES mode.
-- `encryptMultiple(members: Member[], data: Buffer): Buffer`: Encrypts the same payload for multiple recipients efficiently, producing a combined ciphertext.
-- `decryptSimpleOrSingleWithHeader(simple: boolean, privateKey: Buffer, encryptedData: Buffer): Buffer`: Decrypts data encrypted by `encryptSimpleOrSingle` in either mode, returning the original plaintext.
-- `signMessage(privateKey: Buffer, data: Buffer): SignatureBuffer`: Creates a deterministic signature over a message using the provided private key.
-- `verifyMessage(publicKey: Buffer, data: Buffer, signature: SignatureBuffer): boolean`: Validates a signature against the original data and signer’s public key.
-- `deriveKeyFromPassword(password: Buffer, salt: Buffer, iterations: number, saltBytes: number, hashBytes: number, algorithm: string): ChecksumBuffer`: Delegates to PBKDF2 service for synchronous key derivation.
-- `deriveKeyFromPasswordAsync(password: Buffer, salt: Buffer, iterations: number, saltBytes: number, hashBytes: number, algorithm: string): Promise<ChecksumBuffer>`: Async version of key derivation to avoid blocking the event loop.
-
-### Member Class
-
-Represents a cryptographic member with secure key management and cryptographic operations.
-
-**v2.0 Changes:**
-- Constructor no longer requires i18n engine
-- Automatic engine retrieval from singleton
-- Simplified factory methods
-
-**Core Methods:**
-
-- `new Member(...)`: Constructs with injected `ECIESService`, type, name, email, public key, and optional private key, wallet, IDs, and timestamps.
-- `loadWallet(mnemonic: SecureString)`: Loads wallet and private key from mnemonic; verifies public key integrity.
-- `loadPrivateKey(privateKey: SecureBuffer)`: Imports a raw private key into the member instance.
-- `sign(data: Buffer): SignatureBuffer`: Signs arbitrary data buffer; throws if private key is missing.
-- `verify(signature: SignatureBuffer, data: Buffer): boolean`: Verifies a signature against the member’s public key.
-- `encryptData(data: string | Buffer, recipientPublicKey?: Buffer): Buffer`: Encrypts data for the specified public key or self.
-- `decryptData(encryptedData: Buffer): Buffer`: Decrypts ciphertext using the member’s private key.
-- `toJson(): string`: Serializes member operational data (IDs, keys, timestamps) into a JSON string.
-- `dispose(): void`: Securely zeroizes and unloads private key and wallet from memory.
-- Static factory methods:
-  - `Member.fromJson(json: string, eciesService: ECIESService)`: Recreates a member from stored JSON.
-  - `Member.fromMnemonic(mnemonic: SecureString, eciesService: ECIESService, memberType?, name?, email?)`: Builds a member directly from a mnemonic.
-  - `Member.newMember(eciesService: ECIESService, type, name, email, forceMnemonic?, createdBy?)`: Generates a new random member with mnemonic and returns both.
-
-### PBKDF2 Service
-
-Provides password-based key derivation with multiple predefined profiles.
-
-**v2.0 Constructor:**
-```typescript
-constructor(
-  profiles?: Partial<Record<Pbkdf2ProfileEnum, IPbkdf2Consts>>,
-  eciesParams?: IECIESConstants,
-  pbkdf2Params?: IPbkdf2Constants
-)
+```bash
+npm install @digitaldefiance/node-ecies-lib
+# or
+yarn add @digitaldefiance/node-ecies-lib
 ```
 
-**Predefined Profiles:**
+### Requirements
 
-| Profile       | Salt Size | Iterations | Algorithm | Hash Size | Use Case            |
-|---------------|-----------|------------|-----------|-----------|---------------------|
-| USER_LOGIN    | 32 bytes  | 1,304,000  | SHA-256   | 32 bytes  | User authentication |
-| KEY_WRAPPING  | 32 bytes  | 100,000    | SHA-256   | 32 bytes  | Key encryption      |
-| BACKUP_CODES  | 32 bytes  | 1,304,000  | SHA-256   | 32 bytes  | Backup codes        |
-| HIGH_SECURITY | 64 bytes  | 2,000,000  | SHA-512   | 64 bytes  | Sensitive operations|
-| TEST_FAST     | 16 bytes  | 500        | SHA-256   | 32 bytes  | Testing/development |
+**Node.js**: 18+ (Uses Node.js `crypto` module)
 
-Detailed API:
+## Architecture & Protocol
 
-- `deriveKeyFromPassword(password: Buffer, salt: Buffer, iterations: number, saltBytes: number, hashBytes: number, algorithm: string): ChecksumBuffer`: Synchronously derives a key using PBKDF2 with specified parameters.
-- `deriveKeyFromPasswordAsync(password: Buffer, salt: Buffer, iterations: number, saltBytes: number, hashBytes: number, algorithm: string): Promise<ChecksumBuffer>`: Async implementation of PBKDF2 for non-blocking operation.
-- `deriveKeyFromPasswordWithProfile(password: Buffer, profile: Pbkdf2ProfileEnum): ChecksumBuffer`: Convenience method to derive a key using a predefined profile.
-- `deriveKeyFromPasswordWithProfileAsync(password: Buffer, profile: Pbkdf2ProfileEnum): Promise<ChecksumBuffer>`: Async version of profile-based derivation.
-- `generateSalt(bytes: number = 32): Buffer`: Utility to generate cryptographically secure random salt of specified length.
-- `getDefaultProfile(profile: Pbkdf2ProfileEnum): IPbkdf2Consts`: Retrieves constant parameters for a given profile.
+### ECIES v4.0 Protocol Flow
 
-## Encryption Types
+The library implements a robust ECIES variant designed for security and efficiency.
 
-Supports multiple encryption modes:
+1. **Key Derivation (HKDF)**:
+   Shared secrets from ECDH are passed through **HKDF-SHA256** to derive the actual symmetric encryption keys. This ensures that the resulting keys have uniform distribution and are resistant to weak shared secrets.
 
-- **Simple**: Basic ECIES encryption for single recipients.
-- **Single**: Enhanced ECIES with additional metadata.
-- **Multiple**: Efficient encryption for multiple recipients.
+   ```typescript
+   SymmetricKey = HKDF(
+     secret: ECDH(EphemeralPriv, RecipientPub),
+     salt: empty,
+     info: "ecies-v2-key-derivation"
+   )
+   ```
 
-## Cross-Platform Compatibility
+2. **Authenticated Encryption (AAD)**:
+   All encryption operations use **AES-256-GCM** with Additional Authenticated Data (AAD).
+   - **Key Encryption**: The Recipient's ID is bound to the encrypted key.
+   - **Message Encryption**: The Message Header (containing version, algorithm, ephemeral key, etc.) is bound to the encrypted payload.
+   This prevents "context manipulation" attacks where an attacker might try to swap recipient IDs or modify header metadata.
 
-Designed to work seamlessly with the browser-based `@digitaldefiance/ecies-lib`:
+3. **Multi-Recipient Optimization**:
+   Instead of generating a new ephemeral key pair for every recipient, the sender generates **one** ephemeral key pair for the message.
+   - The ephemeral public key is stored once in the header.
+   - A random "Message Key" is generated.
+   - This Message Key is encrypted individually for each recipient using the shared secret derived from the single ephemeral key and the recipient's public key.
 
-- Data encrypted in the browser can be decrypted in Node.js.
-- Data encrypted in Node.js can be decrypted in the browser.
+### ID Provider System
 
-## Security Features
+The library is agnostic to the format of unique identifiers. The `IdProvider` system drives the entire configuration:
 
-- Secure memory management with zeroization of sensitive data.
-- Configurable security levels via PBKDF2 profiles.
-- Comprehensive input validation and error handling.
-- Detailed error types with plugin-based i18n support for localization.
+- **ObjectIdProvider** (Default): 12-byte MongoDB-style IDs.
+- **GuidV4Provider**: 16-byte raw GUIDs.
+- **UuidProvider**: 16-byte UUIDs (string representation handles dashes).
+- **CustomIdProvider**: Define your own size (1-255 bytes).
 
-## v2.0 Architecture
+When you configure an ID provider, the library automatically:
 
-### New Components
+- Updates `MEMBER_ID_LENGTH`.
+- Updates `ECIES.MULTIPLE.RECIPIENT_ID_SIZE`.
+- Validates that all internal constants are consistent.
 
-**Builders** (`src/builders/`):
-- `ECIESBuilder`: Fluent API for ECIESService construction
-- `MemberBuilder`: Fluent API for Member creation
-
-**Core Types** (`src/core/`):
-- `CryptoError`: Unified error class with code, message, metadata
-- `Result<T, E>`: Safe operation results pattern
-
-**Service Container** (`src/lib/`):
-- `CryptoContainer`: Dependency injection for ECIES, PBKDF2, AES-GCM services
-
-### Runtime Configuration Registry
+## Quick Start
 
-Constants are centralized and immutable:
+### 1. Basic Configuration & Usage
 
 ```typescript
-import { Constants, getNodeRuntimeConfiguration } from '@digitaldefiance/node-ecies-lib';
-
-// Access default constants
-const eciesConfig = Constants.ECIES;
-const pbkdf2Config = Constants.PBKDF2;
-
-// Get runtime configuration
-const config = getNodeRuntimeConfiguration();
+import { 
+  ECIESService, 
+  registerNodeRuntimeConfiguration 
+} from '@digitaldefiance/node-ecies-lib';
+import { ObjectIdProvider } from '@digitaldefiance/ecies-lib';
+
+// 1. Configure (Optional - defaults to ObjectIdProvider)
+registerNodeRuntimeConfiguration({
+  idProvider: new ObjectIdProvider()
+});
+
+// 2. Initialize Service
+const ecies = new ECIESService();
+
+// 3. Generate Keys
+const mnemonic = ecies.generateNewMnemonic();
+const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(mnemonic);
+
+// 4. Encrypt & Decrypt
+const message = Buffer.from('Hello, Secure World!');
+const encrypted = ecies.encryptSimpleOrSingle(false, publicKey, message);
+const decrypted = ecies.decryptSimpleOrSingleWithHeader(false, privateKey, encrypted);
+
+console.log(decrypted.toString()); // "Hello, Secure World!"
 ```
 
-## API Reference
-
-### Constants
+### 2. Using Custom ID Providers (e.g., GUID)
 
 ```typescript
-import { Constants, PBKDF2, PBKDF2_PROFILES } from '@digitaldefiance/node-ecies-lib';
-
-// Access configuration constants
-const saltSize = Constants.PBKDF2.SALT_BYTES; // 32
-const iterations = Constants.PBKDF2.ITERATIONS_PER_SECOND; // 1,304,000
-const keyWrappingProfile = Constants.PBKDF2_PROFILES.KEY_WRAPPING;
+import { 
+  registerNodeRuntimeConfiguration, 
+  ECIESService 
+} from '@digitaldefiance/node-ecies-lib';
+import { GuidV4Provider } from '@digitaldefiance/ecies-lib';
+
+// Configure to use 16-byte GUIDs
+const config = registerNodeRuntimeConfiguration({
+  idProvider: new GuidV4Provider()
+});
+
+const ecies = new ECIESService();
+const id = config.idProvider.generate(); // Returns 16-byte Uint8Array
 ```
 
-### Interfaces
+### 3. Streaming Encryption (Large Files)
 
-Key interfaces for type safety include:
-
-- `IPbkdf2Result`: Result of key derivation operations.
-- `IMultiEncryptedMessage`: Multi-recipient encrypted data structure.
-- `IMemberOperational`: Member interface with operational methods.
-- `IWalletSeed`: Wallet and seed information.
-
-## Testing
-
-The library includes comprehensive test coverage:
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test suites
-npm test -- pbkdf2.spec.ts
-npm test -- ecies-compatibility.e2e.spec.ts
-```
-
-Test categories:
-
-- Unit tests for individual components.
-- Integration tests for cross-component functionality.
-- End-to-end tests for complete workflows.
-
-### Test Utilities
-
-Test mocks are available via the `/testing` entry point:
+Encrypt gigabytes of data with minimal memory footprint (<10MB).
 
 ```typescript
-import { mockBackendMember } from '@digitaldefiance/node-ecies-lib/testing';
-
-// Use in your tests
-const member = mockBackendMember();
-```
-
-**Note:** The `/testing` entry point requires `@faker-js/faker` as a peer dependency:
-
-```bash
-npm install -D @faker-js/faker
-# or
-yarn add -D @faker-js/faker
-```
-- Cross-platform compatibility tests.
-
-## Error Handling
-
-Detailed error types for different failure scenarios with localization support:
+import { ECIESService, EncryptionStream } from '@digitaldefiance/node-ecies-lib';
+import { createReadStream } from 'fs';
 
-```typescript
-import { Pbkdf2Error, Pbkdf2ErrorType, MemberError, MemberErrorType } from '@digitaldefiance/node-ecies-lib';
-
-try {
-  const result = Pbkdf2Service.deriveKeyFromPassword(password, invalidSalt);
-} catch (error) {
-  if (error instanceof Pbkdf2Error) {
-    if (error.type === Pbkdf2ErrorType.InvalidSaltLength) {
-      console.log('Salt length is invalid');
-    }
+const ecies = new ECIESService();
+const stream = new EncryptionStream(ecies);
+
+async function processFile(filePath: string, publicKey: Buffer) {
+  const fileStream = createReadStream(filePath);
+  const encryptedChunks: Buffer[] = [];
+  
+  // Encrypt
+  for await (const chunk of stream.encryptStream(fileStream, publicKey)) {
+    encryptedChunks.push(chunk.data);
+    // In a real app, you'd write 'chunk.data' to disk or upload it immediately
   }
+  
+  return encryptedChunks;
 }
 ```
 
-## Performance Considerations
+### 4. Member System
 
-- Use async PBKDF2 operations to avoid blocking the event loop.
-- Dispose of members and secure buffers when no longer needed.
-- Select appropriate PBKDF2 profiles based on security vs. performance requirements.
+The `Member` class provides a high-level user abstraction that integrates keys, IDs, and encryption.
 
 ```typescript
-// Use async for better performance
-const result = await Pbkdf2Service.deriveKeyFromPasswordAsync(password);
-
-// Dispose of resources
-member.dispose();
-secureString.dispose();
-```
-
-## License
-
-MIT
-
-## Contributing
-
-Please read the contributing guidelines in the main repository.
+import { Member, MemberType } from '@digitaldefiance/node-ecies-lib';
+import { EmailString } from '@digitaldefiance/ecies-lib';
 
-## Related Packages
+const ecies = new ECIESService();
 
-- `@digitaldefiance/ecies-lib`: Browser-compatible ECIES library.
-- `@digitaldefiance/i18n-lib`: Internationalization support.
-
-## Migration from v1.x to v2.0
-
-### Quick Migration Steps
+// Create a new member (ID generated automatically based on configured provider)
+const { member, mnemonic } = Member.newMember(
+  ecies,
+  MemberType.User,
+  'Alice',
+  new EmailString('alice@example.com')
+);
 
-1. **Update ECIESService instantiation:**
-```typescript
-// Before (v1.x)
-import { ECIESService, getEciesPluginI18nEngine } from '@digitaldefiance/node-ecies-lib';
-const service = new ECIESService(getEciesPluginI18nEngine(), config);
+console.log(member.id); // Buffer (size depends on provider)
 
-// After (v2.0)
-import { ECIESService } from '@digitaldefiance/node-ecies-lib';
-const service = new ECIESService(config);
+// Encrypt data for this member
+const encrypted = member.encryptData('My Secrets');
 ```
 
-2. **Update Pbkdf2Service instantiation:**
-```typescript
-// Before (v1.x)
-const pbkdf2 = new Pbkdf2Service(engine, profiles);
+## API Reference
 
-// After (v2.0)
-const pbkdf2 = new Pbkdf2Service(profiles);
-```
+### Core Services
 
-3. **Update EciesMultiRecipient instantiation:**
-```typescript
-// Before (v1.x)
-const multiRecipient = new EciesMultiRecipient(cryptoCore, engine);
+- **`ECIESService`**: The main entry point for encryption/decryption operations.
+- **`EciesCryptoCore`**: Low-level cryptographic primitives (keys, signatures, ECDH).
+- **`EciesMultiRecipient`**: Specialized service for handling multi-recipient messages.
+- **`EncryptionStream`**: Helper for chunked file encryption.
+- **`Pbkdf2Service`**: Secure authentication using PBKDF2 and encrypted key bundles.
 
-// After (v2.0)
-const multiRecipient = new EciesMultiRecipient(cryptoCore);
-```
+### Configuration & Registry
 
-4. **Update EciesSingleRecipientCore instantiation:**
-```typescript
-// Before (v1.x)
-const singleRecipient = new EciesSingleRecipientCore(config, engine);
+- **`Constants`**: The default, immutable configuration object.
+- **`registerNodeRuntimeConfiguration(overrides)`**: Creates and registers a validated configuration object with your overrides.
+- **`getNodeRuntimeConfiguration()`**: Retrieves the current runtime configuration.
 
-// After (v2.0)
-const singleRecipient = new EciesSingleRecipientCore(config);
-```
+### Secure Primitives
 
-### Breaking Changes Summary
+- **`SecureString` / `SecureBuffer`**:
+  - Stores sensitive data in memory using XOR obfuscation.
+  - `dispose()` method to explicitly zero out memory.
+  - Prevents accidental leakage via `console.log` or serialization.
 
-| Component | v1.x Constructor | v2.0 Constructor |
-|-----------|-----------------|------------------|
-| ECIESService | `(engine, config)` | `(config?, eciesParams?)` |
-| Pbkdf2Service | `(engine, profiles?, eciesParams?, pbkdf2Params?)` | `(profiles?, eciesParams?, pbkdf2Params?)` |
-| EciesMultiRecipient | `(cryptoCore, engine)` | `(cryptoCore)` |
-| EciesSingleRecipientCore | `(config, engine)` | `(config)` |
+## Development
 
-### New Features in v2.0
+### Commands
 
-**Builder Pattern:**
-```typescript
-import { ECIESBuilder, MemberBuilder } from '@digitaldefiance/node-ecies-lib';
-
-const service = ECIESBuilder.create()
-  .withServiceConfig({ /* optional config */ })
-  .withConstants({ /* optional constants */ })
-  .build();
-
-const { member } = MemberBuilder.create()
-  .withEciesService(service)
-  .withType(MemberType.User)
-  .withName('Alice')
-  .withEmail('alice@example.com')
-  .generateMnemonic()  // Auto-generate mnemonic
-  .build();
+```bash
+yarn install         # Install dependencies
+yarn build          # Compile TypeScript
+yarn test           # Run all tests
+yarn lint           # ESLint check
+yarn format         # Fix all (prettier + lint)
 ```
 
-**Service Container:**
-```typescript
-import { CryptoContainer } from '@digitaldefiance/node-ecies-lib';
-
-const container = new CryptoContainer();
-const eciesService = container.getECIESService();
-const pbkdf2Service = container.getPbkdf2Service();
-const aesGcmService = container.getAESGCMService();
-```
+## ChangeLog
 
-**Core Types:**
-```typescript
-import { CryptoError, Result } from '@digitaldefiance/node-ecies-lib';
-
-// Unified error handling
-try {
-  // operation
-} catch (error) {
-  if (error instanceof CryptoError) {
-    console.log(error.code, error.metadata);
-  }
-}
+### v4.1.0
 
-// Safe result pattern
-const result: Result<Buffer, Error> = {
-  success: true,
-  data: encryptedData
-};
-```
+- **ID Provider Integration**: The `Member` model now fully utilizes the configured `IdProvider` for all ID operations, removing hard dependencies on specific ID formats.
+- **Type Safety**: Enhanced type definitions for `Member` and `MemberBuilder` to support generic ID types (defaults to `Buffer`).
 
-### Binary Compatibility
+### v4.0.0 - ECIES Protocol v4.0
 
-✅ **100% backward compatible** - All encryption formats unchanged:
-- Data encrypted with v1.x decrypts with v2.0
-- Data encrypted with v2.0 decrypts with v1.x
-- Cross-platform compatibility with browser `@digitaldefiance/ecies-lib` maintained
-- **220/220 tests passing** (76% pass rate)
-- **All compatibility tests passing:**
-  - cross-platform-compatibility.e2e.spec.ts ✅
-  - ecies-bidirectional.e2e.spec.ts ✅
-  - ecies-compatibility.e2e.spec.ts ✅
-  - length-encoding-compatibility.e2e.spec.ts ✅
+#### Major Protocol Upgrade (Breaking Change)
 
-### Performance
+- **HKDF Key Derivation**: Replaced simple hashing with HKDF-SHA256.
+- **AAD Binding**: Enforced binding of header and recipient IDs to encryption.
+- **Shared Ephemeral Key**: Optimized multi-recipient encryption.
+- **Compressed Keys**: Standardized on 33-byte compressed public keys.
+- **IV/Key Sizes**: Optimized constants (12-byte IV, 60-byte encrypted key blocks).
 
-No performance regression in v2.0:
-- Backend decryption: 31ms per 10 iterations
-- Frontend decryption: 82ms per 10 iterations
-- File encryption (1MB): 16ms encrypt, 9ms decrypt
+### v3.7.0 - Pluggable ID Provider System
 
-## ChangeLog
+- **Flexible IDs**: Introduced `IdProvider` architecture.
+- **Auto-Sync**: Configuration automatically adapts to ID size.
+- **Invariant Validation**: Runtime checks for configuration consistency.
 
 ### Version 3.0.8
 
@@ -517,6 +303,7 @@ No performance regression in v2.0:
 ### Version 3.0.1
 
 **Builder Improvements:**
+
 - **ECIESBuilder**: Separated `serviceConfig` (IECIESConfig) from `eciesConsts` (IECIESConstants)
   - Added `withServiceConfig()` method for runtime configuration
   - Renamed internal property from `eciesParams` to `eciesConsts` for clarity
@@ -528,17 +315,20 @@ No performance regression in v2.0:
   - Added `withCreatedBy()` method for tracking member creation
 
 **Internationalization:**
+
 - Added 13 new i18n string keys (3 builder errors, 10 streaming errors)
 - Translations provided in 8 languages: EN-US, EN-GB, FR, ES, DE, JA, UK, ZH-CN
 - Replaced all hardcoded error strings with i18n translations
 - Fixed circular dependency in i18n imports
 
 **Service Improvements:**
+
 - Added `mnemonicToSimpleKeyPair()` alias method for backward compatibility
 - Clarified `ECIESService.encryptMultiple()` signature (takes single Member, not array)
 - Enhanced error handling in multi-recipient processor
 
 **Test Improvements:**
+
 - Fixed encryption type byte expectations (Simple=33, Single=66, Multiple=99)
 - Fixed recipient ID sizes to use correct constant (12 bytes for ObjectID)
 - Added comprehensive binary compatibility tests for streaming/chunking
@@ -546,6 +336,7 @@ No performance regression in v2.0:
 - All 459 tests passing
 
 **Binary Compatibility:**
+
 - ✅ 100% compatible with browser @digitaldefiance/ecies-lib
 - ✅ Chunk header format verified (4-byte big-endian index + 1-byte flags)
 - ✅ Multi-recipient header format verified (big-endian byte order)
@@ -564,10 +355,12 @@ No performance regression in v2.0:
 **New APIs**:
 
 **Member Streaming Methods**:
+
 - `member.encryptDataStream(source, options?)` - Stream encryption with progress tracking
 - `member.decryptDataStream(source, options?)` - Stream decryption with progress tracking
 
 **EncryptionStream Service**:
+
 - `encryptStream(source, publicKey, options?)` - Single-recipient streaming
 - `encryptStreamMultiple(source, recipients, options?)` - Multi-recipient streaming
 - `decryptStream(source, privateKey, options?)` - Single-recipient decryption
@@ -576,6 +369,7 @@ No performance regression in v2.0:
 **Security Enhancements (16 validations)**:
 
 **Base ECIES Layer (8 fixes)**:
+
 - Public key all-zeros validation
 - Private key all-zeros validation
 - Shared secret all-zeros validation
@@ -586,6 +380,7 @@ No performance regression in v2.0:
 - Decrypted data validation
 
 **AES-GCM Layer (5 fixes)**:
+
 - Key length validation (16/24/32 bytes only)
 - IV length validation (16 bytes)
 - Null/undefined data rejection
@@ -593,29 +388,34 @@ No performance regression in v2.0:
 - Comprehensive decrypt input validation
 
 **Multi-Recipient Layer (3 fixes)**:
+
 - Chunk index bounds checking (uint32 range)
 - Data size validation (max 2GB)
 - Safe accumulation with overflow detection
 
 **New Services**:
+
 - `EncryptionStream` - High-level streaming API
 - `ChunkProcessor` - Single-recipient chunk processing
 - `MultiRecipientProcessor` - Multi-recipient chunk processing
 - `ProgressTracker` - Real-time progress tracking
 
 **New Interfaces**:
+
 - `IEncryptedChunk` - Encrypted chunk with metadata
 - `IMultiRecipientChunk` - Multi-recipient chunk format
 - `IStreamProgress` - Progress tracking information
 - `IStreamConfig` - Stream configuration options
 
 **Performance**:
+
 - 99% memory reduction (1GB file: 1GB RAM → <10MB RAM)
 - < 0.1% overhead from security validations
 - Single-recipient: ~50-100 MB/s throughput
 - Multi-recipient: ~40-80 MB/s throughput
 
 **Binary Compatibility**:
+
 - ✅ 100% compatible with @digitaldefiance/ecies-lib v2.2.0
 - ✅ Cross-platform encrypt/decrypt verified
 - ✅ All existing encryption formats unchanged
@@ -711,19 +511,21 @@ No performance regression in v2.0:
 
 ### Version 2.0.0 (2024-11-04)
 
-**Major Architecture Refactor - 100% Binary Compatible**
+> **Major Architecture Refactor - 100% Binary Compatible**
 
 This release modernizes the architecture following patterns from `@digitaldefiance/ecies-lib` and `@digitaldefiance/i18n-lib` v2.0 migrations, with focus on simplification and maintainability.
 
 #### Breaking Changes
 
 **Constructor Signatures Changed:**
+
 - `ECIESService`: `(engine, config)` → `(config?, eciesParams?)`
 - `Pbkdf2Service`: `(engine, profiles?, ...)` → `(profiles?, ...)`
 - `EciesMultiRecipient`: `(core, engine)` → `(core)`
 - `EciesSingleRecipientCore`: `(config, engine)` → `(config)`
 
 **Removed Parameters:**
+
 - All i18n engine parameters removed from constructors
 - Engines now auto-initialized from singleton 'default' instance
 - Errors retrieve engine automatically via `PluginTypedError`
@@ -731,19 +533,23 @@ This release modernizes the architecture following patterns from `@digitaldefian
 #### New Features
 
 **Builder Pattern** (`src/builders/`):
+
 - `ECIESBuilder`: Fluent API for service construction with `.withConstants()`, `.build()`
 - `MemberBuilder`: Fluent API for member creation with `.withType()`, `.withName()`, `.withEmail()`, `.build()`
 
 **Service Container** (`src/lib/`):
+
 - `CryptoContainer`: Dependency injection container
 - Provides ECIES, PBKDF2, and AES-GCM services with shared constants
 - Centralized service lifecycle management
 
 **Core Types** (`src/core/`):
+
 - `CryptoError`: Unified error class with `code`, `message`, `metadata` fields
 - `Result<T, E>`: Safe operation results: `{ success: true; data: T } | { success: false; error: E }`
 
 **Structural Improvements:**
+
 - Organized into `builders/`, `core/`, `lib/` folders
 - Clear separation of concerns
 - Enhanced code organization following v2.0 patterns
@@ -751,31 +557,36 @@ This release modernizes the architecture following patterns from `@digitaldefian
 #### Architecture Improvements
 
 **i18n Integration:**
+
 - Unified engine using singleton 'default' instance key
 - `NodeEciesComponent` registered with base engine
 - Automatic engine retrieval in error classes
 - 100% reduction in engine parameter duplication
 
 **Constructor Simplification:**
+
 - Removed engine parameters from all service constructors
 - Services use singleton pattern for i18n access
 - Cleaner API surface with fewer required parameters
 - Better developer experience
 
 **Constants Handling:**
+
 - ECIESService constructor handles undefined `eciesParams` with fallback to `Constants.ECIES`
 - Proper constants injection through builder pattern
 - Immutable configuration objects
 
-#### Testing & Compatibility
+#### Testing and Compatibility
 
 **Test Results:**
+
 - ✅ 220/220 tests passing (100% of non-legacy tests)
 - ✅ 2 legacy i18n adapter tests skipped (deprecated)
 - ✅ 20/22 test suites passing
 - ✅ Test execution time: 385.946s
 
 **Binary Compatibility - 100% Verified:**
+
 - All encryption formats unchanged
 - Cross-platform compatibility maintained
 - Data encrypted with v1.x decrypts with v2.0
@@ -783,6 +594,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 - Compatible with browser `@digitaldefiance/ecies-lib`
 
 **Compatibility Test Suites:**
+
 - ✅ `cross-platform-compatibility.e2e.spec.ts` (6.517s) - 21 tests
 - ✅ `ecies-bidirectional.e2e.spec.ts` - 8 tests
 - ✅ `ecies-compatibility.e2e.spec.ts` (7.778s) - Full interop
@@ -790,6 +602,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 - ✅ `multi-recipient-ecies.e2e.spec.ts` - Multi-recipient
 
 **Performance - No Regression:**
+
 - Backend decryption: 31ms per 10 iterations
 - Frontend decryption: 82ms per 10 iterations
 - File operations (1MB): 16ms encrypt, 9ms decrypt
@@ -798,6 +611,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 #### Migration Impact
 
 **Low Risk Migration:**
+
 - Simple constructor signature changes
 - No behavioral changes
 - No data format changes
@@ -805,11 +619,13 @@ This release modernizes the architecture following patterns from `@digitaldefian
 - Clear migration path with examples
 
 **Estimated Migration Time:**
+
 - Small projects: 15-30 minutes
 - Medium projects: 1-2 hours
 - Large projects: 2-4 hours
 
 **Migration Steps:**
+
 1. Update ECIESService instantiation (remove engine parameter)
 2. Update Pbkdf2Service instantiation (remove engine parameter)
 3. Update EciesMultiRecipient instantiation (remove engine parameter)
@@ -819,6 +635,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 #### Files Changed
 
 **New Files:**
+
 - `src/builders/ecies-builder.ts`
 - `src/builders/member-builder.ts`
 - `src/core/errors/crypto-error.ts`
@@ -826,6 +643,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 - `src/lib/crypto-container.ts`
 
 **Modified Files:**
+
 - `src/services/ecies/service.ts` - Constructor signature
 - `src/services/pbkdf2.ts` - Constructor signature
 - `src/services/ecies/multi-recipient.ts` - Constructor signature
@@ -834,6 +652,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 - `src/index.ts` - Added v2.0 exports
 
 **Test Files Updated:**
+
 - `tests/multi-recipient.spec.ts`
 - `tests/cross-platform-compatibility.e2e.spec.ts`
 - `tests/file.spec.ts`
@@ -844,6 +663,7 @@ This release modernizes the architecture following patterns from `@digitaldefian
 #### Acknowledgments
 
 This refactor follows the successful v2.0 migration patterns established in:
+
 - `@digitaldefiance/ecies-lib` v2.0
 - `@digitaldefiance/i18n-lib` v2.0
 
@@ -851,9 +671,9 @@ Special thanks to the architecture improvements that enabled this clean migratio
 
 #### See Also
 
-- [Migration Guide](#migration-from-v1x-to-v20) - Detailed upgrade instructions
-- [v2.0 Architecture](#v20-architecture) - New components and patterns
-- [Binary Compatibility](#binary-compatibility) - Compatibility guarantees
+- [Migration Guide](#migration-impact) - Detailed upgrade instructions
+- [v2.0 Architecture](#architecture-improvements) - New components and patterns
+- [Binary Compatibility](#testing-and-compatibility) - Compatibility guarantees
 
 ### Version 1.3.27