@blamejs/pki 0.5.7 → 0.5.9

package/lib/guard-der.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the consumers
+// whose encoding integrity composes this guard (pki.schema.c509 reconstruct sites,
+// pki.x509.sign and its sibling builders on any subjectAltName otherName value).
+//
+// guard-der: the single choke point for "these raw bytes are exactly one strictly-valid
+// DER element", for every site that splices caller-supplied ANY bytes verbatim into
+// something it then signs or reconstructs.
+//
+// The bug class is framing mistaken for validation. asn1.decode checks TLV framing and
+// rejects trailing data, and stopping there feels sufficient. It is not: framing accepts
+// a BOOLEAN whose content octet is 0x01 where DER requires 0xFF, a NumericString holding
+// "@", and a SET whose members sit in no canonical order. None of those is DER. Spliced
+// into a certificate and signed, the issuer emits a structure that strict relying parties
+// reject, under a real signature, while the producing verb reported success (CWE-20).
+//
+// The rule is validate-or-refuse. A universal primitive runs through its strict content
+// reader, and a universal type with no reader here is REFUSED, so the table is exhaustive
+// by refusal and adding a type is a deliberate act. A non-universal element (a
+// legitimately context- or application-tagged ANY) passes on its framing because no
+// content rule is knowable for it, and its constructed children are still walked.
+//
+// Every entry point takes the CALLER's error factory and code, so a c509 splice reports in
+// the c509 domain and a certificate builder in the x509 domain.
+// asn1-der composes this guard family, so requiring the codec at module scope would read its
+// exports mid-initialisation and see an empty object. The require and the table it builds are
+// therefore both deferred to first use -- the documented circular-load exception to top-of-file
+// requires. Guards sit BELOW the codec in the dependency order; this is the one place that
+// order is inverted, and it is inverted lazily.
+var asn1 = null;
+function _asn1() { if (asn1 === null) asn1 = require("./asn1-der"); return asn1; }
+
+// The strict content reader per universal primitive tag. A tag absent from this table has no
+// validator here and is refused by `element` below -- that refusal is the point.
+var VALUE_READERS = null;
+function _readers() {
+  if (VALUE_READERS !== null) return VALUE_READERS;
+  var asn1 = _asn1();
+  var m = {}, R = asn1.read, T = asn1.TAGS;
+  // ENUMERATED shares INTEGER's content rules and is NOT constrained to non-negative
+  // values. X.680 (02/2021) sec. 20.2 requires each NamedNumber's SignedNumber to be
+  // distinct, and sec. 19 defines SignedNumber ::= number | "-" number; the non-negativity
+  // in sec. 20.3 governs only an EnumerationItem written as a bare identifier, which is
+  // auto-assigned. `ENUMERATED { lowPriority(-1), normal(0) }` is well-formed, so rejecting
+  // a negative here would refuse valid input. This guard validates the ENCODING; which
+  // values a particular ENUMERATED admits lives in a type definition an opaque ANY does
+  // not carry.
+  m[T.BOOLEAN] = R.boolean; m[T.INTEGER] = R.integer; m[T.ENUMERATED] = R.enumerated;
+  m[T.BIT_STRING] = R.bitString; m[T.OCTET_STRING] = R.octetString; m[T.NULL] = R.nullValue;
+  m[T.OBJECT_IDENTIFIER] = R.oid; m[T.UTC_TIME] = R.time; m[T.GENERALIZED_TIME] = R.time;
+  // NumericString reads through its own reader: it is not a DirectoryString type, and routing
+  // it through read.string would fold it into the RFC 5280 sec. 7.1 name-comparison identity
+  // class (see asn1-der.js).
+  m[T.NUMERIC_STRING] = R.numericString;
+  [T.UTF8_STRING, T.PRINTABLE_STRING, T.IA5_STRING, T.TELETEX_STRING, T.VISIBLE_STRING,
+    T.BMP_STRING, T.UNIVERSAL_STRING].forEach(function (t) { m[t] = R.string; });
+  VALUE_READERS = m;
+  return VALUE_READERS;
+}
+
+// A universal SET's required member order depends on a type the ANY does not carry: X.690
+// sec. 11.6 orders a SET OF by the members' full encodings, while a structured SET is ordered
+// by TAG (X.680 sec. 8.6), and the two differ whenever the constructed bit does (a SEQUENCE
+// member, tag 16, sorts before a PrintableString, tag 19, by tag but after it by octets). A
+// structured SET cannot repeat a tag, so a repeated tag proves SET OF and the octet rule binds;
+// with all-distinct tags either reading is possible, so accept a value that satisfies EITHER
+// (rejecting only what is non-canonical under both readings: sound in both directions, never a
+// guess).
+//
+// KNOWN LIMITATION, and the two consumers do not weigh it identically. The either-reading rule
+// admits a SET OF that is tag-ordered but not octet-ordered, which is not canonical DER. On a
+// RECONSTRUCT path the input already exists and the alternative would refuse a valid structured
+// SET, so accepting is the sound direction. On a SIGNING path the caller composes the bytes and
+// could be held to octet order, so the same permissiveness lets a signer emit a non-canonical
+// SET under a real signature. Tightening it for signers alone would mean a mode flag on a
+// security posture, which this family avoids, and tightening it for both would reject valid
+// structured SETs that c509 round-trips today. The rule is therefore unchanged and the cost is
+// written down rather than discovered later.
+var TAG_CLASS_RANK = { universal: 0, application: 1, context: 2, private: 3 };
+function setOrderOk(kids) {
+  var i, dup = false, seen = {};
+  for (i = 0; i < kids.length; i++) {
+    var key = kids[i].tagClass + ":" + kids[i].tagNumber;
+    if (seen[key]) { dup = true; break; }
+    seen[key] = true;
+  }
+  var octetAsc = true, tagAsc = true;
+  for (i = 1; i < kids.length; i++) {
+    if (Buffer.compare(kids[i - 1].bytes, kids[i].bytes) > 0) octetAsc = false;
+    // Tag order ranks by CLASS first (universal < application < context < private, X.680
+    // sec. 8.6), then by tag number. Compare the class's NUMBER: the names do not sort in
+    // class order.
+    var pc = TAG_CLASS_RANK[kids[i - 1].tagClass], cc = TAG_CLASS_RANK[kids[i].tagClass];
+    if (pc !== cc ? pc > cc : kids[i - 1].tagNumber > kids[i].tagNumber) tagAsc = false;
+  }
+  return dup ? octetAsc : (octetAsc || tagAsc);
+}
+
+// element(node, E, code, label). Strict-validate an already-decoded DER element at ANY depth.
+// Rejects the reserved EOC tag 0; runs a universal primitive through its strict content reader
+// (or refuses a type with none); recurses into a constructed element's children; holds a
+// universal SET to a canonical order. Only SEQUENCE and SET are accepted as universal
+// CONSTRUCTED types -- an EXTERNAL / EMBEDDED PDV / CHARACTER STRING has mandatory components
+// this gate cannot verify (the degenerate empty form is not a valid encoding of any of them),
+// so it is refused for the same reason an unvalidatable primitive is.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape _ANY_VALUE_READERS\[
+function element(node, E, code, label) {
+  if (node.tagClass === "universal" && node.tagNumber === 0) {
+    throw E(code, label + " must not use the reserved end-of-contents encoding (tag 0)");
+  }
+  var T = _asn1().TAGS;
+  if (node.constructed) {
+    if (node.tagClass === "universal" && node.tagNumber !== T.SEQUENCE && node.tagNumber !== T.SET) {
+      throw E(code, label + " of universal constructed type " + node.tagNumber + " has no strict DER structure validator here");
+    }
+    var kids = node.children;   // asn1.decode always sets a (possibly empty) children array
+    for (var i = 0; i < kids.length; i++) element(kids[i], E, code, label);
+    if (node.tagClass === "universal" && node.tagNumber === T.SET && !setOrderOk(kids)) {
+      throw E(code, label + " has a SET whose members are in no canonical DER order (X.690 sec. 11.6 / X.680 sec. 8.6)");
+    }
+    return;
+  }
+  if (node.tagClass === "universal") {
+    var reader = _readers()[node.tagNumber];
+    if (!reader) throw E(code, label + " of universal type " + node.tagNumber + " has no strict DER content validator here");
+    try { reader(node); }
+    catch (e) { throw E(code, label + " is not a valid DER element for its type", e); }
+  }
+}
+
+// tlv(content, E, code, label) -> content. Raw ANY bytes about to be spliced verbatim must be
+// exactly one non-empty, well-formed AND strictly-valid DER element: framing + no-trailing-data
+// via asn1.decode, then content / structure / SET order via `element`. Returns the bytes so a
+// call site can wrap a splice inline.
+//
+// @enforced-by guard-shape-reinlined
+// @guard-shape must be exactly one well-formed DER element
+function tlv(content, E, code, label) {
+  if (!content || content.length === 0) throw E(code, label + " must be a non-empty DER element");
+  var node;
+  try { node = _asn1().decode(content); }
+  catch (e) { throw E(code, label + " must be exactly one well-formed DER element (no trailing data)", e); }
+  element(node, E, code, label);
+  return content;
+}
+
+module.exports = { element: element, tlv: tlv };

