How juspay/hyperswitch-card-vault works
Project Type & Overview
• This project is a backend, Rust-based secure vault service. Its primary role is to offer encrypted storage services through RESTful APIs. Clients communicate with the system via a middleware using encrypted and signed requests (JWS/JWE algorithms).
• The README highlights key flows such as authentication, encryption signing, and key hierarchy (master key and custodian keys) which are essential parts of the system.
Analysis of the File Structure
• Top-Level Directories:
• “src”: Contains the core application logic. It’s organized into several submodules including API endpoints (routes folders for data, cards, tenant, etc.), cryptography (encryption, hash, key manager, secrets manager), storage, error handling, logging, and configuration.
• “config” and “config.example.toml”: Provide runtime and environment-specific configurations.
• “migrations”: Contains Diesel migrations for defining and evolving the underlying database schema.
• “benches” and “loadtest”: Contain performance and load testing scenarios, ensuring that the secure vault can handle high loads and verify cryptographic operations.
• “.github”: Holds CI/CD configurations (workflows for building, testing, releasing, and docker image creation), emphasizing automated deployment and integration.
• This structured organization reflects a modular design where each module (API, cryptography, storage, error handling, logging) serves a dedicated function in the overall architecture.
Key Components
a. Client / Middleware:
b. API Gateway / Endpoint Layer:
• Routes (e.g., /data, /cards, /tenant) that handle incoming REST API requests.
• Security middleware components as the first point of contact for verifying request authenticity.
c. Cryptography Module:
• Separate subcomponents:
• Encryption Manager: Implements JWE/JWS algorithms for request signing/encryption.
• Hash Manager: Handles internal hashing checks to prevent data duplication.
• Key Manager and Secrets Manager: Manage master key and custodian key operations as well as interactions with external systems (e.g., AWS KMS, HC Vault, etc.).
d. Storage & Database Layer:
• Database layer (utilizing Diesel, migrations, and table schemas) for persisting encrypted sensitive data.
• A caching subcomponent if relevant from the “storage/caching” modules.
e. Logging and Error Handling:
• Dedicated logging components (with configuration, formatting, and storage modules) and error management modules that ensure system-wide visibility.
f. External Services & Infrastructure:
• Load testing and monitoring components (from the "loadtest" folder) that integrate with Grafana or other monitoring tools.
Relationships & Data Flow
• From external clients/middleware to the API layer.
• API requests are authenticated and then processed through the cryptography modules.
• After processing, data is persisted into the secure database (managed via Diesel and migrations).
• Feedback loops for error reporting, logging, and monitoring.
• That encryption and key management precede data storage — capture the order of operations like how a master key is managed by custodian keys.
• Distinguish internal vs. external communications; for example, note that external communications use encrypted channels and require signature verification.