simple-hpke 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { type RecipientKey, encryptToString, encryptBytes, keyId } from './util';
-export { keyId };
+import { type RecipientKey, encryptToString, encryptBytes, keyId, verifyKeyId } from './util';
+export { keyId, verifyKeyId };
 export { HpkeError, type HpkeErrorCode } from './errors';
 /**
  * Create a new AES key for the given public key.
@@ -127,14 +127,17 @@ declare function openBytes(keypair: CryptoKeyPair, wrapped: Uint8Array, opts?: {
  * @param aesKey Optional key to wrap, as either an AES-GCM `CryptoKey` or its
  *   raw bytes (`Uint8Array`, 16 or 32 bytes). Omit to generate a fresh key
  *   of `opts.size` bits. A supplied `CryptoKey` MUST be extractable (its
- *   raw bytes are wrapped) -- that is an input constraint, unrelated to
- *   `opts.extractable`, which governs the key this returns.
+ *   raw bytes are wrapped) and is returned as-is: the same object, with
+ *   its own `extractable` and usages. It does not need the `encrypt`
+ *   usage, since wrapping never encrypts with it.
  * @param opts `size` (128/256, default 256; ignored when `aesKey` is
  *   supplied), `info` (bound into the HPKE key schedule; default empty),
- *   and `extractable` (whether the RETURNED key can be exported; default
- *   false).
+ *   and `extractable` (whether a key this function imports -- a
+ *   generated key or raw `Uint8Array` bytes -- can be exported; default
+ *   false). `extractable` does not apply to a supplied `CryptoKey`.
  * @returns { wrapped:Uint8Array, key:CryptoKey } The wrapped envelope
- *   bytes and a usable AES-GCM `CryptoKey`.
+ *   bytes and the AES-GCM `CryptoKey`: the supplied `CryptoKey` itself
+ *   when one was given, otherwise a newly imported key.
  */
 export declare function encryptKey(recipient: RecipientKey, aesKey?: CryptoKey | Uint8Array | null, opts?: {
     size?: 128 | 256;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,YAAY,EAGjB,eAAe,EACf,YAAY,EAOZ,KAAK,EACL,WAAW,EACd,MAAM,QAAQ,CAAA;AAYf,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAA;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAA;AAWxD;;;;;;;GAOG;AACH,wBAAsB,MAAM,CACxB,SAAS,EAAC,YAAY,EACtB,IAAI,CAAC,EAAC;IAEF,IAAI,CAAC,EAAC,GAAG,GAAC,GAAG,CAAA;IAEb,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;IAEvB,WAAW,CAAC,EAAC,OAAO,CAAA;CACvB,GACH,OAAO,CAAC;IAAE,OAAO,EAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAAC,GAAG,EAAC,SAAS,CAAA;CAAE,CAAC,CAGhE;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI;;CAEf,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,OAAO;;CAElB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;CAGlB,CAAA;AAEF;;;;;;;;GAQG;AACH,iBAAe,YAAY,CACvB,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,UAAU,EAClB,IAAI,CAAC,EAAC;IAAE,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;CAAE,GACnC,OAAO,CAAC,UAAU,CAAC,CA+CpB;AAED;;;;;;;;GAQG;AACH,iBAAe,eAAe,CAC1B,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,UAAU,EAClB,IAAI,CAAC,EAAC;IAAE,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;CAAE,GACnC,OAAO,CAAC,MAAM,CAAC,CAGhB;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAe,iBAAiB,CAC5B,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,MAAM,EACd,IAAI,CAAC,EAAC;IAAE,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAC;IAAC,MAAM,CAAC,EAAC,KAAK,CAAA;CAAE,GAClD,OAAO,CAAC,MAAM,CAAC,CAAA;AAEjB,iBAAe,iBAAiB,CAC5B,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,MAAM,EACd,IAAI,EAAC;IAAE,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAC;IAAC,MAAM,EAAC,IAAI,CAAA;CAAE,GAC/C,OAAO,CAAC,UAAU,CAAC,CAAA;AA6IrB;;;;;;;;;;GAUG;AACH,iBAAe,YAAY,CACvB,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,UAAU,EAClB,IAAI,CAAC,EAAC;IAAE,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;CAAE,GACnC,OAAO,CAAC,UAAU,CAAC,CAepB;AAED;;;;;;;;;GASG;AACH,iBAAe,SAAS,CACpB,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,UAAU,EAClB,IAAI,CAAC,EAAC;IAAE,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAC;IAAC,WAAW,CAAC,EAAC,OAAO,CAAA;CAAE,GACzD,OAAO,CAAC,SAAS,CAAC,CAGnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,UAAU,CAC5B,SAAS,EAAC,YAAY,EACtB,MAAM,CAAC,EAAC,SAAS,GAAC,UAAU,GAAC,IAAI,EACjC,IAAI,CAAC,EAAC;IAEF,IAAI,CAAC,EAAC,GAAG,GAAC,GAAG,CAAA;IAEb,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;IAGvB,WAAW,CAAC,EAAC,OAAO,CAAA;CACvB,GACH,OAAO,CAAC;IAAE,OAAO,EAAC,UAAU,CAAC;IAAC,GAAG,EAAC,SAAS,CAAA;CAAE,CAAC,CA8C/C"}

package/dist/index.js

@@ -1365,6 +1365,12 @@ async function aeadOpen(key, nonce, ciphertext) {
 }
 __name(aeadOpen, "aeadOpen");
 async function encryptBytes(recipient, message, aesKey, opts) {
+  if (aesKey instanceof CryptoKey && !aesKey.usages.includes("encrypt")) {
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
+      'aesKey is missing the "encrypt" usage, which encrypt needs to encrypt the message'
+    );
+  }
   const plaintext = typeof message === "string" ? new TextEncoder().encode(message) : message;
   const { wrapped, key } = await encryptKey(recipient, aesKey, opts);
   const iv = globalThis.crypto.getRandomValues(new Uint8Array(NN));
@@ -1463,37 +1469,28 @@ async function resolveRecipientPublicKey(recipient) {
     return importRawPublic(recipient);
   }
   if (recipient instanceof CryptoKey) {
-    if (recipient.type !== "public") {
-      throw new HpkeError(
-        "ERR_INVALID_RECIPIENT_KEY",
-        "recipient CryptoKey must be a public key"
-      );
-    }
-    assertX25519Algorithm(
-      recipient,
-      "recipient CryptoKey",
-      "ERR_INVALID_RECIPIENT_KEY"
-    );
-    return recipient;
+    return assertRecipientPublicKey(recipient, "recipient CryptoKey");
   }
   if (typeof recipient.publicKey === "string") {
     const { publicKey, encoding } = recipient;
-    return importRawPublic(fromString2(publicKey, encoding ?? "base64url"));
-  }
-  const pair = recipient;
-  if (pair.publicKey instanceof CryptoKey) {
-    if (pair.publicKey.type !== "public") {
+    let decoded;
+    try {
+      decoded = fromString2(publicKey, encoding ?? "base64url");
+    } catch (err) {
       throw new HpkeError(
         "ERR_INVALID_RECIPIENT_KEY",
-        "recipient keypair publicKey must be a public key"
+        `recipient publicKey string does not decode as ${encoding ?? "base64url"}`,
+        { cause: err }
       );
     }
-    assertX25519Algorithm(
+    return importRawPublic(decoded);
+  }
+  const pair = recipient;
+  if (pair.publicKey instanceof CryptoKey) {
+    return assertRecipientPublicKey(
       pair.publicKey,
-      "recipient keypair publicKey",
-      "ERR_INVALID_RECIPIENT_KEY"
+      "recipient keypair publicKey"
     );
-    return pair.publicKey;
   }
   throw new HpkeError(
     "ERR_INVALID_RECIPIENT_KEY",
@@ -1501,6 +1498,23 @@ async function resolveRecipientPublicKey(recipient) {
   );
 }
 __name(resolveRecipientPublicKey, "resolveRecipientPublicKey");
+function assertRecipientPublicKey(key, context) {
+  if (key.type !== "public") {
+    throw new HpkeError(
+      "ERR_INVALID_RECIPIENT_KEY",
+      `${context} must be a public key`
+    );
+  }
+  assertX25519Algorithm(key, context, "ERR_INVALID_RECIPIENT_KEY");
+  if (!key.extractable) {
+    throw new HpkeError(
+      "ERR_INVALID_RECIPIENT_KEY",
+      `${context} must be extractable (the KEM exports it)`
+    );
+  }
+  return key;
+}
+__name(assertRecipientPublicKey, "assertRecipientPublicKey");
 function assertX25519Algorithm(key, context, code2) {
   if (key.algorithm.name !== "X25519") {
     throw new HpkeError(
@@ -1511,11 +1525,23 @@ function assertX25519Algorithm(key, context, code2) {
 }
 __name(assertX25519Algorithm, "assertX25519Algorithm");
 async function dh(priv, pub) {
-  const bits = await subtle.deriveBits(
-    { name: "X25519", public: pub },
-    priv,
-    256
-  );
+  let bits;
+  try {
+    bits = await subtle.deriveBits(
+      { name: "X25519", public: pub },
+      priv,
+      256
+    );
+  } catch (err) {
+    if (err?.name === "OperationError") {
+      throw new HpkeError(
+        "ERR_SMALL_ORDER_KEY",
+        "X25519 deriveBits rejected a small-order public key",
+        { cause: err }
+      );
+    }
+    throw err;
+  }
   const bytes = new Uint8Array(bits);
   if (bytes.every((b) => b === 0)) {
     throw new HpkeError(
@@ -1568,6 +1594,23 @@ async function decap(enc, keypair) {
     "keypair.privateKey",
     "ERR_INVALID_KEYPAIR"
   );
+  if (!keypair.privateKey.usages.includes("deriveBits")) {
+    throw new HpkeError(
+      "ERR_INVALID_KEYPAIR",
+      "keypair.privateKey must have the deriveBits usage"
+    );
+  }
+  if (keypair.publicKey.type !== "public" || !keypair.publicKey.extractable) {
+    throw new HpkeError(
+      "ERR_INVALID_KEYPAIR",
+      "keypair.publicKey must be an extractable public key"
+    );
+  }
+  assertX25519Algorithm(
+    keypair.publicKey,
+    "keypair.publicKey",
+    "ERR_INVALID_KEYPAIR"
+  );
   const pkE = await subtle.importKey(
     "raw",
     enc,
@@ -1610,6 +1653,16 @@ async function keyId(key) {
   return toString2(new Uint8Array(digest2), "base64url");
 }
 __name(keyId, "keyId");
+async function verifyKeyId(key, expected) {
+  const actual = await keyId(key);
+  if (actual.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) {
+    diff |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return diff === 0;
+}
+__name(verifyKeyId, "verifyKeyId");
 function i2osp(n, len) {
   const out = new Uint8Array(len);
   let v = n;
@@ -1698,7 +1751,16 @@ async function decryptToString(keypair, message, opts) {
 }
 __name(decryptToString, "decryptToString");
 async function decryptFromString(keypair, message, opts) {
-  const bytes = fromString2(message, "base64url");
+  let bytes;
+  try {
+    bytes = fromString2(message, "base64url");
+  } catch (err) {
+    throw new HpkeError(
+      "ERR_MALFORMED_MESSAGE",
+      "malformed message: not base64url",
+      { cause: err }
+    );
+  }
   const plaintext = await decryptBytes(
     keypair,
     bytes,
@@ -1826,6 +1888,12 @@ async function encryptKey(recipient, aesKey, opts) {
     validateRawKeyBytes(aesKey);
     keyBytes = aesKey;
   } else if (aesKey) {
+    if (aesKey.algorithm.name !== "AES-GCM") {
+      throw new HpkeError(
+        "ERR_INVALID_AES_KEY",
+        "aesKey must be an AES-GCM key, got " + aesKey.algorithm.name
+      );
+    }
     keyBytes = await exportAesKeyBytes(aesKey);
     validateRawKeyBytes(keyBytes);
   } else {
@@ -1840,6 +1908,7 @@ async function encryptKey(recipient, aesKey, opts) {
   const { key, baseNonce } = await keySchedule(sharedSecret, info);
   const ciphertext = await aeadSeal(key, baseNonce, keyBytes);
   const wrapped = concat2(enc, ciphertext);
+  if (aesKey instanceof CryptoKey) return { wrapped, key: aesKey };
   const aesGcmKey = await importAesKey(
     keyBytes,
     opts?.extractable ?? false
@@ -1854,6 +1923,7 @@ export {
   encrypt,
   encryptKey,
   keyId,
-  open
+  open,
+  verifyKeyId
 };
 //# sourceMappingURL=index.js.map