@blamejs/pki 0.5.10 → 0.5.12

package/lib/guard-parsed.js

@@ -39,6 +39,7 @@
 // changes what is checked, never what the operator reads.
 
 var bytes = require("./guard-bytes");
+var time = require("./guard-time");
 
 // Every form the toolkit calls "bytes": a Buffer, any typed-array view, a DataView, or a bare
 // ArrayBuffer. Testing `Buffer.isBuffer(x) || x instanceof Uint8Array` is narrower than what the
@@ -46,8 +47,11 @@ var bytes = require("./guard-bytes");
 // through to the object branch and be refused as a rebuilt structure, which reads to the caller as
 // "your certificate is malformed" when what happened is that their container was not recognized.
 // guard.bytes is what finally reads them, and it accepts all four, so the door has to as well.
+// Asked of guard.bytes rather than restated here, because a restatement is what drifts. An
+// `x instanceof ArrayBuffer` here turns away a real buffer built in another realm that guard.bytes
+// goes on to accept, so one container gets opposite answers from the two doors it passes through.
 function _isBytes(x) {
-  return Buffer.isBuffer(x) || ArrayBuffer.isView(x) || x instanceof ArrayBuffer;
+  return bytes.isByteSource(x);
 }
 
 // The shapes below assert the parser's complete output: every field
