simple-hpke 0.2.0 → 0.3.1

package/dist/util.d.ts

@@ -49,7 +49,7 @@ export declare function encryptBytes(recipient: RecipientKey, message: Uint8Arra
     info?: Uint8Array | string;
 }): Promise<Uint8Array>;
 /**
- * Like `encrypt`, but encodes the envelope bytes to a string — handy for
+ * Like `encrypt`, but encodes the envelope bytes to a string -- handy for
  * transports that carry text (JSON, URLs, headers). Decode with
  * `fromString(...)` (or any matching decoder) and pass the bytes to
  * `decrypt` / `decrypt.asString`. Exposed as `encrypt.asString`.
@@ -85,6 +85,37 @@ export declare function encap(pkR: CryptoKey): Promise<{
     enc: Uint8Array;
 }>;
 export declare function decap(enc: Uint8Array, keypair: CryptoKeyPair): Promise<Uint8Array>;
+/**
+ * A stable fingerprint for an AES-GCM key: the same key bytes always give
+ * the same string, and two different keys effectively never collide.
+ *
+ * Derived from the key's *behavior* rather than its bytes, so it works on
+ * a non-extractable key -- including one rehydrated from IndexedDB, and
+ * the keys `create` / `encryptKey` / `open` return by default. The obvious
+ * implementation, `exportKey('raw')` then SHA-256, would force every such
+ * key to be extractable. HKDF is not an option either: WebCrypto cannot
+ * convert an AES-GCM key into an HKDF key, and `deriveBits` only accepts a
+ * key imported under HKDF, which needs the raw bytes a non-extractable key
+ * withholds. AES-GCM as a PRF is the only primitive such a key still
+ * exposes.
+ *
+ * The derivation is fixed forever (see `src/constants.ts`):
+ *
+ * ```
+ * LABEL = utf8("simple-hpke/keyId/v1")
+ * N     = SHA-256(LABEL)[0..12]        // fixed nonce
+ * C     = AES-GCM(key, N, LABEL)       // ciphertext || 16-byte tag
+ * keyId = base64url(SHA-256(LABEL || C))
+ * ```
+ *
+ * @param key An AES-GCM `CryptoKey` with the `encrypt` usage. It does not
+ *   need to be extractable.
+ * @returns The fingerprint: the full 32-byte digest, base64url, unpadded
+ *   (43 characters).
+ * @throws {HpkeError} `ERR_INVALID_AES_KEY` if `key` is not an AES-GCM key
+ *   or cannot encrypt.
+ */
+export declare function keyId(key: CryptoKey): Promise<string>;
 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;AAYpB;;;;;;;;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,CAcpB;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,CAepB;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;AA8BD,wBAAsB,yBAAyB,CAC3C,SAAS,EAAC,YAAY,GACxB,OAAO,CAAC,SAAS,CAAC,CAiCnB;AA6DD,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,CAiBpB;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":"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"}

package/dist/util.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/index.ts
 var subtle = globalThis.crypto.subtle;
@@ -1320,13 +1335,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);
@@ -1337,11 +1358,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");
@@ -1362,7 +1392,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)`
     );
   }
@@ -1370,7 +1401,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)`
     );
   }
@@ -1384,19 +1416,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"]
   );
 }
@@ -1451,7 +1484,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);
@@ -1463,7 +1499,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) {
@@ -1487,8 +1523,11 @@ 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 };
+  const aesGcmKey = await importAesKey(
+    keyBytes,
+    opts?.extractable ?? false
+  );
+  return { wrapped, key: aesGcmKey };
 }
 __name(encryptKey, "encryptKey");
 
@@ -1518,24 +1557,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;
-  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 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) {
@@ -1601,7 +1654,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})`
     );
   }
@@ -1620,9 +1674,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") {
@@ -1632,17 +1693,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})`
     );
   }
@@ -1656,7 +1728,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?)"
     );
   }
@@ -1695,9 +1768,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,
@@ -1711,6 +1791,35 @@ 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 subtle2.digest("SHA-256", KEY_ID_LABEL)
+  );
+  const nonce = labelHash.slice(0, KEY_ID_NONCE_LENGTH);
+  const ciphertext = new Uint8Array(await subtle2.encrypt(
+    { name: "AES-GCM", iv: nonce },
+    key,
+    KEY_ID_LABEL
+  ));
+  const digest2 = await subtle2.digest(
+    "SHA-256",
+    concat2(KEY_ID_LABEL, ciphertext)
+  );
+  return toString2(new Uint8Array(digest2), "base64url");
+}
+__name(keyId, "keyId");
 function i2osp(n, len) {
   const out = new Uint8Array(len);
   let v = n;
@@ -1743,6 +1852,7 @@ export {
   encryptToString,
   hmac,
   i2osp,
+  keyId,
   labeledExpand,
   labeledExtract,
   resolveRecipientPublicKey