@blamejs/pki 0.5.17 → 0.5.19

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.5.19 — 2026-08-20
+
+The crypto engine and the JWS signer decide with operations captured at load, so code that runs after the module does cannot change what a permission check concludes.
+
+### Changed
+
+- `pki.webcrypto` and `pki.jose` are held to the live-read rule the guard family already follows: the check over `lib/` that refuses reading an operation from the runtime at call time covers every module that takes the captures, and these two now do. Operator-visible behavior is unchanged except where a refusal that could be bypassed now holds.
+
+### Fixed
+
+- The WebCrypto key-usage check holds against a replaced `Array.prototype.indexOf`. The membership test IS the permission decision, so it runs through the captured method: dispatched live, a key permitted only for `verify` passed the engine's gate for `sign` and failed later, in the platform's own crypto, with an untyped fault instead of `webcrypto/invalid-access`.
+- A CryptoKey's usage list is a copy this engine took with a captured `slice`, so a replaced one cannot leave the caller holding the array the key is checked against for the rest of its life. The same applies to the partition that decides which usages each half of a generated pair is minted with.
+- `pki.key.import`, `pki.key.generate` and `subtle.generateKey` refuse a non-array `usages` by name. It reached the key constructor, where `Array.prototype.slice` on a number yields an empty list, so the call minted a key permitted for nothing rather than naming the argument that was wrong. The asymmetric branch of `generateKey` partitions the usages before either half is constructed and `filter` treats a non-list the same way, so it is checked at that verb's own door and the whole pair is refused.
+- The AES-GCM ciphertext and authentication tag are split with a captured `subarray`, so a replaced one cannot hand the tag check a different range of the same buffer.
+- A JWK thumbprint (RFC 7638 sec. 3.3) is built with a captured serializer. The canonical JSON is the thumbprint's preimage, so a replaced `JSON.stringify` changes the identity every consumer compares keys by.
+- The JOSE header checks -- own-name reads, the `crit` list walk, the embedded-JWK shape test -- and the protected-header serialization all run on captured operations, so a caller who reaches the header through an accessor cannot decide which of them apply.
+- A digest runs under the algorithm the caller named. The hash name is case-folded to pick its registry row, and dispatched live a replaced `String.prototype.toUpperCase` answering `SHA-1` gave a caller who asked for SHA-256 a 20-byte digest. The same fold picks the HMAC block size and decides whether a key's algorithm matches the operation's.
+- `getRandomValues` settles the kinds WebCrypto refuses from the value's internal slot rather than by `instanceof` against a replaceable global, so a real `Float32Array` cannot pass a check written to reject it by swapping the constructor the comparison names.
+
+## v0.5.18 — 2026-08-20
+
+Every producing verb refuses an authoring field it does not read, so a misspelling is a refusal at the call instead of a signed artifact that quietly omits what was asked for.
+
+### Changed
+
+- The issuer argument of `pki.x509.sign` and `pki.crl.sign` accepts only the fields the form it selects reads: `{ key, cert }` when an issuing certificate is supplied, `{ key, name, publicKey }` otherwise. A caller who hands over a key-store object carrying anything else must narrow it to one of the two. The check is there because a misspelled `cert` is not otherwise refused on this argument -- the issuing certificate is optional, so a dropped one falls through to self-signing, and a cross-certificate issued that way names its own subject as its issuer. Supplying both forms is refused for the same reason: the certificate branch wins unconditionally and reads neither `name` nor `publicKey`, so a caller who named a different issuer got one issued under the certificate's own distinguished name.
+- The TSA argument of `pki.tsp.sign` accepts only the certificate and key it reads. A misspelling of either was always refused for what it left missing, but that is half the class: a name belonging on the third argument, written on the TSA instead, is read by nothing there. `ordering` placed on the TSA emitted a token the same size as one that never asked for it, with the flag unset, while the caller believed they had set it. A caller passing a key-store object whole must narrow it to `{ cert, key }`.
+
+### Fixed
+
+- `pki.x509.sign` refuses an unrecognized field on the certificate spec, the issuer and the options. `extension` in place of `extensions` signed a certificate carrying NONE of them: a caller asking for `basicConstraints: { cA: true }` and `keyUsage` got neither, and nothing in the returned certificate said so. An `issuer` nested inside the spec is refused by name as well -- the issuer is the second argument, and nesting it produced a self-signed certificate with no error, which reads as a broken signer rather than a mis-shaped call.
+- `pki.crl.sign` refuses an unrecognized field on the CRL spec, the issuer and the options. The revoked list is `revoked`; the parser reports the same list as `revokedCertificates`, so a caller round-tripping a parsed CRL back into signing reached for that name and got a correctly signed, structurally valid CRL asserting that nothing is revoked. The refusal names the field the producer reads.
+- `pki.pkcs12.build` refuses an unrecognized field on the store spec and the options, and no longer accepts an option belonging to `open` or `verifyMac`. A store that silently omits a certificate or a key looks well formed and opens cleanly; the omission surfaces wherever it is later imported.
+- `pki.pkcs12.build` refuses an unrecognized field on a `safeContents` entry, on a bag, and on the PBE descriptor either of them carries. The safeContents entry is where the privacy directive lives, so a misspelling there was the costliest in the format: `encrypt` misspelled is neither present nor falsy, so it passed the guard that rejects a present-but-falsy directive, no privacy was selected, and that safe went out as plaintext `id-data` -- an unshrouded private-key bag in the clear, inside a PFX whose MAC still verified and which opened without complaint. A misspelled PBE parameter, on either the safe or the bag, silently reverted to the built-in default, so a caller who asked for a stronger KDF or a different cipher got neither. `opts.mac` is checked the same way, and every one of its fields has a default too: a misspelled `iterations` produced a store MAC'd at the shipped iteration count while the caller believed they had raised it, and an array passed as `opts.mac` carried no field any table lists, so it reached the builder as an empty descriptor and produced the default MAC.
+- `pki.pkcs12.build` refuses a spec that mixes its two forms. `safeContents` and the `{ key, cert, ca }` shorthand are alternatives, and the builder returns `safeContents` the moment it is present without ever reading the shorthand fields -- so `{ safeContents: [...], key }` produced a store with the key silently absent.
+- A `safeContents` entry is checked against the privacy branch it selects. `contentEncryptionAlgorithm` is the public-key branch's content cipher and is read by nothing on a password safe, whose cipher comes from `encrypt.cipher`, so an explicit `aes-128-cbc` request on a password safe was accepted and the default used anyway.
+- A certificate recipient of `pki.cms.encrypt` is checked against the fields ITS CERTIFICATE'S KEY ALGORITHM reads. The arms differ: RSA reads `oaepHash` and never `ukm`; ECDH, X25519, X448 and ML-KEM read `ukm` and never `oaepHash`. One table across all three accepted `oaepHash` on an elliptic-curve recipient, where nothing reads it, and wrapped the content key under the arm's own defaults.
+- A bag is checked against the fields ITS OWN TYPE reads, rather than against one table covering every type. `encrypt` is real on a `shroudedKey` bag and read by nothing on a plaintext `key` bag, so a union accepted the combination and emitted the private key as an unencrypted key bag while the caller had supplied an explicit encryption directive and the surrounding MAC gave integrity only.
+- `pki.crl.sign` refuses an unrecognized field on a revoked-certificate entry. Every optional field on an entry is encoded only when present, so `reson` in place of `reason` listed the certificate as revoked carrying no reason code at all -- in a CRL that verifies, where a relying party cannot distinguish it from a revocation published without a reason.
+- `pki.cms.encrypt` refuses an unrecognized field on a recipient descriptor, against a table per recipient type. The fields beyond the selector all have defaults, so `oaepHsh` encrypted the content key under the default SHA-256 OAEP, and a misspelled `iterations`, `salt` or `prf` on a password recipient derived the key at the default work factor. The single descriptor an `EncryptedData` takes is checked per arm as well: its `cek` branch derives nothing, so a work factor handed to it was discarded exactly as a misspelling would be.
+- `pki.tsp.sign` refuses an unrecognized field on the `accuracy` descriptor. Its three fields are all optional, so `milis` emitted an empty Accuracy that reads back as zero seconds, millis and micros, and the token understated the precision the caller asked it to claim.
+- `pki.cms.encrypt` and `pki.cms.authenticate` each refuse an unrecognized option, against separate tables. The two verbs have different option sets, so a single shared table would have accepted either verb's keys and defeated the check.
+- `pki.tsp.sign` refuses an unrecognized field on the message imprint and the options. A one-letter slip -- `odering` for `ordering` -- emitted a token with the ordering flag unset, which is a claim about the timestamp the caller believed they had made.
+- `pki.pkcs12.open` and `pki.pkcs12.verifyMac` each refuse an unrecognized option, against their own tables. `maxIterations` caps the work a hostile store can demand of the key derivation, so a misspelling restored the built-in ceiling and the tighter bound the caller set was never applied.
+- `pki.tsp.request` refuses an unrecognized field on the message imprint as well as on the options -- the same table `pki.tsp.sign` holds its imprint to. The request's own options are the second argument, so `nonce` written on the imprint reached nothing and the request went out with no nonce.
+- `pki.tsp.request` refuses an unrecognized option. Every field it encodes is optional in the request structure, so a misspelled one was dropped without complaint: `nonce` misspelled put a request on the wire carrying no nonce at all, and the client then matched the reply against a replay defense it had never actually asked for.
+- `pki.tsp.response` refuses an unrecognized option. `status` carries the verdict and defaults to granted, so a misspelling did not lose a detail -- it inverted the answer, and a TSA declining a request emitted a granted response over a token it meant to withhold.
+- The options of `pki.pkcs12.build` are checked against the spec form in force. `recipientCerts` selects public-key privacy only where the builder assembles the safes itself, so under the `safeContents` form it selected nothing: a plaintext key bag went into an `id-data` safe with the private key in the clear, while the caller had asked for recipient-enveloped privacy. The full form carries privacy per entry, as `safeContents[i].recipients`.
+- `pki.cms.encrypt` and `pki.cms.authenticate` refuse a per-recipient default that no recipient of the message reads. `oaepHash` is read only by an RSA certificate recipient, `ukm` only by a key-agreement or KEM certificate recipient, and `keyIdentifier` only by a certificate recipient -- so a password-only message given an `oaepHash` described a wrapping it never performed. A recipient that supplies its own value reads that one and never the default, so a default every recipient overrides is refused too; one recipient that does read it is enough. An `EncryptedData` carries no recipients at all and so reads none of the three.
+- `pki.cmp.build` refuses a signature parameter under MAC protection. `pss` and `digestAlgorithm` are read only by the `{ key, cert }` form; supplied alongside `mac`, they emitted a message MAC'd under the default PRF, byte for byte identical to the call that never named them.
+- `pki.jose.sign` refuses `opts.jwk` when the protected header already embeds one. The embedded key wins, so the option is read in kid mode only, and a caller who named a different public JWK beside an embedded one had it discarded.
+- `pki.jose.sign` serializes the protected header once and every check reads back those exact bytes, through the same bounded reader a received JWS goes through. The header is a caller-owned object, so a `toJSON` or an accessor could answer the public-only check and the serializer differently: a JWK whose own members carried no private half but which serialized `d` passed the check and shipped the private key in the header. Serializing runs that code, so the option check now runs before it -- a `toJSON` reaching into the options bag could otherwise delete a misspelled option before the door looked at it. A header that cannot be serialized is refused rather than reaching the signer.
+- `pki.pkcs12.build` decides which of the two spec forms it has once, and the field check and the builder both act on that decision. Held separately the two tests disagreed on a `safeContents` that is present but not a list, so the refusal named a field that was correct instead of the one that was wrong.
+- `pki.cms.encrypt` refuses `authAttrs` under a CBC content algorithm. Authenticated attributes are carried by an `AuthEnvelopedData`, which an AEAD algorithm produces; a CBC algorithm selects `EnvelopedData`, which has no field for them, so the attributes a caller asked to authenticate were dropped and the message went out without them.
+- `pki.cms.authenticate` refuses `digestAlgorithm` and `authAttrs` when `authenticatedAttributes` is `false`. That branch MACs the content octets directly and builds no attribute set, so the digest algorithm that names its hash, and any attribute added to it, are read by nothing.
+- `pem` on an `EncryptedData` descriptor is refused; it is an option, the third argument, as on every other verb here. A second spelling on the descriptor was read by the password arm alone, so a `{ cek, pem: true }` descriptor was accepted and returned DER.
+- `pki.crl.sign` refuses `spec.issuer` when the issuer argument already names one. The distinguished name has three possible sources and `issuer.cert` and `issuer.name` both win outright, so a spec naming one issuer beside a certificate for another produced a CRL, which verifies, issued under the certificate's name. `spec.issuer` is still the name when the issuer argument supplies none.
+- `opts.mac.keyLength` on a `pki.pkcs12.build` store is refused under the classic `hmac` algorithm, which is the default. The Appendix B derivation produces a key at the hash's own output length and reads no key length, so an explicit one was discarded and the store carried the same MAC as a call that never named it. `keyLength` remains a PBMAC1 parameter (RFC 9579).
+- A `pki.pkcs12.build` public-key integrity signer is checked against the form it selects, `{ cert, key }` or `{ spki, keyIdentifier, key }`, plus the signature parameters. Every field beyond the identity has a default, so a misspelled `pss` or `digestAlgorithm` signed the store under PKCS#1 with SHA-256 while the caller had asked for something else, and a store records only what was used. `opts.integrity.signer` and `opts.integrity.signers` are the same setting spelled two ways and the list won outright, so supplying both signed the store under the list alone; exactly one is now required.
+
 ## v0.5.17 — 2026-08-20
 
 A failed integrity check destroys the plaintext it recovered, AuthEnvelopedData validates the attributes it is asked to authenticate, and every refusal names the rule it is actually applying.

