@blamejs/pki 0.5.7 → 0.5.8

package/lib/guard-identifier.js

@@ -21,11 +21,11 @@
 // silent false-reject). Every string-form identifier check routes through here so
 // the string and DER forms cannot diverge.
 
-// The dotted-decimal grammar, walked rather than matched. `(0|[1-9]\d*)(\.(0|[1-9]\d*))+`
+// The dotted-decimal grammar, walked instead of matched. `(0|[1-9]\d*)(\.(0|[1-9]\d*))+`
 // nests a quantified group inside a quantified group with an alternation in each,
-// which is the shape whose cost on a REJECTING string is a property of the pattern
-// rather than of the length -- and this guard's whole job is to be handed strings
-// that reject. Walking the string is one pass, one comparison per character, and it
+// which is the shape whose cost on a rejecting string is a property of the pattern
+// and not of the length, and this guard's whole job is to be handed strings that
+// reject. Walking the string is one pass, one comparison per character, and it
 // states the two rules plainly: an arc is one or more digits, and an arc longer than
 // one digit does not start with zero (the leading-zero form round-trips to a
 // DIFFERENT OID, which is the divergence this guard exists to stop).
@@ -49,14 +49,14 @@ function _isDottedDecimal(str) {
 
 // assertCanonicalOid(str, E, code, label, boundsCode) -> str | throws
 // A canonical dotted-decimal object identifier string: two or more arcs, each a
-// non-negative decimal integer with no leading zero (the SYNTAX), and -- unless
-// bounds are waived -- the root arc 0..2 with the second arc 0..39 under roots 0
-// and 1 (the X.660 ENCODABILITY bounds: the first two arcs pack into a single
+// non-negative decimal integer with no leading zero (the syntax), and, unless
+// bounds are waived, the root arc 0..2 with the second arc 0..39 under roots 0
+// and 1 (the X.660 encodability bounds: the first two arcs pack into a single
 // sub-identifier as 40*root+second). E is the (code, message) typed-error factory:
 //   - a syntax fault always throws E(code, ...).
-//   - boundsCode === null waives the arc-bound check -- for a LOOKUP key (oid.name
+//   - boundsCode === null waives the arc-bound check, for a lookup key (oid.name
 //     / oid.has), where a well-formed but non-encodable OID is simply not
-//     registered (a miss), not an error.
+//     registered (a miss) and not an error.
 //   - otherwise an out-of-range arc throws E(boundsCode, ...) (boundsCode defaults
 //     to code), so a caller distinguishing the two reasons (oid.js: oid/bad-input
 //     syntax vs oid/bad-arc bounds) keeps both codes.
@@ -79,27 +79,27 @@ function assertCanonicalOid(str, E, code, label, boundsCode) {
   return str;
 }
 
-// assertKnownKeys(obj, known, E, code, label) -- every own key of `obj` must appear in `known`.
+// assertKnownKeys(obj, known, E, code, label): every own key of `obj` must appear in `known`.
 //
 // The shape this replaces was hand-written in a dozen callers, and it is worth one home because
-// getting it wrong fails OPEN in the quietest possible way: an options object whose key is
+// getting it wrong fails open in the quietest possible way: an options object whose key is
 // misspelled silently carries the default, so a caller who asked for a stricter check gets the
 // looser behaviour and no error. Two details are easy to lose in a re-inline and are fixed here.
-// `known` is consulted with hasOwnProperty rather than a truthiness test, so an inherited Object
+// `known` is consulted with hasOwnProperty and not a truthiness test, so an inherited Object
 // member ("constructor", "toString") cannot read as a recognised key; and the walk is over own
-// enumerable keys, so a `__proto__` arriving from JSON is inspected rather than skipped.
+// enumerable keys, so a `__proto__` arriving from JSON is inspected instead of skipped.
 //
 // @enforced-by behavioral -- an options-shape walk has no rename-proof code shape; the RED vectors
 // (an unknown key, an inherited name, a JSON-borne __proto__) are the guard.
 //
-// `message` is the caller's OWN wording, so routing an existing check through this guard changes
+// `message` is the caller's own wording, so routing an existing check through this guard changes
 // what is checked, never what the operator reads: a string is the prefix the quoted key is appended
 // to, and a function (key) -> string builds the whole sentence, for the many callers that name the
 // key mid-sentence and follow it with the hint that says what to pass instead.
 //
 // @enforced-by guard-shape-reinlined
-// The shape requires the THROW: an identical walk whose body FILTERS on the same table (copying the
-// recognised keys onward rather than rejecting the unrecognised ones) is a different operation with
+// The shape requires the throw: an identical walk whose body filters on the same table (copying the
+// recognised keys onward instead of rejecting the unrecognised ones) is a different operation with
 // no fail-open risk, and must not be dragged through a guard that only knows how to reject.
 // @guard-shape Object\.keys\(\w+(?:\.\w+)*\)\.forEach\(function \((\w+)\) \{\s*if \(![\w.]+\[\1\]\) (?:\{\s*)?throw
 function assertKnownKeys(obj, known, E, code, message) {

package/lib/guard-json.js

@@ -7,17 +7,17 @@
 // pki.acme resource objects, pki.webcrypto JWK unwrap).
 //
 // guard-json -- strict, bounded parse of an untrusted JSON document. JSON.parse
-// silently takes the LAST value of a DUPLICATE member, so a signed / wrapped
+// silently takes the last value of a duplicate member, so a signed or wrapped
 // object carrying two members of the same name resolves differently for a
-// verifier than for a consumer -- the JSON smuggling / parser-differential class
-// (CWE-20 / CWE-436). It also caps neither size nor nesting (CWE-770 / CWE-400),
-// and over a Buffer substitutes U+FFFD for invalid UTF-8 rather than failing.
+// verifier than for a consumer. That is the JSON smuggling / parser-differential
+// class (CWE-20 / CWE-436). It also caps neither size nor nesting (CWE-770 /
+// CWE-400), and over a Buffer substitutes U+FFFD for invalid UTF-8 instead of failing.
 //
 // This is a single hand-written recursive-descent reader that composes
-// guard.text.decode (the byte cap runs BEFORE the strict/fatal UTF-8 decode, so
+// guard.text.decode (the byte cap runs before the strict/fatal UTF-8 decode, so
 // an oversized document is rejected before it is materialized), then rejects a
-// duplicate member at EVERY nesting depth, caps nesting, assigns each member as
-// an OWN data property (a "__proto__" key becomes a normal member -- it cannot
+// duplicate member at every nesting depth, caps nesting, assigns each member as
+// an own data property (a "__proto__" key becomes a normal member: it cannot
 // mutate the prototype nor, being a non-own assignment for a primitive, silently
 // defeat the duplicate-member gate), and enforces the RFC 8259 number/string
 // grammar (no leading zero, a fraction/exponent needs a digit, no bare "-").
@@ -35,11 +35,11 @@ function _hexVal(c) {
 
 // parse(input, ErrorClass, spec) -> value. `input` is a Buffer or a string.
 // spec = { maxBytes, maxDepth, badJson, tooDeep, duplicateMember, tooLarge,
-//   badInput, label } -- the caller's caps + frozen domain/reason codes.
-// Both caps are REQUIRED authoring inputs: an omitted / NaN / fractional cap
+//   badInput, label }, the caller's caps and frozen domain/reason codes.
+// Both caps are required authoring inputs: an omitted, NaN or fractional cap
 // would silently disable the bound it configures (a depth-uncapped recursive
 // descent escapes as a raw stack-overflow RangeError), so they are validated
-// through the shared cap guards at entry -- maxDepth additionally against the
+// through the shared cap guards at entry, maxDepth additionally against the
 // stack-safe recursion ceiling, so no caller cap can exceed frame safety.
 // @enforced-by json-parse-not-via-guard
 function parse(input, ErrorClass, spec) {
@@ -49,7 +49,7 @@ function parse(input, ErrorClass, spec) {
   }
   var maxBytes = limits.cap(spec.maxBytes, "guard.json.parse spec.maxBytes", undefined);
   var maxDepth = limits.depthCap(spec.maxDepth, "guard.json.parse spec.maxDepth", undefined);
-  // Byte cap BEFORE the fatal UTF-8 decode (an oversized/ill-encoded document is
+  // Byte cap before the fatal UTF-8 decode (an oversized/ill-encoded document is
   // rejected before it is turned into a string).
   var str = text.decode(input, maxBytes, ErrorClass, {
     charset: "utf-8", fatal: true, tooLarge: spec.tooLarge, badDecode: spec.badJson, badInput: spec.badInput, label: spec.label,
@@ -126,7 +126,7 @@ function parse(input, ErrorClass, spec) {
         else if (e === "r") s += "\r";
         else if (e === "t") s += "\t";
         else if (e === "u") {
-          // Four hex digits, read as digits rather than matched as a pattern: the
+          // Four hex digits, read as digits instead of matched as a pattern: the
           // scanner is already walking this string one character at a time, and a
           // parser handed hostile input should not hand any of it to a second engine.
           var cp = 0;
@@ -144,10 +144,10 @@ function parse(input, ErrorClass, spec) {
       } else s += c;
     }
   }
-  // RFC 8259 sec. 6, enforced BY the walk rather than by re-matching the token
+  // RFC 8259 sec. 6, enforced by the walk itself and not by re-matching the token
   // afterwards. The scan already knows where each part starts and ends, so the
-  // grammar's three rules -- an integer part that is "0" or has no leading zero, a
-  // fraction with at least one digit, an exponent with at least one digit -- are
+  // grammar's three rules (an integer part that is "0" or has no leading zero, a
+  // fraction with at least one digit, an exponent with at least one digit) are
   // checked as it goes. Re-matching what the scanner just read meant maintaining
   // the same grammar twice, in two notations, and the pattern was the copy whose
   // cost on a rejecting token could not be bounded from outside.

package/lib/guard-limits.js

@@ -19,8 +19,8 @@
 // raw RangeError, not a typed verdict) once the cap is raised past the frame
 // limit; depthCap refuses a maxDepth above the stack-safe ceiling. A bad limit
 // is an authoring bug, so this tier throws a TypeError (not a PkiError). NIST
-// 800-53 SI-10 / SC-5 do not require these bounds (framework lag) -- the bound
-// at the parser is the actual control.
+// 800-53 SI-10 / SC-5 do not require these bounds (framework lag). The control
+// that actually holds is the bound at the parser.
 
 var constants = require("./constants");
 
@@ -31,7 +31,7 @@ var constants = require("./constants");
 // With no opts it is the config-time codec default: a bare TypeError with the
 // "decode:" prefix and a >= 0 floor (the asn1-der / cbor-det callers are
 // untouched). opts lets a caller in another currency reuse the same integer
-// floor with its OWN typed verdict and bounds -- so a fractional/negative/NaN
+// floor with its own typed verdict and bounds, so a fractional/negative/NaN
 // bound cannot be spelled a fifth way with a dropped Number.isInteger:
 //   E     - a (code, message) -> Error factory; when given, an out-of-range
 //           value throws E(code, ...) instead of the bare TypeError.
@@ -89,7 +89,7 @@ function depthCap(value, key, dflt) {
 //   dense TLV run rejects at the cap) driving the composing decoders are the guard.
 function counter(max, E, code, label) {
   // The ceiling is an authoring input: an undefined / NaN / fractional max
-  // builds a counter whose `n > max` NEVER fires -- a silently dead fanout
+  // builds a counter whose `n > max` never fires, leaving a silently dead fanout
   // defence. Reject at construction (config-time TypeError).
   if (!Number.isInteger(max) || max < 0) {
     throw new TypeError("guard.limits.counter: max must be a non-negative integer");
@@ -104,7 +104,7 @@ function counter(max, E, code, label) {
 }
 
 // byteCap(buf, max, E, code, label) -> the same buffer, once proven within `max`
-// bytes. Bounds a caller-supplied buffer BEFORE an expensive hash / verify / parse
+// bytes. Bounds a caller-supplied buffer before an expensive hash / verify / parse
 // materializes over it (CWE-400 uncontrolled resource consumption / CWE-770
 // allocation without limits -- the class guard.text.decode closes for a decoded
 // string and counter closes for element fanout, here for a raw byte input). Tier-2:
@@ -117,8 +117,8 @@ function counter(max, E, code, label) {
 //   over-size RED vectors driving the composing verifiers are the guard.
 function byteCap(buf, max, E, code, label) {
   // The ceiling is an authoring input: an undefined / NaN / fractional / negative
-  // max makes `length > max` never fire -- a silently dead size defence. Reject at
-  // config time (TypeError), regardless of the value currency E selects.
+  // max makes `length > max` never fire, and the size defence is then silently
+  // dead. Reject at config time (TypeError), regardless of the value currency E selects.
   if (!Number.isInteger(max) || max < 0) {
     throw new TypeError("guard.limits.byteCap: max must be a non-negative integer");
   }

package/lib/guard-name.js

@@ -8,7 +8,7 @@
 //
 // guard-name -- fail-closed name integrity: reject an embedded control byte in a
 // distinguished-name / SAN string, and compare two distinguished names by their
-// RFC 5280 sec. 7.1 canonical identity rather than their raw bytes.
+// RFC 5280 sec. 7.1 canonical identity, never their raw bytes.
 //
 // Defends the name-truncation / display-confusion class (CVE-2009-2408): a NUL
 // or control byte embedded in a decoded name lets an attacker make two different
@@ -19,8 +19,8 @@
 //
 // Defends the DN identity-vs-bytes class (CWE-706): a distinguished name has many
 // RFC 5280 sec. 7.1-equal DER encodings (case, whitespace, PrintableString vs
-// UTF8String). Binding identity to raw bytes -- a byte compare, or hashing
-// name.bytes as a lookup key -- silently treats two equal names as different, so
+// UTF8String). Binding identity to raw bytes (a byte compare, or hashing
+// name.bytes as a lookup key) silently treats two equal names as different, so
 // certificate chaining breaks, a revocation issuer / OCSP responder fails to
 // match, or (the mirror risk) a name constraint is escaped. Every DN identity
 // decision routes through the one canonical comparison here.
@@ -45,7 +45,7 @@ function assertNoControlBytes(str, E, code, label) {
 
 // assertPrintableIa5(buf, E, code, label) -> buf | throws E(code, ...)
 // IA5String policy (a dNSName / rfc822Name / URI GeneralName): every byte must be
-// printable 7-bit ASCII [0x20, 0x7e] -- an embedded NUL / control byte enables the
+// printable 7-bit ASCII [0x20, 0x7e], since an embedded NUL or control byte enables the
 // same name-truncation bypass downstream. `buf` is the raw GeneralName content.
 // @enforced-by behavioral -- the printable-IA5 byte-range reject has no rename-proof
 //   code shape distinct from the ASN.1 IA5 reader; the CVE-2009-2408 RED vectors
@@ -65,9 +65,9 @@ function assertPrintableIa5(buf, E, code, label) {
 // matches OpenSSL's X509_NAME_cmp, so a chain OpenSSL accepts is not rejected. This
 // canonicalization is the shape the guard-shape-reinlined detector keys on
 // (declared on dnEqual): a boundary hand-rolling it is re-implementing DN identity.
-// The collapse is a single walk rather than a pattern replace. This runs on every
-// attribute value of every name the toolkit compares -- a certificate an attacker
-// supplies included -- and one pass with a running "was the last character a space"
+// The collapse is a single walk, not a pattern replace. This runs on every
+// attribute value of every name the toolkit compares, a certificate an attacker
+// supplies included, and one pass with a running "was the last character a space"
 // flag costs exactly the length. It also spells out which characters count as
 // whitespace: RFC 5280 sec. 7.1 defers to X.520's caseIgnoreMatch, whose SPACE is
 // the ASCII space, and a pattern's \s silently also folds VT, FF, NBSP and every
@@ -95,9 +95,9 @@ function _canonAttrValue(v, E, code, label) {
 // not a style check: a parsed Name has no `length`, so `a.length !== b.length` compares undefined
 // with undefined, the loop over `i < undefined` never runs, and the comparison returns TRUE for two
 // unrelated names. An identity comparison that answers "equal" because it was handed the wrong
-// shape is the worst possible failure of this guard -- it is the one place a DN identity is
-// decided, and every caller reads a true from it as proof. So a comparison that CANNOT be
-// performed refuses, and the caller learns at the call site rather than trusting a fabricated
+// shape is the worst possible failure of this guard: it is the one place a DN identity is
+// decided, and every caller reads a true from it as proof. So a comparison that cannot be
+// performed refuses, and the caller learns at the call site instead of trusting a fabricated
 // match. (A caller holding a parsed Name passes its `.rdns`.)
 function _assertSequence(a, b, E, code, label, what) {
   if (!Array.isArray(a) || !Array.isArray(b)) {
@@ -122,10 +122,10 @@ function rdnEqual(a, b, E, code, label) {
   return true;
 }
 // dnEqual(rdnsA, rdnsB, E, code, label) -> boolean. RFC 5280 sec. 7.1 canonical
-// distinguished-name comparison over the RDN sequence -- the ONE place a DN identity
+// distinguished-name comparison over the RDN sequence, the single place a DN identity
 // is decided, so no caller binds identity to raw DER (a byte compare, or hashing
-// name.bytes, would treat two RFC 5280-equal names as different, breaking a chain /
-// a revocation match, or -- the mirror risk -- escaping a name constraint). The
+// name.bytes, would treat two RFC 5280-equal names as different, breaking a chain or
+// a revocation match, or, the mirror risk, escaping a name constraint). The
 // per-RDN canonicalization + control-byte reject is in rdnEqual / _canonAttrValue.
 // @enforced-by guard-shape-reinlined
 // @guard-shape replace\(/\\s\+/g,
@@ -140,7 +140,7 @@ function dnEqual(rdnsA, rdnsB, E, code, label) {
 
 // escapeControlBytes(str) -> str. The render-side sibling of assertNoControlBytes:
 // where a name string must still be DISPLAYED best-effort (a human-readable report,
-// a log line) rather than rejected, neutralize every C0 control byte and DEL by
+// a log line) instead of rejected, neutralize every C0 control byte and DEL by
 // rendering it as \xHH. A bare CR / LF / NUL in a decoded dNSName or DN value would
 // otherwise forge or overwrite report lines in a terminal or log (CWE-117 output-log
 // injection / CWE-116 improper output encoding). Non-control bytes pass through.
@@ -170,7 +170,7 @@ var DN_SPECIAL = { 0x2c: 1, 0x2b: 1, 0x22: 1, 0x5c: 1, 0x3c: 1, 0x3e: 1, 0x3b: 1
 // RFC 4514 sec. 2.4's special set is the TABLE above and the walk is a single pass.
 // The separator escape used to be a pattern replace feeding a second loop, which
 // meant two passes over an attacker-supplied value and a character class holding a
-// quote and a backslash inside a regex literal -- the form most easily misread by a
+// quote and a backslash inside a regex literal, the form most easily misread by a
 // human and, as it happened, by the codebase-patterns literal-stripper.
 //
 // @enforced-by behavioral -- the escaping has no rename-proof code shape distinct
@@ -191,8 +191,73 @@ function escapeDnValue(v) {
   return out;
 }
 
+// emailEqual(a, b) -> "match" | "no-match" | "not-comparable". The RFC 5280 sec. 7.5
+// sibling of dnEqual: two email addresses match iff their local-parts are an exact match
+// AND their host-parts match under a case-insensitive ASCII comparison. The local-part is
+// NEVER case-folded -- RFC 8398 sec. 5 states it "MUST NOT be transformed in any way, such
+// as by doing case folding or normalization of any kind", because Alice@ and alice@ are
+// permitted to be different mailboxes.
+//
+// The result is three-valued on purpose. An internationalized host-part (an `xn--` A-label
+// or any non-ASCII octet) needs an IDNA2008 A-label/U-label transform this toolkit does not
+// carry, so the rule cannot be applied. Returning "no-match" there would answer a question
+// that was never asked, and a caller acting on it would reject a legitimate sender; the
+// honest verdict is that the comparison was unavailable. A guard that cannot decide says so
+// instead of guessing (the value is fail-CLOSED at the call site: no caller may read
+// "not-comparable" as a pass).
+//
+// RFC 8398 sec. 5 also forbids wildcards outright -- "implementations MUST NOT interpret
+// any characters as wildcards" -- so no character here is ever special. A certificate
+// carrying `*@example.com` matches that literal string and nothing else. Name-CONSTRAINT
+// processing (RFC 5280 sec. 4.2.1.10 as extended by RFC 8398 sec. 6), where a bare domain
+// legitimately covers a whole subtree, is a different rule and stays in path-validate.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape lastIndexOf\("@"\)
+function emailEqual(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return "not-comparable";
+  // Split on the LAST "@": a quoted local-part may legally contain one, and taking the
+  // first would move part of the mailbox into the domain and compare the wrong halves.
+  var ai = a.lastIndexOf("@"), bi = b.lastIndexOf("@");
+  if (ai <= 0 || bi <= 0 || ai === a.length - 1 || bi === b.length - 1) return "not-comparable";
+  var aLocal = a.slice(0, ai), bLocal = b.slice(0, bi);
+  var aHost = a.slice(ai + 1), bHost = b.slice(bi + 1);
+  if (!_asciiHost(aHost) || !_asciiHost(bHost)) return "not-comparable";
+  if (aLocal !== bLocal) return "no-match";
+  return _lowerAscii(aHost) === _lowerAscii(bHost) ? "match" : "no-match";
+}
+
+// A host-part this comparison can decide: ASCII, and carrying no A-label. Anything else
+// needs the IDNA transform named above, so it is reported as undecidable rather than
+// compared as raw bytes -- `xn--e1afmkfd.example` and its Unicode form are one host, and
+// treating them as different would be a wrong answer rather than an absent one.
+function _asciiHost(h) {
+  if (h.length === 0) return false;
+  // ASCII is the whole test, and an A-label is ASCII. Two hosts already in A-label form
+  // need no transformation to be compared -- they are the same encoding -- so rejecting
+  // them for carrying `xn--` would make sender binding unusable for every certificate with
+  // an internationalized domain, including one whose address matches exactly. The case an
+  // IDNA transform WOULD be needed for is an A-label against a U-label, and the U-label
+  // side is non-ASCII, so it is refused here anyway.
+  for (var i = 0; i < h.length; i++) if (h.charCodeAt(i) > 0x7f) return false;
+  return true;
+}
+
+// ASCII-only lowercase. String.toLowerCase() is Unicode-aware and would fold characters
+// outside ASCII (the Kelvin sign lowercases to "k"), which is precisely the mapping the
+// host-part rule does not authorize; _asciiHost has already excluded those inputs, so this
+// stays a plain A-Z shift rather than inheriting a locale-sensitive transform.
+function _lowerAscii(s) {
+  var out = "";
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charCodeAt(i);
+    out += (c >= 0x41 && c <= 0x5a) ? String.fromCharCode(c + 32) : s.charAt(i);
+  }
+  return out;
+}
+
 module.exports = {
   assertNoControlBytes: assertNoControlBytes, assertPrintableIa5: assertPrintableIa5,
-  dnEqual: dnEqual, rdnEqual: rdnEqual,
+  dnEqual: dnEqual, rdnEqual: rdnEqual, emailEqual: emailEqual,
   escapeControlBytes: escapeControlBytes, escapeDnValue: escapeDnValue,
 };