@blamejs/pki 0.5.17 → 0.5.18

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.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/jose.js

@@ -457,7 +457,7 @@ async function verify(jws, opts) {
  *   payload: Buffer      // the raw payload octets ("" for POST-as-GET)
  *   key: CryptoKey       // the private signing key
  *   profile: string      // default "acme-outer"
- *   jwk: object          // the public JWK, when the header embeds jwk
+ *   jwk: object          // the public JWK, in kid mode (a header that embeds jwk supplies its own)
  *
  * @example
  *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
@@ -466,11 +466,38 @@ async function verify(jws, opts) {
  *     nonce: "oFvnlFP1wIhRlYS2jTaXbA", url: "https://ca.example/acme/new-acct" };
  *   var jws = await pki.jose.sign({ protected: hdr, payload: Buffer.from("{}"), key: priv });
  */
+// The public JWK has two sources and the embedded one wins, so opts.jwk is read only in kid mode.
+// Supplied alongside a header that embeds its own, it selected nothing: the signature parameters
+// came from the header's key while the caller had named a different one.
 var _SIGN_KEYS = { protected: 1, payload: 1, key: 1, jwk: 1, profile: 1 };
+var _SIGN_KEYS_EMBEDDED_JWK = { protected: 1, payload: 1, key: 1, profile: 1 };
 async function sign(opts) {
   opts = opts || {};
+  // The options are checked BEFORE the header is touched. Serializing it runs the caller's own code
+  // -- a toJSON, an accessor -- and that code can delete an option from the very bag being checked,
+  // so a misspelling reached the door already removed and the message went out signed.
   guard.identifier.assertKnownKeys(opts, _SIGN_KEYS, E, "jose/bad-input", "unknown pki.jose.sign option ");
-  var header = opts.protected;
+  // The header is then serialized ONCE, and every read below comes from a snapshot of those exact
+  // bytes: the header validated, the header embedded in the JWS and the key confirmed against the
+  // produced signature are then all the same values. Read live, a caller getter answers each of
+  // those questions separately -- assertPublicJwk sees a public JWK while the bytes that ship carry
+  // the private one, and the door sees a jwk-mode header while the signer sees a kid-mode one.
+  var headerJson;
+  try { headerJson = JSON.stringify(opts.protected); }
+  catch (e) { throw E("jose/bad-header", "the protected header must be JSON-serializable", e); }
+  // Read back through the same bounded reader a received JWS goes through, so a header this side
+  // produces is held to the caps and the duplicate-member rule the other side enforces.
+  var headerBytes = headerJson === undefined ? null : Buffer.from(headerJson, "utf8");
+  var header = headerBytes === null ? opts.protected : parseJson(headerBytes);
+  // Which of the two key sources is in force is known only once the header has been read, so the
+  // narrower table runs here. It re-walks the bag, which also catches a name that code added.
+  var embedsJwk = !!(header && typeof header === "object" && header.jwk);
+  if (embedsJwk) {
+    guard.identifier.assertKnownKeys(opts, _SIGN_KEYS_EMBEDDED_JWK, E, "jose/bad-input", function (k) {
+      return "unknown pki.jose.sign option " + JSON.stringify(k) +
+        (k === "jwk" ? "; the protected header already embeds the public JWK" : "");
+    });
+  }
   var payload = opts.payload;
   if (!Buffer.isBuffer(payload)) throw E("jose/bad-input", "payload must be a Buffer (empty Buffer for POST-as-GET)");
   // Re-view before the length===0 fast-path: a DETACHED payload reads as zero-length
@@ -494,7 +521,7 @@ async function sign(opts) {
   // also PUBLISHED to the server, so it must be public-only: an accidentally exported
   // private JWK must never be serialized into the protected header.
   if (header.jwk) { _assertKeyType(checked.algRow, header.jwk); assertPublicJwk(header.jwk); }
-  var protectedB64 = b64uEncode(Buffer.from(JSON.stringify(header), "utf8"));
+  var protectedB64 = b64uEncode(headerBytes);   // the exact bytes every check above read
   var payloadB64 = payload.length === 0 ? "" : b64uEncode(payload);
   var signingInput = Buffer.from(protectedB64 + "." + payloadB64, "ascii");
   var jwk = header.jwk || opts.jwk || {};

package/lib/pkcs12-build.js

@@ -43,6 +43,7 @@ var x509 = require("./schema-x509");
 var schemaCrl = require("./schema-crl");
 var key = require("./key");
 var cms = require("./cms-verify");   // pki.cms.sign (build the id-signedData authSafe) + pki.cms.verify (the open integrity gate) + cms.encrypt (the privacy envelope)
+var cmsSign = require("./cms-sign");   // the signer-descriptor field tables, for the integrity signers this verb authors
 var cmsDecrypt = require("./cms-decrypt");   // the @internal decryptEnvelopedData seam -- opens a privacy safe off the pkcs12 parser's already-walked (BER-capable) EnvelopedData node
 var schemaPkcs12 = require("./schema-pkcs12");
 var pkix = require("./schema-pkix");
@@ -116,6 +117,91 @@ var _MISSING_PASSWORD = "a password must be a string, Buffer, or Uint8Array -- a
 // Every field opts.integrity reads. Adding one here is the only way to make it accepted, so a
 // capability cannot arrive with its option silently ignored at this boundary.
 var _INTEGRITY_OPTS = { mode: 1, signer: 1, signers: 1, certificates: 1, sid: 1, signingTime: 1 };
+// The two caller-owned objects pki.pkcs12.build reads. The spec keys are what _normalizeSpec
+// consumes -- the explicit `safeContents` form and the `{ key, cert, ca }` shorthand -- so the table
+// is derived from that function rather than from the doc block. opts.integrity already had its own
+// door; the objects containing it did not, so a misspelled `certificates` at the top level was
+// dropped and the store built without them.
+// The spec comes in two mutually exclusive FORMS, so it is checked against the one it selects.
+// `_normalizeSpec` returns `spec.safeContents` the moment it is an array and never looks at the
+// shorthand fields, so a union accepted `{ safeContents: [...], key }` and built a store with the
+// key silently absent -- the same omission the door exists to refuse, reached by mixing the forms
+// rather than by misspelling one.
+var _BUILD_SPEC_FULL_KEYS = { safeContents: 1 };
+var _BUILD_SPEC_SHORTHAND_KEYS = { key: 1, cert: 1, ca: 1, friendlyName: 1, localKeyId: 1 };
+// `recipientCerts` selects the privacy recipients and is read by _normalizeSpec, which _build hands
+// opts to -- it belongs here even though _build never names it. The three verbs this module exports
+// have disjoint option sets (verifyMac reads maxIterations / recipientKey / allowUnauthenticated,
+// open reads signerCerts / keys / importAlgorithm), so build gets its own table rather than a
+// shared one that would admit theirs.
+// Per spec FORM, because `recipientCerts` is read only by the shorthand branch of _normalizeSpec.
+// Under the full form it is read by nothing: a caller who put a plaintext key bag in safeContents
+// and supplied recipientCerts expecting public-key privacy got an id-data safe holding the private
+// key in cleartext. The full form builds its own safes, so privacy there is `recipients` on the
+// entry.
+var _BUILD_OPTS_FULL = { integrity: 1, mac: 1, password: 1, pem: 1 };
+var _BUILD_OPTS_SHORTHAND = { integrity: 1, mac: 1, password: 1, pem: 1, recipientCerts: 1 };
+// The fields a safeContents entry carries. This entry is where the PRIVACY directive lives, which
+// makes an unrecognized name here the costliest misspelling in the format: a misspelled `encrypt`
+// is neither present nor falsy, so it passes the present-but-falsy guard in _buildAuthSafeElement,
+// no privacy is selected, and the safe goes out as plaintext id-data -- an unshrouded keyBag in the
+// clear, inside a PFX whose MAC still verifies and which opens without complaint.
+// Per privacy branch, because the branches read different fields:
+// `contentEncryptionAlgorithm` is the public-key branch's content cipher and is read by NOTHING on
+// a password safe, whose cipher comes from `encrypt.cipher`. A union accepted an explicit cipher
+// request on a password safe and encrypted under the default anyway.
+var _SAFE_RECIPIENTS_KEYS = { bags: 1, recipients: 1, contentEncryptionAlgorithm: 1 };
+var _SAFE_PASSWORD_KEYS = { bags: 1, encrypt: 1 };
+var _SAFE_PLAINTEXT_KEYS = { bags: 1 };
+// The fields a bag carries, PER TYPE rather than as one union. A union would admit a field that
+// this bag's own arm never reads, which is worse here than a dropped attribute: `encrypt` on a
+// `key` bag is read by nothing, so the private key is emitted as a plaintext keyBag while the
+// caller supplied an explicit encryption directive and the outer MAC gives integrity only. Naming
+// the fields per type makes that combination a refusal instead of a silent downgrade. Written out
+// per type rather than merged at load, so each row reads as the whole contract for that bag.
+var _BAG_KEYS_BY_TYPE = {
+  key:          { type: 1, friendlyName: 1, localKeyId: 1, key: 1 },
+  shroudedKey:  { type: 1, friendlyName: 1, localKeyId: 1, key: 1, encrypt: 1 },
+  cert:         { type: 1, friendlyName: 1, localKeyId: 1, cert: 1 },
+  crl:          { type: 1, friendlyName: 1, localKeyId: 1, crl: 1 },
+  secret:       { type: 1, friendlyName: 1, localKeyId: 1, secretTypeId: 1, secretValue: 1 },
+  safeContents: { type: 1, friendlyName: 1, localKeyId: 1, nested: 1 },
+};
+// The PBE descriptor both privacy levels share (_pbeOpts is the one place it is read, so one door
+// covers the safe-level and bag-level spellings). A misspelled parameter reverts to the built-in
+// default, so a caller who asked for a stronger KDF or a different cipher silently gets neither.
+var _ENCRYPT_KEYS = { password: 1, cipher: 1, salt: 1, iterations: 1, prf: 1 };
+// The MAC descriptor. Every field has a default, so a misspelled one reverts to the shipped value:
+// a caller who asked for a higher iteration count, a different hash or a longer key gets the
+// default instead, and the store carries no record of which was used.
+// Per MAC algorithm: the classic Appendix B key derivation produces a key at the hash's own output
+// length and has no keyLength to set, so admitting one there took an explicit security parameter and
+// emitted the same MAC as a call that never named it. Only PBMAC1 (RFC 9579) derives to a length.
+var _MAC_KEYS = { algorithm: 1, hash: 1, salt: 1, iterations: 1, keyLength: 1, password: 1 };
+var _MAC_KEYS_HMAC = { algorithm: 1, hash: 1, salt: 1, iterations: 1, password: 1 };
+var _MAC_KEYS_PBMAC1 = { algorithm: 1, hash: 1, salt: 1, iterations: 1, keyLength: 1, password: 1 };
+// The reading verbs take their own option sets, disjoint from build's. `maxIterations` is the one
+// that matters most: it caps the work a hostile store can demand, so a misspelling restores the
+// built-in ceiling and the caller's tighter bound is never applied.
+// The table is what the CALL reads, including through its delegations -- and those cross a module
+// boundary here. recipientKey / recipientCert are read by _openEncryptedSafe; `recipientIndex` is
+// read by cms-decrypt's decryptEnvelopedData, which _openEncryptedSafe hands this whole options
+// object to, so a table built from this file's own `opts.` reads alone would refuse a documented
+// option and break selecting a recipient by index in a multi-recipient store.
+//
+// One table here, not one per branch, and the distinction is who selects the branch. A builder's
+// options are checked against the form the CALLER chose, because a field the chosen form never
+// reads is a request that silently did not happen. Reading a store, the branch is chosen by the
+// BYTES: which integrity mode it carries, and whether a safe is password- or recipient-encrypted,
+// are not known until it is parsed. These options are the policy a caller declares in advance for
+// whatever the store turns out to be, so one that goes unread means the store did not need it --
+// signerCerts on a MAC'd store, recipientKey on one with no enveloped safe. Refusing those would
+// make a correct, store-agnostic call fail on the shape of its input.
+var _OPEN_OPTS = {
+  allowUnauthenticated: 1, importAlgorithm: 1, keys: 1, maxIterations: 1, signerCerts: 1,
+  recipientKey: 1, recipientCert: 1, recipientIndex: 1,
+};
+var _VERIFY_MAC_OPTS = { maxIterations: 1 };
 
 // The same encoding, reporting ownership, mirroring pbes2.passwordBytesOwned. A caller-supplied
 // Buffer is returned as-is and is borrowed: clearing it would destroy the caller's own credential,
@@ -280,6 +366,14 @@ function _safeBag(bagName, bagValueDer, bag) {
 
 function _buildBag(bag, opts, depth) {
   if (!bag || typeof bag !== "object") throw _err("pkcs12/bad-input", "each bag must be an object with a type");
+  // Checked against THIS type's table. An unrecognized type falls through to the switch below,
+  // which is the one place that names the permitted set.
+  if (guard.intrinsic.hasOwn(_BAG_KEYS_BY_TYPE, bag.type)) {
+    guard.identifier.assertKnownKeys(bag, _BAG_KEYS_BY_TYPE[bag.type], _err, "pkcs12/bad-input", function (k) {
+      return "unknown field " + JSON.stringify(k) + " on a " + JSON.stringify(bag.type) +
+        " bag; that field is not read for this bag type";
+    });
+  }
   switch (bag.type) {
     case "key": {
       var keyDer = _coerceDer(bag.key, "keyBag key");
@@ -290,9 +384,12 @@ function _buildBag(bag, opts, depth) {
       var kDer = _coerceDer(bag.key, "shroudedKey key");
       try { pkcs8.parse(kDer); } catch (e2) { throw _err("pkcs12/bad-input", "shroudedKey key is not a well-formed PKCS#8 PrivateKeyInfo", e2); }
       var enc = bag.encrypt || {};
+      // The descriptor is checked BEFORE its password is read, so no field of an object carrying an
+      // unrecognized name reaches the KDF -- the same order the safe-level path uses below.
+      var bagPbe = _pbeOpts(enc);
       var pw = _pbePasswordOwned(enc.password != null ? enc.password : opts.password);
       var r;
-      try { r = pbes2.pbes2Encrypt(pw.bytes, kDer, _pbeOpts(enc), _err, "pkcs12"); }
+      try { r = pbes2.pbes2Encrypt(pw.bytes, kDer, bagPbe, _err, "pkcs12"); }
       finally { _wipePw(pw); }
       return _safeBag("pkcs8ShroudedKeyBag", b.sequence([r.algId, b.octetString(r.ct)]), bag);   // EncryptedPrivateKeyInfo
     }
@@ -349,6 +446,10 @@ function _reqDer(input, label) {
 }
 
 function _pbeOpts(enc) {
+  guard.identifier.assertKnownKeys(enc, _ENCRYPT_KEYS, _err, "pkcs12/bad-input", function (k) {
+    return "unknown encrypt field " + JSON.stringify(k) +
+      "; the PBE descriptor is { password?, cipher?, salt?, iterations?, prf? }";
+  });
   var cipher = CIPHER_NAME[enc.cipher || "aes-256-cbc"];
   if (!cipher) throw _err("pkcs12/bad-input", "unsupported PBES2 cipher " + JSON.stringify(enc.cipher) + " (aes-128-cbc / aes-192-cbc / aes-256-cbc)");
   return {
@@ -379,6 +480,18 @@ async function _buildAuthSafeElement(sc, opts) {
   var hasRecipients = sc.recipients !== undefined;
   var hasEncrypt = sc.encrypt !== undefined;
   if (hasEncrypt && hasRecipients) throw _err("pkcs12/bad-input", "a safeContents cannot combine encrypt (password) and recipients (public-key) -- one ContentInfo is one privacy type (RFC 7292 sec. 4.1)");
+  // Checked against the branch the directive above selects, and BEFORE that branch reads anything.
+  // The branches read different fields: `contentEncryptionAlgorithm` is the public-key branch's
+  // cipher and is read by nothing on a password safe, whose cipher comes from `encrypt.cipher` --
+  // so a union accepted an explicit cipher request on a password safe and encrypted under the
+  // default anyway.
+  guard.identifier.assertKnownKeys(sc, hasRecipients ? _SAFE_RECIPIENTS_KEYS : (hasEncrypt ? _SAFE_PASSWORD_KEYS : _SAFE_PLAINTEXT_KEYS),
+    _err, "pkcs12/bad-input", function (k) {
+      return "unknown safeContents field " + JSON.stringify(k) + " for a " +
+        (hasRecipients ? "public-key safe; it takes { bags, recipients, contentEncryptionAlgorithm? }"
+          : hasEncrypt ? "password safe; it takes { bags, encrypt } and its cipher comes from encrypt.cipher"
+            : "plaintext safe; it takes { bags }, and a privacy directive must be encrypt or recipients");
+    });
   var safeContentsDer = _buildSafeContents(sc.bags || [], opts, 0);
   if (hasRecipients) {
     if (!Array.isArray(sc.recipients) || !sc.recipients.length) throw _err("pkcs12/bad-input", "safeContents.recipients must be a non-empty array of recipient descriptors (RFC 5652 sec. 6.1)");
@@ -401,9 +514,12 @@ async function _buildAuthSafeElement(sc, opts) {
     return b.sequence([b.oid(O("data")), b.explicit(0, b.octetString(safeContentsDer))]);
   }
   if (!sc.encrypt || typeof sc.encrypt !== "object") throw _err("pkcs12/bad-input", "safeContents.encrypt must be an object { password? } (RFC 7292 sec. 5.1) -- omit it entirely for a plaintext safe");
+  // Checked before the password is read, so no field of a descriptor carrying an unrecognized name
+  // reaches the KDF.
+  var safePbe = _pbeOpts(sc.encrypt);
   var pw = _pbePasswordOwned(sc.encrypt.password != null ? sc.encrypt.password : opts.password);
   var r;
-  try { r = pbes2.pbes2Encrypt(pw.bytes, safeContentsDer, _pbeOpts(sc.encrypt), _err, "pkcs12"); }
+  try { r = pbes2.pbes2Encrypt(pw.bytes, safeContentsDer, safePbe, _err, "pkcs12"); }
   finally { _wipePw(pw); }
   var eci = b.sequence([b.oid(O("data")), r.algId, b.contextPrimitive(0, r.ct)]);   // EncryptedContentInfo, [0] IMPLICIT ct
   var encData = b.sequence([b.integer(0n), eci]);                                    // EncryptedData { version 0, eci }
@@ -464,11 +580,26 @@ async function _buildMacData(macOpts, sharedPassword, authSafeDer) {
 // Accept the OpenSSL-style convenience form ({ key, cert, ca, friendlyName, localKeyId }) or the full
 // inverse-of-parse form ({ safeContents: SafeContentsSpec[] }). The convenience form -> one privacy safe of
 // PBES2 cert bags + one shrouded-key safe.
-function _normalizeSpec(spec, opts) {
-  if (spec && Array.isArray(spec.safeContents)) return spec.safeContents;
+// Which of the two forms a spec is gets decided ONCE, and that one decision is what both the door
+// and this normalizer act on. Decided separately they can disagree: two spellings of "is this the
+// full form" drift apart on their own, and a caller getter returning an array to one and something
+// else to the other makes them disagree on demand -- the full form checked while the shorthand form
+// is the one assembled.
+function _specForm(spec) {
+  var isObject = !!spec && typeof spec === "object" && !Buffer.isBuffer(spec);
+  var safeContents = isObject ? spec.safeContents : null;
+  var full = guard.intrinsic.isArray(safeContents);
+  return { isObject: isObject, full: full, safeContents: full ? safeContents : null };
+}
+
+function _normalizeSpec(spec, opts, form) {
+  if (form.full) return form.safeContents;
   if (spec && (spec.key != null || spec.cert != null)) {
-    var enveloped = opts.recipientCerts != null;
-    if (enveloped && (!Array.isArray(opts.recipientCerts) || !opts.recipientCerts.length)) throw _err("pkcs12/bad-input", "opts.recipientCerts must be a non-empty array of recipient certificates");
+    // One read of the caller's array, so the emptiness check and the recipients built from it cannot
+    // be handed different values.
+    var recipientCerts = opts.recipientCerts;
+    var enveloped = recipientCerts != null;
+    if (enveloped && (!guard.intrinsic.isArray(recipientCerts) || !recipientCerts.length)) throw _err("pkcs12/bad-input", "opts.recipientCerts must be a non-empty array of recipient certificates");
     var certBags = [];
     if (spec.cert != null) certBags.push({ type: "cert", cert: spec.cert, friendlyName: spec.friendlyName, localKeyId: spec.localKeyId });
     if (spec.ca != null && !Array.isArray(spec.ca)) throw _err("pkcs12/bad-input", "spec.ca must be an array of certificates");
@@ -480,7 +611,7 @@ function _normalizeSpec(spec, opts) {
       // caller password, if any, remains the MAC (integrity) password; privacy and integrity are independent.
       var bags = certBags.slice();
       if (spec.key != null) bags.push({ type: "key", key: spec.key, friendlyName: spec.friendlyName, localKeyId: spec.localKeyId });
-      sc.push({ recipients: opts.recipientCerts.map(function (c) { return { cert: c }; }), bags: bags });
+      sc.push({ recipients: recipientCerts.map(function (c) { return { cert: c }; }), bags: bags });
       return sc;
     }
     if (certBags.length) sc.push({ encrypt: { password: opts.password }, bags: certBags });
@@ -512,7 +643,7 @@ function _normalizeSpec(spec, opts) {
  *
  * @opts
  *   - `password` -- the shared privacy + integrity password (string / Buffer / Uint8Array).
- *   - `mac` -- `false` for a MAC-less store, or `{ algorithm: 'hmac'(default)|'pbmac1', hash: 'sha256'(default)|'sha1'|'sha384'|'sha512', salt?, iterations?, keyLength? }`.
+ *   - `mac` -- `false` for a MAC-less store, or `{ algorithm: 'hmac'(default)|'pbmac1', hash: 'sha256'(default)|'sha1'|'sha384'|'sha512', salt?, iterations? }`. `keyLength` is a `pbmac1` field: the classic Appendix B derivation produces a key at the hash's own output length, and naming one under `hmac` is refused.
  *   - `integrity` -- `{ mode: 'public-key', signer: { cert, key, digestAlgorithm?, pss? } | signers: [ ... ], sid?, signingTime?, certificates? }` for public-key integrity (a CMS SignedData authSafe over any `pki.cms.sign` signer algorithm, no MacData). Combining it with a truthy `mac` is rejected.
  *   - `recipientCerts` -- (public-key privacy convenience) `[certDer|PEM, ...]`; the convenience-form cert + key are placed in one recipient-enveloped safe (a plaintext keyBag). For the full form, set per-`safeContents` `recipients: [{ cert }, ...]` -- CERTIFICATE recipients only (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM, dispatched off the cert key); a password or KEK recipient is not public-key privacy and is rejected -- with an optional `contentEncryptionAlgorithm` (`aes-128|192|256-cbc`, default 256; GCM/AEAD rejected). `encrypt` (password) and `recipients` (public-key) on the same safe is rejected; privacy is independent of integrity.
  *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
@@ -541,6 +672,26 @@ function build(spec, opts) {
 
 async function _build(spec, opts) {
   opts = opts || {};
+  // Before the spec is normalized, so a misspelled bag field is a refusal rather than a store built
+  // without it. A PKCS#12 file that silently omits the certificate or the key a caller asked for
+  // looks well-formed and opens cleanly; the omission surfaces wherever it is later imported.
+  var form = _specForm(spec);
+  if (form.isObject) {
+    guard.identifier.assertKnownKeys(spec, form.full ? _BUILD_SPEC_FULL_KEYS : _BUILD_SPEC_SHORTHAND_KEYS,
+      _err, "pkcs12/bad-input", function (k) {
+        return "unknown PKCS#12 spec field " + JSON.stringify(k) + " for the " +
+          (form.full ? "safeContents form; the shorthand fields belong to { key, cert, ca } and are not read here"
+                     : "shorthand form; pass safeContents instead to build the safes yourself");
+      });
+  }
+  // The options answer to the same form: recipientCerts is read only by the shorthand branch.
+  guard.identifier.assertKnownKeys(opts, form.full ? _BUILD_OPTS_FULL : _BUILD_OPTS_SHORTHAND, _err, "pkcs12/bad-input",
+    function (k) {
+      return "pki.pkcs12.build has an unknown option " + JSON.stringify(k) +
+        (form.full && k === "recipientCerts"
+          ? " for the safeContents form; the full form carries privacy per entry, as safeContents[i].recipients"
+          : "");
+    });
   // The integrity mode is checked against the permitted set rather than compared to one literal.
   // Compared, any other spelling reads as "not public-key" and silently selects password integrity,
   // dropping the signer with it: a caller who wrote "publicKey" gets a MAC where they asked for a
@@ -556,7 +707,7 @@ async function _build(spec, opts) {
   // RFC 7292 sec. 4: public-key integrity OMITS MacData entirely -- a caller combining opts.mac with it is a
   // config-time reject (the self-check re-parse would otherwise fail the coherence rule anyway).
   if (pubKey && opts.mac != null && opts.mac !== false) throw _err("pkcs12/bad-integrity-mode", "public-key integrity has no MacData -- do not combine opts.mac with opts.integrity.mode 'public-key' (RFC 7292 sec. 4)");
-  var safeContentsSpecs = _normalizeSpec(spec, opts);
+  var safeContentsSpecs = _normalizeSpec(spec, opts, form);
   if (!Array.isArray(safeContentsSpecs) || !safeContentsSpecs.length) throw _err("pkcs12/bad-input", "the store has no safe contents");
   var elements = [];
   for (var i = 0; i < safeContentsSpecs.length; i++) elements.push(await _buildAuthSafeElement(safeContentsSpecs[i], opts));
@@ -569,13 +720,48 @@ async function _build(spec, opts) {
     // password) provides the integrity, and there is NO MacData. Compose pki.cms.sign -- so every cms.sign
     // signer algorithm (RSA / ECDSA / EdDSA / ML-DSA / SLH-DSA / composite) ships for free.
     var ig = opts.integrity;
+    // `signer` is the one-signer spelling of `signers`, and the list wins outright, so supplying
+    // both signed the store under the list alone and dropped the single signer without a word.
+    if (ig.signers != null && ig.signer != null) throw _err("pkcs12/bad-input", "supply exactly one of opts.integrity.signer or opts.integrity.signers, not both");
     var signers = ig.signers != null ? ig.signers : (ig.signer != null ? [ig.signer] : null);
     if (!Array.isArray(signers) || !signers.length) throw _err("pkcs12/bad-input", "public-key integrity requires opts.integrity.signer or opts.integrity.signers (a cms.sign signer descriptor)");
+    // The signer descriptors are authoring input for this store, so they answer to the same rule as
+    // every other field the caller writes here, against the form each one selects. Every field
+    // beyond the identity has a default: without the door a misspelled `pss` or `digestAlgorithm`
+    // signed the store under PKCS#1 with SHA-256 while the caller had asked for something else, and
+    // the store records only what was used, never what was requested.
+    for (var sx = 0; sx < signers.length; sx++) {
+      var sd = signers[sx];
+      if (sd == null || typeof sd !== "object" || Buffer.isBuffer(sd)) throw _err("pkcs12/bad-input", "each opts.integrity signer must be a descriptor object");
+      var keyOnly = sd.cert == null && sd.spki != null;
+      guard.identifier.assertKnownKeys(sd, keyOnly ? cmsSign.KNOWN_SIGNER_KEY_ONLY_KEYS : cmsSign.KNOWN_SIGNER_CERT_KEYS,
+        _err, "pkcs12/bad-input", function (k) {
+          return "unknown opts.integrity signer field " + JSON.stringify(k) + " for the " + (keyOnly
+            ? "key-only form; it takes { key, spki, keyIdentifier } plus the signature parameters"
+            : "certificate form; it takes { key, cert } plus the signature parameters");
+        });
+    }
     var authSafeCi = await cms.sign(authSafeDer, signers, { eContentType: "data", detached: false, certificates: ig.certificates !== false, sid: ig.sid, signingTime: ig.signingTime });
     pfx = b.sequence([b.integer(3n), b.raw(authSafeCi)]);   // PFX ::= SEQUENCE { version v3, authSafe (id-signedData) } -- NO MacData
   } else {
     var pfxChildren = [b.integer(3n), b.sequence([b.oid(O("data")), b.explicit(0, b.octetString(authSafeDer))])];
-    if (opts.mac != null && opts.mac !== false && typeof opts.mac !== "object") throw _err("pkcs12/bad-input", "opts.mac must be false or a { algorithm, hash, salt, iterations, keyLength } object");
+    // An array passes `typeof x === "object"`, and its own names are indices no table lists, so an
+    // array reached _buildMacData as an empty descriptor and produced the DEFAULT MAC. Excluded by
+    // the same test opts.integrity already applies, read through the load-time capture so a
+    // replaced Array.isArray cannot reopen it.
+    if (opts.mac != null && opts.mac !== false && (typeof opts.mac !== "object" || guard.intrinsic.isArray(opts.mac))) throw _err("pkcs12/bad-input", "opts.mac must be false or a { algorithm, hash, salt, iterations, keyLength } object");
+    if (opts.mac != null && opts.mac !== false) {
+      // The algorithm selects the derivation, so the table that runs is the one belonging to it.
+      // An unrecognized spelling keeps the union; _buildMacData refuses it by name a moment later.
+      var macAlg = opts.mac.algorithm == null ? "hmac" : opts.mac.algorithm;
+      var macKeys = macAlg === "hmac" ? _MAC_KEYS_HMAC : macAlg === "pbmac1" ? _MAC_KEYS_PBMAC1 : _MAC_KEYS;
+      guard.identifier.assertKnownKeys(opts.mac, macKeys, _err, "pkcs12/bad-input", function (k) {
+        return "opts.mac has an unknown option " + JSON.stringify(k) +
+          (macAlg === "hmac" && k === "keyLength"
+            ? " for the classic HMAC algorithm; its key is derived at the hash's own output length, and only pbmac1 takes a keyLength"
+            : "");
+      });
+    }
     if (opts.mac !== false) pfxChildren.push(await _buildMacData(opts.mac || {}, opts.password, authSafeDer));
     pfx = b.sequence(pfxChildren);
   }
@@ -612,6 +798,9 @@ async function _build(spec, opts) {
  *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
  */
 async function verifyMac(pfx, password, opts) {
+  if (opts != null && typeof opts === "object" && !Buffer.isBuffer(opts)) {
+    guard.identifier.assertKnownKeys(opts, _VERIFY_MAC_OPTS, _err, "pkcs12/bad-input", "pki.pkcs12.verifyMac has an unknown option ");
+  }
   return _verifyMacOfStore(_storeFromBytes(pfx), password, opts);
 }
 
@@ -715,7 +904,8 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  */
 async function open(pfx, password, opts) {
   opts = opts || {};
-  if (opts.maxIterations != null && (typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations)) {
+  guard.identifier.assertKnownKeys(opts, _OPEN_OPTS, _err, "pkcs12/bad-input", "pki.pkcs12.open has an unknown option ");
+  if (opts.maxIterations != null &&(typeof opts.maxIterations !== "number" || !isFinite(opts.maxIterations) || opts.maxIterations < 1 || Math.floor(opts.maxIterations) !== opts.maxIterations)) {
     throw _err("pkcs12/bad-input", "maxIterations must be a positive integer");
   }
   var m = _storeFromBytes(pfx);

package/lib/tsp-sign.js

@@ -142,9 +142,38 @@ function sign(messageImprint, tsa, opts) {
   ], _sign);
 }
 
+// The three caller-owned objects pki.tsp.sign reads. A dropped option here is a token that quietly
+// lacks what was asked for -- `odering` for `ordering` emitted a token with the ordering flag unset,
+// which is a claim about the timestamp's orderability that the caller believes they made.
+// The TSA is gated too, and the reason it needs to be is not the one it looks like. Both fields it
+// carries are REQUIRED, so a MISSPELLING of either is already refused for what it leaves missing --
+// but that is only half the class. A name belonging on the OPTIONS, written on the TSA instead, is
+// read by nothing here: `ordering` placed on the TSA emits a token the same size as one that never
+// asked for it, with the flag unset, while the caller believes they set it. Requiring the argument
+// to carry only what it reads is what closes that, so all three caller-owned arguments answer the
+// same question -- is this a name I read? -- rather than two of them answering it.
+var _TSA_KEYS = { cert: 1, key: 1 };
+var _IMPRINT_KEYS = { hashAlgorithm: 1, hashedMessage: 1 };
+var _SIGN_OPTS = {
+  policy: 1, serialNumber: 1, genTime: 1, nonce: 1, accuracy: 1, ordering: 1, sid: 1,
+  digestAlgorithm: 1, certHashAlgorithm: 1, additionalSignedAttributes: 1, pss: 1, pem: 1,
+};
+
 function _sign(messageImprint, tsa, opts) {
   opts = opts || {};
+  if (messageImprint && typeof messageImprint === "object" && !Buffer.isBuffer(messageImprint)) {
+    guard.identifier.assertKnownKeys(messageImprint, _IMPRINT_KEYS, _err, "tsp/bad-input", function (k) {
+      return "unknown messageImprint field " + JSON.stringify(k) + " (the imprint is { hashAlgorithm, hashedMessage })";
+    });
+  }
+  guard.identifier.assertKnownKeys(opts, _SIGN_OPTS, _err, "tsp/bad-input", "pki.tsp.sign has an unknown option ");
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.sign options must be an object");
+  if (tsa && typeof tsa === "object" && !Buffer.isBuffer(tsa)) {
+    guard.identifier.assertKnownKeys(tsa, _TSA_KEYS, _err, "tsp/bad-input", function (k) {
+      return "unknown TSA field " + JSON.stringify(k) +
+        " (the TSA is { cert, key }; a signing option belongs in the third argument)";
+    });
+  }
   var mi = messageImprint || {};
   if (!mi.hashAlgorithm || !NODE_DIGEST[mi.hashAlgorithm]) throw _err("tsp/unsupported-algorithm", "messageImprint.hashAlgorithm must be a supported hash name");
   if (!Buffer.isBuffer(mi.hashedMessage) && !(mi.hashedMessage instanceof Uint8Array)) throw _err("tsp/bad-input", "messageImprint.hashedMessage must be a Buffer");
@@ -187,7 +216,17 @@ function _sign(messageImprint, tsa, opts) {
 // Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] INTEGER (1..999) OPTIONAL,
 // micros [1] INTEGER (1..999) OPTIONAL } (RFC 3161 sec. 2.4.2). seconds is a non-negative
 // integer; millis and micros MUST each be in 1..999 -- enforced before encoding.
+// Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] OPTIONAL, micros [1] OPTIONAL }
+// (RFC 3161 sec. 2.4.2). All three are OPTIONAL and encoded only when present, so a misspelling is
+// missed by nothing: `milis` emitted an EMPTY Accuracy that parses back as zero seconds, millis and
+// micros, and the token then understates its own precision -- a claim about the timestamp that the
+// caller believed they had made.
+var _ACCURACY_KEYS = { seconds: 1, millis: 1, micros: 1 };
+
 function _accuracy(a) {
+  guard.identifier.assertKnownKeys(a, _ACCURACY_KEYS, _err, "tsp/bad-input", function (k) {
+    return "unknown accuracy field " + JSON.stringify(k) + "; Accuracy is { seconds?, millis?, micros? }";
+  });
   var f = [];
   if (a.seconds != null) {
     var s = Number(a.seconds);
@@ -264,10 +303,29 @@ function _assertImprint(mi) {
  *   var sha256Digest = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello")));
  *   var req = pki.tsp.request({ hashAlgorithm: "sha256", hashedMessage: sha256Digest }, { nonce: 0x0102030405060708n, certReq: true });
  */
+// The options pki.tsp.request encodes into the TimeStampReq. Every one is OPTIONAL in the
+// structure, so a misspelled name is missed by nothing and the request goes out claiming less than
+// was asked for. `nonce` is the one that costs most: misspelled, the request carries no nonce at
+// all, and the caller matches a reply against a replay defense that was never asked for.
+var _REQUEST_OPTS = { reqPolicy: 1, nonce: 1, certReq: 1, extensions: 1, pem: 1 };
+
 function request(messageImprint, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.request options must be an object");
+  guard.identifier.assertKnownKeys(opts, _REQUEST_OPTS, _err, "tsp/bad-input", "pki.tsp.request has an unknown option ");
   var mi = messageImprint || {};
+  // The same table pki.tsp.sign holds its imprint to. The request's own options live in the second
+  // argument, so `nonce` written on the imprint reaches nothing and the request goes out without
+  // the replay defense the caller believes they asked for.
+  // The same table pki.tsp.sign holds its imprint to. The request's own options live in the second
+  // argument, so `nonce` written on the imprint reaches nothing and the request goes out without
+  // the replay defense the caller believes they asked for.
+  if (mi && typeof mi === "object" && !Buffer.isBuffer(mi)) {
+    guard.identifier.assertKnownKeys(mi, _IMPRINT_KEYS, _err, "tsp/bad-input", function (k) {
+      return "unknown messageImprint field " + JSON.stringify(k) +
+        " (the imprint is { hashAlgorithm, hashedMessage }; a request option belongs in the second argument)";
+    });
+  }
   _assertImprint(mi);
   var imprint = b.sequence([_hashAlgId(mi.hashAlgorithm), b.octetString(Buffer.from(mi.hashedMessage))]);
   // TimeStampReq: version(1), messageImprint, then OPTIONAL reqPolicy / nonce / certReq /
@@ -349,9 +407,15 @@ function parseRequest(input) { return schemaTsp.parseRequest(input); }
  *   var resp = pki.tsp.response(token, {});                                  // granted
  *   var rej  = pki.tsp.response(null, { status: 2, failInfo: ["badAlg"] });  // rejection
  */
+// The options pki.tsp.response encodes into the TimeStampResp. `status` carries the verdict and
+// defaults to granted(0), so a misspelled name does not lose a detail -- it INVERTS the answer: a
+// TSA refusing a request emits a granted response instead, over a token it did mean to withhold.
+var _RESPONSE_OPTS = { status: 1, statusString: 1, failInfo: 1, pem: 1 };
+
 function response(token, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.response options must be an object");
+  guard.identifier.assertKnownKeys(opts, _RESPONSE_OPTS, _err, "tsp/bad-input", "pki.tsp.response has an unknown option ");
   var status = opts.status == null ? 0 : Number(opts.status);
   if (!Number.isInteger(status) || status < 0 || status > 5) throw _err("tsp/bad-input", "PKIStatus must be an integer in 0..5 (RFC 3161 sec. 2.4.2)");
   var granted = status === 0 || status === 1;

package/lib/x509-sign.js

@@ -53,6 +53,27 @@ var OID_SKI = O("subjectKeyIdentifier");
 
 // The recognized keys of the `extensions` spec object; an unknown key is a typo and throws at
 // config-time (a custom extension is passed as pre-encoded DER via the array form).
+// The three caller-owned objects pki.x509.sign reads, each with its own door. A key nothing here
+// names is a typo or a misplaced argument, and the failure it causes is invisible: the certificate
+// builds, signs, and simply does not carry what was asked for. `spec.extension` (one letter short
+// of `extensions`) emitted a certificate with NO extensions at all -- no basicConstraints on an
+// intended CA, no keyUsage on an intended constrained leaf. `spec.issuer` is the other shape: the
+// issuer is argument TWO, and nesting it in the spec left the certificate SELF-SIGNED with nothing
+// to read as a failure.
+//
+// Every table is derived from what the function actually reads, not from the doc block, because a
+// table naming a key nothing reads reopens the hole it was added to close.
+var KNOWN_SPEC_KEYS = {
+  subject: 1, subjectPublicKey: 1, notBefore: 1, notAfter: 1, serialNumber: 1, extensions: 1,
+};
+// The issuer names itself in one of two FORMS, and the cert form wins unconditionally: when
+// `issuer.cert` is present the builder takes the DN and the public key from it and never reads
+// `name` or `publicKey`. A union accepted `{ key, cert, name: "Different CA", publicKey }` and
+// signed under the certificate's identity while discarding the identity 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_EXT_KEYS = {
   subjectKeyIdentifier: 1, authorityKeyIdentifier: 1, keyUsage: 1, keyUsageCritical: 1,
   extendedKeyUsage: 1, extendedKeyUsageCritical: 1, basicConstraints: 1, subjectAltName: 1,
@@ -282,6 +303,22 @@ function _sign(spec, issuer, opts) {
   opts = opts || {};
   if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("x509/bad-input", "the certificate spec must be an object");
   issuer = issuer || {};
+  // Before a single field is read, so a misspelling is a refusal rather than an omission carried
+  // into a signed certificate. The issuer message names its own argument because the mistake this
+  // catches most often is putting the issuer inside the spec, where it self-signed in silence.
+  guard.identifier.assertKnownKeys(spec, KNOWN_SPEC_KEYS, _err, "x509/bad-input", function (k) {
+    return "unknown certificate spec field " + JSON.stringify(k) +
+      (k === "issuer" ? "; the issuer is the SECOND argument to pki.x509.sign, not a spec field" : "") +
+      (k === "extension" ? "; the extensions spec field is `extensions`" : "");
+  });
+  var byCert = issuer.cert != null;
+  guard.identifier.assertKnownKeys(issuer, byCert ? KNOWN_ISSUER_CERT_KEYS : KNOWN_ISSUER_EXPLICIT_KEYS,
+    _err, "x509/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, "x509/bad-input", "pki.x509.sign has an unknown option ");
   if (issuer.key == null) throw _err("x509/bad-input", "a signing key (issuer.key, a PKCS#8 private key) is required");
 
   var spki = _reqDer(spec.subjectPublicKey, "spec.subjectPublicKey (the SPKI DER of the certified key)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:b8b3d2cf-001e-4a5b-8644-a627ed3ce3c5",
+  "serialNumber": "urn:uuid:123ddb5e-05ea-4e65-9d7d-7a667c46e3a3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-20T14:50:41.972Z",
+    "timestamp": "2026-08-20T20:31:47.390Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.17",
+      "bom-ref": "@blamejs/pki@0.5.18",
       "type": "application",
       "name": "pki",
-      "version": "0.5.17",
+      "version": "0.5.18",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.5.17",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.18",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.17",
+      "ref": "@blamejs/pki@0.5.18",
       "dependsOn": []
     }
   ]