@blamejs/pki 0.6.13 → 0.6.15

package/lib/hpke.js

@@ -28,14 +28,11 @@ var nodeCrypto = require("crypto");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
-// Own-key membership through an operation taken at load. Written out, the question reads two
-// replaceable properties to answer one thing, and here it decides which suite parameters are read.
 var _hasOwn = intrinsic.hasOwn;
 
 var HpkeError = frameworkError.HpkeError;
 function _err(code, message, cause) { return new HpkeError(code, message, cause); }
 
-// ---- I2OSP + byte helpers ----------------------------------------------------
 
 function i2osp(n, len) {
   var b = Buffer.alloc(len);
@@ -49,28 +46,17 @@ function xor(a, b) { var o = Buffer.alloc(a.length); for (var i = 0; i < a.lengt
 var HPKE_V1 = Buffer.from("HPKE-v1", "ascii");
 function L(s) { return Buffer.from(s, "ascii"); }
 
-// ---- registries: the RFC 9180 sec. 7 data tables (Tables 2/3/5) --------------
 
-// KDF: id -> { hash (node name), Nh }.
-// HKDF-SHA384 (0x0002) and DHKEM(P-384) (0x0011) are registered by RFC 9180 sec.
-// 7 but Appendix A / the cited [TestVectors] file ship no known-answer vector for
-// them, so they are omitted here until an authoritative KAT exists. A request for
-// either fails closed as hpke/unknown-suite, because no test vector proves the
-// crypto it would otherwise run. They admit as a one-row addition the moment a
-// KAT lands.
 var KDFS = {
   0x0001: { hash: "sha256", Nh: 32 },
   0x0003: { hash: "sha512", Nh: 64 },
 };
-// AEAD: id -> { cipher (node name), Nk, Nn, Nt } or exportOnly.
 var AEADS = {
   0x0001: { cipher: "aes-128-gcm", Nk: 16, Nn: 12, Nt: 16 },
   0x0002: { cipher: "aes-256-gcm", Nk: 32, Nn: 12, Nt: 16 },
   0x0003: { cipher: "chacha20-poly1305", Nk: 32, Nn: 12, Nt: 16 },
   0xFFFF: { exportOnly: true, Nn: 12 },
 };
-// KEM: id -> DHKEM group descriptor. `group` is the node keygen/import family;
-// `kdf` is the KEM-internal KDF (its ExtractAndExpand); Nsecret = that KDF's Nh.
 var KEMS = {
   0x0010: { kind: "ec", curve: "P-256", nodeCurve: "prime256v1", kdf: 0x0001, Nsecret: 32, Npub: 65 },
   0x0012: { kind: "ec", curve: "P-521", nodeCurve: "secp521r1", kdf: 0x0003, Nsecret: 64, Npub: 133 },
@@ -80,17 +66,11 @@ var KEMS = {
 
 var MODE_BASE = 0x00, MODE_PSK = 0x01, MODE_AUTH = 0x02, MODE_AUTH_PSK = 0x03;
 
-// Format a code point for an error message without assuming it is a number: a
-// missing suiteIds member arrives as undefined, and undefined.toString(16) would
-// crash the very error path meant to report it.
 function _idStr(id) { return typeof id === "number" ? "0x" + id.toString(16) : String(id); }
 function _kem(id) { var s = KEMS[id]; if (!s) throw _err("hpke/unknown-suite", "unsupported KEM id " + _idStr(id)); return s; }
 function _kdf(id) { var s = KDFS[id]; if (!s) throw _err("hpke/unknown-suite", "unsupported KDF id " + _idStr(id)); return s; }
 function _aead(id) { var s = AEADS[id]; if (!s) throw _err("hpke/unknown-suite", "unsupported AEAD id " + _idStr(id)); return s; }
 
-// ---- labeled KDF (RFC 9180 sec. 4): HKDF Extract/Expand SPLIT over HMAC -------
-// suite_id is the caller's ("KEM"||... for the KEM layer, "HPKE"||... for the
-// rest). Extract = HMAC(salt-or-zeros, ikm); Expand = RFC 5869 sec. 2.3 feedback.
 
 function _extract(hash, Nh, salt, ikm) {
   var key = (salt && salt.length) ? salt : Buffer.alloc(Nh);
@@ -100,16 +80,11 @@ function _expand(hash, Nh, prk, info, len) {
   if (len > 255 * Nh) throw _err("hpke/export-length", "requested length " + len + " exceeds 255*Nh");
   var out = [], t = Buffer.alloc(0), n = Math.ceil(len / Nh);
   for (var i = 1; i <= n; i++) {
-    // The feedback input carries the PREVIOUS output block, so each round's concatenation holds
-    // secret material and is cleared once the HMAC has absorbed it.
     var fed = concat([t, info, Buffer.from([i])]);
     t = nodeCrypto.createHmac(hash, prk).update(fed).digest();
     guard.secret.zeroize(fed, HpkeError, "hpke/bad-input", "an expand feedback input");
     out.push(t);
   }
-  // An exact-sized owning buffer, not a VIEW over the joined blocks: this is keying material, and a
-  // caller clearing what it received must not leave the unused tail of the final HMAC block behind
-  // it. The accumulator and each block are cleared here.
   var joined = concat(out);
   var exact = Buffer.alloc(len);
   joined.copy(exact, 0, 0, len);
@@ -118,8 +93,6 @@ function _expand(hash, Nh, prk, info, len) {
   return exact;
 }
 function _labeledExtract(kdf, suiteId, salt, label, ikm) {
-  // The concatenation copies the input keying material (a DH secret or a PSK) into a fresh
-  // buffer, so that copy is cleared once extract has consumed it. The caller still owns .
   var labeled = concat([HPKE_V1, suiteId, L(label), ikm]);
   try { return _extract(kdf.hash, kdf.Nh, salt, labeled); }
   finally { guard.secret.zeroize(labeled, HpkeError, "hpke/bad-input", "the labeled extract input"); }
@@ -128,14 +101,10 @@ function _labeledExpand(kdf, suiteId, prk, label, info, len) {
   return _expand(kdf.hash, kdf.Nh, prk, concat([i2osp(len, 2), HPKE_V1, suiteId, L(label), info]), len);
 }
 
-// ---- KEM key (de)serialization + Diffie-Hellman (node:crypto) ----------------
 
 var OKP_SPKI = { X25519: "302a300506032b656e032100", X448: "3042300506032b656f033900" };
 var OKP_PKCS8 = { X25519: "302e020100300506032b656e04220420", X448: "3046020100300506032b656f043a0438" };
 
-// Deserialize a serialized KEM public key (enc / pkRm / pkSm) into a node
-// KeyObject. EC is an uncompressed 0x04 point (SerializePublicKey, sec. 7.1.1);
-// OKP is the raw curve point. A wrong length / shape fails closed.
 function _importPublic(kem, raw) {
   if (!Buffer.isBuffer(raw) || raw.length !== kem.Npub) {
     throw _err("hpke/bad-key", kem.curve + " public key must be " + kem.Npub + " bytes");
@@ -153,18 +122,13 @@ function _importPublic(kem, raw) {
     throw _err("hpke/bad-key", "invalid " + kem.curve + " public key", e);
   }
 }
-// Serialize a node public KeyObject back to the RFC 9180 wire encoding.
 function _exportPublic(kem, keyObject) {
   var jwk = keyObject.export({ format: "jwk" });
   if (kem.kind === "ec") return concat([Buffer.from([0x04]), _b64u(jwk.x), _b64u(jwk.y)]);
   return _b64u(jwk.x);
 }
-// Node's own JWK export -- decode its canonical base64url coordinates through the
-// guard so the alphabet/canonicality check is the single shared choke point.
 function _b64u(s) { return guard.encoding.base64url(s, null, _err, "hpke/bad-key", "JWK coordinate"); }
 
-// Import a serialized KEM private key (skRm / skEm / skSm) into a node KeyObject,
-// given the matching serialized public key for the EC JWK (or none for OKP).
 function _importPrivate(kem, rawSk, rawPk) {
   try {
     if (kem.kind === "ec") {
@@ -177,11 +141,6 @@ function _importPrivate(kem, rawSk, rawPk) {
     throw _err("hpke/bad-key", "invalid " + kem.curve + " private key", e);
   }
 }
-// The single KEM Diffie-Hellman choke point. node:crypto throws a raw
-// ERR_OSSL_FAILED_DURING_DERIVATION when the peer point is low-order / invalid
-// (an all-zero X25519 shared secret, a point not on the curve). RFC 9180 sec.
-// 4.1: Decap raises an error on DH failure. Surface it as a typed hpke/bad-key
-// so no raw OpenSSL error escapes any encap / decap path.
 function _dh(privateKey, publicKey) {
   try {
     return nodeCrypto.diffieHellman({ privateKey: privateKey, publicKey: publicKey });
@@ -194,34 +153,22 @@ function _generate(kem) {
   return nodeCrypto.generateKeyPairSync(kem.curve.toLowerCase());
 }
 
-// ---- DHKEM (RFC 9180 sec. 4.1) -----------------------------------------------
 
 function _kemSuiteId(kemId) { return concat([L("KEM"), i2osp(kemId, 2)]); }
 function _extractAndExpand(kem, dh, kemContext) {
   var kdf = _kdf(kem.kdf), sid = _kemSuiteId(_kemId(kem));
-  // The extract PRK is a secret intermediate this function allocated: it is as sensitive as the DH
-  // input it summarises, so it is cleared once the expand has consumed it.
   var eaePrk = _labeledExtract(kdf, sid, Buffer.alloc(0), "eae_prk", dh);
   try { return _labeledExpand(kdf, sid, eaePrk, "shared_secret", kemContext, kem.Nsecret); }
   finally { guard.secret.zeroize(eaePrk, HpkeError, "hpke/bad-input", "the KEM extract PRK"); }
 }
 function _kemId(kem) { for (var k in KEMS) if (KEMS[k] === kem) return Number(k); return 0; }
 
-// Encap(pkR) -> { sharedSecret, enc }. An injected ephemeral (skE, pkEnc) makes
-// the KAT deterministic; otherwise a fresh ephemeral is generated.
 function _ephemeral(kem, eph) {
   if (eph) return { skE: _importPrivate(kem, eph.skm, eph.pkm), enc: _buf(eph.pkm) };
   var kp = _generate(kem);
   return { skE: kp.privateKey, enc: _exportPublic(kem, kp.publicKey) };
 }
-// The raw DH output is the KEM's shared secret before extraction: it is this module's allocation
-// and is cleared once _extractAndExpand has consumed it, on every DHKEM arm. In the authenticated
-// arms  builds a THIRD copy holding both DH results, so the concatenation is cleared as
-// well, since clearing only the pieces would leave the joined buffer readable.
 function _wipeDh(dh) { guard.secret.zeroize(dh, HpkeError, "hpke/bad-input", "the KEM shared secret"); }
-// Every agreement happens inside the protected region. In the authenticated modes the second
-// agreement can throw on an attacker-supplied low-order sender key, and a first secret computed
-// outside the region would be left behind on exactly that failure path.
 function _encap(kem, pkR, pkRm, eph) {
   var e = _ephemeral(kem, eph);
   var dh = null;
@@ -259,7 +206,6 @@ function _authDecap(kem, enc, skR, pkRm, pkS, pkSm) {
   } finally { _wipeDh(dh1); _wipeDh(dh2); _wipeDh(dh); }
 }
 
-// ---- key schedule (RFC 9180 sec. 5.1) ----------------------------------------
 
 function _hpkeSuiteId(kemId, kdfId, aeadId) { return concat([L("HPKE"), i2osp(kemId, 2), i2osp(kdfId, 2), i2osp(aeadId, 2)]); }
 
@@ -276,8 +222,6 @@ function _keySchedule(suite, mode, sharedSecret, info, psk, pskId, role) {
   var pskIdHash = _labeledExtract(kdf, sid, Buffer.alloc(0), "psk_id_hash", pskId);
   var infoHash = _labeledExtract(kdf, sid, Buffer.alloc(0), "info_hash", info);
   var ksc = concat([Buffer.from([mode]), pskIdHash, infoHash]);
-  //  is the key schedule's master PRK -- every key below is derived from it, so it is the
-  // most valuable intermediate here and is cleared once the derivations are done.
   var secret = _labeledExtract(kdf, sid, sharedSecret, "secret", psk);
   try {
     var exporterSecret = _labeledExpand(kdf, sid, secret, "exp", ksc, kdf.Nh);
@@ -292,18 +236,11 @@ function _keySchedule(suite, mode, sharedSecret, info, psk, pskId, role) {
   }
 }
 
-// ---- AEAD context (RFC 9180 sec. 5.2 / 5.3) ----------------------------------
 
-// role is "S" (sender: seal only) or "R" (recipient: open only). Sender and
-// recipient derive the same key + base_nonce, so a wrong-direction call would
-// reuse a nonce (RFC 9180 sec. 5.2); export is available to both.
 function Context(suite, key, baseNonce, exporterSecret, role) {
   this._suite = suite; this._key = key; this._baseNonce = baseNonce;
   this._exporterSecret = exporterSecret; this._seq = 0n; this._role = role;
 }
-// Clear the context's key material. The single-shot entry points below build a context, use it once
-// and drop it, so without this the AEAD key, base nonce and exporter secret stay readable for the
-// process lifetime -- the multi-message API hands the context to the caller, who owns its lifetime.
 Context.prototype._dispose = function () {
   guard.secret.zeroizeAll([this._key, this._baseNonce, this._exporterSecret], HpkeError, "hpke/bad-input", "the HPKE context key material");
 };
@@ -340,9 +277,6 @@ Context.prototype.open = function (aad, ct) {
   if (aad && aad.length) d.setAAD(aad);
   d.setAuthTag(ct.subarray(ct.length - aead.Nt));
   var pt;
-  // Through the shared guard so the recovered plaintext is destroyed when the AEAD tag does not
-  // check out (RFC 9180 sec. 5.2 gives open one outcome on failure, and it is not a copy left in
-  // the heap), and so the success path's abandoned intermediate is cleared too.
   try { pt = guard.secret.cipherFinish(d, ct.subarray(0, ct.length - aead.Nt), HpkeError, "hpke/bad-input", "the recovered plaintext"); }
   catch (e) { throw _err("hpke/open-failed", "AEAD authentication failed (RFC 9180 sec. 5.2)", e); }
   this._inc();
@@ -354,7 +288,6 @@ Context.prototype.export = function (exporterContext, len) {
 };
 function _buf(x) { return Buffer.isBuffer(x) ? x : Buffer.from(x || []); }
 
-// ---- suite resolution + setup ------------------------------------------------
 
 function _suite(ids) {
   if (!ids || typeof ids !== "object") throw _err("hpke/unknown-suite", "suiteIds must be an object { kem, kdf, aead } from pki.hpke.suites");
@@ -363,14 +296,9 @@ function _suite(ids) {
   return { kem: kem, kdf: kdf, aead: aead, kemId: kemId, kdfId: kdfId, aeadId: aeadId, suiteId: _hpkeSuiteId(kemId, kdfId, aeadId) };
 }
 
-// A KEM key argument is a node KeyObject or serialized bytes: a public key as a
-// raw buffer (or { pkm }), a private key as { skm, pkm } (raw scalar + public
-// point). A KAT drives the deterministic path via those serialized forms.
 function _recipPublic(suite, pk) {
   if (Buffer.isBuffer(pk)) return { key: _importPublic(suite.kem, pk), pkm: pk };
   if (pk && pk.pkm) return { key: _importPublic(suite.kem, pk.pkm), pkm: pk.pkm };
-  // A node KeyObject: derive its wire form. A null/undefined/invalid value must
-  // fail closed here, so no raw error from node's export escapes upward.
   try {
     return { key: pk, pkm: _exportPublic(suite.kem, pk) };
   } catch (e) {
@@ -380,10 +308,6 @@ function _recipPublic(suite, pk) {
 }
 function _recipPrivate(suite, sk) {
   if (sk && sk.skm) return { key: _importPrivate(suite.kem, sk.skm, sk.pkm), pkm: sk.pkm };
-  // A raw scalar alone cannot be imported (an EC private key needs its public
-  // point for the JWK), so the serialized private form is { skm, pkm }; reject a
-  // bare buffer, and fail any other bad key closed; a raw createPublicKey error
-  // must not escape the setup path.
   if (Buffer.isBuffer(sk)) throw _err("hpke/bad-key", "a serialized private key must be provided as { skm, pkm } (raw scalar + public point), not a bare buffer");
   try {
     var pkm = _exportPublic(suite.kem, nodeCrypto.createPublicKey(sk));
@@ -394,21 +318,6 @@ function _recipPrivate(suite, sk) {
   }
 }
 
-// Resolve and validate the HPKE mode: RFC 9180 sec. 5.1 defines exactly base /
-// psk / auth / auth-psk. An unknown mode must fail closed, never key-schedule
-// with an out-of-registry mode byte.
-// The sender and the recipient read the same option object from OPPOSITE ends, so each direction
-// gets its own table. A shared union recognizes every name at both ends and so accepts the one that
-// cannot do anything there: `senderPublicKey` handed to setupS, or
-// `senderKey` handed to setupR, is silently ignored, which is the exact silence these tables exist
-// to remove, in a wider form. An option that means nothing where it was passed is a misunderstanding
-// worth reporting, and usually a misdirected auth-mode setup.
-//
-// Every one of these narrows or authenticates: a misspelled `psk` leaves a psk-mode setup with no
-// pre-shared key and a misspelled `senderKey` leaves an auth-mode setup unauthenticated, each
-// failing with a message about the field the caller believes they supplied. `eph` is the
-// deterministic-KAT seam and is sender-side only; supplied by mistake it fixes the ephemeral key,
-// which is the one option here whose silent acceptance is catastrophic.
 var _COMMON_KEYS = { mode: 1, info: 1, psk: 1, pskId: 1 };
 function _withCommon(extra) {
   var out = {};
@@ -417,11 +326,11 @@ function _withCommon(extra) {
   return out;
 }
 var _SETUP_S_KEYS = _withCommon({
-  senderKey: 1,          // auth modes: the sender's OWN KEM private key
-  eph: 1,                // test-vector determinism: fixes the ephemeral key this side generates
+  senderKey: 1,
+  eph: 1,
 });
 var _SETUP_R_KEYS = _withCommon({
-  senderPublicKey: 1,    // auth modes: the sender's KEM public key, to authenticate them
+  senderPublicKey: 1,
 });
 function _mode(opts, keys, who) {
   guard.identifier.assertKnownKeys(opts, keys, _err, "hpke/bad-input", function (k) {
@@ -438,8 +347,6 @@ function _mode(opts, keys, who) {
   return mode;
 }
 
-// pki.hpke.suites -- the RFC 9180 sec. 7 registry code points (KEM / KDF / AEAD /
-// MODE), passed to the setup functions to select a ciphersuite (documented in the
 // @module @intro; a data registry, not a callable primitive).
 var suites = {
   KEM: { DHKEM_P256_HKDF_SHA256: 0x0010, DHKEM_P521_HKDF_SHA512: 0x0012, DHKEM_X25519_HKDF_SHA256: 0x0020, DHKEM_X448_HKDF_SHA512: 0x0021 },
@@ -448,8 +355,6 @@ var suites = {
   MODE: { BASE: MODE_BASE, PSK: MODE_PSK, AUTH: MODE_AUTH, AUTH_PSK: MODE_AUTH_PSK },
 };
 
-// setup*S(suiteIds, pkR, opts) -> { enc, context }. opts: { info, psk, pskId,
-// senderKey (auth), eph (KAT determinism) }. setup*R(suiteIds, enc, skR, opts).
 
 /**
  * @primitive pki.hpke.setupS
@@ -528,8 +433,6 @@ function _setupR(ids, enc, skR, opts) {
   } else {
     ss = _decap(kem, _buf(enc), r.key, r.pkm);
   }
-  // The recipient derives this shared secret and never hands it back (unlike setupS, whose caller
-  // receives it and owns it from then on), so it is cleared once the key schedule has consumed it.
   try { return _keySchedule(suite, mode, ss, _buf(opts.info), _buf(opts.psk), _buf(opts.pskId), "R"); }
   finally { guard.secret.zeroize(ss, HpkeError, "hpke/bad-input", "the KEM shared secret"); }
 }
@@ -553,14 +456,9 @@ function _setupR(ids, enc, skR, opts) {
  *   var out = pki.hpke.seal(ids, pkR, {}, Buffer.from("aad"), Buffer.from("msg"));
  */
 function seal(ids, pkR, opts, aad, pt) {
-  // _setupS itself can reject after allocating (an unusable AEAD, a bad psk pairing), so the whole
-  // call is inside the protected region rather than only what follows a successful setup.
   var s = null;
   try {
   s = _setupS(ids, pkR, opts);
-  // The single-shot wrapper returns neither the setup result nor its shared secret, so no caller can
-  // own that buffer -- it is cleared here along with the context. setupS itself still hands both to
-  // its caller, whose lifetime they become.
   return { enc: s.enc, ct: s.context.seal(_buf(aad), _buf(pt)) };
   } finally {
     if (s) {