mirage-encryption
An npm package that simplifies MongoDB Client-Side Field Level Encryption (CSFLE) for Node.js applications.
Overview
A published npm utility package that abstracts the complexity of MongoDB Client-Side Field Level Encryption. Supports multiple KMS providers (Local, AWS, Azure, GCP), automated Data Encryption Key management, and schema-based field-level encryption configuration — all with a clean, intuitive API.
Problem
MongoDB CSFLE is powerful but involves significant boilerplate: managing key vaults, DEK provisioning, schema generation, and crypt_shared library configuration. Each project has to re-implement this infrastructure.
Approach
Encapsulated the entire CSFLE setup behind a `ServerEncryptionService` class. Developers provide a KMS config and a schema file; the package handles DEK management, schema generation, and returns a standard MongoDB client with encryption transparent to business logic.
Technical Decisions
Peer dependencies (`mongodb`, `mongodb-client-encryption`) kept separate to allow consumers to control MongoDB driver versions. Comprehensive error types (ConfigurationError, ValidationError, EncryptionError, KMSError) make debugging straightforward.
Challenges
Cross-platform support for the crypt_shared library (.dll / .dylib / .so). Designing the schema DSL to be simple enough for quick setup while still supporting complex nested field encryption.