@blamejs/pki 0.5.7 → 0.5.8

package/lib/cms-encrypt.js

@@ -13,7 +13,7 @@
 // material (RSA -> ktri OAEP; EC -> kari stdDH; X25519/X448 -> kari HKDF; ML-KEM -> ori/KEMRI;
 // password -> pwri; symmetric KEK -> kekri) through the OID-keyed registry, never a hardcoded
 // switch. AEAD (AES-GCM) content is the default and yields AuthEnvelopedData; CBC yields
-// EnvelopedData. PKCS#1 v1.5 is NEVER emitted.
+// EnvelopedData. PKCS#1 v1.5 is never emitted.
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
@@ -61,13 +61,13 @@ function _wrapOidForKek(keyBytes) {
   if (keyBytes === 16) return "aes128-wrap";
   if (keyBytes === 24) return "aes192-wrap";
   if (keyBytes === 32) return "aes256-wrap";
-  // Coverage residual: unreachable via the API -- a KEK/CEK is always an AES key size (16/24/32);
+  // Coverage residual: unreachable via the API, since a KEK/CEK is always an AES key size (16/24/32);
   // a defensive throw for a future caller that hands an off-size key.
   throw _err("cms/bad-input", "no AES key-wrap algorithm for a " + keyBytes + "-octet key-encryption key");
 }
 
