How mastercard/client-encryption-nodejs works
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.