@blamejs/pki 0.6.13 → 0.6.15

package/lib/guard-compress.js

@@ -1,97 +1,32 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// consumers whose decompression composes this guard (pki.cms.decompress,
-// pki.tls.decompressCertificate).
-//
-// guard-compress -- bounded, non-malleable decompression of an untrusted stream.
-// Node's zlib / brotli / zstd decompressors are by default both UNBOUNDED and
-// PERMISSIVE, and each is a distinct vulnerability class:
-//
-//   * Unbounded output (CWE-409, decompression bomb) -- a few hundred bytes
-//     expand to gigabytes. `maxOutputLength` refuses the moment the output WOULD
-//     exceed the bound; it does not allocate the whole output and then measure.
-//     So the cap has to be applied AT the call and can never be a check on the
-//     returned value.
-//   * Trailing input silently ignored (CWE-20, canonicalization malleability) --
-//     all three stop at the end of the first complete frame and discard whatever
-//     follows, so a caller may append arbitrary bytes, or a second entire frame,
-//     and still recover byte-identical output. One content would then have
-//     unboundedly many encodings, and a digest over the compressed object would
-//     stop identifying what it decompresses to.
-//
-// Both defenses are applied here, once, for every algorithm, so a new consumer
-// cannot pick up one and miss the other. Verified uniform across zlib, brotli
-// and zstd: each reports consumed input as `engine.bytesWritten` under
-// `info: true`, each raises ERR_BUFFER_TOO_LARGE on a cap breach, and each
-// accepts trailing bytes when left unchecked.
-//
-// E is the caller's (code, message, cause) typed-error factory, never an error
-// class. Passing a class here crashes on the error path ("class cannot be invoked
-// without new"), which converts a rejection into a fail-open. `codes` names the
-// two verdicts a caller distinguishes: `tooLarge` when the output would exceed
-// the cap, `failed` for every other fault. Every non-cap fault collapses to one
-// code deliberately -- a per-errno surface is attack telemetry.
+// @internal
 
 var zlib = require("zlib");
-// Taken at load. The capability probe below decides which algorithms are safe to expose, and the
-// bounded decompress measures its cap with these, so a replacement chooses both. See
-// guard-intrinsic for the whole captured set.
 var _intrinsic = require("./guard-intrinsic");
 var _bufferFrom = _intrinsic.bufferFrom;
 var _isBuffer = _intrinsic.isBuffer;
 var _isInteger = _intrinsic.isInteger;
 var _objectKeys = _intrinsic.keys;
 var _stringify = _intrinsic.stringify;
-// This probe decides which algorithms qualify as truncation-reporting, so both the round-trip
-// comparison and the frame-size floor below settle whether a compressor is trusted. Reading either
-// off a prototype lets a replacement qualify one that silently accepts a cut frame.
 var _compare = _intrinsic.compare;
 var _sizeOf = _intrinsic.sizeOf;
-// The cut that makes the truncated frame. A replacement returning the whole frame means the
-// decompressor is handed something intact, so an algorithm that ignores truncation qualifies on a
-// test that never truncated anything.
 var _subarray = _intrinsic.uncurry(Uint8Array.prototype.subarray);
 var _hasOwn = _intrinsic.hasOwn;
 
-// The decompressor per algorithm: a registry, so a new algorithm is a row rather
-// than a branch and an unrecognized name fails closed.
 var DECOMPRESS = {
-  zlib: zlib.inflateSync,               // RFC 1950
-  brotli: zlib.brotliDecompressSync,    // RFC 7932
-  zstd: zlib.zstdDecompressSync,        // RFC 8478
+  zlib: zlib.inflateSync,
+  brotli: zlib.brotliDecompressSync,
+  zstd: zlib.zstdDecompressSync,
 };
 
-// The compressors, used only by the truncation probe below. Producing a compressed stream is
-// not the guarded shape; decompressing an untrusted one is.
 var _PROBE_COMPRESS = {
   zlib: zlib.deflateSync,
   brotli: zlib.brotliCompressSync,
   zstd: zlib.zstdCompressSync,
 };
 
