@ubay182/hpke-wrapper

HPKE (Hybrid Public Key Encryption) wrapper for modern web applications (Next.js, SvelteKit, etc.) with end-to-end (E2E) encryption and seal/unseal obfuscation. RFC 9180 compliant.

Demo

Check out the complete implementation examples in the example/ folder:

• Next.js Example
• SvelteKit Example

cd example/next-16 # or example/sveltekit
npm install
npm run dev

Open http://localhost:3000 (or http://localhost:5173 for SvelteKit) — to see the end-to-end encryption form using HPKE.

Installation

npm install @ubay182/hpke-wrapper

Quick Start (Agnostic)

1. Server-side Initialization

You can create a singleton HPKE server instance that persists keys and rotates them automatically:

import { createHpkeServer } from "@ubay182/hpke-wrapper";

const server = createHpkeServer({
  persistKeys: true, // Save keys to .hpke-server-keys.json
  rotateKeys: true, // Auto rotate every 24 hours
  keysFilePath: "./.keys", // Custom path (optional)
  rotationIntervalMs: 24 * 60 * 60 * 1000,
});

await server.init();

// Use these functions in your API routes/endpoints:
const pubKey = server.getPublicKeyBase64();
const decryptedText = await server.decrypt(wrappedCiphertext);
const encryptedResponse = await server.encrypt(message, clientPubKeyB64);

2. Client-side Encryption

import {
  createHpkeSuite,
  generateKeyPair,
  seal,
  unseal,
} from "@ubay182/hpke-wrapper";

const suite = createHpkeSuite();
const clientKeys = await generateKeyPair();

// 1. Encrypt data to send to the server
const sealedPayload = await seal(
  suite,
  serverPubKeyB64,
  JSON.stringify({
    data: "my secret",
    _clientPublicKey: clientKeys.publicKey,
  }),
);

// ... send sealedPayload to the server via POST, receive encrypted response ...

// 2. Decrypt server response
const decrypted = await unseal(suite, clientKeys.privateKey, encryptedResponse);

Next.js Integration Helpers

This package provides specific helper functions for Next.js to make setup easier.

Route Handlers

app/api/hpke/route.ts:

import { createHpkeHandlers } from "@ubay182/hpke-wrapper";

const { GET, POST } = createHpkeHandlers({
  persistKeys: true,
  rotateKeys: true,
  onRequest: async (decrypted) => {
    // decrypted: parsed JSON from client (without _clientPublicKey)
    // The return value will be encrypted and sent back to the client
    return { result: "success", data: decrypted };
  },
});

export { GET, POST };

Middleware Helper (Send public key via cookie)

middleware.ts:

import { createHpkeServer, createHpkeMiddleware } from "@ubay182/hpke-wrapper";

const server = createHpkeServer({ autoGenerateKeys: true });
server.init().catch(() => {});

export default createHpkeMiddleware(server);

export const config = { matcher: "/:path*" };

Note: Middleware runs on Edge Runtime where the fs module is not available. For fully persistent key storage, use the Route Handler approach.

API

Core HPKE

| Function | Description | | ------------------------------- | --------------------------------- | | createHpkeSuite() | HPKE suite with AES-128-GCM | | createHpkeSuiteChaCha20() | HPKE suite with ChaCha20-Poly1305 | | generateKeyPair() | Generate X25519 key pair | | exportKeyToBase64(key) | Export public key to base64 | | importKeyFromBase64(b64) | Import public key from base64 | | hpkeEncrypt(msg, pubKey) | Encrypt message | | hpkeDecrypt(ct, enc, privKey) | Decrypt message | | uint8ArrayToBase64(buf) | Encode Uint8Array to base64 | | base64ToUint8Array(b64) | Decode base64 to Uint8Array |

Seal / Unseal (Recommended)

| Function | Description | | ----------------------------------- | ------------------------------------- | | seal(suite, pubKeyB64, plainText) | Encrypt + obfuscate → single string | | unseal(suite, privKey, cipher) | Decrypt obfuscated string → plaintext |

The sealed format wraps the HPKE ciphertext with random prefix/suffix, which aims to hide the encryption structure:

"x7k2mSGVsbG8gV29ybG...x7k2m0"

Encryption Flow

CLIENT (Browser)                          SERVER (Node/Next.js/SvelteKit)
─────────────────                        ─────────────────
1. Page loads                             Hook/Middleware sets cookie:
   Reads cookie:                          hpke_server_public_key=<b64>
   hpke_server_public_key

2. Generate client X25519 key pair

3. seal(suite, serverPubKey, payload)
   → "x7k2m<encrypted>...x7k2m0"

4. POST /api/hpke { data: "..." }
                                          5. server.decrypt(data)
                                             → unseal → plaintext

                                          6. Extract _clientPublicKey

                                          7. Process Request / Call external API

                                          8. server.encrypt(response, clientPubKey)
                                             → seal → "..."

                                          9. Return { data: "..." }

10. unseal(suite, clientPrivKey, response)
    → plaintext

Key Persistence

If using persistKeys: true, keys will be saved to the .hpke-server-keys.json file. This ensures keys persist across server restarts. Note: This feature uses the fs module (Node.js only) — it is not available on Edge Runtime.

Key Rotation

If using rotateKeys: true, new keys will be generated every rotationIntervalMs interval. Old keys will be kept for a grace period so in-flight encrypted messages can still be decrypted.

Security

• RFC 9180 compliant (X25519 + HKDF-SHA256 + AES-128-GCM)
• Seal/Unseal obfuscation hides encryption metadata structure
• Auto key rotation with grace period
• Public key delivery via cookie (no additional API call required)

For production with sensitive data:

1. Use KMS/HSM instead of file-based key storage
2. Always use HTTPS
3. Add rate limiting and request validation
4. Use Redis for servers with multi-instance setups
5. Consider ChaCha20-Poly1305 if you have many mobile app clients

License

MIT