HTTP Encrypted Content-Encoding

1.2.1 · active · verified Tue Apr 21

This package provides a simple, direct implementation of the HTTP Encrypted Content-Encoding (RFC 8188) specification for Node.js environments. It enables the encryption and decryption of HTTP request and response bodies, primarily used in Web Push applications. The current stable version is 1.2.1. While not on a fixed release schedule, updates occur as needed, with the latest focusing on development tooling. Its primary differentiator is its focused adherence to RFC 8188, offering functions for both symmetric and static-ephemeral ECDH encryption modes, without additional layers or external runtime dependencies beyond Node.js built-ins, making it a lightweight option for content encryption. It targets modern Node.js environments, requiring Node.js version 16 or newer.

Common errors

```
TypeError: require is not defined in ES module scope
```
cause Attempting to use `require()` in a JavaScript file that is treated as an ES module (e.g., a `.mjs` file or a file in a package with `"type": "module"`).

fix Replace `const ece = require('http_ece');` with `import ece from 'http_ece';` for ES module compatibility.
```
TypeError: Cannot read properties of undefined (reading 'encrypt')
```
cause This usually occurs when trying to call `ece.encrypt` after an incorrect ES module import, such as `import { ece } from 'http_ece';`, which would make `ece` undefined or an empty object.

fix Ensure you are using the correct default import for ES modules: `import ece from 'http_ece';`. The CommonJS `module.exports` object is the default export.

Warnings

gotcha The `http_ece` package explicitly requires Node.js version 16 or higher. Running it on older Node.js versions may lead to unexpected errors due to unavailable APIs or module loading issues.
Fix: Ensure your project's Node.js environment is version 16 or newer. Update Node.js using `nvm install 16` (or higher) and `nvm use 16` or similar version management tools.

Install

npm install http_ece npm
yarn add http_ece yarn
pnpm add http_ece pnpm

Imports

ece (CommonJS)
```
const ece = require('http_ece');
```
This is the standard CommonJS import pattern. The package is primarily distributed as a CommonJS module.
ece (ES Modules)
wrong:
```
import { ece } from 'http_ece';
```
correct:
```
import ece from 'http_ece';
```
When using ES Modules, the CommonJS `module.exports` object is imported as the default export. Attempting to destructure `ece` will result in `undefined` for named imports.
encrypt / decrypt methods
wrong:
```
import { encrypt, decrypt } from 'http_ece';
```
correct:
```
import ece from 'http_ece'; ece.encrypt(data, params);
```
The `encrypt` and `decrypt` functions are methods of the `ece` module object, not named exports from the package root.

Quickstart

This quickstart demonstrates how to encrypt and decrypt a Buffer using the `http_ece` module with randomly generated keys and salts, and then verifies the integrity of the decrypted data.

import ece from 'http_ece';
import { randomBytes } from 'crypto';
import assert from 'assert';

async function runEncryptionExample() {
  // Data to be encrypted – a Buffer is expected.
  const data = Buffer.from('This is some sensitive data that needs to be encrypted before sending over HTTP. It should be long enough to test the encryption process properly and verify integrity.');

  // Generate random keys and salts for encryption parameters. These must be kept secret and shared out-of-band.
  const parameters = {
    key: randomBytes(16).toString('base64url'), // 16 bytes for a 128-bit key
    salt: randomBytes(16).toString('base64url') // 16 bytes for a 128-bit salt
  };

  console.log('Original Data:', data.toString('utf8'));
  console.log('Encryption Parameters (base64url):', parameters);

  // Encrypt the data using the generated parameters
  const encrypted = ece.encrypt(data, parameters);
  console.log('Encrypted Data (Buffer):', encrypted);

  // Decrypt the data using the same parameters
  const decrypted = ece.decrypt(encrypted, parameters);
  console.log('Decrypted Data (Buffer):', decrypted);

  // Verify that the decrypted data matches the original data
  assert.equal(decrypted.compare(data), 0, 'Decrypted data does not match original!');
  console.log('Verification successful: Decrypted data matches original.');
}

runEncryptionExample().catch(console.error);

view raw JSON →