simple-hpke 0.3.1 → 0.3.3

package/dist/util.d.ts

@@ -32,7 +32,11 @@ export declare function aeadOpen(key: Uint8Array, nonce: Uint8Array, ciphertext:
  * @param message Plaintext to encrypt. A `string` is UTF-8 encoded.
  * @param aesKey Optional key, 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. Each
+ *   `opts.size` bits. A supplied `CryptoKey` MUST be extractable and
+ *   MUST have the `encrypt` usage (the message is encrypted under it
+ *   directly; otherwise this throws `ERR_INVALID_AES_KEY`). It is used
+ *   as-is and never re-imported, so the `opts.extractable` setting that
+ *   `encryptKey` takes does not apply to it. Each
  *   call picks a fresh random 96-bit IV for the message ciphertext, so
  *   reusing the same `aesKey` across many calls carries the standard
  *   birthday bound for random nonces (collision risk becomes
@@ -60,7 +64,11 @@ export declare function encryptBytes(recipient: RecipientKey, message: Uint8Arra
  * @param message Plaintext to encrypt. A `string` is UTF-8 encoded.
  * @param aesKey Optional key, 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. Each
+ *   `opts.size` bits. A supplied `CryptoKey` MUST be extractable and
+ *   MUST have the `encrypt` usage (the message is encrypted under it
+ *   directly; otherwise this throws `ERR_INVALID_AES_KEY`). It is used
+ *   as-is and never re-imported, so the `opts.extractable` setting that
+ *   `encryptKey` takes does not apply to it. Each
  *   call picks a fresh random 96-bit IV for the message ciphertext, so
  *   reusing the same `aesKey` across many calls carries the standard
  *   birthday bound for random nonces (collision risk becomes
@@ -116,6 +124,20 @@ export declare function decap(enc: Uint8Array, keypair: CryptoKeyPair): Promise<
  *   or cannot encrypt.
  */
 export declare function keyId(key: CryptoKey): Promise<string>;
+/**
+ * Check whether `key` matches a stored `keyId`.
+ *
+ * Compares in constant time over the string. Errors from `keyId`
+ * propagate: a key that cannot be fingerprinted rejects rather than
+ * resolving `false`, so "cannot check" never reads as "wrong key".
+ *
+ * @param key An AES-GCM `CryptoKey` with the `encrypt` usage.
+ * @param expected A `keyId` string recorded earlier.
+ * @returns `true` if `keyId(key)` equals `expected`, else `false`.
+ * @throws {HpkeError} `ERR_INVALID_AES_KEY` if `key` is not an AES-GCM key
+ *   or cannot encrypt.
+ */
+export declare function verifyKeyId(key: CryptoKey, expected: string): Promise<boolean>;
 export declare function i2osp(n: number, len: number): Uint8Array;
 export declare function concat(...arrays: Uint8Array[]): Uint8Array;
 //# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,KAAK,kBAAkB,EAC1B,MAAM,aAAa,CAAA;AAepB;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAClB,SAAS,GACT,aAAa,GACb,UAAU,GACV;IAAE,SAAS,EAAC,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAC,kBAAkB,CAAA;CAAE,CAAA;AAExD;;GAEG;AACH,wBAAsB,QAAQ,CAC1B,GAAG,EAAC,UAAU,EACd,KAAK,EAAC,UAAU,EAChB,SAAS,EAAC,UAAU,GACtB,OAAO,CAAC,UAAU,CAAC,CAcpB;AAED,wBAAsB,QAAQ,CAC1B,GAAG,EAAC,UAAU,EACd,KAAK,EAAC,UAAU,EAChB,UAAU,EAAC,UAAU,GACvB,OAAO,CAAC,UAAU,CAAC,CA2BpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,YAAY,CAC9B,SAAS,EAAC,YAAY,EACtB,OAAO,EAAC,UAAU,GAAC,MAAM,EACzB,MAAM,CAAC,EAAC,SAAS,GAAC,UAAU,GAAC,IAAI,EACjC,IAAI,CAAC,EAAC;IACF,IAAI,CAAC,EAAC,GAAG,GAAC,GAAG,CAAA;IACb,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;CAC1B,GACH,OAAO,CAAC,UAAU,CAAC,CAoBpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACjC,SAAS,EAAC,YAAY,EACtB,OAAO,EAAC,UAAU,GAAC,MAAM,EACzB,MAAM,CAAC,EAAC,SAAS,GAAC,UAAU,GAAC,IAAI,EACjC,IAAI,CAAC,EAAC;IACF,IAAI,CAAC,EAAC,GAAG,GAAC,GAAG,CAAA;IACb,IAAI,CAAC,EAAC,UAAU,GAAC,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAC,kBAAkB,CAAA;CAC/B,GACH,OAAO,CAAC,MAAM,CAAC,CAGhB;AAQD,wBAAsB,IAAI,CAAE,GAAG,EAAC,UAAU,EAAE,IAAI,EAAC,UAAU,GAAE,OAAO,CAAC,UAAU,CAAC,CAS/E;AAiCD,wBAAsB,cAAc,CAChC,OAAO,EAAC,UAAU,EAClB,IAAI,EAAC,UAAU,EACf,KAAK,EAAC,MAAM,EACZ,GAAG,EAAC,UAAU,GAChB,OAAO,CAAC,UAAU,CAAC,CAQpB;AAGD,wBAAsB,aAAa,CAC/B,OAAO,EAAC,UAAU,EAClB,GAAG,EAAC,UAAU,EACd,KAAK,EAAC,MAAM,EACZ,IAAI,EAAC,UAAU,EACf,MAAM,EAAC,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CASpB;AA+BD,wBAAsB,yBAAyB,CAC3C,SAAS,EAAC,YAAY,GACxB,OAAO,CAAC,SAAS,CAAC,CAkDnB;AAmED,wBAAsB,KAAK,CACvB,GAAG,EAAC,SAAS,GACf,OAAO,CAAC;IAAE,YAAY,EAAC,UAAU,CAAC;IAAC,GAAG,EAAC,UAAU,CAAA;CAAE,CAAC,CAarD;AAID,wBAAsB,KAAK,CACvB,GAAG,EAAC,UAAU,EACd,OAAO,EAAC,aAAa,GACvB,OAAO,CAAC,UAAU,CAAC,CAwBpB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,KAAK,CAAE,GAAG,EAAC,SAAS,GAAE,OAAO,CAAC,MAAM,CAAC,CAuC1D;AAKD,wBAAgB,KAAK,CAAE,CAAC,EAAC,MAAM,EAAE,GAAG,EAAC,MAAM,GAAE,UAAU,CAQtD;AAED,wBAAgB,MAAM,CAAE,GAAG,MAAM,EAAC,UAAU,EAAE,GAAE,UAAU,CAUzD"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/dist/util.js

@@ -1381,7 +1381,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,
@@ -1509,6 +1518,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 {
@@ -1523,6 +1538,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
@@ -1575,6 +1591,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));
@@ -1673,37 +1695,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",
@@ -1711,6 +1724,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(
@@ -1721,11 +1751,23 @@ function assertX25519Algorithm(key, context, code2) {
 }
 __name(assertX25519Algorithm, "assertX25519Algorithm");
 async function dh(priv, pub) {
-  const bits = await subtle2.deriveBits(
-    { name: "X25519", public: pub },
-    priv,
-    256
-  );
+  let bits;
+  try {
+    bits = await subtle2.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(
@@ -1778,6 +1820,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 subtle2.importKey(
     "raw",
     enc,
@@ -1820,6 +1879,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;
@@ -1855,6 +1924,7 @@ export {
   keyId,
   labeledExpand,
   labeledExtract,
-  resolveRecipientPublicKey
+  resolveRecipientPublicKey,
+  verifyKeyId
 };
 //# sourceMappingURL=util.js.map