@blamejs/pki 0.5.7 → 0.5.8

package/lib/cms-decrypt.js

@@ -6,10 +6,10 @@
 // @primitive pki.cms.decrypt block live in cms-verify.js, which re-exports this function.
 //
 // CMS EnvelopedData / AuthEnvelopedData / EncryptedData decryption (RFC 5652/5083/5084/3560/5753/
-// 8418/9629/9936/3211/8018), the consuming side of pki.cms.encrypt. Three stages behind ONE
-// oracle-free choke point: (1) SELECT the recipient (identifier matching -- typed + distinct),
-// (2) ACQUIRE the CEK (per-arm unwrap/decap/derive), (3) OPEN the content (AEAD verify / CBC
-// decrypt+unpad). Every secret-dependent failure in stages 2-3 collapses to the SINGLE uniform
+// 8418/9629/9936/3211/8018), the consuming side of pki.cms.encrypt. Three stages behind one
+// oracle-free choke point: (1) select the recipient (identifier matching, typed + distinct),
+// (2) acquire the CEK (per-arm unwrap/decap/derive), (3) open the content (AEAD verify / CBC
+// decrypt+unpad). Every secret-dependent failure in stages 2-3 collapses to the single uniform
 // verdict `cms/decrypt-failed` (Bleichenbacher / EFAIL / PWRI-check-byte oracle freedom); the
 // ktri v1.5 arm substitutes a random CEK on any decode fault (RFC 3218 implicit rejection) so its
 // failure emerges at stage 3 identically to every other bad-key path.
@@ -32,7 +32,7 @@ var KEM_CT_LENGTHS = schemaCms.KEM_CT_LENGTHS;
 
 function O(n) { return oid.byName(n); }
 function _err(code, message, cause) { return new CmsError(code, message, cause); }
-// The ONE uniform secret-dependent-failure verdict. No cause chaining that distinguishes the site.
+// The single uniform secret-dependent-failure verdict. No cause chaining that distinguishes the site.
 function _fail() { return new CmsError("cms/decrypt-failed", "the CMS content could not be decrypted (uniform by design -- padding / integrity / key-unwrap failures are indistinguishable to defeat oracles)"); }
 
 var CONTENT_KEYBITS = pbes2.CONTENT_KEYBITS; // content-encryption OID -> key bits (the shared PBES2 table)
@@ -50,13 +50,31 @@ async function decrypt(input, keyMaterial, opts) {
   return decryptEnvelopedData(parsed, keyMaterial, opts, ct);
 }
 
-// The post-parse decrypt of an ALREADY-PARSED EnvelopedData / AuthEnvelopedData: select a recipient, acquire
-// the CEK, open the content -- oracle-free (every secret-dependent failure collapses to cms/decrypt-failed).
-// @internal -- NOT re-exported on pki.cms. Taking the parsed structure (rather than DER) is a DELIBERATE seam
-// for a sibling composer that already holds a strictly-walked content node it must NOT re-serialize/re-parse:
+// The post-parse decrypt of an already-parsed EnvelopedData / AuthEnvelopedData: select a recipient, acquire
+// the CEK, open the content, oracle-free (every secret-dependent failure collapses to cms/decrypt-failed).
+// @internal -- not re-exported on pki.cms. Taking the parsed structure in place of DER is a deliberate seam
+// for a sibling composer that already holds a strictly-walked content node it must not re-serialize/re-parse:
 // pki.pkcs12.open drives this off the pkcs12 parser's walkEnvelopedData result so an RFC 7292 privacy safe
