simple-hpke 0.1.5 → 0.3.1

package/dist/constants.d.ts

@@ -11,4 +11,6 @@ export declare const HPKE_V1: Uint8Array<ArrayBuffer>;
 export declare const WRAPPED_LEN_PREFIX = 2;
 export declare const KEM_SUITE_ID: Uint8Array<ArrayBufferLike>;
 export declare const HPKE_SUITE_ID: Uint8Array<ArrayBufferLike>;
+export declare const KEY_ID_LABEL: Uint8Array<ArrayBuffer>;
+export declare const KEY_ID_NONCE_LENGTH = 12;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,MAAM,KAAS,CAAA;AAC5B,eAAO,MAAM,MAAM,IAAS,CAAA;AAC5B,eAAO,MAAM,OAAO,IAAS,CAAA;AAI7B,eAAO,MAAM,OAAO,KAAK,CAAA;AACzB,eAAO,MAAM,EAAE,KAAK,CAAA;AACpB,eAAO,MAAM,EAAE,KAAK,CAAA;AACpB,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,eAAO,MAAM,eAAe,KAAK,CAAA;AAGjC,eAAO,MAAM,SAAS,IAAO,CAAA;AAE7B,eAAO,MAAM,OAAO,yBAAsC,CAAA;AAK1D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAGnC,eAAO,MAAM,YAAY,6BAGxB,CAAA;AAID,eAAO,MAAM,aAAa,6BAKzB,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,MAAM,KAAS,CAAA;AAC5B,eAAO,MAAM,MAAM,IAAS,CAAA;AAC5B,eAAO,MAAM,OAAO,IAAS,CAAA;AAI7B,eAAO,MAAM,OAAO,KAAK,CAAA;AACzB,eAAO,MAAM,EAAE,KAAK,CAAA;AACpB,eAAO,MAAM,EAAE,KAAK,CAAA;AACpB,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,eAAO,MAAM,eAAe,KAAK,CAAA;AAGjC,eAAO,MAAM,SAAS,IAAO,CAAA;AAE7B,eAAO,MAAM,OAAO,yBAAsC,CAAA;AAK1D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAGnC,eAAO,MAAM,YAAY,6BAGxB,CAAA;AAID,eAAO,MAAM,aAAa,6BAKzB,CAAA;AAUD,eAAO,MAAM,YAAY,yBACU,CAAA;AAMnC,eAAO,MAAM,mBAAmB,KAAK,CAAA"}

package/dist/constants.js

@@ -1283,18 +1283,21 @@ 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/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 { wrapped, key } = await encryptKey(recipient, aesKey, opts);
-  return { enc: wrapped, key };
-}
-__name(seal, "seal");
 var open = Object.assign(openBytes, {
   raw: openRawBytes
 });
@@ -1307,13 +1310,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);
@@ -1324,11 +1333,20 @@ async function decryptBytes(keypair, message, opts) {
     opts?.info !== void 0 ? { info: opts.info } : void 0
   );
   const key = await importAesKeyDecryptOnly(keyBytes);
-  const pt = await subtle.decrypt(
-    { name: "AES-GCM", iv },
-    key,
-    ciphertext
-  );
+  let pt;
+  try {
+    pt = await subtle.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");
@@ -1349,7 +1367,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)`
     );
   }
@@ -1357,7 +1376,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)`
     );
   }
@@ -1371,19 +1391,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 subtle.exportKey("raw", key));
 }
 __name(exportAesKeyBytes, "exportAesKeyBytes");
-async function importAesKey(raw) {
+async function importAesKey(raw, extractable) {
   return subtle.importKey(
     "raw",
     raw,
     { name: "AES-GCM" },
-    true,
+    extractable,
     ["encrypt", "decrypt"]
   );
 }
@@ -1438,7 +1459,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);
@@ -1450,7 +1474,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) {
@@ -1474,7 +1498,10 @@ 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);
+  const aesGcmKey = await importAesKey(
+    keyBytes,
+    opts?.extractable ?? false
+  );
   return { wrapped, key: aesGcmKey };
 }
 __name(encryptKey, "encryptKey");
@@ -1505,34 +1532,38 @@ async function aeadOpen(key, nonce, ciphertext) {
     false,
     ["decrypt"]
   );
-  const pt = await subtle2.decrypt(
-    { name: "AES-GCM", iv: nonce },
-    k,
-    ciphertext
-  );
+  let pt;
+  try {
+    pt = await subtle2.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) {
   const plaintext = typeof message === "string" ? new TextEncoder().encode(message) : message;
-  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 { wrapped, key } = await encryptKey(recipient, aesKey, opts);
   const iv = globalThis.crypto.getRandomValues(new Uint8Array(NN));
   const ct = new Uint8Array(await subtle2.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) {
@@ -1598,7 +1629,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})`
     );
   }
@@ -1617,9 +1649,16 @@ async function resolveRecipientPublicKey(recipient) {
   }
   if (recipient instanceof CryptoKey) {
     if (recipient.type !== "public") {
-      throw new Error("recipient CryptoKey must be a public key");
+      throw new HpkeError(
+        "ERR_INVALID_RECIPIENT_KEY",
+        "recipient CryptoKey must be a public key"
+      );
     }
-    assertX25519Algorithm(recipient, "recipient CryptoKey");
+    assertX25519Algorithm(
+      recipient,
+      "recipient CryptoKey",
+      "ERR_INVALID_RECIPIENT_KEY"
+    );
     return recipient;
   }
   if (typeof recipient.publicKey === "string") {
@@ -1629,17 +1668,28 @@ async function resolveRecipientPublicKey(recipient) {
   const pair = recipient;
   if (pair.publicKey instanceof CryptoKey) {
     if (pair.publicKey.type !== "public") {
-      throw new Error("recipient keypair publicKey must be a public key");
+      throw new HpkeError(
+        "ERR_INVALID_RECIPIENT_KEY",
+        "recipient keypair publicKey must be a public key"
+      );
     }
-    assertX25519Algorithm(pair.publicKey, "recipient keypair publicKey");
+    assertX25519Algorithm(
+      pair.publicKey,
+      "recipient keypair publicKey",
+      "ERR_INVALID_RECIPIENT_KEY"
+    );
     return pair.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 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})`
     );
   }
@@ -1653,7 +1703,8 @@ async function dh(priv, pub) {
   );
   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?)"
     );
   }
@@ -1692,9 +1743,16 @@ 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"
+  );
   const pkE = await subtle2.importKey(
     "raw",
     enc,
@@ -1753,6 +1811,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;
 export {
   AEAD_ID,
   AEAD_TAG_LENGTH,
@@ -1762,6 +1822,8 @@ export {
   KDF_ID,
   KEM_ID,
   KEM_SUITE_ID,
+  KEY_ID_LABEL,
+  KEY_ID_NONCE_LENGTH,
   MODE_BASE,
   NK,
   NN,