A TypeScript Hybrid Public Key Encryption (HPKE) core module implemented using only Web Cryptography API. It does not support the X448-based KEM and the ChaCha20Poly1305 AEAD, but it has no external module dependencies. It's small in size and tree-shaking friendly.
Auth and AuthPSK require a KEM that supports AuthEncap/AuthDecap. ML-KEM, X-Wing
and X25519-Kyber768 support only Base and PSK modes; requesting authentication
with these KEMs throws NotSupportedError (RFC 9180 Section 7.1.5).
Where possible, it is recommended to use @hpke/core along with extension
modules (such as @hpke/chacha20poly1305) instead of hpke-js.
Node.js
You can install the package with npm, yarn or pnpm.
# Using npm:npm install @hpke/coreyarn add @hpke/corepnpm install @hpke/core# Using jsr:npx jsr add @hpke/coreyarn add jsr:@hpke/corepnpm add jsr:@hpke/core
The above manner can be used with other JavaScript runtimes that support npm,
such as Cloudflare Workers and Bun.
Then, you can use the module from code like this:
import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256,} from "@hpke/core";
Deno
For Deno, it is recommended to use the jsr.io registry.
deno add jsr:@hpke/core
Web Browsers
Followings are how to use this module with typical CDNs. Other CDNs can be used
as well.
Using esm.sh:
<!-- use a specific version --><script type="module">import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256,} from "https://esm.sh/@hpke/core@<SEMVER>";// ...</script><!-- use the latest stable version --><script type="module">import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256,} from "https://esm.sh/@hpke/core";// ...</script>
Using unpkg:
<!-- use a specific version --><script type="module">import * as hpke from "https://unpkg.com/@hpke/core@<SEMVER>/esm/mod.js";// ...</script>
Usage
This section shows some typical usage examples.
Node.js
import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256,} from "@hpke/core";async function doHpke() { // setup const suite = new CipherSuite({ kem: new DhkemP256HkdfSha256(), kdf: new HkdfSha256(), aead: new Aes128Gcm(), }); const rkp = await suite.kem.generateKeyPair(); const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, });
Deno
import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256,} from "@hpke/core";async function doHpke() { // setup const suite = new CipherSuite({ kem: new DhkemP256HkdfSha256(), kdf: new HkdfSha256(), aead: new Aes128Gcm(), }); const rkp = await suite.kem.generateKeyPair(); const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, });
Web Browsers
<html> <head></head> <body> <script type="module"> import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256, } from "https://esm.sh/@hpke/core"; globalThis.doHpke = async () => { const suite = new CipherSuite({ kem: new DhkemP256HkdfSha256(), kdf: new HkdfSha256(), aead: new Aes128Gcm(), });
Contributing
We welcome all kind of contributions, filing issues, suggesting new features or
sending PRs.