@digitaldefiance/ecies-lib 4.0.0 → 4.1.1

package/README.md

@@ -2,1466 +2,289 @@
 
 [![npm version](https://badge.fury.io/js/%40digitaldefiance%2Fecies-lib.svg)](https://www.npmjs.com/package/@digitaldefiance/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-646%20passing-brightgreen)](https://github.com/Digital-Defiance/ecies-lib)
+[![Tests](https://img.shields.io/badge/tests-1200%2B%20passing-brightgreen)](https://github.com/Digital-Defiance/ecies-lib)
 
 Production-ready, browser-compatible ECIES (Elliptic Curve Integrated Encryption Scheme) library for TypeScript. Built on Web Crypto API and @noble/curves with comprehensive encryption, key management, and authentication services. Binary compatible with @digitaldefiance/node-ecies-lib for seamless cross-platform operations.
 
 Part of [Express Suite](https://github.com/Digital-Defiance/express-suite)
 
-**Version 2.0** features a modernized i18n architecture with automatic error translation in 8 languages and simplified service APIs.
+**Current Version: v4.1.0**
 
-## Features
-
-### Core Cryptography
-
-- **ECIES Encryption** – Simple (98-byte overhead), Single (106-byte overhead), Multiple (multi-recipient) modes
-- **secp256k1 Curve** – ECDH key exchange and ECDSA signatures
-- **AES-256-GCM** – Authenticated symmetric encryption via Web Crypto API
-- **PBKDF2** – Configurable password-based key derivation profiles
-
-### Key Management
-
-- **BIP39 Mnemonics** – 12/15/18/21/24-word phrase generation and key derivation
-- **HD Wallets** – BIP32/BIP44 hierarchical deterministic derivation
-- **Member System** – User abstraction with cryptographic operations
-- **Secure Storage** – Memory-safe SecureString/SecureBuffer with XOR obfuscation and auto-zeroing
-
-### Advanced
-
-- **Streaming Encryption** – Memory-efficient encryption for large files (<10MB RAM for any size) ✨ NEW
-- **Multi-Recipient** – Encrypt for up to 65,535 recipients efficiently
-- **File Encryption** – Chunked 1MB segments for large files
-- **Password Login** – Complete authentication with encrypted key storage
-- **Signatures** – ECDSA message signing and verification
-
-### Developer Experience
-
-- **TypeScript** – Full type definitions and interfaces
-- **i18n** – Error messages in 8 languages (en-US, en-GB, fr, es, de, zh-CN, ja, uk)
-- **Runtime Config** – Injectable configuration profiles via ConstantsRegistry
-- **Testing** – 40 test files with 480+ specs (unit, integration, e2e)
-- **Cross-Platform** – Node.js 18+ and modern browsers
-
-## Installation
-
-```bash
-npm install @digitaldefiance/ecies-lib
-# or
-yarn add @digitaldefiance/ecies-lib
-```
-
-### Requirements
-
-**Node.js**: 18+ (Web Crypto API built-in)
-
-- For Node < 18: `import { webcrypto } from 'crypto'; globalThis.crypto = webcrypto as unknown as Crypto;`
-
-**Browsers**: Chrome/Edge 60+, Firefox 60+, Safari 14+, Opera 47+
-
-**Dependencies**: `@digitaldefiance/i18n-lib`, `@noble/curves`, `@scure/bip32`, `@scure/bip39`, `@ethereumjs/wallet`, `bson`, `ts-brand`
-
-## Quick Start
-
-### Streaming Encryption (NEW)
-
-Memory-efficient encryption for large files:
-
-```typescript
-import { ECIESService, EncryptionStream } from '@digitaldefiance/ecies-lib';
-
-const ecies = new ECIESService();
-const stream = new EncryptionStream(ecies);
-const mnemonic = ecies.generateNewMnemonic();
-const { publicKey, privateKey } = ecies.mnemonicToSimpleKeyPair(mnemonic);
-
-// Encrypt large file with <10MB RAM
-const file = document.querySelector('input[type="file"]').files[0];
-const encryptedChunks: Uint8Array[] = [];
-
-for await (const chunk of stream.encryptStream(file.stream(), publicKey)) {
-  encryptedChunks.push(chunk.data);
-}
-
-// Decrypt
-const decryptedChunks: Uint8Array[] = [];
-for await (const chunk of stream.decryptStream(
-  (async function* () {
-    for (const encrypted of encryptedChunks) yield encrypted;
-  })(),
-  privateKey
-)) {
-  decryptedChunks.push(chunk);
-}
-```
-
-**Features:**
-
-- 99% memory reduction (1GB file: 1GB RAM → <10MB RAM)
-- Cancellation support via AbortSignal
-- AsyncGenerator API for flexibility
-- Works with ReadableStream and AsyncIterable
-
-See [Streaming API Quick Start](./docs/STREAMING_API_QUICKSTART.md) for more examples.
-
-### Basic Encryption
-
-```typescript
-import { ECIESService, getEciesI18nEngine } from '@digitaldefiance/ecies-lib';
-
-// Initialize i18n engine (required for error messages)
-getEciesI18nEngine();
-
-const ecies = new ECIESService();
-const mnemonic = ecies.generateNewMnemonic();
-const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(mnemonic);
-
-// Encrypt
-const message = new TextEncoder().encode('Hello, World!');
-const encrypted = await ecies.encryptSimpleOrSingle(false, publicKey, message);
-
-// Decrypt
-const decrypted = await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, encrypted);
-console.log(new TextDecoder().decode(decrypted)); // "Hello, World!"
-```
-
-### Member System
-
-```typescript
-import { ECIESService, Member, MemberType, EmailString } from '@digitaldefiance/ecies-lib';
-
-const ecies = new ECIESService();
-const { member, mnemonic } = Member.newMember(
-  ecies,
-  MemberType.User,
-  'Alice',
-  new EmailString('alice@example.com')
-);
-
-// Encrypt/decrypt (up to 10MB)
-const encrypted = await member.encryptData('Sensitive data');
-const decrypted = await member.decryptData(encrypted);
-
-// Streaming encryption (any size)
-const file = document.querySelector('input[type="file"]').files[0];
-const chunks: Uint8Array[] = [];
-for await (const chunk of member.encryptDataStream(file.stream())) {
-  chunks.push(chunk.data);
-}
-
-// Sign/verify
-const signature = member.sign(new TextEncoder().encode('Message'));
-const valid = member.verify(signature, new TextEncoder().encode('Message'));
-```
-
-## Core Services
-
-### ECIESService
-
-Main encryption service with three modes:
-
-```typescript
-import { ECIESService } from '@digitaldefiance/ecies-lib';
-
-const ecies = new ECIESService();
-const mnemonic = ecies.generateNewMnemonic();
-const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(mnemonic);
-
-// Simple mode (98-byte overhead, no length prefix)
-const simple = await ecies.encryptSimpleOrSingle(true, publicKey, message);
-
-// Single mode (106-byte overhead, 8-byte length prefix)
-const single = await ecies.encryptSimpleOrSingle(false, publicKey, message);
-
-// Decrypt with automatic header parsing
-const decrypted = await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, single);
-```
-
-### EciesMultiRecipient
-
-Encrypt once for multiple recipients:
-
-```typescript
-import { EciesMultiRecipient, EciesCryptoCore, Constants } from '@digitaldefiance/ecies-lib';
-
-const config = {
-  curveName: Constants.ECIES.CURVE_NAME,
-  primaryKeyDerivationPath: Constants.ECIES.PRIMARY_KEY_DERIVATION_PATH,
-  mnemonicStrength: Constants.ECIES.MNEMONIC_STRENGTH,
-  symmetricAlgorithm: Constants.ECIES.SYMMETRIC.ALGORITHM,
-  symmetricKeyBits: Constants.ECIES.SYMMETRIC.KEY_BITS,
-  symmetricKeyMode: Constants.ECIES.SYMMETRIC.MODE,
-};
-
-const multi = new EciesMultiRecipient(config);
-const core = new EciesCryptoCore(config);
-
-// Generate recipients
-const recipients = await Promise.all(
-  [...Array(3)].map(async () => {
-    const { privateKey, publicKey } = await core.generateEphemeralKeyPair();
-    return {
-      id: crypto.getRandomValues(new Uint8Array(Constants.ECIES.MULTIPLE.RECIPIENT_ID_SIZE)),
-      privateKey,
-      publicKey,
-    };
-  })
-);
-
-// Encrypt for all
-const encrypted = await multi.encryptMultiple(
-  recipients.map(({ id, publicKey }) => ({ id, publicKey })),
-  new TextEncoder().encode('Broadcast message')
-);
-
-// Any recipient can decrypt
-const decrypted = await multi.decryptMultipleForRecipient(
-  multi.parseMessage(multi.buildHeader(encrypted) + encrypted.encryptedMessage),
-  recipients[0].id,
-  recipients[0].privateKey
-);
-```
-
-### EciesFileService
-
-Chunked file encryption:
-
-```typescript
-import { ECIESService, EciesFileService } from '@digitaldefiance/ecies-lib';
-
-const ecies = new ECIESService();
-const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(ecies.generateNewMnemonic());
-const fileService = new EciesFileService(ecies, privateKey);
-
-// Encrypt file (1MB chunks)
-const encrypted = await fileService.encryptFile(file, publicKey);
-
-// Decrypt file
-const decrypted = await fileService.decryptFile(encrypted);
-
-// Download
-fileService.downloadEncryptedFile(encrypted, 'document.enc');
-fileService.downloadDecryptedFile(decrypted, 'document.pdf');
-```
-
-### PasswordLoginService
-
-Password-based authentication:
-
-```typescript
-import {
-  ECIESService,
-  PasswordLoginService,
-  Pbkdf2Service,
-  Pbkdf2ProfileEnum,
-  SecureString,
-  getEciesI18nEngine,
-} from '@digitaldefiance/ecies-lib';
-
-// Initialize i18n (v2.0 - no longer passed to services)
-getEciesI18nEngine();
-
-const ecies = new ECIESService();
-const pbkdf2 = new Pbkdf2Service();
-const passwordLogin = new PasswordLoginService(ecies, pbkdf2);
-
-// Setup
-const mnemonic = ecies.generateNewMnemonic();
-const password = new SecureString('MySecurePassword123!');
-await passwordLogin.setupPasswordLoginLocalStorageBundle(
-  mnemonic,
-  password,
-  Pbkdf2ProfileEnum.BROWSER_PASSWORD
-);
-
-// Login
-const { wallet, mnemonic: recovered } = 
-  await passwordLogin.getWalletAndMnemonicFromLocalStorageBundle(password);
-
-// Check setup
-if (PasswordLoginService.isPasswordLoginSetup()) {
-  console.log('Ready');
-}
-```
-
-### Pbkdf2Service
-
-Key derivation with profiles:
-
-```typescript
-import { Pbkdf2Service, Pbkdf2ProfileEnum, getEciesI18nEngine } from '@digitaldefiance/ecies-lib';
-
-// Initialize i18n
-getEciesI18nEngine();
-
-const pbkdf2 = new Pbkdf2Service();
-
-// Use built-in profile
-const result = await pbkdf2.deriveKeyFromPasswordWithProfileAsync(
-  new TextEncoder().encode('password123'),
-  Pbkdf2ProfileEnum.HIGH_SECURITY
-);
-
-console.log(result.hash);       // Derived key
-console.log(result.salt);       // Salt
-console.log(result.iterations); // 5,000,000
-
-// Custom profiles
-const custom = new Pbkdf2Service({
-  ULTRA_SECURE: {
-    hashBytes: 64,
-    saltBytes: 32,
-    iterations: 5000000,
-    algorithm: 'SHA-512',
-  },
-});
-```
-
-**Built-in Profiles:**
-
-- `BROWSER_PASSWORD`: 2M iterations, SHA-512, 32-byte hash
-- `HIGH_SECURITY`: 5M iterations, SHA-256, 64-byte hash  
-- `TEST_FAST`: 1K iterations, SHA-512, 32-byte hash
-
-## Runtime Configuration
-
-Injectable configuration profiles via ConstantsRegistry:
-
-```typescript
-import {
-  ConstantsRegistry,
-  registerRuntimeConfiguration,
-  getRuntimeConfiguration,
-  ECIESService,
-  Pbkdf2Service,
-  getEciesI18nEngine,
-} from '@digitaldefiance/ecies-lib';
-
-// Register profiles
-registerRuntimeConfiguration('security-first', {
-  PBKDF2: { ITERATIONS_PER_SECOND: 3_000_000 },
-});
-
-registerRuntimeConfiguration('performance-first', {
-  PBKDF2: { ITERATIONS_PER_SECOND: 250_000 },
-});
-
-// Use profiles
-getEciesI18nEngine(); // Initialize i18n
-
-const secureConfig = getRuntimeConfiguration('security-first');
-const secureEcies = new ECIESService(undefined, secureConfig.ECIES);
-const securePbkdf2 = new Pbkdf2Service(
-  secureConfig.PBKDF2_PROFILES,
-  secureConfig.ECIES,
-  secureConfig.PBKDF2
-);
-
-// Cleanup
-unregisterRuntimeConfiguration('performance-first');
-```
-
-**Registry API:**
-
-- `ConstantsRegistry.get(key)` – Retrieve configuration
-- `ConstantsRegistry.register(key, config)` – Register new profile
-- `ConstantsRegistry.create(overrides)` – Create without registering
-- `ConstantsRegistry.listKeys()` – List all keys
-- `ConstantsRegistry.has(key)` – Check existence
-- `ConstantsRegistry.unregister(key)` – Remove profile
-- `ConstantsRegistry.clear()` – Reset to defaults
-
-**Exports:**
-
-- `Constants` – Frozen default configuration
-- `createRuntimeConfiguration(overrides, base?)` – Deep merge and validate
-- `PASSWORD_REGEX`, `MNEMONIC_REGEX` – Validation patterns
-
-## Secure Memory
-
-XOR-obfuscated storage with checksums:
-
-```typescript
-import { SecureString, SecureBuffer } from '@digitaldefiance/ecies-lib';
-
-// SecureString for passwords/mnemonics
-const password = new SecureString('MyPassword123');
-console.log(password.value);           // Access value
-console.log(password.valueAsHexString); // Hex format
-console.log(password.length);          // Length
-password.dispose();                    // Zero memory
-
-// SecureBuffer for binary secrets
-const key = new SecureBuffer(new Uint8Array(32));
-console.log(key.value);               // Uint8Array
-console.log(key.valueAsString);       // String
-console.log(key.valueAsBase64String); // Base64
-key.dispose();                        // Zero memory
-
-// Features:
-// - XOR obfuscation in memory
-// - Checksum validation
-// - Disposal detection
-// - Stack traces for debugging
-```
-
-## Value Objects
-
-Type-safe wrapper:
-
-```typescript
-import { EmailString } from '@digitaldefiance/ecies-lib';
-
-// Validated emails
-const email = new EmailString('user@example.com');
-// new EmailString('invalid'); // throws InvalidEmailError
-```
-
-## Error Handling
-
-Typed errors with i18n (8 languages):
-
-```typescript
-import {
-  ECIESError,
-  ECIESErrorTypeEnum,
-  MemberError,
-  MemberErrorType,
-  Pbkdf2Error,
-  Pbkdf2ErrorType,
-} from '@digitaldefiance/ecies-lib';
-
-try {
-  await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, tamperedData);
-} catch (error) {
-  if (error instanceof ECIESError) {
-    switch (error.type) {
-      case ECIESErrorTypeEnum.DecryptionFailed:
-        console.error('Decryption failed');
-        break;
-      case ECIESErrorTypeEnum.InvalidEncryptionType:
-        console.error('Invalid encryption type');
-        break;
-    }
-  }
-}
-
-// Error categories:
-// - ECIESError: Encryption/decryption
-// - MemberError: Member operations
-// - Pbkdf2Error: Key derivation
-// - LengthError: Data length
-// - SecureStorageError: Memory operations
-// - InvalidEmailError: Email validation
-```
-
-## Architecture
-
-### Structure
-
-```
-src/
-├── services/
-│   ├── ecies/
-│   │   ├── service.ts          # ECIESService
-│   │   ├── crypto-core.ts      # EciesCryptoCore
-│   │   ├── multi-recipient.ts  # EciesMultiRecipient
-│   │   ├── single-recipient.ts # EciesSingleRecipient
-│   │   ├── file.ts             # EciesFileService
-│   │   └── signature.ts        # EciesSignature
-│   ├── aes-gcm.ts              # AESGCMService
-│   ├── pbkdf2.ts               # Pbkdf2Service
-│   ├── password-login.ts       # PasswordLoginService
-│   └── xor.ts                  # XorService
-├── enumerations/               # Type-safe enums
-├── errors/                     # Typed error classes
-├── interfaces/                 # TypeScript interfaces
-├── types/                      # Type definitions
-├── constants.ts                # Constants & ConstantsRegistry
-├── member.ts                   # Member class
-├── secure-string.ts            # SecureString
-├── secure-buffer.ts            # SecureBuffer
-├── email-string.ts             # EmailString
-├── utils.ts                    # Utilities
-├── i18n-setup.ts               # i18n configuration
-└── index.ts                    # Public API
-
-tests/                          # 32 test files, 389+ specs
-```
-
-### Key Concepts
-
-**Encryption Modes:**
-
-- Simple: 98-byte overhead (type + pubkey + IV + tag)
-- Single: 106-byte overhead (Simple + 8-byte length)
-- Multiple: Shared symmetric key per recipient
-
-**Key Derivation:**
-
-- BIP39 mnemonic → BIP32 HD wallet → secp256k1 keypair
-- Deterministic generation
-- Custom derivation paths supported
-
-**Security:**
-
-- AES-256-GCM authenticated encryption
-- ECDH key agreement (secp256k1)
-- PBKDF2 with configurable iterations
-- Memory-safe storage with auto-zeroing
-- XOR obfuscation for in-memory secrets
-
-## Development
-
-### Commands
-
-```bash
-yarn install         # Install dependencies
-yarn build          # Compile TypeScript
-yarn test           # Run all tests (389+ specs)
-yarn test:stream    # Stream test output
-yarn lint           # ESLint check
-yarn lint:fix       # Auto-fix issues
-yarn prettier:check # Format check
-yarn prettier:fix   # Auto-format
-yarn format         # Fix all (prettier + lint)
-```
-
-### Testing
-
-32 test files covering:
-
-- Unit tests for all services
-- Integration tests for workflows
-- E2E tests for password login and file encryption
-- Cross-platform compatibility
-- Error handling and edge cases
-
-#### Test Utilities
-
-Test mocks are available via the `/testing` entry point:
-
-```typescript
-import { mockFrontendMember } from '@digitaldefiance/ecies-lib/testing';
-
-// Use in your tests
-const member = mockFrontendMember();
-```
-
-**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
-```
-
-### Quality Gates
-
-CI enforces:
-
-- ESLint (no errors)
-- Prettier formatting
-- 389+ Jest specs passing
-- TypeScript compilation
-
-## Platform Notes
-
-### Node.js
-
-Node 18+ includes Web Crypto API. For older versions:
-
-```typescript
-import { webcrypto } from 'crypto';
-globalThis.crypto = webcrypto as unknown as Crypto;
-```
-
-### Browser
-
-Works in all modern browsers:
-
-- Web Crypto API for cryptography
-- No polyfills needed
-- Tree-shakeable with Vite/Webpack/Rollup
-- ESM-compatible dependencies
-
-### Bundler Config
-
-**Vite:**
-
-```javascript
-export default {
-  optimizeDeps: {
-    include: ['@digitaldefiance/ecies-lib']
-  }
-}
-```
-
-**Webpack:**
-
-```javascript
-module.exports = {
-  resolve: {
-    fallback: {
-      crypto: false,
-      stream: false
-    }
-  }
-}
-```
-
-### Memory Management
-
-Always dispose sensitive data:
-
-```typescript
-const password = new SecureString('secret');
-try {
-  // Use password
-} finally {
-  password.dispose(); // Zeros memory
-}
-```
-
-## API Reference
-
-### Main Exports
-
-```typescript
-// Services
-export { ECIESService, EciesCryptoCore, EciesMultiRecipient, EciesFileService };
-export { AESGCMService, Pbkdf2Service, PasswordLoginService, XorService };
-
-// Member System
-export { Member, MemberType };
-
-// Secure Primitives
-export { SecureString, SecureBuffer, EmailString };
-
-// Configuration
-export { Constants, ConstantsRegistry, CHECKSUM, ECIES, PBKDF2 };
-export { createRuntimeConfiguration, getRuntimeConfiguration };
-export { registerRuntimeConfiguration, unregisterRuntimeConfiguration };
-export { PASSWORD_REGEX, MNEMONIC_REGEX };
-
-// Enumerations
-export { EciesEncryptionTypeEnum, Pbkdf2ProfileEnum };
-export { MemberErrorType, ECIESErrorTypeEnum };
-
-// Errors
-export { ECIESError, MemberError, Pbkdf2Error };
-export { LengthError, SecureStorageError, InvalidEmailError };
-
-// Utilities
-export { concatUint8Arrays, uint8ArrayToHex, hexToUint8Array };
-export { uint8ArrayToBase64, base64ToUint8Array };
-
-// i18n
-export { getEciesI18nEngine, EciesI18nEngine };
-```
-
-## Contributing
-
-1. Fork & clone the repo.
-2. Install dependencies with `yarn install` (Yarn 4 is already configured via `.yarnrc`).
-3. Create a feature branch (`git checkout -b feature/awesome`).
-4. Make changes and run `yarn format && yarn lint && yarn test`.
-5. Submit a PR with a clear description and test evidence.
-
-Bug reports and feature requests are welcome—open an issue with reproduction steps and expected behavior.
-
-## Security
-
-If you discover a vulnerability, please **do not** open a public issue. Email <security@digitaldefiance.org> with details so we can coordinate a fix and responsible disclosure timeline.
-
-## License
-
-MIT © Digital Defiance
-
-## Links
-
-- **Repository:** <https://github.com/Digital-Defiance/ecies-lib>
-- **npm:** <https://www.npmjs.com/package/@digitaldefiance/ecies-lib>
-- **Companion:** @digitaldefiance/node-ecies-lib (binary compatible)
-
-## Migration from v1.x to v2.0
-
-**Breaking Changes**: Service constructors no longer accept i18n engine parameter.
-
-### Quick Migration
-
-**Before (v1.x)**:
-
-```typescript
-const engine = getEciesI18nEngine();
-const pbkdf2 = new Pbkdf2Service(engine);
-const passwordLogin = new PasswordLoginService(ecies, pbkdf2, engine);
-```
-
-**After (v2.0)**:
-
-```typescript
-getEciesI18nEngine(); // Just initialize once
-const pbkdf2 = new Pbkdf2Service();
-const passwordLogin = new PasswordLoginService(ecies, pbkdf2);
-```
-
-### Key Changes
-
-1. **Automatic Engine Retrieval**: Errors now automatically retrieve the i18n engine from a singleton instance
-2. **Simplified Constructors**: Services no longer require engine parameter
-3. **Initialize Once**: Call `getEciesI18nEngine()` at app startup or in test setup
-
-## ChangeLog
-
-### v4.0.0 - ECIES Protocol v4.0: Enterprise-Grade Security & Efficiency
-
-#### 🛡️ Major Protocol Upgrade (Breaking Changes)
-
-Version 4.0 introduces a complete overhaul of the ECIES protocol to meet modern security standards and improve efficiency. This is a **breaking change**; messages encrypted with v4.0 cannot be decrypted by v3.x libraries, and vice versa.
-
-**Key Improvements:**
-
-- **Compressed Keys (33 bytes)**: Switched from uncompressed (65 bytes) to compressed public keys, reducing overhead and aligning with modern crypto standards.
-- **HKDF Key Derivation**: Replaced simple SHA-256 hashing with **HKDF-SHA256** (RFC 5869) for cryptographically robust key derivation.
-- **Shared Ephemeral Key**: Multi-recipient encryption now uses a **single ephemeral key pair** for all recipients, significantly reducing encryption time and message size.
-- **AAD Binding**: Header fields (version, algorithm, recipient IDs) are now bound to the encryption via **Additional Authenticated Data (AAD)**. This prevents header tampering and context manipulation attacks.
-- **Sign-then-Encrypt**: Added native support for signing messages before encryption, ensuring sender authenticity.
-
-#### 💥 v4.0 Breaking Changes
-
-1. **Message Format**: The version byte is now `0x04`. The internal structure of encrypted messages has changed completely.
-2. **API Changes**:
-   - `encryptMultiple` now takes a `SharedKeyMode` parameter (default: `Shared`).
-   - `EciesRecipient` now expects compressed public keys (33 bytes).
-3. **Key Management**:
-   - `mnemonicToSimpleKeyPair` and other key utilities now return compressed public keys by default.
-
-#### 🔒 Security Enhancements
-
-- **Strict Header Validation**: Decryption now strictly validates all header fields against the AAD tag.
-- **Recipient ID Binding**: Recipient IDs are included in the AAD, preventing ID swapping attacks.
-- **Robust Signatures**: Improved signature handling with strict type checking for `@noble/curves` return values.
-
-#### 📚 Documentation
-
-- **Architecture**: See [ECIES_V4_ARCHITECTURE.md](./docs/ECIES_V4_ARCHITECTURE.md) for the full protocol specification.
-- **Migration**: See [NODE_ECIES_V4_MIGRATION_INSTRUCTIONS.md](./docs/NODE_ECIES_V4_MIGRATION_INSTRUCTIONS.md) for porting guidelines.
+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.
 
----
-
-### v3.8.0
-
-- Add recipient ID length to header
-
-### v3.7.5
-
-- Fix export
-
-### v3.7.4
-
-- Fix export
-
-### v3.7.0-3.7.3 - Pluggable ID Provider System & Critical Bug Fixes
-
-#### 🎯 Overview
-
-Version 3.7.0 introduces a **pluggable ID provider system** that replaces hardcoded recipient ID sizes with a flexible, extensible architecture. This release fixes a critical 12 vs 32-byte recipient ID discrepancy and adds enterprise-grade validation to prevent entire classes of configuration bugs.
-
-**Critical Fix:** Resolved silent encryption/decryption failures caused by mismatched recipient ID size constants (12 bytes in `ECIES.MULTIPLE.RECIPIENT_ID_SIZE` vs 32 bytes in `MULTI_RECIPIENT_CONSTANTS.RECIPIENT_ID_SIZE`).
-
----
-
-#### 🚀 Major Features
-
-**Pluggable ID Provider System**
-
-Introduced flexible ID provider architecture with multiple built-in implementations:
-
-- **ObjectIdProvider** (12 bytes) - MongoDB/BSON compatible IDs, **DEFAULT**
-- **GuidV4Provider** (16 bytes) - RFC 4122 compliant GUIDs without dashes  
-- **UuidProvider** (16 bytes) - Standard UUIDs with dash separators
-- **CustomIdProvider** (1-255 bytes) - User-defined ID sizes and formats
-
-```typescript
-// Example: Using GUID provider
-import { createRuntimeConfiguration, GuidV4Provider } from '@digitaldefiance/ecies-lib';
-
-const config = createRuntimeConfiguration({
-  idProvider: new GuidV4Provider(), // 16-byte GUIDs
-});
-
-const id = config.idProvider.generate(); // Generates 16-byte GUID
-```
-
-**Auto-Sync Configuration System**
-
-All ID-size-related constants now automatically synchronize when an ID provider is set:
-
-- `MEMBER_ID_LENGTH`
-- `ECIES.MULTIPLE.RECIPIENT_ID_SIZE`  
-- `idProvider.byteLength`
-
-This prevents the 12 vs 32-byte misconfiguration that existed in v3.0.8.
+## Features
 
-**Invariant Validation System**
+### 🛡️ Core Cryptography (Protocol v4.0)
+
+- **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.
+
+### 🆔 Identity & Management
+
+- **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.
+
+### 🚀 Advanced Capabilities
+
+- **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 Node.js 18+ and modern browsers (Chrome, Edge, Firefox, Safari).
 
-Added comprehensive validation to catch configuration mismatches at initialization:
+## Installation
 
-```typescript
-// Automatic validation prevents mismatched configurations
-const config = createRuntimeConfiguration({
-  idProvider: new GuidV4Provider(), // 16 bytes
-  MEMBER_ID_LENGTH: 12, // ❌ Throws error - mismatch detected!
-});
+```bash
+npm install @digitaldefiance/ecies-lib
+# or
+yarn add @digitaldefiance/ecies-lib
 ```
 
-Invariants include:
-
-- `RecipientIdConsistency` - Ensures all ID size constants match
-- `Pbkdf2ProfilesValidity` - Validates PBKDF2 profile configuration
-- `EncryptionAlgorithmConsistency` - Validates encryption algorithm settings
-
-**Configuration Provenance Tracking**
-
-Track configuration lineage for debugging and compliance:
-
-```typescript
-import { ConstantsRegistry } from '@digitaldefiance/ecies-lib';
-
-const config = ConstantsRegistry.register('production', {
-  idProvider: new ObjectIdProvider(),
-}, {
-  description: 'Production configuration with ObjectID',
-});
+### Requirements
 
-// Later, retrieve provenance info
-const provenance = ConstantsRegistry.getProvenance('production');
-console.log(provenance.timestamp); // When created
-console.log(provenance.checksum); // Configuration hash
-```
+**Node.js**: 18+ (Web Crypto API built-in)
+**Browsers**: Modern browsers with Web Crypto API support.
 
----
+## Architecture & Protocol
 
-#### 🐛 Critical Bug Fixes
+### ECIES v4.0 Protocol Flow
 
-**Fixed 12 vs 32-Byte ID Discrepancy**
+The library implements a robust ECIES variant designed for security and efficiency.
 
-- **Issue:** `ECIES.MULTIPLE.RECIPIENT_ID_SIZE` defaulted to 12 bytes while `MULTI_RECIPIENT_CONSTANTS.RECIPIENT_ID_SIZE` used 32 bytes, causing silent encryption/decryption failures
-- **Root Cause:** Two separate constant definitions that were never validated against each other
-- **Fix:**
-  - All recipient ID sizes now derive from `idProvider.byteLength`
-  - Automatic validation prevents mismatches
-  - Integration tests added to catch regressions
-  - `getMultiRecipientConstants()` now dynamically calculates sizes
+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.
 
-**Fixed Frozen Constant Mutation**
+   ```typescript
+   SymmetricKey = HKDF(
+     secret: ECDH(EphemeralPriv, RecipientPub),
+     salt: empty,
+     info: "ecies-v2-key-derivation"
+   )
+   ```
 
-- **Issue:** Attempting to modify frozen `ENCRYPTION` constant with `Object.assign()` caused runtime errors
-- **Fix:** Removed `Object.assign()` mutations, constants are now properly immutable
+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.
 
-**Fixed PBKDF2 Profile Validation**
+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.
 
-- **Issue:** Invalid PBKDF2 profile configuration could pass validation
-- **Fix:** Added comprehensive PBKDF2 profile validation in invariant system
+### ID Provider System
 
-**Fixed Disposed Object Error Messages**
+The library is agnostic to the format of unique identifiers. The `IdProvider` system drives the entire configuration:
 
-- **Issue:** `DisposedError` had incorrect i18n string keys
-- **Fix:** Added proper error type enumeration and i18n translations
+- **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).
 
----
+When you configure an ID provider, the library automatically:
 
-#### 💥 Breaking Changes
+- Updates `MEMBER_ID_LENGTH`.
+- Updates `ECIES.MULTIPLE.RECIPIENT_ID_SIZE`.
+- Validates that all internal constants are consistent.
 
-**1. Direct Constant Assignments Removed**
+## Quick Start
 
-**Before (v3.0.8):**
+### 1. Basic Configuration & Usage
 
 ```typescript
-const config = createRuntimeConfiguration({
-  MEMBER_ID_LENGTH: 16,
-  ECIES: {
-    MULTIPLE: {
-      RECIPIENT_ID_SIZE: 16,
-    },
-  },
-});
-```
+import { 
+  ECIESService, 
+  getEciesI18nEngine, 
+  createRuntimeConfiguration, 
+  ObjectIdProvider 
+} from '@digitaldefiance/ecies-lib';
 
-**After (v3.7.x):**
+// 1. Initialize i18n (required once)
+getEciesI18nEngine();
 
-```typescript
+// 2. Configure (Optional - defaults to ObjectIdProvider)
 const config = createRuntimeConfiguration({
-  idProvider: new GuidV4Provider(), // Auto-syncs all size constants
+  idProvider: new ObjectIdProvider()
 });
-```
-
-**2. Recipient ID Generation Changes**
-
-**Before:**
-
-```typescript
-const recipientId = crypto.getRandomValues(new Uint8Array(32)); // Hardcoded
-```
-
-**After:**
-
-```typescript
-const recipientId = config.idProvider.generate(); // Dynamic sizing
-```
-
-**3. Multi-Recipient Constants Function Signature**
-
-**Before:**
 
-```typescript
-const constants = getMultiRecipientConstants(); // Used hardcoded 32
-```
-
-**After:**
-
-```typescript
-const constants = getMultiRecipientConstants(config.idProvider.byteLength); // Dynamic
-```
-
----
-
-#### 📚 New Documentation
-
-- **docs/MIGRATION_GUIDE_v3.7.md** - Complete migration guide from v3.6.x/v3.0.8 to v3.7.x
-- **docs/ID_PROVIDER_ARCHITECTURE.md** - Deep dive into the ID provider system (implied)
-- **docs/ENTERPRISE_ARCHITECTURE_ASSESSMENT.md** - Enterprise-grade architecture recommendations
-- **docs/ENTERPRISE_READINESS_CHECKLIST.md** - Production readiness assessment
-- **docs/EXECUTIVE_SUMMARY.md** - Executive overview of ID provider system
-- **docs/ID_PROVIDER_TESTING.md** - Comprehensive testing documentation
-- **docs/ID_SYSTEM_IMPLEMENTATION_STATUS.md** - Implementation status and roadmap
-- **docs/MIGRATION_CHECKLIST_NODE_LIB.md** - Node.js library migration checklist
-
----
-
-#### 🧪 Testing Improvements
-
-**New Test Suites**
-
-- `tests/lib/id-providers/id-providers.spec.ts` - Basic provider functionality (314 lines)
-- `tests/lib/id-providers/id-providers-comprehensive.spec.ts` - Comprehensive provider validation (913 lines)
-- `tests/lib/invariant-validator.spec.ts` - Invariant system validation (250 lines)
-- `tests/lib/configuration-provenance.spec.ts` - Provenance tracking tests (215 lines)
-- `tests/integration/recipient-id-consistency.spec.ts` - Cross-configuration ID consistency (319 lines)
-- `tests/integration/encrypted-message-structure.spec.ts` - Message structure validation (490 lines)
-- `tests/errors/ecies-error-context.spec.ts` - Enhanced error context testing (337 lines)
-
-**Test Statistics**
-
-- **Total Tests:** 1,200+ (up from ~1,100)
-- **Test Pass Rate:** 100% (1,200/1,200)
-- **Test Suites:** 61 suites
-- **New Test Files:** 7
-- **Test Execution Time:** ~77 seconds
-
-**Test Coverage**
-
-- All 4 ID providers have comprehensive test coverage
-- Cross-provider compatibility tests
-- Encrypted message structure validation with different ID sizes
-- Performance benchmarks (serialization/deserialization <50ms for 1000 operations)
-- Constant-time comparison validation (timing attack resistance)
-- Invariant validation edge cases
-
----
-
-#### ⚡ Performance
-
-**ID Provider Benchmarks**
-
-All providers meet performance requirements:
-
-- **ObjectIdProvider:** ~40ms per 1000 operations
-- **GuidV4Provider:** ~45ms per 1000 operations  
-- **UuidProvider:** ~45ms per 1000 operations
-- **CustomIdProvider:** ~40ms per 1000 operations
-
-**Performance Baselines**
-
-- Serialization: 1000 IDs in <50ms (relaxed from 20ms for CI stability)
-- Deserialization: 1000 IDs in <50ms (relaxed from 25ms for CI stability)
-- Constant-time comparison ratio: <15.0x (relaxed from 5.0x for CI variance)
-
----
-
-#### 🔒 Security Enhancements
-
-**Constant-Time Operations**
-
-- All ID providers use constant-time comparison to prevent timing attacks
-- Validation timing tests ensure consistent execution time regardless of input
-
-**Immutable Configuration**
-
-- All constants are deeply frozen to prevent accidental modification
-- Configuration provenance tracking provides audit trail
-
-**Validation at Initialization**
-
-- Invariant validation catches misconfigurations before runtime
-- Comprehensive error context for debugging
+// 3. Initialize Service
+const ecies = new ECIESService(config);
 
----
-
-#### 🌍 Internationalization
-
-**New Error Messages**
-
-Added i18n support for ID provider errors in 7 languages (en-US, fr, de, es, ja, uk, zh-cn):
-
-- `IdProviderInvalidByteLength` - Invalid byte length for ID provider
-- `IdProviderInvalidIdFormat` - Invalid ID format
-- `IdProviderIdValidationFailed` - ID validation failed
-- `IdProviderSerializationFailed` - Serialization failed
-- `IdProviderDeserializationFailed` - Deserialization failed
-- `IdProviderInvalidStringLength` - Invalid string length
-- `IdProviderInputMustBeUint8Array` - Input must be Uint8Array
-- `IdProviderInputMustBeString` - Input must be string
-- `IdProviderInvalidCharacters` - Invalid characters in input
-
-**Updated Error Messages**
-
-- Enhanced `DisposedError` with proper type enumeration
-- Added context parameters to ECIES error messages
-- Improved error message clarity across all services
-
----
-
-#### 📦 New Exports
-
-**ID Providers**
-
-```typescript
-export { ObjectIdProvider } from './lib/id-providers/objectid-provider';
-export { GuidV4Provider } from './lib/id-providers/guidv4-provider';
-export { UuidProvider } from './lib/id-providers/uuid-provider';
-export { CustomIdProvider } from './lib/id-providers/custom-provider';
-```
+// 4. Generate Keys
+const mnemonic = ecies.generateNewMnemonic();
+const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(mnemonic);
 
-**Interfaces**
+// 5. Encrypt & Decrypt
+const message = new TextEncoder().encode('Hello, Secure World!');
+const encrypted = await ecies.encryptSimpleOrSingle(false, publicKey, message);
+const decrypted = await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, encrypted);
 
-```typescript
-export type { IIdProvider } from './interfaces/id-provider';
-export { BaseIdProvider } from './interfaces/id-provider';
-export type { IInvariant } from './interfaces/invariant';
-export { BaseInvariant } from './interfaces/invariant';
-export type { IConfigurationProvenance } from './interfaces/configuration-provenance';
+console.log(new TextDecoder().decode(decrypted)); // "Hello, Secure World!"
 ```
 
-**Validation**
+### 2. Using Custom ID Providers (e.g., GUID)
 
 ```typescript
-export { InvariantValidator } from './lib/invariant-validator';
-export { RecipientIdConsistencyInvariant } from './lib/invariants/recipient-id-consistency';
-export { Pbkdf2ProfilesValidityInvariant } from './lib/invariants/pbkdf2-profiles-validity';
-export { EncryptionAlgorithmConsistencyInvariant } from './lib/invariants/encryption-algorithm-consistency';
-```
+import { 
+  createRuntimeConfiguration, 
+  GuidV4Provider, 
+  ECIESService 
+} from '@digitaldefiance/ecies-lib';
 
-**Errors**
+// Configure to use 16-byte GUIDs
+const config = createRuntimeConfiguration({
+  idProvider: new GuidV4Provider()
+});
 
-```typescript
-export { IdProviderError } from './errors/id-provider';
-export { IdProviderErrorType } from './enumerations/id-provider-error-type';
-export { DisposedErrorType } from './enumerations/disposed-error-type';
+const ecies = new ECIESService(config);
+const id = config.idProvider.generate(); // Returns 16-byte Uint8Array
 ```
 
----
-
-#### 🔧 Code Structure Changes
-
-**New Files Added (7,611 insertions)**
-
-Core Implementation:
-
-- `src/lib/id-providers/objectid-provider.ts` (97 lines)
-- `src/lib/id-providers/guidv4-provider.ts` (122 lines)
-- `src/lib/id-providers/uuid-provider.ts` (117 lines)
-- `src/lib/id-providers/custom-provider.ts` (165 lines)
-- `src/lib/id-providers/index.ts` (31 lines)
-
-Validation System:
-
-- `src/lib/invariant-validator.ts` (133 lines)
-- `src/lib/invariants/recipient-id-consistency.ts` (46 lines)
-- `src/lib/invariants/pbkdf2-profiles-validity.ts` (78 lines)
-- `src/lib/invariants/encryption-algorithm-consistency.ts` (73 lines)
-
-Interfaces:
-
-- `src/interfaces/id-provider.ts` (117 lines)
-- `src/interfaces/invariant.ts` (60 lines)
-- `src/interfaces/configuration-provenance.ts` (72 lines)
-
-Errors:
-
-- `src/errors/id-provider.ts` (40 lines)
-- `src/enumerations/id-provider-error-type.ts` (50 lines)
-- `src/enumerations/disposed-error-type.ts` (11 lines)
+### 3. Streaming Encryption (Large Files)
 
-**Major File Modifications**
-
-- `src/constants.ts` (+115 lines) - Added ID provider integration and auto-sync
-- `src/interfaces/constants.ts` (+27 lines) - Extended with ID provider field
-- `src/interfaces/multi-recipient-chunk.ts` (+69 lines) - Dynamic size calculation
-- `src/services/multi-recipient-processor.ts` (+72 lines) - ID provider integration
-- `src/services/encryption-stream.ts` (+18 lines) - Dynamic size support
-- `src/secure-buffer.ts` (+28 lines) - Enhanced disposal handling
-- `src/errors/ecies.ts` (+107 lines) - New error types with context
-
-**Translation Updates**
-
-Updated all 7 language files with new error messages:
-
-- `src/translations/en-US.ts` (+22 lines)
-- `src/translations/fr.ts` (+26 lines)
-- `src/translations/de.ts` (+22 lines)
-- `src/translations/es.ts` (+28 lines)
-- `src/translations/ja.ts` (+21 lines)
-- `src/translations/uk.ts` (+24 lines)
-- `src/translations/zh-cn.ts` (+27 lines)
-
----
-
-#### 🔄 Migration Guide
-
-**For Default Users (No Changes Needed)**
-
-If you're using the default ObjectID provider (12 bytes), **no code changes are required**:
+Encrypt gigabytes of data with minimal memory footprint (<10MB).
 
 ```typescript
-// v3.0.8 - Still works in v3.7.x!
-import { ECIESService } from '@digitaldefiance/ecies-lib';
+import { ECIESService, EncryptionStream } from '@digitaldefiance/ecies-lib';
 
 const ecies = new ECIESService();
-const encrypted = await ecies.encrypt(data, publicKey);
-```
-
-**For Custom ID Size Users**
-
-If you were customizing ID sizes in v3.0.8:
-
-```typescript
-// v3.0.8 (OLD - BREAKS in v3.7.x)
-const config = createRuntimeConfiguration({
-  MEMBER_ID_LENGTH: 16,
-});
-
-// v3.7.x (NEW)
-import { GuidV4Provider } from '@digitaldefiance/ecies-lib';
-
-const config = createRuntimeConfiguration({
-  idProvider: new GuidV4Provider(),
-});
-```
-
-**Creating Custom ID Providers**
-
-```typescript
-import { BaseIdProvider } from '@digitaldefiance/ecies-lib';
+const stream = new EncryptionStream(ecies);
 
-class MyCustomProvider extends BaseIdProvider {
-  constructor() {
-    super('MyCustom', 24, 'My 24-byte custom IDs');
-  }
-  
-  generate(): Uint8Array {
-    return crypto.getRandomValues(new Uint8Array(24));
-  }
+// Assuming 'fileStream' is a ReadableStream from a File object
+async function processFile(fileStream: ReadableStream, publicKey: Uint8Array) {
+  const encryptedChunks: Uint8Array[] = [];
   
-  validate(id: Uint8Array): boolean {
-    return id.length === 24;
+  // 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
   }
   
-  serialize(id: Uint8Array): string {
-    return Array.from(id).map(b => b.toString(16).padStart(2, '0')).join('');
-  }
-  
-  deserialize(str: string): Uint8Array {
-    const bytes = new Uint8Array(24);
-    for (let i = 0; i < 24; i++) {
-      bytes[i] = parseInt(str.substr(i * 2, 2), 16);
-    }
-    return bytes;
-  }
+  return encryptedChunks;
 }
 ```
 
----
-
-#### 📊 Version Details
-
-**v3.7.3**
-
-- Removed Legacy32ByteProvider from all code and documentation
-- Fixed test failures from Legacy32ByteProvider removal
-- Updated migration guides to only show supported providers
-- Relaxed timing test thresholds for CI stability (15.0x ratio, 50ms thresholds)
-
-**v3.7.2**
-
-- Initial release of ID provider system
-- Added comprehensive documentation
-- Full test suite with 1,200+ tests
-
----
-
-#### 🙏 Contributors
-
-- Jessica Mulein (@JessicaMulein) - Lead developer
-- GitHub Copilot - Architecture review and code assistance
-
----
-
-#### 📝 Release Statistics
-
-- **Lines of code changed:** ~7,600 additions, ~135 deletions
-- **Files modified:** 61
-- **New test files:** 7
-- **New source files:** 14
-- **Documentation added:** ~3,800 lines
-- **Tests added:** 100+
-- **Test pass rate:** 100% (1,200/1,200)
-
----
-
-### v3.0.8
-
-- Update i18n
-
-### v3.0.7
-
-- Update i18n
-
-### v3.0.6
-
-- Update i18n
-
-### v3.0.5
-
-- Update i18n
-
-### v3.0.4
-
-- Fix EmailString usage of InvalidEmailError
-
-### v3.0.3
-
-- Slight tweak to InvalidEmailError
-
-### v3.0.2
-
-- Update test-utils
-
-### v3.0.1
-
-- Fix strings mainly
-- add service.encryptMultiple endpoint, clarify service.encrypt endpoint
-
-### v3.0.0 - Streaming Encryption & Security Hardening
+### 4. Member System
 
-**Major Features**:
+The `Member` class provides a high-level user abstraction that integrates keys, IDs, and encryption.
 
-- ✨ **Streaming Encryption**: Memory-efficient encryption for large files (<10MB RAM for any size)
-- 🔐 **Multi-Recipient Streaming**: Encrypt once for up to 65,535 recipients with shared symmetric key
-- 📊 **Progress Tracking**: Real-time throughput, ETA, and completion percentage
-- 🔒 **Security Hardening**: 16 comprehensive security validations across all layers
-- ✅ **AsyncGenerator API**: Flexible streaming with cancellation support
-- 🎯 **100% Test Coverage**: 646/646 tests passing, 52/52 suites
-
-**New APIs**:
-
-**Single-Recipient Streaming**:
-
-- `EncryptionStream.encryptStream()` - Stream encryption with configurable chunks
-- `EncryptionStream.decryptStream()` - Stream decryption with validation
-- `Member.encryptDataStream()` - Member-level streaming encryption
-- `Member.decryptDataStream()` - Member-level streaming decryption
-
-**Multi-Recipient Streaming**:
-
-- `EncryptionStream.encryptStreamMultiple()` - Encrypt for multiple recipients
-- `EncryptionStream.decryptStreamMultiple()` - Decrypt as specific recipient
-- `MultiRecipientProcessor.encryptChunk()` - Low-level multi-recipient encryption
-- `MultiRecipientProcessor.decryptChunk()` - Low-level multi-recipient decryption
-
-**Progress Tracking**:
-
-- `ProgressTracker.update()` - Track bytes processed, throughput, ETA
-- `IStreamProgress` interface with `throughputBytesPerSec` property
-- Optional progress callbacks in all streaming operations
-
-**Security Enhancements (16 validations)**:
-
-**Base ECIES Layer (8 fixes)**:
-
-- Public key all-zeros validation
-- Private key all-zeros validation
-- Shared secret all-zeros validation
-- Message size validation (max 2GB)
-- Encrypted size bounds checking
-- Minimum encrypted data size validation
-- Component extraction validation
-- 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
-- Data size validation (max 2GB)
-- 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
-
-**Performance**:
-
-- 99% memory reduction (1GB file: 1GB RAM → <10MB RAM)
-- < 0.1% overhead from security validations
-- Independent chunk encryption (resumability ready)
-- Chunk sequence validation (prevents reordering attacks)
-- Optional SHA-256 checksums (in addition to AES-GCM auth)
-- Single symmetric key per stream (not per chunk)
-
-**Multi-Recipient Features**:
-
-- Maximum 65,535 recipients supported
-- 32-byte recipient IDs required
-- Shared symmetric key encrypted per recipient
-- Efficient header format with recipient metadata
-- Buffer overflow protection (100MB max per source chunk)
-
-**New Error Types**:
-
-- `InvalidAESKeyLength` - AES key must be 16/24/32 bytes
-- `CannotEncryptEmptyData` - Empty/null data rejected
-- `CannotDecryptEmptyData` - Empty/null encrypted data rejected
-- `EncryptedSizeExceedsExpected` - Encrypted output too large
-- `InvalidChunkIndex` - Chunk index out of uint32 range
-- `HeaderSizeOverflow` - Recipient header size overflow
-
-**Documentation**:
-
-- Added `docs/STREAMING_ENCRYPTION_ARCHITECTURE.md`
-- Added `docs/STREAMING_API_QUICKSTART.md`
-- Added `docs/PHASE_1_COMPLETE.md`
-- Added `ECIES_STREAMING_CHANGES_SUMMARY.md` (for node-ecies porting)
-- Updated README with streaming and multi-recipient examples
-
-**Test Coverage**:
-
-- 646 tests passing (100%)
-- 52 test suites passing (100%)
-- 5 multi-recipient streaming tests
-- 87+ streaming tests (unit + integration + e2e)
-- All 16 security validations covered
-- Error coverage validation updated
-
-### v2.1.42
-
-- Fix Hmac constant
-
-### v2.1.40
-
-- Alignment with Express Suite packages
-- All packages updated to v2.1.40 (i18n, ecies-lib, node-ecies-lib, suite-core-lib, node-express-suite, express-suite-react-components)
-- Test utilities remain at v1.0.7
-- `/testing` entry point exports test mocks (mockFrontendMember)
-- Requires `@faker-js/faker` as dev dependency for test utilities
-
-## v2.1.39 - Update test-utils dep
-
-## v2.1.38 - Export test mock for frontend member
-
-## v2.1.32 - Config on i18n create
-
-## v2.1.30 - Alignment bump
-
-## v2.1.26 - use new express-suite-test-utils
-
-## v2.1.25 - Upgrade i18n, mostly testing improvements
+```typescript
+import { Member, MemberType, EmailString } from '@digitaldefiance/ecies-lib';
 
-## v2.1.17 - Add frontend member mock
+// 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')
+);
 
-## v2.1.16 - upgrade i18n
+console.log(member.id); // Uint8Array (size depends on provider)
 
-## v2.1.15 - upgrade i18n
+// Encrypt data for this member
+const encrypted = await member.encryptData('My Secrets');
+```
 
-## v2.1.12 - upgrade i18n
+## API Reference
 
-### v2.1.10 - Convergence bump
+### Core Services
 
-### v2.1.7 - minor version bump to fix core component aliases
+- **`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.
+- **`EciesFileService`**: Helper for chunked file encryption.
+- **`PasswordLoginService`**: Secure authentication using PBKDF2 and encrypted key bundles.
 
-### v2.1.6 - minor version bump from i18n lib
+### Configuration & Registry
 
-### v2.1.5 - minor version bump from i18n lib
+- **`Constants`**: The default, immutable configuration object.
+- **`ConstantsRegistry`**: Manages runtime configurations.
+  - `register(key, config)`: Register a named configuration.
+  - `get(key)`: Retrieve a configuration.
+- **`createRuntimeConfiguration(overrides)`**: Creates a validated configuration object with your overrides.
 
-### v2.1.4 - minor version bump from i18n lib
+### Secure Primitives
 
-### v2.1.3 - drop GUID altogether for ObjectID via BSON for better compatibility with node-ecies
+- **`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.
 
-### v2.1.2 - add faux GUID support for MongoDB ObjectIds
+## Development
 
-### v2.1.1 - upgrade to match i18n, upgrade error classes, deprecate Plu1inI8nEngine
+### Commands
 
-### v2.0.3 - version bump/update i18n
+```bash
+yarn install         # Install dependencies
+yarn build          # Compile TypeScript
+yarn test           # Run all tests (1200+ specs)
+yarn lint           # ESLint check
+yarn format         # Fix all (prettier + lint)
+```
 
-### v2.0.2 - version bump/update i18n
+### Testing
 
-### v2.0.1 - Minor bump to remove generics on some error classes
+The library maintains **100% test coverage** with over 1,200 tests, including:
 
-### v2.0.0 - i18n Architecture Modernization
+- **Unit Tests**: For all services and utilities.
+- **Integration Tests**: Verifying protocol flows and message structures.
+- **Vectors**: Validating against known test vectors.
+- **Property-based Tests**: Fuzzing inputs for robustness.
 
-**Release Date**: January 2025
+## ChangeLog
 
-**Major Changes**:
+### v4.1.1
 
-- 🎉 **i18n v2.0**: Automatic error translation with singleton pattern
-- ✨ **Simplified APIs**: Removed engine parameters from all service constructors
-- 🔧 **Breaking**: `Pbkdf2Service`, `PasswordLoginService` constructors changed
-- 📚 **Documentation**: Added comprehensive migration guides
-- ✅ **Testing**: 393/393 tests passing (100%)
+- Tweak to objectId provider to make generate() more robust
 
-**Migration Required**: See [Migration Guide](./docs/I18N_V2_MIGRATION_GUIDE.md)
+### v4.1.0
 
-**Services Updated**:
+- **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 `Uint8Array`).
 
-- `Pbkdf2Service(profiles?, eciesParams?, pbkdf2Params?)` - removed engine parameter
-- `PasswordLoginService(ecies, pbkdf2, eciesParams?)` - removed engine parameter
+### v4.0.0 - ECIES Protocol v4.0
 
-**New Features**:
+#### Major Protocol Upgrade (Breaking Change)
 
-- Automatic i18n engine retrieval via singleton
-- Unified index exports (v1 + v2 architecture)
-- Enhanced error messages in 8 languages
+- **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).
 
-**Bug Fixes**:
+### v3.7.0 - Pluggable ID Provider System
 
-- Fixed PBKDF2 profile lookup issues
-- Resolved test initialization timing problems
-- Corrected constructor parameter ordering
+- **Flexible IDs**: Introduced `IdProvider` architecture.
+- **Auto-Sync**: Configuration automatically adapts to ID size.
+- **Invariant Validation**: Runtime checks for configuration consistency.
 
-**Documentation**:
+### v3.0.0 - Streaming Encryption
 
-- Added `docs/I18N_V2_MIGRATION_GUIDE.md`
-- Added `docs/LESSONS_LEARNED.md`
-- Added `docs/NODE_ECIES_MIGRATION_GUIDE.md`
-- Updated README with v2.0 examples
+- **Memory Efficiency**: Streaming support for large datasets.
+- **Progress Tracking**: Real-time throughput and ETA monitoring.
 
-**Performance**:
+### v2.0.0 - i18n Architecture
 
-- No degradation: 44s test suite (vs 45s in v1.x)
-- Reduced code complexity by 40%
-- Eliminated parameter threading overhead
+- **Singleton i18n**: Simplified service instantiation.
+- **Translation**: Error messages in 8 languages.
 
 ### v1.3.27 and Earlier
 
@@ -1687,3 +510,14 @@ class MyCustomProvider extends BaseIdProvider {
 - Fri Sep 26 2025 10:21:00 GMT-0700 (Pacific Daylight Time)
 
   - Initial release of the ECIES library with multi-recipient support, AES-GCM helpers, PBKDF2 profiles, and password-login tooling
+
+## License
+
+MIT © Digital Defiance
+
+## Links
+
+- **Repository:** <https://github.com/Digital-Defiance/ecies-lib>
+- **npm:** <https://www.npmjs.com/package/@digitaldefiance/ecies-lib>
+- **Companion:** @digitaldefiance/node-ecies-lib (binary compatible)
+