How ecies/js works
Based on our analysis of the file tree and the README, this project is an implementation of the Elliptic Curve Integrated Encryption Scheme (ECIES) in JavaScript/TypeScript – a cryptography library that provides encryption and decryption using elliptic curves (specifically secp256k1 and curve25519 variants). It is designed to be multi-platform (supporting Node, Browser, Bun, Deno, and React Native) and emphasizes security by relying on audited libraries (noble-curves, noble-hashes, and noble-ciphers) as well as native crypto implementations where available.
Main Components
• Core Library (src): This is where the encryption/decryption logic, key management, configuration, and utility functions reside.
• src/index.ts: Acts as the main entry point.
• src/config.ts: Contains the configuration settings (e.g., elliptic curve type, cipher algorithm, compression options).
• src/consts.ts: Holds constant values used across the library.
• Key Management (src/keys): Implements key-related functionalities including:
• PrivateKey: Generation, conversion (fromHex, toHex), encapsulation/multiplication.
• PublicKey: Conversion between formats (compressed/uncompressed) and decapsulation.
• Utilities (src/utils): Contains helper functions for cryptographic operations such as elliptic curve functions, hash functions, hex conversions, and symmetric encryption.
• API Methods: The core API consists of the encrypt and decrypt functions that are exposed for end-users. These functions internally make use of PrivateKey and PublicKey operations.
• Examples: Provides usage samples in:
• example/browser: Example for the browser platform showing integration with HTML/CSS/JS.
• example/runtime: Example for a Node/Bun/Deno runtime, demonstrating command line or runtime execution.
• Testing: Contains both browser tests (tests-browser) and node-based tests (tests) that ensure functionality across cryptographic operations and API endpoints.
Relationships and Interactions
• Data Flow:
• During encryption: The public key is used to generate and encapsulate ephemeral keys, followed by symmetric encryption (using AES-256-GCM or XChaCha20-Poly1305 based on the configuration).
• During decryption: The corresponding private key is used to retrieve the shared secret, and then the data is decrypted using symmetric decryption.
• The configuration object (from src/config.ts) influences how the keys and encryption are handled (i.e., whether the ephemeral key is compressed, how the shared key is derived, and the symmetric algorithm employed).
• Utility functions (in src/utils) support the above cryptographic operations, ensuring data is processed (e.g., hashed or properly formatted as hex) as required.
• Integration tests verify the interactions among these units.
Architectural Patterns & Design Principles
• Modularity: The project is neatly separated into distinct modules (keys, utils, config) that encapsulate specific functionalities.
• Multi-platform Adaptation: The examples and designated configurations for browser and runtime environments reflect careful design for cross-platform support.
• Security-First: The project’s architecture enforces security best practices by isolating cryptographic primitives to well-audited libraries and by providing clear configuration options that help maintain consistency across different usages.
Relevant Technologies, Frameworks, and Dependencies
• TypeScript is utilized for type safety and clarity.
• Node:crypto (when available) is used for AES-256-GCM and XChaCha20-Poly1305 implementations.
• External libraries: noble-curves, noble-hashes, and noble-ciphers are central to cryptographic functions.
• The testing toolchain (Vitest, among others) to ensure robust unit and integration tests across environments.