@@ -150,7 +154,7 @@ function isCert(o) {
     _isAlgorithmIdentifier(o.signatureAlgorithm) &&
     _isAlgorithmIdentifier(o.tbsSignatureAlgorithm) &&
     _isBitString(o.signatureValue) &&
-    !!o.validity && o.validity.notBefore instanceof Date && o.validity.notAfter instanceof Date &&
+    !!o.validity && time.isDate(o.validity.notBefore) && time.isDate(o.validity.notAfter) &&
     _isName(o.issuer) &&
     _isName(o.subject) &&
     !!o.subjectPublicKeyInfo && Buffer.isBuffer(o.subjectPublicKeyInfo.bytes) &&
@@ -174,13 +178,13 @@ function isCrl(o) {
     _isAlgorithmIdentifier(o.signatureAlgorithm) &&
     _isBitString(o.signatureValue) &&
     _isName(o.issuer) &&
-    o.thisUpdate instanceof Date &&
-    (o.nextUpdate === null || o.nextUpdate instanceof Date) &&
+    time.isDate(o.thisUpdate) &&
+    (o.nextUpdate === null || time.isDate(o.nextUpdate)) &&
     Array.isArray(o.crlExtensions) && o.crlExtensions.every(_isCrlExtensionEntry) &&
     Array.isArray(o.revokedCertificates) && o.revokedCertificates.every(function (e) {
       return !!e && typeof e.serialNumber === "bigint" &&
         typeof e.serialNumberHex === "string" &&
-        e.revocationDate instanceof Date &&
+        time.isDate(e.revocationDate) &&
         Array.isArray(e.crlEntryExtensions) && e.crlEntryExtensions.every(_isCrlExtensionEntry);
     });
 }

package/lib/guard-time.js

@@ -27,6 +27,8 @@
 // OCSP / CRL currency callers that treat out-of-window as a `continue` skip keep
 // their control flow while a NaN operand can never slip through as a false.
 
+var util = require("util");
+
 // assertValid(value, E, code, label) -> the same Date, once proven valid.
 //   value : a Date (or an alleged one) from a caller boundary.
 //   E     : the (code, message[, cause]) typed-error FACTORY in scope at the call
@@ -34,9 +36,44 @@
 //           would crash `class cannot be invoked without new` on the error path.
 //   code  : the frozen domain/reason code this boundary rejects malformed time under.
 //   label : field phrase for the message.
+// The instant a Date holds, asked of the language rather than of the Date.
+//
+// `getTime` is an ordinary method on `Date.prototype`, so `class T extends Date { getTime() {} }`
+// and an own `getTime` on any instance both answer it. Reading it off the value let a caller throw
+// a raw exception out of a guard whose contract is a typed error, and let one return a fabricated
+// instant that passed the check while the real one did not. It also made the read repeatable: a
+// method asked twice may answer twice, so a window check could validate one instant and compare
+// another.
+//
+// The intrinsic is called against the value, which reaches the internal slot whatever the value's
+// own class says, and refuses a receiver with no slot behind it.
+//
+// The capture is of whatever `Date.prototype.getTime` holds when this module first loads, so it
+// is the language's own function only if nothing replaced it earlier in the process. Code that
+// runs before this module is inside the trust boundary already and can reach further than this
+// one method, so there is no defense here to add; what the capture buys is immunity to every
+// replacement that happens afterwards, which is the case a caller's argument can reach.
+var _dateGetTime = Date.prototype.getTime;
+
+// instantOf(value) -> the epoch milliseconds a Date holds, read through the intrinsic.
+//
+// The shape is the method call itself, wherever it appears. There is no boundary at which reading
+// `getTime` off a value is the safe spelling: a caller's Date reaches the read through an override,
+// and this toolkit's own Date reaches it through whatever `Date.prototype.getTime` has been made
+// to be, which a dependency loaded before this module gets to decide. So the rule is that lib/
+// calls no `getTime` at all, and the one capture above is where it lives.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape \.getTime\s*\(
+function instantOf(value) { return _dateGetTime.call(value); }
+
 // @enforced-by nan-date-comparison-unguarded
 function assertValid(value, E, code, label) {
-  if (!(value instanceof Date) || isNaN(value.getTime())) {
+  // The slot, never the prototype. `instanceof Date` asks what a value inherits from, and
+  // `Object.create(Date.prototype)` inherits everything while holding no instant, so it passes
+  // that test and `getTime()` then throws a raw TypeError out of this guard. `util.types.isDate`
+  // reads the internal slot, which a caller cannot fake and which answers the same across realms.
+  if (!util.types.isDate(value) || isNaN(instantOf(value))) {
     throw E(code, (label || "value") + " must be a valid Date");
   }
   return value;
@@ -56,13 +93,37 @@ function within(instant, lower, upper, E, code, label, opts) {
   assertValid(instant, E, code, label);
   assertValid(lower, E, code, (label || "window") + " lower bound");
   assertValid(upper, E, code, (label || "window") + " upper bound");
-  var t = instant.getTime();
-  var lo = lower.getTime();
-  var hi = upper.getTime();
+  // Read through the intrinsic, so the instants compared here are the ones assertValid just
+  // proved. A caller's `getTime` override answers each call afresh, which made the value checked
+  // and the value compared two different reads of the same argument.
+  var t = instantOf(instant);
+  var lo = instantOf(lower);
+  var hi = instantOf(upper);
   return t >= lo && (opts && opts.upperInclusive ? t <= hi : t < hi);
 }
 
+// isDate(value) -> boolean: does this value actually hold an instant?
+//
+// The predicate half of assertValid, for the boundaries that choose a default rather than refuse
+// (`opts.genTime instanceof Date ? opts.genTime : new Date()`). `instanceof` asks what a value
+// inherits from, so `Object.create(Date.prototype)` passes it while holding no instant, and the
+// `.getTime()` that follows throws a raw TypeError out of a verb whose contract is a typed error.
+// A caller who supplied one and got the default instead would be worse served still: the value
+// they passed would have been silently replaced. This reads the slot, which cannot be faked and
+// answers the same for a Date built in another realm.
+//
+// An Invalid Date has the slot and a NaN instant, so this says yes to one. A boundary that
+// compares instants wants assertValid, which rejects both shapes.
+// @enforced-by behavioral -- a prototype test in place of a slot test has no rename-proof code
+// shape; the RED vectors (a slot-less Date lookalike at cms.verify / cms.sign / tsp.sign) are
+// the guard.
+function isDate(value) {
+  return util.types.isDate(value);
+}
+
 module.exports = {
   assertValid: assertValid,
+  instantOf: instantOf,
+  isDate: isDate,
   within: within,
 };

package/lib/inspect.js

@@ -91,8 +91,13 @@ var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oc
 function _two(n) { return (n < 10 ? "0" : "") + n; }
 // OpenSSL date: "Jul  4 07:00:27 2026 GMT" (month, space-padded day, time, year, GMT).
 function _date(iso) {
-  var d = (iso instanceof Date) ? iso : new Date(iso);
-  if (isNaN(d.getTime())) return String(iso);
+  // Rebuilt from the instant the value holds, so every field below is read off a Date of this
+  // realm. The calendar methods are ordinary ones a subclass answers, and a parsed structure can
+  // carry a Date a caller supplied, so reading them off that value let it decide the date printed
+  // beside a certificate rather than the one the certificate carries.
+  var held = guard.time.isDate(iso) ? guard.time.instantOf(iso) : Date.parse(String(iso));
+  if (isNaN(held)) return String(iso);
+  var d = new Date(held);
   var day = d.getUTCDate(), dd = (day < 10 ? " " : "") + day;
   return MONTHS[d.getUTCMonth()] + " " + dd + " " +
     _two(d.getUTCHours()) + ":" + _two(d.getUTCMinutes()) + ":" + _two(d.getUTCSeconds()) +
@@ -745,7 +750,7 @@ function _crlExtension(ext, pad) {
   var inner = pad + "    ";
   if (ext.oid === OID_CRL_NUMBER && typeof ext.value === "bigint") return header + "\n" + inner + String(ext.value);
   if (ext.oid === OID_REASON_CODE && typeof ext.value === "number") return header + "\n" + inner + (NAMES.CRL_REASON[ext.value] || String(ext.value));
-  if (ext.oid === OID_INVALIDITY_DATE && ext.value instanceof Date) return header + "\n" + inner + _date(ext.value);
+  if (ext.oid === OID_INVALIDITY_DATE && guard.time.isDate(ext.value)) return header + "\n" + inner + _date(ext.value);
   if (ext.oid === OID_DELTA_CRL_INDICATOR && Buffer.isBuffer(ext.value)) {
     try { return header + "\n" + inner + "BaseCRLNumber: " + String(asn1.read.integer(asn1.decode(ext.value))); }
     catch (_e) { /* malformed BaseCRLNumber -> fall through to the shared _extension (hex) */ }

package/lib/key.js

@@ -106,8 +106,16 @@ async function _toPrivateKeyDer(input) {
  *   var enc = await pki.key.encrypt(der, "s3cr3t", { pem: true });
  *   var back = await pki.key.decrypt(enc, "s3cr3t");
  */
+// Every option pki.key.encrypt reads. `iterations` here answers a different question from
+// `maxIterations` on decrypt. This side chooses a PBKDF2 count, and that side caps the one it
+// will honor. Passing either name to the other verb is silently nothing, so both are refused.
+var _ENCRYPT_OPTS = { cipher: 1, iterations: 1, pem: 1, prf: 1, salt: 1 };
+
 async function encrypt(privateKey, password, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.encrypt options");
+  guard.identifier.assertKnownKeys(opts, _ENCRYPT_OPTS, _err, "key/bad-input",
+    "pki.key.encrypt has an unknown option (the PBKDF2 count here is `iterations`; " +
+    "`maxIterations` is the decrypt-side cap): ");
   var der = await _toPrivateKeyDer(privateKey);
   // RFC 5958 sec. 3: the plaintext is the DER PrivateKeyInfo -- validate it IS one (the strict parser
   // rejects BER / non-canonical / trailing bytes) before encrypting, so we never wrap opaque input.
@@ -166,8 +174,15 @@ async function encrypt(privateKey, password, opts) {
  *   var enc = await pki.key.encrypt(await pki.key.export(pair.privateKey), "s3cr3t", { pem: true });
  *   var der = await pki.key.decrypt(enc, "s3cr3t");
  */
+// Every option pki.key.decrypt reads. `maxIterations` is the cap this side honors, not the
+// `iterations` the encrypt side chooses; see the note above _ENCRYPT_OPTS.
+var _DECRYPT_OPTS = { maxIterations: 1, pem: 1 };
+
 async function decrypt(encrypted, password, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.decrypt options");
+  guard.identifier.assertKnownKeys(opts, _DECRYPT_OPTS, _err, "key/bad-input",
+    "pki.key.decrypt has an unknown option (the PBKDF2 cap here is `maxIterations`; " +
+    "`iterations` is the encrypt-side count): ");
   // opts.maxIterations is a CALLER authoring bound (a downward-only cap): validate it config-time so an
   // invalid value is a key/bad-input, never a NaN that silently disables the DoS cap and never mis-coded as
   // a fault in the attacker-controlled input parameters.
@@ -226,8 +241,19 @@ function _decryptPbes2(encAlg, ciphertext, password, opts) {
  *   var pair = await pki.key.generate("Ed25519");
  *   var spkiPem = await pki.key.export(pair.publicKey, { format: "pem" });
  */
+// Every option pki.key.export reads. Adding one here is the only way to make it accepted.
+var _EXPORT_OPTS = { format: 1, label: 1 };
+
 async function export_(key, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.export options");
+  // This verb does NOT encrypt, and `password` is the option a caller reaches for when they
+  // think it does. Ignoring it writes the private key in the clear while the call site reads
+  // as though it were protected. Every other unknown option here costs a setting that does
+  // nothing; this one costs a plaintext key on disk. `pki.key.encrypt(key, password, opts)`
+  // is the verb that encrypts; export serializes whatever it is handed.
+  guard.identifier.assertKnownKeys(opts, _EXPORT_OPTS, _err, "key/bad-input",
+    "pki.key.export has an unknown option. It serializes only. To protect a private key, call " +
+    "pki.key.encrypt(key, password) first and export its result. The unknown option was: ");
   if (!_isCryptoKey(key)) throw _err("key/bad-input", "export expects a WebCrypto CryptoKey");
   var defaultLabel;
   if (key.type === "private") defaultLabel = "PRIVATE KEY";
@@ -264,8 +290,13 @@ async function export_(key, opts) {
  *   var spki = await pki.key.export(pair.publicKey);
  *   var pub = await pki.key.import(spki);                       // Ed25519 -- algorithm inferred
  */
+// Every option pki.key.import reads.
+var _IMPORT_OPTS = { algorithm: 1, extractable: 1, password: 1, usages: 1 };
+
 async function import_(input, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.import options");
+  guard.identifier.assertKnownKeys(opts, _IMPORT_OPTS, _err, "key/bad-input",
+    "pki.key.import has an unknown option: ");
   var detected = _detectKeyInput(input);
   if (detected.format === "encrypted") {
     if (opts.password == null) throw _err("key/bad-input", "an ENCRYPTED PRIVATE KEY requires opts.password to import");
@@ -303,8 +334,14 @@ async function import_(input, opts) {
  *   var pair = await pki.key.generate("Ed25519");
  *   var pkcs8 = await pki.key.export(pair.privateKey);
  */
+// Every option pki.key.generate reads. `extractable` follows the WebCrypto spelling; a
+// misspelling would leave a key extractable by default, which is the permissive direction.
+var _GENERATE_OPTS = { extractable: 1, usages: 1 };
+
 async function generate(algorithm, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.generate options");
+  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;
   var usages = opts.usages || _generateUsages(_algName(algorithm));
   var pair;
@@ -333,8 +370,13 @@ async function generate(algorithm, opts) {
  *   var pair = await pki.key.generate("Ed25519");
  *   var spki = await pki.key.publicFromPrivate(await pki.key.export(pair.privateKey));
  */
+// Every option pki.key.publicFromPrivate reads.
+var _PUBLIC_FROM_PRIVATE_OPTS = { pem: 1 };
+
 async function publicFromPrivate(privateKey, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.publicFromPrivate options");
+  guard.identifier.assertKnownKeys(opts, _PUBLIC_FROM_PRIVATE_OPTS, _err, "key/bad-input",
+    "pki.key.publicFromPrivate has an unknown option: ");
   var der = await _toPrivateKeyDer(privateKey);
   var spki;
   try {

package/lib/lint.js

@@ -174,7 +174,7 @@ function _effective(rule, cert) {
   if (!rule.effectiveDate) return true;
   var nb = cert.validity && cert.validity.notBefore;
   // allow:nan-date-comparison-unguarded -- nb is a codec-parsed cert notBefore (asn1 readTime rejects a NaN instant); effectiveDate is a Date literal.
-  return (nb instanceof Date) && nb.getTime() >= rule.effectiveDate.getTime();
+  return guard.time.isDate(nb) && guard.time.instantOf(nb) >= guard.time.instantOf(rule.effectiveDate);
 }
 
 function _runLints(rules, cert, ctx) {
@@ -374,7 +374,8 @@ var RFC5280_RULES = [
     check: function (cert) {
       var v = cert.validity;
       // allow:nan-date-comparison-unguarded -- notBefore/notAfter are codec-parsed cert dates (asn1 readTime rejects a NaN instant).
-      return (v.notBefore instanceof Date && v.notAfter instanceof Date && v.notBefore.getTime() > v.notAfter.getTime()) ? true : null;
+      return (guard.time.isDate(v.notBefore) && guard.time.isDate(v.notAfter) &&
+        guard.time.instantOf(v.notBefore) > guard.time.instantOf(v.notAfter)) ? true : null;
     },
   },
   {
@@ -558,7 +559,7 @@ var VALIDITY_SCHEDULE_START = VALIDITY_SCHEDULE[VALIDITY_SCHEDULE.length - 1].fr
 function _validityCeilingDays(notBefore) {
   for (var i = 0; i < VALIDITY_SCHEDULE.length; i++) {
     // allow:nan-date-comparison-unguarded -- notBefore is a codec-parsed cert date (NaN-rejected); the schedule bounds are Date literals.
-    if (notBefore.getTime() >= VALIDITY_SCHEDULE[i].from.getTime()) return VALIDITY_SCHEDULE[i].maxDays;
+    if (guard.time.instantOf(notBefore) >= guard.time.instantOf(VALIDITY_SCHEDULE[i].from)) return VALIDITY_SCHEDULE[i].maxDays;
   }
   // Unreachable: the rule's effectiveDate (VALIDITY_SCHEDULE_START) reports NE for any cert
   // whose notBefore predates the schedule, so the loop always matches the last entry.
@@ -634,9 +635,9 @@ var CABF_TLS_RULES = [
     effectiveDate: VALIDITY_SCHEDULE_START,
     check: function (cert) {
       var v = cert.validity;
-      if (!(v.notBefore instanceof Date) || !(v.notAfter instanceof Date)) return null;
+      if (!guard.time.isDate(v.notBefore) || !guard.time.isDate(v.notAfter)) return null;
       var maxDays = _validityCeilingDays(v.notBefore);
-      var days = (v.notAfter.getTime() - v.notBefore.getTime()) / MS_PER_DAY;
+      var days = (guard.time.instantOf(v.notAfter) - guard.time.instantOf(v.notBefore)) / MS_PER_DAY;
       return days > maxDays ? { context: { days: Math.round(days), maxDays: maxDays } } : null;
     },
   },
@@ -739,9 +740,15 @@ function _applyThreshold(report, severity) {
  *   report.worst;                              // "notice" | "error" | ...
  *   report.findings.map(function (f) { return f.id; });
  */
+// Every option pki.lint.certificate reads. The values of both are already validated below;
+// this refuses a key that is not one of them, so a misspelled `profile` cannot silently lint
+// against the default profile while the call site reads as though it named one.
+var _CERTIFICATE_OPTS = { profile: 1, severity: 1 };
+
 function certificate(input, opts) {
-  opts = opts || {};
-  if (typeof opts !== "object") throw _cfg("lint/bad-input", "pki.lint options must be an object");
+  opts = guard.identifier.optionsObject(opts, _cfg, "lint/bad-input", "pki.lint options");
+  guard.identifier.assertKnownKeys(opts, _CERTIFICATE_OPTS, _cfg, "lint/bad-input",
+    "pki.lint.certificate has an unknown option: ");
   // Validate BOTH config options up front so a config error fails fast, before any work.
   if (opts.severity != null && VALID_SEVERITY.indexOf(opts.severity) === -1) {
     throw _cfg("lint/bad-severity", "unknown severity threshold \"" + opts.severity + "\" (known: " + VALID_SEVERITY.join(", ") + ")");

package/lib/ocsp-verify.js

@@ -28,6 +28,7 @@
 //     unusable per the lightweight profile).
 
 var asn1 = require("./asn1-der");
+var guard = require("./guard-all");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
 var compositeSig = require("./composite-sig");
@@ -144,7 +145,11 @@ function makeOcspVerify(deps) {
       if (!isOctetAligned(rc.signatureValue)) continue;
       if (!(await verifyWithSpki(rc.signatureAlgorithm, rc.signatureValue.bytes, issuer.workingPublicKey, rc.tbsBytes))) continue;
       // The delegate cert MUST itself be valid at the validation instant.
-      if (time < rc.validity.notBefore || time > rc.validity.notAfter) continue;
+      // Instants, never the Date objects: comparing two Dates coerces each through `valueOf`,
+      // which a caller's subclass answers, so the delegate would be checked at whatever moment
+      // the caller's `time` chose to report rather than the one it holds.
+      if (guard.time.instantOf(time) < guard.time.instantOf(rc.validity.notBefore) ||
+        guard.time.instantOf(time) > guard.time.instantOf(rc.validity.notAfter)) continue;
       // The delegate MUST assert id-kp-OCSPSigning; anyEKU / an absent EKU do not.
       var eku;
       try { eku = decodeExt(rc, OID_EKU); }
@@ -199,15 +204,16 @@ function makeOcspVerify(deps) {
       var sr = br.responses[s];
       if (!(await ocspCertIdMatches(sr.certID, cert, issuerNameCandidates, issuerKeyBits))) continue;
       if (ocspHasCriticalExtension(sr.singleExtensions)) continue;
-      if (sr.thisUpdate > time) continue;
-      if (!sr.nextUpdate || sr.nextUpdate < time) continue;
+      if (guard.time.instantOf(sr.thisUpdate) > guard.time.instantOf(time)) continue;
+      if (!sr.nextUpdate || guard.time.instantOf(sr.nextUpdate) < guard.time.instantOf(time)) continue;
       out.matched = true; out.thisUpdate = sr.thisUpdate; out.nextUpdate = sr.nextUpdate;
       var st = sr.certStatus;
       if (st.type === "revoked") {
         // Present-time validation revokes regardless of a future revocationTime (skew/post-dating);
         // only explicit historical validation defers a strictly-future revocation (reports good).
         // allow:nan-date-comparison-unguarded -- revocationTime is codec-parsed (NaN-rejected); a NaN check time makes this FAIL CLOSED (sawGood stays unset -> not treated good), and `time` is validated at the pki.ocsp.verify / path.verifyOcspResponse entry points.
-        if (historical && st.revocationTime instanceof Date && st.revocationTime.getTime() > time.getTime()) { out.sawGood = true; }
+        if (historical && guard.time.isDate(st.revocationTime) &&
+          guard.time.instantOf(st.revocationTime) > guard.time.instantOf(time)) { out.sawGood = true; }
         else if (!out.revoked) { out.revoked = { revocationReason: st.revocationReason || null, reason: "certificate reported revoked by an authorized OCSP responder" + (st.revocationReason ? " (" + st.revocationReason + ")" : "") }; }
       } else if (st.type === "good") { out.sawGood = true; }
       else { out.sawUnknownStatus = true; }

package/lib/ocsp.js

@@ -159,8 +159,19 @@ function buildRequest(query, opts) {
   ], _buildRequest);
 }
 
+// Every option pki.ocsp.buildRequest reads. `nonce` earns the named refusal: it is the
+// anti-replay binding, and a misspelling ships a request with no nonce at all, which the
+// responder answers happily and the caller cannot later bind to.
+// Taken from this verb's own @opts block, which is the published contract; a grep of the
+// function body misses `pem`, read by the shared emitter rather than here.
+var _BUILD_REQUEST_OPTS = {
+  hashAlgorithm: 1, nonce: 1, pem: 1, profile: 1, requestorName: 1, signer: 1
+};
+
 function _buildRequest(query, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "ocsp/bad-input", "pki.ocsp.buildRequest options");
+  guard.identifier.assertKnownKeys(opts, _BUILD_REQUEST_OPTS, _err, "ocsp/bad-input",
+    "pki.ocsp.buildRequest has an unknown option (the anti-replay nonce is `nonce`): ");
   var lightweight = opts.profile === "lightweight";
   var hashName = opts.hashAlgorithm || "sha1";
   if (lightweight && hashName !== "sha1") throw _err("ocsp/bad-input", "the lightweight profile requires a SHA-1 CertID (RFC 5019 sec. 2.1.1)");
@@ -273,8 +284,15 @@ function sign(responseData, responder, opts) {
   ], _sign);
 }
 
+// Every option pki.ocsp.sign reads. `nonce` here is the request nonce this response echoes back.
+// A misspelling emits a response that answers nobody's request, and the client that sent a nonce
+// then reads it as unbound.
+var _SIGN_OPTS = { embedCert: 1, extendedRevoke: 1, nonce: 1, pem: 1 };
+
 function _sign(responseData, responder, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, _err, "ocsp/bad-input", "pki.ocsp.sign options");
+  guard.identifier.assertKnownKeys(opts, _SIGN_OPTS, _err, "ocsp/bad-input",
+    "pki.ocsp.sign has an unknown option (the nonce to echo back is `nonce`): ");
   responseData = responseData || {};
   if (!responder || responder.cert == null || responder.key == null) throw _err("ocsp/bad-input", "a responder must be { cert, key }");
   var respCertDer = _normCertDer(responder.cert, "the responder certificate");
@@ -343,8 +361,8 @@ function _signResponse(responseData, responder, respCert, respCertDer, responder
 // GeneralizedTime in a SIGNED response, and compare false against every currency bound on verify.
 function _asDate(d) {
   if (d == null) return null;
-  var dt = d instanceof Date ? d : new Date(d);
-  if (isNaN(dt.getTime())) throw _err("ocsp/bad-input", "an invalid date value " + JSON.stringify(d));
+  var dt = guard.time.isDate(d) ? d : new Date(d);
+  if (isNaN(guard.time.instantOf(dt))) throw _err("ocsp/bad-input", "an invalid date value " + JSON.stringify(d));
   return dt;
 }
 // A private copy of whatever signer-key material the caller owns, taken at the entry
@@ -485,8 +503,19 @@ function buildErrorResponse(status) {
  *   var res = await pki.ocsp.verify(responseDer, { cert: leafDer, issuer: caDer });
  *   res.status;   // "good" | "revoked" | "unknown"
  */
+// Every option pki.ocsp.verify reads. `requestNonce` is the one worth refusing by name: it is
+// what binds the response to this request. A misspelling leaves nonceMatched null on a call
+// that did ask, and null is the value meaning "the client never asked".
+var _VERIFY_OPTS = { cert: 1, historicalMode: 1, issuer: 1, requestNonce: 1, time: 1 };
+
 function verify(response, opts) {
-  opts = opts || {};
+  // This verb reports faults by rejecting, not throwing, so both entry guards run inside the
+  // same try and surface as a rejection like every other fault on this path.
+  try {
+    opts = guard.identifier.optionsObject(opts, _err, "ocsp/bad-input", "pki.ocsp.verify options");
+    guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "ocsp/bad-input",
+      "pki.ocsp.verify has an unknown option (the request nonce to bind against is `requestNonce`): ");
+  } catch (e) { return Promise.reject(e); }
   if (opts.cert == null || opts.issuer == null) return Promise.reject(_err("ocsp/bad-input", "verify requires opts.cert and opts.issuer"));
   var parsed, cert, issuerCert, time;
   try {

package/lib/path-validate.js

@@ -1170,8 +1170,28 @@ function validateCriticalExtensionStructure(cert) {
  *   });
  *   res.valid;  // boolean; res.results[0].checks carries the per-check codes
  */
+// Every option pki.path.validate reads. The anchor option here is the singular `trustAnchor`,
+// while pki.path.build in this same module spells it `trustAnchors` and takes a list. A caller
+// moving between the two verbs carries the wrong spelling without leaving the namespace, and
+// before this it bought them no anchoring and no error, just "a trustAnchor is required" about
+// an option they believed they had passed.
+// Derived from three sources, because no one of them is complete: the `opts.*` reads in this
+// function, the `params.*` reads in the RFC 5280 6.1.1 state it is passed down to, and the
+// documented prose above, which is the only place `requiredEku` and the three initial-policy
+// inputs appear together. A grep of one function would have shipped a list missing four real
+// options and rejected callers that work today.
+var _VALIDATE_OPTS = {
+  checkPurpose: 1, historicalMode: 1, initialAnyPolicyInhibit: 1, initialExcludedSubtrees: 1,
+  initialExplicitPolicy: 1, initialPermittedSubtrees: 1, initialPolicyMappingInhibit: 1,
+  maxPathCerts: 1, maxPolicyNodes: 1, requireRevocation: 1, requiredEku: 1, revocationChecker: 1,
+  softFail: 1, time: 1, trustAnchor: 1, userInitialPolicySet: 1, verifier: 1
+};
+
 async function validate(path, opts) {
-  opts = opts || {};
+  opts = guard.identifier.optionsObject(opts, E, "path/bad-input", "validate: opts");
+  guard.identifier.assertKnownKeys(opts, _VALIDATE_OPTS, E, "path/bad-input",
+    "pki.path.validate has an unknown option. The anchor here is `trustAnchor`, singular; " +
+    "pki.path.build takes `trustAnchors`. The unknown option was: ");
   if (!Array.isArray(path)) throw E("path/bad-input", "validate: path must be an array of certificates");
   // Bound the per-cert asymmetric-verify work BEFORE parsing an untrusted bundle
   // (the policy-tree cap guards CVE-2023-0464-style blow-up; this guards linear
@@ -1288,10 +1308,15 @@ async function validate(path, opts) {
     }
 
     // 6.1.3(a)(2) validity window.
-    var t = opts.time;
+    //
+    // Instants, never the Date objects. Comparing two Dates coerces each one, and coercion runs
+    // `Symbol.toPrimitive` or `valueOf`, which a caller's subclass answers. opts.time was checked
+    // for a valid held instant at entry, and comparing the object here asked it again through a
+    // door the check never used -- so the value validated and the value compared were two reads.
+    var t = guard.time.instantOf(opts.time);
     var vOk = true, vCode;
-    if (t < cert.validity.notBefore) { vOk = false; vCode = "path/not-yet-valid"; }
-    else if (t > cert.validity.notAfter) { vOk = false; vCode = "path/expired"; }
+    if (t < guard.time.instantOf(cert.validity.notBefore)) { vOk = false; vCode = "path/not-yet-valid"; }
+    else if (t > guard.time.instantOf(cert.validity.notAfter)) { vOk = false; vCode = "path/expired"; }
     checks.push({ name: "validity", ok: vOk, code: vCode });
     if (!vOk) failed = true;
 
@@ -1435,7 +1460,7 @@ async function validate(path, opts) {
         // (Mozilla certverifier isDistrustedCertificateChain: endEntityNotBefore
         // <= distrustAfterTime -> not distrusted; the end-of-day ...235959Z
         // convention keeps the whole boundary day trusted).
-        if (cert.validity.notBefore > distrustDate) {
+        if (guard.time.instantOf(cert.validity.notBefore) > guard.time.instantOf(distrustDate)) {
           checks.push({ name: "distrustAfter", ok: false, code: "path/distrusted-after" }); failed = true;
         }
       }
@@ -1808,7 +1833,7 @@ function selectDelta(candidates) {
   for (var i = 0; i < candidates.length; i++) {
     var c = candidates[i];
     if (best === null) { best = c; continue; }
-    var t = c.crl.thisUpdate.getTime(), bt = best.crl.thisUpdate.getTime();
+    var t = guard.time.instantOf(c.crl.thisUpdate), bt = guard.time.instantOf(best.crl.thisUpdate);
     if (t > bt) { best = c; continue; }
     if (t === bt && c.crlNumber !== null && best.crlNumber !== null && c.crlNumber > best.crlNumber) best = c;
   }
@@ -2053,11 +2078,12 @@ function crlChecker(crls, opts) {
             }
           }
         }
-        if (theCrl.thisUpdate > time) return null;            // not yet valid
+        if (guard.time.instantOf(theCrl.thisUpdate) > guard.time.instantOf(time)) return null;   // not yet valid
         // A CRL with no nextUpdate has no bounded validity -- its currency
         // cannot be confirmed (RFC 5280 sec. 5.1.2.5 requires nextUpdate), so a
         // replayed old CRL must not read "good". Treat it as unusable.
-        if (!theCrl.nextUpdate || theCrl.nextUpdate < time) return null;   // stale / no bound
+        if (!theCrl.nextUpdate ||
+          guard.time.instantOf(theCrl.nextUpdate) < guard.time.instantOf(time)) return null;   // stale / no bound
 
         var sigOk = await crlVerify.verifyCrlSignature(theCrl, issuer.workingPublicKey);
         if (!sigOk) return null;                              // unverifiable -> not authoritative
@@ -2085,7 +2111,8 @@ function crlChecker(crls, opts) {
           // e.g. a timestamped signature -- does an entry dated AFTER the
           // validation time not yet apply.
           // allow:nan-date-comparison-unguarded -- revocationDate is codec-parsed (NaN-rejected); a NaN check time makes this FAIL CLOSED (the skip is not taken -> the entry is treated as revoked), and `time` is validated at the path.validate / crlChecker entry points.
-          if (historical && entry.revocationDate instanceof Date && entry.revocationDate.getTime() > time.getTime()) continue;
+          if (historical && guard.time.isDate(entry.revocationDate) &&
+            guard.time.instantOf(entry.revocationDate) > guard.time.instantOf(time)) continue;
           var rc = crlEntryReason(entry);
           return rc === null ? 0 : rc;
         }
@@ -2460,7 +2487,7 @@ function _verifyOcspParsed(parsedResponse, cert, issuerCert, time, opts) {
   opts = opts || {};
   // The currency + responder-cert validity windows compare against `time`; a missing or invalid
   // check date must fail closed (a NaN compares false against every bound), never silently pass.
-  if (!(time instanceof Date) || isNaN(time.getTime())) {
+  if (!guard.time.isDate(time) || isNaN(guard.time.instantOf(time))) {
     return Promise.reject(E("path/bad-input", "verifyOcspResponse: time must be a valid Date (the currency + responder-validity check date)"));
   }
   // Bind the supplied issuer certificate to the target: the target's issuer DN must equal the
@@ -2666,8 +2693,9 @@ function scoreCandidate(cand, childAki, anchors, time) {
   if (ku && ku.value && ku.value.keyCertSign === true) score += 10;                 // sec. 3.5.3 keyUsage keyCertSign
   var v = cand.validity;
   // allow:nan-date-comparison-unguarded -- cand.validity dates are codec-parsed (asn1 readTime rejects a NaN instant) and time is guard.time.assertValid'd at entry; the validity term is a fail-safe sort hint regardless.
-  if (v && v.notBefore instanceof Date && v.notAfter instanceof Date &&
-    v.notBefore.getTime() <= time.getTime() && time.getTime() <= v.notAfter.getTime()) score += 5;   // sec. 3.5.4 validity
+  if (v && guard.time.isDate(v.notBefore) && guard.time.isDate(v.notAfter) &&
+    guard.time.instantOf(v.notBefore) <= guard.time.instantOf(time) &&
+    guard.time.instantOf(time) <= guard.time.instantOf(v.notAfter)) score += 5;   // sec. 3.5.4 validity
   return score;
 }
 
@@ -2870,9 +2898,30 @@ async function _fetchAiaIssuers(current, aia) {
  *   });
  *   result.valid;                  // true when a path to a trust anchor was found and validated
  */
+// pki.path.build takes its own options AND forwards every pki.path.validate option to each
+// internal validate() call. The documented contract above says so, and validateOpts() copies
+// them wholesale. So the accepted set is the union, derived from _VALIDATE_OPTS. Retyping it
+// would let the two lists drift the first time validate gains an option.
+//
+// `trustAnchor` is removed from the union on purpose: build assigns it per candidate anchor,
+// so a caller passing the singular would have it overwritten and silently ignored. Refusing it
+// is what makes the singular/plural message below actionable rather than trivia.
+var _BUILD_OPTS = (function () {
+  var o = {
+    aiaTimeout: 1, candidates: 1, fetchAia: 1, intermediates: 1, maxAiaFetches: 1,
+    maxAiaPerCert: 1, maxCandidatesConsidered: 1, maxDepth: 1, maxPathCerts: 1,
+    maxResponseBytes: 1, time: 1, tls: 1, transport: 1, trustAnchors: 1, validate: 1
+  };
+  Object.keys(_VALIDATE_OPTS).forEach(function (k) { o[k] = 1; });
+  delete o.trustAnchor;
+  return o;
+})();
+
 async function build(leaf, opts) {
-  opts = opts || {};
-  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw E("path/bad-input", "build: opts must be an object");
+  opts = guard.identifier.optionsObject(opts, E, "path/bad-input", "build: opts");
+  guard.identifier.assertKnownKeys(opts, _BUILD_OPTS, E, "path/bad-input",
+    "pki.path.build has an unknown option. The anchors here are `trustAnchors`, plural; " +
+    "pki.path.validate takes `trustAnchor`. The unknown option was: ");
   var leafCert;
   try { leafCert = coerceCert(leaf); }
   catch (e) { throw E("path/bad-input", "build: the leaf certificate did not parse", e); }
@@ -2965,10 +3014,38 @@ async function build(leaf, opts) {
   // enumerates only own enumerable properties, so no prototype-pollution belt.
   var BUILD_ONLY_OPT = { candidates: 1, intermediates: 1, trustAnchors: 1, maxDepth: 1, maxCandidatesConsidered: 1, validate: 1,
     fetchAia: 1, transport: 1, tls: 1, maxAiaFetches: 1, maxAiaPerCert: 1, aiaTimeout: 1, maxResponseBytes: 1 };
-  var forwarded = {};
-  Object.keys(opts).forEach(function (k) { if (!BUILD_ONLY_OPT[k]) forwarded[k] = opts[k]; });
+  // No prototype, so the set forwarded to each internal validate holds what was put in it and
+  // nothing a runtime carries. A plain `{}` here re-acquired a polluted name after the caller's
+  // own value had been dropped, which is how an explicit `softFail: false` became a waiver.
+  var forwarded = Object.create(null);
+  // Driven by the contract. Walk the validate options this verb forwards and take the ones the
+  // bag answers for.
+  //
+  // Enumerating the bag reads whatever a property walk chooses to report, and that walk skips a
+  // method so a caller's class keeps its own. A known option whose value were a bare function
+  // would be indistinguishable from one, and a defaults-style bag like
+  // `Object.create({ someOption: fn })` would have it dropped here, leaving each internal
+  // validate running without something the caller supplied.
+  //
+  // No option takes a bare function today. `revocationChecker` is `{ check }`, `verifier` is
+  // `{ verify }`, and `transport` is build-only and never forwarded. So this is a hardening
+  // rather than a live defect, and there is no vector that fails without it. It is here because
+  // asking the contract cannot drop a known option whatever its value, and the alternative makes
+  // the forwarded set depend on a walk whose rules exist for an unrelated question.
+  //
+  // `in` rather than an own check, because an option carried on a prototype is one the caller
+  // supplied and `opts.softFail` answers for it. Own membership decides only whether a name is
+  // build-only, which is a question about this module's own table and never about the caller.
+  Object.keys(_VALIDATE_OPTS).forEach(function (k) {
+    if (Object.prototype.hasOwnProperty.call(BUILD_ONLY_OPT, k)) return;
+    if (k in opts) forwarded[k] = opts[k];
+  });
   function validateOpts(anchor) {
-    var vo = {};
+    var vo = Object.create(null);   // same reason as `forwarded` above
+    // Every name in the forwarded set, which was built from the contract above and has no
+    // prototype, so its own keys are exactly what was put in it. A property walk here would
+    // apply the method rule a second time and drop a function-valued option all over again;
+    // forwarding less than was validated is worse than refusing the bag.
     Object.keys(forwarded).forEach(function (f) { vo[f] = forwarded[f]; });
     vo.trustAnchor = anchor;
     return vo;