-// GCMParameters ::= SEQUENCE { aes-nonce OCTET STRING, aes-ICVlen INTEGER DEFAULT 12 } -- the
-// DEFAULT 12 is OMITTED on emit (RFC 5084 sec. 3.2 / canonical DER).
+// GCMParameters ::= SEQUENCE { aes-nonce OCTET STRING, aes-ICVlen INTEGER DEFAULT 12 }, where the
+// DEFAULT 12 is omitted on emit (RFC 5084 sec. 3.2 / canonical DER).
 function _gcmParams(nonce, icvLen) {
   var kids = [b.octetString(nonce)];
   if (icvLen !== 12) kids.push(b.integer(BigInt(icvLen)));
@@ -75,7 +75,7 @@ function _gcmParams(nonce, icvLen) {
 }
 
 // The keyIdentifier option selects the RecipientIdentifier form. "issuerAndSerial" is the documented
-// default (its RFC name issuerAndSerialNumber is accepted too); reject anything else rather than
+// default (its RFC name issuerAndSerialNumber is accepted too); reject anything else instead of
 // silently emitting issuerAndSerialNumber, so a typo surfaces instead of a rid the caller never asked for.
 function _assertKeyIdentifier(form) {
   if (form != null && form !== "issuerAndSerial" && form !== "issuerAndSerialNumber" && form !== "subjectKeyIdentifier") {
@@ -97,7 +97,7 @@ function _rid(cert, form) {
 // unsupported-curve / low-order / unsupported-KEM-cert throws further below): these validate the
 // CALLER's own recipient certificate at config time (tier-1 THROW). They fire only when a caller
 // supplies a certificate whose SKI/keyUsage extension is malformed, or whose key is an unsupported
-// curve / a low-order Montgomery point / an unsupported KEM -- inputs the toolkit never produces.
+// curve, a low-order Montgomery point, or an unsupported KEM: inputs the toolkit never produces.
 function _skiOf(cert) {
   var exts = cert.extensions || [];
   for (var i = 0; i < exts.length; i++) if (exts[i].name === "subjectKeyIdentifier" && exts[i].value != null) {
@@ -120,7 +120,7 @@ var OAEP_HASH = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 function _oaepParams(hashName) {
   var hAlg = _algId(hashName, "null");
   var mgf = b.sequence([b.oid(O("mgf1")), hAlg]);
-  // pSourceAlgorithm [2] DEFAULT pSpecifiedEmpty -- the empty-label default MUST be omitted (X.690).
+  // pSourceAlgorithm [2] DEFAULT pSpecifiedEmpty: the empty-label default MUST be omitted (X.690).
   return b.sequence([b.explicit(0, hAlg), b.explicit(1, mgf)]);
 }
 async function _buildKtri(cek, cert, opts) {
@@ -144,8 +144,8 @@ MONT_KA[O("X25519")] = { name: "X25519", hkdf: "SHA-256", scheme: "dhSinglePass-
 MONT_KA[O("X448")] = { name: "X448", hkdf: "SHA-512", scheme: "dhSinglePass-stdDH-hkdf-sha512-scheme" };
 
 // ECC-CMS-SharedInfo ::= SEQUENCE { keyInfo AlgorithmIdentifier (the wrap, params ABSENT),
-//   entityUInfo [0] EXPLICIT OCTET STRING OPTIONAL, suppPubInfo [2] EXPLICIT OCTET STRING } --
-// suppPubInfo = the KEK length in BITS, 4-octet big-endian (RFC 5753 sec. 7.2). ONE builder,
+//   entityUInfo [0] EXPLICIT OCTET STRING OPTIONAL, suppPubInfo [2] EXPLICIT OCTET STRING }, where
+// suppPubInfo is the KEK length in bits, 4-octet big-endian (RFC 5753 sec. 7.2). One builder,
 // shared by encrypt + decrypt so the two sides cannot diverge.
 function _eccSharedInfo(wrapName, ukm, kekBytes) {
   var kids = [_algId(wrapName, "absent")];
@@ -184,12 +184,12 @@ async function _buildKari(cek, cert, opts) {
       mz = Buffer.from(await subtle.deriveBits({ name: mka.name, public: rPub }, meph.privateKey, null));
       if (mz.every(function (x) { return x === 0; })) throw _err("cms/bad-input", "the X25519/X448 shared secret is all-zero (low-order point)");
       var mzKey = await subtle.importKey("raw", mz, { name: "HKDF" }, false, ["deriveBits"]);
-      // RFC 8418 sec. 2.2: when a ukm is present it is used BOTH as the HKDF salt AND as the
-      // ECC-CMS-SharedInfo entityUInfo (the HKDF info) -- omitting it from the info diverges the KEK
+      // RFC 8418 sec. 2.2: when a ukm is present it is used as both the HKDF salt and the
+      // ECC-CMS-SharedInfo entityUInfo (the HKDF info). Omitting it from the info diverges the KEK
       // from any conformant peer that reads the transmitted ukm.
       kek = Buffer.from(await subtle.deriveBits({ name: "HKDF", hash: mka.hkdf, salt: ukm || Buffer.alloc(0), info: _eccSharedInfo(wrapName, ukm, cek.length) }, mzKey, cek.length * 8));
     } else {
-      // Coverage residual: unreachable -- _buildRecipient routes only ecPublicKey / X25519 / X448
+      // Coverage residual: unreachable, since _buildRecipient routes only ecPublicKey / X25519 / X448
       // keys into _buildKari; a defensive throw against a future dispatch change.
       throw _err("cms/unsupported-algorithm", "unsupported recipient key algorithm for kari");
     }
@@ -199,7 +199,7 @@ async function _buildKari(cek, cert, opts) {
     var origPubBits = origSpki.children[1]; // BIT STRING node
     var originatorKey = b.contextConstructed(1, Buffer.concat([origSpki.children[0].bytes, origPubBits.bytes]));
     // KeyAgreeRecipientIdentifier CHOICE { issuerAndSerialNumber, rKeyId [0] IMPLICIT
-    // RecipientKeyIdentifier } -- the SKI form here wraps a SEQUENCE (rKeyId), unlike ktri's bare
+    // RecipientKeyIdentifier }, where the SKI form wraps a SEQUENCE (rKeyId), unlike ktri's bare
     // subjectKeyIdentifier [0] IMPLICIT OCTET STRING.
     var ridNode;
     _assertKeyIdentifier(opts.keyIdentifier);
@@ -234,13 +234,13 @@ async function _buildKekri(cek, desc) {
   return { tag: 2, node: b.sequence([b.integer(4n), kekid, _algId(wrapName, "absent"), b.octetString(encryptedKey)]) };
 }
 
-// A PBKDF2 iterationCount MUST be a positive integer within the same cap the decryptor enforces -- a
+// A PBKDF2 iterationCount MUST be a positive integer within the same cap the decryptor enforces, so a
 // ---- pwri (password) : PBKDF2 + RFC 3211 double-CBC PWRI-KEK ---------------
 async function _buildPwri(cek, desc) {
-  // 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.
-  // The option validation runs BEFORE the password is encoded: a rejected iteration count or salt
+  // The option validation runs before the password is encoded: a rejected iteration count or salt
   // would otherwise abandon an owned credential copy on the way out.
   var iterations = pbes2.assertIterations(desc.iterations == null ? 600000 : desc.iterations, _err, "cms");
   var salt = desc.salt ? pbes2.assertSalt(guard.bytes.view(desc.salt, CmsError, "cms/bad-input", "salt"), _err, "cms") : nodeCrypto.randomBytes(16);
@@ -250,9 +250,9 @@ async function _buildPwri(cek, desc) {
   var pwOwn = pbes2.passwordBytesOwned(desc.password, _err, "cms");
   var password = pwOwn.bytes;
   var kekKey = await subtle.importKey("raw", password, { name: "PBKDF2" }, false, ["deriveBits"]);
-  // The derived KEK is this function's allocation and is cleared below. `password` is NOT: when the
+  // The derived KEK is this function's allocation and is cleared below. `password` is not: when the
   // caller passes a Buffer, passwordBytes hands back that very buffer, so wiping it would destroy
-  // the caller's own memory -- the one failure this rule must never cause.
+  // the caller's own memory, the one failure this rule must never cause.
   var kek = Buffer.from(await subtle.deriveBits({ name: "PBKDF2", hash: _prfHash(prf), salt: salt, iterations: iterations }, kekKey, innerKeyBytes * 8));
   if (pwOwn.owned) guard.secret.zeroize(password, CmsError, "cms/bad-input", "the password encoding");
   try {
@@ -278,7 +278,7 @@ KEM_WRAP[O("id-ml-kem-1024")] = "aes256-wrap";
 var KEM_WC = {}; KEM_WC[O("id-ml-kem-512")] = "ML-KEM-512"; KEM_WC[O("id-ml-kem-768")] = "ML-KEM-768"; KEM_WC[O("id-ml-kem-1024")] = "ML-KEM-1024";
 
 // CMSORIforKEMOtherInfo ::= SEQUENCE { wrap AlgorithmIdentifier, kekLength INTEGER,
-//   ukm [0] EXPLICIT OCTET STRING OPTIONAL } -- the RFC 9629 sec. 5 KDF info, one builder both sides.
+//   ukm [0] EXPLICIT OCTET STRING OPTIONAL }, the RFC 9629 sec. 5 KDF info, one builder both sides.
 function _kemOtherInfo(wrapName, kekBytes, ukm) {
   var kids = [_algId(wrapName, "absent"), b.integer(BigInt(kekBytes))];
   if (ukm) kids.push(b.explicit(0, b.octetString(ukm)));
@@ -309,7 +309,7 @@ async function _buildKemri(cek, cert, opts) {
     return { tag: 4, node: b.sequence([b.oid(O("kem")), kemri]) };
   } finally {
     // RFC 9629 sec. 7 asks the SENDER to discard the shared secret and KEK once the recipient entry
-    // is built -- and to use a fresh secret per recipient, so this runs per call rather than once at
+    // is built, and to use a fresh secret per recipient, so this runs per call and not once at
     // the end of a multi-recipient message. In a `finally`, so a wrap or encoding failure does not
     // leave them behind. The CEK is the caller's and is wiped by no one here; kemct is public.
     // kem.sharedKey is the ArrayBuffer the engine returned and ss is this function's copy of it;
@@ -340,7 +340,7 @@ function _pwriFormat(cek) {
   var padLen = body.length % blk === 0 ? 0 : blk - (body.length % blk);
   if (body.length + padLen < 2 * blk) padLen += (2 * blk - (body.length + padLen));
   //  and  each hold a plaintext copy of the CEK; only the padded result is returned, so
-  // the intermediates are cleared here rather than abandoned.
+  // the intermediates are cleared here and never abandoned.
   var wrapped = Buffer.concat([body, nodeCrypto.randomBytes(padLen)]);
   guard.secret.zeroizeAll([check, body], CmsError, "cms/bad-input", "a PWRI formatting intermediate");
   return wrapped;
@@ -381,7 +381,7 @@ async function _buildRecipient(cek, desc, opts) {
 function mergeOpts(opts, desc) {
   return { oaepHash: desc.oaepHash || opts.oaepHash, keyIdentifier: desc.keyIdentifier || opts.keyIdentifier, ukm: desc.ukm != null ? desc.ukm : opts.ukm };
 }
-// RecipientInfo CHOICE: ktri untagged; kari [1], kekri [2], pwri [3], ori [4] -- all IMPLICIT,
+// RecipientInfo CHOICE: ktri untagged; kari [1], kekri [2], pwri [3], ori [4], all IMPLICIT,
 // so the arm's SEQUENCE tag is replaced by the context tag.
 function _taggedRecipient(r) {
   if (r.tag == null) return r.node;
@@ -406,8 +406,8 @@ async function encrypt(content, recipients, opts) {
   var contentType = opts.contentType || "data";
   var cek = nodeCrypto.randomBytes(ca.keyBits / 8);
 
-  // The CEK protects the content for EVERY recipient, so unlike a per-recipient shared secret it is
-  // cleared ONCE, after the last recipient entry is built and the content is encrypted -- wiping it
+  // The CEK protects the content for every recipient, so unlike a per-recipient shared secret it is
+  // cleared once, after the last recipient entry is built and the content is encrypted. Wiping it
   // inside the recipient loop would destroy the key the remaining recipients must be given.
   try {
     // EncryptedData: a single non-array { cek } or { password } descriptor, no RecipientInfos.
@@ -450,9 +450,9 @@ function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, r
     var setOf = b.setOf(opts.authAttrs);
     aad = setOf; authAttrsDer = b.contextConstructed(1, setOf.subarray(_tlvHeaderLen(setOf)));
   }
-  // A 16-octet (128-bit) GCM tag -- the strongest ICV and what OpenSSL emits, so the message
+  // A 16-octet (128-bit) GCM tag, the strongest ICV and what OpenSSL emits, so the message
   // interops across OpenSSL 3.5 / 4.x. The aes-ICVlen (16) is carried explicitly (RFC 5084 sec. 3.2
-  // omits it ONLY when it equals the DEFAULT 12); it MUST equal the mac octet length (M42).
+  // omits it only when it equals the DEFAULT 12); it MUST equal the mac octet length (M42).
   var g = _gcmEncrypt(cek, nonce, contentBytes, aad, ca.keyBits, 16);
   var eci = b.sequence([b.oid(O(contentType)), b.sequence([b.oid(O(ca.oid)), _gcmParams(nonce, 16)]), b.contextPrimitive(0, g.ct)]);
   var kids = [b.integer(0n), b.setOf(riNodes), eci];
@@ -482,8 +482,8 @@ function _encryptedData(contentBytes, desc, ca, contentType, opts, cek) {
 }
 
 function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
-  // 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 pwOwn2 = pbes2.passwordBytesOwned(desc.password, _err, "cms");
   var password = pwOwn2.bytes;
@@ -554,7 +554,7 @@ async function authenticate(content, recipients, opts) {
   if (contentType !== "data" && !withAttrs) throw _err("cms/bad-input", "AuthenticatedData with a non-data contentType requires authenticated attributes (RFC 5652 sec. 9.1)");
 
   // The MAC key is this path's content-encryption key: every recipient is given it, so it is cleared
-  // ONCE at the end rather than per recipient, and only after the MAC has been computed over it.
+  // once at the end and not per recipient, and only after the MAC has been computed over it.
   var macKey = nodeCrypto.randomBytes(MAC_KEY_OCTETS);
   try {
     var recips = [];
@@ -574,8 +574,8 @@ async function authenticate(content, recipients, opts) {
       ];
       if (opts.authAttrs && opts.authAttrs.length) pairs = pairs.concat(opts.authAttrs);
       // Every authAttr (auto-built or caller-supplied) MUST be a well-formed Attribute SEQUENCE
-      // { type OBJECT IDENTIFIER, values SET OF } and each type appears at most once (RFC 5652) -- so a
-      // malformed or duplicate caller attribute is rejected BEFORE it is MACed and emitted, never left to
+      // { type OBJECT IDENTIFIER, values SET OF } and each type appears at most once (RFC 5652), so a
+      // malformed or duplicate caller attribute is rejected before it is MACed and emitted, never left to
       // fail an operator's parser downstream.
       var seenTypes = {};
       pairs.forEach(function (p) {

package/lib/cms-sign.js

@@ -2,7 +2,7 @@
 // Copyright (c) blamejs contributors
 "use strict";
 //
-// @internal -- the pki.cms.sign implementation. So the pki.cms namespace has ONE @module home,
+// @internal -- the pki.cms.sign implementation. So the pki.cms namespace has one @module home,
 // the operator-facing @module pki.cms + the @primitive pki.cms.sign documentation block live in
 // cms-verify.js, which re-exports this sign function.
 //
@@ -33,10 +33,27 @@ function _err(code, message, cause) { return new CmsError(code, message, cause);
 // cms/<kind>), so its faults keep the cms/* codes.
 function _signE(kind, message, cause) { return new CmsError("cms/" + kind, message, cause); }
 function O(name) { return oid.byName(name); }
+
+// Every option each verb READS, and nothing else. Derived from the signing paths themselves rather
+// than from what callers happen to pass: an option this list omits is one the verb would ignore in
+// silence, and the ones that matter most are the ones a caller would most expect to work.
+// A misspelled option name is the shape this closes: it does not select the mode the caller meant,
+// and without the gate the message is signed the other way with nothing said about it.
+var KNOWN_SIGN_OPTS = {
+  signedAttributes: 1, signingTime: 1, additionalSignedAttributes: 1, unsignedAttributes: 1,
+  sid: 1, eContentType: 1, detached: 1, certificates: 1, pem: 1,
+};
+// Countersign has its own set: it takes signerIndex and countersignatureOf to SELECT which
+// signature it attaches to, and has no content of its own, so eContentType, detached and
+// unsignedAttributes are not among the options it reads.
+var KNOWN_COUNTERSIGN_OPTS = {
+  signerIndex: 1, countersignatureOf: 1, signingTime: 1, certificates: 1, pem: 1,
+  signedAttributes: 1, additionalSignedAttributes: 1, sid: 1,
+};
 // The shared producing-side helpers, bound to this domain's error class. Only the
-// post-sign self-check is used here -- the same one every other signer in the
-// toolkit runs -- so a key-only signer's declared public key is bound by evidence
-// rather than by the caller's word.
+// post-sign self-check is used here (the same one every other signer in the
+// toolkit runs), so a key-only signer's declared public key is bound by evidence
+// and never by the caller's word.
 var NS = pkix.makeNS("cms", CmsError, oid);
 var _b = pkiBuild.makeBuilder({
   ErrorClass: CmsError, prefix: "cms", O: O, NS: NS,
@@ -85,10 +102,10 @@ function _buildSid(cert, useSki) {
 // Assemble a SignedAttributes SET from resolved attribute pairs (each { type: <dotted OID>, values:
 // [<build node or DER Buffer>] }), returning { setOf, wire }: `setOf` is the canonical DER SET OF
 // (tag 0x31, build.set SET-OF-sorts) the signature covers (RFC 5652 sec. 5.4); `wire` is the same
-// bytes with the on-wire [0] IMPLICIT tag (0xA0). Each attribute type appears AT MOST ONCE (sec.
-// 5.3) -- a duplicate throws. Shared by the top-level signer (content-type + message-digest +
+// bytes with the on-wire [0] IMPLICIT tag (0xA0). Each attribute type appears at most once (sec.
+// 5.3), so a duplicate throws. Shared by the top-level signer (content-type + message-digest +
 // signing-time + caller attrs) and the countersignature builder (message-digest over the target
-// signature octets + signing-time, content-type OMITTED per sec. 11.4).
+// signature octets + signing-time, content-type omitted per sec. 11.4).
 function _buildSignedAttrs(pairs) {
   var seenTypes = {};
   var attrs = pairs.map(function (p) {
@@ -112,16 +129,16 @@ function _resolveAttrPairs(list, what) {
   });
 }
 
-// content-type / message-digest / signing-time are content-binding SIGNED attributes and MUST NOT
-// appear as unsigned attributes (RFC 5652 sec. 11.1/11.2/11.3 -- the parser's ATTR_FORBIDDEN_IN).
+// content-type / message-digest / signing-time are content-binding signed attributes and MUST NOT
+// appear as unsigned attributes (RFC 5652 sec. 11.1/11.2/11.3, the parser's ATTR_FORBIDDEN_IN).
 var UNSIGNED_FORBIDDEN = {};
 UNSIGNED_FORBIDDEN[O("contentType")] = "content-type";
 UNSIGNED_FORBIDDEN[O("messageDigest")] = "message-digest";
 UNSIGNED_FORBIDDEN[O("signingTime")] = "signing-time";
 
 // Build the [1] IMPLICIT unsignedAttrs SET OF (on-wire tag 0xA1) from opts.unsignedAttributes
-// (each { type, values: [DER] } -- a countersignature, an RFC 3161 timestamp token), or null when
-// absent/empty. Unsigned attributes are OUTSIDE the signature; a placement-forbidden type or a
+// (each { type, values: [DER] }, such as a countersignature or an RFC 3161 timestamp token), or null when
+// absent/empty. Unsigned attributes sit outside the signature; a placement-forbidden type or a
 // duplicate type (RFC 5652 sec. 11 / sec. 5.3) is a config-time cms/bad-input.
 function _buildUnsignedAttrs(list) {
   if (list == null) return null;
@@ -144,9 +161,9 @@ function _buildUnsignedAttrs(list) {
 // SignedData digestAlgorithms + certificates sets).
 function _buildSignerInfo(signer, content, eContentType, opts) {
   var so = signer || {};
-  // A KEY-ONLY signer: `{ key, spki, keyIdentifier }` with no certificate. RFC
+  // A key-only signer: `{ key, spki, keyIdentifier }` with no certificate. RFC
   // 5272 sec. 3.2 requires exactly this when a Full PKI Request is signed with the
-  // key of a certification request it carries -- there is no certificate yet, the
+  // key of a certification request it carries: there is no certificate yet, the
   // sid MUST be the subjectKeyIdentifier form, and its value MUST be the SKI the
   // request itself declares. The scheme resolver only ever reads
   // `cert.subjectPublicKeyInfo.algorithm`, so the request's own parsed SPKI stands
@@ -217,9 +234,9 @@ function _buildSignerInfo(signer, content, eContentType, opts) {
 // comparing it works only for key material this process can export, and the keys
 // this signer serves are often exactly the ones that cannot be: a non-extractable
 // CryptoKey, an HSM handle, or a composite `{ mldsa, trad }` pair that is two keys
-// rather than one. Every one of those can still be checked the direct way -- the
+// and not one. Every one of those can still be checked the direct way: the
 // signature it just produced either verifies under the declared public key or it
-// does not -- so there is no key kind this has to take on trust.
+// does not, so there is no key kind this has to take on trust.
 //
 // This is the same post-sign self-check every other signer in the toolkit runs,
 // through the same shared helper. It costs one verification per SignerInfo, which
@@ -227,8 +244,8 @@ function _buildSignerInfo(signer, content, eContentType, opts) {
 function _assertKeyMatchesSpki(keyOnly, soKey, soSpki, scheme, sig, signedBytes, cert) {
   var declared = keyOnly ? soSpki : (cert && cert.subjectPublicKeyInfo && cert.subjectPublicKeyInfo.bytes);
   // A parsed certificate that does not retain its SPKI bytes cannot be checked this
-  // way. That is not a shape x509.parse produces -- and if it ever were, refusing is
-  // the answer rather than skipping, since a skip is the fail-open this prevents.
+  // way. That is not a shape x509.parse produces, and if it ever were, refusing is
+  // the answer, never skipping, since a skip is the fail-open this prevents.
   if (!declared) {
     throw _signE("bad-input",
       "a signer certificate did not surface its subjectPublicKeyInfo, so the signature it produced could " +
@@ -253,21 +270,21 @@ function _timeValue(when) {
 
 // Normalize a signer certificate input to its raw DER (DER Buffer / PEM string / Uint8Array).
 // The same bytes drive scheme resolution and the certificates [0] embedding, so a parsed
-// certificate (which does not retain its full DER) is rejected -- pass DER or PEM.
+// certificate (which does not retain its full DER) is rejected; pass DER or PEM.
 // The stand-in a key-only signer resolves its signature scheme from: the parsed
 // SubjectPublicKeyInfo of the key that will sign. Only `.subjectPublicKeyInfo` is
-// read downstream, so this deliberately carries nothing else -- a fuller fake
+// read downstream, so this deliberately carries nothing else; a fuller fake
 // would invite code to start trusting fields no certificate actually backs.
 function _keyOnlyCertStandIn(spkiDer) {
   var alg;
   try {
     // SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }
-    // The WHOLE structure, not just the field this function goes on to read. For an
-    // OPAQUE key handle the derivation check downstream is deliberately skipped, so
-    // this is the ONLY thing standing between a caller's bytes and a SignerInfo that
+    // The whole structure, not just the field this function goes on to read. For an
+    // opaque key handle the derivation check downstream is deliberately skipped, so
+    // this is the only thing standing between a caller's bytes and a SignerInfo that
     // declares them: a SEQUENCE carrying an algorithm and nothing else, or a third
     // field, would be emitted as the signer's public key and resolve to nothing for
-    // anyone trying to verify. The key VALUE is not interpreted -- only that there
+    // anyone trying to verify. The key value is not interpreted, only that there
     // is one, in the field the structure reserves for it.
     var node = asn1.decode(spkiDer);
     if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children ||
@@ -288,7 +305,7 @@ function _keyOnlyCertStandIn(spkiDer) {
         "a key-only signer's spki algorithm is SEQUENCE { algorithm OID, parameters OPTIONAL } (RFC 5280 sec. 4.1.1.2)");
     }
     // The same shape schema-x509 surfaces: the algorithm OID plus its parameters
-    // as the RAW TLV (or null when absent) -- the resolver re-decodes those bytes
+    // as the raw TLV (or null when absent); the resolver re-decodes those bytes
     // for an EC named curve and for the RSASSA-PSS hash pinning, so handing it a
     // different representation here would break exactly those two algorithms.
     alg = {
@@ -312,9 +329,9 @@ function _keyOnlyKeyId(so) {
     throw _err("cms/bad-input",
       "a key-only signer requires keyIdentifier -- the subjectKeyIdentifier the certification request declares (RFC 5272 sec. 3.2)");
   }
-  // A key identifier is BYTES, so the type is checked rather than coerced. Buffer.from
-  // ACCEPTS far more than it should mean here: Buffer.from(20) allocates twenty zero
-  // octets and Buffer.from("a1b2") takes the ASCII of the text rather than the two
+  // A key identifier is bytes, so the type is checked and never coerced. Buffer.from
+  // accepts far more than it should mean here: Buffer.from(20) allocates twenty zero
+  // octets and Buffer.from("a1b2") takes the ASCII of the text, not the two
   // octets a reader means by it. Either would emit a structurally valid
   // SignerIdentifier carrying an identifier the caller never asked for, which no
   // verifier can match back to the certification request (RFC 5272 sec. 3.2).
@@ -342,7 +359,7 @@ function _pemToDer(text) {
 // Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
 // synchronous because they read the caller's mutable content and signer list.
 function sign(content, signers, opts) {
-  // Every caller-owned argument copied at entry and released when the call settles -- see the note
+  // Every caller-owned argument copied at entry and released when the call settles; see the note
   // on the same call in x509-sign. Here it is what makes the attribute-shaped-content refusal below
   // hold: the value that decides it and the value that gets signed are now the same read.
   return guard.bytes.fixedCall(CmsError, "cms/bad-input", [
@@ -353,10 +370,11 @@ function sign(content, signers, opts) {
 function _sign(content, signers, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.sign options must be an object");
+  guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
   // The arguments were copied at entry (see `sign` above), which is what makes the refusal below
   // hold: flipping signedAttributes from true to false after the call returns would otherwise skip
-  // the attribute-shaped-content check while the signer signs that content directly -- the very
-  // signature the stripping attack needs.
+  // the attribute-shaped-content check while the signer signs that content directly, which is the
+  // very signature the stripping attack needs.
   var contentBuf = _toBuf(content, "content");
   var list = Array.isArray(signers) ? signers : [signers];
   if (!list.length) throw _err("cms/bad-input", "pki.cms.sign requires at least one signer");
@@ -374,7 +392,7 @@ function _sign(content, signers, opts) {
       "a key-only signer must be the ONLY SignerInfo in a Full PKI Request (RFC 5272 sec. 3.2)");
   }
   // RFC 5652 sec. 5.3: signed attributes MUST be present (carrying a content-type attribute)
-  // whenever the encapsulated content type is not id-data -- so signedAttributes:false is only
+  // whenever the encapsulated content type is not id-data, so signedAttributes:false is only
   // valid for id-data content. Refusing it here keeps cms.sign from emitting a non-conformant
   // SignedData (e.g. a timestamp token, id-ct-TSTInfo, with no signed attributes).
   if (opts.signedAttributes === false && eContentType !== OID_DATA) {
@@ -382,9 +400,9 @@ function _sign(content, signers, opts) {
   }
   // The signer's half of the signed-attribute stripping problem
   // (draft-vangeest-lamps-cms-euf-cma-signeddata, Attack Type 2). Signing attribute-shaped content
-  // WITHOUT attributes produces a signature that can afterwards be promoted into an
+  // without attributes produces a signature that can afterwards be promoted into an
   // attributes-present message, because the signature does not commit to which mode was used: the
-  // attacker attaches the signed bytes AS the SignedAttributes and swaps in whatever content their
+  // attacker attaches the signed bytes as the SignedAttributes and swaps in whatever content their
   // message-digest attribute names. Refusing to mint the ambiguous signature is the only point at
   // which this direction can be stopped -- by the time it is a message, the damage is done.
   if (opts.signedAttributes === false && cms.looksLikeSignedAttributes(contentBuf)) {
@@ -392,7 +410,7 @@ function _sign(content, signers, opts) {
       "it WITHOUT signed attributes would produce a signature that could be re-presented as one over " +
       "attributes (RFC 5652 sec. 5.4); sign it with signed attributes instead");
   }
-  // A supplied signing-time MUST be a valid Date (or false to omit the attribute) -- never a
+  // A supplied signing-time MUST be a valid Date (or false to omit the attribute), never a
   // silently-ignored non-Date or an Invalid Date that would encode a garbage Time.
   if (opts.signingTime != null && opts.signingTime !== false) guard.time.assertValid(opts.signingTime, _err, "cms/bad-input", "signingTime");
 
@@ -426,7 +444,7 @@ function _sign(content, signers, opts) {
   });
 }
 
-// Dedupe certificate DERs (two signers may share a cert -- embed it once).
+// Dedupe certificate DERs (two signers may share a cert, so embed it once).
 function _dedupe(ders) {
   var seen = {}, out = [];
   ders.forEach(function (d) { var k = d.toString("hex"); if (!seen[k]) { seen[k] = 1; out.push(d); } });
@@ -439,11 +457,11 @@ function _toBuf(v, what) {
 }
 
 // ---- pki.cms.countersign (RFC 5652 sec. 11.4) ------------------------------
-// A countersignature is a SignerInfo (Countersignature ::= SignerInfo) over the CONTENTS of the
-// countersigned SignerInfo's signature OCTET STRING -- NOT the eContent -- attached as the
+// A countersignature is a SignerInfo (Countersignature ::= SignerInfo) over the contents of the
+// countersigned SignerInfo's signature OCTET STRING, never the eContent, attached as the
 // id-countersignature unsigned attribute. It reuses the whole build+sign flow (resolveSignScheme /
 // _buildSid / _buildSignedAttrs / signOverTbs); only the preimage (the target signature octets) and
-// the content-type OMISSION are the deltas, and the orchestrator splices the [1] unsignedAttrs into
+// the omitted content-type are the deltas, and the orchestrator splices the [1] unsignedAttrs into
 // an existing SignedData while preserving the targeted SignerInfo's signed bytes BYTE-FOR-BYTE.
 
 // Resolve opts.signerIndex (a number, an array of numbers, or "all"; default 0) to primary indices.
@@ -457,8 +475,8 @@ function _resolveSignerIndices(spec, n) {
 }
 
 // Build one countersignature value (RFC 5652 sec. 11.4) over `targetSigOctets`: message-digest bound
-// to digest(targetSigOctets) under the countersignature's own digestAlgorithm, content-type OMITTED,
-// signed through the SAME per-algorithm scheme machinery as a top-level signer.
+// to digest(targetSigOctets) under the countersignature's own digestAlgorithm, content-type omitted,
+// signed through the same per-algorithm scheme machinery as a top-level signer.
 function _buildCountersignature(targetSigOctets, countersigner, opts) {
   var so = countersigner || {};
   var certDer = _normCertDer(so.cert);
@@ -485,9 +503,9 @@ function _buildCountersignature(targetSigOctets, countersigner, opts) {
   });
 }
 
-// Build the [1] IMPLICIT unsignedAttrs bytes for a SignerInfo, merging `newCsValues` into the ONE
-// id-countersignature attribute (RFC 5652 sec. 11: single instance per type, MULTIPLE values), and
-// keeping every OTHER unsigned attribute and every EXISTING countersignature value verbatim.
+// Build the [1] IMPLICIT unsignedAttrs bytes for a SignerInfo, merging `newCsValues` into the single
+// id-countersignature attribute (RFC 5652 sec. 11: one instance per type, multiple values), and
+// keeping every other unsigned attribute and every existing countersignature value verbatim.
 function _mergeCountersig(uaNode, newCsValues) {
   var CS = O("countersignature");
   var others = [], csValues = [];
@@ -561,10 +579,10 @@ function _targetPreimage(siNode, opts) {
 }
 
 // pki.cms.countersign -- documented by the @primitive block in cms-verify.js (the @module pki.cms home).
-// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async).
+// Documented `-> Promise`, so a fault leaves as a rejection (guard-async).
 function countersign(cmsInput, signers, opts) {
-  // Every caller-owned argument copied at entry and released when the call settles -- see the note
-  // on the same call in x509-sign. `signerIndex` and `countersignatureOf` SELECT which signature is
+  // Every caller-owned argument copied at entry and released when the call settles; see the note
+  // on the same call in x509-sign. `signerIndex` and `countersignatureOf` select which signature is
   // countersigned, so a late read could attach the countersignature to a different one.
   return guard.bytes.fixedCall(CmsError, "cms/bad-input", [
     [cmsInput, "the CMS message"], [signers, "the signer list"], [opts, "pki.cms.countersign options"],
@@ -574,6 +592,7 @@ function countersign(cmsInput, signers, opts) {
 function _countersign(cmsInput, signers, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.countersign options must be an object");
+  guard.identifier.assertKnownKeys(opts, KNOWN_COUNTERSIGN_OPTS, _err, "cms/bad-input", "unknown opts field ");
   var list = Array.isArray(signers) ? signers : [signers];
   if (!list.length) throw _err("cms/bad-input", "pki.cms.countersign requires at least one countersigner");
   if (opts.signingTime != null && opts.signingTime !== false) guard.time.assertValid(opts.signingTime, _err, "cms/bad-input", "signingTime");
@@ -603,7 +622,7 @@ function _countersign(cmsInput, signers, opts) {
       return opts.countersignatureOf == null ? _appendCountersigs(siNode, byTarget[idx]) : _spliceNested(siNode, opts.countersignatureOf, byTarget[idx]);
     }));
 
-    // Rebuild SignedData: version, digestAlgorithms (UNCHANGED -- a countersignature digest is not a
+    // Rebuild SignedData: version, digestAlgorithms (unchanged, since a countersignature digest is not a
     // SignedData digestAlgorithm), encapContentInfo, certificates [0]?, crls [1]?, the new signerInfos.
     var certsNode = null, crlsNode = null;
     for (var i = 3; i < sdKids.length - 1; i++) {
@@ -624,21 +643,21 @@ function _countersign(cmsInput, signers, opts) {
   });
 }
 
-// Coverage residual -- three defensive branches are unreachable through the shipped path:
-//   * `_skiValue`'s `cert.extensions || []` fallback -- x509.parse always surfaces `extensions`
+// Coverage residual: three defensive branches are unreachable through the shipped path.
+//   * `_skiValue`'s `cert.extensions || []` fallback. x509.parse always surfaces `extensions`
 //     as an array (empty when absent), so the `|| []` never fires.
-//   * `_assertKeyMatchesScheme`'s `key.algorithm || {}` -- a WebCrypto CryptoKey always carries
+//   * `_assertKeyMatchesScheme`'s `key.algorithm || {}`. A WebCrypto CryptoKey always carries
 //     an `algorithm`, so the `|| {}` fallback never fires.
-//   * `_assertKeyMatchesScheme`'s `!ka.hash` guard -- an `imp.hash` is set only for an RSA
+//   * `_assertKeyMatchesScheme`'s `!ka.hash` guard. An `imp.hash` is set only for an RSA
 //     scheme, which requires `ka.name` to already equal the RSA name (else the earlier name
 //     check throws); an RSA CryptoKey always carries a `hash`, so `!ka.hash` never fires.
 // Countersign-side residuals also unreachable through the shipped path:
-//   * `_resolveSignerIndices`'s `n < 1` throw -- a parsed SignedData always carries at least one
+//   * `_resolveSignerIndices`'s `n < 1` throw. A parsed SignedData always carries at least one
 //     SignerInfo, so the default index [0] is always in range.
-//   * `_spliceNested`'s no-countersignature / index-out-of-range / not-found throws -- the same node
-//     is validated by `_targetPreimage` FIRST (it computes the nested preimage before the build), so
+//   * `_spliceNested`'s no-countersignature / index-out-of-range / not-found throws. The same node
+//     is validated by `_targetPreimage` first (it computes the nested preimage before the build), so
 //     by the time `_spliceNested` re-walks it those conditions cannot hold; the checks are
 //     belt-and-suspenders against a future caller reordering the two.
-//   * the `crls [1]` preservation branches in `countersign` -- pki.cms.sign never emits a crls field,
+//   * the `crls [1]` preservation branches in `countersign`. pki.cms.sign never emits a crls field,
 //     so a store this producer countersigns never carries one to preserve.
 module.exports = { sign: sign, countersign: countersign };