@blamejs/pki 0.5.6 → 0.5.8

package/lib/guard-parsed.js

@@ -18,17 +18,17 @@
 // 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 rather than as a malformed input.
+//   - 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
+//     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
+// 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
@@ -42,7 +42,7 @@ var bytes = require("./guard-bytes");
 
 // Every form the toolkit calls "bytes": a Buffer, any typed-array view, a DataView, or a bare
 // ArrayBuffer. Testing `Buffer.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
+// 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 recognised.
 // guard.bytes is what finally reads them, and it accepts all four, so the door has to as well.
@@ -50,16 +50,16 @@ function _isBytes(x) {
   return Buffer.isBuffer(x) || ArrayBuffer.isView(x) || x instanceof ArrayBuffer;
 }
 
-// The shapes below assert the PARSER'S COMPLETE OUTPUT -- every field
+// 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.
+// 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
+// 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.
@@ -68,7 +68,7 @@ function _isBytes(x) {
 // 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
+// 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
@@ -78,10 +78,10 @@ function _isBytes(x) {
 // 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
+// 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
+// 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) {
@@ -112,8 +112,8 @@ function _isBitString(b) {
   return !!b && Buffer.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
+// 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
@@ -123,9 +123,9 @@ function _isExtensionEntry(e) {
     typeof e.critical === "boolean" && Buffer.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
+// 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) &&
@@ -134,8 +134,8 @@ function _isCrlExtensionEntry(e) {
 
 // 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" rather than throw --
+// 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.
 //
@@ -160,10 +160,10 @@ function isCert(o) {
 }
 
 // isCrl(o) -- the complete parsed-CertificateList shape. `crlExtensions` and each
-// entry's `crlEntryExtensions` are REQUIRED arrays rather than optional ones: the
+// 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
+// `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.
@@ -185,12 +185,12 @@ 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
+// 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 rather than at the door, because
+// 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) {
@@ -207,20 +207,20 @@ var _SHAPES = { 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
+// 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 rather than being sent to a byte parser that reports something unrelated.
+// 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,
+// 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.
 //
@@ -266,30 +266,30 @@ function accept(input, kind, parse, E, code, label) {
 // derived the object from, and the door derives the structure it verifies from those
 // bytes again.
 //
-// Recording the bytes rather than a boolean is what makes this hold. A flag saying
+// 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
+// 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,
+// 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
+// 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
+//   - 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
+//     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.
 //   - `Object.create(parsed)` is likewise a different object, so it inherits no
 //     record, while `Object.assign({}, parsed)` and `{...parsed}` are different
-//     objects too. All three -- the ways a mixed structure is actually assembled --
-//     fall out of the same rule rather than needing three checks.
+//     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
+// 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.
@@ -310,10 +310,10 @@ var PROVENANCE = new WeakMap();
 //     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
+//     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
+// 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
@@ -327,16 +327,17 @@ function recordingParser(kind, parse, ErrorClass, code, label) {
     var isText = typeof input === "string";   // strings are immutable; nothing to snapshot
     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.
+    // 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
+    // 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") {
-      PROVENANCE.set(out, { kind: kind, source: isText ? snap : Buffer.from(snap) });
+      PROVENANCE.set(out, { kind: kind, source: isText ? snap : Buffer.from(snap),
+        shape: _shapeOf(out) });
     }
     return out;
   };
@@ -344,18 +345,18 @@ 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 rather than bytes.
+// 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.
+// 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
+// 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
-// walker over that copy, so a re-derivation reproduces the structure exactly -- the decode is the
+// 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
@@ -368,6 +369,7 @@ function recordingWalker(kind, walkNode, decodeBytes) {
       PROVENANCE.set(out, {
         kind: kind,
         source: Buffer.from(node.bytes),
+        shape: _shapeOf(out),
         derive: function (src) { return walkNode(decodeBytes(src)); },
       });
     }
@@ -383,18 +385,84 @@ function _recordOf(obj, kind) {
   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" && PROVENANCE.has(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 = PROVENANCE.get(obj).shape;
+  var keys = _allNames(obj);
+  for (var i = 0; i < keys.length; i++) {
+    if (!shape[keys[i]]) return false;
+  }
+  return true;
+}
+
+function _shapeOf(obj) {
+  var shape = Object.create(null);
+  var keys = _allNames(obj);
+  for (var i = 0; i < keys.length; i++) shape[keys[i]] = true;
+  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 = Object.create(null);
+  for (var o = obj; o && o !== Object.prototype; o = Object.getPrototypeOf(o)) {
+    var own = Object.getOwnPropertyNames(o);
+    for (var i = 0; i < own.length; i++) {
+      if (seen[own[i]]) continue;
+      seen[own[i]] = true;
+      names.push(own[i]);
+    }
+  }
+  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
+// 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 rather than trusted. An object that CLAIMS to be parser output
-// -- it carries a field only a parsed structure of this kind has -- but carries no
+// 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, rather than handing the
-// object to a byte parser that would report something about its type instead.
+// `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
@@ -422,38 +490,38 @@ function fromTrustedSource(input, kind, claimFields, parse, E, code, why) {
 //
 // acceptDerived(input, kind, parse, E, code, label) -> the parsed structure | throws.
 //
-// THE 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.
+// 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 rather than a rule for the doors that "reach a verdict", because
+// 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
+// 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.
+// 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 rather than handed to a byte parser that would report something
-// about its type instead.
+// was rebuilt is told what happened, never handed to a byte parser that would report something
+// about its type.
 var _CLAIMS = {
   certificate: ["tbsBytes", "subjectPublicKeyInfo", "serialNumberHex"],
   crl: ["tbsBytes", "revokedCertificates", "crlExtensions"],
   cms: ["signerInfos", "encapContentInfo"],
 };
 var _WHY = {
-  certificate: "the signed byte range, the signature and the fields that range encodes are separate properties of a parsed object, so a REBUILT certificate (Object.assign, spread, a JSON round-trip) could have them describe different certificates -- keep a real CA certificate's signed bytes and signature and replace only its public key and every field is still well-formed",
-  crl: "the signed byte range, the revocation list and the scope extensions are separate properties of a parsed object, so a REBUILT CRL could have them describe different CRLs -- empty the revocation list and a correctly signed CRL reports a revoked certificate as good",
-  cms: "the signed attribute bytes, the signature, the encapsulated content and the certificates that verify it are separate properties of a parsed object, so a REBUILT SignedData could have them describe different messages -- keep a genuine signer's signature and signed attributes and put other content beside them, and every part of the check passes for content that signer never signed",
+  certificate: "the signed byte range, the signature and the fields that range encodes are separate properties of a parsed object, so a rebuilt certificate (Object.assign, spread, a JSON round-trip) could have them describe different certificates: keep a real CA certificate's signed bytes and signature, replace only its public key, and every field is still well-formed",
+  crl: "the signed byte range, the revocation list and the scope extensions are separate properties of a parsed object, so a rebuilt CRL could have them describe different CRLs: empty the revocation list and a correctly signed CRL reports a revoked certificate as good",
+  cms: "the signed attribute bytes, the signature, the encapsulated content and the certificates that verify it are separate properties of a parsed object, so a rebuilt SignedData could have them describe different messages: keep a genuine signer's signature and signed attributes, put other content beside them, and every part of the check passes for content that signer never signed",
 };
 // @enforced-by guard-shape-reinlined -- shares the fromTrustedSource shape it composes: a door that
-//   tests the claim fields itself, rather than routing here, is the re-inline both replace.
+//   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 rather than handed
-  // to the byte parser. The parser would refuse it too, but with its own domain's code -- a caller
+  // 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)) {
@@ -478,5 +546,6 @@ module.exports = {
   accept: accept, acceptDerived: acceptDerived,
   fromTrustedSource: fromTrustedSource, recordingParser: recordingParser,
   recordingWalker: recordingWalker,
-  isCert: certShape, isCrl: crlShape,
+  isCert: certShape, isCrl: crlShape, isRecorded: isRecorded,
+  isRecordedAsProduced: isRecordedAsProduced,
 };

package/lib/guard-range.js

@@ -6,25 +6,25 @@
 // 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
+// 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
+// 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 / iteration counter -- acts on the WRONG number;
+// 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
+// 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.
 
-// 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
+// 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.
 var UINT31_MAX = 2147483647n;
 var SAFE_MAX   = 9007199254740991n;
 var SAFE_MIN   = -9007199254740991n;
-// 2^64 - 1 (also spelled 0xffffffffffffffffn). The uint64 ceiling lives ONLY here
+// 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;
 
@@ -40,14 +40,14 @@ var UINT64_MAX = 18446744073709551615n;
 // @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
+  // 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 -- a min below the floor rounds a
+  // 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 (this is why the uint64
-  // Merkle-coordinate domain must NOT route here).
+  // 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");
   }
@@ -74,12 +74,12 @@ function uint31(value, E, code, label) { return int(value, 0n, UINT31_MAX, E, co
 // @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
+// 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() -- narrowing to Number would corrupt the very value it guards, so
+// (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
@@ -102,9 +102,9 @@ function uint64(value, E, code, label) {
 // 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
+// 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 rather than be silently
+// arrives), so a large identifier MUST come as a bigint and cannot be silently
 // rounded to a neighbour. Everything else is a config-time reject.
 //
 // Distinct from int() on purpose: int() BOUNDS a value the wire decoded and narrows

package/lib/guard-secret.js

@@ -23,7 +23,7 @@
 // window. It does not support a claim that a secret never persists in memory,
 // and no operator-facing text may imply that it does.
 //
-// OWNERSHIP IS THE CONTRACT. Only a buffer the toolkit allocated may be wiped --
+// Ownership is the contract. Only a buffer the toolkit allocated may be wiped:
 // never a caller's opts.key / opts.cert / opts.kek / opts.password, and never the
 // input DER. Silently destroying a caller's own memory is a worse defect than
 // leaving a secret readable, and it is the failure mode a zeroization patch
@@ -38,7 +38,7 @@ var bytes = require("./guard-bytes");
 //                `{ withCause: true }`. The guard family carries two currencies --
 //                most guards take a (code, message) factory and call it without
 //                `new`, while guard-bytes / guard-header take the class and
-//                construct it. This module's ONLY throw is the delegated re-view
+//                construct it. This module's one throw is the delegated re-view
 //                below, so it must pass what guard-bytes expects: the class, and
 //                one that accepts a cause, because guard-bytes threads the raw
 //                detach fault through as one. A plain class fails to construct at
@@ -47,13 +47,14 @@ var bytes = require("./guard-bytes");
 //   label      : field phrase for the message.
 //
 // A detached ArrayBuffer cannot be written, and reaching one here means a caller
-// handed over memory that was transferred away -- a real fault, not something to
-// swallow, so it routes through the shared re-view guard and throws typed.
+// handed over memory that was transferred away. That is a real fault and not
+// something to swallow, so it routes through the shared re-view guard and throws
+// typed.
 //
-// The `.fill(0)` shape lives ONLY in this module: a wipe re-inlined anywhere in
-// lib/ -- including a module not yet written -- is flagged, so the safe
-// implementation is also the tripwire that stops the next consumer from rolling
-// its own partial one.
+// The `.fill(0)` shape lives only in this module. A wipe re-inlined anywhere in
+// lib/, including a module not yet written, is flagged, so the safe implementation
+// is also the tripwire that stops the next consumer from rolling its own partial
+// one.
 // @enforced-by guard-shape-reinlined
 // @guard-shape \.fill\s*\(\s*0\s*[,)]
 function zeroize(value, ErrorClass, code, label) {
@@ -65,14 +66,14 @@ function zeroize(value, ErrorClass, code, label) {
   return value;
 }
 
-// zeroizeAll(list, ErrorClass, code, label) -- wipe every present member, tolerating
+// zeroizeAll(list, ErrorClass, code, label) wipes every present member, tolerating
 // holes so a `finally` can name intermediates that may not have been reached.
 //
 // @enforced-by behavioral -- this is a loop over zeroize, which carries the family's only
 // rename-proof shape (the `.fill(0)` above). It introduces no shape of its own, so a lexical
 // detector here would anchor on a renameable symbol and go silently green (drift rule sec. 3).
 // The behavioural guards are guard-secret.test.js (holes tolerated, every member cleared) and the
-// CMS vectors that assert the shared secret and KEK are wiped on BOTH the success and failure paths.
+// CMS vectors that assert the shared secret and KEK are wiped on both the success and failure paths.
 function zeroizeAll(list, ErrorClass, code, label) {
   if (!list) return list;
   for (var i = 0; i < list.length; i++) zeroize(list[i], ErrorClass, code, label);

package/lib/guard-text.js

@@ -7,7 +7,7 @@
 // PEM decoders, the EST transfer decoders).
 //
 // guard-text -- fail-closed decode of an untrusted byte-source input to a
-// string, capping the RAW byte length BEFORE the string is materialized.
+// string, capping the raw byte length before the string is materialized.
 // Enforced choke point for the byte->string boundary.
 //
 // Defends the parser-DoS string-allocation class (CWE-770 allocation without
@@ -25,10 +25,10 @@ var LATIN1 = "latin1";
 
 // decode(input, maxBytes, ErrorClass, spec) -> string.
 //   input     : a Buffer (decoded per spec.charset) or a string (taken as-is).
-//   maxBytes  : the raw byte-length ceiling, checked BEFORE any string copy.
+//   maxBytes  : the raw byte-length ceiling, checked before any string copy.
 //   ErrorClass: a PkiError subclass (withCause where spec.fatal is set).
 //   spec      : { charset: "latin1"|"utf-8" (default latin1),
-//                 fatal:   boolean -- strict UTF-8 (a lone continuation /
+//                 fatal:   boolean, strict UTF-8 (a lone continuation /
 //                          truncated sequence throws, never substitutes U+FFFD),
 //                 tooLarge: code for the over-cap reject,
 //                 badDecode: code for a fatal-charset (bad-UTF-8) reject
@@ -40,15 +40,15 @@ var LATIN1 = "latin1";
 //   enforced) are the guard.
 function decode(input, maxBytes, ErrorClass, spec) {
   // maxBytes is an authoring input: an undefined / NaN / fractional cap makes
-  // the `length > maxBytes` comparison always false -- the size cap silently
-  // disabled on the guard whose contract is cap-BEFORE-copy. Config-time
+  // the `length > maxBytes` comparison always false, silently disabling the size
+  // cap on the guard whose whole contract is cap-before-copy. Config-time
   // TypeError (every composing boundary passes a C.LIMITS constant).
   if (!Number.isInteger(maxBytes) || maxBytes < 0) {
     throw new TypeError("guard.text.decode: maxBytes must be a non-negative integer");
   }
   var charset = spec.charset || LATIN1;
   if (Buffer.isBuffer(input)) {
-    // Re-view through the byte guard FIRST so a detached backing ArrayBuffer (a
+    // Re-view through the byte guard first so a detached backing ArrayBuffer (a
     // transferred / structuredClone'd Buffer, which reads as zero-length) fails
     // closed here -- the same detached-buffer defence the byte boundaries get --
     // instead of being decoded as an empty string. Then cap, then decode.