package/lib/guard-encoding.js

@@ -10,28 +10,28 @@
 // guard-encoding -- strict decode of an untrusted base64 / base64url / hex text
 // to bytes. Node's Buffer.from(x, "base64"|"base64url"|"hex") is LENIENT: it
 // silently drops the first invalid character (and everything after a stray one),
-// accepts non-canonical trailing bits, and tolerates missing/extra padding, so
-// two distinct texts alias one byte string -- or a malformed text decodes to a
-// SHORTER, different value than intended. And it allocates the whole decode
-// before any size is checked. This is CWE-172 (encoding-transformation error) /
+// accepts non-canonical trailing bits, and tolerates missing/extra padding. Two
+// distinct texts can therefore alias one byte string, and a malformed text can
+// decode to a shorter, different value than intended. And it allocates the whole
+// decode before any size is checked. This is CWE-172 (encoding-transformation error) /
 // CWE-20 (canonicalization malleability) + CWE-770 (allocate-before-cap): RFC
 // 4648 sec. 3.5 / sec. 5 and RFC 8555 sec. 6.1 require the UNIQUE canonical
 // encoding. Each decoder here gates the alphabet, rejects an impossible length,
-// enforces the byte cap BEFORE the copy, decodes, and verifies canonicality by a
-// re-encode round-trip -- so a value that is not the one canonical encoding of
+// enforces the byte cap before the copy, decodes, and verifies canonicality by a
+// re-encode round-trip, so a value that is not the one canonical encoding of
 // its bytes fails closed with the caller's typed error.
 //
 // E is the caller's (code, message) typed-error factory; `code` the frozen
 // domain/reason; `label` the field phrase; `maxBytes` an optional decoded-size
 // cap (null/undefined = uncapped, for a PEM cert body already bounded upstream).
 
