@blamejs/pki 0.6.14 → 0.6.16

package/lib/guard-parsed.js

@@ -1,126 +1,32 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the verbs
-// whose "a DER Buffer, a PEM string, or a parsed X" argument composes this guard
-// (pki.path.validate / build, pki.crl.verify / isRevoked, pki.x509.sign,
-// pki.attrcert.sign, pki.ocsp.*, pki.cmp.session).
-//
-// guard-parsed -- fail-closed acceptance of a CLAIMED-parsed structure.
-//
-// Every verb that takes bytes also takes the parser's output, so a caller holding
-// a parsed certificate need not re-encode and re-parse it. The convenience carries
-// a trust boundary: the object arrives from the caller, not from the parser, and
-// the code downstream reads its fields as though the parser had produced them.
-//
-// Defends the type-confusion / unverified-provenance class (CWE-843, CWE-345).
-// Two distinct failures follow from accepting a claimed-parsed object on a partial
-// duck-type test, and the toolkit has had both:
-//
-//   - A missing field reads as an absent feature, never as a malformed input.
-//     `crlExtensions` omitted altogether made a scope-restricted CRL answer as an
-//     unrestricted one, because every scope guard reads the list as `(list || [])`.
-//     The guard cannot fire on a list that is not there.
-//   - A partial object reaches code that dereferences a field it lacks, and the
-//     verb throws a raw TypeError instead of its own typed error: a fault an
-//     operator cannot catch by code and a fuzz harness reports as a finding.
-//
-// The rule is completeness, checked at the door: an object claiming to be parser
-// output must carry every field the consuming code dereferences, each with the type
-// that code assumes. It is not a signature check and does not pretend to be. An
-// object can still describe a certificate that never existed, which is why the
-// fields a decision depends on are re-derived from `tbsBytes` where that matters.
-// What it buys is that "parsed" means one thing at every door, so a shape refused
-// by `pki.path.build` is not accepted by `pki.path.validate`.
-//
-// Each entry point keeps its own typed error: `E` is the caller's (code, message)
-// factory and `code` its own domain reason, so routing a door through this guard
-// changes what is checked, never what the operator reads.
+// @internal
 
 var bytes = require("./guard-bytes");
 var time = require("./guard-time");
-// The array test, taken at load. Every shape check below asks it whether a field IS a list, and
-// one answering `false` makes each of those checks reject a well-formed parsed structure -- the
-// fail-closed direction, and still a caller deciding what this guard recognizes.
 var _isArray = require("./guard-intrinsic").isArray;
 var _freezeExports = require("./guard-intrinsic").freeze;
-// The copy that becomes the recorded provenance bytes. A replacement returning a buffer over the
-// caller's own memory would let those bytes change after they were recorded, which is the one
-// thing provenance exists to prevent.
 var _bufferFrom = require("./guard-intrinsic").bufferFrom;
-// The sentinel the chain walk below stops at. Reached as a property of a replaceable global, a
-// replacement makes the walk run past the top and report inherited names as the value's own.
 var _ObjectProto = require("./guard-intrinsic").ObjectProto;
-// The rest of what this module reads from the runtime, taken at load. The shape checks below ask
-// these what a value IS and how it is put together, so a replacement decides what this guard
-// recognizes as parser output. See guard-intrinsic for the whole captured set.
 var _isBuffer = require("./guard-intrinsic").isBuffer;
 var _create = require("./guard-intrinsic").create;
 var _assign = require("./guard-intrinsic").assign;
 var _getPrototypeOf = require("./guard-intrinsic").getPrototypeOf;
 var _getOwnPropertyNames = require("./guard-intrinsic").getOwnPropertyNames;
-// The array operations, uncurried. Each shape check below asks `every` whether a list's members
-// are all well formed, so one replaced to return true makes every malformed list pass.
 var _every = require("./guard-intrinsic").every;
-// The provenance store's own operations. This WeakMap is what says a value came out of this
-// toolkit's parser, so a `get` that answers for a key never stored hands the door a forged
-// provenance record, and a `has` that answers true admits an object the parser never produced.
 var _weakGet = require("./guard-intrinsic").weakGet;
 var _weakSet = require("./guard-intrinsic").weakSet;
 var _weakHas = require("./guard-intrinsic").weakHas;
 var _WeakMap = require("./guard-intrinsic").WeakMap;
 var _defineProperty = require("./guard-intrinsic").defineProperty;
-// Appended by index rather than through `push`, so the growth reads no prototype method at all.
 function _append(arr, v) { _defineProperty(arr, arr.length, { value: v, writable: true, enumerable: true, configurable: true }); }
 