package/lib/acme.js

@@ -694,7 +694,9 @@ var _promised = guard.async.deferred;
 function _signOuter(o, payloadObj) {
   if (!_isObject(o)) throw E("acme/bad-input", "a request options object is required");
   if (!o.key) throw E("acme/bad-input", "a signing key (opts.key) is required");
-  return jose.sign({ protected: _outerHeader(o), payload: _payloadBuf(payloadObj), key: o.key, jwk: o.jwk, profile: "acme-outer" });
+  // The header carries the account jwk in jwk mode and the kid in kid mode, so the public JWK is
+  // already there whenever there is one to name; jose.sign reads its own opts.jwk in kid mode only.
+  return jose.sign({ protected: _outerHeader(o), payload: _payloadBuf(payloadObj), key: o.key, profile: "acme-outer" });
 }
 
 /**
@@ -778,7 +780,7 @@ function newAccount(o) {
     if (!_isObject(o.externalAccountBinding)) throw E("acme/bad-input", "externalAccountBinding must be an EAB inner JWS object");
     payload.externalAccountBinding = o.externalAccountBinding;
   }
-  return jose.sign({ protected: { alg: o.alg, nonce: o.nonce, url: o.url, jwk: o.jwk }, payload: _payloadBuf(payload), key: o.key, jwk: o.jwk, profile: "acme-outer" });
+  return jose.sign({ protected: { alg: o.alg, nonce: o.nonce, url: o.url, jwk: o.jwk }, payload: _payloadBuf(payload), key: o.key, profile: "acme-outer" });
   });
 }
 
@@ -1123,7 +1125,7 @@ function revokeCert(o) {
   }
   var header = { alg: o.alg, nonce: o.nonce, url: o.url };
   if (hasKid) header.kid = o.kid; else header.jwk = o.jwk;
-  return jose.sign({ protected: header, payload: _payloadBuf(payload), key: o.key, jwk: o.jwk, profile: "acme-outer" });
+  return jose.sign({ protected: header, payload: _payloadBuf(payload), key: o.key, profile: "acme-outer" });
   });
 }
 
@@ -1164,7 +1166,7 @@ async function keyChange(o) {
   var inner = await jose.sign({
     protected: { alg: o.newAlg, url: o.url, jwk: o.newJwk },
     payload: _payloadBuf({ account: o.account, oldKey: o.oldKey }),
-    key: o.newKey, jwk: o.newJwk, profile: "keychange-inner",
+    key: o.newKey, profile: "keychange-inner",
   });
   return jose.sign({ protected: { alg: o.alg, nonce: o.nonce, url: o.url, kid: o.kid }, payload: _payloadBuf(inner), key: o.key, profile: "acme-outer" });
 }

package/lib/cmp-build.js

@@ -75,7 +75,13 @@ var BODY_TAG = {
 };
 var CRMF_BODY = { ir: 1, cr: 1, kur: 1 };   // arms whose content is a CertReqMessages via pki.crmf.build
 var CERT_REP_ARM = { ip: 1, cp: 1, kup: 1, ccp: 1 };   // arms carrying a CertRepMessage
+// Protection has two mutually exclusive forms, and the signature parameters are read only by the
+// signature one: under PBMAC1 a requested pss or digestAlgorithm selects nothing and the message
+// goes out MAC'd under the default PRF, byte-identical to the call that never named them. The union
+// stays in force where the form is ambiguous, so _resolveProtection keeps its both/neither verdicts.
 var KNOWN_OPTS_KEYS = { key: 1, cert: 1, mac: 1, extraCerts: 1, pem: 1, pss: 1, digestAlgorithm: 1 };
+var KNOWN_OPTS_SIG_KEYS = { key: 1, cert: 1, extraCerts: 1, pem: 1, pss: 1, digestAlgorithm: 1 };
+var KNOWN_OPTS_MAC_KEYS = { mac: 1, extraCerts: 1, pem: 1 };
 var KNOWN_MESSAGE_KEYS = { header: 1, body: 1 };
 var KNOWN_MAC_KEYS = { secret: 1, salt: 1, iterationCount: 1, prf: 1, keyLength: 1, algorithm: 1 };
 
@@ -565,7 +571,15 @@ function _build(message, opts) {
   guard.identifier.assertKnownKeys(message, KNOWN_MESSAGE_KEYS, _err, "cmp/bad-input", function (k) {
     return "unknown message field " + JSON.stringify(k) + " (a message carries only header + body)";
   });
-  guard.identifier.assertKnownKeys(opts, KNOWN_OPTS_KEYS, _err, "cmp/bad-input", "unknown opts field ");
+  var sigForm = opts.key != null || opts.cert != null, macForm = opts.mac != null;
+  guard.identifier.assertKnownKeys(opts,
+    sigForm === macForm ? KNOWN_OPTS_KEYS : sigForm ? KNOWN_OPTS_SIG_KEYS : KNOWN_OPTS_MAC_KEYS,
+    _err, "cmp/bad-input", function (k) {
+      return "unknown opts field " + JSON.stringify(k) +
+        (macForm && (k === "pss" || k === "digestAlgorithm")
+          ? " for MAC protection; the signature parameters are read only by the { key, cert } form"
+          : "");
+    });
   if (message.header == null) throw _err("cmp/bad-input", "message.header is required");
   if (message.body == null) throw _err("cmp/bad-input", "message.body is required");
 

package/lib/cms-encrypt.js

@@ -364,22 +364,91 @@ var PRF_HASH = { hmacWithSHA1: "SHA-1", hmacWithSHA256: "SHA-256", hmacWithSHA38
 function _prfHash(prf) { if (!PRF_HASH[prf]) throw _err("cms/bad-input", "unsupported pwri prf " + JSON.stringify(prf)); return PRF_HASH[prf]; }
 
 // ---- recipient dispatch ----------------------------------------------------
-async function _buildRecipient(cek, desc, opts) {
+// The fields a recipient descriptor carries, PER ARM. Each arm reads a disjoint set, and every
+// field beyond the selector is optional with a default, so an unrecognized name is missed by
+// nothing and the recipient is built with the shipped parameters instead: `oaepHsh` for `oaepHash`
+// encrypts the content key under the default SHA-256 OAEP, and a misspelled `iterations`, `salt`
+// or `prf` on a password recipient derives the key at the default work factor. A union table would
+// admit another arm's fields, which the chosen arm never reads.
+var _PWRI_KEYS = { password: 1, iterations: 1, prf: 1, salt: 1 };
+var _KEKRI_KEYS = { kek: 1, kekId: 1 };
+// A certificate recipient dispatches on the certificate's KEY ALGORITHM, and the arms read
+// different fields: ktri (RSA) reads oaepHash and never ukm; kari (ECDH / X25519 / X448) and kemri
+// (ML-KEM) read ukm and never oaepHash. One table across all three accepted `oaepHash` on an EC
+// certificate, where nothing reads it, so the content key was wrapped under the arm's own defaults
+// while the caller had named a hash. Checked after the key algorithm resolves, since that is what
+// selects the arm.
+var _KTRI_RECIPIENT_KEYS = { cert: 1, oaepHash: 1, keyIdentifier: 1 };
+var _AGREE_RECIPIENT_KEYS = { cert: 1, keyIdentifier: 1, ukm: 1 };
+
+// The three top-level options that are per-recipient DEFAULTS rather than message-wide settings.
+// Which of them any given message actually consumes depends on the recipient arms it selects, so
+// they are checked against the arms after those resolve, not against a fixed list.
+var _RECIPIENT_DEFAULTS = ["oaepHash", "keyIdentifier", "ukm"];
+
+function _assertRecipientKeys(desc, known, arm) {
+  guard.identifier.assertKnownKeys(desc, known, _err, "cms/bad-input", function (k) {
+    return "unknown field " + JSON.stringify(k) + " on a " + arm +
+      " recipient; that field is not read for this recipient type";
+  });
+}
+
+// A default no selected recipient reads is discarded exactly as a misspelling would be: `oaepHash`
+// on a message whose only recipient is a password recipient names a wrapping the message does not
+// perform. Run after every recipient's arm has resolved and BEFORE anything is emitted.
+function _assertDefaultsConsumed(opts, consumed) {
+  for (var i = 0; i < _RECIPIENT_DEFAULTS.length; i++) {
+    var name = _RECIPIENT_DEFAULTS[i];
+    if (opts[name] != null && !consumed[name]) {
+      throw _err("cms/bad-input", "opts." + name + " is a per-recipient default and no recipient of this message reads it" +
+        (name === "oaepHash" ? " (only an RSA certificate recipient does)"
+          : name === "ukm" ? " (only a key-agreement or KEM certificate recipient does)"
+            : " (only a certificate recipient does)"));
+    }
+  }
+}
+
+async function _buildRecipient(cek, desc, opts, consumed) {
   if (desc == null || typeof desc !== "object") throw _err("cms/bad-input", "each recipient must be a descriptor object");
-  if (desc.password != null) return _buildPwri(cek, desc);
-  if (desc.kek != null) return _buildKekri(cek, desc);
+  // Checked per arm, on the same selector the dispatch below uses, so the table that runs is the
+  // one belonging to the arm that will build. `consumed` records which top-level defaults the
+  // selected arms read, so a default no recipient consumes can be refused once they all resolve.
+  if (desc.password != null) { _assertRecipientKeys(desc, _PWRI_KEYS, "password"); return _buildPwri(cek, desc); }
+  if (desc.kek != null) { _assertRecipientKeys(desc, _KEKRI_KEYS, "KEK"); return _buildKekri(cek, desc); }
   if (desc.cert != null) {
     var cert = x509.parse(_normCertDer(desc.cert, "a recipient certificate"));
     var keyOid = cert.subjectPublicKeyInfo.algorithm.oid;
-    if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) return _buildKtri(cek, cert, mergeOpts(opts, desc));
-    if (keyOid === O("ecPublicKey") || MONT_KA[keyOid]) return _buildKari(cek, cert, mergeOpts(opts, desc));
-    if (KEM_WC[keyOid]) return _buildKemri(cek, cert, mergeOpts(opts, desc));
+    if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) {
+      _assertRecipientKeys(desc, _KTRI_RECIPIENT_KEYS, "RSA certificate");
+      return _buildKtri(cek, cert, mergeOpts(opts, desc, _KTRI_RECIPIENT_KEYS, consumed));
+    }
+    if (keyOid === O("ecPublicKey") || MONT_KA[keyOid]) {
+      _assertRecipientKeys(desc, _AGREE_RECIPIENT_KEYS, "key-agreement certificate");
+      return _buildKari(cek, cert, mergeOpts(opts, desc, _AGREE_RECIPIENT_KEYS, consumed));
+    }
+    if (KEM_WC[keyOid]) {
+      _assertRecipientKeys(desc, _AGREE_RECIPIENT_KEYS, "KEM certificate");
+      return _buildKemri(cek, cert, mergeOpts(opts, desc, _AGREE_RECIPIENT_KEYS, consumed));
+    }
     throw _err("cms/unsupported-algorithm", "unsupported recipient certificate key algorithm " + keyOid);
   }
   throw _err("cms/bad-input", "a recipient needs { cert }, { password }, or { kek, kekId }");
 }
-function mergeOpts(opts, desc) {
-  return { oaepHash: desc.oaepHash || opts.oaepHash, keyIdentifier: desc.keyIdentifier || opts.keyIdentifier, ukm: desc.ukm != null ? desc.ukm : opts.ukm };
+// Each default is taken from the descriptor when it supplies one and from the top-level options
+// otherwise. That one choice is also the record of which top-level defaults the recipient CONSUMED:
+// an arm that does not read the name never consumes it, and neither does one whose descriptor
+// overrode it, so recording it from the arm's table alone would accept a value nothing read.
+function _pickDefault(desc, opts, name, known, consumed, nullish) {
+  var supplied = desc[name], fromDesc = nullish ? supplied != null : !!supplied;
+  if (!fromDesc && known[name] && consumed && opts[name] != null) consumed[name] = 1;
+  return fromDesc ? supplied : opts[name];
+}
+function mergeOpts(opts, desc, known, consumed) {
+  return {
+    oaepHash: _pickDefault(desc, opts, "oaepHash", known, consumed, false),
+    keyIdentifier: _pickDefault(desc, opts, "keyIdentifier", known, consumed, false),
+    ukm: _pickDefault(desc, opts, "ukm", known, consumed, true),
+  };
 }
 // 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.
@@ -397,12 +466,46 @@ function _envelopedVersion(recips, hasUnprotected) {
   return forcesTwo ? 2 : 0;
 }
 
+// The two exported verbs have DISJOINT option sets, so they get separate tables: one shared table
+// would admit every other verb's keys, which is the hole rather than the door. Each is the union of
+// what the verb reads THROUGH ITS DELEGATIONS -- encrypt never names oaepHash, keyIdentifier or ukm
+// itself, but hands opts to the per-recipient builders that do, and to _emit for pem.
+// Authenticated attributes live in an AuthEnvelopedData, which only an AEAD content algorithm
+// produces: a CBC algorithm selects EnvelopedData, which has no field for them and is not handed
+// opts at all. Requested there, they named a protection the message does not carry.
+var _ENCRYPT_OPTS_AEAD = {
+  contentEncryptionAlgorithm: 1, contentType: 1, authAttrs: 1, oaepHash: 1, keyIdentifier: 1,
+  ukm: 1, pem: 1,
+};
+var _ENCRYPT_OPTS_CBC = {
+  contentEncryptionAlgorithm: 1, contentType: 1, oaepHash: 1, keyIdentifier: 1, ukm: 1, pem: 1,
+};
+// authenticatedAttributes: false MACs the content octets directly, and the attribute set is what
+// carries the digest: neither the digest algorithm nor any extra attribute is read on that branch.
+var _AUTHENTICATE_OPTS_ATTRS = {
+  macAlgorithm: 1, digestAlgorithm: 1, authenticatedAttributes: 1, authAttrs: 1, contentType: 1,
+  keyIdentifier: 1, oaepHash: 1, ukm: 1, pem: 1,
+};
+var _AUTHENTICATE_OPTS_BARE = {
+  macAlgorithm: 1, authenticatedAttributes: 1, contentType: 1,
+  keyIdentifier: 1, oaepHash: 1, ukm: 1, pem: 1,
+};
+
 async function encrypt(content, recipients, opts) {
   opts = opts || {};
-  var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
+  // The content algorithm selects the structure, so it is resolved before the door and the table
+  // that runs is the one belonging to the structure this call will emit.
   var algName = opts.contentEncryptionAlgorithm || "aes-256-gcm";
   var ca = CONTENT_ALGS[algName];
   if (!ca) throw _err("cms/bad-input", "unsupported contentEncryptionAlgorithm " + JSON.stringify(algName));
+  guard.identifier.assertKnownKeys(opts, ca.aead ? _ENCRYPT_OPTS_AEAD : _ENCRYPT_OPTS_CBC, _err, "cms/bad-input",
+    function (k) {
+      return "pki.cms.encrypt has an unknown option " + JSON.stringify(k) +
+        (!ca.aead && k === "authAttrs"
+          ? " for a CBC content algorithm; authenticated attributes are carried only by an AuthEnvelopedData, which an AEAD algorithm produces"
+          : "");
+    });
+  var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
   var contentType = opts.contentType || "data";
   var cek = nodeCrypto.randomBytes(ca.keyBits / 8);
 
@@ -415,7 +518,9 @@ async function encrypt(content, recipients, opts) {
 
     if (!recipients.length) throw _err("cms/bad-input", "at least one recipient is required (RFC 5652 sec. 6.1)");
     var recips = [];
-    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(cek, recipients[i], opts));
+    var consumed = {};
+    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(cek, recipients[i], opts, consumed));
+    _assertDefaultsConsumed(opts, consumed);
     var riNodes = recips.map(_taggedRecipient);
 
     if (ca.aead) return _emit(_authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, recips), "authEnvelopedData", opts);
@@ -500,8 +605,31 @@ function _authEnvelopedData(contentBytes, cek, ca, contentType, opts, riNodes, r
   return b.sequence(kids);
 }
 
+// The single descriptor an EncryptedData takes, PER ARM. `cek` and `password` select the arm and
+// the arms read disjoint sets, so a union would admit the other arm's fields: `{ cek, iterations }`
+// supplies a work factor to a branch that derives nothing, and the caller's parameter is discarded
+// exactly as a misspelling would be. `pem` is read after both arms, so it belongs to each.
+// pem selects the output encoding of the whole call and is an OPTION, the third argument, on every
+// other verb here. A second spelling on the descriptor was read by the password arm alone, so the
+// cek arm accepted it and returned DER; there is now one place to ask for PEM.
+var _ENCRYPTED_DATA_CEK_KEYS = { cek: 1 };
+var _ENCRYPTED_DATA_PW_KEYS = { password: 1, iterations: 1, salt: 1, prf: 1 };
+
 function _encryptedData(contentBytes, desc, ca, contentType, opts, cek) {
   if (ca.aead) throw _err("cms/bad-input", "EncryptedData supports only CBC content encryption");
+  // An EncryptedData carries no RecipientInfos at all, so nothing here reads a per-recipient
+  // default. This branch returns before the recipient loop, so it answers for them itself.
+  _assertDefaultsConsumed(opts, {});
+  // Checked per arm, on the same selector the dispatch below uses, so the table that runs belongs
+  // to the branch that will encrypt.
+  if (desc != null && typeof desc === "object") {
+    var edKeys = desc.cek != null ? _ENCRYPTED_DATA_CEK_KEYS : _ENCRYPTED_DATA_PW_KEYS;
+    var edArm = desc.cek != null ? "cek" : "password";
+    guard.identifier.assertKnownKeys(desc, edKeys, _err, "cms/bad-input", function (k) {
+      return "unknown field " + JSON.stringify(k) + " on a " + edArm +
+        " EncryptedData descriptor; that field is not read for this arm";
+    });
+  }
   var iv = nodeCrypto.randomBytes(16);
   var contentAlgNode, encKey;
   if (desc && desc.cek != null) {
@@ -537,7 +665,7 @@ function _encryptedDataPbes2(contentBytes, desc, ca, contentType, iv, opts) {
     var contentAlg = pbes2.pbes2AlgId(salt, iterations, prf, ca.oid, iv);
     var eci = b.sequence([b.oid(O(contentType)), contentAlg, b.contextPrimitive(0, enc)]);
     var inner = b.sequence([b.integer(0n), eci]);
-    return _emit(inner, "encryptedData", { pem: opts && opts.pem != null ? opts.pem : desc.pem });
+    return _emit(inner, "encryptedData", opts);
   } finally {
     guard.secret.zeroize(key, CmsError, "cms/bad-input", "the password-derived content-encryption key");
   }
@@ -581,13 +709,22 @@ var SUPPORTED_DIGEST = { sha256: 1, sha384: 1, sha512: 1 };
 
 async function authenticate(content, recipients, opts) {
   opts = opts || {};
+  // The attribute branch is selected once, and the door and the MAC below both act on that one
+  // decision, so the table that runs belongs to the branch that will compute the MAC.
+  var withAttrs = opts.authenticatedAttributes !== false;
+  guard.identifier.assertKnownKeys(opts, withAttrs ? _AUTHENTICATE_OPTS_ATTRS : _AUTHENTICATE_OPTS_BARE,
+    _err, "cms/bad-input", function (k) {
+      return "pki.cms.authenticate has an unknown option " + JSON.stringify(k) +
+        (!withAttrs && (k === "digestAlgorithm" || k === "authAttrs")
+          ? " with authenticatedAttributes: false; the MAC then covers the content octets directly and no attribute set is built"
+          : "");
+    });
   var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
   var macName = opts.macAlgorithm || "hmac-sha256";
   var mac = MAC_ALGS[macName];
   if (!mac) throw _err("cms/bad-input", "unsupported macAlgorithm " + JSON.stringify(macName) + " (hmac-sha256/384/512)");
   if (!Array.isArray(recipients) || !recipients.length) throw _err("cms/bad-input", "at least one recipient is required (RFC 5652 sec. 9.1)");
   var contentType = opts.contentType || "data";
-  var withAttrs = opts.authenticatedAttributes !== false;
   // RFC 5652 sec. 9.1: authAttrs MUST be present when the eContentType is not id-data.
   if (contentType !== "data" && !withAttrs) throw _err("cms/bad-input", "AuthenticatedData with a non-data contentType requires authenticated attributes (RFC 5652 sec. 9.1)");
 
@@ -596,12 +733,16 @@ async function authenticate(content, recipients, opts) {
   var macKey = nodeCrypto.randomBytes(MAC_KEY_OCTETS);
   try {
     var recips = [];
-    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(macKey, recipients[i], opts));
+    var consumedAuth = {};
+    for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(macKey, recipients[i], opts, consumedAuth));
+    _assertDefaultsConsumed(opts, consumedAuth);
     var riNodes = recips.map(_taggedRecipient);
 
-    var digestName = opts.digestAlgorithm || mac.node;
     var digestAlgTagged = null, authAttrsDer = null, preimage;
     if (withAttrs) {
+      // Inside the branch that uses it: the attribute set is what carries the digest, so on the
+      // other branch there is no digest to name and opts.digestAlgorithm is refused at the door.
+      var digestName = opts.digestAlgorithm || mac.node;
       if (!SUPPORTED_DIGEST[digestName]) throw _err("cms/bad-input", "unsupported digestAlgorithm " + JSON.stringify(digestName) + " (sha256/384/512)");
       // sec. 9.2: content-type (== eContentType) + message-digest (== digest(content)) attributes,
       // SET-OF-sorted, MACed under the EXPLICIT SET OF tag (0x31) but transmitted [2] IMPLICIT (0xA2).

package/lib/cms-sign.js

@@ -43,6 +43,14 @@ var KNOWN_SIGN_OPTS = {
   signedAttributes: 1, signingTime: 1, additionalSignedAttributes: 1, unsignedAttributes: 1,
   sid: 1, eContentType: 1, detached: 1, certificates: 1, pem: 1,
 };
+// The SIGNER descriptor has two forms, and every field it reads is named here so a caller that
+// authors one can be held to the form it selects: a certificate signer, and the key-only signer
+// RFC 5272 sec. 3.2 requires for a Full PKI Request, whose identity comes from `spki` +
+// `keyIdentifier` instead. The signature parameters are read by both. Exported for the verbs that
+// take signer descriptors as AUTHORING input and gate them at their own door -- pki.cms.sign takes
+// them straight from its caller, where a bag carrying extra handles is an ordinary shape.
+var KNOWN_SIGNER_CERT_KEYS = { cert: 1, key: 1, pss: 1, digestAlgorithm: 1, combinedRsaSig: 1 };
+var KNOWN_SIGNER_KEY_ONLY_KEYS = { spki: 1, keyIdentifier: 1, key: 1, pss: 1, digestAlgorithm: 1, combinedRsaSig: 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.
@@ -658,4 +666,10 @@ function _countersign(cmsInput, signers, opts) {
 //     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,
 //     so a store this producer countersigns never carries one to preserve.
-module.exports = { sign: sign, countersign: countersign };
+module.exports = {
+  sign: sign, countersign: countersign,
+  // @internal -- the signer-descriptor field tables, for a verb that AUTHORS signer descriptors
+  // from its own caller's options and gates them at its own door.
+  KNOWN_SIGNER_CERT_KEYS: KNOWN_SIGNER_CERT_KEYS,
+  KNOWN_SIGNER_KEY_ONLY_KEYS: KNOWN_SIGNER_KEY_ONLY_KEYS,
+};

package/lib/crl-sign.js

@@ -72,8 +72,38 @@ var REASON_BY_NAME = {};
 Object.keys(CRL_REASON).forEach(function (v) { REASON_BY_NAME[CRL_REASON[v]] = Number(v); });
 
 var KNOWN_CRL_EXT_KEYS = { authorityKeyIdentifier: 1, issuingDistributionPoint: 1, deltaCRLIndicator: 1, freshestCRL: 1, authorityInfoAccess: 1 };
+// The three caller-owned objects pki.crl.sign reads. `crlNumber` and `extensions` are read by
+// _buildCrlExtensions, which _sign hands the whole spec to, so they belong here even though _sign
+// never names them -- the table is derived from what the call ACTUALLY reads, including through
+// its delegations, not from the doc block.
+var KNOWN_SPEC_KEYS = {
+  issuer: 1, thisUpdate: 1, nextUpdate: 1, revoked: 1, crlNumber: 1, extensions: 1,
+};
+// spec.issuer is the third place an issuer distinguished name can come from, and it is read only
+// when neither issuer.cert nor issuer.name supplies one: both of those win outright. A spec naming
+// one issuer beside a certificate for another was signed under the certificate's.
+var KNOWN_SPEC_KEYS_ISSUER_NAMED = {
+  thisUpdate: 1, nextUpdate: 1, revoked: 1, crlNumber: 1, extensions: 1,
+};
+// Two FORMS, exactly as x509-sign has: when `issuer.cert` is present the builder takes the DN and
+// the public key from it and never reads `name` or `publicKey`, so a union signed under the
+// certificate's identity while discarding the one the caller wrote out.
+var KNOWN_ISSUER_CERT_KEYS = { key: 1, cert: 1 };
+var KNOWN_ISSUER_EXPLICIT_KEYS = { key: 1, name: 1, publicKey: 1 };
+var KNOWN_SIGN_OPTS = { digestAlgorithm: 1, pem: 1, pss: 1 };
+
 var KNOWN_IDP_KEYS = { fullName: 1, onlyContainsUserCerts: 1, onlyContainsCACerts: 1, onlyContainsAttributeCerts: 1, indirectCRL: 1 };
 
+// The fields ONE revoked-certificate entry carries. Every optional one is encoded only when
+// present, so a misspelling is missed by nothing and the entry is signed without it: `reson` for
+// `reason` lists the certificate as revoked with no reasonCode at all, and a relying party reading
+// the CRL cannot tell a caller who meant keyCompromise from one who gave no reason. The entry is
+// where this bites hardest, because the CRL as a whole still verifies. `certificateIssuer` is
+// listed because the builder DOES read it -- to refuse it with its own message.
+var KNOWN_REVOKED_KEYS = {
+  serialNumber: 1, revocationDate: 1, reason: 1, invalidityDate: 1, certificateIssuer: 1, extensions: 1,
+};
+
 // RFC 5280 sec. 5.2 -- the profile-fixed criticality of each recognized CRL extension. cRLNumber (5.2.3),
 // authorityKeyIdentifier (5.2.1), freshestCRL (5.2.6), and authorityInfoAccess (5.2.7) MUST be non-critical;
 // issuingDistributionPoint (5.2.5) and deltaCRLIndicator (5.2.4) MUST be critical. Enforced on the object
@@ -312,6 +342,12 @@ function _buildRevoked(entryList, isDelta) {
   var anyExt = false, seenSerials = {};
   var entries = entryList.map(function (e, idx) {
     if (!e || typeof e !== "object" || Buffer.isBuffer(e)) throw _err("crl/bad-input", "each revoked entry must be an object");
+    // Before any field of the entry is encoded, so an unrecognized name is a refusal rather than an
+    // entry signed without what it asked for.
+    guard.identifier.assertKnownKeys(e, KNOWN_REVOKED_KEYS, _err, "crl/bad-input", function (k) {
+      return "unknown field " + JSON.stringify(k) + " in revoked entry [" + idx +
+        "]; an entry is { serialNumber, revocationDate, reason?, invalidityDate?, extensions? }";
+    });
     if (e.serialNumber == null) throw _err("crl/bad-input", "revoked entry [" + idx + "] requires a serialNumber");
     var serialTlv = _serialInteger(e.serialNumber);
     // RFC 5280 sec. 5.1.2.6 -- a serial number identifies a certificate uniquely, so a CRL MUST NOT list the
@@ -399,11 +435,34 @@ function _sign(spec, issuer, opts) {
   opts = opts || {};
   if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("crl/bad-input", "the CRL spec must be an object");
   issuer = issuer || {};
+  // Before any field is read. A dropped key here is worse than elsewhere in the toolkit: a CRL
+  // asserts what is revoked, so the failure is a correctly signed, structurally valid CRL saying
+  // NOTHING is revoked. `revokedCertificates` earns its own hint because it is the name the parser
+  // uses for the same list -- a caller round-tripping a parsed CRL back into sign reaches for it
+  // first, and got a signed empty list.
+  // The issuer form is settled once, before either door, so the spec table matches the source the
+  // distinguished name will actually come from.
+  var byCert = issuer.cert != null, byName = issuer.name != null;
+  guard.identifier.assertKnownKeys(spec, byCert || byName ? KNOWN_SPEC_KEYS_ISSUER_NAMED : KNOWN_SPEC_KEYS,
+    _err, "crl/bad-input", function (k) {
+      return "unknown CRL spec field " + JSON.stringify(k) +
+        (k === "revokedCertificates" ? "; the producer reads `revoked` (the parser reports the same list as `revokedCertificates`)"
+          : k === "issuer" ? "; the issuer argument already names one, through " + (byCert ? "issuer.cert" : "issuer.name") +
+            ", and that is the name the CRL is signed under"
+            : "");
+    });
+  guard.identifier.assertKnownKeys(issuer, byCert ? KNOWN_ISSUER_CERT_KEYS : KNOWN_ISSUER_EXPLICIT_KEYS,
+    _err, "crl/bad-input", function (k) {
+      return "unknown issuer field " + JSON.stringify(k) + " for the " + (byCert
+        ? "certificate form; issuer.cert supplies the name and the public key, so they are not read here"
+        : "explicit form; the issuer takes { key, name, publicKey }, or { key, cert } to take both from a certificate");
+    });
+  guard.identifier.assertKnownKeys(opts, KNOWN_SIGN_OPTS, _err, "crl/bad-input", "pki.crl.sign has an unknown option ");
   if (issuer.key == null) throw _err("crl/bad-input", "a signing key (issuer.key, a PKCS#8 private key) is required");
 
   // Resolve the issuer name + signing-key SPKI. `{ cert }` supplies both; else `{ name|spec.issuer, publicKey }`.
   var issuerDer, issuerSpki, issuerCert = null;
-  if (issuer.cert != null) {
+  if (byCert) {
     issuerCert = _parseIssuerCert(issuer.cert);
     _assertIssuerCanSignCrl(issuerCert);
     issuerDer = pkiBuild.tbsNameField(issuerCert, "subject");
@@ -411,7 +470,7 @@ function _sign(spec, issuer, opts) {
   } else {
     issuerSpki = _reqDer(issuer.publicKey, "issuer.publicKey (the issuer SPKI DER)");
     _assertValidSpki(issuerSpki, "issuer.publicKey");
-    var dnSource = issuer.name != null ? issuer.name : spec.issuer;
+    var dnSource = byName ? issuer.name : spec.issuer;
     if (dnSource == null) throw _err("crl/bad-issuer", "an issuer distinguished name is required (issuer.name or spec.issuer) when no issuer.cert is given");
     issuerDer = _encodeName(dnSource);
   }

package/lib/guard-intrinsic.js

@@ -84,6 +84,10 @@ var _jsonStringify = JSON.stringify;
 var _mathFloor = Math.floor;
 var _mathCeil = Math.ceil;
 var _mathMin = Math.min;
+var _mathMax = Math.max;
+// A numeric parse a bound is then compared against: one answering a larger value widens the bound
+// the comparison was written to enforce.
+var _parseInt = parseInt;
 var _promiseResolve = Promise.resolve;
 var _promiseReject = Promise.reject;
 
@@ -102,6 +106,19 @@ var _arrSort = uncurry(Array.prototype.sort);
 var _arrConcat = uncurry(Array.prototype.concat);
 var _arrSlice = uncurry(Array.prototype.slice);
 var _arrJoin = uncurry(Array.prototype.join);
+var _arrPush = uncurry(Array.prototype.push);
+
+// The string and byte-view operations a decision is then made on. A `toUpperCase` or `toLowerCase`
+// replaced after load changes which registry row an algorithm name resolves to; a `subarray`
+// returning a different window hands the next step bytes from somewhere else in the same buffer;
+// and a radix conversion is how a key's own numbers are read back before they are compared.
+var _strToUpperCase = uncurry(String.prototype.toUpperCase);
+var _strToLowerCase = uncurry(String.prototype.toLowerCase);
+var _strIndexOf = uncurry(String.prototype.indexOf);
+var _taSubarray = uncurry(Uint8Array.prototype.subarray);
+var _abSlice = uncurry(ArrayBuffer.prototype.slice);
+var _numToString = uncurry(Number.prototype.toString);
+var _bigIntToString = uncurry(BigInt.prototype.toString);
 
 // The collection operations, uncurried. A guard's cycle-safe chain walk is a `Set` it owns, and
 // `has` is what stops it: one answering `true` ends the walk at the first prototype, so a scan that
@@ -270,6 +287,16 @@ module.exports = {
   floor: _mathFloor,
   ceil: _mathCeil,
   min: _mathMin,
+  max: _mathMax,
+  parseInt: _parseInt,
+  push: _arrPush,
+  toUpperCase: _strToUpperCase,
+  toLowerCase: _strToLowerCase,
+  stringIndexOf: _strIndexOf,
+  subarray: _taSubarray,
+  arrayBufferSlice: _abSlice,
+  numberToString: _numToString,
+  bigIntToString: _bigIntToString,
   promiseResolve: _promiseResolve,
   promiseReject: _promiseReject,
   forEach: _arrForEach,