-// The alphabets are TABLES, walked one character at a time, rather than regular
-// expressions. A guard runs on the most hostile input the toolkit sees, and a
-// pattern engine's cost on a non-matching string is a property of the pattern
-// rather than of the length -- the one thing a bound cannot be placed on from the
-// outside. A table lookup is one array index per character and its cost is the
-// length, which the caller already caps. It is also the more honest statement of
-// the rule: the set of permitted characters IS the rule, written out.
+// The alphabets are tables, walked one character at a time. Regular expressions
+// would be the obvious alternative, but a guard runs on the most hostile input
+// the toolkit sees, and a pattern engine's cost on a non-matching string is
+// decided by the pattern, which is the one thing a bound cannot be placed on from
+// the outside. A table lookup is one array index per character, so its cost
+// follows the length, which the caller already caps. It is also the more honest
+// statement of the rule: the set of permitted characters is the rule, written out.
 function _alphabet(chars) {
   var t = new Uint8Array(128);
   for (var i = 0; i < chars.length; i++) t[chars.charCodeAt(i)] = 1;
@@ -43,8 +43,8 @@ var B64_ALPHABET = _alphabet(UPPER + LOWER + DIGITS + "+/");
 var HEX_ALPHABET = _alphabet(DIGITS + "abcdef" + "ABCDEF");
 
 // Every character of `text` is in `table`. A code point outside Latin-1's low half
-// (including every astral half) is outside all three alphabets, so the table bound
-// is the reject rather than an index that reads undefined.
+// (including every astral half) is outside all three alphabets, and the explicit
+// bound rejects it, so no lookup can read undefined off the end of the table.
 function _inAlphabet(text, table) {
   for (var i = 0; i < text.length; i++) {
     var c = text.charCodeAt(i);

package/lib/guard-header.js

@@ -20,9 +20,9 @@
 var C = require("./constants");
 
 // assertField(name, value, E, code) -> value | throws new E(code, ...)
-// name: RFC 5322 ftext -- printable ASCII [0x21, 0x7e] except ':' (0x3a), non-empty
+// name: RFC 5322 ftext, printable ASCII [0x21, 0x7e] except ':' (0x3a), non-empty
 //   (a space, control byte, or ':' in a field name breaks the "Name: value" grammar).
-// value: reject CR (0x0d) / LF (0x0a) / NUL (0x00) -- the injection bytes; TAB
+// value: reject CR (0x0d), LF (0x0a) and NUL (0x00), the injection bytes; TAB
 //   (0x09, folding whitespace) and printable non-ASCII (a UTF-8 header value, RFC
 //   6532) pass. E is the caller's typed-error CLASS, thrown `new E(code, message)`
 //   -- the same convention lib/mime.js (this guard's caller) and guard.bytes/text use.
@@ -42,7 +42,7 @@ function assertField(name, value, E, code) {
     if (vc === 0x00 || vc === 0x0d || vc === 0x0a) throw new E(code, "a header field value must not contain CR / LF / NUL (header injection) in " + JSON.stringify(name));
   }
   // RFC 5322 sec. 2.1.1: the serialized "Name: value" line (UTF-8 octets, excluding CRLF) must not exceed
-  // the line limit, or a relay may re-fold it -- silently changing the signed bytes of a protected header.
+  // the line limit, or a relay may re-fold it and silently change the signed bytes of a protected header.
   if (Buffer.byteLength(name, "utf8") + 2 + Buffer.byteLength(v, "utf8") > C.LIMITS.HEADER_LINE_MAX_OCTETS) {
     throw new E(code, "a header field line exceeds RFC 5322's " + C.LIMITS.HEADER_LINE_MAX_OCTETS + "-octet limit: " + JSON.stringify(name));
   }

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,
 };