-// A decompressor must REPORT a frame it could not finish. Not all of them do: on some supported
-// runtimes the zstd binding returns a SHORT (often empty) result for a truncated frame instead
-// of faulting, and reports the entire input as consumed, so neither the returned bytes nor the
-// consumed-length check below can see that the frame was cut. That is a silent truncation: a peer
-// strips a frame's tail and the receiver processes a prefix as though it were the whole message.
-//
-// An algorithm whose runtime cannot report this cannot be decompressed safely here, so it is
-// dropped from the advertised set at load instead of accepted with a defect. Consumers build
-// their wire registries by intersecting with algorithms(), so a protocol simply does not offer
-// or accept it, and it returns on its own once the runtime reports truncation.
-// Nothing here is enabled by an exception alone: an algorithm qualifies only by positive proof
-// that a whole frame round-trips and that a cut frame is refused. Every other outcome (a
-// missing function, a compressor fault, a wrong round-trip, an unrelated error) leaves it out.
-//
-// Coverage residual: the early-return branches are reachable only on a runtime whose own
-// compression library is broken (a missing export, a compressor that throws on 46 ASCII bytes, a
-// round-trip that does not reproduce its input). The tables are captured at module load, so those
-// states cannot be induced from a test without replacing node:zlib beforehand, and forcing them
-// would assert nothing about the property this function exists to establish. They stay because
-// their absence is what would make a broken runtime silently qualify an algorithm.
 function _reportsTruncation(name) {
   var compress = _PROBE_COMPRESS[name];
   var decompress = DECOMPRESS[name];
@@ -100,53 +35,32 @@ function _reportsTruncation(name) {
   var frame, whole;
   try { frame = compress(sample); }
   catch (_e) { /* allow:swallow-unverified a compressor that cannot compress 46 ASCII bytes is a broken runtime; the algorithm simply does not qualify, which is the fail-closed direction */ return false; }
-  // A cut of 2 removes the frame's end marker; the sample is long enough that what remains is
-  // still a plausible frame head and not nothing at all.
   if (!_isBuffer(frame) || _sizeOf(frame) < 4) return false;
   try { whole = decompress(frame, { maxOutputLength: 4096 }); }
   catch (_e2) { /* allow:swallow-unverified a decompressor that rejects its own compressor's whole frame is a broken runtime; the algorithm does not qualify, again fail-closed */ return false; }
   if (!_isBuffer(whole) || _compare(whole, sample) !== 0) return false;
-  // The cut frame must be refused. A returned value of any length, including the empty buffer
-  // some bindings hand back, means a truncation would pass through unseen.
   var cutAccepted = false;
   try {
     decompress(_subarray(frame, 0, _sizeOf(frame) - 2), { maxOutputLength: 4096 });
     cutAccepted = true;
-  } catch (_e3) { /* refused, as a decompressor handed an unfinished frame must */ }
+  } catch (_e3) { }
   return !cutAccepted;
 }
 
 var SAFE = {};
 _intrinsic.forEach(_objectKeys(DECOMPRESS), function (n) { if (_reportsTruncation(n)) SAFE[n] = true; });
 
-// bounded(algorithm, stream, cap, E, codes, label) -> Buffer. Decompress `stream`
-// under `algorithm`, refusing any output that would exceed `cap` bytes and any
-// input carrying bytes past the end of the compressed frame.
-// The shape is the DECOMPRESSOR CALL ITSELF, not the presence of a cap: an
-// uncapped call is precisely the dangerous form, so keying on `maxOutputLength`
-// would fire on the safe re-inline and stay silent on the unsafe one. Every
-// decompression in lib/ therefore belongs to this module or routes through it.
 // @enforced-by guard-shape-reinlined
 // @guard-shape \bzlib\.(inflate|brotliDecompress|zstdDecompress)Sync\b
 // @guard-via \bguard\.compress\.bounded\s*\(
 function bounded(algorithm, stream, cap, E, codes, label) {
   var decompress = DECOMPRESS[algorithm];
-  // An unknown algorithm -- or one this runtime cannot decompress safely -- is an authoring
-  // fault, not untrusted input: a caller resolves a wire value to a name against algorithms()
-  // and rejects one it does not find, before reaching here. Arriving with a name outside that
-  // set means the consumer skipped the step, so it faults loudly and never silently.
   if (!_hasOwn(SAFE, algorithm) || !decompress) {
     throw new TypeError("guard.compress.bounded: unknown or unsafe algorithm " + _stringify(algorithm));
   }
-  // The byte-source normalization is guard.bytes.view's job and belongs at the
-  // consumer's boundary; reaching here with anything else means it was skipped.
   if (!_isBuffer(stream)) {
     throw new TypeError("guard.compress.bounded: stream must be a Buffer (route the input through guard.bytes.view first)");
   }
-  // The ceiling is an authoring input: an undefined / NaN / fractional / negative
-  // cap would silently disable the bomb defense. It must also be at least 1 --
-  // node rejects maxOutputLength 0 with a different fault than a cap breach, so a
-  // zero cap would surface as a malformed-stream verdict instead of a config error.
   if (!_isInteger(cap) || cap < 1) {
     throw new TypeError("guard.compress.bounded: cap must be a positive integer");
   }
@@ -160,9 +74,6 @@ function bounded(algorithm, stream, cap, E, codes, label) {
     }
     throw E(codes.failed, what + " could not be decompressed", e);
   }