-// whose EnvelopedData is BER-encoded (indefinite lengths, some NSS output -- accepted by the pkcs12 parser)
-// opens without hitting the public decrypt()'s strict-DER re-parse. Callers pass a TRUSTED parse result only.
+// whose EnvelopedData is BER-encoded (indefinite lengths, some NSS output the pkcs12 parser accepts)
+// opens without hitting the public decrypt()'s strict-DER re-parse. Callers pass a trusted parse result only.
+// `authenticated` answers a question about the content and the key that opened it. It
+// cannot answer the question an operator hears in the word -- who sent this -- and no
+// recipient type this toolkit supports authenticates an individual originator: a ktri or
+// ephemeral-static kari message is minted by anyone holding the recipient's PUBLIC key,
+// and a password or KEK message is minted by any co-recipient sharing the secret. The
+// origin question therefore gets its own field instead of being left to the reader's
+// inference. originatorInfo rides outside the AEAD's authenticated data, so it is a hint
+// the sender chose, never evidence, and it is surfaced saying so rather than dropped.
+// Every verdict this module returns carries all three, including the unauthenticated
+// ciphers: a field present on some returns and absent on others is read as a capability
+// difference, and the caller cannot tell "no origin" from "this path forgot to say".
+function _originFields(res, authenticatedBy, originatorInfo) {
+  res.authenticatedBy = authenticatedBy || null;
+  res.originAuthenticated = false;
+  res.originatorInfo = originatorInfo || null;
+  return res;
+}
+
 async function decryptEnvelopedData(parsed, keyMaterial, opts, contentTypeName) {
   opts = opts || {};
   if (keyMaterial == null || typeof keyMaterial !== "object") throw _err("cms/bad-input", "decrypt requires a key-material object");
@@ -64,8 +82,8 @@ async function decryptEnvelopedData(parsed, keyMaterial, opts, contentTypeName)
   var recips = parsed.recipientInfos || [];
   var candidates = _selectCandidates(recips, keyMaterial, opts);   // stage 1 (typed, distinct)
   var eci = parsed.encryptedContentInfo;
-  // The content cipher's MODE is a structural property of the message -- readable from the algorithm
-  // identifier with no key material at all -- so it is decided HERE, before any recipient is tried.
+  // The content cipher's mode is a structural property of the message, readable from the algorithm
+  // identifier with no key material at all, so it is decided here, before any recipient is tried.
   // Deciding it per candidate would make a structural verdict depend on key acquisition succeeding
   // first: several password or KEK recipients can match the same key material, so the distinct
   // cms/unsupported-algorithm would be swallowed by the ambiguous-candidate loop below and the caller
@@ -78,18 +96,18 @@ async function decryptEnvelopedData(parsed, keyMaterial, opts, contentTypeName)
     try {
       _assertSupported(candidates[ci].ri, keyMaterial);                    // distinct-code reject (MQV / non-KEM ori)
       var cek = await _acquireCek(candidates[ci].ri, keyMaterial, opts);   // stage 2 (uniform)
-      // The recovered CEK is cleared only AFTER the content is open -- it is the key the next stage
-      // needs, so an earlier wipe would break decryption rather than protect it. The returned object
+      // The recovered CEK is cleared only after the content is open: it is the key the next stage
+      // needs, so an earlier wipe would break decryption instead of protecting it. The returned object
       // is built before the `finally` runs and holds the plaintext, not the key.
       try {
         var content = await _openContent(parsed, eci, cek, ct);            // stage 3 (uniform)
-        return {
+        return _originFields({
           content: content,
           contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType,
           recipientType: candidates[ci].ri.type, recipientIndex: candidates[ci].index,
           contentEncryptionAlgorithm: eci.contentEncryptionAlgorithm.name || eci.contentEncryptionAlgorithm.oid,
           authenticated: ct === "authEnvelopedData",
-        };
+        }, ct === "authEnvelopedData" ? "content-encryption-key" : null, parsed.originatorInfo);
       } finally {
         guard.secret.zeroize(cek, CmsError, "cms/bad-input", "the recovered content-encryption key");
       }
@@ -101,7 +119,7 @@ async function decryptEnvelopedData(parsed, keyMaterial, opts, contentTypeName)
 }
 
 function _parse(input) {
-  // Always drive the strict parser over caller-supplied bytes -- an arbitrary object that merely
+  // Always drive the strict parser over caller-supplied bytes: an arbitrary object that merely
   // carries a contentTypeName is not a trusted parse result and must not bypass DER validation.
   return schemaCms.parse(_toDer(input));
 }
@@ -111,7 +129,7 @@ function _toDer(input) {
   throw _err("cms/bad-input", "input must be a DER Buffer, Uint8Array, or PEM string");
 }
 
-// ---- stage 1: recipient selection (NOT secret-dependent) -------------------
+// ---- stage 1: recipient selection (not secret-dependent) -------------------
 // Returns every recipient the key material may target. An explicit recipientIndex or an rid match
 // yields exactly one; unlabelled pwri / kekri recipients yield all matches for the caller to try.
 function _selectCandidates(recips, km, opts) {
@@ -198,12 +216,12 @@ async function _acquireCek(ri, km, opts) {
     if (ri.type === "pwri") return await _pwriCek(ri, km, opts);
     if (ri.type === "ori") return await _kemriCek(ri, km);
   } catch (e) {
-    // Structural / resource / config faults keep their own code -- only SECRET-DEPENDENT failures
+    // Structural / resource / config faults keep their own code; only secret-dependent failures
     // (a bad unwrap, a wrong key, a padding fault) collapse to the uniform verdict.
     if (e instanceof CmsError && _passThrough[e.code]) throw e;
     throw _fail();
   }
-  // Coverage residual: unreachable -- _selectCandidates only returns one of the five handled types.
+  // Coverage residual: unreachable, since _selectCandidates only returns one of the five handled types.
   throw _err("cms/unsupported-recipient-type", "unsupported recipient type " + ri.type);
 }
 
@@ -229,7 +247,7 @@ async function _ktriCek(ri, km) {
       }
     }
     // Coverage residual: reachable only from a hostile message (our encrypt emits only OAEP; OpenSSL
