@blamejs/pki 0.5.16 → 0.5.18

package/lib/pkcs12-build.js

@@ -5,6 +5,7 @@
  * @module     pki.pkcs12
  * @nav        Signing
  * @title      PKCS#12
+ * @fullname   PKCS#12 keystores (.p12 and .pfx): build and open
  * @intro The PKCS#12 (.p12 / .pfx) producing side (RFC 7292, RFC 9579). `pki.pkcs12.build` assembles a
  *   password-integrity PFX -- key, certificate, CRL, and secret bags (shrouded keys and cert safes encrypted
  *   under RFC 8018 PBES2) wrapped in an AuthenticatedSafe, protected by either a classic Appendix B HMAC or
@@ -42,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");
@@ -115,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,
@@ -279,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");
@@ -289,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
     }
@@ -348,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 {
@@ -378,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)");
@@ -400,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 }
@@ -463,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");
@@ -479,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 });
@@ -511,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.
@@ -540,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
@@ -555,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));
@@ -568,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);
   }
@@ -611,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);
 }
 
@@ -714,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);
@@ -848,7 +1039,7 @@ function _decryptLegacyPbe(ea, ct, password, opts, budget) {
   try {
     if (scheme.rc2) return rc2.cbcDecrypt(keyM, scheme.rc2, iv, ct, _err, "pkcs12/decrypt-failed");
     var d = nodeCrypto.createDecipheriv(scheme.cipher, keyM, iv);
-    return Buffer.concat([d.update(ct), d.final()]);
+    return guard.secret.cipherFinish(d, ct, Pkcs12Error, "pkcs12/bad-input", "the recovered safe contents");
   } catch (_e) { throw _err("pkcs12/decrypt-failed", "decryption failed"); }
   finally { guard.secret.zeroize(keyM, Pkcs12Error, "pkcs12/bad-input", "the password-derived decryption key"); }
 }

package/lib/schema-all.js

@@ -5,6 +5,7 @@
  * @module     pki.schema
  * @nav        Schema
  * @title      Schema
+ * @fullname   Format detection: parse DER without knowing the format first
  * @order      10
  * @featured   true
  * @slug       schema

package/lib/schema-c509.js

@@ -5,6 +5,7 @@
  * @module pki.schema.c509
  * @nav    Schema
  * @title  C509
+ * @fullname   C509 compact certificates (CBOR-encoded X.509)
  * @intro  C509 CBOR-encoded certificates (draft-ietf-cose-cbor-encoded-cert). A compact CBOR
  *   re-encoding of an X.509 v3 certificate: a deterministic-CBOR array of exactly 11 elements
  *   (10 TBS fields + the issuer signature). Two modes: c509CertificateType 2 is a natively-signed

package/lib/schema-csrattrs.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.csrattrs
  * @nav        Schema
  * @title      CSR Attributes
+ * @fullname   CSR attributes: what an EST server asks an enrollee to include
  * @order      185
  * @slug       csrattrs
  *

package/lib/schema-engine.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.engine
  * @nav        Schema
  * @title      Schema engine
+ * @fullname   ASN.1 schema engine: one definition drives encode and decode
  * @order      60
  *
  * @intro

package/lib/schema-pkcs8.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.pkcs8
  * @nav        Schema
  * @title      PKCS#8
+ * @fullname   PKCS#8 private keys, encrypted and unencrypted
  * @order      140
  * @slug       pkcs8
  *

package/lib/schema-smime.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.smime
  * @nav        Schema
  * @title      S/MIME (ESS)
+ * @fullname   S/MIME signed and encrypted mail, with ESS security labels
  * @order      180
  * @slug       smime
  *

package/lib/schema-tsp.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.tsp
  * @nav        Schema
  * @title      TSP
+ * @fullname   RFC 3161 timestamps (TSP): request, sign and verify
  * @order      170
  * @slug       tsp
  *

package/lib/schema-x509.js

@@ -5,6 +5,7 @@
  * @module     pki.schema.x509
  * @nav        Schema
  * @title      X.509
+ * @fullname   X.509 certificates: parse, sign and inspect
  * @order      100
  * @featured   true
  * @slug       x509

package/lib/shbs.js

@@ -5,6 +5,7 @@
  * @module pki.shbs
  * @nav        Signatures
  * @title      Stateful hash-based
+ * @fullname   Stateful hash-based signatures: LMS and XMSS
  * @intro Stateful hash-based signature VERIFICATION -- HSS/LMS (RFC 8554),
  *   carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST
  *   SP 800-208. Verify only, by deliberate design: stateful hash-based signing

package/lib/sigstore.js

@@ -5,6 +5,7 @@
  * @module pki.sigstore
  * @nav        Supply chain
  * @title      Sigstore
+ * @fullname   Sigstore bundles: keyless signing and provenance
  * @intro Zero-dependency verifier for a Sigstore bundle, the exact artifact
  *   `npm publish --provenance` produces and the npm registry serves at its
  *   attestations API. A bundle is a keyless (Fulcio) signature over a DSSE-wrapped

package/lib/smime.js

@@ -5,6 +5,7 @@
  * @module     pki.smime
  * @nav        Messaging
  * @title      S/MIME
+ * @fullname   S/MIME signed and encrypted mail
  * @order      175
  * @slug       smime
  *

package/lib/tls-cert-compress.js

@@ -5,6 +5,7 @@
  * @module     pki.tls
  * @nav        Transparency
  * @title      TLS
+ * @fullname   TLS certificate compression (RFC 8879)
  * @order      215
  * @slug       tls
  *

package/lib/trust.js

@@ -5,6 +5,7 @@
  * @module     pki.trust
  * @nav        Path validation
  * @title      Trust-store ingestion
+ * @fullname   Trust stores: load and pin root certificate anchors
  * @order      230
  * @slug       trust
  *

package/lib/tsp-sign.js

@@ -5,6 +5,7 @@
  * @module     pki.tsp
  * @nav        Signing
  * @title      Timestamps
+ * @fullname   RFC 3161 trusted timestamps: request, sign and verify
  * @intro Create an RFC 3161 timestamp token. A TimeStampToken IS a CMS SignedData whose
  *   encapsulated content is a `TSTInfo` (the timestamped message imprint + trusted time), so
  *   `sign(messageImprint, tsa, opts)` builds the `TSTInfo`, attaches the RFC 3161 sec. 2.4.2
@@ -141,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");
@@ -186,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);
@@ -263,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 /
@@ -348,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/webauthn.js

@@ -5,6 +5,7 @@
  * @module pki.webauthn
  * @nav        Validation
  * @title      WebAuthn
+ * @fullname   WebAuthn: verify registration attestation and assertions
  * @intro Trust evaluation of a W3C WebAuthn (Level 3) / passkey attestation: parse
  *   the attestation object + authenticatorData, decode the COSE credential public
  *   key, and verify each defined attestation-statement format (packed, tpm,