@blamejs/pki 0.5.17 → 0.5.19

package/lib/jose.js

@@ -42,6 +42,24 @@ var webcrypto = wcEngine.webcrypto;
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var edwardsPoint = require("./edwards-point");
+// What this module reads from the runtime while it is deciding something, taken at load. A JWS is
+// signed and verified against a header the caller owns, and the reads below are the ones that decide
+// what that header IS: whether a value is a list, whether a name is the caller's own, which
+// conversion turns a claim into the string compared against a profile. A caller who receives control
+// afterwards -- through an accessor on the header, or a `toJSON` while it is being serialized -- can
+// replace any of them, and every check around them still runs and still passes. See guard-intrinsic.
+var intrinsic = require("./guard-intrinsic");
+var _isArray = intrinsic.isArray;
+var _hasOwn = intrinsic.hasOwn;
+var _keys = intrinsic.keys;
+var _isBuffer = intrinsic.isBuffer;
+var _bufferFrom = intrinsic.bufferFrom;
+var _stringify = intrinsic.stringify;
+var _ObjectProto = intrinsic.ObjectProto;
+var _push = intrinsic.uncurry(Array.prototype.push);
+var _join = intrinsic.join;
+var _map = intrinsic.map;
+var _bufToString = intrinsic.uncurry(Buffer.prototype.toString);
 
 var JoseError = frameworkError.JoseError;
 function E(code, message, cause) { return new JoseError(code, message, cause); }