-    // emits OAEP or rsaEncryption) -- a fail-closed reject the fuzz harness exercises.
+    // emits OAEP or rsaEncryption): a fail-closed reject the fuzz harness exercises.
     throw _err("cms/unsupported-algorithm", "unsupported ktri keyEncryptionAlgorithm " + kea.oid);
   } finally {
     _releaseKeyDer(k);
@@ -242,7 +260,7 @@ async function _kariCek(ri, km) {
   // otherwise be an unprotected window, and it is not a narrow one: reading the wrap algorithm, the
   // originator's key, the recipient's certificate and the matching RecipientEncryptedKey all parse
   // attacker-supplied structure and all throw on malformed input. A message crafted to fail any one
-  // of them would be a way to leave the key copy in the heap -- the exact outcome the wipe is for.
+  // of them would be a way to leave the key copy in the heap, the exact outcome the wipe is for.
   var k = _normKeyDer(km.key);
   // The agreement secret and the KEK derived from it are both allocated here; one `finally` clears
   // whichever branch produced them, including when the unwrap below throws on a tampered key.
@@ -253,7 +271,7 @@ async function _kariCek(ri, km) {
     var wrapAlg = _kariWrap(kea);
     var scheme = kea.oid;
     var origSpki = _originatorSpki(ri.originator);
-    // Unwrap THIS recipient's RecipientEncryptedKey (matched by rid), not element 0 -- a kari may list
+    // Unwrap this recipient's own RecipientEncryptedKey (matched by rid), not element 0; a kari may list
     // several recipients under one ephemeral key.
     var rek = (km.cert != null && _kariRekFor(ri, x509.parse(_normCertDer(km.cert)))) || ri.recipientEncryptedKeys[0];
     var kekBytes = WRAP_KEK_LENGTHS[wrapAlg.oid];
@@ -266,8 +284,8 @@ async function _kariCek(ri, km) {
       mz = Buffer.from(await subtle.deriveBits({ name: mont.name, public: origPub }, recipPriv, null));
       if (mz.every(function (x) { return x === 0; })) throw _fail();
       var mzKey = await subtle.importKey("raw", mz, { name: "HKDF" }, false, ["deriveBits"]);
-      // RFC 8418 sec. 2.2: a present ukm is used BOTH as the HKDF salt AND as the ECC-CMS-SharedInfo
-      // entityUInfo -- mirror the producer so both sides derive the same KEK as a conformant peer.
+      // RFC 8418 sec. 2.2: a present ukm serves as both the HKDF salt and the ECC-CMS-SharedInfo
+      // entityUInfo, so mirror the producer and both sides derive the same KEK as a conformant peer.
       kek = Buffer.from(await subtle.deriveBits({ name: "HKDF", hash: mont.hkdf, salt: ukm || Buffer.alloc(0), info: _eccSharedInfo(wrapAlg.name, ukm, kekBytes) }, mzKey, kekBytes * 8));
     } else {
       // RFC 5753 sec. 7.1 permits the originator EC key to omit its curve parameters, inheriting the
@@ -313,11 +331,11 @@ async function _pwriCek(ri, km, opts) {
   // override a built-in name, and a name-matched mode check would then admit a non-CBC inner cipher.
   if (!innerBits || CONTENT_MODE[innerOid] !== "cbc") throw _err("cms/unsupported-algorithm", "unsupported pwri inner cipher");
   var iv = asn1.read.octetString(inner.children[1]);
-  // The derived KEK is ours and is cleared once the unwrap has consumed it -- on the failing path
+  // The derived KEK is ours and is cleared once the unwrap has consumed it, on the failing path
   // too, which is the one an attacker induces by tampering with the wrapped key. The caller's
   // password is not touched: passwordBytes returns a caller-supplied Buffer as-is.
-  // A string / Uint8Array password is encoded into a buffer THIS toolkit allocated -- a credential
-  // copy -- so it is cleared once the derivation has consumed it. A caller-supplied Buffer is
+  // A string / Uint8Array password is encoded into a buffer this toolkit allocated, a credential
+  // copy, so it is cleared once the derivation has consumed it. A caller-supplied Buffer is
   // borrowed and left intact.
   var pw = pbes2.passwordBytesOwned(km.password, _err, "cms");
   var kek;
@@ -336,18 +354,18 @@ async function _kemriCek(ri, km) {
   var wcName = _mlkemName(k.kem.oid);
   if (!wcName) throw _err("cms/unsupported-algorithm", "unsupported KEM " + k.kem.oid);
   // Honor the declared key-derivation function: we implement HKDF-SHA256 (RFC 9629), so a message
-  // naming any other KDF is rejected rather than silently derived with the wrong one.
+  // naming any other KDF is rejected, never silently derived with the wrong one.
   if (k.kdf.oid !== O("hkdfWithSha256")) throw _err("cms/unsupported-algorithm", "unsupported KEM key-derivation " + k.kdf.oid);
   var wantCt = KEM_CT_LENGTHS[k.kem.oid];
   var kemct = k.kemct;
-  // Coverage residual (both _fail re-checks): unreachable via a parsed message -- the strict parser
+  // Coverage residual (both _fail re-checks): unreachable via a parsed message, because the strict parser
   // already rejects a wrong kemct length (cms/bad-kem-ciphertext) and a kekLength != wrap size
   // (cms/kek-length-mismatch). These are defense-in-depth on the consumer path (M32 / M29).
-  if (wantCt && kemct.length !== wantCt) throw _fail();          // M32: exact ct length BEFORE decap
+  if (wantCt && kemct.length !== wantCt) throw _fail();          // M32: exact ct length before decap
   var kekBytes = Number(k.kekLength);
   var wrapAlg = k.wrap;
   if (WRAP_KEK_LENGTHS[wrapAlg.oid] !== kekBytes) throw _fail(); // M29 re-check on the consumer path
-  // The decapsulation key copy is released as soon as the engine has imported it -- the import is
+  // The decapsulation key copy is released as soon as the engine has imported it: the import is
   // the only thing that reads it, so its lifetime does not need to span the decapsulation below.
   var keyCopy = _normKeyDer(km.key);
   var priv;
@@ -366,8 +384,8 @@ async function _kemriCek(ri, km) {
     return await _aesKwUnwrap(kek, k.encryptedKey);
   } finally {
     // NIST SP 800-227 RS5 / sec. 4.2 and RFC 9629 sec. 7: the shared secret and the KEK it derives
-    // are destroyed as soon as they stop being needed. In a `finally`, so an unwrap that FAILS --
-    // the common case under a wrong key or a tampered encryptedKey -- leaves nothing behind either;
+    // are destroyed as soon as they stop being needed. In a `finally`, so an unwrap that fails
+    // (the common case under a wrong key or a tampered encryptedKey) leaves nothing behind either;
     // a wipe on the success path alone would keep the secret exactly when an attacker made it fail.
     // Only buffers allocated here are wiped: km.key, the message bytes and the returned CEK are the
     // caller's or the caller's to consume.
@@ -381,7 +399,7 @@ async function _kemriCek(ri, km) {
 // The declared cipher MODE must match the container's authentication model: an AEAD cipher belongs in
 // AuthEnvelopedData and a plain CBC cipher in EnvelopedData (RFC 5083 sec. 2.1 / RFC 5084 sec. 3). Key
 // length alone does not separate them, so without this an EnvelopedData naming AES-GCM was opened as
-// unauthenticated CBC while the result still reported the AEAD algorithm -- telling the caller the
+// unauthenticated CBC while the result still reported the AEAD algorithm, telling the caller the
 // content was authenticated when nothing had authenticated it. The mirror case dereferenced AEAD
 // parameters the parser leaves null for a non-AEAD algorithm, faulting instead of failing closed.
 // An unresolvable OID is left to _openContent, which names it as the unsupported algorithm it is.
@@ -403,10 +421,10 @@ async function _openContent(parsed, eci, cek, ct) {
   // A null CEK (v1.5 implicit rejection) or a wrong-length CEK -> a fresh random key of the right
   // length, so the failure surfaces here as the uniform verdict, never earlier.
   //
-  // The substitute is THIS function's allocation, so this function clears it: reassigning the
+  // The substitute is this function's own allocation, so this function clears it: reassigning the
   // parameter does not change the caller's variable, so the caller's `finally` would wipe the
   // original null / wrong-length value and leave the substitute behind. It is held separately
-  // rather than wiping `cek` here, because on the normal path `cek` is the CALLER's recovered key
+  // and `cek` is left alone here, because on the normal path `cek` is the caller's recovered key
   // and is still in use after this returns.
   var substitute = null;
   if (cek == null || cek.length !== keyBits / 8) { substitute = nodeCrypto.randomBytes(keyBits / 8); cek = substitute; }
@@ -426,7 +444,7 @@ async function _openContent(parsed, eci, cek, ct) {
   }
 }
 function _gcmOpen(cek, nonce, ct, tag, aad, keyBits, icvLen) {
-  // Coverage residual: unreachable via a parsed message -- the strict parser rejects any
+  // Coverage residual: unreachable via a parsed message, since the strict parser rejects any
   // AuthEnvelopedData whose mac length != aes-ICVlen (cms/mac-length-mismatch) before we get here.
   if (!tag || tag.length !== icvLen) throw _fail();
   var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-gcm", cek, nonce, { authTagLength: icvLen });
@@ -447,14 +465,14 @@ async function _decryptEncryptedData(parsed, km, opts) {
   var cek = guard.bytes.view(km.cek, CmsError, "cms/bad-input", "cek");
   if (cek.length !== keyBits / 8) throw _err("cms/bad-input", "the supplied cek length does not match the content algorithm");
   var iv = asn1.read.octetString(asn1.decode(alg.parameters));
-  try { return { content: pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "cek", recipientIndex: -1, contentEncryptionAlgorithm: alg.name || alg.oid, authenticated: false }; }
+  try { return _originFields({ content: pbes2.cbcDecrypt(cek, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "cek", recipientIndex: -1, contentEncryptionAlgorithm: alg.name || alg.oid, authenticated: false }, null, null); }
   catch (_e) { throw _fail(); }
 }
 async function _decryptPbes2(parsed, eci, km, opts) {
   if (km.password == null) throw _err("cms/bad-input", "this EncryptedData needs a { password }");
   // The PBES2 parameters are attacker-controlled structure the strict parser surfaces raw (PBES2 is
   // not an AEAD it validates): parse them behind a structural guard so a malformed shape is a typed
-  // cms/bad-input, never a raw dereference fault (the PBES2 structure is public -- not a decrypt oracle).
+  // cms/bad-input, never a raw dereference fault (the PBES2 structure is public, not a decrypt oracle).
   var kdf, encOid, iv, pb;
   try {
     var params = pbes2.seqChildren(eci.contentEncryptionAlgorithm.parameters, 2, "PBES2 parameters", _err, "cms");
@@ -472,14 +490,14 @@ async function _decryptPbes2(parsed, eci, km, opts) {
   if (!keyBits) throw _err("cms/unsupported-algorithm", "unsupported PBES2 content cipher " + encOid);
   // The password-derived content key is ours; the caller's password buffer is not (passwordBytes
   // passes a supplied Buffer straight through) and is left intact.
-  // A string / Uint8Array password is encoded into a buffer THIS toolkit allocated -- a credential
-  // copy -- so it is cleared once the derivation has consumed it. A caller-supplied Buffer is
+  // A string / Uint8Array password is encoded into a buffer this toolkit allocated, a credential
+  // copy, so it is cleared once the derivation has consumed it. A caller-supplied Buffer is
   // borrowed and left intact.
   var pwE = pbes2.passwordBytesOwned(km.password, _err, "cms");
   var key;
   try { key = nodeCrypto.pbkdf2Sync(pwE.bytes, pb.salt, pb.iterations, keyBits / 8, pb.prfNode); }
   finally { if (pwE.owned) guard.secret.zeroize(pwE.bytes, CmsError, "cms/bad-input", "the password encoding"); }
-  try { return { content: pbes2.cbcDecrypt(key, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "password", recipientIndex: -1, contentEncryptionAlgorithm: oid.name(encOid) || encOid, authenticated: false }; }
+  try { return _originFields({ content: pbes2.cbcDecrypt(key, iv, eci.encryptedContent, keyBits), contentType: eci.contentType, contentTypeName: oid.name(eci.contentType) || eci.contentType, recipientType: "password", recipientIndex: -1, contentEncryptionAlgorithm: oid.name(encOid) || encOid, authenticated: false }, null, null); }
   catch (_e) { throw _fail(); }
   finally { guard.secret.zeroize(key, CmsError, "cms/bad-input", "the password-derived content-encryption key"); }
 }
@@ -487,19 +505,19 @@ async function _decryptPbes2(parsed, eci, km, opts) {
 // ---- shared helpers (mirror cms-encrypt's builders) ------------------------
 async function _aesKwUnwrap(kek, wrapped) {
   var kekKey = await subtle.importKey("raw", kek, { name: "AES-KW" }, false, ["unwrapKey"]);
-  // Import the unwrapped key as HMAC, not AES-CBC: this function EXPORTS to raw bytes, so the CryptoKey
-  // type is transient and the exported bytes are identical for an AES CEK -- but HMAC accepts any wrap
+  // Import the unwrapped key as HMAC, not AES-CBC: this function exports to raw bytes, so the CryptoKey
+  // type is transient and the exported bytes are identical for an AES CEK, while HMAC accepts any wrap
   // length, so an AuthenticatedData MAC key that is not 16/24/32 octets (e.g. a 64-octet HMAC-SHA-512
   // key from another implementation) is recovered instead of rejected before the MAC is even checked.
   var raw = await subtle.unwrapKey("raw", wrapped, kekKey, { name: "AES-KW" }, { name: "HMAC", hash: "SHA-256" }, true, ["sign"]);
   // exportKey allocates an ArrayBuffer holding the unwrapped key; the Buffer below is a copy of it,
   // and the original would otherwise stay readable with nothing referencing it. That is a
   // controllable allocation, not one of the runtime-internal copies the best-effort caveat covers.
-  // Only the intermediate is wiped -- the returned Buffer IS the key the caller must use to open
-  // the content, so wiping it here would destroy the result rather than protect it.
+  // Only the intermediate is wiped: the returned Buffer is the key the caller must use to open
+  // the content, so wiping it here would destroy the result instead of protecting it.
   var rawAb = await subtle.exportKey("raw", raw);
   try {
-    // An explicit COPY, not Buffer.from(arrayBuffer) -- that form returns a VIEW sharing the
+    // An explicit copy, not Buffer.from(arrayBuffer): that form returns a view sharing the
     // ArrayBuffer's memory, so wiping the intermediate below would zero the key being returned.
     var view = new Uint8Array(rawAb);
     var out = Buffer.alloc(view.length);
@@ -522,14 +540,14 @@ function _kemOtherInfo(wrapName, kekBytes, ukm) {
   return b.sequence(kids);
 }
 // RFC 3211 double-CBC unwrap (M26): decrypt pass 2 (IV = last block of pass 1), then pass 1
-// (IV = first block), validate the count + complement check bytes -- uniform failure on mismatch.
+// (IV = first block), validate the count + complement check bytes, with uniform failure on mismatch.
 function _pwriUnwrap(kek, wrapped, iv, keyBits) {
   var blk = 16, alg = "aes-" + keyBits + "-cbc";
   if (wrapped.length < 2 * blk || wrapped.length % blk !== 0) throw _fail();
   var n = wrapped.length;
   // pass2 = CBC(kek, iv2 = pass1[last block], pass1). Recover pass1's last block by decrypting the
-  // last ciphertext block (ECB) and XORing the previous ciphertext block -- a standard CBC last-
-  // block decrypt that needs no IV -- then CBC-decrypt pass2 under that recovered iv2 to get pass1.
+  // last ciphertext block (ECB) and XORing the previous ciphertext block, a standard CBC last-
+  // block decrypt that needs no IV, then CBC-decrypt pass2 under that recovered iv2 to get pass1.
   var ecb = nodeCrypto.createDecipheriv("aes-" + keyBits + "-ecb", kek, Buffer.alloc(0)); ecb.setAutoPadding(false);
   var lastDec = Buffer.concat([ecb.update(wrapped.subarray(n - blk)), ecb.final()]);
   var iv2 = Buffer.alloc(blk);
@@ -538,7 +556,7 @@ function _pwriUnwrap(kek, wrapped, iv, keyBits) {
   var pass1 = Buffer.concat([d1.update(wrapped), d1.final()]);
   var d2 = nodeCrypto.createDecipheriv(alg, kek, iv); d2.setAutoPadding(false);
   // body is the recovered plaintext block: it holds the CEK. The caller receives an independent
-  // COPY, so the block is cleared on every exit -- including the two validation rejects, which are
+  // copy, so the block is cleared on every exit, including the two validation rejects, which are
   // the paths an attacker induces by tampering with the wrapped key.
   var body = Buffer.concat([d2.update(pass1), d2.final()]);
   try {
@@ -553,7 +571,7 @@ function _pwriUnwrap(kek, wrapped, iv, keyBits) {
     guard.secret.zeroizeAll([body, pass1], CmsError, "cms/bad-input", "the PWRI plaintext block");
   }
 }
-// Coverage residual (the unsupported-algorithm throw arm of each lookup below -- _hashW3c,
+// Coverage residual (the unsupported-algorithm throw arm of each lookup below: _hashW3c,
 // _x963Hash, and _originatorSpki that follow): reachable only from a fully well-formed recipient that
 // names an inner algorithm we do not implement (a non-registry OAEP hash / kari scheme / originator
 // form). The producer never emits one; the fuzz harness (fuzz/cms-decrypt.fuzz.js) drives these arms
@@ -572,8 +590,8 @@ function _oaepHashFromParams(paramsBytes) {
       mgfHash = _hashW3c(asn1.read.oid(mg.children[1].children[0]));
     } else if (ch.tagNumber === 2) { label = asn1.read.octetString(ch.children[0].children[1]); }             // pSourceAlgorithm [2]
   });
-  // WebCrypto RSA-OAEP ties the MGF1 hash to the OAEP hash and supports only an empty label -- reject,
-  // rather than silently ignore, any parameter set we cannot faithfully honor.
+  // WebCrypto RSA-OAEP ties the MGF1 hash to the OAEP hash and supports only an empty label, so any
+  // parameter set we cannot faithfully honor is rejected, never silently ignored.
   if (mgfHash != null && mgfHash !== hashName) throw _err("cms/unsupported-algorithm", "the OAEP MGF1 hash must equal the OAEP hash");
   if (label != null && label.length > 0) throw _err("cms/unsupported-algorithm", "a non-empty OAEP label is not supported");
   return hashName;
@@ -593,7 +611,7 @@ function _kariWrap(kea) {
 }
 function _originatorSpki(originator) {
   // originator OriginatorIdentifierOrKey CHOICE; we require originatorKey [1] (RFC 5753 MUST for
-  // ephemeral-static). The parser surfaces { form, value:{ algorithm, publicKey } } -- reconstruct
+  // ephemeral-static). The parser surfaces { form, value:{ algorithm, publicKey } }, so reconstruct
   // the SPKI (SEQUENCE { algorithm, subjectPublicKey BIT STRING }) for importKey.
   if (!originator || originator.form !== "originatorKey") throw _err("cms/unsupported-algorithm", "kari requires an originatorKey (ephemeral-static ECDH)");
   var v = originator.value;
@@ -639,11 +657,11 @@ var DIGEST_WC = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 var MAC_KEY_MIN_OCTETS = 16;
 function _isDerNull(p) { return Buffer.isBuffer(p) && p.length === 2 && p[0] === 0x05 && p[1] === 0x00; }
 
-// Verify a CMS AuthenticatedData (RFC 5652 sec. 9): recover the MAC key through the SAME RecipientInfo
+// Verify a CMS AuthenticatedData (RFC 5652 sec. 9): recover the MAC key through the same RecipientInfo
 // unwrap decrypt uses, recompute the HMAC over the sec. 9.2 preimage (the re-tagged [2] authAttrs SET
-// OF when present, else the eContent value octets), constant-time-compare to the transmitted mac, and
-// -- when authAttrs are present -- INDEPENDENTLY confirm message-digest == digest(content) (sec. 9.3
-// do-not-trust-originator). The content is returned ONLY after every check passes. Every
+// OF when present, else the eContent value octets), constant-time-compare to the transmitted mac, and,
+// when authAttrs are present, independently confirm message-digest == digest(content) (sec. 9.3
+// do-not-trust-originator). The content is returned only after every check passes. Every
 // secret-dependent failure collapses to the uniform cms/decrypt-failed (no unwrap-success oracle).
 async function _verifyAuthenticatedData(parsed, km, opts) {
   var macAlg = parsed.macAlgorithm;
@@ -674,10 +692,10 @@ async function _verifyAuthenticatedData(parsed, km, opts) {
       _assertSupported(candidates[ci].ri, km);
       var macKey = await _acquireCek(candidates[ci].ri, km, opts);   // recover the MAC key (uniform failure)
       // RFC 3218 implicit rejection: _ktriCek returns null on an RSA v1.5 unwrap fault, and a hostile
-      // ktri/pwri could convey a below-floor (128-bit) key; in EITHER case substitute a fresh random
-      // key so the MAC verify still RUNS and fails uniformly -- never a fast-path that distinguishes an
+      // ktri/pwri could convey a below-floor (128-bit) key; in either case substitute a fresh random
+      // key so the MAC verify still runs and fails uniformly, never a fast-path that distinguishes an
       // invalid/short unwrap from a MAC mismatch (Bleichenbacher / weak-key oracle freedom).
-      // The substitute is held SEPARATELY rather than overwriting macKey: a hostile recipient can
+      // The substitute is held separately, never overwriting macKey: a hostile recipient can
       // unwrap to a non-null key that is merely too short, and assigning over it would drop the only
       // reference to that recovered secret, leaving it readable while the cleanup cleared the random
       // replacement instead. Both are this module's allocations and both are cleared below.
@@ -693,14 +711,14 @@ async function _verifyAuthenticatedData(parsed, km, opts) {
           var actual = Buffer.from(await subtle.digest(mdCheck.hash, content));
           if (!actual.equals(mdCheck.declared)) throw _fail();   // sec. 9.3: recompute, never trust the originator's digest
         }
-        return {
+        return _originFields({
           content: Buffer.from(content),
           contentType: parsed.encapContentInfo.eContentType, contentTypeName: oid.name(parsed.encapContentInfo.eContentType) || parsed.encapContentInfo.eContentType,
           recipientType: candidates[ci].ri.type, recipientIndex: candidates[ci].index,
           macAlgorithm: macAlg.name || macAlg.oid,
           digestAlgorithm: parsed.digestAlgorithm ? (parsed.digestAlgorithm.name || parsed.digestAlgorithm.oid) : null,
           authenticated: true,
-        };
+        }, "message-authentication-key", parsed.originatorInfo);
       } finally {
         guard.secret.zeroizeAll([macKey, macSubstitute], CmsError, "cms/bad-input", "the message-authentication key");
       }
@@ -717,7 +735,7 @@ async function _verifyAuthenticatedData(parsed, km, opts) {
 //     the frozen cms/unsupported-algorithm code, not a round-trip.
 //   * the detached (absent eContent) reject is the deferred-with-condition path (this producer always
 //     attaches the content); re-open when a detached AuthenticatedData caller appears.
-//   * `parsed.authAttrs || []` / `parsed.recipientInfos || []` -- the parser always surfaces these as
+//   * `parsed.authAttrs || []` / `parsed.recipientInfos || []`: the parser always surfaces these as
 //     arrays (or rejects), so the `|| []` fallbacks never fire.
 //   * `oid.name(eContentType) || eContentType` fires only for an unregistered content type; `macAlg.name
 //     || macAlg.oid` and `digestAlgorithm.name || .oid` never reach the `.oid` fallback because the
@@ -725,17 +743,17 @@ async function _verifyAuthenticatedData(parsed, km, opts) {
 //   * the `macKey == null` half of the random-key substitution fires only for a hand-crafted RSA v1.5
 //     ktri (this producer emits OAEP); its behaviour is identical to the tested below-floor path (a
 //     random key -> the MAC verify fails uniformly), so the < 16 vector covers the substitution.
-// _normKeyDer(key) -> { der, owned } -- the recipient private key as PKCS#8 DER, and whether the
-// buffer is one THIS module made.
+// _normKeyDer(key) -> { der, owned }: the recipient private key as PKCS#8 DER, and whether the
+// buffer is one this module made.
 //
 // The distinction decides who may wipe it. A caller handing in their own Buffer keeps a live
 // reference and will use it again; wiping that would destroy the key out from under them. The other
-// two forms produce a NEW buffer here -- a Uint8Array is copied, a PEM string is decoded -- and that
+// two forms produce a new buffer here (a Uint8Array is copied, a PEM string is decoded), and that
 // buffer is a second copy of a private key which nothing else can reach, so it lives until the
 // garbage collector happens to reuse the page unless this module clears it.
 //
-// Returning the flag rather than always copying keeps the caller's buffer un-duplicated: making our
-// own copy of every key so we could uniformly wipe it would ADD a copy of the secret to solve the
+// Returning the flag, in place of always copying, keeps the caller's buffer un-duplicated: making our
+// own copy of every key so we could uniformly wipe it would add a copy of the secret to solve the
 // problem of having one.
 function _normKeyDer(key) {
   if (Buffer.isBuffer(key)) return { der: key, owned: false };