simple-hpke 0.0.11 → 0.1.1

package/README.md

@@ -1,5 +1,5 @@
 # Simple HPKE
-[![tests](https://img.shields.io/github/actions/workflow/status/nichoth/simple-hpke/nodejs.yml?style=flat-square)](https://github.com/nichoth/simple-hpke/actions/workflows/nodejs.yml)
+[![tests](https://img.shields.io/github/actions/workflow/status/vanishing-page/simple-hpke/nodejs.yml?style=flat-square)](https://github.com/vanishing-page/simple-hpke/actions/workflows/nodejs.yml)
 [![types](https://img.shields.io/npm/types/simple-hpke?style=flat-square)](README.md)
 [![module](https://img.shields.io/badge/module-ESM%2FCJS-blue?style=flat-square)](README.md)
 [![semantic versioning](https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square)](https://semver.org/)
@@ -54,7 +54,7 @@ Wrap an AES key, or encrypt a message.
 Encrypt an AES key to yourself, then recover it later.
 
 ```ts
-import { seal, open } from 'simple-hpke'
+import { create, seal, open } from 'simple-hpke'
 
 // An X25519 keypair. (asymmetric keypair).
 // The private key can be non-extractable.
@@ -65,8 +65,8 @@ const keypair = await crypto.subtle.generateKey(
     ['deriveBits']
 )
 
-// create a new AES key, and encrypt it to your public key.
-const { wrapped, key } = await seal(keypair)
+// Create a new AES key and encrypt it to your public key.
+const { enc, key } = await create(keypair)
 
 // Or wrap an existing AES key. The supplied AES key must be extractable.
 const aesKey = await crypto.subtle.generateKey(
@@ -75,11 +75,13 @@ const aesKey = await crypto.subtle.generateKey(
     ['encrypt', 'decrypt']
 )
 
-// pass in an existing key. The return value has the wrapped key.
-const { wrapped } = await seal(keypair, aesKey)
+// Wrap an existing key.
+const { enc: sealedKey } = await seal(keypair, aesKey)
+
+// or pass in just a public key
 
 // Later, recover the same key with your private key.
-const recoveredKey = await open(keypair, wrapped)
+const recoveredKey = await open(keypair, sealedKey)
 
 // `recoveredKey` is equal to `aesKey`
 ```
@@ -98,7 +100,7 @@ along with the IV. The recipient uses their private key to open the AES key and
 decrypt the message.
 
 ```ts
-import { seal, open } from 'simple-hpke'
+import { create, open } from 'simple-hpke'
 
 const recipient = await crypto.subtle.generateKey(
     { name: 'X25519' },
@@ -106,31 +108,34 @@ const recipient = await crypto.subtle.generateKey(
     ['deriveBits']
 )
 
-// Create and seal a fresh AES-GCM key, and encrypt a message with it.
-const { wrapped, key } = await seal(recipient)
+// Create a fresh AES-GCM key, and encrypt a message with it.
+const { enc, key } = await create(recipient)
 const iv = crypto.getRandomValues(new Uint8Array(12))
-const ciphertext = await crypto.subtle.encrypt(
+const ciphertextBuffer = await crypto.subtle.encrypt(
     { name: 'AES-GCM', iv },
     key,
     new TextEncoder().encode('attack at dawn')
 )
 
-// Send `wrapped`, `iv`, and `ciphertext` together. `wrapped` is a fixed
-// 80 bytes for this suite, and the AES-GCM IV is 12 bytes, so the recipient
-// can slice the payload back apart at known offsets.
-const ciphertext = new Uint8Array(ciphertext)
-const message = new Uint8Array(wrapped.length + iv.length + ciphertext.length)
-message.set(wrapped, 0)
-message.set(iv, wrapped.length)
-message.set(ciphertext, wrapped.length + iv.length)
+// Send `enc`, `iv`, and `ciphertext` together. `create(...)` defaults to a
+// 256-bit AES key, so `enc.length` is 80 bytes in this example.
+//
+// If your protocol allows different wrapped-key sizes, prefix `enc.length`
+// (or otherwise transmit it) so the recipient can split the payload safely.
+const ciphertext = new Uint8Array(ciphertextBuffer)
+const encLength = enc.length
+const message = new Uint8Array(encLength + iv.length + ciphertext.length)
+message.set(enc, 0)
+message.set(iv, encLength)
+message.set(ciphertext, encLength + iv.length)
 
 // On the other side, split the payload back into its parts.
-const wrapped2 = message.subarray(0, 80)
-const iv2 = message.subarray(80, 80 + 12)
-const ciphertext2 = message.subarray(80 + 12)
+const enc2 = message.subarray(0, encLength)
+const iv2 = message.subarray(encLength, encLength + 12)
+const ciphertext2 = message.subarray(encLength + 12)
 
 // Recover the key, then decrypt the message.
-const recovered = await open(recipient, wrapped2)
+const recovered = await open(recipient, enc2)
 const plaintext = await crypto.subtle.decrypt(
     { name: 'AES-GCM', iv: iv2 },
     recovered,
@@ -146,7 +151,8 @@ So that was a lot of code to encrypt and decrypt a message...
 This package exposes functions `encrypt` and `decrypt` which do the same thing.
 
 `encrypt` seals an AES key to the recipient, encrypts the message under
-that key, and returns a single envelope: `wrappedLen + wrapped + iv + ciphertext`
+that key, and returns a single envelope:
+`wrappedLen + wrapped + iv + ciphertext`
 (a 2-byte length prefix, the wrapped key, the 12-byte AES-GCM IV, and the
 cipher text). `decrypt` reverses it, returning the plaintext bytes.
 
@@ -156,8 +162,8 @@ cipher text). `decrypt` reverses it, returning the plaintext bytes.
 > [`decrypt.fromString`](#decryptfromstring) below for a convenient way
 > to decrypt from a string.
 >
-> See [`encrypt.asString`](#encrypt-to-a-string) for encrypting and ecoding to
-> a string.
+> See [`encrypt.asString`](#encryptasstring) for encrypting and encoding to a
+> string.
 >
 
 
@@ -249,7 +255,7 @@ bytes to `decrypt` / `decrypt.asString`.
 
 ##### `decrypt`
 
-Descrypt the given data, return a `Uint8Array`.
+Decrypt the given data, return a `Uint8Array`.
 
 ```ts
 async function decrypt (
@@ -261,7 +267,7 @@ async function decrypt (
 
 ##### `decrypt.asString`
 
-Take a `Uint8Array`, return a sttring.
+Take a `Uint8Array`, return a string.
 
 ```ts
 decrypt.asString = async function decryptToString (
@@ -293,7 +299,7 @@ This exposes ESM and common JS via
 
 ### ESM
 ```js
-import { seal, open, encrypt, decrypt } from 'simple-hpke'
+import { create, seal, open, encrypt, decrypt } from 'simple-hpke'
 ```
 
 ### Common JS

package/dist/constants.cjs

@@ -1317,51 +1317,19 @@ __name(toString2, "toString");
 
 // src/index.ts
 var subtle = globalThis.crypto.subtle;
+async function create2(recipient, opts) {
+  const { wrapped, key } = await encryptKey(recipient, null, opts);
+  return { enc: wrapped, key };
+}
+__name(create2, "create");
 async function seal(recipient, aesKey, opts) {
-  const info = normalizeInfo(opts?.info);
-  let keyBytes;
-  if (aesKey instanceof Uint8Array) {
-    validateRawKeyBytes(aesKey);
-    keyBytes = aesKey;
-  } else if (aesKey) {
-    keyBytes = await exportAesKeyBytes(aesKey);
-    validateRawKeyBytes(keyBytes);
-  } else {
-    const keysize = opts?.keysize ?? 256;
-    validateKeysize(keysize);
-    keyBytes = globalThis.crypto.getRandomValues(
-      new Uint8Array(keysize / 8)
-    );
-  }
-  const publicKey = await resolveRecipientPublicKey(recipient);
-  const { sharedSecret, enc } = await encap(publicKey);
-  const { key, baseNonce } = await keySchedule(sharedSecret, info);
-  const ciphertext = await aeadSeal(key, baseNonce, keyBytes);
-  const wrapped = concat2(enc, ciphertext);
-  const aesGcmKey = await importAesKey(keyBytes);
-  return { wrapped, key: aesGcmKey };
+  const { wrapped, key } = await encryptKey(recipient, aesKey, opts);
+  return { enc: wrapped, key };
 }
 __name(seal, "seal");
 var open = Object.assign(openBytes, {
   raw: openRawBytes
 });
-async function openBytes(keypair, wrapped, opts) {
-  const keyBytes = await openRawBytes(keypair, wrapped, opts);
-  return importAesKey(keyBytes);
-}
-__name(openBytes, "openBytes");
-async function openRawBytes(keypair, wrapped, opts) {
-  if (wrapped.byteLength < ENC_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("malformed envelope: too short");
-  }
-  const info = normalizeInfo(opts?.info);
-  const enc = wrapped.slice(0, ENC_LENGTH);
-  const ciphertext = wrapped.slice(ENC_LENGTH);
-  const sharedSecret = await decap(enc, keypair);
-  const { key, baseNonce } = await keySchedule(sharedSecret, info);
-  return aeadOpen(key, baseNonce, ciphertext);
-}
-__name(openRawBytes, "openRawBytes");
 var encrypt = Object.assign(encryptBytes, {
   asString: encryptToString
 });
@@ -1500,6 +1468,48 @@ async function keySchedule(sharedSecret, info) {
   return { key, baseNonce };
 }
 __name(keySchedule, "keySchedule");
+async function openRawBytes(keypair, wrapped, opts) {
+  if (wrapped.byteLength < ENC_LENGTH + AEAD_TAG_LENGTH) {
+    throw new Error("malformed envelope: too short");
+  }
+  const info = normalizeInfo(opts?.info);
+  const enc = wrapped.slice(0, ENC_LENGTH);
+  const ciphertext = wrapped.slice(ENC_LENGTH);
+  const sharedSecret = await decap(enc, keypair);
+  const { key, baseNonce } = await keySchedule(sharedSecret, info);
+  return aeadOpen(key, baseNonce, ciphertext);
+}
+__name(openRawBytes, "openRawBytes");
+async function openBytes(keypair, wrapped, opts) {
+  const keyBytes = await openRawBytes(keypair, wrapped, opts);
+  return importAesKey(keyBytes);
+}
+__name(openBytes, "openBytes");
+async function encryptKey(recipient, aesKey, opts) {
+  const info = normalizeInfo(opts?.info);
+  let keyBytes;
+  if (aesKey instanceof Uint8Array) {
+    validateRawKeyBytes(aesKey);
+    keyBytes = aesKey;
+  } else if (aesKey) {
+    keyBytes = await exportAesKeyBytes(aesKey);
+    validateRawKeyBytes(keyBytes);
+  } else {
+    const keysize = opts?.size ?? 256;
+    validateKeysize(keysize);
+    keyBytes = globalThis.crypto.getRandomValues(
+      new Uint8Array(keysize / 8)
+    );
+  }
+  const publicKey = await resolveRecipientPublicKey(recipient);
+  const { sharedSecret, enc } = await encap(publicKey);
+  const { key, baseNonce } = await keySchedule(sharedSecret, info);
+  const ciphertext = await aeadSeal(key, baseNonce, keyBytes);
+  const wrapped = concat2(enc, ciphertext);
+  const aesGcmKey = await importAesKey(keyBytes);
+  return { wrapped, key: aesGcmKey };
+}
+__name(encryptKey, "encryptKey");
 
 // src/util.ts
 var subtle2 = globalThis.crypto.subtle;
@@ -1537,14 +1547,24 @@ async function aeadOpen(key, nonce, ciphertext) {
 __name(aeadOpen, "aeadOpen");
 async function encryptBytes(recipient, message, aesKey, opts) {
   const plaintext = typeof message === "string" ? new TextEncoder().encode(message) : message;
-  const { wrapped, key } = await seal(recipient, aesKey, opts);
+  let enc;
+  let key;
+  if (!aesKey) {
+    const keys = await create2(recipient, opts);
+    enc = keys.enc;
+    key = keys.key;
+  } else {
+    const keys = await seal(recipient, aesKey, opts);
+    enc = keys.enc;
+    key = keys.key;
+  }
   const iv = globalThis.crypto.getRandomValues(new Uint8Array(NN));
   const ct = new Uint8Array(await subtle2.encrypt(
     { name: "AES-GCM", iv },
     key,
     plaintext
   ));
-  return concat2(i2osp(wrapped.length, WRAPPED_LEN_PREFIX), wrapped, iv, ct);
+  return concat2(i2osp(enc.length, WRAPPED_LEN_PREFIX), enc, iv, ct);
 }
 __name(encryptBytes, "encryptBytes");
 async function encryptToString(recipient, message, aesKey, opts) {