# mastercard/client-encryption-nodejs architecture

> Architecture diagram of the GitHub repository mastercard/client-encryption-nodejs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mastercard/client-encryption-nodejs
- Repository: https://github.com/mastercard/client-encryption-nodejs

## Overview

##### Project Type and Purpose
- Project Type: It is a Node.js library designed to provide payload encryption and decryption functionality. This library supports two modes: field-level encryption and JWE (JSON Web Encryption).
- Purpose: It allows integration with Mastercard API endpoints by seamlessly encrypting requests and decrypting responses. There is also built-in support for integration with OpenAPI generated client libraries through a “Service” decorator for automatic handling of encryption tasks.

##### File Structure
- Top-Level Files and Directories:
- Files like index.js, package.json, and webpack.config.js indicate it’s a Node project.
- The lib directory contains the core encryption logic. In particular, the “lib/mcapi” folder holds modules divided into subdirectories (e.g., crypto and encryption) that implement both field-level and JWE methods.
- The “test” directory holds numerous test cases for the different encryption functions (field level and JWE) along with mocks and resources (keys, certificates). This reaffirms a modular design with well-defined responsibilities.
- The presence of configuration files (e.g., .eslintrc, .editorconfig, sonar-project.properties, GitHub workflows) suggest a modern development workflow with automated builds, continuous integration, and code quality checks.

##### README for Additional Insights
- The README clearly outlines the usage, configuration, and examples for both encryption methods.
- It provides detailed examples on how to configure encryption (including paths, keys, and JWT configurations), and it explains the integration with OpenAPI client libraries, emphasizing the “Service” decorator.

##### Core Components
a. Main Components:
- Encryption Modules:
- FieldLevelEncryption (and its underlying crypto utilities found in crypto folders)
- JweEncryption (with associated methods and JWE-specific config handling)
- Configuration Object:
- Used to specify encryption paths, file paths for certificates, and keys.
- mcapi-Service:
- Decorator for integrating with OpenAPI-generated API clients, enabling transparent payload encryption/decryption.
- Utility Modules:
- Under “lib/mcapi/utils” (constants and helper functions) serving support for encryption operations.
- Test and Resource Modules:
- How the encryption functions are validated (these can be a separate “Testing Environment” block).

b. Relationships and Interactions:
- A client application imports the encryption library (or the “Service” decorator for OpenAPI clients).
- The client passes a configuration object which informs the encryption modules how to handle data (paths to encrypt/decrypt, and key locations).
- The FieldLevelEncryption and JweEncryption classes process JSON payloads:
- Incoming API requests: encrypt the payload based on provided configuration.
- Outgoing API responses: perform decryption after retrieving encrypted data.
- Underneath, the crypto layers (e.g., jwe-crypto.js, field-level-crypto.js) provide the low-level encryption algorithms required for the encryption modules.

c. Architectural Patterns and Design Principles:
- Modularity: Each encryption strategy (field-level and JWE) is encapsulated in its own module with shared configuration.
- Separation of Concerns: Clear distribution between higher-level service orchestration (via the ‘Service’ decorator) and low-level encryption tasks.
- Extensibility: The config-driven approach allows integration with various API clients and changes in encryption parameters without modifying core logic.

d. Relevant Technologies:
- Node.js as the runtime platform.
- NPM for dependency management (as indicated by package.json).
- Testing frameworks and configuration tools hosted in “test” and GitHub workflows.
- Integration with external certificates/keys (public encryption certificates and private decryption keys).
- OpenAPI generator for API client integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["API Consumer / Client"]:::client
    B["Configuration Object"]:::config
    C["mcapi-Service (Decorator)"]:::service
    
    A -->|"sendsRequest"| B
    B -->|"suppliesConfig"| C
    
    subgraph "Field Level Encryption Flow"
        D["FieldLevelEncryption Module"]:::encryption
        E["Field-Level Crypto Utility"]:::crypto
        D -->|"callsCrypto"| E
        E -->|"returnsData"| D
    end

    subgraph "JWE Encryption Flow"
        F["JweEncryption Module"]:::encryption
        G["JWE Crypto Utility"]:::crypto
        F -->|"callsCrypto"| G
        G -->|"returnsData"| F
    end

    C -->|"invokes"| D
    C -->|"invokes"| F
    D -->|"returnsPayload"| A
    F -->|"returnsPayload"| A

    H["Utility Modules"]:::utils
    H -.->|"supports"| D
    H -.->|"supports"| F

    I["Testing Environment"]:::test
    I -->|"validatesEncryption"| D
    I -->|"validatesEncryption"| F

    click B "https://github.com/mastercard/client-encryption-nodejs/blob/main/test/mock/config.js"
    click C "https://github.com/mastercard/client-encryption-nodejs/blob/main/lib/mcapi/mcapi-service.js"
    click D "https://github.com/mastercard/client-encryption-nodejs/blob/main/lib/mcapi/encryption/field-level-encryption.js"
    click E "https://github.com/mastercard/client-encryption-nodejs/blob/main/lib/mcapi/crypto/field-level-crypto.js"
    click F "https://github.com/mastercard/client-encryption-nodejs/blob/main/lib/mcapi/encryption/jwe-encryption.js"
    click G "https://github.com/mastercard/client-encryption-nodejs/blob/main/lib/mcapi/crypto/jwe-crypto.js"
    click H "https://github.com/mastercard/client-encryption-nodejs/tree/main/lib/mcapi/utils"
    click I "https://github.com/mastercard/client-encryption-nodejs/tree/main/test"

    classDef client fill:#fceabb,stroke:#d68f2c,stroke-width:2px;
    classDef config fill:#d0f0c0,stroke:#82b74b,stroke-width:2px;
    classDef service fill:#ffe699,stroke:#ffcc00,stroke-width:2px;
    classDef encryption fill:#cfe2f3,stroke:#6baed6,stroke-width:2px;
    classDef crypto fill:#f9c0c0,stroke:#e27272,stroke-width:2px;
    classDef utils fill:#e7e7e7,stroke:#aaa,stroke-width:2px;
    classDef test fill:#d9e6f2,stroke:#5082b4,stroke-width:2px;
```