-  // `bytesWritten` is the count of INPUT bytes the engine consumed. A frame that
-  // ends before the input does means the remainder was ignored, which is the
-  // malleability above, so the whole input must be exactly one frame.
   var consumed = res.engine.bytesWritten;
   var streamLen = _sizeOf(stream);
   if (consumed !== streamLen) {
@@ -172,15 +83,7 @@ function bounded(algorithm, stream, cap, E, codes, label) {
   return res.buffer;
 }
 
-// The algorithm names this guard can decompress safely on this runtime: the registry
-// minus any whose decompressor cannot report an unfinished frame. A consumer intersects
-// its protocol's algorithm registry with this, so it never advertises or accepts something
-// it could not refuse a truncation of.
 // @enforced-by behavioral -- a read-only list of the safe registry's keys has no
-// rename-proof code shape to re-inline; the guard's reject path is the contract,
-// and a consumer offering an algorithm this list omits fails closed at `bounded`.
 function algorithms() { return _objectKeys(SAFE); }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = _intrinsic.freeze({ bounded: bounded, algorithms: algorithms });

package/lib/guard-crypto.js

@@ -1,60 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// verify paths whose comparison composes this guard (pki.merkle,
-// pki.webcrypto.subtle.verify).
-//
-// guard-crypto -- fail-closed cryptographic-invariant guards. Enforced choke
-// point: a codebase-patterns detector requires every constant-time byte
-// comparison to route through here, so no verify path re-implements it with a
-// timing leak.
-//
-// Defends the timing side-channel class (CWE-208 observable timing discrepancy;
-// the Lucky13 / MAC-forgery family). A secret-dependent byte comparison with an
-// early exit (=== or a short-circuited &&) leaks the position of the first
-// differing byte, letting an attacker recover a MAC / tag / tree root
-// byte-by-byte. constantTimeEqual runs the whole comparison: a public length
-// gate (lengths are not secret; crypto.timingSafeEqual RangeErrors on unequal
-// lengths, so the gate must precede it) then a single timingSafeEqual over the
-// equal-length buffers -- both operands are always read, no data-dependent
-// branch. A length mismatch is an honest false, never a throw.
-//
-// Also defends the signature-malleability class (CWE-347 / CWE-20): a signature /
-// MAC / digest BIT STRING with a non-zero unused-bits count is not whole octets,
-// so trailing sub-octet bits let two encodings carry "one" signature. Every RFC
-// 9481/4211/6960/5280 signature output is a whole number of octets, so a value
-// with unusedBits !== 0 fails closed before its bytes reach a verifier.
+// @internal
 
 var nodeCrypto = require("node:crypto");
 var _freeze = require("./guard-intrinsic").freeze;
 
-// constantTimeEqual(a, b) -> boolean. Length-checked, then constant-time over
-// equal lengths. a and b are Buffers.
 // @enforced-by guard-shape-reinlined
 // @guard-shape \.timingSafeEqual\s*\(
 function constantTimeEqual(a, b) {
   return a.length === b.length && nodeCrypto.timingSafeEqual(a, b);
 }
 
-// isOctetAligned(bitString) -> boolean. True when a decoded BIT STRING (a
-// { bytes, unusedBits } node) is whole octets. For the never-throw verify paths
-// (a boolean/continue verdict) so a malleable signature is skipped, not honored.
 // @enforced-by behavioral -- shares the octet-alignment rule below; a bare
-//   .unusedBits check has legitimate non-signature siblings, so the RED vectors
-//   (a non-octet-aligned signature is skipped / rejected) are the guard.
 function isOctetAligned(bitString) {
   return !!bitString && bitString.unusedBits === 0;
 }
 
-// assertOctetAligned(bitString, E, code, label) -> bitString | throws E(code,...).
-// The throwing form for a parse boundary: a signature / MAC / digest BIT STRING
-// MUST be octet-aligned, else the malleable value is rejected fail-closed.
 // @enforced-by behavioral -- .unusedBits !== 0 is a per-field RFC rule, and the
-//   same token legitimately tests a DIFFERENT invariant (NamedBitList minimality,
-//   schema-engine assertMinimalNamedBits), so a blanket detector would false-fire;
-//   the RED vectors (a non-octet-aligned signature/digest rejects) are the guard.
 function assertOctetAligned(bitString, E, code, label) {
   if (!isOctetAligned(bitString)) {
     throw E(code, (label || "signature") + " BIT STRING must be octet-aligned (0 unused bits)");
@@ -62,6 +25,4 @@ function assertOctetAligned(bitString, E, code, label) {
   return bitString;
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = _freeze({ constantTimeEqual: constantTimeEqual, isOctetAligned: isOctetAligned, assertOctetAligned: assertOctetAligned });

package/lib/guard-der.js

@@ -1,73 +1,24 @@
 // 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-initialization 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.
-// The byte comparison SET-OF ordering is decided by, taken at load. A replacement chooses which
-// encodings this guard calls correctly ordered. See guard-intrinsic for the whole captured set.
+// @internal
 var _compare = require("./guard-intrinsic").compare;
 var _freeze = require("./guard-intrinsic").freeze;
 var _forEach = require("./guard-intrinsic").forEach;
-// The emptiness gate below decides whether bytes reach the decoder at all, and on a byte view
-// `length` is a replaceable accessor: one answering non-zero for an empty buffer sends nothing to
-// asn1.decode as though it were an element.
 var _sizeOf = require("./guard-intrinsic").sizeOf;
 var _create = require("./guard-intrinsic").create;
 
 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();
-  // Null-prototype: this table IS the allowlist of universal tags with a strict content reader, and
-  // a tag it does not carry is refused. Built on a `{}`, an inherited numeric property supplies a
-  // reader for a tag that was deliberately left out, and the refusal that is the point stops.
   var m = _create(null), 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;
   _forEach([T.UTF8_STRING, T.PRINTABLE_STRING, T.IA5_STRING, T.TELETEX_STRING, T.VISIBLE_STRING,
     T.BMP_STRING, T.UNIVERSAL_STRING], function (t) { m[t] = R.string; });
@@ -75,36 +26,12 @@ function _readers() {
   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.
-// Null-prototype: the rank decides canonical SET order, so an inherited property answering for an
-// unrecognized tag class would rank it rather than leave it unranked, and a SET in no canonical
-// order would compare as ordered.
 var TAG_CLASS_RANK = _create(null);
 TAG_CLASS_RANK.universal = 0;
 TAG_CLASS_RANK.application = 1;
 TAG_CLASS_RANK.context = 2;
 TAG_CLASS_RANK["private"] = 3;
 function setOrderOk(kids) {
-  // A null-prototype accumulator: on a `{}` a planted `Object.prototype["universal:16"]` answers
-  // this membership test for a tag the SET never carried, which reports a duplicate that is not
-  // there and selects the wrong canonical-order rule for the whole SET.
   var i, dup = false, seen = _create(null);
   for (i = 0; i < kids.length; i++) {
     var key = kids[i].tagClass + ":" + kids[i].tagNumber;
@@ -114,23 +41,12 @@ function setOrderOk(kids) {
   var octetAsc = true, tagAsc = true;
   for (i = 1; i < kids.length; i++) {
     if (_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) {
@@ -142,7 +58,7 @@ function element(node, E, code, label) {
     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
+    var kids = node.children;
     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)");
@@ -157,11 +73,6 @@ function element(node, E, code, label) {
   }
 }
 
-// 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) {
@@ -173,6 +84,4 @@ function tlv(content, E, code, label) {
   return content;
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = _freeze({ element: element, tlv: tlv });

package/lib/guard-encoding.js

@@ -1,49 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// consumers whose textual-encoding integrity composes this guard (pki.jose
-// base64url, pki.schema.* PEM bodies, pki.webcrypto JWK key material, pki.acme
-// / pki.est transfer encodings).
-//
-// 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. 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
-// 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).
+// @internal
 
-// 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) {
   // allow:guard-reads-runtime-live -- the three tables below are the only callers and they are
-  // built at module load, before any caller code has run. There is no live read to remove.
   var t = new Uint8Array(128);
   for (var i = 0; i < chars.length; i++) t[_charCodeAt(chars, i)] = 1;
   return t;
 }
-// Both halves of the round trip, taken at load, along with the string reads the alphabet checks
-// are built on. Canonicality here is decided by decoding the text and re-encoding the result, so
-// either half is enough to decide the answer: a `toString` returning the input makes every
-// non-canonical encoding canonical, and a `charCodeAt` deciding what is in the alphabet chooses
-// which characters are there to be judged.
 var _intrinsic = require("./guard-intrinsic");
 var _bufferFrom = _intrinsic.bufferFrom;
 var _toString = _intrinsic.uncurry(Buffer.prototype.toString);
@@ -58,9 +23,6 @@ var B64URL_ALPHABET = _alphabet(UPPER + LOWER + DIGITS + "-_");
 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, 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 = _charCodeAt(text, i);
@@ -69,13 +31,8 @@ function _inAlphabet(text, table) {
   return true;
 }
 
-// Reject before Buffer.from allocates: a base64 text of N chars decodes to at
-// most floor(N*3/4) bytes, a hex text to N/2.
 function _capBefore(nChars, perByteChars, maxBytes, E, code, label) {
-  if (maxBytes == null) return;   // documented uncapped mode (bounded upstream)
-  // The cap is an authoring input: a NaN / fractional / negative maxBytes makes
-  // the comparison below always false -- the cap silently disabled. Config-time
-  // TypeError instead (null/undefined stays the documented uncapped mode).
+  if (maxBytes == null) return;
   if (!_isInteger(maxBytes) || maxBytes < 0) {
     throw new TypeError("guard.encoding: maxBytes must be a non-negative integer or null");
   }
@@ -84,8 +41,6 @@ function _capBefore(nChars, perByteChars, maxBytes, E, code, label) {
   }
 }
 
-// base64url(text, maxBytes, E, code, label) -> Buffer. Unpadded base64url (RFC
-// 4648 sec. 5 / RFC 7515): no "=" padding, no "+"/"/", canonical final char.
 // @enforced-by base64-decode-not-via-guard
 function base64url(text, maxBytes, E, code, label) {
   if (typeof text !== "string") throw E(code, label + " must be a string");
@@ -97,14 +52,9 @@ function base64url(text, maxBytes, E, code, label) {
   return buf;
 }
 
-// base64(text, maxBytes, E, code, label) -> Buffer. Padded base64 (RFC 4648
-// sec. 4): whole 4-character groups, canonical padding + trailing bits.
 // @enforced-by base64-decode-not-via-guard
 function base64(text, maxBytes, E, code, label) {
   if (typeof text !== "string") throw E(code, label + " must be a string");
-  // Padding is positional, not alphabetic: at most two "=" and only at the end, so
-  // the body is measured first and the alphabet applies to what remains. An "="
-  // anywhere else leaves a non-alphabet character in the body and rejects there.
   var pad = 0;
   while (pad < 2 && text.length > pad && _charCodeAt(text, text.length - 1 - pad) === 0x3d) pad++;
   if (!_inAlphabet(_strSlice(text, 0, text.length - pad), B64_ALPHABET)) throw E(code, label + " is not base64 (a non-alphabet character)");
@@ -115,13 +65,7 @@ function base64(text, maxBytes, E, code, label) {
   return buf;
 }
 
-// hex(text, maxBytes, E, code, label) -> Buffer. Even-length hex; canonical via
-// a lower-case re-encode round-trip (RFC 4514 sec. 2.4 hex-string values).
 // @enforced-by behavioral -- the hex Buffer.from token has legitimate non-decode
-//   siblings in the tree (a hard-coded AES-KW IV constant, an internal
-//   parser-emitted canonical serial, an internal BigInt->hex), so a blanket
-//   Buffer.from(x,"hex") detector would false-fire; the RED conformance vectors
-//   (a non-canonical / odd-length / non-hex #hex attribute value rejects) guard it.
 function hex(text, maxBytes, E, code, label) {
   if (typeof text !== "string") throw E(code, label + " must be a string");
   if (!_inAlphabet(text, HEX_ALPHABET)) throw E(code, label + " is not hexadecimal");
@@ -132,6 +76,4 @@ function hex(text, maxBytes, E, code, label) {
   return buf;
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = _intrinsic.freeze({ base64url: base64url, base64: base64, hex: hex });

package/lib/guard-header.js

@@ -1,47 +1,16 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// consumer whose emitted-header integrity composes this guard (pki.smime header
-// protection, RFC 9788).
-//
-// guard-header -- fail-closed header-field integrity for a MIME / RFC 5322 header
-// a composer EMITS. Defends the HEADER INJECTION class (CWE-93): a caller-supplied
-// header field name or value carrying a CR (0x0d) / LF (0x0a) / NUL (0x00) could
-// inject an extra header (a Bcc, an HP-Outer record), split the message, or forge
-// a multipart boundary; a field name outside RFC 5322 ftext could break the
-// "Name: value" header grammar. It also caps the serialized line length (RFC 5322
-// sec. 2.1.1, 998 octets) so an over-long emitted field cannot be re-folded by a
-// relay into different signed bytes. Every field a composer inlines routes through
-// this one guard, so an emission site cannot re-inline a weaker check and
-// reintroduce the injection.
+// @internal
 
 var C = require("./constants");
-// Taken at load. `byteLength` is what the RFC 5322 line limit is measured with, so a replacement
-// decides whether an over-long header line is refused. See guard-intrinsic for the whole set.
 var _byteLength = require("./guard-intrinsic").byteLength;
 var _freeze = require("./guard-intrinsic").freeze;
-// The character-code read the RFC 5322 ftext and CR/LF/NUL checks are built on. One that never
-// reports a control byte is a header-injection defense that inspects nothing.
 var _charCodeAt = require("./guard-intrinsic").uncurry(String.prototype.charCodeAt);
 var _stringify = require("./guard-intrinsic").stringify;
-// The conversion that produces the text this guard then scans for CR and LF. A replacement returns
-// a clean string for a value carrying a line break, so the injection scan runs on text that is not
-// what gets emitted.
 var _String = require("./guard-intrinsic").String;
 
-// assertField(name, value, E, code) -> value | throws new E(code, ...)
-// 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) 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.
 // @enforced-by behavioral -- the CR/LF/NUL value reject + the ftext name check have
-//   no rename-proof code shape distinct from the guard-name control-byte loop / the
-//   ASN.1 charset readers; the header-injection RED vectors (a CR / LF / NUL value
-//   or a non-ftext field name rejects smime/bad-header) are the guard.
 function assertField(name, value, E, code) {
   if (typeof name !== "string" || name.length === 0) throw new E(code, "a header field name must be a non-empty string");
   for (var i = 0; i < name.length; i++) {
@@ -53,14 +22,10 @@ function assertField(name, value, E, code) {
     var vc = _charCodeAt(v, j);
     if (vc === 0x00 || vc === 0x0d || vc === 0x0a) throw new E(code, "a header field value must not contain CR / LF / NUL (header injection) in " + _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 and silently change the signed bytes of a protected header.
   if (_byteLength(name, "utf8") + 2 + _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: " + _stringify(name));
   }
   return v;
 }
 
-// Frozen for the reason the family header gives: a boundary reads its guard off this object at the
-// call, so a writable export would let a caller replace the check rather than pass it.
 module.exports = _freeze({ assertField: assertField });