@blamejs/pki 0.4.14 → 0.5.0

package/lib/path-validate.js

@@ -1107,7 +1107,7 @@ function validateCriticalExtensionStructure(cert) {
  * @primitive  pki.path.validate
  * @signature  pki.path.validate(path, opts) -> Promise<result>
  * @since      0.1.16
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280
  * @related    pki.schema.x509.parse, pki.path.crlChecker
  *
@@ -1134,6 +1134,10 @@ function validateCriticalExtensionStructure(cert) {
  * throws a typed `PathError`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2019-01-01T00:00:00Z"), notAfter: new Date("2029-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cert = pki.schema.x509.parse(der);
  *   var res = await pki.path.validate([cert], {
  *     time: new Date("2020-01-01T00:00:00Z"),
@@ -1469,6 +1473,9 @@ function userConstrainedPolicies(state, n) {
 
 var OID_IDP = oid.byName("issuingDistributionPoint");
 var OID_DELTA_CRL = oid.byName("deltaCRLIndicator");
+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,
@@ -1489,6 +1496,58 @@ var IDP_SCHEMA = schema.seq([
   ], { minTag: 0, maxTag: 5, unexpectedCode: "path/bad-idp", orderCode: "path/bad-idp" }),
 ], { assert: "sequence", code: "path/bad-idp", what: "IssuingDistributionPoint" });
 
+// 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`
+// has no ReasonFlags bit at all). 0x1FE is bits 1..8 set.
+//
+// NOTE the numbering divergence, which is the trap in this area: a ReasonFlags BIT
+// is not a CRLReason VALUE. Bits 1..6 coincide with codes 1..6, but bit 7 is
+// privilegeWithdrawn (code 9) and bit 8 is aACompromise (code 10). sec. 6.3.3 never
+// needs a mapping between them -- the mask comes only from IDP/DP ReasonFlags and
+// cert_status only from an entry's CRLReason -- so no bit<->code table exists here,
+// deliberately. constants.NAMES.REASON_FLAGS and NAMES.CRL_REASON stay separate.
+var ALL_REASONS = 0x1FE;
+
+// A ReasonFlags BIT STRING { unusedBits, bytes } -> a bit mask, or null when the
+// encoding is not minimal DER (X.690 sec. 11.2.2 NamedBitList: trailing zero bits
+// MUST be dropped). A null tells the caller the CRL's scope is unknown, which is
+// the same fail-closed posture decodeIdp already takes for a malformed IDP.
+//
+// Bits at or above 9 are undefined by sec. 4.2.1.13. They are IGNORED rather than
+// rejected: an undefined bit can never help reach all-reasons, so ignoring it can
+// only withhold coverage, never grant it. Reading a bounded prefix also means a
+// hostile multi-kilobyte ReasonFlags costs nothing.
+function reasonMaskFromBitString(bs) {
+  if (!bs || !bs.bytes) return null;
+  try { schema.assertMinimalNamedBits(bs.unusedBits, bs.bytes, function (msg) { throw E("path/bad-idp", msg); }); }
+  catch (_e) { return null; }
+  var mask = 0;
+  // From bit 1: sec. 6.3.2(a) defines the legal members as the eight NAMED reasons, and ReasonFlags
+  // bit 0 is  -- not a reason at all. Admitting it could not grant coverage (the completeness
+  // test masks with ALL_REASONS) but would make a shard that asserts ONLY bit 0 look like partial
+  // coverage rather than none, which is the wrong verdict to report.
+  for (var bit = 1; bit <= 8; bit++) {
+    var byteI = bit >> 3;
+    if (byteI >= bs.bytes.length) break;
+    if (bs.bytes[byteI] & (0x80 >> (bit & 7))) mask |= (1 << bit);
+  }
+  return mask;
+}
+
+// RFC 5280 sec. 6.3.3(d)(1)-(4) -- the interim_reasons_mask, in ONE place.
+//   (1) both present            -> intersection
+//   (2) IDP present, DP absent  -> the IDP's reasons
+//   (3) IDP absent, DP present  -> the DP's reasons
+//   (4) both absent             -> all-reasons
+// A null mask means "present but unreadable"; the caller has already marked such a
+// CRL unusable, so treating it as 0 here is belt-and-braces, never a coverage grant.
+function interimReasonMask(idpMask, dpMask) {
+  if (idpMask != null && dpMask != null) return idpMask & dpMask;      // (d)(1)
+  if (idpMask != null) return idpMask;                                  // (d)(2)
+  if (dpMask != null) return dpMask;                                    // (d)(3)
+  return ALL_REASONS;                                                   // (d)(4)
+}
+
 function decodeIdp(ext) {
   // Surface the scope flags the checker gates on. ANY structural or value fault
   // -- non-SEQUENCE, unknown/duplicate/out-of-order field tag, a non-DER BOOLEAN,
@@ -1523,6 +1582,15 @@ function decodeIdp(ext) {
   out.onlyUser = flag(m.fields.onlyContainsUserCerts);
   out.onlyCa = flag(m.fields.onlyContainsCACerts);
   out.onlySomeReasons = m.fields.onlySomeReasons.present ? true : null;
+  // The reason BITS, not just their presence: sec. 6.3.3(d)(1)/(d)(2) need the
+  // value. A present-but-non-minimal ReasonFlags leaves the CRL's scope unknown,
+  // which is the same unusable posture every other IDP fault takes -- otherwise
+  // the (d)(1) intersection would be computed over an encoding DER forbids.
+  out.onlySomeReasonsMask = null;
+  if (m.fields.onlySomeReasons.present) {
+    out.onlySomeReasonsMask = reasonMaskFromBitString(m.fields.onlySomeReasons.value);
+    if (out.onlySomeReasonsMask === null) out.malformed = true;
+  }
   out.indirect = flag(m.fields.indirectCRL);
   out.onlyAttr = flag(m.fields.onlyContainsAttributeCerts);
   return out;
@@ -1582,11 +1650,130 @@ function crlIssuerNamesIssuer(cRLIssuer, issuerRdns) {
   return false;
 }
 
+// The raw extnValue octets of a CRL extension, or null. sec. 6.3.3(c)(2)/(c)(3)
+// compare the IDP and authorityKeyIdentifier of a delta and its base for identity;
+// the comparison is over the exact encoded octets (the sec. 5.2.5 @3648
+// "identical encoding" discipline already used for distributionPoint matching),
+// never over a re-normalized decode.
+function crlExtValue(theCrl, wantOid) {
+  for (var i = 0; i < theCrl.crlExtensions.length; i++) {
+    if (theCrl.crlExtensions[i].oid === wantOid) return theCrl.crlExtensions[i].value;
+  }
+  return null;
+}
+
+// One pass over the bundle: split complete CRLs from deltas and decode, per CRL,
+// the values the merge preconditions compare. A delta whose BaseCRLNumber will not
+// decode as a non-negative INTEGER is unusable AS A DELTA but stays consultable for
+// revocation -- dropping it wholesale would lose a revocation it lists (T1).
+// RFC 5280 sec. 5.2.3 @3404 bounds a CRL number at 20 octets, and pki.crl.sign enforces that on
+// emission. A number past it is non-conforming, so it does not earn the merge -- which can RELEASE
+// a certificate. The value still decodes and the CRL is still consulted for revocation; only the
+// new capability is withheld. Measured on the ENCODED length, matching the producer-side check
+// rather than a re-derived numeric bound.
+function crlNumberWithinBound(n) {
+  if (typeof n !== "bigint" || n < 0n) return false;
+  try { return asn1.decode(asn1.build.integer(n)).content.length <= 20; }
+  catch (_e) { return false; }
+}
+
+function classifyCrls(parsed) {
+  var completes = [], deltas = [];
+  for (var i = 0; i < parsed.length; i++) {
+    var theCrl = parsed[i];
+    var deltaRaw = crlExtValue(theCrl, OID_DELTA_CRL);
+    var deltaCritical = false;
+    for (var dz = 0; dz < theCrl.crlExtensions.length; dz++) {
+      if (theCrl.crlExtensions[dz].oid === OID_DELTA_CRL) { deltaCritical = theCrl.crlExtensions[dz].critical === true; break; }
+    }
+    // schema-crl already decoded cRLNumber to a non-negative BigInt; the IDP,
+    // authorityKeyIdentifier and deltaCRLIndicator values stay RAW octets there,
+    // which is exactly what the byte-identical compares below need.
+    var num = crlExtValue(theCrl, OID_CRL_NUMBER);
+    var rec = {
+      crl: theCrl,
+      crlNumber: crlNumberWithinBound(num) ? num : null,
+      idpRaw: crlExtValue(theCrl, OID_IDP),
+      akiRaw: crlExtValue(theCrl, OID_AUTHORITY_KEY_ID),
+      baseCrlNumber: null,
+      mergeable: false,
+    };
+    if (deltaRaw === null) { completes.push(rec); continue; }
+    try {
+      var n = asn1.read.integer(asn1.decode(deltaRaw));
+      // sec. 5.2.3 @3404: a CRL number may be up to 20 octets. It stays a BigInt
+      // through every comparison below -- narrowing through Number would collapse
+      // large values and make 5.2.4(c)/(d) compare the wrong things.
+      // sec. 5.2.4 @3447 makes deltaCRLIndicator a MUST-be-critical extension. A non-critical one
+      // is non-conforming, so it does not earn the NEW capability of being merged -- merging can
+      // RELEASE a certificate, and that must rest on a conforming indicator. It is still classified
+      // as a delta and still consulted for revocation, which is the shipped behaviour and the
+      // conservative direction.
+      if (crlNumberWithinBound(n) && deltaCritical) { rec.baseCrlNumber = n; rec.mergeable = true; }
+    } catch (_e) {
+      // Unusable AS A DELTA, but still scanned for revocation. That is the conservative direction:
+      // the CRL is still the issuer's, signed and current (it must pass every gate before it is
+      // consulted), so a serial it lists is a genuine revocation and dropping it wholesale could
+      // lose one. Consulting it can only ever find MORE revocations, never grant coverage -- a
+      // delta contributes no reason mask.
+    }
+    deltas.push(rec);
+  }
+  return { completes: completes, deltas: deltas };
+}
+
+// RFC 5280 sec. 6.3.3(c)(1)-(3) + sec. 5.2.4(a)-(d), as one predicate. Every
+// comparison is BigInt or byte-exact: no narrowing, no canonicalization. An
+// extension ABSENT on both sides matches; present on one side only does not.
+function deltaMergesWith(delta, complete) {
+  if (!delta.mergeable) return false;
+  // Both numbers are required: 5.2.4(c)/(d) are ordering rules, and a missing
+  // cRLNumber on either side leaves the ordering unknowable -- fail closed.
+  if (complete.crlNumber === null || delta.crlNumber === null) return false;
+  if (!dnEqualUsable(delta.crl.issuer.rdns, complete.crl.issuer.rdns)) return false;  // (c)(1)
+  if (!sameRawExt(delta.idpRaw, complete.idpRaw)) return false; // (c)(2) / 5.2.4(b)
+  if (!sameRawExt(delta.akiRaw, complete.akiRaw)) return false; // (c)(3)
+  if (!(complete.crlNumber >= delta.baseCrlNumber)) return false;  // 5.2.4(c)
+  if (!(complete.crlNumber < delta.crlNumber)) return false;      // 5.2.4(d)
+  return true;
+}
+// dnEqual THROWS on a DN carrying an embedded NUL/control byte (CVE-2009-2408).
+// For the merge preconditions a DN that cannot be compared is simply not a match:
+// the delta and the base are not shown to share an issuer, so they are not merged.
+// The throw is contained here rather than at the call site so the predicate itself
+// stays a straight-line sequence of comparisons.
+function dnEqualUsable(a, b) {
+  try { return dnEqual(a, b); }
+  catch (_e) { return false; }
+}
+
+function sameRawExt(a, b) {
+  if (a === null && b === null) return true;
+  if (a === null || b === null) return false;
+  return a.equals(b);
+}
+
+// sec. 5.2.4 @3580 makes MULTIPLE current deltas for one scope legal and says the
+// application SHOULD take the one with the latest thisUpdate. Selection, never
+// rejection: treating two current deltas as a fault would refuse a conforming
+// publication. Ties break on the greater cRLNumber, then first-wins.
+function selectDelta(candidates) {
+  var best = null;
+  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();
+    if (t > bt) { best = c; continue; }
+    if (t === bt && c.crlNumber !== null && best.crlNumber !== null && c.crlNumber > best.crlNumber) best = c;
+  }
+  return best;
+}
+
 /**
  * @primitive  pki.path.crlChecker
- * @signature  pki.path.crlChecker(crls) -> RevocationChecker
+ * @signature  pki.path.crlChecker(crls, opts?) -> RevocationChecker
  * @since      0.1.16
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280
  * @related    pki.path.validate, pki.schema.crl.parse
  *
@@ -1599,17 +1786,38 @@ function crlIssuerNamesIssuer(cRLIssuer, issuerRdns) {
  * "unknown" }`. A partitioned/sharded CRL (a critical IDP naming a
  * distribution point) establishes "good" when it corresponds to one of the
  * certificate's own cRLDistributionPoints -- at least one identically-encoded
- * name in common (RFC 5280 sec. 6.3.3) -- and neither side restricts reason
- * codes; a non-corresponding or reason-restricted shard is consulted for
- * revocation only. An out-of-scope, stale, unauthorized, or unverifiable CRL
- * yields `unknown`, which the validator fails closed unless `softFail` is set.
+ * name in common (RFC 5280 sec. 6.3.3). Reason-sharded CRLs ACCUMULATE: each
+ * corresponding CRL contributes its interim reason mask (sec. 6.3.3(d)) and the
+ * certificate is "good" once the shards together cover all eight revocation
+ * reasons, so a CA that partitions by reason code is served. A DELTA CRL is
+ * merged onto a complete CRL it may be combined with (sec. 5.2.4 / 6.3.3(c)):
+ * the delta is searched first, the complete CRL only if the delta left the
+ * status unrevoked, and `removeFromCRL` then releases the certificate -- so a
+ * base+delta pair reports a real verdict where the base alone could not. A
+ * delta that merges with nothing is still consulted for revocation and still
+ * blocks "good": merging may turn undetermined into good or revoked, never a
+ * revoked into a good. A non-corresponding shard is consulted for revocation
+ * only. An out-of-scope, stale, unauthorized, or unverifiable CRL yields
+ * `unknown`, which the validator fails closed unless `softFail` is set.
+ *
+ * A `revoked` verdict carries `reasonCode` (the CRLReason integer, 0 for
+ * `unspecified`) and a `reason` naming it.
+ *
+ * @opts
+ *   useDeltas  boolean  merge delta CRLs onto their base (RFC 5280 sec. 6.3.1(b)).
+ *                       Default true. When false a delta is never merged; it is
+ *                       still consulted for revocation.
  *
  * @example
  *   var checker = pki.path.crlChecker([]);   // no CRLs -> every cert is "unknown"
  *   typeof checker.check;                     // "function"
  */
-function crlChecker(crls) {
+function crlChecker(crls, opts) {
   var parsed = (crls || []).map(function (c) { return (c && c.tbsBytes) ? c : crl.parse(c); });
+  // 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.
+  var useDeltas = !(opts && opts.useDeltas === false);
   return {
     check: async function (cert, issuer, ctx) {
       var time = ctx.time;
@@ -1660,42 +1868,58 @@ function crlChecker(crls) {
       }
 
       // Consult EVERY CRL issued by the cert's issuer -- a clean CRL must not
-      // shadow a revoking one (RFC 5280 6.3.3). A serial listed in ANY
+      // shadow a revoking one (RFC 5280 sec. 6.3.3). A serial listed in ANY
       // authoritative, in-scope, current, verified CRL is revoked; the cert is
-      // "good" only if at least one such CRL was consulted and none list it;
-      // otherwise the status is undetermined.
-      var sawAuthoritative = false;
-      var sawDelta = false;
-      var sawDeltaRemoval = false;   // a delta released this serial from hold
-      var revokedResult = null;      // a base/full CRL revocation, decided at the end
-      for (var k = 0; k < parsed.length; k++) {
-        var theCrl = parsed[k];
+      // "good" only when the CRLs consulted together cover ALL EIGHT revocation
+      // reasons (sec. 6.3.3(l) + the termination rule at @5291) and none list it.
+      //
+      // Note there is deliberately no early exit once the mask is complete: the
+      // shipped checker scans every CRL so a clean one cannot shadow a revoking
+      // one, and stopping at full coverage would reintroduce exactly that.
+      var certStatus = null;          // sec. 6.3.2(b) cert_status; null = UNREVOKED
+      var reasonsMask = 0;            // sec. 6.3.2(a) reasons_mask; the empty set
+      var releasedByUnmergedDelta = false;
+      // A CURRENT, authoritative delta that merged with nothing means the local
+      // revocation picture is incomplete: the base it names may be newer than any
+      // complete CRL held here, so a clean base proves less than it appears to.
+      // The shipped checker blocks  on exactly this, and the merge must only
+      // ever turn undetermined INTO good -- never make an unmerged delta weaker
+      // than it was before this feature existed.
+      var sawUnmergedDelta = false;
+      var classified = classifyCrls(parsed);
+      var consumedDeltas = [];
+
+      // Every gate a CRL must pass before it may speak for this certificate, in
+      // the shipped order. Returns null when the CRL is unusable, otherwise the
+      // interim_reasons_mask it may contribute -- 0 meaning "consulted for
+      // revocation only", which is how a non-corresponding shard is honestly
+      // encoded (it can reveal a revocation but can never establish coverage).
+      async function gateCrl(rec) {
+        // Memoized per RECORD, and the records are rebuilt by classifyCrls on every check(), so the
+        // cache is per-call and the checker stays re-entrant. Without it the base-by-delta pairing
+        // below would repeat an asynchronous public-key signature verification for every pair --
+        // O(completes x deltas) verifications where the shipped loop did O(crls).
+        if (rec._gated) return rec._gate;
+        rec._gate = await gateCrlUncached(rec);
+        rec._gated = true;
+        return rec._gate;
+      }
+      async function gateCrlUncached(rec) {
+        var theCrl = rec.crl;
         // dnEqual throws on a DN carrying an embedded NUL/control byte (CVE-2009-2408).
         // A single malformed CRL in the bundle must NOT abort the whole check (which
         // would mask a later authoritative CRL and pass under softFail) -- treat it
         // as unusable and skip it, consulting the remaining CRLs.
         var issuerMatches;
         try { issuerMatches = dnEqual(theCrl.issuer.rdns, cert.issuer.rdns); }
-        catch (_e) { continue; }
-        if (!issuerMatches) continue;
-        if (!signerAuthorized) continue;
-
-        // A CRL carrying deltaCRLIndicator is a DELTA CRL: it lists only the
-        // CHANGES since a base CRL (RFC 5280 sec. 5.2.4). deltaCRLIndicator is a
-        // RECOGNIZED extension (so a critical one is not "unhandled"); the delta
-        // is acted on only AFTER it passes the currency + signature checks below,
-        // so a stale, malformed, or unverifiable delta cannot spuriously block a
-        // good result. An AUTHORITATIVE delta blocks "good" (its base is not
-        // merged here) and can still reveal a revocation for a serial it lists.
-        var isDelta = false;
-        for (var dz = 0; dz < theCrl.crlExtensions.length; dz++) {
-          if (theCrl.crlExtensions[dz].oid === OID_DELTA_CRL) { isDelta = true; break; }
-        }
+        catch (_e) { return null; }
+        if (!issuerMatches) return null;
+        if (!signerAuthorized) return null;
 
         // A validly-signed CRL carrying a CRITICAL extension this checker does
         // not understand (anything but issuingDistributionPoint / deltaCRLIndicator)
         // may change the CRL's scope or meaning -- treat it as unusable (RFC 5280
-        // 5.2 critical-extension semantics), never authoritative.
+        // sec. 5.2 critical-extension semantics), never authoritative.
         var unhandledCritical = false;
         for (var x = 0; x < theCrl.crlExtensions.length; x++) {
           var xe = theCrl.crlExtensions[x];
@@ -1715,28 +1939,38 @@ function crlChecker(crls) {
             if (ees[ex].critical && ees[ex].oid !== OID_REASON_CODE) { unhandledCritical = true; break; }
           }
         }
-        if (unhandledCritical) continue;
-
-        // A partition-scoped CRL (a specific distributionPoint, or reason-sharded
-        // via onlySomeReasons) covers only part of the issuer's revocations, so it
-        // cannot by itself establish "good" (full coverage is unconfirmed). But a
-        // serial it LISTS is a genuine revocation of this certificate (serials are
-        // unique per issuer), so such a CRL must still be consulted for revocation
-        // -- dropping it wholesale would let a revoked cert slip under softFail.
-        var scopeRevocationOnly = false;
-        var idpExt = null;
-        for (var e = 0; e < theCrl.crlExtensions.length; e++) if (theCrl.crlExtensions[e].oid === OID_IDP) idpExt = theCrl.crlExtensions[e];
-        if (idpExt) {
-          var idp = decodeIdp(idpExt);
-          if (idp.malformed) continue;                       // scope unknown -> unusable
+        if (unhandledCritical) return null;
+
+        // sec. 6.3.3(d): the interim reason mask this CRL contributes. Its two
+        // inputs are the IDP's onlySomeReasons and the CORRESPONDING certificate
+        // DistributionPoint's reasons -- never an entry's reasonCode (sec. 5.2.5
+        // @3628 explicitly permits a shard entry to omit one).
+        // Set when the shard covers no reasons for this certificate. It is recorded rather than
+        // RETURNED here: the currency and signature gates below still have to run, or an expired,
+        // not-yet-valid or FORGED shard could be scanned for revocations and falsely revoke.
+        var noCoverage = false;
+        var idpMask = null, dpMask = null, sawIdp = false;
+        var idpExtension = null;
+        for (var e = 0; e < theCrl.crlExtensions.length; e++) if (theCrl.crlExtensions[e].oid === OID_IDP) idpExtension = theCrl.crlExtensions[e];
+        if (idpExtension) {
+          sawIdp = true;
+          var idp = decodeIdp(idpExtension);
+          if (idp.malformed) return null;                    // scope unknown -> unusable
           // An indirect CRL carries entries for other issuers keyed by the
           // per-entry certificateIssuer attribute (not tracked here) -- matching
           // by serial alone could revoke the wrong cert or falsely cover it, so
           // treat an indirect CRL as unusable until certificateIssuer is honored.
-          if (idp.indirect) continue;
-          if (idp.onlyAttr) continue;                        // scoped to attribute certs, not this public-key cert
-          if (idp.onlyCa && certIsCa !== true) continue;     // out of scope (or CA-ness undeterminable)
-          if (idp.onlyUser && certIsCa !== false) continue;
+          if (idp.indirect) return null;
+          if (idp.onlyAttr) return null;                     // scoped to attribute certs, not this public-key cert
+          if (idp.onlyCa && certIsCa !== true) return null;   // out of scope (or CA-ness undeterminable)
+          if (idp.onlyUser && certIsCa !== false) return null;
+          // The same fail-closed decision the distributionPoint correspondence rests on (sec. 5.2.5
+          // @3601 lets a relying party not support the IDP at all): a scope a non-supporting
+          // verifier would IGNORE is not a scope to build coverage on. So a non-critical IDP's
+          // onlySomeReasons contributes nothing -- which also preserves the shipped property that
+          // an onlySomeReasons shard could only ever WITHHOLD good, never establish it.
+          if (idpExtension.critical === true) idpMask = idp.onlySomeReasonsMask;
+          else if (idp.onlySomeReasons) noCoverage = true;
           if (idp.hasDistributionPoint) {
             // RFC 5280 sec. 6.3.3(b)(2)(i): a partition shard speaks for this
             // certificate only when the IDP's distribution point shares at
@@ -1744,50 +1978,50 @@ function crlChecker(crls) {
             // own DistributionPoints (sec. 5.2.5: "The identical encoding MUST
             // be used in the distributionPoint fields of the certificate and
             // the CRL"). The IDP must also be CRITICAL to be relied on for
-            // scope: sec. 5.2.5 defines the IDP as "a critical CRL extension"
-            // (descriptive phrasing, not an imperative MUST), and a partition
-            // scope a non-supporting relying party would ignore is not a scope
-            // to build "good" on -- a deliberate fail-closed decision. A
-            // non-corresponding shard cannot establish "good" but is still
-            // consulted for revocation below: serials are unique per issuer,
-            // so a listed serial is a genuine revocation (fail closed toward
-            // revoked).
-            var matchedDp = idpExt.critical === true
+            // scope: sec. 5.2.5 describes the IDP as "a critical CRL extension"
+            // (descriptive phrasing, not an imperative MUST -- and @3601 lets a
+            // relying party not support it at all), so building coverage on a
+            // scope a non-supporting verifier would ignore is a deliberate
+            // fail-closed decision. A non-corresponding shard contributes NO
+            // coverage but is still consulted for revocation below: serials are
+            // unique per issuer, so a listed serial is a genuine revocation.
+            var matchedDp = idpExtension.critical === true
               ? correspondingCertDp(idp.distributionPoint, certDPs, cert.issuer.rdns)
               : null;
-            if (!matchedDp) scopeRevocationOnly = true;
-            // sec. 6.3.3(d)(3): a matched DP carrying `reasons` bounds the
-            // interim reason mask below all-reasons -- under the coarse rule
-            // ("good" only at the (d)(4) all-reasons case) that shard is
-            // revocation-only.
-            else if (matchedDp.reasons) scopeRevocationOnly = true;
+            if (!matchedDp) noCoverage = true;
+            // sec. 6.3.3(d)(1)/(d)(3): a matched DP carrying `reasons` bounds the
+            // interim mask. A present-but-unreadable value cannot bound anything
+            // safely, so it contributes nothing rather than defaulting open.
+            else if (matchedDp.reasons) {
+              dpMask = reasonMaskFromBitString(matchedDp.reasons);
+              if (dpMask === null) noCoverage = true;
+            }
           }
-          // sec. 6.3.3(d)(1)/(d)(2): any onlySomeReasons restriction keeps the
-          // interim reason mask below all-reasons -- revocation-only (coarse).
-          if (idp.onlySomeReasons) scopeRevocationOnly = true;
         }
-        if (theCrl.thisUpdate > time) continue;              // not yet valid
+        if (theCrl.thisUpdate > 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) continue;   // stale / no bound
+        if (!theCrl.nextUpdate || theCrl.nextUpdate < time) return null;   // stale / no bound
 
         var sigOk = await crlVerify.verifyCrlSignature(theCrl, issuer.workingPublicKey);
-        if (!sigOk) continue;                                // unverifiable -> not authoritative
-
-        // The CRL is now authoritative + current + verified. An authoritative
-        // delta blocks a "good" result (its base is not merged here) and can only
-        // reveal a revocation -- never establish "good" on its own.
-        if (isDelta) { sawDelta = true; scopeRevocationOnly = true; }
+        if (!sigOk) return null;                              // unverifiable -> not authoritative
+
+        // sec. 6.3.3 @5295: a CRL not named by any distribution point is processed
+        // as though under a DP whose `reasons` and `cRLIssuer` are absent -- i.e.
+        // all-reasons. That is why a full-scope CRL still covers a certificate
+        // that happens to carry a cRLDistributionPoints extension.
+        void sawIdp;
+        return { interim: noCoverage ? 0 : interimReasonMask(idpMask, dpMask) };
+      }
 
+      // sec. 6.3.3(i)/(j): the certificate's entry on one CRL, as a CRLReason
+      // value, or null for UNREVOKED. sec. 6.3.3(i)(2): an entry with no
+      // reasonCode extension is `unspecified` (0), which is a revocation.
+      function scanCrl(theCrl) {
         for (var r = 0; r < theCrl.revokedCertificates.length; r++) {
           var entry = theCrl.revokedCertificates[r];
           if (entry.serialNumberHex !== cert.serialNumberHex) continue;
-          // reasonCode removeFromCRL (8) means the entry was un-revoked. In a
-          // DELTA this releases the serial from hold; because the base is not
-          // merged here, a definitive "revoked" is no longer possible for it -- a
-          // base CRL that still lists it must not override the delta removal.
-          if (crlEntryReason(entry) === 8) { if (isDelta) sawDeltaRemoval = true; continue; }
           // A revocation is effective as of its revocationDate (RFC 5280 sec. 5.3).
           // In the DEFAULT present-time validation a listed serial is revoked
           // regardless of that date -- a future revocationDate is post-dating or
@@ -1797,28 +2031,113 @@ function crlChecker(crls) {
           // 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;
-          // Record the revocation but keep scanning: a delta removeFromCRL for the
-          // same serial (in another CRL) overrides it (base/delta not merged).
-          revokedResult = { status: "revoked", reason: "serial listed in a CRL" };
-          break;
+          var rc = crlEntryReason(entry);
+          return rc === null ? 0 : rc;
+        }
+        return null;
+      }
+
+      // sec. 6.3.3(a)(2): a delta is obtained only when use-deltas is set AND a
+      // locator exists -- freshestCRL on the certificate or on the complete CRL.
+      // sec. 5.2.6 @3719: the locator's CONTENTS are only ever used to find a
+      // delta, never to validate one, so its presence is the whole gate.
+      // PRESENCE only, deliberately. sec. 5.2.6 @3719 says the freshestCRL contents are used to
+      // LOCATE a delta and never to validate one, so decoding them would be using a value the RFC
+      // says not to use. It is also not a security control: enabling the merge grants nothing on its
+      // own, because a delta still has to pass every gate -- issuer, authorization, criticality,
+      // scope, currency and SIGNATURE -- plus the sec. 5.2.4 merge preconditions. An attacker who
+      // could satisfy those already controls the issuing key.
+      var certHasFreshest = !!findExt(cert, OID_FRESHEST_CRL);
+      function deltaLocatorPresent(completeRec) {
+        return certHasFreshest || crlExtValue(completeRec.crl, OID_FRESHEST_CRL) !== null;
+      }
+
+      for (var ci = 0; ci < classified.completes.length; ci++) {
+        var rec = classified.completes[ci];
+        var gate = await gateCrl(rec);
+        if (!gate) continue;
+
+        // sec. 6.3.3(c): pair this complete CRL with a delta it may be combined
+        // with. The delta passes its OWN gates first -- sec. 6.3.3(h) requires
+        // its signature verified and (f) its issuer authorized, exactly as for a
+        // complete CRL -- so a stale, unverifiable or out-of-scope delta is never
+        // merged.
+        var chosenDelta = null;
+        if (useDeltas && deltaLocatorPresent(rec)) {
+          var candidates = [];
+          for (var di = 0; di < classified.deltas.length; di++) {
+            var cand = classified.deltas[di];
+            if (!deltaMergesWith(cand, rec)) continue;
+            if (!(await gateCrl(cand))) continue;
+            // Mergeable and usable: this delta's scope IS covered by a merge, even
+            // if sec. 5.2.4 @3580 selection prefers a sibling with a later
+            // thisUpdate. Only a delta that pairs with NO complete CRL leaves the
+            // picture incomplete -- a losing candidate must not block a good result,
+            // or publishing two current deltas (which the RFC permits) would be
+            // worse than publishing one.
+            cand.accounted = true;
+            candidates.push(cand);
+          }
+          chosenDelta = selectDelta(candidates);
         }
-        // A partition-scoped CRL that did not list this serial does NOT prove the
-        // cert is unrevoked (another shard/reason may revoke it) -- only a
-        // full-scope CRL can establish "good".
-        if (!scopeRevocationOnly) sawAuthoritative = true;   // covered this cert, not listed
+
+        var status;
+        if (chosenDelta) {
+          consumedDeltas.push(chosenDelta);
+          status = scanCrl(chosenDelta.crl);                   // (i) search the delta FIRST
+          if (status === null) status = scanCrl(rec.crl);      // (j) the complete CRL only if still UNREVOKED
+        } else {
+          status = scanCrl(rec.crl);
+        }
+        // (k): removeFromCRL means the certificate is no longer revoked. It is
+        // normalized wherever it appears -- sec. 5.3.1's "only in delta CRLs" binds
+        // the CA that emits it, not this consumer, and rejecting a complete CRL
+        // that carries one would make an unusual-but-harmless CRL unusable.
+        if (status === 8) status = null;
+
+        if (status !== null && certStatus === null) certStatus = status;
+        else if (status === null) reasonsMask |= gate.interim;  // (l): only a clean scope covers
+      }
+
+      // An unmerged delta still speaks, under the shipped fail-closed posture: a
+      // serial it lists is a genuine revocation (serials are unique per issuer),
+      // and a removeFromCRL it carries blocks a definitive revoked without being
+      // able to establish good. This is what keeps the merge MONOTONIC -- it may
+      // turn undetermined into good or revoked, but a delta that merges with
+      // nothing can never erase a revocation the checker would otherwise report.
+      for (var dj = 0; dj < classified.deltas.length; dj++) {
+        var dRec = classified.deltas[dj];
+        if (consumedDeltas.indexOf(dRec) !== -1) continue;
+        // A delta that was MERGEABLE with some complete CRL but lost the sec. 5.2.4 @3580 selection
+        // does not speak for its scope at all -- the selected delta does, and it was evaluated
+        // against the base. Letting a superseded delta contribute its revocation while ignoring its
+        // release would be incoherent: an older delta revoking a certificate that the newer one
+        // releases would resurrect the revocation the CA withdrew.
+        if (dRec.accounted) continue;
+        if (!(await gateCrl(dRec))) continue;
+        sawUnmergedDelta = true;
+        var dStatus = scanCrl(dRec.crl);
+        if (dStatus === null) continue;
+        if (dStatus === 8) { releasedByUnmergedDelta = true; continue; }
+        if (certStatus === null) certStatus = dStatus;
       }
-      // A delta released this serial from hold: without merging its base we cannot
-      // return a definitive revoked (else a released cert stays rejected) -- the
+
+      // A delta released this serial from hold but its base was not merged: a
+      // definitive revoked would leave a released certificate rejected, so the
       // status is undetermined. This outranks a base CRL's revocation.
-      if (sawDeltaRemoval) return { status: "unknown", reason: "a delta CRL released this serial from hold; without merging its base CRL the revocation status is undetermined" };
-      if (revokedResult) return revokedResult;
-      // A delta CRL for this issuer was seen but cannot be merged with its base,
-      // so the current revocation picture is incomplete -- never report "good".
-      if (sawDelta) return { status: "unknown", reason: "a delta CRL cannot be evaluated without combining it with its base CRL, so the revocation status is undetermined" };
-      if (sawAuthoritative) return { status: "good" };
+      if (releasedByUnmergedDelta) return { status: "unknown", reason: "a delta CRL released this serial from hold; without merging its base CRL the revocation status is undetermined" };
+      if (certStatus !== null) {
+        var reasonName = constants.NAMES.CRL_REASON[String(certStatus)] || "unspecified";
+        return { status: "revoked", reasonCode: certStatus, reason: "serial listed in a CRL (" + reasonName + ")" };
+      }
+      if (sawUnmergedDelta) return { status: "unknown", reason: "a delta CRL cannot be combined with any complete CRL held here, so the revocation picture is incomplete" };
+      if ((reasonsMask & ALL_REASONS) === ALL_REASONS) return { status: "good" };
       if (certScopeFault) {
         return { status: "unknown", reason: "no authoritative in-scope CRL covers this certificate; its basicConstraints extension is unreadable (" + certScopeFault + "), so scope-limited CRLs were skipped" };
       }
+      if (reasonsMask !== 0) {
+        return { status: "unknown", reason: "the CRLs available cover only some revocation reasons for this certificate; no combination covers all of them" };
+      }
       return { status: "unknown", reason: "no authoritative in-scope CRL covers this certificate" };
     },
   };
@@ -1897,7 +2216,7 @@ cmpSession.setEngine({ build: build, validate: validate, toAnchor: toAnchor, coe
  * @primitive  pki.path.ocspChecker
  * @signature  pki.path.ocspChecker(responses) -> RevocationChecker
  * @since      0.1.32
- * @status     experimental
+ * @status     stable
  * @spec       RFC 6960
  * @related    pki.path.validate, pki.schema.ocsp.parseResponse, pki.path.crlChecker
  *
@@ -1976,7 +2295,7 @@ 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 }>
  * @since       0.2.22
- * @status      experimental
+ * @status      stable
  * @spec        RFC 6960
  * @related     pki.ocsp.verify, pki.path.ocspChecker
  *
@@ -2003,6 +2322,20 @@ function ocspChecker(responses) {
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: caKey });
+ *   var der = await pki.ocsp.sign(
+ *     { 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());
  *   v.status;   // "good" | "revoked" | "unknown"
@@ -2359,6 +2692,11 @@ async function _fetchAiaIssuers(current, aia) {
  * @opts  maxResponseBytes       Per-fetch response size cap, forwarded to the transport (tightenable downward only).
  * @opts  (validate options)     Every `pki.path.validate` option (`requiredEku`, `revocationChecker`, `checkPurpose`, the initial policy inputs, ...) is forwarded unchanged.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemString = await pki.x509.sign({ subject: "Example Root", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"], subjectKeyIdentifier: true } },
+ *     { key: await pki.key.export(pair.privateKey) }, { pem: true });
  *   var result = await pki.path.build(pemString, {
  *     candidates: [],              // untrusted intermediates (the openssl -untrusted set)
  *     trustAnchors: [pemString],   // a self-signed root, or a { name, publicKey, algorithm } tuple