simple-hpke 0.2.0 → 0.3.3

package/dist/index.d.ts

@@ -1,17 +1,20 @@
-import { type RecipientKey, encryptToString, encryptBytes } from './util';
+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.
  *
  * @param recipient Public key for decryptor
- * @param opts `size` and `info`
- * @returns {{ enc, key }} The wrapped envelope bytes and the generated
+ * @param opts `size`, `info`, and `extractable`
+ * @returns {{ wrapped, key }} The wrapped envelope bytes and the generated
  *   AES-GCM key.
  */
 export declare function create(recipient: RecipientKey, opts?: {
     size?: 128 | 256;
     info?: Uint8Array | string;
+    extractable?: boolean;
 }): Promise<{
-    enc: Uint8Array<ArrayBufferLike>;
+    wrapped: Uint8Array<ArrayBufferLike>;
     key: CryptoKey;
 }>;
 /**
@@ -46,7 +49,7 @@ export declare const decrypt: typeof decryptBytes & {
  *
  * @param keypair The same recipient `CryptoKeyPair` used to `encrypt`.
  * @param message The envelope returned by `encrypt`.
- * @param opts `info` — must match the value passed to `encrypt`.
+ * @param opts `info` -- must match the value passed to `encrypt`.
  * @returns The decrypted plaintext bytes. Use `decrypt.asString` for a string.
  */
 declare function decryptBytes(keypair: CryptoKeyPair, message: Uint8Array, opts?: {
@@ -58,7 +61,7 @@ declare function decryptBytes(keypair: CryptoKeyPair, message: Uint8Array, opts?
  *
  * @param keypair The same recipient `CryptoKeyPair` used to `encrypt`.
  * @param message The envelope returned by `encrypt`.
- * @param opts `info` — must match the value passed to `encrypt`.
+ * @param opts `info` -- must match the value passed to `encrypt`.
  * @returns The decrypted plaintext as a string.
  */
 declare function decryptToString(keypair: CryptoKeyPair, message: Uint8Array, opts?: {
@@ -91,24 +94,28 @@ declare function decryptFromString(keypair: CryptoKeyPair, message: string, opts
  * importing it as an AES-GCM `CryptoKey`. Exposed as `open.raw`.
  *
  * @param keypair The same X25519 `CryptoKeyPair` used to create or encryptKey.
- * @param wrapped The `enc` bytes returned by `create` or `encryptKey`.
- * @param opts `info` — must match the value passed to `create` or `encryptKey`.
+ * @param wrapped The `wrapped` bytes returned by `create` or `encryptKey`.
+ * @param opts `info` -- must match the value passed to `create` or
+ *   `encryptKey`.
  * @returns The recovered key bytes (16 or 32 bytes, matching whatever
  *   was wrapped).
  */
 declare function openRawBytes(keypair: CryptoKeyPair, wrapped: Uint8Array, opts?: {
-    info: Uint8Array | string;
+    info?: Uint8Array | string;
 }): Promise<Uint8Array>;
 /**
  * Recover an AES key that was wrapped with `create` or `encryptKey`.
  *
  * @param keypair The same X25519 `CryptoKeyPair` used to create or encryptKey.
- * @param wrapped The `enc` bytes returned by `create` or `encryptKey`.
- * @param opts `info` — must match the value passed to `create` or `encryptKey`.
- * @returns The recovered AES-GCM `CryptoKey` (extractable).
+ * @param wrapped The `wrapped` bytes returned by `create` or `encryptKey`.
+ * @param opts `info` -- must match the value passed to `create` or
+ *   `encryptKey` -- and `extractable` (default false).
+ * @returns The recovered AES-GCM `CryptoKey`, non-extractable unless
+ *   `opts.extractable` is true.
  */
 declare function openBytes(keypair: CryptoKeyPair, wrapped: Uint8Array, opts?: {
-    info: Uint8Array | string;
+    info?: Uint8Array | string;
+    extractable?: boolean;
 }): Promise<CryptoKey>;
 /**
  * Wrap an AES key to a recipient's public key. `create(...)` calls this
@@ -118,20 +125,26 @@ declare function openBytes(keypair: CryptoKeyPair, wrapped: Uint8Array, opts?: {
  *   `CryptoKeyPair` (its `.publicKey` is used), 32 raw bytes (`Uint8Array`),
  *   or `{ publicKey:string, encoding? }` (encoding defaults to `base64url`).
  * @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
- *   extractable key of `opts.size` bits. A supplied `CryptoKey` MUST be
- *   extractable (its raw bytes are wrapped).
+ *   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) 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) and `info` (bound into the HPKE key schedule; default empty).
- * @returns { enc:Uint8Array, key:CryptoKey } The wrapped envelope bytes
- *   and a usable AES-GCM `CryptoKey`.
+ *   supplied), `info` (bound into the HPKE key schedule; default empty),
+ *   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 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;
     info?: Uint8Array | string;
+    extractable?: boolean;
 }): Promise<{
-    enc: Uint8Array;
+    wrapped: Uint8Array;
     key: CryptoKey;
 }>;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,KAAK,YAAY,EAGjB,eAAe,EACf,YAAY,EAOf,MAAM,QAAQ,CAAA;AAoBf;;;;;;;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;CAC1B,GACH,OAAO,CAAC;IAAE,GAAG,EAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAAC,GAAG,EAAC,SAAS,CAAA;CAAE,CAAC,CAG5D;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,CA6BpB;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;AA0HrB;;;;;;;;;GASG;AACH,iBAAe,YAAY,CACvB,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,UAAU,EAClB,IAAI,CAAC,EAAC;IAAE,IAAI,EAAC,UAAU,GAAC,MAAM,CAAA;CAAE,GAClC,OAAO,CAAC,UAAU,CAAC,CAYpB;AAED;;;;;;;GAOG;AACH,iBAAe,SAAS,CACpB,OAAO,EAAC,aAAa,EACrB,OAAO,EAAC,UAAU,EAClB,IAAI,CAAC,EAAC;IAAE,IAAI,EAAC,UAAU,GAAC,MAAM,CAAA;CAAE,GAClC,OAAO,CAAC,SAAS,CAAC,CAGnB;AAED;;;;;;;;;;;;;;;GAeG;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;CAC1B,GACH,OAAO,CAAC;IAAE,GAAG,EAAC,UAAU,CAAC;IAAC,GAAG,EAAC,SAAS,CAAA;CAAE,CAAC,CA0B3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1283,6 +1283,19 @@ function toString2(array, encoding = "utf8") {
 }
 __name(toString2, "toString");
 
+// src/errors.ts
+var HpkeError = class extends Error {
+  static {
+    __name(this, "HpkeError");
+  }
+  code;
+  constructor(code2, message, opts) {
+    super(message, opts);
+    this.name = "HpkeError";
+    this.code = code2;
+  }
+};
+
 // src/constants.ts
 var KEM_ID = 32;
 var KDF_ID = 1;
@@ -1305,6 +1318,8 @@ var HPKE_SUITE_ID = concat2(
   i2osp(KDF_ID, 2),
   i2osp(AEAD_ID, 2)
 );
+var KEY_ID_LABEL = new TextEncoder().encode("simple-hpke/keyId/v1");
+var KEY_ID_NONCE_LENGTH = 12;
 
 // src/util.ts
 var subtle = globalThis.crypto.subtle;
@@ -1332,24 +1347,44 @@ async function aeadOpen(key, nonce, ciphertext) {
     false,
     ["decrypt"]
   );
-  const pt = await subtle.decrypt(
-    { name: "AES-GCM", iv: nonce },
-    k,
-    ciphertext
-  );
+  let pt;
+  try {
+    pt = await subtle.decrypt(
+      { name: "AES-GCM", iv: nonce },
+      k,
+      ciphertext
+    );
+  } catch (err) {
+    throw new HpkeError(
+      "ERR_DECRYPT_FAILED",
+      "failed to decrypt the wrapped key: wrong keypair, wrong info, or a tampered envelope",
+      { cause: err }
+    );
+  }
   return new Uint8Array(pt);
 }
 __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 { enc, key } = await encryptKey(recipient, aesKey, opts);
+  const { wrapped, key } = await encryptKey(recipient, aesKey, opts);
   const iv = globalThis.crypto.getRandomValues(new Uint8Array(NN));
   const ct = new Uint8Array(await subtle.encrypt(
     { name: "AES-GCM", iv },
     key,
     plaintext
   ));
-  return concat2(i2osp(enc.length, WRAPPED_LEN_PREFIX), enc, iv, ct);
+  return concat2(
+    i2osp(wrapped.length, WRAPPED_LEN_PREFIX),
+    wrapped,
+    iv,
+    ct
+  );
 }
 __name(encryptBytes, "encryptBytes");
 async function encryptToString(recipient, message, aesKey, opts) {
@@ -1415,7 +1450,8 @@ async function exportRawPublic(key) {
 __name(exportRawPublic, "exportRawPublic");
 async function importRawPublic(raw) {
   if (raw.length !== ENC_LENGTH) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_RECIPIENT_KEY",
       `invalid public key length: ${raw.length} bytes (expected ${ENC_LENGTH})`
     );
   }
@@ -1433,44 +1469,83 @@ async function resolveRecipientPublicKey(recipient) {
     return importRawPublic(recipient);
   }
   if (recipient instanceof CryptoKey) {
-    if (recipient.type !== "public") {
-      throw new Error("recipient CryptoKey must be a public key");
-    }
-    assertX25519Algorithm(recipient, "recipient CryptoKey");
-    return recipient;
+    return assertRecipientPublicKey(recipient, "recipient CryptoKey");
   }
   if (typeof recipient.publicKey === "string") {
     const { publicKey, encoding } = recipient;
-    return importRawPublic(fromString2(publicKey, encoding ?? "base64url"));
+    let decoded;
+    try {
+      decoded = fromString2(publicKey, encoding ?? "base64url");
+    } catch (err) {
+      throw new HpkeError(
+        "ERR_INVALID_RECIPIENT_KEY",
+        `recipient publicKey string does not decode as ${encoding ?? "base64url"}`,
+        { cause: err }
+      );
+    }
+    return importRawPublic(decoded);
   }
   const pair = recipient;
   if (pair.publicKey instanceof CryptoKey) {
-    if (pair.publicKey.type !== "public") {
-      throw new Error("recipient keypair publicKey must be a public key");
-    }
-    assertX25519Algorithm(pair.publicKey, "recipient keypair publicKey");
-    return pair.publicKey;
+    return assertRecipientPublicKey(
+      pair.publicKey,
+      "recipient keypair publicKey"
+    );
   }
-  throw new Error("unrecognized recipient key form");
+  throw new HpkeError(
+    "ERR_INVALID_RECIPIENT_KEY",
+    "unrecognized recipient key form"
+  );
 }
 __name(resolveRecipientPublicKey, "resolveRecipientPublicKey");
-function assertX25519Algorithm(key, context) {
+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 Error(
+    throw new HpkeError(
+      code2,
       `${context} must be an X25519 key (got ${key.algorithm.name})`
     );
   }
 }
 __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 Error(
+    throw new HpkeError(
+      "ERR_SMALL_ORDER_KEY",
       "X25519 shared secret is all-zero (small-order public key?)"
     );
   }
@@ -1509,9 +1584,33 @@ async function encap(pkR) {
 __name(encap, "encap");
 async function decap(enc, keypair) {
   if (keypair.privateKey.type !== "private") {
-    throw new Error("keypair.privateKey must be a private key");
+    throw new HpkeError(
+      "ERR_INVALID_KEYPAIR",
+      "keypair.privateKey must be a private key"
+    );
   }
-  assertX25519Algorithm(keypair.privateKey, "keypair.privateKey");
+  assertX25519Algorithm(
+    keypair.privateKey,
+    "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,
@@ -1525,6 +1624,45 @@ async function decap(enc, keypair) {
   return extractAndExpand(dhBytes, kemContext);
 }
 __name(decap, "decap");
+async function keyId(key) {
+  if (key.algorithm.name !== "AES-GCM") {
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
+      `keyId needs an AES-GCM key (got ${key.algorithm.name})`
+    );
+  }
+  if (!key.usages.includes("encrypt")) {
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
+      "keyId needs a key with the 'encrypt' usage"
+    );
+  }
+  const labelHash = new Uint8Array(
+    await subtle.digest("SHA-256", KEY_ID_LABEL)
+  );
+  const nonce = labelHash.slice(0, KEY_ID_NONCE_LENGTH);
+  const ciphertext = new Uint8Array(await subtle.encrypt(
+    { name: "AES-GCM", iv: nonce },
+    key,
+    KEY_ID_LABEL
+  ));
+  const digest2 = await subtle.digest(
+    "SHA-256",
+    concat2(KEY_ID_LABEL, ciphertext)
+  );
+  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;
@@ -1551,8 +1689,8 @@ __name(concat2, "concat");
 // src/index.ts
 var subtle2 = globalThis.crypto.subtle;
 async function create2(recipient, opts) {
-  const { enc, key } = await encryptKey(recipient, null, opts);
-  return { enc, key };
+  const { wrapped, key } = await encryptKey(recipient, null, opts);
+  return { wrapped, key };
 }
 __name(create2, "create");
 var open = Object.assign(openBytes, {
@@ -1567,13 +1705,19 @@ var decrypt = Object.assign(decryptBytes, {
 });
 async function decryptBytes(keypair, message, opts) {
   if (message.byteLength < WRAPPED_LEN_PREFIX) {
-    throw new Error("malformed message: too short");
+    throw new HpkeError(
+      "ERR_MALFORMED_MESSAGE",
+      "malformed message: too short"
+    );
   }
   const wrappedLen = message[0] << 8 | message[1];
   const ivStart = WRAPPED_LEN_PREFIX + wrappedLen;
   const ctStart = ivStart + NN;
   if (message.byteLength < ctStart + AEAD_TAG_LENGTH) {
-    throw new Error("malformed message: too short");
+    throw new HpkeError(
+      "ERR_MALFORMED_MESSAGE",
+      "malformed message: too short"
+    );
   }
   const wrapped = message.slice(WRAPPED_LEN_PREFIX, ivStart);
   const iv = message.slice(ivStart, ctStart);
@@ -1584,11 +1728,20 @@ async function decryptBytes(keypair, message, opts) {
     opts?.info !== void 0 ? { info: opts.info } : void 0
   );
   const key = await importAesKeyDecryptOnly(keyBytes);
-  const pt = await subtle2.decrypt(
-    { name: "AES-GCM", iv },
-    key,
-    ciphertext
-  );
+  let pt;
+  try {
+    pt = await subtle2.decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      ciphertext
+    );
+  } catch (err) {
+    throw new HpkeError(
+      "ERR_DECRYPT_FAILED",
+      "failed to decrypt the message: tampered ciphertext",
+      { cause: err }
+    );
+  }
   return new Uint8Array(pt);
 }
 __name(decryptBytes, "decryptBytes");
@@ -1598,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,
@@ -1609,7 +1771,8 @@ async function decryptFromString(keypair, message, opts) {
 __name(decryptFromString, "decryptFromString");
 function validateKeysize(keysize) {
   if (keysize !== 128 && keysize !== 256) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_KEYSIZE",
       `invalid keysize: ${keysize} (expected 128 or 256)`
     );
   }
@@ -1617,7 +1780,8 @@ function validateKeysize(keysize) {
 __name(validateKeysize, "validateKeysize");
 function validateRawKeyBytes(raw) {
   if (raw.length !== 16 && raw.length !== 32) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
       `invalid aesKey length: ${raw.length} bytes (expected 16 or 32)`
     );
   }
@@ -1631,19 +1795,20 @@ function normalizeInfo(info) {
 __name(normalizeInfo, "normalizeInfo");
 async function exportAesKeyBytes(key) {
   if (!key.extractable) {
-    throw new Error(
+    throw new HpkeError(
+      "ERR_INVALID_AES_KEY",
       "aesKey must be extractable: its raw bytes are what get sealed"
     );
   }
   return new Uint8Array(await subtle2.exportKey("raw", key));
 }
 __name(exportAesKeyBytes, "exportAesKeyBytes");
-async function importAesKey(raw) {
+async function importAesKey(raw, extractable) {
   return subtle2.importKey(
     "raw",
     raw,
     { name: "AES-GCM" },
-    true,
+    extractable,
     ["encrypt", "decrypt"]
   );
 }
@@ -1698,7 +1863,10 @@ async function keySchedule(sharedSecret, info) {
 __name(keySchedule, "keySchedule");
 async function openRawBytes(keypair, wrapped, opts) {
   if (wrapped.byteLength < ENC_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("malformed envelope: too short");
+    throw new HpkeError(
+      "ERR_MALFORMED_ENVELOPE",
+      "malformed envelope: too short"
+    );
   }
   const info = normalizeInfo(opts?.info);
   const enc = wrapped.slice(0, ENC_LENGTH);
@@ -1710,7 +1878,7 @@ async function openRawBytes(keypair, wrapped, opts) {
 __name(openRawBytes, "openRawBytes");
 async function openBytes(keypair, wrapped, opts) {
   const keyBytes = await openRawBytes(keypair, wrapped, opts);
-  return importAesKey(keyBytes);
+  return importAesKey(keyBytes, opts?.extractable ?? false);
 }
 __name(openBytes, "openBytes");
 async function encryptKey(recipient, aesKey, opts) {
@@ -1720,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 {
@@ -1734,15 +1908,22 @@ 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);
-  const aesGcmKey = await importAesKey(keyBytes);
-  return { enc: wrapped, key: aesGcmKey };
+  if (aesKey instanceof CryptoKey) return { wrapped, key: aesKey };
+  const aesGcmKey = await importAesKey(
+    keyBytes,
+    opts?.extractable ?? false
+  );
+  return { wrapped, key: aesGcmKey };
 }
 __name(encryptKey, "encryptKey");
 export {
+  HpkeError,
   create2 as create,
   decrypt,
   encrypt,
   encryptKey,
-  open
+  keyId,
+  open,
+  verifyKeyId
 };
 //# sourceMappingURL=index.js.map