@@ -65,11 +83,11 @@ var LIMITS = constants.LIMITS;
  *   pki.jose.base64url.encode(Buffer.from([1, 2, 3]));   // -> "AQID"
  */
 function b64uEncode(bytes) {
-  if (!Buffer.isBuffer(bytes)) throw E("jose/bad-input", "base64url.encode requires a Buffer");
+  if (!_isBuffer(bytes)) throw E("jose/bad-input", "base64url.encode requires a Buffer");
   // Re-view through the byte guard: a detached-backed Buffer reads as zero-length,
   // so a bare .toString would silently encode "" -- fail closed instead.
   bytes = guard.bytes.view(bytes, JoseError, "jose/bad-input", "base64url.encode input");
-  return bytes.toString("base64url");
+  return _bufToString(bytes, "base64url");
 }
 
 /**
@@ -182,19 +200,19 @@ var PROFILES = {
 // { alg, algRow, header }; throws a typed jose/* fault on any violation.
 function _checkHeader(header, profileName) {
   var profile = PROFILES[profileName];
-  if (!profile) throw E("jose/bad-input", "unknown JWS profile " + JSON.stringify(profileName));
-  if (!header || typeof header !== "object" || Array.isArray(header)) throw E("jose/bad-header", "the protected header must be a JSON object");
+  if (!profile) throw E("jose/bad-input", "unknown JWS profile " + _stringify(profileName));
+  if (!header || typeof header !== "object" || _isArray(header)) throw E("jose/bad-header", "the protected header must be a JSON object");
   // Every field is read as an OWN property. JSON.stringify (used by sign) omits
   // inherited members, so an alg/nonce/url living on the prototype (a polluted or
   // Object.create(...) header) would pass here yet serialize to a header MISSING
   // them -- so require own-ness, matching what the serialized JWS will actually carry.
-  var own = function (k) { return Object.prototype.hasOwnProperty.call(header, k); };
+  var own = function (k) { return _hasOwn(header, k); };
   // b64 (RFC 7797) MUST NOT be present at all -- the unencoded-payload downgrade.
   if (own("b64")) throw E("jose/bad-jws", "the RFC 7797 b64 header parameter is forbidden");
   var alg = header.alg;
   if (!own("alg") || typeof alg !== "string") throw E("jose/bad-header", "the protected header must carry a string alg");
   var algRow = profile.algs[alg];
-  if (!algRow) throw E("jose/bad-alg", "unsupported or forbidden algorithm " + JSON.stringify(alg) + " for this JWS profile");
+  if (!algRow) throw E("jose/bad-alg", "unsupported or forbidden algorithm " + _stringify(alg) + " for this JWS profile");
   if (profile.requireUrl && (!own("url") || typeof header.url !== "string" || header.url.length === 0)) throw E("jose/bad-header", "the protected header must carry a non-empty string url");
   // nonce discipline.
   var hasNonce = own("nonce");
@@ -219,20 +237,20 @@ function _checkHeader(header, profileName) {
   } else if (profile.keyId === "jwk") {
     if (!hasJwk || hasKid) throw E("jose/bad-header", "this JWS must carry an embedded jwk, not kid");
   }
-  if (hasJwk && (!header.jwk || typeof header.jwk !== "object" || Array.isArray(header.jwk))) throw E("jose/bad-header", "jwk must be a JSON object");
+  if (hasJwk && (!header.jwk || typeof header.jwk !== "object" || _isArray(header.jwk))) throw E("jose/bad-header", "jwk must be a JSON object");
   // crit: protected-only, non-empty, no standard names, no duplicates, all understood.
-  if (Object.prototype.hasOwnProperty.call(header, "crit")) {
+  if (_hasOwn(header, "crit")) {
     var crit = header.crit;
-    if (!Array.isArray(crit) || crit.length === 0) throw E("jose/bad-crit", "crit must be a non-empty array");
+    if (!_isArray(crit) || crit.length === 0) throw E("jose/bad-crit", "crit must be a non-empty array");
     var seen = {};
     for (var c = 0; c < crit.length; c++) {
       var name = crit[c];
       if (typeof name !== "string") throw E("jose/bad-crit", "crit entries must be strings");
-      if (Object.prototype.hasOwnProperty.call(seen, name)) throw E("jose/bad-crit", "duplicate crit entry " + JSON.stringify(name));
+      if (_hasOwn(seen, name)) throw E("jose/bad-crit", "duplicate crit entry " + _stringify(name));
       seen[name] = 1;
-      if (UNDERSTOOD_HEADER[name]) throw E("jose/bad-crit", "crit must not name a standard header parameter " + JSON.stringify(name));
+      if (UNDERSTOOD_HEADER[name]) throw E("jose/bad-crit", "crit must not name a standard header parameter " + _stringify(name));
       // Anything else is an extension parameter this implementation does not process.
-      throw E("jose/bad-crit", "unprocessed critical header parameter " + JSON.stringify(name));
+      throw E("jose/bad-crit", "unprocessed critical header parameter " + _stringify(name));
     }
   }
   return { alg: alg, algRow: algRow, header: header };
@@ -267,9 +285,9 @@ function _cryptoAlg(algRow, jwk, key) {
 // The key type the JWK MUST have for this alg (fail closed on confusion).
 function _assertKeyType(algRow, jwk) {
   if (!jwk || typeof jwk !== "object" || typeof jwk.kty !== "string") throw E("jose/bad-key", "a JWK object with a kty is required");
-  if (jwk.kty !== algRow.kty) throw E("jose/bad-alg", "the key type " + JSON.stringify(jwk.kty) + " does not match the algorithm");
+  if (jwk.kty !== algRow.kty) throw E("jose/bad-alg", "the key type " + _stringify(jwk.kty) + " does not match the algorithm");
   if (algRow.kty === "EC" && jwk.crv !== algRow.crv) throw E("jose/bad-alg", "the EC curve does not match the algorithm");
-  if (algRow.kty === "OKP" && jwk.crv !== "Ed25519" && jwk.crv !== "Ed448") throw E("jose/bad-alg", "unsupported OKP curve " + JSON.stringify(jwk.crv));
+  if (algRow.kty === "OKP" && jwk.crv !== "Ed25519" && jwk.crv !== "Ed448") throw E("jose/bad-alg", "unsupported OKP curve " + _stringify(jwk.crv));
   // node/OpenSSL import a low-order (e.g. identity) OKP point without complaint and it verifies a
   // forged signature; reject a non-full-order Edwards point through the shared gate, the same check
   // every EdDSA verify path in the toolkit applies.
@@ -278,7 +296,7 @@ function _assertKeyType(algRow, jwk) {
   }
   // An AKP (ML-DSA) JWK carries its parameter set in `alg` (RFC 9964); it MUST match
   // the algorithm's set, or an ML-DSA-44 key could embed an ML-DSA-65 public JWK.
-  if (algRow.kty === "AKP" && jwk.alg !== algRow.subtle) throw E("jose/bad-alg", "the AKP parameter set " + JSON.stringify(jwk.alg) + " does not match the algorithm " + algRow.subtle);
+  if (algRow.kty === "AKP" && jwk.alg !== algRow.subtle) throw E("jose/bad-alg", "the AKP parameter set " + _stringify(jwk.alg) + " does not match the algorithm " + algRow.subtle);
 }
 
 // The exact signature byte length this alg + key must produce.
@@ -317,10 +335,10 @@ var PRIVATE_JWK_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "k", "priv"];
  *   pki.jose.assertPublicJwk({ kty: "EC", crv: "P-256", x: "...", y: "..." });
  */
 function assertPublicJwk(jwk) {
-  if (!jwk || typeof jwk !== "object" || Array.isArray(jwk)) throw E("jose/bad-key", "a JWK object is required");
+  if (!jwk || typeof jwk !== "object" || _isArray(jwk)) throw E("jose/bad-key", "a JWK object is required");
   for (var i = 0; i < PRIVATE_JWK_MEMBERS.length; i++) {
-    if (Object.prototype.hasOwnProperty.call(jwk, PRIVATE_JWK_MEMBERS[i])) {
-      throw E("jose/private-key-material", "a published JWK must be public-only; it carries the private member " + JSON.stringify(PRIVATE_JWK_MEMBERS[i]));
+    if (_hasOwn(jwk, PRIVATE_JWK_MEMBERS[i])) {
+      throw E("jose/private-key-material", "a published JWK must be public-only; it carries the private member " + _stringify(PRIVATE_JWK_MEMBERS[i]));
     }
   }
   return jwk;
@@ -374,9 +392,9 @@ var _VERIFY_KEYS = { key: 1, profile: 1 };
 async function verify(jws, opts) {
   opts = opts || {};
   guard.identifier.assertKnownKeys(opts, _VERIFY_KEYS, E, "jose/bad-input", "unknown pki.jose.verify option ");
-  if (!jws || typeof jws !== "object" || Array.isArray(jws)) throw E("jose/bad-jws", "a flattened JWS object is required");
-  if (Object.prototype.hasOwnProperty.call(jws, "signatures")) throw E("jose/bad-jws", "the multi-signature signatures member is forbidden");
-  if (Object.prototype.hasOwnProperty.call(jws, "header")) throw E("jose/bad-jws", "the unprotected header member is forbidden");
+  if (!jws || typeof jws !== "object" || _isArray(jws)) throw E("jose/bad-jws", "a flattened JWS object is required");
+  if (_hasOwn(jws, "signatures")) throw E("jose/bad-jws", "the multi-signature signatures member is forbidden");
+  if (_hasOwn(jws, "header")) throw E("jose/bad-jws", "the unprotected header member is forbidden");
   if (typeof jws.protected !== "string" || typeof jws.signature !== "string") throw E("jose/bad-jws", "protected and signature must be base64url strings");
   if (typeof jws.payload !== "string") throw E("jose/bad-jws", "payload must be a base64url string (never detached)");
   var header = parseJson(b64uDecode(jws.protected));
@@ -393,7 +411,7 @@ async function verify(jws, opts) {
   // matters most -- a `key` that came back null from a lookup would verify against whatever the
   // message carried, and the verdict would report the embedded key as though none was named.
   // `undefined` alone means "not supplied", so spreading an options object stays safe.
-  if (opts.key !== undefined && (typeof opts.key !== "object" || opts.key === null || Array.isArray(opts.key))) {
+  if (opts.key !== undefined && (typeof opts.key !== "object" || opts.key === null || _isArray(opts.key))) {
     throw E("jose/bad-key", "opts.key was supplied but is not a JWK object, so the key this message must be signed under cannot be established");
   }
   var jwk = header.jwk || opts.key;
@@ -419,7 +437,7 @@ async function verify(jws, opts) {
   var want = _expectedSigBytes(checked.algRow, jwk);
   if (want != null && sig.length !== want) throw E("jose/bad-signature", "the signature length " + sig.length + " is not the " + want + " bytes " + checked.alg + " requires");
   // Signing input from the RECEIVED base64url strings verbatim (never a re-serialize).
-  var signingInput = Buffer.from(jws.protected + "." + jws.payload, "ascii");
+  var signingInput = _bufferFrom(jws.protected + "." + jws.payload, "ascii");
   var key;
   try { key = await webcrypto.subtle.importKey("jwk", jwk, _importParams(checked.algRow, jwk), false, ["verify"]); }
   catch (e) { throw E("jose/bad-key", "the JWK could not be imported for verification", e); }
@@ -457,7 +475,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,13 +484,40 @@ 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 = _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 : _bufferFrom(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 " + _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)");
+  if (!_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
   // and would be silently signed as an empty POST-as-GET body -- fail closed instead.
   payload = guard.bytes.view(payload, JoseError, "jose/bad-input", "payload");
@@ -494,16 +539,16 @@ 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 signingInput = _bufferFrom(protectedB64 + "." + payloadB64, "ascii");
   var jwk = header.jwk || opts.jwk || {};
   // opts.key is documented as a CryptoKey, so one created outside this engine signs here too: it
   // carries none of the material this engine signs with, and is re-imported through it rather than
   // reaching subtle.sign as a key it cannot read. A key whose material this process cannot reach at
   // all -- non-extractable, or held behind another implementation's interface -- is refused there.
   var signKey = await wcEngine.adoptKey(opts.key, null, ["sign"], E, "jose/bad-input");
-  var sigBuf = Buffer.from(await webcrypto.subtle.sign(_cryptoAlg(checked.algRow, jwk, signKey), signKey, signingInput));
+  var sigBuf = _bufferFrom(await webcrypto.subtle.sign(_cryptoAlg(checked.algRow, jwk, signKey), signKey, signingInput));
   // Pin the produced signature length the same way verify does. A key whose curve /
   // hash / modulus does not match the header alg (a P-384 key under ES256, an
   // HS512 key under HS256) still signs, but emits the wrong length -- caught here
@@ -563,15 +608,17 @@ var THUMBPRINT_MEMBERS = {
 async function thumbprint(jwk) {
   if (!jwk || typeof jwk !== "object" || typeof jwk.kty !== "string") throw E("jose/bad-key", "a JWK object with a kty is required");
   var members = THUMBPRINT_MEMBERS[jwk.kty];
-  if (!members) throw E("jose/bad-key", "unsupported JWK key type " + JSON.stringify(jwk.kty));
+  if (!members) throw E("jose/bad-key", "unsupported JWK key type " + _stringify(jwk.kty));
   var parts = [];
   for (var i = 0; i < members.length; i++) {
     var m = members[i];
-    if (typeof jwk[m] !== "string") throw E("jose/bad-key", "the JWK is missing the required member " + JSON.stringify(m));
-    parts.push(JSON.stringify(m) + ":" + JSON.stringify(jwk[m]));
+    if (typeof jwk[m] !== "string") throw E("jose/bad-key", "the JWK is missing the required member " + _stringify(m));
+    // The canonical form IS the thumbprint preimage (RFC 7638 sec. 3.3), so the serializer that
+    // builds it is the captured one: a replacement changes the identity every consumer compares.
+    _push(parts, _stringify(m) + ":" + _stringify(jwk[m]));
   }
-  var canonical = "{" + parts.join(",") + "}";
-  var digest = Buffer.from(await webcrypto.subtle.digest("SHA-256", Buffer.from(canonical, "utf8")));
+  var canonical = "{" + _join(parts, ",") + "}";
+  var digest = _bufferFrom(await webcrypto.subtle.digest("SHA-256", _bufferFrom(canonical, "utf8")));
   return b64uEncode(digest);
 }
 
@@ -603,7 +650,7 @@ async function thumbprint(jwk) {
  *   pss.map(function (r) { return r.alg; });   // -> ["PS256", "PS384", "PS512"]
  */
 function sigAlgs() {
-  return Object.keys(SIG_ALGS).map(function (alg) {
+  return _map(_keys(SIG_ALGS), function (alg) {
     var row = SIG_ALGS[alg];
     var out = { alg: alg, kty: row.kty };
     if (row.crv) out.crv = row.crv;

package/lib/key.js

@@ -305,6 +305,10 @@ async function import_(input, opts) {
   }
   var algorithm = opts.algorithm != null ? opts.algorithm : _inferAlgorithm(detected);
   var isPublic = detected.format === "spki";
+  // Checked at this verb's own door rather than left for the engine to discover: a non-list reached
+  // the CryptoKey copy, where `Array.prototype.slice` on a number yields an empty list, so the key
+  // was minted permitted for NOTHING instead of the call naming the argument that was wrong.
+  if (opts.usages != null && !Array.isArray(opts.usages)) throw _err("key/bad-input", "opts.usages must be an array of key-usage strings");
   var usages = opts.usages || _importUsages(_algName(algorithm), isPublic);
   var extractable = opts.extractable != null ? opts.extractable : false;
   try {
@@ -344,6 +348,8 @@ async function generate(algorithm, opts) {
   guard.identifier.assertKnownKeys(opts, _GENERATE_OPTS, _err, "key/bad-input",
     "pki.key.generate has an unknown option (the WebCrypto spelling is `extractable`): ");
   var extractable = opts.extractable != null ? opts.extractable : true;
+  // The same door as import: a non-list is named here rather than becoming an empty usage set.
+  if (opts.usages != null && !Array.isArray(opts.usages)) throw _err("key/bad-input", "opts.usages must be an array of key-usage strings");
   var usages = opts.usages || _generateUsages(_algName(algorithm));
   var pair;
   try { pair = await subtle.generateKey(algorithm, extractable, usages); }

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);