From the Releases page, download the installer for your platform at https://github.com/engrsadaqath/e2ee-adapter/releases and run it.

E2EE Adapter: Plug-and-Play Hybrid Encryption Middleware for Express & NestJS

A plug-and-play TypeScript package providing End-to-End Encryption (E2EE) middleware for Express.js and NestJS applications using hybrid encryption (AES-CBC + RSA).

• Topic focus: aes-cbc, cryptography, e2ee, encryption, end-to-end-encryption, express, hybrid-encryption, key-exchange, middleware, nestjs, no-code-e2ee, plug-and-play, rsa, secure-communication, security, typescript, zero-config
• Official releases: https://github.com/engrsadaqath/e2ee-adapter/releases

Table of contents

• Quick start
• Why this project
• How it works
• Supported environments
• Installation
• Usage guide
• Express integration
• NestJS integration
• API reference
• Security guidance
• Configuration and environment
• Testing and quality
• Roadmap
• Contributing
• License
• Changelog
• FAQ

Quick start

• This library aims to be zero-config out of the box. Install, wire up a middleware, and start securing traffic with a hybrid encryption layer between clients and servers.
• The core idea is simple: encrypt payloads with AES-CBC, and protect the AES key with RSA. The result is end-to-end secure data, with the server acting as a processing point for encrypted messages without accessing plaintext data where it matters.
• The package targets Node.js environments that run Express or NestJS servers. It provides a middleware API that fits naturally into the request pipeline.

Why this project

• End-to-end encryption improves data confidentiality at rest and in transit. It reduces risk from intermediate services and ensures only the intended recipient can decrypt payloads.
• The library uses a hybrid approach. AES-CBC handles bulk data efficiently. RSA handles secure key exchange without sharing symmetric keys in the open.
• It is designed for zero-config use. Developers can add robust encryption without rewriting existing request flows.

How it works

• Data path: client app -> encryption module -> HTTP request -> server middleware -> decryption module (on the intended recipient) -> application logic.
• Encryption flow:
  • Generate a fresh AES key for each message or session.
  • Encrypt the message with AES-CBC using the AES key and an IV.
  • Encrypt the AES key with RSA using the recipient’s public key.
  • Send the encrypted payload and the encrypted AES key together.
• Decryption flow:
  • Use the recipient’s private RSA key to decrypt the AES key.
  • Use the decrypted AES key and IV to decrypt the message.
  • Pass plaintext to the application logic in a secure, internal context.
• This approach minimizes plaintext exposure and supports secure key rotation and forward secrecy practices when used with rotating keys and strong RSA settings.

Supported environments

• Express.js apps
• NestJS apps
• TypeScript projects
• Node.js runtimes with modern ECMAScript support
• Environments that can load and run middleware in the request pipeline

Installation

• Install via npm or yarn as a local dependency.
• The package is designed to be installed into a Node.js project and then wired as middleware in your server setup.
• After installation, you will configure keys and options to enable encryption in your app.

Usage guide

• The middleware is intended to sit between the HTTP layer and your business logic. It intercepts requests, applies encryption/decryption as configured, and passes control to your route handlers.
• You configure a few core pieces: RSA key material, AES mode (AES-CBC), and any platform-specific adjustments you need to match your security posture.
• The library favors explicit configuration overmagic. You provide key material and options. The module handles the rest with sensible defaults.

Express integration

• Basic setup

  • Import the middleware factory from the package.
  • Bind the middleware to your Express app via app.use or your chosen routing strategy.
  • Provide a minimal configuration to enable encryption in your request/response flow.

