@blamejs/pki 0.5.7 → 0.5.8

package/lib/lint.js

@@ -12,11 +12,11 @@
  *   a spec-clause citation, and a human message. It ships the RFC 5280 certificate profile
  *   plus a representative CA/Browser Forum TLS Baseline Requirements subset.
  *
- *   Unlike every other toolkit entry, the lint DATA path NEVER throws. A linter surveys a
+ *   Unlike every other toolkit entry, the lint data path never throws. A linter surveys a
  *   corpus that includes malformed members, so `pki.lint.certificate(hostileBytes)` returns
  *   a report whose worst finding is a `fatal` id `lint/unparseable` (carrying the inner
- *   `PkiError.code`) rather than raising. The SOLE throw path is CONFIG-time misuse -- an
- *   unknown profile, an out-of-range severity threshold, or a wrong-type input -- which
+ *   `PkiError.code`) and does not raise. The one throw path is config-time misuse (an
+ *   unknown profile, an out-of-range severity threshold, or a wrong-type input), which
  *   raises a typed `LintError`. This deliberate inversion of the toolkit's fail-closed-throw
  *   posture is what lets an operator lint a whole directory without a try/catch per file.
  * @spec RFC 5280, CA/Browser Forum TLS Baseline Requirements
@@ -41,7 +41,7 @@ function _cfg(code, message, cause) { return new LintError(code, message, cause)
 // Strict-parse pre-emption: this toolkit's parser is strict-DER, so several RFC 5280
 // profile violations a lenient linter (zlint/pkilint) would report as a SPECIFIC finding
 // are instead rejected fail-closed at PARSE and surface here as a single `fatal`
-// lint/unparseable whose context.code names the exact structural violation -- e.g. a
+// lint/unparseable whose context.code names the exact structural violation: e.g. a
 // duplicate extension OID (x509/duplicate-extension), a pathLenConstraint without cA
 // (bad-basic-constraints), an explicit cA=FALSE, or a signatureAlgorithm/tbs mismatch.
 // The registry therefore ships no dedicated rule for a violation the parser already
@@ -53,14 +53,14 @@ function _cfg(code, message, cause) { return new LintError(code, message, cause)
 var NS = pkix.makeNS("lint", LintError, oid);
 var EXT_DECODERS = pkix.certExtensionDecoders(NS).byOid;
 
-// Coverage note: the rules and helpers below carry defensive guards -- `|| []` / `|| ""`
-// on fields the strict parser ALWAYS sets (extensions, serialNumberHex, subject.rdns), and
+// Coverage note: the rules and helpers below carry defensive guards, `|| []` / `|| ""`
+// on fields the strict parser always sets (extensions, serialNumberHex, subject.rdns), and
 // `!Buffer.isBuffer` / `instanceof Date` / minimal-encoding checks against malformed-but-
 // parsed shapes the strict parser never produces. These are fail-safe belts, not reachable
-// paths; they stay verified-unreachable (documented) rather than removed, since the lint
+// paths; they stay verified-unreachable (documented) and are kept, since the lint
 // data path must never throw even on an unexpected upstream shape.
 
-// ---- the advisory result surface (the Do-FIRST: graded findings, not a throw) ----
+// ---- the advisory result surface: graded findings, not a throw ----
 
 // Severity ordering (zlint's LintStatus). NA (not applicable) and NE (not effective --
 // outside a rule's date window) are rule OUTCOMES, tracked in counts, not severities.
@@ -91,8 +91,8 @@ function _finding(rule, detail) {
 // on. That makes it a decision like any other, so it takes the same derivation: the parser's record,
 // not the caller's object.
 //
-// Returns the DERIVED certificate or null, rather than a boolean, because the derived value is what
-// the rules must run against -- answering "yes, that is a certificate" and then linting the object
+// Returns the derived certificate or null, never a boolean, because the derived value is what
+// the rules must run against: answering "yes, that is a certificate" and then linting the object
 // would be the check computed and thrown away. Never throws: _ingest's contract is to return a
 // finding for bad DATA and reserve throws for a wrong-TYPE argument.
 function _derivedCert(o) {
@@ -106,7 +106,7 @@ function _derivedCert(o) {
 }
 
 // Returns { cert } on success, or { fatal: <Finding> } when hostile bytes do not parse
-// (the never-throw data path). Throws LintError ONLY on a wrong-TYPE input (config misuse).
+// (the never-throw data path). Throws LintError only on a wrong-type input (config misuse).
 function _ingest(input) {
   var derived = _derivedCert(input);
   if (derived) return { cert: derived };
@@ -151,7 +151,7 @@ function _hasEku(cert, ekuName) {
 function _makeCtx(cert, profile) {
   var explicitTls = profile === "cabf-tls";
   // A CA certificate is not a TLS server (leaf) certificate even when it carries a
-  // serverAuth EKU, so the default profile must NOT apply the CABF leaf rules (SAN
+  // serverAuth EKU, so the default profile must not apply the CABF leaf rules (SAN
   // required, CN-in-SAN, validity ceiling, ...) to it. An explicit cabf-tls selection
   // still lints whatever the caller hands it as a server cert.
   var bc = _decodeOrNull(cert, "basicConstraints");
@@ -211,7 +211,7 @@ function _serialOctets(cert) {
 // so the linter and the identity comparators agree on what a well-formed dNSName is. Returns a reason or null.
 function _dnsNameProblem(s) { return pkix.dnsNameProblem(s); }
 
-// A genuine IPv4 or IPv6 literal -- a CN validated against an iPAddress SAN rather than a
+// A genuine IPv4 or IPv6 literal, so a CN is validated against an iPAddress SAN and not a
 // dNSName. Routed through the shared strict validator (no node:net, so the toolkit needs no
 // networking module): a per-octet-bounded dotted quad, or a full RFC 4291 IPv6 form
 // (including the IPv4-mapped / dual-stack tail). Rejects 999.999.999.999 and "api:443".
@@ -231,26 +231,26 @@ function _subjectCNs(cert) {
   return out;
 }
 
-// An extension's CRITICALITY is honoured (RFC 5280 4.2: a consumer MUST reject a critical extension
-// it cannot PROCESS) only when this toolkit actually processes its semantics. That authority is
-// path-validate's PROCESSED_EXTENSIONS (the RFC 5280 sec. 6.1 path-processing set), NOT the decoder
-// table: certExtensionDecoders also DECODES many extensions purely for display (qcStatements, the MS
+// An extension's criticality is honoured (RFC 5280 4.2: a consumer MUST reject a critical extension
+// it cannot process) only when this toolkit actually processes its semantics. That authority is
+// path-validate's PROCESSED_EXTENSIONS (the RFC 5280 sec. 6.1 path-processing set), never the decoder
+// table: certExtensionDecoders also decodes many extensions purely for display (qcStatements, the MS
 // enterprise-CA extensions, the SCT list, the *KeyIdentifiers, freshestCRL, issuerAltName) whose
-// critical semantics are not enforced -- path-validate rejects a critical instance of any of those
+// critical semantics are not enforced. path-validate rejects a critical instance of any of those
 // as unrecognized-critical, so the linter flags them too (structural decodability is not validation
-// processing). The one decode-only extension that is LEGITIMATELY critical is precertificatePoison
-// (RFC 6962 sec. 3.1 REQUIRES it critical), so it is allow-listed. Everything else -- a processed
-// extension, or an unregistered OID (algorithm / EKU-purpose OID the name registry resolves but that
-// is no extension) -- falls out correctly: processed -> recognized, unregistered -> unknown. Driving
+// processing). The one decode-only extension that is legitimately critical is precertificatePoison
+// (RFC 6962 sec. 3.1 REQUIRES it critical), so it is allow-listed. Everything else, a processed
+// extension or an unregistered OID (algorithm / EKU-purpose OID the name registry resolves but that
+// is no extension), falls out correctly: processed -> recognized, unregistered -> unknown. Driving
 // this off the validator's set (not the decoder table) means a newly-decoded extension is
 // flagged-when-critical automatically until its semantics are actually processed.
 var _CRITICAL_LEGIT = {};
 _CRITICAL_LEGIT[oid.byName("precertificatePoison")] = true;
 // Mirrors path-validate's unrecognizedCriticalExtension. An extension not in PROCESSED_EXTENSIONS is
 // unknown everywhere (precertificatePoison is the one legitimately-critical exception). An extension
-// that IS processed for an intermediate but is unprocessed on the TARGET (policyMappings) is also
-// flagged: path-validate decides target status purely by path position (i === n), so ANY certificate
-// -- a CA included -- can be validated as the final/target certificate, where a critical instance is
+// that is processed for an intermediate but unprocessed on the target (policyMappings) is also
+// flagged: path-validate decides target status purely by path position (i === n), so any certificate,
+// a CA included, can be validated as the final/target certificate, where a critical instance is
 // rejected. A linter has no path context and cannot rule that out, so it flags these regardless of
 // cA-ness (policyMappings is SHOULD-be-non-critical everywhere, so this never mis-flags conformant input).
 function _isUnknownExtension(extOid) {
@@ -267,7 +267,7 @@ function _rsaModulusBits(spki) {
     var pk = spki.publicKey && (spki.publicKey.bytes || spki.publicKey);
     if (!Buffer.isBuffer(pk)) return null;
     var seq = asn1.decode(pk);
-    // RSAPublicKey ::= SEQUENCE { modulus INTEGER, publicExponent INTEGER } -- exactly two
+    // RSAPublicKey ::= SEQUENCE { modulus INTEGER, publicExponent INTEGER }: exactly two
     // INTEGERs, and the modulus MUST be positive. A negative/zero modulus (a high-bit key
     // mis-encoded without a sign pad) or a missing exponent is malformed, not a real key.
     if (!seq.children || seq.children.length !== 2) return null;
@@ -292,17 +292,17 @@ function _ecCurveName(spki) {
 
 // RFC 5280 marks several extensions MUST (error) or SHOULD (warn) be critical. The shape is
 // uniform: applies when the extension is present, fires when its raw `critical` flag is not
-// true. The rule reads `ctx.raw(name).critical` WITHOUT decoding the value -- criticality is
-// a structural property of the extension, independent of its contents.
+// true. The rule reads `ctx.raw(name).critical` without decoding the value, because criticality
+// is a structural property of the extension, independent of its contents.
 // ---- RFC 5280 4.2.1.4 userNotice DisplayText ----
-// certificatePolicies surfaces each policy's qualifiers as RAW bytes (an external verifier may hash
+// certificatePolicies surfaces each policy's qualifiers as raw bytes (an external verifier may hash
 // them), so the DisplayText values are read out of those bytes here. The UserNotice walk itself lives
 // in schema-pkix (pki.inspect renders the same values), so the two consumers cannot disagree about
 // which members are DisplayText or how a BMPString decodes.
 var OID_UNOTICE = oid.byName("unotice");
 var _T_BMP = asn1.TAGS.BMP_STRING, _T_VISIBLE = asn1.TAGS.VISIBLE_STRING, _T_UTF8 = asn1.TAGS.UTF8_STRING;
-// The C0 and C1 control ranges, tested by code point rather than a regex: the characters this rule is
-// ABOUT cannot appear in the source, and a regex holding them would be a control byte here.
+// The C0 and C1 control ranges, tested by code point instead of a regex: the characters this rule is
+// about cannot appear in the source, and a regex holding them would be a control byte here.
 function _hasControlChar(str) {
   for (var i = 0; i < str.length; i++) {
     var c = str.charCodeAt(i);
@@ -316,7 +316,7 @@ function _hasControlChar(str) {
 // The two decodes below are fail-safe belts on the never-throw data path, not reachable paths: the
 // shared decoder ran pkix.assertPolicyQualifiers before surfacing qualifiersBytes, so the bytes are
 // already known to decode as a SEQUENCE whose every element is a two-member PolicyQualifierInfo led
-// by a readable OID. An undecodable extension never reaches here at all -- it is the separate
+// by a readable OID. An undecodable extension never reaches here at all; it is the separate
 // extension-undecodable finding.
 function _policyDisplayTexts(ctx) {
   var d = ctx.decode("certificatePolicies");
@@ -333,8 +333,8 @@ function _policyDisplayTexts(ctx) {
       try { qid = asn1.read.oid(pq.children[0]); } catch (_e2) { return; }
       if (qid !== OID_UNOTICE) return;
       // Entries whose contents did not decode arrive with a null `text` and keep their tag: the rules
-      // below that read the text skip them, while the encoding rule -- which the ASN.1 tag alone
-      // answers -- still sees them.
+      // below that read the text skip them, while the encoding rule, which the ASN.1 tag alone
+      // answers, still sees them.
       out = out.concat(pkix.userNoticeTexts(pq.children[1]));
     });
   });
@@ -344,8 +344,8 @@ function _hasPolicyDisplayText(cert, ctx) { return _policyDisplayTexts(ctx).leng
 
 // RFC 5280 marks several extensions MUST (error) or SHOULD (warn) be critical. The shape is
 // uniform: applies when the extension is present, fires when its raw `critical` flag is not
-// true. The rule reads `ctx.raw(name).critical` WITHOUT decoding the value -- criticality is
-// a structural property of the extension, independent of its contents.
+// true. The rule reads `ctx.raw(name).critical` without decoding the value, because criticality
+// is a structural property of the extension, independent of its contents.
 function _criticalityRule(name, id, severity, citation, message) {
   return {
     id: id, severity: severity, source: "rfc5280", citation: citation, message: message,
@@ -441,7 +441,7 @@ var RFC5280_RULES = [
     // public keys used to validate digital signatures on certificates" (keyCertSign). A CA
     // key used exclusively for other purposes (CRL signing, key management) MAY carry a
     // non-critical basicConstraints, so the rule applies only when keyCertSign is asserted
-    // (or keyUsage is absent) -- gating on cA alone would false-positive on a CRL-signing CA.
+    // (or keyUsage is absent); gating on cA alone would false-positive on a CRL-signing CA.
     id: "lint/rfc5280/basic-constraints-not-critical", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.9",
     message: "a CA certificate that validates certificate signatures must mark basicConstraints critical",
     appliesTo: function (cert, ctx) {
@@ -466,8 +466,8 @@ var RFC5280_RULES = [
   _criticalityRule("inhibitAnyPolicy", "lint/rfc5280/inhibit-any-policy-not-critical", "error",
     "RFC 5280 4.2.1.14", "the inhibitAnyPolicy extension must be marked critical"),
   // 4.2.1.3: "When present, conforming CAs SHOULD mark this extension as critical." The
-  // recommendation directs the ISSUING CA whenever it includes keyUsage -- in ANY certificate,
-  // including an end-entity leaf -- and does NOT restrict it to certificates whose subject is
+  // recommendation directs the issuing CA whenever it includes keyUsage, in any certificate
+  // including an end-entity leaf, and does not restrict it to certificates whose subject is
   // itself a CA. So the rule is present-gated (matching zlint's w_ext_key_usage_not_critical),
   // not CA-subject-gated; a SHOULD, hence warn.
   _criticalityRule("keyUsage", "lint/rfc5280/key-usage-not-critical", "warn",
@@ -487,9 +487,9 @@ var RFC5280_RULES = [
   // would refuse certificates that are in the wild and otherwise valid. Reporting them is exactly what
   // a linter is for, so each rule carries the severity its normative word does.
   {
-    // DisplayText is SIZE (1..200) -- both ends -- but the two ends get SEPARATE ids rather than one
+    // DisplayText is SIZE (1..200) at both ends, but the two ends get separate ids instead of one
     // length rule, because the section treats them differently: it tells certificate users to handle a
-    // notice ABOVE 200 gracefully, and says nothing of the sort about an empty one. An operator acting
+    // notice above 200 gracefully, and says nothing of the sort about an empty one. An operator acting
     // on that advice suppresses the over-long finding; folding both into a single id would silently
     // suppress the empty case along with it, which has no such carve-out.
     id: "lint/rfc5280/explicit-text-too-long", severity: "warn", source: "rfc5280", citation: "RFC 5280 4.2.1.4",
@@ -604,9 +604,9 @@ var CABF_TLS_RULES = [
   {
     id: "lint/cabf-tls/eku-missing-serverauth", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 7.1.2.7.6",
     message: "a TLS server certificate's extKeyUsage must include id-kp-serverAuth",
-    // Only meaningful when the caller EXPLICITLY lints against the TLS profile; under the
-    // default profile a cert is recognized as TLS BY its serverAuth EKU, so the check is
-    // vacuous and reports NA rather than firing on every non-TLS certificate.
+    // Only meaningful when the caller explicitly lints against the TLS profile; under the
+    // default profile a cert is recognized as TLS by its serverAuth EKU, so the check is
+    // vacuous and reports NA, never firing on every non-TLS certificate.
     appliesTo: function (cert, ctx) { return ctx.explicitTlsProfile; },
     check: function (cert, ctx) { return _hasEku(cert, "serverAuth") ? null : true; },
   },
@@ -618,8 +618,8 @@ var CABF_TLS_RULES = [
       var spki = cert.subjectPublicKeyInfo, name = spki && spki.algorithm && spki.algorithm.name;
       // Fail closed: a key whose size/curve cannot be confirmed to meet the minimum is
       // flagged, not passed. RSA below 2048 bits (or an unreadable modulus), or an EC key
-      // NOT on an approved named curve (including absent / explicit / invalid parameters,
-      // which resolve to a null curve) is a finding -- CABF permits only P-256/384/521.
+      // that is not on an approved named curve (including absent / explicit / invalid parameters,
+      // which resolve to a null curve) is a finding: CABF permits only P-256/384/521.
       if (RSA_KEY_ALGS[name]) { var bits = _rsaModulusBits(spki); return (bits === null || bits < 2048) ? { context: { rsaBits: bits } } : null; }
       if (name === "ecPublicKey") { var curve = _ecCurveName(spki); return APPROVED_EC_CURVES.indexOf(curve) === -1 ? { context: { curve: curve } } : null; }
       // Any other key type (e.g. EdDSA) is out of this rule's RSA-size / EC-curve scope --
@@ -694,7 +694,7 @@ function _selectRules(profile) {
   if (profile == null || profile === "all" || profile === "default") return ALL_RULES;
   if (!PROFILES[profile]) throw _cfg("lint/unknown-profile", "unknown lint profile \"" + profile + "\" (known: " + Object.keys(PROFILES).join(", ") + ")");
   // An explicit cabf-tls run still needs the always-on rfc5280 structural rules? No: the
-  // caller asked for ONE profile. Return exactly that profile's rules.
+  // caller asked for one profile. Return exactly that profile's rules.
   return PROFILES[profile];
 }
 
@@ -721,10 +721,10 @@ function _applyThreshold(report, severity) {
  * `pki.schema.x509` object. Returns a `LintReport`
  * `{ findings: [{id, severity, source, citation, message, context?}], counts, worst, ran }`.
  *
- * The DATA path never throws: hostile bytes produce a single `fatal` finding
- * `lint/unparseable` rather than raising. The ONLY throw path is config-time misuse
- * (`opts.profile` unknown, `opts.severity` out of range, or a wrong-type input) -- a
- * typed `LintError`.
+ * The data path never throws: hostile bytes produce a single `fatal` finding
+ * `lint/unparseable` and no exception. The one throw path is config-time misuse
+ * (`opts.profile` unknown, `opts.severity` out of range, or a wrong-type input), which
+ * raises a typed `LintError`.
  *
  * @opts  profile   One of `pki.lint.profiles()` (default runs every profile). Selecting
  *                  `"cabf-tls"` lints the input AS a TLS server certificate.

package/lib/merkle.js

@@ -12,11 +12,11 @@
  *   RFC 6962 (Certificate Transparency) / RFC 9162 (CT 2.0) Merkle-tree hash
  *   and proof-verification core -- the load-bearing primitive a static-CT
  *   client, a Merkle-Tree-Certificates relying party, and a sigstore / Rekor
- *   inclusion check all compose. It is ALL strict verification over SHA-256:
- *   zero new crypto.
+ *   inclusion check all compose. Every verb is strict verification over
+ *   SHA-256: zero new crypto.
  *
  *   `leafHash` / `nodeHash` / `emptyRootHash` build the tree hashes with the
- *   two domain-separation prefixes fixed by the spec -- a leaf is
+ *   two domain-separation prefixes fixed by the spec: a leaf is
  *   `SHA-256(0x00 || entry)`, an interior node is `SHA-256(0x01 || left ||
  *   right)`, the empty tree is `SHA-256("")`. Those `0x00` / `0x01` prefixes
  *   are the second-preimage defense: without them a leaf whose bytes equal a
@@ -24,16 +24,16 @@
  *
  *   `verifyInclusion` folds an audit path back to a root and constant-time-
  *   compares it to a trusted checkpoint root; `verifyConsistency` reconstructs
- *   BOTH the old and the new root from a consistency proof (the append-only
+ *   both the old and the new root from a consistency proof (the append-only
  *   guarantee lives in the old-root leg). Both are fail-closed: a malformed
  *   coordinate, an out-of-range index, an inverted window, a wrong hash length,
  *   or a proof whose node count does not match the tree geometry throws a typed
- *   `merkle/*` error; the ONLY boolean-`false` result is the final root
+ *   `merkle/*` error; the one boolean-`false` result is the final root
  *   comparison ("root matched" vs "did not"). A `false` from `verifyInclusion`
- *   means "not proven present against this root", never "validly absent" -- an
+ *   means "not proven present against this root", never "validly absent": an
  *   inclusion proof cannot express absence. Tree coordinates are uint64, carried
- *   as `BigInt` so a large index is never `Number`-narrowed. This is NOT a DER
- *   format: like `pki.ct` it is a companion module reached explicitly, never
+ *   as `BigInt` so a large index is never `Number`-narrowed. This is not a DER
+ *   format. Like `pki.ct` it is a companion module reached explicitly, never
  *   routed by the detect-and-parse orchestrator.
  *
  * @card
@@ -171,11 +171,11 @@ function emptyRootHash() {
  * Verify an RFC 6962 / RFC 9162 audit (inclusion) proof: fold `leafHash` up the
  * audit path and constant-time-compare the reconstructed root to `rootHash`.
  * Returns `true` iff the proof binds the leaf to the root; a well-formed proof
- * that does not match returns `false` ("not proven present against this root",
- * NEVER "validly absent"). A malformed input -- a coordinate that is not a
- * non-negative integer (or a Number >= 2^53), `treeSize` 0, `leafIndex >=
- * treeSize`, a non-32-byte hash, or a proof whose node count does not match the
- * tree geometry -- throws a typed `merkle/*` error.
+ * that does not match returns `false`, meaning "not proven present against this
+ * root" and never "validly absent". A malformed input throws a typed `merkle/*`
+ * error: a coordinate that is not a non-negative integer (or a Number >= 2^53),
+ * `treeSize` 0, `leafIndex >= treeSize`, a non-32-byte hash, or a proof whose
+ * node count does not match the tree geometry.
  *
  * @opts
  *   leafIndex:  number | bigint,  // 0-based leaf position (uint64; pass BigInt above 2^53)
@@ -235,19 +235,26 @@ function verifyInclusion(opts) {
  *
  * Verify an RFC 6962 / RFC 9162 consistency proof between an older tree of
  * `oldSize` leaves (root `oldRoot`) and a newer tree of `newSize` leaves (root
- * `newRoot`). Reconstructs BOTH roots from the proof and constant-time-compares
- * each; returns `true` iff both match (the append-only guarantee lives in the
- * old-root leg -- a proof that yields a valid `newRoot` but the wrong `oldRoot`
- * is a rewritten history and returns `false`). The empty tree is a prefix of
- * every tree, so `oldSize` 0 checks `oldRoot == emptyRootHash()` -- and, when
- * `newSize` is also 0, `newRoot == emptyRootHash()` too (both trees empty); for
- * `newSize > 0` an empty-old proof places no binding on `newRoot` (an empty prior
- * tree carries no append-only guarantee -- authenticate `newRoot` separately,
- * e.g. via its checkpoint signature). Equal non-zero sizes require an empty proof
- * and `oldRoot == newRoot`. A malformed input --
- * `oldSize > newSize`, a non-empty proof where
- * the geometry requires none (or empty where it requires one), a non-32-byte
- * hash, or a wrong node count -- throws a typed `merkle/*` error.
+ * `newRoot`). Reconstructs both roots from the proof and constant-time-compares
+ * each; returns `true` iff both match. The append-only guarantee lives in the
+ * old-root leg: a proof that yields a valid `newRoot` but the wrong `oldRoot`
+ * is a rewritten history and returns `false`. Equal non-zero sizes require an
+ * empty proof and `oldRoot == newRoot`.
+ *
+ * An `oldSize` of 0 with a non-empty newer tree is refused as
+ * `merkle/no-consistency-claim`. RFC 6962 sec. 2.1.2 defines the proof for
+ * `0 < oldSize < newSize`: the empty tree is a prefix of every tree by
+ * definition, so there is no proof to check and nothing at all binds `newRoot`.
+ * Returning `true` there would say a step was proven append-only when nothing had
+ * been proven, and a monitor written `if (!verifyConsistency(...)) alarm()` would
+ * take that silence for evidence. A caller with no prior tree has an inclusion
+ * question about the new one, or should start from a checkpoint it already
+ * trusts. Two empty trees are still answered:
+ * that is the degenerate identity case, and both roots must be `emptyRootHash()`.
+ *
+ * A malformed input throws a typed `merkle/*` error: `oldSize > newSize`, a
+ * non-empty proof where the geometry requires none (or empty where it requires
+ * one), a non-32-byte hash, or a wrong node count.
  *
  * @opts
  *   oldSize:  number | bigint,  // leaf count of the older tree (uint64)
@@ -273,18 +280,26 @@ function verifyConsistency(opts) {
 
   if (oldSize > newSize) throw new MerkleError("merkle/old-size-exceeds-new", "oldSize " + oldSize + " exceeds newSize " + newSize);
   if (oldSize === 0n) {
-    if (proof.length !== 0) throw new MerkleError("merkle/bad-proof-length", "an empty older tree admits only the empty consistency proof");
     var er = emptyRootHash();
-    var oldEmpty = _ctEq(oldRoot, er);
-    // The empty tree is a prefix of every tree, so its own root must be the
-    // empty root. When the NEW tree is also empty, its root must be the empty
-    // root too (a bogus newRoot must not pass); when newSize > 0 an empty-old
-    // proof places no binding on newRoot.
+    // newSize 0 is the degenerate identity case, not a consistency proof: both trees are the empty
+    // tree, so both roots must be the empty root and a bogus newRoot must not pass.
     if (newSize === 0n) {
-      var newEmpty = _ctEq(newRoot, er);
-      return oldEmpty && newEmpty;
+      if (proof.length !== 0) throw new MerkleError("merkle/bad-proof-length", "two empty trees admit only the empty consistency proof");
+      return _ctEq(oldRoot, er) && _ctEq(newRoot, er);
     }
-    return oldEmpty;
+    // newSize > 0 falls outside the definition. RFC 6962 sec. 2.1.2 defines PROOF(m, D[n]) for
+    // 0 < m < n, and an empty older tree is a prefix of every tree by definition: there is no
+    // proof to check and nothing whatever is bound about newRoot, which is why the value is not
+    // read on this branch. Returning the same `true` the honest path returns would state that a
+    // step was proven append-only when nothing was proven, and a monitor written
+    // `if (!verifyConsistency(...)) alarm()` would take silence for evidence. A boolean cannot
+    // carry the difference, so the question is refused. A caller with no prior tree has an
+    // inclusion question about the new tree, not a consistency question.
+    throw new MerkleError("merkle/no-consistency-claim",
+      "an empty older tree (oldSize 0) makes no consistency claim about a non-empty newer tree: " +
+      "RFC 6962 sec. 2.1.2 defines the proof for 0 < oldSize < newSize, and nothing here binds " +
+      "newRoot. Verify an inclusion proof against the new tree, or start from a signed tree head " +
+      "you already trust");
   }
   if (oldSize === newSize) {
     if (proof.length !== 0) throw new MerkleError("merkle/sizes-equal-nonempty-proof", "equal tree sizes require an empty consistency proof");
@@ -319,7 +334,7 @@ function verifyConsistency(opts) {
     sn >>= 1n;
   }
   if (sn !== 0n) throw new MerkleError("merkle/bad-proof-length", "consistency proof is shorter than the geometry requires");
-  // Evaluate BOTH constant-time compares unconditionally before combining, so a
+  // Evaluate both constant-time compares unconditionally before combining, so a
   // `&&` never short-circuits the second `timingSafeEqual` (which would leak,
   // via timing, whether the old-root leg matched).
   var okOld = _ctEq(fr, oldRoot);

package/lib/mime.js

@@ -9,9 +9,9 @@
  * splits a multipart body on its boundary, and builds an entity/multipart back. There is NO crypto
  * here -- the CMS layer signs/verifies the canonical bytes this module produces.
  *
- * The LOAD-BEARING rule is canonicalization: the detached signature over a multipart/signed first part
- * is computed over that part's canonical MIME form, so the signer and verifier MUST share ONE
- * canonicalizer -- this module. It carries the caller's typed ErrorClass `E` (constructed
+ * The load-bearing rule is canonicalization: the detached signature over a multipart/signed first part
+ * is computed over that part's canonical MIME form, so the signer and verifier MUST share one
+ * canonicalizer, this module. It carries the caller's typed ErrorClass `E` (constructed
  * `new E(code, message)`), exactly as the byte-reader / guard family do, so every consumer keeps its
  * own `domain/reason` fault code.
  */
@@ -50,14 +50,14 @@ function _unfoldHeaders(headerText) {
   return out;
 }
 
-// Parse a Content-Type / any structured header value into { value, type, params } -- the media type
+// Parse a Content-Type / any structured header value into { value, type, params }: the media type
 // (lowercased) plus its parameters (names lowercased, quotes stripped). Tolerant of extra whitespace.
 function _parseStructured(headerValue) {
   var parts = _splitSemicolons(headerValue);   // always >= 1 element
   var type = _stripComments(parts[0]).trim().toLowerCase();
   var params = {};
   for (var i = 1; i < parts.length; i++) {
-    // RFC 5322 CFWS: a comment around the name/value is folding whitespace, not part of either -- strip it
+    // RFC 5322 CFWS: a comment around the name/value is folding whitespace, not part of either, so strip it
     // so "(note) hp" resolves to the "hp" parameter and a trailing comment does not leak into the value.
     var p = _stripComments(parts[i]);
     var eq = p.indexOf("=");
@@ -70,7 +70,7 @@ function _parseStructured(headerValue) {
   return { value: headerValue.trim(), type: type, params: params };
 }
 
-// Remove RFC 5322 comments -- a "(...)" span (nesting; a backslash quoted-pair escapes the next byte) OUTSIDE
+// Remove RFC 5322 comments: a "(...)" span (nesting; a backslash quoted-pair escapes the next byte) outside
 // a double-quoted string. A "(" inside a quoted string is literal qtext, not a comment. Used to drop CFWS
 // from a structured-header token before the name/value is read, so a comment cannot forge or hide a parameter.
 function _stripComments(s) {
@@ -93,10 +93,10 @@ function _splitSemicolons(s) {
   for (var i = 0; i < s.length; i++) {
     var ch = s[i];
     // RFC 5322 quoted-pair: inside a quoted-string OR a comment a backslash escapes the next char (so an
-    // escaped `"` / `)` does not end the span, and a `;` in an escaped value does not split) -- keep both bytes.
+    // escaped `"` / `)` does not end the span, and a `;` in an escaped value does not split), so keep both bytes.
     if ((inQ || depth > 0) && ch === "\\" && i + 1 < s.length) { cur += ch + s[i + 1]; i++; }
     else if (ch === '"' && depth === 0) { inQ = !inQ; cur += ch; }
-    // RFC 5322 comment: parentheses (outside a quoted-string) delimit a nesting comment -- a `;` or `=` inside
+    // RFC 5322 comment: parentheses (outside a quoted-string) delimit a nesting comment, so a `;` or `=` inside
     // one is CFWS, not structural, so a Content-Type comment like `charset=x (note; hp=y)` cannot forge a parameter.
     else if (ch === "(" && !inQ) { depth++; cur += ch; }
     else if (ch === ")" && !inQ && depth > 0) { depth--; cur += ch; }
@@ -127,7 +127,7 @@ function parse(input, E, code) {
     var nm = rawHeaders[i].slice(0, colon).trim();
     var body = rawHeaders[i].slice(colon + 1);
     // value: the trimmed field body (structured-header parsing wants it trimmed). rawValue: the field body
-    // with only the single conventional ": " delimiter space removed -- leading/trailing whitespace INSIDE
+    // with only the single conventional ": " delimiter space removed. Leading/trailing whitespace inside
     // the body is preserved, so a consumer that must reproduce the exact authenticated field body (S/MIME
     // header protection) is not handed a lossily-trimmed value.
     headers.push({ name: nm, lname: nm.toLowerCase(), value: body.trim(), rawValue: body.replace(/^ /, "") });
@@ -151,9 +151,9 @@ function canonicalizeText(bodyBytes) {
 }
 
 // The canonical MIME form of a part for signing (RFC 8551 sec. 3.1.1): line endings normalized to the
-// CRLF pair over the EXACT bytes -- never a header re-serialization, which would diverge from the
+// CRLF pair over the exact bytes, never a header re-serialization, which would diverge from the
 // signer's digest (and would break a header-less clear-signed part, as OpenSSL's `smime -sign` emits).
-// The signer and verifier both call THIS, so their digests cannot diverge; a transport that mangles
+// The signer and verifier both call this function, so their digests cannot diverge; a transport that mangles
 // CR/LF is repaired identically on both sides. (A binary clear-signed part must carry a base64
 // Content-Transfer-Encoding first -- line-ending canonicalization is defined for text, sec. 3.1.1.)
 function canonicalize(input, E, code) {
@@ -192,7 +192,7 @@ function splitMultipart(bodyBytes, boundary, E, code) {
 // a line (at the body start, or immediately after an LF) AND its line MUST be a complete delimiter --
 // the token, then an optional "--" (close), then only transport-padding whitespace, then CRLF / LF /
 // end-of-buffer. So a "--boundary" substring mid-content, a "--boundaryextra" (a different token), a
-// "--boundary garbage" line, or one not at a line start is NOT matched -- an attacker cannot inject a
+// "--boundary garbage" line, or one not at a line start is not matched, so an attacker cannot inject a
 // fake delimiter inside a part's content.
 function _findDelim(body, delim, from) {
   for (var at = body.indexOf(delim, from); at >= 0; at = body.indexOf(delim, at + delim.length)) {
@@ -217,15 +217,15 @@ function _afterLine(buf, from, E, code) {
 
 // Serialize an ordered list of header fields + a body into a canonical MIME entity: each field as
 // "Name: value\r\n" (routed through the header-injection guard so a CR/LF/NUL in a value can never inject a
-// header or split the message), then the blank-line separator, then the body -- all CRLF-canonicalized so
+// header or split the message), then the blank-line separator, then the body, all CRLF-canonicalized so
 // the bytes match a CMS signer's/verifier's digest. `fields` is [{ name, value }]; `body` is a byte source
-// (or null/empty). This is the single header/entity emitter -- an inline "Content-Type: ...\r\n" string
+// (or null/empty). This is the single header/entity emitter: an inline "Content-Type: ...\r\n" string
 // concatenation is the shape this replaces, so a composer cannot re-inline an unguarded header.
 function buildEntity(fields, body, E, code) {
   var head = "";
   for (var i = 0; i < fields.length; i++) {
     var f = fields[i];
-    // Serialize the VALUE the guard validated + returned -- never a second coercion of f.value (a stateful
+    // Serialize the value the guard validated and returned, never a second coercion of f.value (a stateful
     // toString() could return CRLF on the second call and inject a header past the check).
     var v = guard.header.assertField(f.name, f.value, E, code);
     head += f.name + ": " + v + "\r\n";
@@ -249,10 +249,10 @@ function paramCount(headerValue, name) {
   return n;
 }
 
-// Count parameters with this attribute name -- WITH OR WITHOUT a value. paramCount only counts "name=value"
+// Count parameters with this attribute name, with or without a value. paramCount only counts "name=value"
 // parts, so a bare/valueless attribute (e.g. "Content-Type: text/plain; hp") is invisible to it;
-// paramNameCount still sees the attribute name, so a consumer can fail closed on a malformed bare parameter --
-// or on a bare+valued duplicate ("hp; hp=x") that paramCount undercounts -- rather than silently ignore it.
+// paramNameCount still sees the attribute name, so a consumer can fail closed on a malformed bare parameter,
+// or on a bare+valued duplicate ("hp; hp=x") that paramCount undercounts, instead of silently ignoring it.
 // Comment- + quoted-string-aware, like paramCount; part 0 is the media type (not a parameter), so attributes
 // start at index 1.
 function paramNameCount(headerValue, name) {

package/lib/ocsp-verify.js

@@ -4,7 +4,7 @@
 //
 // @internal -- no operator-facing namespace. The documented surfaces are pki.path.ocspChecker
 // (revocation during path validation) and pki.ocsp.verify (standalone RFC 6960 sec. 3.2 client
-// acceptance), which BOTH compose this ONE verify core. There is deliberately no second, weaker
+// acceptance), which both compose this single verify core. There is deliberately no second, weaker
 // OCSP response-verification path: a standalone verify that re-derived the responder-authorization
 // gates would be the exact fail-open the out-of-path-signer-cert-full-validation discipline exists
 // to prevent.
@@ -18,11 +18,11 @@
 //
 // Rule set (gap-checked verbatim against RFC 6960 sec. 3.2 / 4.1.1 / 4.2.2.2 / 4.2.2.2.1):
 //   - authorizeResponder: the issuing CA directly (responderID identifies the issuer) OR a
-//     CA-issued delegate valid at `time` bearing id-kp-OCSPSigning (anyEKU / absent EKU do NOT
+//     CA-issued delegate valid at `time` bearing id-kp-OCSPSigning (anyEKU / absent EKU do not
 //     authorize), keyUsage-permits-signing, no unknown/malformed critical extension, and
 //     id-pkix-ocsp-nocheck (a transport-free verify cannot otherwise confirm the responder is
 //     unrevoked); the delegate's own issuance signature is verified under the issuer key.
-//   - certIdMatches: serial + issuerNameHash + issuerKeyHash under the CertID's OWN hashAlgorithm
+//   - certIdMatches: serial + issuerNameHash + issuerKeyHash under the CertID's own hashAlgorithm
 //     (a serial-only match is a cross-CA substitution and is rejected).
 //   - currency: thisUpdate <= time and a bounded nextUpdate > time (a nextUpdate-less response is
 //     unusable per the lightweight profile).
@@ -50,7 +50,7 @@ var OID_KEY_USAGE = oid.byName("keyUsage");
 
 function ocspDigest(alg, buf) { return subtle.digest(alg, buf).then(function (h) { return Buffer.from(h); }); }
 
-// The subjectPublicKey BIT STRING VALUE (past the unused-bits octet) of an SPKI DER -- the exact
+// The subjectPublicKey BIT STRING value (past the unused-bits octet) of an SPKI DER: the exact
 // bytes an OCSP CertID issuerKeyHash / byKey KeyHash hash over (RFC 6960 sec. 4.1.1). Throws on a
 // malformed SPKI; the caller fails closed.
 function ocspKeyValue(spkiDer) {
@@ -59,7 +59,7 @@ function ocspKeyValue(spkiDer) {
 
 // makeOcspVerify(deps) -> the bound OCSP verify core. deps = { verifyWithSpki, decodeExt, findExt,
 // unrecognizedCriticalExtension, validateCriticalExtensionStructure, compositeKeyUsageCheck,
-// isNullOrAbsentParams, spliceSpkiParameters, dnEqual } -- the signature engine + RFC 5280
+// isNullOrAbsentParams, spliceSpkiParameters, dnEqual }, the signature engine and RFC 5280
 // cert-profile gates owned by the caller.
 function makeOcspVerify(deps) {
   var verifyWithSpki = deps.verifyWithSpki;
@@ -99,8 +99,8 @@ function makeOcspVerify(deps) {
     return false;
   }
 
-  // A SingleResponse's CertID names the target cert IFF serial AND issuerNameHash + issuerKeyHash
-  // (under the CertID's OWN hashAlgorithm) match the issuer. `issuerNameCandidates` is every RFC
+  // A SingleResponse's CertID names the target cert if and only if serial, issuerNameHash and issuerKeyHash
+  // (under the CertID's own hashAlgorithm) match the issuer. `issuerNameCandidates` is every RFC
   // 5280 sec. 7.1-equal byte encoding of the validated issuer DN to try.
   async function ocspCertIdMatches(certID, cert, issuerNameCandidates, issuerKeyBits) {
     if (certID.serialNumberHex !== cert.serialNumberHex) return false;
@@ -170,13 +170,13 @@ function makeOcspVerify(deps) {
     return null;
   }
 
-  // A BIT STRING is octet-aligned iff its unused-bits count is 0 -- reused from the caller's
+  // A BIT STRING is octet-aligned iff its unused-bits count is 0, reused from the caller's
   // guard so a non-octet-aligned responder signature is never verified.
   function isOctetAligned(bitString) { return !!bitString && bitString.unusedBits === 0; }
 
   // evaluateResponse(resp, cert, issuer, issuerKeyBits, issuerNameCandidates, time, historical) ->
-  // a granular per-response SUMMARY for ONE parsed OCSPResponse, aggregating over ALL of its
-  // matching SingleResponses (a revoked SingleResponse shadows a good one WITHIN the response, the
+  // a granular per-response summary for one parsed OCSPResponse, aggregating over all of its
+  // matching SingleResponses (a revoked SingleResponse shadows a good one within the response, the
   // same fail-closed law the multi-response aggregator applies). Never throws (fail-closed):
   //   { applicable, responderAuthorized, signatureValid, matched, revoked:{reason,revocationReason}?,
   //     sawGood, sawUnknownStatus, thisUpdate?, nextUpdate?, reason }