@blamejs/pki 0.5.3 → 0.5.5

package/lib/merkle.js

@@ -188,8 +188,14 @@ function emptyRootHash() {
  *   var lh = pki.merkle.leafHash(Buffer.from([0]));
  *   pki.merkle.verifyInclusion({ leafIndex: 0, treeSize: 1, leafHash: lh, proof: [], rootHash: lh }); // -> true
  */
+// Every field of this verb is REQUIRED, so a misspelling is the one input that reads as an omission
+// rather than as a value -- and an omitted required field is caught, while a misspelled one leaves
+// the caller believing they supplied a proof about a leaf they never named.
+var _INCLUSION_KEYS = { leafIndex: 1, treeSize: 1, leafHash: 1, rootHash: 1, proof: 1 };
 function verifyInclusion(opts) {
   opts = opts || {};
+  guard.identifier.assertKnownKeys(opts, _INCLUSION_KEYS, function (c, m) { return new MerkleError(c, m); },
+    "merkle/bad-input", "unknown verifyInclusion option ");
   var leafIndex = _coerceCoord(opts.leafIndex, "leafIndex");
   var treeSize = _coerceCoord(opts.treeSize, "treeSize");
   if (treeSize === 0n) throw new MerkleError("merkle/empty-tree", "an empty tree has no leaves to include");
@@ -254,8 +260,11 @@ function verifyInclusion(opts) {
  *   var r = pki.merkle.leafHash(Buffer.from([0]));
  *   pki.merkle.verifyConsistency({ oldSize: 1, newSize: 1, oldRoot: r, newRoot: r, proof: [] }); // -> true
  */
+var _CONSISTENCY_KEYS = { oldSize: 1, newSize: 1, oldRoot: 1, newRoot: 1, proof: 1 };
 function verifyConsistency(opts) {
   opts = opts || {};
+  guard.identifier.assertKnownKeys(opts, _CONSISTENCY_KEYS, function (c, m) { return new MerkleError(c, m); },
+    "merkle/bad-input", "unknown verifyConsistency option ");
   var oldSize = _coerceCoord(opts.oldSize, "oldSize");
   var newSize = _coerceCoord(opts.newSize, "newSize");
   var oldRoot = _node32(opts.oldRoot, "oldRoot");

package/lib/ocsp.js

@@ -57,14 +57,31 @@ var OID_EXTENDED_REVOKE = O("ocspExtendedRevoke");
 
 function _digest(wcHash, buf) { return subtle.digest(wcHash, buf).then(function (h) { return Buffer.from(h); }); }
 function _certOf(arg, what) {
-  if (arg && arg.subjectPublicKeyInfo && arg.tbsBytes) return arg;   // already parsed
-  var der;
-  if (Buffer.isBuffer(arg)) der = arg;
-  else if (arg instanceof Uint8Array) der = Buffer.from(arg);
-  else if (typeof arg === "string") { try { der = x509.pemDecode(arg); } catch (e) { throw _err("ocsp/bad-input", (what || "a certificate") + " PEM could not be decoded", e); } }
-  else throw _err("ocsp/bad-input", (what || "a certificate") + " must be a parsed certificate, a DER Buffer, or a PEM string");
-  try { return x509.parse(der); } catch (e) { throw _err("ocsp/bad-input", (what || "a certificate") + " is not a well-formed X.509 certificate", e); }
+  var label = what || "a certificate";
+  // Re-derived from the bytes its parser read, like every other certificate door. A CertID is an
+  // IDENTITY -- the issuer's name and key hashed, plus the serial -- so a certificate that names one
+  // identity while carrying another's signed bytes would have this verb ask about, or answer for,
+  // a certificate nobody issued.
+  return guard.parsed.acceptDerived(arg, "certificate", function (bytes) {
+    var der = bytes;
+    if (typeof bytes === "string") {
+      try { der = x509.pemDecode(bytes); } catch (e) { throw _err("ocsp/bad-input", label + " PEM could not be decoded", e); }
+    }
+    try { return x509.parse(der); } catch (e) { throw _err("ocsp/bad-input", label + " is not a well-formed X.509 certificate", e); }
+  }, _err, "ocsp/bad-input", label);
+}
+// The response, always parsed from the bytes the caller handed over. See verify's own comment for
+// why an object cannot be accepted here: the three parts of a signature check would come from three
+// independently-chosen properties. The claim is detected on any of the parsed-response fields, so a
+// caller who passes one is told what happened rather than getting a byte-parse fault about its type.
+var _RESPONSE_CLAIM = ["responseStatus", "basicResponse", "tbsResponseDataBytes"];
+function _responseFromBytes(response) {
+  return guard.parsed.fromTrustedSource(response, "ocspResponse", _RESPONSE_CLAIM, function (bytes) {
+    return ocspSchema.parseResponse(_toDer(bytes, "the OCSP response"));
+  }, _err, "ocsp/bad-input",
+  "the OCSP response must be its DER bytes, a PEM string, or an unmodified pki.schema.ocsp.parseResponse result: the signature, the algorithm that verifies it and the bytes it covers are separate properties of a parsed object, so a REBUILT response (Object.assign, spread, a JSON round-trip) could have the three describe different responses and is refused");
 }
+
 function _toDer(input, what) {
   if (Buffer.isBuffer(input)) return input;
   if (input instanceof Uint8Array) return Buffer.from(input);
@@ -456,13 +473,26 @@ function verify(response, opts) {
   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 {
-    parsed = (response && response.responseStatus) ? response : ocspSchema.parseResponse(_toDer(response, "the OCSP response"));
+    // The response is parsed from BYTES, always. A claimed-parsed response carries the signature,
+    // the algorithm that verifies it and the byte range it covers as three independent properties,
+    // so an object could pair one structure's tbsResponseDataBytes with another's signature -- and a
+    // signature the issuing CA made over a certificate it issued would verify as a ResponseData
+    // signature, returning status "good" for a certificate the responder never spoke about.
+    // Parsing here binds all three to one byte string. pki.schema.ocsp.parseResponse remains the
+    // parse-only route for a caller who wants the structure without a verdict.
+    parsed = _responseFromBytes(response);
     cert = _certOf(opts.cert, "the target certificate");
     issuerCert = _certOf(opts.issuer, "the issuer certificate");
     // The time drives the currency + responder-cert validity windows; an invalid Date fails closed
     // via _asDate (a NaN compares false against every bound, silently disabling both), never defaults.
     time = opts.time == null ? new Date() : _asDate(opts.time);
   } catch (e) { return Promise.reject(e); }
+  // The object parsed HERE goes to the verdict verb, not the caller's argument again. It carries the
+  // parser's record, so the verdict verb re-derives from the same recorded bytes -- one snapshot,
+  // read by both. Passing the caller's argument a second time would take a SECOND snapshot of it,
+  // and a shared-memory view can differ between the two: the nonce compared below would belong to
+  // one response and the signature verified to another, which is the split this whole mechanism
+  // exists to close.
   return pathValidate.verifyOcspResponse(parsed, cert, issuerCert, time, { historicalMode: opts.historicalMode === true }).then(function (verdict) {
     // A client that sent no nonce still gets the field, as null. Leaving it absent would make
     // "not requested" indistinguishable from "the field is not there yet" for a consumer reading

package/lib/path-validate.js

@@ -1127,13 +1127,35 @@ function validateCriticalExtensionStructure(cert) {
  * The value-carrying options (`time`, `maxPathCerts`, `maxPolicyNodes`, the
  * subtree seeds, `userInitialPolicySet`, `requiredEku`) are validated at the
  * entry point -- a mis-shaped value throws `path/bad-input` rather than
- * silently not applying. Returns `{ valid, path,
- * results, workingPublicKey, workingPublicKeyAlgorithm,
+ * silently not applying. Returns `{ valid, revocationChecked, anchorConstraints,
+ * path, results, workingPublicKey, workingPublicKeyAlgorithm,
  * workingPublicKeyParameters, validPolicyTree }` where `results[i].checks`
  * carries a per-check reason code (`path/*`) for every step. Pure and
  * re-entrant -- no input object is mutated. An empty path or a missing anchor
  * throws a typed `PathError`.
  *
+ * `valid` alone cannot say whether revocation was ever established, so
+ * `revocationChecked` answers separately, taking the WEAKEST outcome on the
+ * path: `false` when no `revocationChecker` was supplied, `"determined"` when
+ * every certificate got an explicit good or revoked answer, `"waived"` when
+ * `softFail` turned an undetermined one into a pass, and `"undetermined"` when
+ * one could not be answered at all and the path fails for it. The
+ * per-certificate `revocation` check carries the `status` it was decided on and
+ * marks a waiver, so "checked, good" is distinguishable from "could not check,
+ * and you waived it" -- which a stored verdict is re-read to settle. A checker
+ * that THROWS is a fault in the checker rather than a status it reported, so it
+ * fails the path as `path/revocation-checker-error` carrying the fault whatever
+ * `softFail` says -- `softFail` opts into an undetermined ANSWER, and the
+ * built-in checkers report one as `{ status: "unknown" }` rather than throwing.
+ *
+ * `anchorConstraints` reports what the anchor's own trust metadata decided:
+ * the `checkedPurpose` it was judged under, and whether the `distrustAfter`
+ * date and the `purposes` delegator map each applied. That metadata is keyed BY
+ * key purpose, so an anchor carrying it while `opts.checkPurpose` is absent is a
+ * configuration fault (`path/bad-input`) rather than a constraint that silently
+ * does nothing -- a root distrusted years ago must not quietly validate a
+ * current leaf.
+ *
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
@@ -1156,7 +1178,10 @@ async function validate(path, opts) {
   // crypto amplification from an oversized path). Entry-point tier: throw.
   var maxCerts = guard.limits.cap(opts.maxPathCerts, "validate: opts.maxPathCerts", constants.LIMITS.PATH_MAX_CERTS, { E: E, code: "path/bad-input", min: 1 });
   if (path.length > maxCerts) throw E("path/bad-input", "validate: the certification path has " + path.length + " certificates, exceeding the maxPathCerts limit (" + maxCerts + ")");
-  var certs = path.map(function (c) { return (c && c.tbsBytes) ? c : x509.parse(c); });
+  // Through the same door `build` uses, and for the same reason: every certificate this walk decides
+  // over is re-derived from the bytes its parser read (see coerceCert), so a rebuilt object cannot
+  // present a genuine signed range alongside substituted fields.
+  var certs = path.map(function (c, ci) { return coerceCert(c, "validate: path[" + ci + "]"); });
   var n = certs.length;
   if (n < 1) throw E("path/empty-path", "validate: the certification path is empty");
   if (!opts.trustAnchor) throw E("path/bad-input", "validate: a trustAnchor is required");
@@ -1204,6 +1229,22 @@ async function validate(path, opts) {
   // then fails the path closed instead of silently skipping the step.
   var requireRevocation = opts.requireRevocation === true;
   var failed = false;
+  // Whether the revocation rule RAN, and whether any certificate's answer had to be waived. The
+  // verdict reports the two separately because they are different claims: a caller re-reading a
+  // stored result needs to tell "every certificate was determined not revoked" from "the step was
+  // skipped" from "the step could not conclude and you had asked for that to pass".
+  var revocationRan = false, revocationWaived = false, revocationUndetermined = false;
+  // Which of the anchor's purpose-scoped constraints actually decided anything, reported so a
+  // verdict can be re-read to tell an anchor that was judged from one that carried nothing to judge.
+  var anchorDistrustApplied = false, anchorPurposeApplied = false;
+  // A trust anchor carrying purpose-scoped metadata, validated with no purpose to select by, is a
+  // configuration fault. The constraint is KEYED by purpose -- there is no way to apply
+  // `distrustAfter.serverAuth` without being told the validation is about serverAuth -- so without
+  // one the caller's stated intent would be discarded silently, and a root distrusted years ago
+  // would validate a current leaf. An anchor carrying no such metadata is unaffected.
+  if (!checkPurpose && opts.trustAnchor && _hasPurposeScopedMetadata(opts.trustAnchor)) {
+    throw E("path/bad-input", "validate: the trust anchor carries purpose-scoped metadata (distrustAfter / purposes), which is keyed by key purpose -- supply opts.checkPurpose to say which purpose this validation is for, or the constraint cannot be applied");
+  }
 
   for (var idx = 0; idx < n; idx++) {
     var i = idx + 1;
@@ -1274,16 +1315,48 @@ async function validate(path, opts) {
     // 6.1.3(a)(3) revocation.
     if (revocationChecker) {
       var issuerCert = idx > 0 ? certs[idx - 1] : null;   // the anchor issues cert[1]
-      var rv;
+      var rv, rvError = null;
+      // A checker that THROWS -- or whose promise rejects -- is not a checker reporting "unknown".
+      // Laundering the two together made a broken checker indistinguishable from a working one that
+      // could not reach the responder, and under softFail both became a pass. The fault is carried
+      // onto the check so an operator can tell their own bug from a network condition, and it fails
+      // the path whatever softFail says (see the branch below).
       try { rv = await revocationChecker.check(cert, { workingIssuerName: state.workingIssuerName, workingPublicKey: state.workingPublicKey, workingPublicKeyAlgorithm: state.workingPublicKeyAlgorithm, issuerCert: issuerCert }, { time: opts.time, historicalMode: opts.historicalMode === true }); }
-      catch (_e) { rv = { status: "unknown" }; }
+      catch (e) { rv = { status: "error" }; rvError = e; }
       // ONLY an explicit "good" is a determined non-revocation; "revoked" fails;
       // every other value ("unknown", an OCSP tryLater/unauthorized, a typo, a
       // missing status) is undetermined and fails closed unless softFail.
-      if (rv && rv.status === "good") { checks.push({ name: "revocation", ok: true }); }
-      else if (rv && rv.status === "revoked") { checks.push({ name: "revocation", ok: false, code: "path/revoked" }); failed = true; }
-      else if (softFail) { checks.push({ name: "revocation", ok: true }); }
-      else { checks.push({ name: "revocation", ok: false, code: "path/revocation-undetermined" }); failed = true; }
+      //
+      // The two `ok: true` outcomes are NOT the same claim and no longer the same object. "checked,
+      // and it said good" and "could not check, and you waived it" read identically from a bare
+      // boolean, which is the whole reason a stored verdict cannot be re-read to answer whether
+      // revocation was ever established. Each entry now names the status it was decided on, and a
+      // waiver marks itself.
+      var rvStatus = (rv && typeof rv.status === "string") ? rv.status : "unknown";
+      if (rv && rv.status === "good") { checks.push({ name: "revocation", ok: true, status: "good" }); }
+      else if (rv && rv.status === "revoked") { checks.push({ name: "revocation", ok: false, status: "revoked", code: "path/revoked" }); failed = true; }
+      else if (rvError) {
+        // A checker that threw is a FAULT in the checker, not a status it could not reach, and
+        // softFail is the caller opting into an undetermined ANSWER. The built-in CRL and OCSP
+        // checkers return `{status:"unknown"}` for every unreachable or unverifiable condition and
+        // never throw, so a throw here is the caller's own bug -- waiving it would pass the
+        // certificate with no revocation result at all, which is the outcome softFail is asked for
+        // and this is not.
+        checks.push({ name: "revocation", ok: false, status: "error", code: "path/revocation-checker-error", error: rvError });
+        revocationUndetermined = true;
+        failed = true;
+      }
+      else if (softFail) {
+        // No `error` slot here or below: a fault took the branch above, so anything reaching these
+        // two is a status the checker actually reported.
+        checks.push({ name: "revocation", ok: true, status: rvStatus, waived: true });
+        revocationWaived = true;
+      } else {
+        checks.push({ name: "revocation", ok: false, status: rvStatus, code: "path/revocation-undetermined" });
+        revocationUndetermined = true;
+        failed = true;
+      }
+      revocationRan = true;
     } else if (requireRevocation) {
       // No checker was supplied but the caller demands a revocation determination:
       // the step cannot be performed, so fail closed (never silently skip).
@@ -1357,6 +1430,7 @@ async function validate(path, opts) {
       // before the comparison; an absent (undefined/null) date is no restriction.
       var distrustDate = assertAnchorConstraints(ta, checkPurpose);
       if (distrustDate != null) {
+        anchorDistrustApplied = true;
         // STRICTLY > : a leaf whose notBefore == the distrust date stays trusted
         // (Mozilla certverifier isDistrustedCertificateChain: endEntityNotBefore
         // <= distrustAfterTime -> not distrusted; the end-of-day ...235959Z
@@ -1365,8 +1439,11 @@ async function validate(path, opts) {
           checks.push({ name: "distrustAfter", ok: false, code: "path/distrusted-after" }); failed = true;
         }
       }
-      if (checkPurpose && ta.purposes && ta.purposes[checkPurpose] !== true) {
-        checks.push({ name: "purposeTrust", ok: false, code: "path/purpose-not-trusted" }); failed = true;
+      if (checkPurpose && ta.purposes) {
+        anchorPurposeApplied = true;
+        if (ta.purposes[checkPurpose] !== true) {
+          checks.push({ name: "purposeTrust", ok: false, code: "path/purpose-not-trusted" }); failed = true;
+        }
       }
       updateWorkingKey(state, cert);   // 6.1.5(c),(d) -- key AND algorithm AND parameters
     }
@@ -1404,6 +1481,20 @@ async function validate(path, opts) {
 
   return {
     valid: !failed,
+    // What the revocation rule and the anchor's own trust metadata actually decided. `valid` alone
+    // cannot answer either, and both are questions a stored verdict is re-read to settle: was this
+    // certificate ever established as un-revoked, and was the anchor's distrust date consulted.
+    // The WEAKEST outcome on the path, not the fact that a checker ran: a certificate nobody could
+    // answer for leaves revocation unestablished however many others answered, and deriving the word
+    // from "a checker ran" put that run on the same value as one that established every answer.
+    revocationChecked: !revocationRan ? false
+      : revocationUndetermined ? "undetermined"
+        : revocationWaived ? "waived" : "determined",
+    anchorConstraints: {
+      checkedPurpose: checkPurpose || null,
+      distrustAfterApplied: anchorDistrustApplied,
+      purposeTrustApplied: anchorPurposeApplied,
+    },
     path: certs,
     results: state.results,
     workingPublicKey: state.workingPublicKey,
@@ -1446,24 +1537,10 @@ var OID_AUTHORITY_KEY_ID = oid.byName("authorityKeyIdentifier");
 var OID_CRL_NUMBER = oid.byName("cRLNumber");
 var OID_FRESHEST_CRL = oid.byName("freshestCRL");
 
-// IssuingDistributionPoint ::= SEQUENCE { distributionPoint [0] OPTIONAL,
-// onlyContainsUserCerts [1] DEFAULT FALSE, onlyContainsCACerts [2] DEFAULT FALSE,
-// onlySomeReasons [3] ReasonFlags OPTIONAL, indirectCRL [4] DEFAULT FALSE,
-// onlyContainsAttributeCerts [5] DEFAULT FALSE } (RFC 5280 sec. 5.2.5). Declared
-// through the engine so the trailing-field grammar (strictly-ascending tags, each
-// at most once) and the DER BOOLEAN value rules are the shared enforcement, not a
-// hand-walk; a present DEFAULT-FALSE flag encoding FALSE is the omitted default
-// (X.690 sec. 11.5) and rejects at the leaf-value level below.
-var IDP_SCHEMA = schema.seq([
-  schema.trailing([
-    { tag: 0, name: "distributionPoint", schema: schema.any() },
-    { tag: 1, name: "onlyContainsUserCerts", schema: schema.implicitBoolean(1) },
-    { tag: 2, name: "onlyContainsCACerts", schema: schema.implicitBoolean(2) },
-    { tag: 3, name: "onlySomeReasons", schema: schema.implicitBitString(3) },
-    { tag: 4, name: "indirectCRL", schema: schema.implicitBoolean(4) },
-    { tag: 5, name: "onlyContainsAttributeCerts", schema: schema.implicitBoolean(5) },
-  ], { minTag: 0, maxTag: 5, unexpectedCode: "path/bad-idp", orderCode: "path/bad-idp" }),
-], { assert: "sequence", code: "path/bad-idp", what: "IssuingDistributionPoint" });
+// The RFC 5280 sec. 5.2.5 IssuingDistributionPoint grammar, shared with the CRL
+// verbs (pkix.issuingDistributionPoint) so the scope this validator reads and the
+// scope pki.crl.isRevoked refuses to answer past are read by the same rules.
+var IDP_SCHEMA = pkix.issuingDistributionPoint("path/bad-idp");
 
 // RFC 5280 sec. 6.3.2(a): the legal members of reasons_mask are exactly the eight
 // named ReasonFlags bits, 1..8 (`unused` bit 0 is not a reason, and `unspecified`
@@ -1782,7 +1859,16 @@ function selectDelta(candidates) {
  *   typeof checker.check;                     // "function"
  */
 function crlChecker(crls, opts) {
-  var parsed = (crls || []).map(function (c) { return (c && c.tbsBytes) ? c : crl.parse(c); });
+  var parsed = (crls || []).map(function (c, ci) {
+    // Re-derived from the bytes the parser read, exactly as a certificate is. A CRL's answer is a
+    // verdict, and its signature covers a byte range while the revocation list and the scope
+    // extensions are separate properties of the parsed object: keep a correctly signed CRL's
+    // `tbsBytes` and signature, empty `revokedCertificates`, and the signature still verifies while
+    // a revoked certificate reports good. The scope fields fail the same way -- an emptied
+    // `crlExtensions` turns a scope-restricted CRL into one that answers for everything.
+    return guard.parsed.acceptDerived(c, "crl", crl.parse, E, "path/bad-input",
+      "crlChecker: crls[" + ci + "]");
+  });
   // RFC 5280 sec. 6.3.1(b): use-deltas is an INPUT to the algorithm. Default ON --
   // a caller holding a delta wants it used -- and turning it off never makes a
   // verdict weaker, only less determined.
@@ -2222,7 +2308,10 @@ cmsVerify.setEngine({ build: build, validate: validate, toAnchor: toAnchor,
  *   typeof checker.check;                       // "function"
  */
 function ocspChecker(responses) {
-  var parsed = (responses || []).map(function (r) { return (r && r.responseStatus) ? r : ocsp.parseResponse(r); });
+  // The same door verifyOcspResponse uses. This checker's responses reach the identical three-part
+  // signature check, so accepting a parsed object here on a truthy responseStatus would leave the
+  // door shut on one of the two ways into that check and open on the other.
+  var parsed = (responses || []).map(function (r) { return _ocspFromBytes(r); });
   return {
     check: async function (cert, issuer, ctx) {
       var time = ctx.time;
@@ -2272,14 +2361,14 @@ function ocspChecker(responses) {
 
 /**
  * @primitive  pki.path.verifyOcspResponse
- * @signature  pki.path.verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts?) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, reason }>
+ * @signature  pki.path.verifyOcspResponse(response, cert, issuerCert, time, opts?) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, reason }>
  * @since       0.2.22
  * @status      stable
  * @spec        RFC 6960
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
- * Verify a single already-parsed OCSP response for one certificate against its
- * already-parsed issuer certificate at `time` -- the lower-level primitive
+ * Verify a single OCSP response for one certificate
+ * against its already-parsed issuer certificate at `time` -- the lower-level primitive
  * `pki.ocsp.verify` composes after parsing its inputs (most callers want that
  * ergonomic entry, which also handles DER/PEM decoding and request-nonce
  * matching). It runs the EXACT SAME gates the path validator's `ocspChecker`
@@ -2300,6 +2389,16 @@ function ocspChecker(responses) {
  * `time` either way. `time` must be a valid `Date`. A malformed response's parse
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
+ * The response is its DER bytes, a PEM string, or an unmodified
+ * `pki.schema.ocsp.parseResponse` result. A REBUILT parsed response is refused. A
+ * signature check has three parts -- the signature, the algorithm that verifies it,
+ * and the bytes it covers -- and on a parsed object all three are separate properties:
+ * a genuine CA signature over a certificate that CA issued, relabelled, verifies as a
+ * ResponseData signature for a response that never existed. The parser marks what it
+ * returns, so those three are known to have been derived together from one byte
+ * string; `Object.assign`, spread and a JSON round-trip all drop the mark, which is
+ * exactly how such an object is assembled.
+ *
  * @example
  *   var ca = await pki.key.generate("Ed25519");
  *   var caKey = await pki.key.export(ca.privateKey);
@@ -2315,11 +2414,49 @@ function ocspChecker(responses) {
  *     { responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
  *     { cert: caDer, key: caKey });
  *   var cert = pki.schema.x509.parse(leafDer), issuerCert = pki.schema.x509.parse(caDer);
- *   var resp = pki.schema.ocsp.parseResponse(der);
- *   var v = await pki.path.verifyOcspResponse(resp, cert, issuerCert, new Date());
+ *   var v = await pki.path.verifyOcspResponse(der, cert, issuerCert, new Date());
  *   v.status;   // "good" | "revoked" | "unknown"
  */
-function verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts) {
+function verifyOcspResponse(response, cert, issuerCert, time, opts) {
+  var parsedResponse, subject, issuer;
+  try {
+    parsedResponse = _ocspFromBytes(response);
+    // The two certificates go through the same door as the response, for the same reason: this
+    // verdict is about a certificate's IDENTITY -- its serial and its issuer's name and key are
+    // what the CertID is matched against, and the issuer's key is what authorizes a delegated
+    // responder. A caller-assembled certificate could name one identity while carrying another's
+    // signed bytes, so both are re-derived from the bytes their parser read.
+    subject = coerceCert(cert, "the certificate");
+    issuer = coerceCert(issuerCert, "the issuer certificate");
+  } catch (e) { return Promise.reject(e); }
+  return _verifyOcspParsed(parsedResponse, subject, issuer, time, opts);
+}
+
+// The response, always parsed from the bytes the caller handed over.
+//
+// A signature check has three parts -- the signature, the algorithm that verifies it, and the byte
+// range it covers -- and on a claimed-parsed response all three are separate properties of one
+// caller-supplied object. Pair a real CA's signature over a certificate IT issued with that
+// certificate's own tbsBytes and algorithm, label them `signature` / `tbsResponseDataBytes` /
+// `signatureAlgorithm`, and the check verifies: a genuine signature, over the bytes it was made
+// over, under the right key -- for a structure the responder never produced. Parsing binds the three
+// to one byte string, which is the only thing that makes the verdict about a response at all.
+var _OCSP_CLAIM = ["responseStatus", "basicResponse", "tbsResponseDataBytes"];
+function _ocspFromBytes(response) {
+  return guard.parsed.fromTrustedSource(response, "ocspResponse", _OCSP_CLAIM, function (bytes) {
+    if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array) && typeof bytes !== "string") {
+      throw E("path/bad-input", "verifyOcspResponse: the response must be an OCSP response DER Buffer, a PEM string, or a pki.schema.ocsp.parseResponse result");
+    }
+    return ocsp.parseResponse(bytes);
+  }, E, "path/bad-input",
+  "verifyOcspResponse: the response must be its DER bytes, a PEM string, or an unmodified pki.schema.ocsp.parseResponse result: the signature, the algorithm that verifies it and the bytes it covers are separate properties of a parsed object, so a REBUILT response (Object.assign, spread, a JSON round-trip) could have the three describe different responses and is refused");
+}
+
+// The verification over a response this module has ALREADY derived from bytes -- reached only
+// through the door above and through ocspChecker, which parses the responder's own reply. Not
+// exported: this module's export object IS pki.path, so anything on it is public surface and frozen
+// by the API snapshot, whatever a comment beside it claims.
+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.
@@ -2377,41 +2514,22 @@ function nameMatchSoft(rdnsA, rdnsB) {
   catch (_e) { return false; }
 }
 
-// A parsed extension entry the search's findExt dereferences by .oid and, for
-// the subjectAltName, by .value (a Buffer in the identity key).
-function _isExtensionEntry(e) { return !!e && typeof e.oid === "string" && Buffer.isBuffer(e.value); }
-
-// The complete parsed-certificate shape build produces AND hands to validate --
-// every top-level field this module dereferences (grep-verified), each with the
-// type the code assumes. A claimed-parsed object satisfying this cannot throw a
-// raw TypeError anywhere in the search or the validate hand-off.
-function _isParsedCert(o) {
-  return Buffer.isBuffer(o.tbsBytes) &&
-    typeof o.serialNumberHex === "string" &&
-    !!o.signatureAlgorithm && typeof o.signatureAlgorithm.oid === "string" &&
-    !!o.signatureValue && Buffer.isBuffer(o.signatureValue.bytes) &&
-    !!o.validity && o.validity.notBefore instanceof Date && o.validity.notAfter instanceof Date &&
-    !!o.issuer && Array.isArray(o.issuer.rdns) &&
-    !!o.subject && Array.isArray(o.subject.rdns) && Buffer.isBuffer(o.subject.bytes) &&
-    !!o.subjectPublicKeyInfo && Buffer.isBuffer(o.subjectPublicKeyInfo.bytes) &&
-    !!o.subjectPublicKeyInfo.algorithm && typeof o.subjectPublicKeyInfo.algorithm.oid === "string" &&
-    !!o.subjectPublicKeyInfo.publicKey && Buffer.isBuffer(o.subjectPublicKeyInfo.publicKey.bytes) &&
-    typeof o.subjectPublicKeyInfo.publicKey.unusedBits === "number" &&
-    Array.isArray(o.extensions) && o.extensions.every(_isExtensionEntry);
-}
-
-function coerceCert(input) {
-  // An already-parsed certificate is passed through; a DER Buffer / PEM string is
-  // parsed (and its typed error normalized by the caller). A claimed-parsed object
-  // (a truthy tbsBytes) must carry the COMPLETE parsed-certificate shape build and
-  // the validate hand-off dereference -- a bare { tbsBytes } object, or any partial
-  // shape, fails closed here as a typed PathError rather than a raw TypeError deeper
-  // in the walk or inside validate.
-  if (input && typeof input === "object" && !Buffer.isBuffer(input) && input.tbsBytes !== undefined) {
-    if (!_isParsedCert(input)) throw E("path/bad-input", "build: an input has tbsBytes but is not a well-formed parsed certificate");
-    return input;
-  }
-  return x509.parse(input);
+// A certificate reaching a VERDICT is re-derived from the bytes the parser read, never trusted as
+// the object it arrives as. Completeness -- every field present with the right type -- is not enough
+// here, because a certificate's meaning is one signature over one byte range while a parsed
+// certificate presents that range, the signature, and the fields the range encodes as separate
+// properties. Keep a real CA certificate's `tbsBytes` and signature and substitute only its
+// `subjectPublicKeyInfo`, and every completeness rule passes, this walk verifies the ORIGINAL signed
+// range, and then uses the substituted key to check the next certificate -- a forged chain built out
+// of a genuine certificate. Emptying `extensions` is the same move against basicConstraints,
+// keyUsage, the name constraints and the unknown-critical rule.
+//
+// So the door takes the parser's record instead: a certificate from pki.schema.x509.parse re-parses
+// from the bytes it was read from, and anything done to that object since is discarded. One a caller
+// assembled has no record and is refused rather than silently believed.
+function coerceCert(input, label) {
+  return guard.parsed.acceptDerived(input, "certificate", x509.parse, E, "path/bad-input",
+    label || "a certificate");
 }
 
 // A trust-store entry is either a ready anchor tuple { name, publicKey,
@@ -2437,6 +2555,17 @@ function coerceCert(input) {
 // exposed for the same reason: a caller that may never reach the walk -- pki.cms.verify when no
 // signer verified -- has to be able to reject a malformed anchor at ITS entry point, through this
 // same definition, so configuration validity never depends on the message.
+// Does this anchor carry trust metadata that only a named key purpose can unlock? A non-empty
+// `distrustAfter` or `purposes` map is such metadata -- both are indexed BY purpose, so both are
+// inert without one. An EMPTY map states no constraint and is not a reason to refuse.
+function _hasPurposeScopedMetadata(ta) {
+  if (!ta || typeof ta !== "object") return false;
+  return ["distrustAfter", "purposes"].some(function (k) {
+    var m = ta[k];
+    return !!m && typeof m === "object" && Object.keys(m).length > 0;
+  });
+}
+
 function assertAnchorConstraints(ta, checkPurpose) {
   var d = (checkPurpose && ta && ta.distrustAfter) ? ta.distrustAfter[checkPurpose] : null;
   if (d == null) return null;

package/lib/pkcs12-build.js

@@ -296,6 +296,24 @@ function _buildBag(bag, opts, depth) {
 }
 
 // A pre-encoded DER value (one well-formed TLV, no trailing bytes) supplied verbatim (secretValue).
+// The store, always parsed from the BYTES the caller handed over.
+//
+// Both verbs that use this decide integrity, and integrity is the one operation that must not read
+// its inputs from two independently-chosen properties. Accepting a claimed-parsed store let
+// `macedBytes` -- the range the MAC is verified over -- and `safeBags` / `encryptedSafes` -- the
+// content returned as verified -- come from different sources: verify store A's MAC, hand back store
+// B's bags. Parsing here binds them, because both are then derived from one byte string.
+//
+// `pki.schema.pkcs12.parse` remains the parse-only route for a caller who wants the structure
+// without an integrity decision.
+var _STORE_CLAIM = ["integrityMode", "mac", "macedBytes"];
+function _storeFromBytes(pfx) {
+  return guard.parsed.fromTrustedSource(pfx, "pkcs12Store", _STORE_CLAIM, function (bytes) {
+    return schemaPkcs12.parse(_coerceDer(bytes, "pfx"));
+  }, _err, "pkcs12/bad-input",
+  "pfx must be the store's DER bytes, a PEM string, or an unmodified pki.schema.pkcs12.parse result: the MAC is verified over a byte range carried on the object and the bags returned as verified are a separate property of it, so a REBUILT store (Object.assign, spread, a JSON round-trip) could have the two describe different stores and is refused");
+}
+
 function _reqDer(input, label) {
   if (input == null) throw _err("pkcs12/bad-input", label + " is required");
   var der = _bytes(input, label);
@@ -522,8 +540,10 @@ async function build(spec, opts) {
  * @defends pkcs12-mac-forgery (CWE-347)
  * @related pki.pkcs12.build, pki.schema.pkcs12.parse
  *
- * Verify a password-integrity PKCS#12 store's MAC. `pfx` is a `pki.schema.pkcs12.parse` result, a DER
- * `Buffer`, or a PEM string. The password is BMPString+NULL encoded (RFC 7292 App. B.1), the MAC is
+ * Verify a password-integrity PKCS#12 store's MAC. `pfx` is the store's DER `Buffer`, a PEM string, or an
+ * unmodified `pki.schema.pkcs12.parse` result. A REBUILT parsed store is refused: the MAC is verified over
+ * a byte range the object carries, and the parser's mark is what says that range and the store it describes
+ * came from one place. `Object.assign`, spread and a JSON round-trip drop the mark. The password is BMPString+NULL encoded (RFC 7292 App. B.1), the MAC is
  * recomputed over the store's exact AuthenticatedSafe byte range (`macedBytes`) using the store's own MAC
  * parameters -- the classic Appendix B (ID=3) HMAC or the RFC 9579 PBMAC1 -- and constant-time-compared to
  * the stored MAC value. Returns `true` / `false` for the password match; throws `Pkcs12Error` on a MAC-less
@@ -538,8 +558,14 @@ async function build(spec, opts) {
  *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
  */
 async function verifyMac(pfx, password, opts) {
+  return _verifyMacOfStore(_storeFromBytes(pfx), password, opts);
+}
+
+// The MAC computation over a store this module has ALREADY parsed from bytes. Separate from the
+// public verb so `open` can verify the store it just parsed without going back through the door --
+// the door's job is to establish that the store came from the caller's bytes, and by here it has.
+async function _verifyMacOfStore(m, password, opts) {
   opts = opts || {};
-  var m = (pfx && pfx.integrityMode !== undefined && pfx.mac !== undefined) ? pfx : schemaPkcs12.parse(_coerceDer(pfx, "pfx"));
   if (m.integrityMode !== "password" || !m.mac) throw _err("pkcs12/bad-input", "the store carries no password MAC (integrityMode " + m.integrityMode + ")");
   var expected = m.mac.macValue;
   var computed;
@@ -600,8 +626,9 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  * (public-key privacy) safe with `opts.recipientKey` (RFC 7292 sec. 3.1, via `pki.cms.decrypt`) -- returning a
  * structured bundle `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` -- each private key as PKCS#8
  * `PrivateKeyInfo` DER (re-validated), each certificate / CRL / secret as raw DER, all carrying their
- * `friendlyName` / `localKeyId` for pairing. `pfx` is a DER `Buffer`, PEM string, or a
- * `pki.schema.pkcs12.parse` result.
+ * `friendlyName` / `localKeyId` for pairing. `pfx` is the store's DER `Buffer`, a PEM string, or an
+ * unmodified `pki.schema.pkcs12.parse` result; a REBUILT parsed store is refused, since the bytes whose
+ * integrity is checked and the bags returned as checked are separate properties of it.
  *
  * A MAC-less store is refused (`pkcs12/no-integrity`) unless `opts.allowUnauthenticated` is set. A public-key
  * integrity store is verified through `pki.cms.verify` before any bag is trusted; a signature failure is
@@ -635,7 +662,7 @@ async function open(pfx, password, opts) {
   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 = (pfx && pfx.integrityMode !== undefined && pfx.mac !== undefined) ? pfx : schemaPkcs12.parse(_coerceDer(pfx, "pfx"));
+  var m = _storeFromBytes(pfx);
   var macVerified = false;
   var signers = null;
   if (m.integrityMode === "public-key") {
@@ -649,7 +676,7 @@ async function open(pfx, password, opts) {
     if (!res.valid) throw _err("pkcs12/signature-invalid", "the PKCS#12 SignedData signature did not verify (an untrusted or tampered store)");
     signers = res.signers;
   } else if (m.integrityMode === "password") {
-    macVerified = await verifyMac(m, password, opts);
+    macVerified = await _verifyMacOfStore(m, password, opts);
     if (!macVerified) throw _err("pkcs12/mac-mismatch", "the PKCS#12 MAC did not verify (wrong password or a tampered store)");
   } else if (!opts.allowUnauthenticated) {
     throw _err("pkcs12/no-integrity", "the store carries no integrity MAC (integrityMode " + m.integrityMode + "); set opts.allowUnauthenticated to open it anyway");

package/lib/pki-build.js

@@ -395,4 +395,15 @@ function tbsNameField(cert, which) {
   return tbs.children[(hasVersion ? 1 : 0) + (which === "subject" ? 4 : 2)].bytes;
 }
 
-module.exports = { makeBuilder: makeBuilder, KU_BIT: KU_BIT, tbsNameField: tbsNameField };
+// The serialNumber of a parsed X.509 certificate, read from the SIGNED bytes rather than off the
+// object. Same tbs layout as above, and the same reason: where a producer binds an identity to an
+// existing certificate, that identity is issuer AND serial together. Deriving one from the bytes
+// and reading the other from the object lets the halves name different certificates -- a Holder
+// whose issuer is genuine and whose serial is whatever the caller wrote.
+function tbsSerialNumber(cert) {
+  var tbs = asn1.decode(cert.tbsBytes);
+  var hasVersion = tbs.children[0].tagClass === "context" && tbs.children[0].tagNumber === 0;
+  return asn1.read.integer(tbs.children[hasVersion ? 1 : 0]);
+}
+
+module.exports = { makeBuilder: makeBuilder, KU_BIT: KU_BIT, tbsNameField: tbsNameField, tbsSerialNumber: tbsSerialNumber };

package/lib/schema-crl.js

@@ -217,7 +217,13 @@ var CERTIFICATE_LIST = pkix.signedEnvelope(NS, TBS_CERTLIST, {
  *   var crl = pki.schema.crl.parse(der);
  *   crl.revokedCertificates[0].serialNumberHex;  // -> "0a3f"
  */
-var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS });
+// Recording, for the same reason the certificate parser is: a CRL is one signature over one byte
+// range, and a parsed CRL presents that range and the revocation list it encodes as separate
+// properties. Keep a correctly signed CRL's `tbsBytes` and signature and empty `revokedCertificates`
+// and the signature still verifies while the revocation answer comes from the edited list -- a
+// revoked certificate reported as good. The scope fields (`crlExtensions`, an IDP, a delta
+// indicator) fail the same way. The verdict verbs re-parse from what is recorded here.
+var parse = pkix.makeRecordingParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS }, "crl");
 
 /**
  * @primitive  pki.schema.crl.pemDecode