@blamejs/pki 0.5.7 → 0.5.8

package/lib/cms-verify.js

@@ -16,9 +16,9 @@
  *   detached content, single and multiple signers, and RSA / RSASSA-PSS / ECDSA / EdDSA, the
  *   post-quantum ML-DSA (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814),
  *   and composite ML-DSA (pairing ML-DSA with a traditional RSA / ECDSA / EdDSA, accepted only when
- *   BOTH components verify -- draft-ietf-lamps-cms-composite-sigs) are covered. It reports a
+ *   both components verify, per draft-ietf-lamps-cms-composite-sigs) are covered. It reports a
  *   per-signer verdict;
- *   it does NOT chain the signer certificate to a trust anchor -- that is the caller's step through
+ *   it does not chain the signer certificate to a trust anchor, which is the caller's step through
  *   `pki.path.validate`.
  * @spec RFC 5652
  * @spec RFC 9882
@@ -63,11 +63,11 @@ var DIGEST_HASH = {
 // The SIGNATURE hash a bare-key-OID scheme (rsaEncryption, ecPublicKey) inherits from the
 // SignerInfo digestAlgorithm. Deliberately a SEPARATE table from DIGEST_HASH, and deliberately
 // without the extendable-output functions: RFC 8702 sec. 3.2 gives RSASSA-PKCS1-v1_5-with-SHAKE
-// and ECDSA-with-SHAKE their OWN signature OIDs and never pairs a bare key OID with a SHAKE
+// and ECDSA-with-SHAKE their own signature OIDs and never pairs a bare key OID with a SHAKE
 // digestAlgorithm, so that combination is non-conformant and must keep its precise refusal.
 // Folding the two roles into one table would resolve a signature hash for it instead, letting
-// it past the fail-closed gate below and into the engine, where it surfaces as a relabeled
-// foreign fault rather than this module's own unsupported-algorithm verdict.
+// it past the fail-closed gate below and into the engine, where the caller gets a relabeled
+// foreign fault and loses this module's own unsupported-algorithm verdict.
 var SIG_HASH = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 // Is `name` a message-digest algorithm this verifier supports?
 function _supportedDigest(name) { return !!DIGEST_HASH[name]; }
@@ -86,7 +86,7 @@ var SIG_SCHEME = {
   rsassaPss: { kind: "rsapss" },
   ecPublicKey: { kind: "ec", params: "absent" },
   // One-shot families (EdDSA, ML-DSA): the same OID identifies the key and the signature, so the
-  // signer cert SPKI algorithm OID MUST equal the signatureAlgorithm OID -- `sameKeyOid` enables
+  // signer cert SPKI algorithm OID MUST equal the signatureAlgorithm OID. `sameKeyOid` enables
   // that agreement check (RFC 8410 / RFC 9882; enforced in _verifyAgainstCandidates).
   Ed25519: { kind: "eddsa", name: "Ed25519", params: "absent", sameKeyOid: true },
   Ed448: { kind: "eddsa", name: "Ed448", params: "absent", sameKeyOid: true },
@@ -104,7 +104,7 @@ var SIG_SCHEME = {
 };
 // SLH-DSA (RFC 9814): the twelve pure FIPS 205 sets, seeded like webcrypto's SLH_DSA_NODE. Each is
 // a one-shot family (kind "slhdsa"), params absent, sig-OID == key-OID (sameKeyOid). The WebCrypto
-// name is "SLH-DSA-"+SET, matching path-validate's transform (drift rule sec. 5 -- one name map).
+// name is "SLH-DSA-"+SET, matching path-validate's transform (drift rule sec. 5: one name map).
 ["sha2-128s", "sha2-128f", "sha2-192s", "sha2-192f", "sha2-256s", "sha2-256f",
  "shake-128s", "shake-128f", "shake-192s", "shake-192f", "shake-256s", "shake-256f"
 ].forEach(function (s) { SIG_SCHEME["id-slh-dsa-" + s] = { kind: "slhdsa", name: "SLH-DSA-" + s.toUpperCase(), params: "absent", sameKeyOid: true, digest: SLHDSA_BY_OID[oid.byName("id-slh-dsa-" + s)].digest }; });
@@ -140,7 +140,7 @@ function _findSignerCerts(sid, parsedCerts) {
   return out;
 }
 
-// Verify `sigBytes` over `signedBytes` against EACH matching candidate certificate in turn; the
+// Verify `sigBytes` over `signedBytes` against each matching candidate certificate in turn; the
 // signer is valid iff one candidate verifies. A candidate whose key is structurally unusable (a
 // low-order EdDSA point, an unsupported curve) or whose signature simply does not verify falls
 // through to the next -- so a colliding certificate cannot make a valid signature read invalid.
@@ -156,7 +156,7 @@ function _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, sid, c
     var c = candidates[idx];
     // One-shot family (EdDSA/ML-DSA): the signer cert public-key algorithm OID MUST equal the
     // SignerInfo signatureAlgorithm OID. A candidate whose SPKI disagrees is skipped with a precise
-    // verdict, rather than a foreign webcrypto/data throw from importing under the wrong name.
+    // verdict; importing it under the wrong name would surface a foreign webcrypto/data throw.
     if (expectedKeyOid && c.cert.subjectPublicKeyInfo.algorithm.oid !== expectedKeyOid) {
       lastErr = _err("cms/unsupported-algorithm", "the signer certificate public-key algorithm does not match the SignerInfo signatureAlgorithm");
       return attempt(idx + 1);
@@ -206,11 +206,11 @@ function _hashAlgOid(seq) {
 }
 
 // Resolve RSASSA-PSS-params (RFC 4055) to { hash, saltLength }, or null if the parameters
-// deviate from the supported profile: an explicit SHA-2 hashAlgorithm, MGF1 keyed to the SAME
+// deviate from the supported profile: an explicit SHA-2 hashAlgorithm, MGF1 keyed to the same
 // hash, saltLength equal to the hash length, and trailerField 1. The SHA-1 DEFAULTs are
 // rejected (params must be explicit), matching the certification-path validator, so a
-// non-conformant PSS AlgorithmIdentifier is a fail-closed verdict -- never verified under
-// WebCrypto's own defaults (a signatureAlgorithm bypass otherwise).
+// non-conformant PSS AlgorithmIdentifier is a fail-closed verdict. Falling back to WebCrypto's
+// own defaults would be a signatureAlgorithm bypass.
 function _resolvePss(paramsBytes) {
   if (!paramsBytes) return null;
   var n;
@@ -264,7 +264,7 @@ function _verifySignature(scheme, hashName, sigBytes, spki, signedBytes, curveOi
     var ec = EC_CURVE[curveOid];
     if (!ec) throw _err("cms/unsupported-algorithm", "the signer key is on an unsupported EC curve");
     // The ORDER-AWARE gate: r,s in [1, n-1] per FIPS 186-5 sec. 6.4.2 (rejecting an out-of-range r/s >= the
-    // curve order n, not only the r=s=0 forgery) -- a verifier that knows the curve MUST use it.
+    // curve order n, not only the r=s=0 forgery). A verifier that knows the curve MUST use it.
     var raw = validator.sig.ecdsaDerToP1363(sigBytes, ec.curve, CmsError, "cms/bad-signature");
     return subtle.importKey("spki", spki, { name: "ECDSA", namedCurve: ec.curve }, false, ["verify"])
       .then(function (k) { return subtle.verify({ name: "ECDSA", hash: hashName }, k, raw, signedBytes); });
@@ -279,13 +279,13 @@ function _verifySignature(scheme, hashName, sigBytes, spki, signedBytes, curveOi
   }
   // EdDSA -- the WebCrypto name follows the signing key's SPKI OID (Ed25519 / Ed448). node/
   // OpenSSL imports any Ed25519/Ed448 SPKI without validating the point, and a low-order (e.g.
-  // all-zeroes) key verifies a forged signature -- so reject a non-full-order point first.
+  // all-zeroes) key verifies a forged signature, so reject a non-full-order point first.
   _requireValidEdPoint(spki, scheme.name);
   return subtle.importKey("spki", spki, { name: scheme.name }, false, ["verify"])
     .then(function (k) { return subtle.verify({ name: scheme.name }, k, sigBytes, signedBytes); });
 }
 
-// The EdDSA signer key's point MUST be a valid, canonical, full-order Edwards point -- reject an
+// The EdDSA signer key's point MUST be a valid, canonical, full-order Edwards point: reject an
 // off-curve or low-order key before it verifies a signature (WebCrypto import does not check it).
 // Routed through the shared edwards-point gate every EdDSA verify path uses; curve from the name.
 function _requireValidEdPoint(spkiBytes, name) {
@@ -303,9 +303,9 @@ function _certCurveOid(cert) {
 
 // Decode the SignedAttributes SET OF Attribute from the exact bytes the signature covers
 // (the re-tagged signedAttrsBytes), returning [{ type, values: [valueNode] }]. Binding the
-// content-type / message-digest checks to THESE decoded attributes -- not the caller-mutable
-// parsed si.signedAttrs -- means a parsed-object input cannot desync the checked attributes
-// from the verified preimage (RFC 5652 sec. 5.4).
+// content-type / message-digest checks to these decoded attributes means a parsed-object input
+// cannot desync the checked attributes from the verified preimage (RFC 5652 sec. 5.4). The
+// caller-mutable parsed si.signedAttrs is deliberately left out of that decision.
 function _decodeSignedAttrs(setOfBytes) {
   var set = asn1.decode(setOfBytes);
   if (set.tagClass !== "universal" || set.tagNumber !== asn1.TAGS.SET || !set.children) throw _err("cms/bad-signed-attrs", "signedAttrs is not a SET OF Attribute");
@@ -317,8 +317,8 @@ function _decodeSignedAttrs(setOfBytes) {
   });
 }
 
-// Verify one SignerInfo. Returns { ok, sid, cert, ... } -- a resolved false is a verdict; a
-// structural failure carries a code.
+// Verify one SignerInfo. Returns { ok, sid, cert, ... }, where a resolved false is a verdict and
+// a structural failure carries a code.
 // `csTarget`, when set (a Buffer), makes this a COUNTERSIGNATURE verify (RFC 5652 sec. 11.4): the
 // preimage is the countersigned signature octets, not the sec. 5.4 content preimage, and no
 // content-type attribute is required or checked (_computeCountersigBytes). content/eContentType are
@@ -343,7 +343,7 @@ function _verifyOne(si, content, eContentType, parsedCerts, csTarget) {
   // The digestAlgorithm parameters, when present, MUST be a DER NULL (RFC 5754 sec. 2 accepts
   // absent OR NULL; a present non-NULL is malformed and, being outside the signed preimage,
   // must fail closed like the signatureAlgorithm parameters above). EXCEPT for an ML-DSA
-  // SignerInfo WITHOUT signed attributes: RFC 9882 sec. 3.3 says the whole digestAlgorithm field
+  // SignerInfo carrying no signed attributes: RFC 9882 sec. 3.3 says the whole digestAlgorithm field
   // has no meaning there and MUST be ignored, so neither its parameters nor its name may reject.
   var dp = si.digestAlgorithm.parameters;
   var mldsaNoAttrs = scheme.kind === "mldsa" && !si.signedAttrsBytes;
@@ -398,7 +398,7 @@ function _computeCountersigBytes(si, csTarget) {
       attrs = _decodeSignedAttrs(reTagged);
     } catch (e) { if (e instanceof CmsError) throw e; throw _err("cms/bad-signed-attrs", "the countersignature signedAttrs is not a valid SET OF Attribute", e); }
     // sec. 11.4: a content-type attribute MUST NOT appear (the parser already rejects it at parse, but
-    // verify never relies on the parse alone -- a parsed-object input could carry one).
+    // verify never relies on the parse alone: a parsed-object input could carry one).
     if (attrs.filter(function (a) { return a.type === OID_CONTENT_TYPE; }).length) throw _err("cms/misplaced-attr", "a countersignature must not carry a content-type attribute (RFC 5652 sec. 11.4)");
     var mdAttr = attrs.filter(function (a) { return a.type === OID_MESSAGE_DIGEST; })[0];
     if (!mdAttr || mdAttr.values.length !== 1) throw _err("cms/bad-signed-attrs", "a countersignature's signedAttrs must carry exactly one message-digest attribute (RFC 5652 sec. 11.4)");
@@ -437,9 +437,9 @@ function _computeSignedBytes(si, content, eContentType) {
       }
       return content;
     }
-    // With signed attributes: decode them from the EXACT bytes the signature covers -- the
-    // SignedAttributes SET OF, the on-wire [0] IMPLICIT tag replaced by a universal SET OF
-    // (RFC 5652 sec. 5.4) -- so the content-type / message-digest checks bind the same bytes
+    // With signed attributes: decode them from the EXACT bytes the signature covers, namely the
+    // SignedAttributes SET OF with the on-wire [0] IMPLICIT tag replaced by a universal SET OF
+    // (RFC 5652 sec. 5.4). The content-type / message-digest checks then bind the same bytes
     // that are verified. Reading the caller-mutable parsed si.signedAttrs instead would let a
     // parsed-object input desync the checked attributes from the verified preimage.
     var reTagged = Buffer.from(si.signedAttrsBytes);
@@ -478,7 +478,7 @@ function _computeSignedBytes(si, content, eContentType) {
 // (sec. 3.4, defense-in-depth over the parse-time _PARAMS_ABSENT gate), the unsupported-arm refusal,
 // and the sec. 3.4/sec. 5 coherence gate binding the SignerInfo digestAlgorithm to the arm's Table-1
 // pre-hash. It reuses the sec. 5.4 preimage + message-digest binding UNCHANGED, then dispatches
-// compositeVerify per candidate certificate (BOTH components must verify -- never an AND->OR
+// compositeVerify per candidate certificate (both components must verify, with no AND->OR
 // downgrade).
 function _verifyComposite(si, comp, content, eContentType, parsedCerts, csTarget) {
   if (si.signatureAlgorithm.parameters !== null && si.signatureAlgorithm.parameters !== undefined) {
@@ -490,8 +490,8 @@ function _verifyComposite(si, comp, content, eContentType, parsedCerts, csTarget
     return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "composite " + comp.name + ": " + comp.trad.unsupported });
   }
   // draft sec. 3.4: for a composite SignerInfo the digestAlgorithm parameters MUST be OMITTED
-  // (id-sha256/id-sha512 and id-shake256) -- stricter than the generic RFC 5754 absent-OR-NULL rule
-  // (which the classical/ML-DSA paths follow), because the composite draft explicitly requires the
+  // (id-sha256/id-sha512 and id-shake256). That is stricter than the generic RFC 5754 absent-OR-NULL
+  // rule (which the classical/ML-DSA paths follow), because the composite draft explicitly requires the
   // field omitted. A present parameter -- even a DER NULL -- is non-conformant and fails closed
   // (it is outside the signed preimage, so a parser differential must not verify).
   var dp = si.digestAlgorithm.parameters;
@@ -515,7 +515,7 @@ function _verifyComposite(si, comp, content, eContentType, parsedCerts, csTarget
   });
 }
 
-// Dispatch compositeVerify against EACH matching candidate; the signer is valid iff one candidate
+// Dispatch compositeVerify against each matching candidate; the signer is valid iff one candidate
 // verifies both components. A candidate whose SPKI composite OID != the SignerInfo signatureAlgorithm
 // OID is skipped with a precise verdict (RFC 9814 sec. 4 key<->signature agreement); a candidate that
 // returns a structural fault code (bad split length, unsupported) falls through, its code surfaced if
@@ -542,9 +542,10 @@ function _verifyCompositeAgainstCandidates(comp, sigBytes, signedBytes, sid, can
   return attempt(0);
 }
 
-// The decoded unsigned attributes of a SignerInfo, surfaced UNAUTHENTICATED (they are outside the
-// signature) with each OID resolved to a name -- so a caller can read an attached RFC 3161 timestamp
-// token or inspect a countersignature attribute. NEVER counted toward a signer's ok / res.valid.
+// The decoded unsigned attributes of a SignerInfo, surfaced UNAUTHENTICATED (they are outside
+// the signature) with each OID resolved to a name, so a caller can read an attached RFC 3161
+// timestamp token or inspect a countersignature attribute. They are never counted toward a
+// signer's ok / res.valid.
 function _surfaceUnsignedAttrs(si) {
   return (si.unsignedAttrs || []).map(function (a) {
     return { type: a.type, typeName: oid.name(a.type) || null, values: a.values };
@@ -553,17 +554,17 @@ function _surfaceUnsignedAttrs(si) {
 
 // Verify every countersignature attached to `si` (RFC 5652 sec. 11.4): each id-countersignature
 // value is a SignerInfo over `si`'s signature octets. Returns per-countersignature verdicts; a
-// countersignature's OWN countersignatures verify over ITS signature octets (recursive). A
-// countersignature that FAILS TO VERIFY is surfaced ok:false -- never silently dropped, and never
-// allowed to change the primary verdict. A countersignature value that is not a well-formed
+// countersignature's own countersignatures verify over its signature octets (recursive). A
+// countersignature that fails to verify is surfaced ok:false. It is never silently dropped, and
+// never allowed to change the primary verdict. A countersignature value that is not a well-formed
 // SignerInfo does not reach here at all: the decoder validates every id-countersignature value by
-// content rather than on the attribute type, so such a message is refused whole. The recursion
-// terminates because it only walks the FINITE parsed structure: each nested countersignature value
-// is a sub-encoding of its parent, and the strict decoder already bounds total nesting by
-// C.LIMITS.DER_MAX_DEPTH at parse (CWE-834/770), so a hostile deep chain fails closed before verify.
+// its content, so such a message is refused whole. The recursion terminates because it only walks
+// the FINITE parsed structure: each nested countersignature value is a sub-encoding of its parent,
+// and the strict decoder already bounds total nesting by C.LIMITS.DER_MAX_DEPTH at parse
+// (CWE-834/770), so a hostile deep chain fails closed before verify.
 function _verifyCountersignatures(si, parsedCerts) {
   // si.signature is always a Buffer from the strict parser (and from walkCountersignature on the
-  // recursive path), so _toBuf is a pass-through here -- the SignerInfo is already well-formed.
+  // recursive path), so _toBuf is a pass-through here. The SignerInfo is already well-formed.
   var targetSig = _toBuf(si.signature, "the countersigned signature");
   var values = [];
   (si.unsignedAttrs || []).forEach(function (a) {
@@ -575,6 +576,14 @@ function _verifyCountersignatures(si, parsedCerts) {
 
 function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
   var csSi;
+  // Coverage residual, and deliberately kept. Every value reaching here was already walked by the
+  // decoder, which validates an id-countersignature by content and not by the attribute type. A
+  // malformed one therefore refused the whole message before verify was entered, so this catch
+  // cannot be reached through the public path. That is settled behaviour: a message the decoder
+  // has found to be malformed has no sound remainder to report a verdict over, so it is refused
+  // whole instead of surfaced as one failed countersignature.
+  // cms-verify.test.js pins that through the shipped verbs; this stays because the walk is also
+  // reachable recursively and a backstop that returns a NEGATIVE verdict costs nothing.
   try { csSi = cms.walkCountersignature(asn1.decode(Buffer.isBuffer(vDer) ? vDer : Buffer.from(vDer))); }
   catch (e) { return Promise.resolve({ ok: false, code: (e instanceof CmsError ? e.code : "cms/bad-countersignature"), message: e && e.message }); }
   return _verifyOne(csSi, targetSig, null, parsedCerts, targetSig).then(function (verdict) {
@@ -609,29 +618,29 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * than RFC 5652's. Signing WITH attributes and signing the content directly are different claims --
  * attributes bind a content type and a signing time alongside the digest, content-only binds
  * nothing but the bytes -- and one message may carry a signer of each. A profile that requires
- * attributes (RFC 8551 S/MIME does) or a particular content type can enforce it from the verdict
- * rather than parsing the message a second time.
+ * attributes (RFC 8551 S/MIME does) or a particular content type can enforce it from the verdict,
+ * with no need to parse the message a second time.
  *
  * `valid` and `trusted` are DIFFERENT claims and neither implies the other. A SignedData carries
- * its own certificates, so `valid` establishes that the message is internally consistent -- the
+ * its own certificates, so `valid` establishes that the message is internally consistent: the
  * signature is sound under a certificate the message or `opts.certs` supplied. Anyone can mint a
  * certificate, sign with it, and embed it, so that says nothing about WHO signed. `trusted` says
  * every signer chained to a root named in `opts.trustAnchors`, validated through the same RFC 5280
  * path engine `pki.path.validate` uses. Without anchors there is nothing to chain to and `trusted`
  * is `false` -- a definite answer, not a missing one. Anchors that cannot be read are a
- * configuration fault and throw, rather than being absorbed into `trusted: false`, which would
- * report a verdict about the message for a check that never ran.
+ * configuration fault and throw. Absorbing them into `trusted: false` would report a verdict
+ * about the message for a check that never ran.
  *
- * Trust is decided from the certificate the SignerInfo selected -- the one reported as
- * `signers[i].cert` -- never from another certificate that happens to share its key. A
+ * Trust is decided from the certificate the SignerInfo selected, the one reported as
+ * `signers[i].cert`, never from another certificate that happens to share its key. A
  * `subjectKeyIdentifier` names a key, and several certificates can hold it with different
  * validity windows, key usage and policies; deciding from a sibling would let an expired or
  * wrong-purpose signer certificate be reported trusted because a different certificate chained.
  * Supply the certificate you want used. RSA (PKCS#1 v1.5 and RSASSA-PSS), ECDSA, EdDSA, and the post-quantum
- * ML-DSA (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814) -- pure mode,
- * empty context -- signatures are recognized, as is composite ML-DSA
- * (draft-ietf-lamps-cms-composite-sigs), which pairs ML-DSA with a traditional RSA / ECDSA / EdDSA
- * and verifies only when BOTH components pass (never an AND-to-OR downgrade).
+ * ML-DSA (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814) signatures
+ * are recognized, the post-quantum families in pure mode with an empty context, as is composite
+ * ML-DSA (draft-ietf-lamps-cms-composite-sigs), which pairs ML-DSA with a traditional
+ * RSA / ECDSA / EdDSA and verifies only when both components pass (never an AND-to-OR downgrade).
  *
  * @opts  content  The detached content (a `Buffer`) when the SignedData carries no
  *                 encapsulated eContent. Required for a detached signature.
@@ -643,7 +652,7 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * @opts  time     The instant to validate the signer's chain at (default now). Only read when
  *                 `trustAnchors` is supplied.
  * @opts  requiredEku   Key purposes the SIGNER certificate must carry, as OID names or dotted OIDs.
- * @opts  checkPurpose  The purpose the ANCHOR's own trust metadata must permit -- a separate
+ * @opts  checkPurpose  The purpose the ANCHOR's own trust metadata must permit. This is a separate
  *                 question from `requiredEku`, since a root distributed with NSS trust bits can be
  *                 marked untrusted for one purpose and good for another. Those bits and
  *                 `distrustAfter` are consulted only when this names a purpose.
@@ -994,7 +1003,7 @@ function _addCert(out, der) {
  * @spec       RFC 9814
  * @related    pki.cms.verify, pki.schema.cms.parse
  *
- * Produce a CMS SignedData (RFC 5652 sec. 5) over `content` (a `Buffer`) -- the structure
+ * Produce a CMS SignedData (RFC 5652 sec. 5) over `content` (a `Buffer`): the structure
  * S/MIME signed mail, RFC 3161 timestamp tokens, and code signing rest on, and exactly what
  * `pki.cms.verify` consumes and OpenSSL `cms -verify` validates. Each `signers[i]` is
  * `{ cert, key, digestAlgorithm?, pss? }`: `cert` the signer certificate (PEM or DER), `key`
@@ -1004,9 +1013,10 @@ function _addCert(out, der) {
  * message-digest attribute is bound to the content digest and the signature is over the
  * canonical DER SET OF SignedAttributes; otherwise over the content directly. RSA (PKCS#1 v1.5
  * and, with `pss`, RSASSA-PSS), ECDSA (P-256/384/521), Ed25519, Ed448, and the post-quantum ML-DSA
- * (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814 -- the message digest
- * pinned per parameter set) are covered, as is composite ML-DSA (draft-ietf-lamps-cms-composite-sigs)
- * -- the arm's pre-hash fixes the digestAlgorithm and the two component keys are signed together.
+ * (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814, with the message
+ * digest pinned per parameter set) are covered, as is composite ML-DSA
+ * (draft-ietf-lamps-cms-composite-sigs), where the arm's pre-hash fixes the digestAlgorithm and
+ * the two component keys are signed together.
  *
  * @opts  detached          Omit the encapsulated content (a detached signature; the verifier
  *                          supplies the content). Default false.
@@ -1019,7 +1029,7 @@ function _addCert(out, der) {
  * @opts  pem               Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
  * @opts  unsignedAttributes  Unsigned attributes for every SignerInfo, each `{ type, values }`
  *                          (`type` an OID name or dotted string, `values` an array of DER value
- *                          `Buffer`s). Placed in the SignerInfo `[1]` unsignedAttrs -- OUTSIDE the
+ *                          `Buffer`s). Placed in the SignerInfo `[1]` unsignedAttrs, outside the
  *                          signature, so they carry no cryptographic assurance and a verifier never
  *                          reports them authenticated. The vehicle for an RFC 3161 timestamp token
  *                          (`timeStampToken`); content-type / message-digest / signing-time are
@@ -1045,12 +1055,12 @@ var sign = cmsSign.sign;
  *
  * Add one or more countersignatures to an existing CMS SignedData (RFC 5652 sec. 11.4). A
  * countersignature is itself a `SignerInfo` whose signature covers the CONTENTS of the countersigned
- * SignerInfo's signature value (NOT the content), attached as the `id-countersignature` unsigned
+ * SignerInfo's signature value (not the content), attached as the `id-countersignature` unsigned
  * attribute -- the construction Authenticode timestamps and signature-attestation workflows rest on.
- * `cms` is the SignedData (a DER `Buffer` or a PEM `CMS` string -- the wire bytes are preserved, so
+ * `cms` is the SignedData (a DER `Buffer` or a PEM `CMS` string; the wire bytes are preserved, so
  * the countersigned primary still verifies byte-for-byte). Each `signers[i]` is the same descriptor
- * `pki.cms.sign` takes -- `{ cert, key, digestAlgorithm?, pss? }`, any RSA / RSASSA-PSS / ECDSA /
- * EdDSA / ML-DSA / SLH-DSA / composite key -- and countersigns over the target signature octets;
+ * `pki.cms.sign` takes (`{ cert, key, digestAlgorithm?, pss? }`, any RSA / RSASSA-PSS / ECDSA /
+ * EdDSA / ML-DSA / SLH-DSA / composite key), and countersigns over the target signature octets;
  * `pki.cms.verify` returns each countersignature verdict under `signers[i].countersignatures`. A
  * countersignature never carries a content-type attribute (sec. 11.4); multiple countersignatures on
  * one signer are multiple values of the one id-countersignature attribute.
@@ -1059,7 +1069,7 @@ var sign = cmsSign.sign;
  *                              array of indices, or `"all"`.
  * @opts  countersignatureOf    Countersign the Nth existing countersignature of the target signer
  *                              instead of the primary signature (a nested countersignature).
- * @opts  signedAttributes      Include signed attributes (message-digest + signing-time; NEVER a
+ * @opts  signedAttributes      Include signed attributes (message-digest + signing-time; never a
  *                              content-type). Default true; false signs the target signature octets
  *                              directly.
  * @opts  signingTime           A `Date` for the countersignature's signing-time, or false to omit it.
@@ -1088,11 +1098,11 @@ var countersign = cmsSign.countersign;
  * @spec RFC 5652, RFC 5083, RFC 5084, RFC 3560, RFC 5753, RFC 8418, RFC 9629, RFC 9936, RFC 3211, RFC 8018
  * @related pki.cms.decrypt, pki.schema.cms.parse
  *
- * Encrypt content as a CMS EnvelopedData (CBC content), AuthEnvelopedData (AEAD content -- the
+ * Encrypt content as a CMS EnvelopedData (CBC content), AuthEnvelopedData (AEAD content, the
  * default), or EncryptedData. `recipients` is an ARRAY of recipient descriptors for the enveloped
- * family, each wrapping the SAME fresh content-encryption key: `{ cert }` auto-dispatches off the
+ * family, each wrapping the same fresh content-encryption key: `{ cert }` auto-dispatches off the
  * recipient certificate's public-key algorithm -- RSA yields a ktri with RSAES-OAEP-SHA256 (PKCS#1
- * v1.5 is NEVER emitted); EC P-256/384/521 a kari with ephemeral-static ECDH and the X9.63 KDF;
+ * v1.5 is never emitted); EC P-256/384/521 a kari with ephemeral-static ECDH and the X9.63 KDF;
  * X25519/X448 a kari per RFC 8418 (HKDF); ML-KEM-512/768/1024 an ori/KEMRecipientInfo per RFC
  * 9629 + 9936. `{ password }` yields a pwri (PBKDF2 + RFC 3211 PWRI-KEK); `{ kek, kekId }` a kekri
  * (AES key wrap). For EncryptedData (no RecipientInfos), pass a single non-array `{ cek }` or
@@ -1126,8 +1136,8 @@ var encrypt = cmsEncrypt.encrypt;
  * @related pki.cms.decrypt, pki.schema.cms.parse
  *
  * Produce a CMS AuthenticatedData (RFC 5652 sec. 9): CLEARTEXT content plus a MAC (HMAC-SHA-2) --
- * authenticated but NOT encrypted, the authenticated-only sibling of AuthEnvelopedData. A single
- * fresh MAC key is minted and wrapped for every recipient with the SAME RecipientInfo model
+ * authenticated but not encrypted, the authenticated-only sibling of AuthEnvelopedData. A single
+ * fresh MAC key is minted and wrapped for every recipient with the same RecipientInfo model
  * `pki.cms.encrypt` uses for a content-encryption key, so `recipients` is the identical array of
  * descriptors: `{ cert }` (RSA -> ktri RSAES-OAEP, EC/X25519/X448 -> kari, ML-KEM -> ori/KEMRI),
  * `{ password }` (pwri), or `{ kek, kekId }` (kekri). By default the MAC covers the authenticated
@@ -1161,7 +1171,7 @@ var authenticate = cmsEncrypt.authenticate;
 
 /**
  * @primitive pki.cms.decrypt
- * @signature pki.cms.decrypt(input, keyMaterial, opts?) -> Promise<{ content, contentType, contentTypeName, recipientType, recipientIndex, contentEncryptionAlgorithm, authenticated }>
+ * @signature pki.cms.decrypt(input, keyMaterial, opts?) -> Promise<{ content, contentType, contentTypeName, recipientType, recipientIndex, contentEncryptionAlgorithm, authenticated, authenticatedBy, originAuthenticated, originatorInfo }>
  * @since 0.2.23
  * @status stable
  * @spec RFC 5652, RFC 5083, RFC 5084, RFC 3560, RFC 5753, RFC 8418, RFC 9629, RFC 9936, RFC 3211, RFC 8018, RFC 3218, RFC 2104
@@ -1173,16 +1183,28 @@ var authenticate = cmsEncrypt.authenticate;
  * ECDH / X25519 / X448; kekri; pwri; ori/ML-KEM), and decrypts (or MAC-verifies) the content.
  * `keyMaterial` is `{ key, cert }` (the recipient private key + its certificate, which drives recipient
  * matching), `{ password }`, `{ kek, kekId? }`, or `{ cek }` (EncryptedData raw-key mode). Fail-closed
- * and oracle-free: every secret-dependent failure -- a bad key-wrap, a padding fault, a GCM tag
- * mismatch, a PWRI check-byte mismatch, an AuthenticatedData MAC/message-digest mismatch -- collapses
- * to the SINGLE uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL oracle freedom, and no
- * unwrap-success bit for the MAC path), and the PKCS#1 v1.5 arm applies the RFC 3218 implicit-rejection
- * countermeasure so its failure is indistinguishable. For an AuthenticatedData the MAC (HMAC-SHA-2)
+ * and oracle-free: every secret-dependent failure collapses to the SINGLE uniform
+ * `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL oracle freedom, and no unwrap-success bit
+ * for the MAC path). That covers a bad key-wrap, a padding fault, a GCM tag mismatch, a PWRI
+ * check-byte mismatch, and an AuthenticatedData MAC/message-digest mismatch. The PKCS#1 v1.5 arm
+ * applies the RFC 3218 implicit-rejection countermeasure so its failure is indistinguishable. For an AuthenticatedData the MAC (HMAC-SHA-2)
  * and, when authenticated attributes are present, the message-digest are verified before the content
  * is released, and the result carries `macAlgorithm` / `digestAlgorithm` in place of
  * `contentEncryptionAlgorithm`. `authenticated` is true for AuthEnvelopedData and AuthenticatedData; a
  * CBC EnvelopedData surfaces `authenticated: false` (the EFAIL caveat in the verdict itself).
  *
+ * `authenticated` is a claim about the CONTENT and the key that opened it, never about who sent the
+ * message, so the origin question is answered separately. `originAuthenticated` is `false` for every
+ * recipient type: a `ktri` or ephemeral-static `kari` message is minted by anyone holding the recipient's
+ * PUBLIC key, and a `pwri` or `kekri` message by any co-recipient sharing the secret. Read
+ * `authenticated: true` as "these bytes were not altered after the key was chosen", and do not read it as
+ * a sender identity -- to bind one, verify a signature (`pki.cms.verify`) over the plaintext.
+ * `authenticatedBy` names what the integrity rests on (`"content-encryption-key"` for AEAD,
+ * `"message-authentication-key"` for AuthenticatedData, `null` for an unauthenticated cipher).
+ * `originatorInfo` is surfaced as the sender supplied it and is UNAUTHENTICATED: it sits outside the
+ * AEAD's authenticated data, so it is a hint, never evidence, and any certificate it carries must be
+ * validated before use.
+ *
  * @opts recipientIndex Explicitly select the recipient by index (overrides key-material matching).
  * @opts maxIterations  Lower the PBKDF2 iteration cap (a DoS bound; downward only).
  * @example
@@ -1208,7 +1230,7 @@ var decrypt = cmsDecrypt.decrypt;
  * ZLIB-compress `content` and wrap it as a CMS `CompressedData` ContentInfo (RFC 3274): version 0,
  * `compressionAlgorithm` = id-alg-zlibCompress (parameters omitted), `encapContentInfo` = the inner
  * content type plus the RFC 1950 ZLIB stream (RFC 1951 DEFLATE) as the eContent. There is exactly
- * ONE compression algorithm in RFC 3274 -- ZLIB -- so there is no algorithm selector. CompressedData
+ * one compression algorithm in RFC 3274, ZLIB, so there is no algorithm selector. CompressedData
  * is a size transform with NO integrity, confidentiality, or authentication (RFC 8551 sec. 2.4.5);
  * compress it, then sign or encrypt it if you need protection. Malformed input throws a typed `CmsError`.
  *
@@ -1231,7 +1253,7 @@ var compress = cmsCompress.compress;
  * Parse a CMS `CompressedData` (DER Buffer or PEM) and recover its content. It requires version 0,
  * `compressionAlgorithm` = id-alg-zlibCompress with absent-or-NULL parameters (RFC 3274 sec. 2), and a
  * present eContent, then inflates the RFC 1950 ZLIB stream. The inflate is BOUNDED at
- * `C.LIMITS.COMPRESS_MAX_BYTES` (16 MiB) and stops before the output is materialized -- a
+ * `C.LIMITS.COMPRESS_MAX_BYTES` (16 MiB) and stops before the output is materialized, a
  * decompression-bomb / resource-exhaustion defense (CWE-409): a cap breach throws
  * `cms/decompress-too-large`, and every malformed / truncated / corrupt stream collapses to the uniform
  * `cms/decompress-failed`. `opts.maxOutputBytes` tightens the cap DOWNWARD only. The verdict carries NO

package/lib/composite-sig.js

@@ -13,9 +13,9 @@
 // mldsaSig || tradSig (sec. 4.3). Verification (sec. 2) reconstructs
 //   M' = Prefix || Label || len(ctx) || ctx || PH(M),
 // verifies the ML-DSA component over M' with ctx = the composite Label, verifies the traditional
-// component over M' under its own hash, and accepts IFF BOTH pass (THREAT-MODEL: all components
-// must verify -- never an AND-to-OR downgrade). The ML-DSA component is the fixed-length FIRST
-// half; the split point is its length.
+// component over M' under its own hash, and accepts if and only if both pass. Every component must
+// verify; there is no AND-to-OR downgrade. The ML-DSA component is the fixed-length first half, and
+// the split point is its length.
 //
 // Error-parameterized like the guard / validator families: each consumer passes its own typed
 // error CONSTRUCTOR `E` and its domain codes (path validation passes PathError + path/*; CMS
@@ -30,8 +30,8 @@ var edwardsPoint = require("./edwards-point");
 var subtle = webcrypto.webcrypto.subtle;
 var _b = asn1.build;
 
-// A caught error's OWN code if it shares the caller's domain prefix (the fallback's namespace,
-// e.g. path/ or cms/), else the fallback -- a foreign code (asn1/*) maps to the fallback so the
+// A caught error's own code if it shares the caller's domain prefix (the fallback's namespace,
+// e.g. path/ or cms/), else the fallback. A foreign code (asn1/*) maps to the fallback so the
 // verdict stays in the caller's error namespace. Mirrors path-validate's original pathCode when
 // the fallback is a path/* code.
 function _codeOf(e, fallback) {
@@ -55,8 +55,8 @@ var COMPOSITE_ALGS = {};
 // _comp(name, mldsa, ph, label, trad). `trad` is exactly one component shape:
 //   { ec, hash } | { eddsa } | { rsaPss, hash, salt } | { rsaPkcs1, hash } |
 //   { unsupported } for the arms Node's WebCrypto surface cannot verify (the two
-//   brainpool curves) -- registered + params-guarded, deferred at verify to the
-//   caller's unsupported-algorithm code rather than silently accepted.
+//   brainpool curves): registered and params-guarded, deferred at verify to the
+//   caller's unsupported-algorithm code instead of silently accepted.
 function _comp(name, mldsa, ph, label, trad) {
   var sz = MLDSA_COMPONENT[mldsa];
   COMPOSITE_ALGS[oid.byName(name)] = {
@@ -84,7 +84,7 @@ _comp("id-MLDSA87-RSA4096-PSS-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-
 _comp("id-MLDSA87-ECDSA-P521-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-P521-SHA512", { ec: "P-521", hash: "SHA-512" });
 
 // Wrap a raw component public key in the SPKI its WebCrypto import expects, so each half is
-// verified through the SAME import + verify seam the classical path uses (no second parallel
+// verified through the same import and verify seam the classical path uses (no second parallel
 // verify path). tradPK for RSA is the RSAPublicKey DER; for EC the uncompressed point; for EdDSA
 // the raw public key.
 function _spkiFor(algNode, keyBytes) { return _b.sequence([algNode, _b.bitString(keyBytes, 0)]); }
@@ -120,10 +120,10 @@ function _verifyTradComponent(trad, tradPK, tradSig, mprime, E, badSig) {
   }
   if (trad.eddsa) {
     // node/OpenSSL imports any Ed25519/Ed448 SPKI without validating the point, and a low-order
-    // (e.g. all-zeroes) key verifies a forged signature -- which would collapse the composite AND
-    // to ML-DSA-only. Reject a non-full-order point before verify, through the same shared
+    // (e.g. all-zeroes) key verifies a forged signature, collapsing the composite conjunction to
+    // ML-DSA alone. Reject a non-full-order point before verify, through the same shared
     // edwards-point gate every other EdDSA verify path in the toolkit routes through, surfacing a
-    // coded fault (like the ECDSA order-bound belt) rather than a silent false.
+    // coded fault (like the ECDSA order-bound belt) instead of a silent false.
     if (!edwardsPoint.validate(tradPK, trad.eddsa === "Ed25519" ? 6 : 7)) {
       throw new E(badSig, "the composite EdDSA component public key is not a valid, full-order Edwards point");
     }
@@ -132,7 +132,7 @@ function _verifyTradComponent(trad, tradPK, tradSig, mprime, E, badSig) {
   }
   if (trad.rsaPss || trad.rsaPkcs1) {
     // The composite OID fixes the RSA modulus size: a downgraded or mismatched modulus under the
-    // declared OID (an id-MLDSA44-RSA2048-* whose component is really 1024-bit) is rejected BEFORE
+    // declared OID (an id-MLDSA44-RSA2048-* whose component is really 1024-bit) is rejected before
     // verify, so a weak RSA component cannot satisfy an arm that promises 2048/3072/4096 bits. A
     // malformed RSAPublicKey rejects the same way.
     var bits;
@@ -167,7 +167,7 @@ function compositeVerify(spkiBytes, sigBytes, message, d, E, unsupported, badSig
     if (bs.unusedBits !== 0) throw new E(badSig, "composite subjectPublicKey has unused bits");
     rawKey = bs.bytes;
   } catch (e) { return Promise.resolve({ ok: false, code: _codeOf(e, badSig), error: e }); }
-  // The ML-DSA half is fixed-length and FIRST; the traditional half is the remainder. Both must be
+  // The ML-DSA half is fixed-length and comes first; the traditional half is the remainder. Both must be
   // non-empty for a well-formed composite.
   if (rawKey.length <= d.mldsaPk || sigBytes.length <= d.mldsaSig) {
     return Promise.resolve({ ok: false, code: badSig,

package/lib/constants.js

@@ -19,7 +19,7 @@
  *   Every scale helper is config-time / entry-point validation: it THROWS
  *   `ConstantsError` on a non-finite or negative argument, and on a product
  *   outside the safe-integer range, so an operator catches the typo at boot
- *   rather than shipping a silently-wrong window or an Infinity that would
+ *   instead of shipping a silently-wrong window or an Infinity that would
  *   disable a size cap.
  *
  * @card
@@ -31,7 +31,7 @@ var frameworkError = require("./framework-error");
 
 var ConstantsError = frameworkError.ConstantsError;
 
-// _positive(n, who) -- the shared guard every scale helper runs. Config-
+// _positive(n, who) is the shared guard every scale helper runs. Config-
 // time tier: a bad scale argument is an authoring bug, so it throws.
 function _positive(n, who) {
   if (typeof n !== "number" || !isFinite(n) || n < 0) {
@@ -43,10 +43,10 @@ function _positive(n, who) {
   return n;
 }
 
-// _scale(n, who, factor) -- validate the argument AND the product. A finite
+// _scale(n, who, factor) validates the argument and the product. A finite
 // operand can still overflow the multiplication (days(1e304) -> Infinity),
 // and an Infinity handed onward silently disables any bound compared
-// against it (`len > Infinity` is always false) -- so a product outside the
+// against it (`len > Infinity` is always false), so a product outside the
 // safe-integer range throws instead of returning.
 function _scale(n, who, factor) {
   var out = Math.round(_positive(n, who) * factor);