# ecies/js architecture

> Architecture diagram of the GitHub repository ecies/js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ecies/js
- Repository: https://github.com/ecies/js

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Subgraph
    subgraph "Core Library"
        API["API: encrypt/decrypt (src/index.ts)"]:::core
        Config["Configuration (src/config.ts)"]:::core
        Consts["Constants (src/consts.ts)"]:::core
    end

    %% Key Management Subgraph
    subgraph "Key Management"
        PrivateKey["PrivateKey (src/keys/PrivateKey.ts)"]:::keys
        PublicKey["PublicKey (src/keys/PublicKey.ts)"]:::keys
    end

    %% Utility Functions Subgraph
    subgraph "Utility Functions"
        Elliptic["Elliptic (src/utils/elliptic.ts)"]:::utils
        Hash["Hash (src/utils/hash.ts)"]:::utils
        Hex["Hex (src/utils/hex.ts)"]:::utils
        Symmetric["Symmetric (src/utils/symmetric.ts)"]:::utils
    end

    %% External Dependencies
    External["External Dependencies (noble-curves, noble-hashes, noble-ciphers, node:crypto)"]:::external

    %% Examples Subgraph
    subgraph "Examples"
        BrowserEx["Browser Example (example/browser)"]:::example
        RuntimeEx["Runtime Example (example/runtime)"]:::example
    end

    %% Testing Modules Subgraph
    subgraph "Testing Modules"
        BrowserTest["Browser Tests (tests-browser)"]:::testing
        NodeTest["Node/Runtime Tests (tests)"]:::testing
    end

    %% Connections

    %% Configuration influences API, Key Management and Utility Functions
    Config -->|"configures"| API
    Config -->|"configures"| PrivateKey
    Config -->|"configures"| PublicKey

    %% API calls Key Management and Utility Functions for encryption/decryption
    API -->|"uses-key-management"| PrivateKey
    API -->|"uses-key-management"| PublicKey
    API -->|"calls-utils"| Elliptic
    API -->|"calls-utils"| Hash
    API -->|"calls-utils"| Hex
    API -->|"calls-utils"| Symmetric

    %% Key Management and Utility Functions interact with External Dependencies
    PrivateKey -->|"utilizes"| External
    PublicKey  -->|"utilizes"| External
    Elliptic   -->|"utilizes"| External
    Hash       -->|"utilizes"| External
    Hex        -->|"utilizes"| External
    Symmetric  -->|"utilizes"| External

    %% Examples demonstrating usage of API
    BrowserEx -->|"demonstrates"| API
    RuntimeEx -->|"demonstrates"| API

    %% Testing modules validate API functionality
    BrowserTest -->|"tests"| API
    NodeTest -->|"tests"| API

    %% Click Events
    click API "https://github.com/ecies/js/blob/master/src/index.ts"
    click Config "https://github.com/ecies/js/blob/master/src/config.ts"
    click Consts "https://github.com/ecies/js/blob/master/src/consts.ts"
    click PrivateKey "https://github.com/ecies/js/blob/master/src/keys/PrivateKey.ts"
    click PublicKey "https://github.com/ecies/js/blob/master/src/keys/PublicKey.ts"
    click Elliptic "https://github.com/ecies/js/blob/master/src/utils/elliptic.ts"
    click Hash "https://github.com/ecies/js/blob/master/src/utils/hash.ts"
    click Hex "https://github.com/ecies/js/blob/master/src/utils/hex.ts"
    click Symmetric "https://github.com/ecies/js/blob/master/src/utils/symmetric.ts"
    click BrowserEx "https://github.com/ecies/js/tree/master/example/browser"
    click RuntimeEx "https://github.com/ecies/js/tree/master/example/runtime"
    click BrowserTest "https://github.com/ecies/js/tree/master/tests-browser"
    click NodeTest "https://github.com/ecies/js/tree/master/tests"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef keys fill:#bbf,stroke:#333,stroke-width:2px;
    classDef utils fill:#afa,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef example fill:#dfd,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffd,stroke:#333,stroke-width:2px;
```