-// Every form the toolkit calls "bytes": a Buffer, any typed-array view, a DataView, or a bare
-// ArrayBuffer. Testing `_isBuffer(x) || x instanceof Uint8Array` is narrower than what the
-// verbs document, and the narrowness is invisible in the good case: an ArrayBuffer would fall
-// through to the object branch and be refused as a rebuilt structure, which reads to the caller as
-// "your certificate is malformed" when what happened is that their container was not recognized.
-// guard.bytes is what finally reads them, and it accepts all four, so the door has to as well.
-// Asked of guard.bytes rather than restated here, because a restatement is what drifts. An
-// `x instanceof ArrayBuffer` here turns away a real buffer built in another realm that guard.bytes
-// goes on to accept, so one container gets opposite answers from the two doors it passes through.
 function _isBytes(x) {
   return bytes.isByteSource(x);
 }
 
-// The shapes below assert the parser's complete output: every field
-// pki.schema.x509.parse and pki.schema.crl.parse assign, with the type each is
-// assigned, and not the subset some consumer happens to dereference today.
-//
-// The distinction is the whole point. A shape derived from one consumer's reads is
-// correct for that consumer and silently incomplete at every other door it gets
-// reused at, and the gap is invisible: the missing field is not named
-// anywhere, so nothing fails until a caller supplies an object without it. This
-// guard shipped derived from the path validator's reads, and three fields the other
-// doors depend on were absent: `serialNumber`, which pki.ocsp.buildRequest encodes
-// into the request; `issuer.bytes`, which the OCSP responder-identity comparison
-// reads; and an extension entry's `critical`, whose ABSENCE reads as non-critical to
-// `if (!ext.critical) continue`, so an unknown critical extension passes unhandled.
-//
-// Anchoring on the parser removes the enumeration step that produced those gaps: the
-// only sanctioned way to obtain one of these objects is to run the parser, the parser
-// assigns every field unconditionally, and so "complete" needs no consumer census and
-// does not drift when a new consumer reads a new field. Adding a field to a parser's
-// output belongs here in the same change; the api-snapshot pins that surface, so
-// the two move together.
 
-// A directory name. `dn` is the RFC 4514 string, `bytes` the raw encoded Name that a
-// byte-level issuer/subject comparison hashes, and `rdns` the structure the RFC 5280
-// sec. 7.1 comparison walks.
-//
-// The walk goes all the way to the attributes. `rdns` being an array is not the
-// property anything downstream depends on: guard-name's dnEqual compares each
-// attribute's `type` and canonicalizes its `value`, and the WebAuthn subject-CN
-// lookup reads `name` and `value`, so an array of anything would pass a
-// shallow test and reach code that dereferences three fields it does not have.
-// Name ::= RDNSequence ::= SEQUENCE OF RelativeDistinguishedName, and an RDN is a
-// SET SIZE (1..MAX), so the parser produces an array of non-empty arrays; the
-// attribute value is always a string, either the decoded directory string or the
-// RFC 4514 "#hex" form the parser falls back to for a type it does not decode.
 function _isAttributeTypeAndValue(a) {
   return !!a && typeof a.type === "string" && _isOptName(a.name) && typeof a.value === "string";
 }
@@ -136,8 +42,6 @@ function _isName(n) {
   return !!n && _isRdnSequence(n.rdns) && _isBuffer(n.bytes) && typeof n.dn === "string";
 }
 