• Example

  • This example shows a minimal Express app that uses the E2EE middleware for all routes.
  • It assumes you have RSA keys configured or provided via the options.

  import express from 'express'; import { e2eeExpressMiddleware } from 'e2ee-adapter';

  const app = express();

  // Minimal options example const options = { rsaPublicKey: -----BEGIN PUBLIC KEY----- // ... key data ... -----END PUBLIC KEY-----, rsaPrivateKey: -----BEGIN PRIVATE KEY----- // ... key data ... -----END PRIVATE KEY-----, aesMode: 'aes-256-cbc', // or a compatible variant };

  app.use(e2eeExpressMiddleware(options));

  app.post('/secure-endpoint', (req, res) => { // Your handler receives decrypted plaintext in req.body or a dedicated context const payload = req.body; // Process payload... res.json({ status: 'ok', received: payload }); });

  app.listen(3000, () => { console.log('Express server with E2EE middleware listening on port 3000'); });

NestJS integration

• NestJS approach

  • Use the middleware in a module configuration with the NestJS MiddlewareConsumer.
  • The middleware is designed to slot into the NestJS lifecycle with minimal boilerplate.

• Example

  • A compact NestJS setup demonstrating how to apply the E2EE middleware across routes.

  import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common'; import { e2eeExpressMiddleware as e2eeMiddleware } from 'e2ee-adapter';

  @Module({}) export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { const options = { rsaPublicKey: -----BEGIN PUBLIC KEY----- // ... key data ... -----END PUBLIC KEY-----, rsaPrivateKey: -----BEGIN PRIVATE KEY----- // ... key data ... -----END PRIVATE KEY-----, aesMode: 'aes-256-cbc', };

  consumer
    .apply(e2eeMiddleware(options))
    .forRoutes('*');
  

  } }

  // The module exports the configured middleware wire-up export class AppModule { }

API reference

• Exported API surface
  • e2eeExpressMiddleware(options): Express.RequestHandler
    • Options:
      • rsaPublicKey: string
      • rsaPrivateKey: string
      • aesMode: string (aes-256-cbc, aes-128-cbc, etc.)
      • keyExpirationMs?: number
      • rotateKeys?: boolean
  • e2eeNestMiddleware(options): NestMiddleware
    • Similar options as above
• Return values and behavior
  • The middleware attaches decrypted plaintext to the request context so your handlers can read req.body or a dedicated place like req.e2eePayload.
  • Encrypted payloads are never passed through to your business logic in plaintext; only after decryption is complete.
• Error handling
  • If key material is invalid, the middleware responds with an appropriate error and halts the request pipeline to avoid leaking data.

Encryption flow and security notes

• Hybrid encryption approach
  • The AES key is used to encrypt large payloads efficiently.
  • The RSA scheme secures the AES key exchange so only the intended recipient can decrypt it.
• IV handling
  • Each message uses a fresh IV to prevent replay and pattern attacks.
  • The IV is transmitted alongside the encrypted payload or derived in a deterministic yet secure way.
• Key management
  • Keys should be stored securely and rotated periodically.
  • Public keys can be distributed openly, while private keys must stay protected.
  • Consider hardware security modules (HSMs) or secure key vaults for production deployments.
• End-to-end boundary
  • Data remains encrypted until it reaches the intended recipient, even if intermediate services process the data.
  • The server acts as a pass-through for encrypted data with minimal plaintext exposure.

Security guidance

• Transport layer security remains essential. Always use TLS to protect data in transit from network-level interception.
• Do not hardcode keys in source code. Use a secure vault, environment-based secrets, or a dedicated key management service.
• Keep RSA key sizes strong (e.g., 2048 bits or higher) and rotate keys regularly.
• Use a strong, unique IV for every message and never reuse IVs with the same key.
• Validate inputs strictly. The middleware should reject malformed ciphertext and keys to prevent crashes or leaks.
• Audit logging should avoid logging plaintext payloads. Log only metadata that does not reveal sensitive content.
• Be mindful of error timing. Do not reveal cryptographic details in error responses.

Configuration and environment

• Key material
  • rsaPublicKey: the recipient’s public RSA key in PEM format
  • rsaPrivateKey: your private RSA key in PEM format
• Encryption settings
  • aesMode: selects AES mode, e.g., aes-256-cbc
  • keyExpirationMs: optional, how long a derived AES key is valid
  • rotateKeys: optional, enable automatic key rotation on a timer or per request
• Network settings
  • It is common to configure your TLS certificates separately from the E2EE middleware. The middleware assumes a secure network channel but does not replace TLS.
• Environment variables (optional)
  • E2EE_RSA_PUBLIC_KEY
  • E2EE_RSA_PRIVATE_KEY
  • E2EE_AES_MODE
  • E2EE_KEY_ROTATION_INTERVAL_MS

Testing and quality

• Unit tests cover core cryptographic operations, key wrapping, and error cases.
• Integration tests simulate Express and NestJS request lifecycles with encrypted payloads.
• Mock keys and ciphertexts are used to verify decryption paths and failure modes.
• Performance tests measure encryption/decryption throughput and latency under typical payload sizes.
• Security tests attempt common attack vectors, such as replay attempts or improper key usage, to ensure proper handling.

Roadmap

• Improve key management integrations with popular secret stores (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager).
• Add support for additional cipher modes and a pluggable crypto backend.
• Provide a browser-side companion library for end-to-end encryption with the same protocol.
• Expand tests to cover edge cases, such as very large payloads and multi-recipient scenarios.
• Enhance observability with structured metrics and rich tracing hooks.

Contributing

• We welcome contributions that improve security, reliability, and ease of use.
• Fork the repository, implement your changes, and submit a pull request with a clear description of the problem and the solution.
• Follow the project’s code style, add or update tests, and run the full test suite before proposing changes.
• Document any breaking changes and update the API reference accordingly.

License

• This project uses an open license to encourage adoption and collaboration.
• Check the LICENSE file in the repository for the exact terms and conditions.

Changelog

• Document feature additions, bug fixes, and security improvements.
• Each release entry includes a short summary and the impact on existing integrations.
• Users should review the changelog before upgrading to a new version to understand potential breaking changes.

FAQ

• Is this library safe for sensitive data?
  • It is designed to provide robust encryption using standard cryptographic primitives. Security depends on proper key management, correct integration, and adherence to best practices.
• Can I use this with any Express or NestJS project?
  • Yes. It is framework-agnostic within the Express/NestJS ecosystem as a middleware layer.
• Do I need to understand cryptography to use this?
  • Basic cryptography concepts help, but the middleware aims to minimize the need for deep cryptography knowledge. You provide keys and configuration, and the rest is handled by the library.
• What if I don’t want to expose private keys in the server?
  • The private key should stay on the server only if the server is the intended recipient for the encrypted data. If not, adapt the workflow to ensure private keys are kept secure and not exposed unnecessarily.

Releases

• The Releases page contains the download assets for different platforms. If you need to install, locate the asset for your OS and run the installer.
• For the latest stable assets and release notes, visit the Releases page at https://github.com/engrsadaqath/e2ee-adapter/releases

End of document

• This README is designed to be thorough and precise. It aims to help you understand, install, configure, and use the E2EE Adapter effectively in Express and NestJS projects. The guidance is practical and action-oriented, with code samples that demonstrate real-world usage and integration patterns.