-// `name` is the registry lookup of the OID and is null for an OID the registry does
-// not carry, so the assertion is on the KEY's presence with the parser's own type.
 function _isOptName(v) { return typeof v === "string" || v === null; }
 
 function _isAlgorithmIdentifier(a) {
@@ -149,35 +53,17 @@ function _isBitString(b) {
   return !!b && _isBuffer(b.bytes) && typeof b.unusedBits === "number";
 }
 
-// A parsed certificate extension entry: dispatched on `.oid`, gated on `.critical`,
-// and its `.value` the raw extension bytes, which the certificate parser leaves
-// undecoded. An entry carrying a `.name` but no `.oid` is the shape that slips past
-// an OID-keyed lookup while reading as present to a human; one carrying no
-// `.critical` is the shape that turns a fail-closed unknown-critical check into a
-// skipped iteration.
 function _isExtensionEntry(e) {
   return !!e && typeof e.oid === "string" && _isOptName(e.name) &&
     typeof e.critical === "boolean" && _isBuffer(e.value);
 }
 
-// A parsed CRL extension entry. The CRL parser decodes the values it knows (a
-// cRLNumber surfaces as a BigInt, a reasonCode as a Number), so the value type
-// varies by extension and only its presence can be asserted here. The dispatch key
-// and the criticality flag are the same as a certificate's, and both decide.
 function _isCrlExtensionEntry(e) {
   return !!e && typeof e.oid === "string" && _isOptName(e.name) &&
     typeof e.critical === "boolean" && e.value !== undefined;
 }
 
-// isCert(o) -- the complete parsed-certificate shape.
-//
-// Exported as a predicate beside the throwing door because a caller deriving a
-// dedupe key (cmp's extraCerts pool) must answer "not usable" and never throw:
-// a non-deduped entry is a redundant slot, while a key derived from a partial object
-// could collapse two different certificates onto one.
-//
 // @enforced-by guard-shape-reinlined -- shares the `accept` shape below: any door
-//   testing tbsBytes and returning the object is the re-inline this replaces.
 function isCert(o) {
   return !!o && typeof o === "object" &&
     _isBuffer(o.tbsBytes) &&
@@ -196,13 +82,6 @@ function isCert(o) {
     _isArray(o.extensions) && _every(o.extensions, _isExtensionEntry);
 }
 
-// isCrl(o) -- the complete parsed-CertificateList shape. `crlExtensions` and each
-// entry's `crlEntryExtensions` are required arrays, never optional ones: the
-// scope guards read them as `(list || [])`, so an omitted list is indistinguishable
-// from an empty one and the difference decides whether a serial may be answered.
-// `nextUpdate` is the one genuinely optional field; the parser assigns null when
-// the CRL omits it, and a validator distinguishes the two.
-//
 // @enforced-by guard-shape-reinlined -- shares the `accept` shape below.
 function isCrl(o) {
   return !!o && typeof o === "object" &&
@@ -222,51 +101,20 @@ function isCrl(o) {
     });
 }
 
-// Neither predicate may throw. A caller-supplied object can define an accessor that
-// throws on read, and a raw fault escaping a completeness check defeats the point of
-// checking: the composing verb's contract is that every failure is its own typed
-// error, and a dedupe caller using the predicate directly would get a raw fault where
-// it expects a boolean. A property that cannot be read is not one the parser produced,
-// so a throw is simply "not the shape". Wrapped here, and not at the door, because
-// both are exported and the rule has to hold for both.
 function _safe(shape) {
   return function (o) {
     try { return shape(o) === true; }
     catch (_e) {
-      return false;   // a field that cannot be read is not a field the parser produced
+      return false;
     }
   };
 }
 var certShape = _safe(isCert);
 var crlShape = _safe(isCrl);
 
-// Null-prototype: this table decides which kinds are recognized, and the lookup below is what the
-// unknown-kind refusal rests on. Built on a `{}`, a planted `Object.prototype[kind]` supplies a
-// predicate for a kind the table never carried, and an unrecognized structure is then authorized.
 var _SHAPES = _assign(_create(null), { certificate: certShape, crl: crlShape });
 
-// accept(input, kind, parse, E, code, label) -> the parsed structure | throws
-//
-// The door every "bytes or a parsed X" argument goes through. Bytes and PEM are
-// handed to `parse`; an object claiming to be parser output (it carries the
-// `tbsBytes` the parser always produces) must satisfy the complete shape for
-// `kind`; anything else is a typed input fault naming what the argument accepts.
-//
-// The claim test is `tbsBytes !== undefined`, not a truthiness test: an object
-// carrying `tbsBytes: null` is claiming to be parsed and failing, and must be told
-// so, never sent to a byte parser that reports something unrelated.
-//
-// Reading the claim is itself a read of a caller-supplied object, so it goes through
-// the same try/catch the shape walk does. A getter or Proxy trap that throws would
-// otherwise escape from outside the guarded walk and reach the operator as a raw
-// fault at every door composing this: the failure the walk is wrapped to prevent,
-// one property earlier. An unreadable claim is treated as a claim made and failed,
-// matching fromTrustedSource below: an object that cannot answer what it is has not
-// come from the parser, and saying so is more useful than reporting its type.
-//
 // @enforced-by guard-shape-reinlined
-// The shape is the partial duck-type acceptance this guard replaces: testing
-// tbsBytes (with or without one companion field) and returning the object.
 // @guard-shape (?:if\s*\(|return\s*\(?)[^;\n]*\.tbsBytes[^;\n]*\)\s*(?:\{\s*)?return\s+\w+\s*;
 // @guard-via guard\.parsed\.(?:accept|isCert|isCrl)\(
 function accept(input, kind, parse, E, code, label) {
@@ -278,7 +126,7 @@ function accept(input, kind, parse, E, code, label) {
   if (input && typeof input === "object") {
     try { claimsParsed = input.tbsBytes !== undefined; }
     catch (_e) {
-      claimsParsed = true;   // an object that cannot answer what it is did not come from the parser
+      claimsParsed = true;
     }
   }
   if (claimsParsed) {
@@ -290,91 +138,14 @@ function accept(input, kind, parse, E, code, label) {
   throw E(code, who + " must be a " + kind + " DER Buffer, a PEM string, or a parsed " + kind);
 }
 
-// ---- provenance: the parser's own mark -------------------------------------
-//
-// Some verbs cannot be satisfied by completeness alone. A signature check has three
-// parts -- the signature, the algorithm that verifies it, and the byte range it
-// covers -- and on a parsed object all three are separate properties, each of them
-// individually well-formed. Pair a real CA's signature over a certificate it issued
-// with that certificate's own signed bytes and algorithm, relabel the three, and
-// every part of the check passes for a structure that never existed. A MAC check has
-// the same shape: the range MACed and the content returned as verified are two
-// properties, so one object can say "verify this" and "return that".
-//
-// What those verbs need is not a shape but a PROVENANCE: these fields were derived
-// together, from one byte string, by the parser. So the parser records the bytes it
-// derived the object from, and the door derives the structure it verifies from those
-// bytes again.
-//
-// Recording the bytes, and not a boolean, is what makes this hold. A flag saying
-// "this came from the parser" is defeated by keeping a legitimately parsed object and
-// then assigning over its fields: the flag is still there and now describes
-// something else. Re-deriving from the recorded bytes discards every later edit,
-// because the verdict is computed from the byte string and not from the object the
-// caller is holding. The object a caller passes is therefore a way of naming bytes,
-// which is all it was ever safe for it to be.
-//
-// The record is kept off the object, in a WeakMap the parser owns, keyed by the
-// returned object itself. Nothing about the record is reachable through the object,
-// which is what makes it unforgeable:
-//
-//   - A property, however hidden, is read through the object, and every read of an
-//     object is interceptable. A Proxy's getOwnPropertyDescriptor and get traps are
-//     handed whatever key they are asked about (the symbol need not be known to be
-//     answered for), so a Proxy could claim any mark and name any bytes. A WeakMap
-//     lookup is on identity: a Proxy is a different object from the parser's result
-//     and simply is not a key.
-//   - `_create(parsed)` is likewise a different object, so it inherits no
-//     record, while `_assign({}, parsed)` and `{...parsed}` are different
-//     objects too. All three, the ways a mixed structure is actually assembled,
-//     fall out of the same rule, with no need for three checks.
-//
-// The recorded bytes are copied. Recording the caller's Buffer by reference would let
-// it be overwritten between the parse and the verify, which is the same defeat by
-// another route: the door would faithfully re-derive from bytes that had changed
-// underneath it. A PEM string needs no copy, strings being immutable.
-//
-// This is not a signature check and does not pretend to be. It says only "verify the
-// bytes this object was parsed from", which is precisely the claim the three-part
-// check was resting on without ever asking for it.
 var PROVENANCE = new _WeakMap();
 
-// recordingParser(kind, parse) -> a parser that records what it parsed.
-//
-// Recording is not a separate step a caller could perform, and the record is not a
-// value a caller can read back. Both follow from the same requirement: the record has
-// to mean "the parser derived this object from these exact bytes", and every way of
-// exposing it weakens that to something else.
-//
-//   - An exported `mark(obj, kind, bytes)` would let any code assert provenance for an
-//     object it did not parse, or overwrite the provenance of one it did not produce.
-//     The only way to obtain a record is therefore to actually run the parse.
-//   - An exported `sourceOf(obj)` would hand back the recorded Buffer, which the caller
-//     could then overwrite, defeating the copy by writing through the value the copy
-//     was made to protect.
-//
-// The snapshot is taken before the parse and the parser is given the snapshot, so the
-// bytes the parser reads and the bytes the record names are the same object by
-// construction. Taking it afterwards from the caller's argument would leave a window:
-// a typed-array subclass with stateful `byteOffset` / `byteLength` getters, or any
-// SharedArrayBuffer, can present one set of bytes to the parser and another to a later
-// copy. guard.bytes.snapshot reads through the BufferSource contract and copies.
-//
 // @enforced-by guard-shape-reinlined -- shares the fromTrustedSource shape below; a
-//   door re-testing the claim fields itself is the re-inline both replace.
 function recordingParser(kind, parse, ErrorClass, code, label) {
   return function (input) {
-    var isText = typeof input === "string";   // strings are immutable; nothing to snapshot
+    var isText = typeof input === "string";
     var snap = isText ? input : bytes.snapshotSource(input, ErrorClass, code, label);
     var out = parse(snap);
-    // The record gets its own copy, not the buffer the parser just read.
-    //
-    // A parser surfaces raw byte ranges (tbsBytes, a Name's encoded form, an extension's value)
-    // as views onto the buffer it parsed, which is what makes them exact and cheap. So the object
-    // handed back reaches into that buffer, and a caller holding it can write through those views:
-    // `parsed.tbsBytes.fill(0)` would then overwrite the very bytes the record names, and the
-    // re-derivation would faithfully reproduce whatever was written. A record the object can reach
-    // is not a record of anything. This copy is never handed out and nothing aliases it.
     if (out && typeof out === "object") {
       _weakSet(PROVENANCE, out, { kind: kind, source: isText ? snap : _bufferFrom(snap),
         shape: _shapeOf(out) });
@@ -383,25 +154,7 @@ function recordingParser(kind, parse, ErrorClass, code, label) {
   };
 }
 
-// recordingWalker(kind, walkNode, decodeBytes) -> function (node) -> the walked structure.
-//
-// The recordingParser sibling for a producer handed an already-decoded node, not bytes.
-// One structure needs it: the RFC 7292 authSafe's SignedData. A PFX is decoded BER-tolerantly
-// because real stores carry the indefinite-length encoding, so its inner SignedData cannot be
-// re-derived by the strict `parse` entry the byte doors use; that entry would refuse a store
-// this toolkit accepts today. The record therefore names the bytes and how to walk them again.
-//
-// The same three properties hold as for recordingParser, and for the same reasons. The record can
-// only be obtained by actually running the walk, so no code can assert provenance for a structure
-// it did not produce. The recorded bytes are a private copy of the node's, because the walked
-// result surfaces views onto the buffer the PFX was decoded from and a caller holding one could
-// otherwise write through it into the very bytes the record names. And `derive` re-runs this same
-// walker over that copy, so a re-derivation reproduces the structure exactly: the decode is the
-// producer's own, never a stricter one substituted at the door.
-//
 // @enforced-by guard-shape-reinlined -- shares recordingParser's shape below: the PROVENANCE.set
-//   that binds a structure to the bytes it was derived from appears only in this module, so no
-//   producer elsewhere can mint a record for a structure it did not itself walk.
 function recordingWalker(kind, walkNode, decodeBytes) {
   return function (node) {
     var out = walkNode(node);
@@ -417,46 +170,19 @@ function recordingWalker(kind, walkNode, decodeBytes) {
   };
 }
 
-// The provenance record for `obj`, or undefined. @internal to this module: touches no
-// property of `obj` at all -- the lookup is on the object's identity.
+// @internal
 function _recordOf(obj, kind) {
   if (!obj || typeof obj !== "object") return undefined;
   var rec = _weakGet(PROVENANCE, obj);
   return (rec && rec.kind === kind) ? rec : undefined;
 }
 
-// isRecorded(obj) -> whether this exact object carries a provenance record, of any kind.
-//
-// The record is keyed on identity, so a copy of a parsed structure, however faithful, is
-// not the parsed structure: it carries no record and every door that decides integrity refuses
-// it. That makes a recorded object a handle, not data, and anything that walks a caller's
-// spec taking copies has to leave it alone. guard-bytes.snapshotDeep asks this before descending.
 // @enforced-by behavioral -- a predicate has no rename-proof shape to detect, and re-inlining it is
-//   not possible outside this module: the registry it reads is a module-private WeakMap. The guard
-//   is the RED vector that passes a parsed certificate through a producing verb's spec and asserts
-//   the integrity door still accepts it, which fails the moment a copy is taken instead.
 function isRecorded(obj) {
   return !!obj && typeof obj === "object" && _weakHas(PROVENANCE, obj);
 }
 
-// isRecordedAsProduced(obj) -> whether this is a recorded structure that still has the field set
-// the parser gave it.
-//
-// A recorded structure is safe to hand on by identity, because the doors that decide integrity
-// re-derive it from the bytes the record names and ignore whatever the object says. That reasoning
-// covers it as a parsed value. It does not cover a caller who takes a parse result, adds an option
-// to it, and passes it where a verb reads options by name: those fields no door re-derives, so
-// they stay the caller's to change. The record therefore also names the shape the parser produced,
-// and a structure that has grown fields since is no longer only a parse result.
-// Only an added field matters. Deleting one changes nothing (the door re-derives the structure
-// from the bytes the record names, so a missing property is not a missing value), and a caller
-// pruning a parse result is a case the shipped vectors cover deliberately. What re-derivation does
-// not reach is a name the parser never produced, which is exactly what an option added to a parse
-// result is.
 // @enforced-by behavioral -- a predicate has no rename-proof shape to detect, and the registry it
-//   reads is a module-private WeakMap so nothing outside can re-inline it. The guard is the RED
-//   vector that adds an option to a parse result, passes it where options are read by name, and
-//   asserts the value the verb used is the one that was there at entry.
 function isRecordedAsProduced(obj) {
   if (!isRecorded(obj)) return false;
   var shape = _weakGet(PROVENANCE, obj).shape;
@@ -474,9 +200,6 @@ function _shapeOf(obj) {
   return shape;
 }
 
-// Every name a `obj.field` lookup could resolve: own and inherited, enumerable or not. A verb
-// reads an option by name and does not care how it was defined, so a comparison that only saw
-// `Object.keys` would miss a field added with defineProperty and call the object unchanged.
 function _allNames(obj) {
   var names = [];
   var seen = _create(null);
@@ -491,34 +214,18 @@ function _allNames(obj) {
   return names;
 }
 
-// fromTrustedSource(input, kind, claimFields, parse, E, code, why) -> the parsed
-// structure | throws.
-//
-// The door for a verb that decides integrity. Bytes are parsed. An object carrying
-// the parser's record is re-parsed from the bytes that record names, so a caller
-// may keep passing the parsed form, and anything done to that object since it was
-// parsed is discarded, never trusted. An object that claims to be parser output
-// (it carries a field only a parsed structure of this kind has) but carries no
-// record was not produced by the parser, and is refused with the caller's own reason.
-//
-// `claimFields` exist so that refusal names what happened, instead of handing the
-// object to a byte parser that would report something about its type.
-//
 // @enforced-by guard-shape-reinlined
 // @guard-shape (?:responseStatus|integrityMode|macedBytes|tbsResponseDataBytes)\s*!==\s*undefined
 // @guard-via guard\.parsed\.(?:fromTrustedSource|recordingParser)\(
 function fromTrustedSource(input, kind, claimFields, parse, E, code, why) {
   if (input && typeof input === "object" && !_isBytes(input)) {
-    // A structure the walker recorded carries its own way back; the byte doors re-derive with the
-    // parser they were given.
     var rec = _recordOf(input, kind);
     if (rec !== undefined) return (rec.derive || parse)(rec.source);
     for (var i = 0; i < claimFields.length; i++) {
-      // A claim field can be an accessor that throws; a guard answers, it does not relay.
       var claims;
       try { claims = input[claimFields[i]] !== undefined; }
       catch (_e) {
-        claims = true;   // a claim that cannot be read is certainly not the parser's own result
+        claims = true;
       }
       if (claims) throw E(code, why);
     }
@@ -526,34 +233,6 @@ function fromTrustedSource(input, kind, claimFields, parse, E, code, why) {
   return parse(input);
 }
 
-// ---- the certificate / CRL door --------------------------------------------
-//
-// acceptDerived(input, kind, parse, E, code, label) -> the parsed structure | throws.
-//
-// The single door for a certificate or a CRL, at every boundary that takes one. Bytes and PEM are
-// parsed; the parser's own result is re-derived from the bytes it recorded; an object that claims to
-// be one without that record is refused.
-//
-// It is one rule for every door, and never a rule for the doors that "reach a verdict", because
-// that judgment is the thing that keeps being got wrong. A certificate is a trust decision wherever
-// it appears: an issuer certificate handed to a signer names who the new certificate says issued it;
-// a root handed to an attestation check is the anchor; a certificate handed to a request builder
-// names what the request asks about. Sorting them into verdict and non-verdict doors invites exactly
-// the substitution this prevents at whichever door was sorted wrong, so no door is sorted at all.
-//
-// The claim fields are the ones a parsed structure has and a byte input does not, so an object that
-// was rebuilt is told what happened, never handed to a byte parser that would report something
-// about its type.
-//
-// This list is a TYPE DETECTOR, not the integrity boundary, and reads as the latter if skimmed.
-// Nothing is trusted because it appears here, and no field is unprotected because it does not:
-// fromTrustedSource re-derives the WHOLE structure from the bytes the provenance record names, so a
-// field edited on a parse result is discarded whether or not it is listed. Adding every
-// security-relevant field would therefore change no verdict. What the list decides is narrower: it
-// separates "an object claiming to be a parse result" from "bytes", so the first gets this domain's
-// typed refusal instead of being handed to a byte parser.
-// Null-prototype, for the same reason as _SHAPES: an inherited entry standing in for an absent one
-// makes an unrecognized kind look recognized, and the refusal keyed on its absence never fires.
 var _CLAIMS = _assign(_create(null), {
   certificate: ["tbsBytes", "subjectPublicKeyInfo", "serialNumberHex"],
   crl: ["tbsBytes", "revokedCertificates", "crlExtensions"],
@@ -571,21 +250,16 @@ var _WHY = _assign(_create(null), {
   attributeCertificate: "the signed byte range, the holder the privileges attach to and the attributes granting them are separate properties of a parsed object, so a rebuilt attribute certificate could have them describe different grants: keep a genuine issuer's signed bytes and signature, replace only the holder or an attribute, and the signature still verifies while the privileges are read for someone the issuer never granted them to",
 });
 // @enforced-by guard-shape-reinlined -- shares the fromTrustedSource shape it composes: a door that
-//   tests the claim fields itself, instead of routing here, is the re-inline both replace.
 function acceptDerived(input, kind, parse, E, code, label) {
   var claims = _CLAIMS[kind];
   if (!claims) throw new TypeError("guard.parsed.acceptDerived: unknown kind " + kind);
   var who = label || "the argument";
-  // An object that is neither bytes nor a claim is named as the wrong type here, never handed
-  // to the byte parser. The parser would refuse it too, but with its own domain's code: a caller
-  // who passed the wrong thing to pki.path.validate should read a path/* fault, not an x509/* one
-  // from a layer they did not call.
   if (input !== null && input !== undefined && typeof input === "object" && !_isBytes(input)) {
     var claimsSomething = false;
     for (var i = 0; i < claims.length && !claimsSomething; i++) {
       try { claimsSomething = input[claims[i]] !== undefined; }
       catch (_e) {
-        claimsSomething = true;   // a claim that cannot be read is certainly not the parser's result
+        claimsSomething = true;
       }
     }
     if (!claimsSomething) {
@@ -599,8 +273,6 @@ function acceptDerived(input, kind, parse, E, code, label) {
     ".parse result: " + _WHY[kind]);
 }
 
-// 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 = _freezeExports({
   accept: accept, acceptDerived: acceptDerived,
   fromTrustedSource: fromTrustedSource, recordingParser: recordingParser,

package/lib/guard-range.js

@@ -1,67 +1,22 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The documented surface is the
-// parsers whose decoded-integer bounds compose this guard (pki.schema.x509 /
-// crl / pkcs12 / cmp, pki.path.validate).
-//
-// guard-range -- fail-closed bound of an untrusted decoded integer before it is
-// narrowed to a JS Number. Parse-time (Tier-2): the value is malformed content,
-// so it throws the caller's typed PkiError, distinct from guard-limits, which
-// validates an operator-supplied option at config time (Tier-1, TypeError).
-//
-// Defends the silent-narrowing class (a decoded ASN.1 INTEGER past 2^53 rounds
-// when coerced to a Number, so a caller acting on the result, a pathLen,
-// skipCerts, saltLength or iteration counter, acts on the wrong number;
-// CWE-190 integer overflow / CWE-681 incorrect conversion). The bound and the
-// narrow are atomic here: a caller cannot obtain the Number without the range
-// having been enforced, so the value can never round silently and be acted on.
+// @internal
 
-// 2^31 - 1, the shared skip-cert / path-length / salt / iteration ceiling.
-// This literal lives only here (a re-inline anywhere else is flagged: the
-// guard-shape walk anchors on the literal). 2^53 - 1 is the safe-narrow ceiling.
-// The safe-integer test, taken at load. It decides whether a decoded value may be narrowed to a
-// Number at all, so one answering true for an unsafe magnitude reopens the precision loss this
-// guard exists to prevent. See guard-intrinsic for the whole captured set.
 var _isSafeInteger = require("./guard-intrinsic").isSafeInteger;
 var _freeze = require("./guard-intrinsic").freeze;
-// The narrow itself. This module exists to turn a bounded BigInt into a Number without losing the
-// bound, and `Number` is a writable property of globalThis, so a replacement returns whatever it
-// likes from a value this function has just certified as in range.
 var _Number = require("./guard-intrinsic").Number;
-// The widening half of the same job. A replacement returns a value the bound below is then applied
-// to instead of the caller's, so the number that passes the range test is not the number that came
-// in and is not the number handed back.
 var _BigInt = require("./guard-intrinsic").BigInt;
 
 var UINT31_MAX = 2147483647n;
 var SAFE_MAX   = 9007199254740991n;
 var SAFE_MIN   = -9007199254740991n;
-// 2^64 - 1 (also spelled 0xffffffffffffffffn). The uint64 ceiling lives only here
 // (both spellings are flagged as a re-inline; see uint64's @guard-shape lines).
 var UINT64_MAX = 18446744073709551615n;
 
-// int(value, min, max, E, code, label) -> a Number in [min, max].
-//   value : the BigInt result of an ASN.1 INTEGER / ENUMERATED read.
-//   min, max : inclusive BigInt bounds.
-//   E     : the (code, message, cause) typed-error factory in scope at the call
-//           site (ns.E / ctx.E / the module-local E) -- guard-range injects the
-//           caller's typed error through it, the tier-appropriate currency (a
-//           parse boundary carries a factory, not a bare ErrorClass).
-//   code  : the frozen domain/reason code this field rejects under.
-//   label : field phrase (+ optional RFC cite) for the message.
 // @enforced-by guard-shape-reinlined
 // @guard-shape 2147483647n
 function int(value, min, max, E, code, label) {
-  // Config-time authoring guard (Tier-1): the bounds must be BigInt. A Number
-  // bound (worst: NaN, which compares false against every BigInt) silently
-  // disables the range so any decoded value narrows. Then: narrowing to Number
-  // is lossless only when the whole range sits inside the safe-integer band
-  // [-(2^53-1), 2^53-1]. Both ends bind, since a min below the floor rounds a
-  // decoded value near it just as a max above the ceiling does. A wider range
-  // needs a BigInt-preserving guard, not this one, which is why the uint64
-  // Merkle-coordinate domain must not route here.
   if (typeof min !== "bigint" || typeof max !== "bigint") {
     throw new TypeError("guard.range.int: the min/max bounds must be BigInt");
   }
@@ -71,30 +26,18 @@ function int(value, min, max, E, code, label) {
   if (min < SAFE_MIN) {
     throw new TypeError("guard.range.int: min " + min + " is below the safe-integer floor; use a BigInt-preserving guard");
   }
-  // Parse-time reject (Tier-2): malformed / out-of-range decoded content.
   if (typeof value !== "bigint" || value < min || value > max) {
     throw E(code, label + " must be an integer within " + min + ".." + max);
   }
   return _Number(value);
 }
 
-// uint31(value, E, code, label) -> Number in [0, 2^31-1]. The DER-INTEGER
-// non-negative skip/path/salt shape (RFC 5280 / 4211 / 9810).
 // @enforced-by guard-shape-reinlined  (shares the 2147483647n shape declared on int)
 function uint31(value, E, code, label) { return int(value, 0n, UINT31_MAX, E, code, label); }
 
-// positiveInt31(value, E, code, label) -> Number in [1, 2^31-1]. The PKCS#12
-// PBKDF2 / MAC iteration-count shape (a count of at least one).
 // @enforced-by guard-shape-reinlined  (shares the 2147483647n shape declared on int)
 function positiveInt31(value, E, code, label) { return int(value, 1n, UINT31_MAX, E, code, label); }
 
-// uint64(value, E, code, label) -> a BigInt in [0, 2^64-1], without narrowing to
-// Number. Accepts a non-negative safe-integer Number (widened to BigInt) or a
-// BigInt; a Number past 2^53 (precision already lost), a negative, a non-integer,
-// or a non-number-non-bigint throws the caller's typed verdict. The uint64 domain
-// (a Merkle tree coordinate RFC 9162, an SCT timestamp RFC 6962) must not route
-// through int(), since narrowing to Number would corrupt the very value it guards, so
-// this is the BigInt-preserving sibling int()'s authoring guard points callers to.
 // @enforced-by guard-shape-reinlined
 // @guard-shape 18446744073709551615n
 // @guard-shape 0xffffffffffffffffn
@@ -113,17 +56,6 @@ function uint64(value, E, code, label) {
   return v;
 }
 
-// authoredInteger(value, E, code, label) -> BigInt. The AUTHORING counterpart to
-// int(): a value a CALLER supplies for an ASN.1 INTEGER with no upper bound (a CMC
-// Transaction Identifier, a CRMF certReqId), normalized to the BigInt the builders
-// take. Accepts a bigint, or a Number that is a safe integer (isSafeInteger, not
-// isInteger, because a Number above 2^53 has already lost precision by the time it
-// arrives), so a large identifier MUST come as a bigint and cannot be silently
-// rounded to a neighbor. Everything else is a config-time reject.
-//
-// Distinct from int() on purpose: int() BOUNDS a value the wire decoded and narrows
-// it to Number; this one is unbounded and returns BigInt, because the field has no
-// ceiling to check against and the encoder wants the wide type.
 // @enforced-by guard-shape-reinlined
 // @guard-shape Number\.isSafeInteger\(\s*[A-Za-z_$][\w$]*\s*\)\s*\)\s*return BigInt
 function authoredInteger(value, E, code, label) {
@@ -132,8 +64,6 @@ function authoredInteger(value, E, code, label) {
   throw E(code, label + " must be an integer (a safe-integer number, or a bigint for a large value)");
 }
 
-// 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({
   int: int, uint31: uint31, positiveInt31: positiveInt31, uint64: uint64,
   authoredInteger: authoredInteger,