@blamejs/pki 0.6.14 → 0.6.15

package/lib/tsp-sign.js

@@ -36,58 +36,43 @@ var _NS = pkix.makeNS("tsp", TspError, oid);
 var b = asn1.build;
 function _err(code, message, cause) { return new TspError(code, message, cause); }
 
-// Any ASCII digit 1-9 present (a non-zero fractional digit), by character scan -- no regex.
 function _hasNonZeroDigit(s) {
   for (var i = 0; i < s.length; i++) { var c = _charCodeAt(s, i); if (c >= 49 && c <= 57) return true; }
   return false;
 }
 function O(name) { return oid.byName(name); }
 
-// The shared authoring-side builder, for the same pre-encoded-Extension validation every other
-// request builder uses (a CSR's extensionRequest, a CRMF CertTemplate, a CRL's entry extensions).
 var _b = pkiBuild.makeBuilder({
   ErrorClass: TspError, prefix: "tsp", O: O, NS: _NS,
   NAME_SCHEMA: pkix.name(_NS), SPKI_SCHEMA: pkix.spki(_NS),
 });
 
-// Digest names whose imprint / certHash this producer supports (the SHA-2 family).
 var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512" };
-// The message-imprint hash MUST be exactly the digest algorithm's output length (RFC 3161 sec.
-// 2.4.1 -- hashedMessage is "the hash of the datum to be time-stamped").
 var HASH_LEN = { sha256: 32, sha384: 48, sha512: 64 };
 
-// How much a `pki.path.validate` revocationChecked outcome ESTABLISHED, ordered. `false` is "no
-// checker ran at all"; "undetermined" is "one ran and could not answer"; "waived" is an
-// undetermined one a caller chose to pass; "determined" is an explicit good-or-revoked answer.
-// Ranking them lets a caller trying several candidate paths keep the most established outcome any
-// of them reached. Order of evaluation then does not decide the answer.
 var _REVOCATION_RANK = { "false": 0, "undetermined": 1, "waived": 2, "determined": 3 };
 function _rankRevocation(v) {
   var r = _REVOCATION_RANK[String(v)];
-  return r === undefined ? 0 : r;   // an unrecognized value establishes nothing
+  return r === undefined ? 0 : r;
 }
 function _moreEstablished(candidate, current) {
   return _rankRevocation(candidate) > _rankRevocation(current);
 }
 
-// A hash AlgorithmIdentifier { OID, NULL }: messageImprint and ESSCertIDv2 hash algorithms
-// carry an explicit NULL parameter (the form RFC 3161 / RFC 5035 producers emit).
 function _hashAlgId(name) {
   if (!NODE_DIGEST[name]) throw _err("tsp/unsupported-algorithm", "unsupported hash algorithm " + JSON.stringify(name));
   return b.sequence([b.oid(O(name)), b.nullValue()]);
 }
-// A policy identifier: an OID name or a dotted-decimal string.
 function _policy(p) {
   if (typeof p !== "string") throw _err("tsp/bad-input", "the timestamp policy must be an OID name or dotted string");
   return oid.isDottedDecimal(p) ? b.oid(p) : b.oid(O(p));
 }
-// The signer certificate DER (a DER BufferSource / PEM string) -- for the ESSCertIDv2 hash.
 function _certDer(c) {
   if (c == null) throw _err("tsp/bad-input", "the TSA signer requires a certificate (cert)");
-  if (guard.bytes.isByteSource(c)) {                                                // any BufferSource -> a byte view
+  if (guard.bytes.isByteSource(c)) {
     var buf = guard.bytes.source(c, TspError, "tsp/bad-input", "the TSA certificate");
-    if (buf[0] === 0x30) return buf;                                                // DER as-is
-    c = buf.toString("latin1");                                                     // else decode as PEM
+    if (buf[0] === 0x30) return buf;
+    c = buf.toString("latin1");
   }
   if (typeof c !== "string") throw _err("tsp/bad-input", "the TSA certificate must be a DER BufferSource or a PEM string");
   var der = pkix.pemDecodeLenient(c, "CERTIFICATE");
@@ -95,14 +80,10 @@ function _certDer(c) {
   return der;
 }
 
-// The RFC 5035 SigningCertificateV2 signed-attribute value binding the token to the TSA cert:
-// SigningCertificateV2 ::= SEQUENCE { certs SEQUENCE OF ESSCertIDv2 }, ESSCertIDv2 ::= SEQUENCE {
-// hashAlgorithm DEFAULT sha256, certHash OCTET STRING, issuerSerial OPTIONAL }. The default
-// sha256 hashAlgorithm is omitted; certHash is the digest of the certificate.
 function _signingCertV2(certDer, hashName) {
   var certHash = nodeCrypto.createHash(NODE_DIGEST[hashName]).update(certDer).digest();
   var essCertId = hashName === "sha256"
-    ? b.sequence([b.octetString(certHash)])                       // hashAlgorithm DEFAULT sha256 omitted
+    ? b.sequence([b.octetString(certHash)])
     : b.sequence([_hashAlgId(hashName), b.octetString(certHash)]);
   return b.sequence([b.sequence([essCertId])]);
 }
@@ -143,26 +124,12 @@ function _signingCertV2(certDer, hashName) {
  *   var token = await pki.tsp.sign(imprint, { cert: signerCertDer, key: signerKeyPkcs8 }, { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
  *   (await pki.cms.verify(token)).valid;   // true
  */
-// Documented `-> Promise`, so a fault leaves as a REJECTION (guard-async); the checks stay
-// synchronous because they read the caller's mutable imprint, TSA material and options.
 function sign(messageImprint, tsa, opts) {
-  // Every caller-owned argument copied at entry and released when the call settles -- see the note
-  // on the same call in x509-sign. The imprint matters most: it is the digest the token attests to.
   return guard.bytes.fixedCall(TspError, "tsp/bad-input", [
     [messageImprint, "the messageImprint"], [tsa, "the TSA"], [opts, "pki.tsp.sign options"],
   ], _sign);
 }
 
-// The three caller-owned objects pki.tsp.sign reads. A dropped option here is a token that quietly
-// lacks what was asked for -- `odering` for `ordering` emitted a token with the ordering flag unset,
-// which is a claim about the timestamp's orderability that the caller believes they made.
-// The TSA is gated too, and the reason it needs to be is not the one it looks like. Both fields it
-// carries are REQUIRED, so a MISSPELLING of either is already refused for what it leaves missing --
-// but that is only half the class. A name belonging on the OPTIONS, written on the TSA instead, is
-// read by nothing here: `ordering` placed on the TSA emits a token the same size as one that never
-// asked for it, with the flag unset, while the caller believes they set it. Requiring the argument
-// to carry only what it reads is what closes that, so all three caller-owned arguments answer the
-// same question -- is this a name I read? -- rather than two of them answering it.
 var _TSA_KEYS = { cert: 1, key: 1 };
 var _IMPRINT_KEYS = { hashAlgorithm: 1, hashedMessage: 1 };
 var _SIGN_OPTS = {
@@ -197,16 +164,9 @@ function _sign(messageImprint, tsa, opts) {
   var certHashAlg = opts.certHashAlgorithm || "sha256";
   if (!NODE_DIGEST[certHashAlg]) throw _err("tsp/unsupported-algorithm", "unsupported certHashAlgorithm " + JSON.stringify(certHashAlg));
 
-  // TSTInfo (RFC 3161 sec. 2.4.2): version(1), policy, messageImprint, serialNumber, genTime,
-  // then the OPTIONAL accuracy / ordering / nonce in ascending order.
   var imprint = b.sequence([_hashAlgId(mi.hashAlgorithm), b.octetString(guard.bytes.source(mi.hashedMessage, TspError, "tsp/bad-input", "messageImprint.hashedMessage"))]);
-  // genTime defaults to now; a supplied value MUST be a valid Date (never a silently-ignored
-  // non-Date or an Invalid Date that would encode a garbage GeneralizedTime).
   if (opts.genTime != null) guard.time.assertValid(opts.genTime, _err, "tsp/bad-input", "genTime");
   var genTime = guard.time.isDate(opts.genTime) ? opts.genTime : new Date();
-  // A caller-authored INTEGER is coerced through the shared guard, so a value that is not one is a
-  // typed tsp/bad-input rather than a raw SyntaxError or RangeError out of BigInt() -- an untyped
-  // fault escaping a public verb, which a caller cannot catch by code.
   var serial = guard.range.authoredInteger(opts.serialNumber, _err, "tsp/bad-input", "serialNumber");
   var fields = [b.integer(1n), _policy(opts.policy), imprint, b.integer(serial), b.generalizedTime(genTime)];
   if (opts.accuracy) fields.push(_accuracy(opts.accuracy));
@@ -225,14 +185,6 @@ function _sign(messageImprint, tsa, opts) {
   });
 }
 
-// Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] INTEGER (1..999) OPTIONAL,
-// micros [1] INTEGER (1..999) OPTIONAL } (RFC 3161 sec. 2.4.2). seconds is a non-negative
-// integer; millis and micros MUST each be in 1..999 -- enforced before encoding.
-// Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] OPTIONAL, micros [1] OPTIONAL }
-// (RFC 3161 sec. 2.4.2). All three are OPTIONAL and encoded only when present, so a misspelling is
-// missed by nothing: `milis` emitted an EMPTY Accuracy that parses back as zero seconds, millis and
-// micros, and the token then understates its own precision -- a claim about the timestamp that the
-// caller believed they had made.
 var _ACCURACY_KEYS = { seconds: 1, millis: 1, micros: 1 };
 
 function _accuracy(a) {
@@ -249,25 +201,15 @@ function _accuracy(a) {
   if (a.micros != null) f.push(b.contextPrimitive(1, _subMilliBytes(a.micros, "micros")));
   return b.sequence(f);
 }
-// The content octets of an Accuracy millis/micros field: an INTEGER in 1..999 (RFC 3161 sec.
-// 2.4.2), without the universal INTEGER tag (the field is IMPLICIT [0]/[1]).
 function _subMilliBytes(n, label) {
   var v = Number(n);
   if (!Number.isInteger(v) || v < 1 || v > 999) throw _err("tsp/bad-input", "Accuracy " + label + " must be an integer in 1..999 (RFC 3161 sec. 2.4.2)");
-  return b.integer(BigInt(v)).subarray(2);               // strip the universal INTEGER tag+length
+  return b.integer(BigInt(v)).subarray(2);
 }
 
-// Coverage residual -- `_hashAlgId`'s unsupported-hash throw is unreachable through the shipped
-// path: both callers (the messageImprint hash and the ESSCertIDv2 certHashAlgorithm) validate
-// the name against NODE_DIGEST before `_hashAlgId` runs, so the guard is belt-and-suspenders.
 
-// PKIFailureInfo name -> NamedBitList bit index (RFC 3161 sec. 2.4.2; the reverse of the
-// schema-tsp FAILURE_BITS decode map). Build maps names -> bits; an unknown name fails closed.
 var FAILINFO_BIT = { badAlg: 0, badRequest: 2, badDataFormat: 5, timeNotAvailable: 14, unacceptedPolicy: 15, unacceptedExtension: 16, addInfoNotAvailable: 17, systemFailure: 25 };
 
-// Encode a PKIFailureInfo as a minimal DER NamedBitList BIT STRING from a set of names: set each
-// named bit (bit 0 = MSB of byte 0), strip trailing zero octets, and place unusedBits exactly
-// below the lowest set bit (X.690 sec. 11.2.2).
 function _failInfoBits(names) {
   if (!Array.isArray(names)) throw _err("tsp/bad-input", "failInfo must be an array of PKIFailureInfo names");
   var idxs = names.map(function (n) {
@@ -275,11 +217,9 @@ function _failInfoBits(names) {
     if (i == null) throw _err("tsp/bad-input", "unknown PKIFailureInfo name " + JSON.stringify(n) + " (RFC 3161 sec. 2.4.2)");
     return i;
   });
-  return b.namedBitString(idxs);   // minimal NamedBitList DER (X.690 sec. 11.2.2), empty when no bits set
+  return b.namedBitString(idxs);
 }
 
-// Coerce a timeStampToken (a CMS ContentInfo the token producer emits) to DER for embedding in a
-// TimeStampResp -- a DER Buffer as-is, a Uint8Array copied, or a PEM string de-armored.
 function _tokenDer(t) {
   if (guard.bytes.isByteSource(t)) { var u = guard.bytes.source(t, TspError, "tsp/bad-input", "the timeStampToken"); if (u[0] === 0x30) return u; }
   if (typeof t === "string") return schemaTsp.pemDecode(t);
@@ -315,10 +255,6 @@ function _assertImprint(mi) {
  *   var sha256Digest = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello")));
  *   var req = pki.tsp.request({ hashAlgorithm: "sha256", hashedMessage: sha256Digest }, { nonce: 0x0102030405060708n, certReq: true });
  */
-// The options pki.tsp.request encodes into the TimeStampReq. Every one is OPTIONAL in the
-// structure, so a misspelled name is missed by nothing and the request goes out claiming less than
-// was asked for. `nonce` is the one that costs most: misspelled, the request carries no nonce at
-// all, and the caller matches a reply against a replay defense that was never asked for.
 var _REQUEST_OPTS = { reqPolicy: 1, nonce: 1, certReq: 1, extensions: 1, pem: 1 };
 
 function request(messageImprint, opts) {
@@ -326,12 +262,6 @@ function request(messageImprint, opts) {
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.request options must be an object");
   guard.identifier.assertKnownKeys(opts, _REQUEST_OPTS, _err, "tsp/bad-input", "pki.tsp.request has an unknown option ");
   var mi = messageImprint || {};
-  // The same table pki.tsp.sign holds its imprint to. The request's own options live in the second
-  // argument, so `nonce` written on the imprint reaches nothing and the request goes out without
-  // the replay defense the caller believes they asked for.
-  // The same table pki.tsp.sign holds its imprint to. The request's own options live in the second
-  // argument, so `nonce` written on the imprint reaches nothing and the request goes out without
-  // the replay defense the caller believes they asked for.
   if (mi && typeof mi === "object" && !Buffer.isBuffer(mi)) {
     guard.identifier.assertKnownKeys(mi, _IMPRINT_KEYS, _err, "tsp/bad-input", function (k) {
       return "unknown messageImprint field " + JSON.stringify(k) +
@@ -340,8 +270,6 @@ function request(messageImprint, opts) {
   }
   _assertImprint(mi);
   var imprint = b.sequence([_hashAlgId(mi.hashAlgorithm), b.octetString(guard.bytes.source(mi.hashedMessage, TspError, "tsp/bad-input", "messageImprint.hashedMessage"))]);
-  // TimeStampReq: version(1), messageImprint, then OPTIONAL reqPolicy / nonce / certReq /
-  // extensions in schema order. certReq DEFAULT FALSE -> only an explicit TRUE is encoded (DER).
   var fields = [b.integer(1n), imprint];
   if (opts.reqPolicy != null) fields.push(_policy(opts.reqPolicy));
   if (opts.nonce != null) fields.push(b.integer(guard.range.authoredInteger(opts.nonce, _err, "tsp/bad-input", "nonce")));
@@ -349,11 +277,6 @@ function request(messageImprint, opts) {
   if (opts.certReq === true) fields.push(b.boolean(true));
   if (opts.extensions != null) {
     if (!Array.isArray(opts.extensions) || !guard.list.allMatch(opts.extensions, function (e) { return guard.bytes.isByteSource(e); })) throw _err("tsp/bad-input", "extensions must be an array of encoded Extension DER buffers");
-    // Each pre-encoded Extension is validated as one, and its extnID must not repeat -- the same
-    // gate every other request builder applies. Spliced in unchecked, a caller relaying a blob it
-    // did not author put fully chosen bytes inside [0] and this encoder emitted DER its own
-    // parseRequest refuses: an undecodable value, a duplicate extnID, an explicit critical=FALSE
-    // the DER DEFAULT rule forbids.
     var seenExt = {};
     var encoded = opts.extensions.map(function (e, i) {
       var der = guard.bytes.source(e, TspError, "tsp/bad-input", "an extension");
@@ -419,9 +342,6 @@ function parseRequest(input) { return schemaTsp.parseRequest(input); }
  *   var resp = pki.tsp.response(token, {});                                  // granted
  *   var rej  = pki.tsp.response(null, { status: 2, failInfo: ["badAlg"] });  // rejection
  */
-// The options pki.tsp.response encodes into the TimeStampResp. `status` carries the verdict and
-// defaults to granted(0), so a misspelled name does not lose a detail -- it INVERTS the answer: a
-// TSA refusing a request emits a granted response instead, over a token it did mean to withhold.
 var _RESPONSE_OPTS = { status: 1, statusString: 1, failInfo: 1, pem: 1 };
 
 function response(token, opts) {
@@ -436,8 +356,6 @@ function response(token, opts) {
   var siFields = [b.integer(BigInt(status))];
   if (opts.statusString != null) {
     var texts = Array.isArray(opts.statusString) ? opts.statusString : [opts.statusString];
-    // PKIFreeText is SEQUENCE SIZE (1..MAX) OF UTF8String -- an empty statusString would build an
-    // empty SEQUENCE the parser (seqOf min:1) rejects, so reject it at the builder instead.
     if (!texts.length) throw _err("tsp/bad-input", "statusString must carry at least one PKIFreeText element (RFC 4210 SEQUENCE SIZE 1..MAX)");
     siFields.push(b.sequence(texts.map(function (t) { return b.utf8(String(t)); })));
   }
@@ -478,61 +396,22 @@ function response(token, opts) {
  */
 function parseResponse(input) { return schemaTsp.parse(input); }
 
-// Coverage residual -- the null-guards and decode/parse catches in the verify helpers below are
-// belt-and-suspenders on values already guaranteed upstream, so their failure arms are unreachable
-// through the shipped path: parseToken has already proven the token is a single-signer SignedData
-// carrying a signing-certificate attribute, so `signerInfo`/`signedAttrs`/the signing-cert attr are
-// present; cms.verify returns a parsed, matched signer certificate, so `tsaCertDer` is set and
-// re-parsing it (or decoding its extensions) cannot fail here; decodeAttribute yields at least one
-// ESSCertID (an empty SEQUENCE OF is rejected at decode -> the `!essCert` guard is defensive); and
-// path.validate returns a fail-closed verdict for a bad anchor rather than throwing, so its catch
-// is defensive. Likewise, in the out-of-path chain step, `parsed.certificates` is always an array
-// (empty when absent), the embedded certs the chain walk parses are the X.509 (universal) choices,
-// and guard.name.dnEqual's control-byte reject is defensive on a cert x509.parse already accepted --
-// so the `|| []`, the non-universal filter arm, and that throw are unreachable through the shipped
-// path. In the tsa-hint check, the tsa GeneralName's decode catch is likewise defensive: parseToken
-// eager-decodes the token, so a constructed GeneralName that would fail decodeGeneralName has already
-// failed there, and a primitive one decodes -- the catch only guards decodeGeneralName's standalone
-// use and yields the same safe no-match. A malformed ESS value, a malformed EKU/keyUsage extnValue,
-// and a malformed subjectAltName ARE reachable (a signed-but-broken cert/attribute) and ARE covered;
-// the reachable verdicts (unsupported hash, EKU shape/wrapper, keyUsage, imprint/nonce/policy/binding
-// mismatch, tsa-hint match + mismatch, unknown critical extension, untrusted TSA, embedded-chain
-// ordering) are each driven by a RED conformance vector.
-
-// The imprint / ESSCertID hash algorithms a verifier can recompute: the SHA-2 family, plus SHA-1
-// for MATCHING a legacy token's imprint (a verify-side digest, never a signing choice). An unknown
-// or weak (e.g. MD5) algorithm cannot be recomputed, so the check fails closed rather than assume.
+
 var _VERIFY_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", sha1: "sha1" };
-// The digest output length each verify hash MUST produce: a messageImprint or precomputed imprint
-// of any other length is not a real digest and can never correspond to data (RFC 3161 sec. 2.4.1).
 var _VERIFY_DIGEST_LEN = { sha1: 20, sha256: 32, sha384: 48, sha512: 64 };
-// The ESSCertID(V2) certificate binding is a pure identity pin, so its digest MUST be
-// collision-resistant: a SHA-1 certHash would let a chosen-prefix collision substitute the TSA
-// certificate. RFC 5816 moved this binding from the SHA-1 ESSCertID to the SHA-2 ESSCertIDv2 for
-// exactly this reason -- accept only SHA-2 here (the messageImprint stays algorithm-agile, since
-// that hash is the requester's documented RFC 3161 choice, not an identity pin).
 var _BIND_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512" };
 
-// M10 -- recompute the imprint over `data` under the token's messageImprint hash algorithm (read
-// from the verified eContent) and compare to hashedMessage. `data` is raw bytes (hashed) or a
-// precomputed { hashAlgorithm, hashedMessage } (algorithm-exact + byte-exact). Returns true or a
-// tsp/* verdict code; a config-shape error throws (the caller's contract).
 function _imprintMatches(mi, data) {
   var name = mi.hashAlgorithm && mi.hashAlgorithm.name;
   var nodeAlg = (name && intrinsic.hasOwn(_VERIFY_DIGEST, name)) ? _VERIFY_DIGEST[name] : null;
-  if (!nodeAlg) return "tsp/unsupported-algorithm";   // cannot recompute -> never assume a match
+  if (!nodeAlg) return "tsp/unsupported-algorithm";
   var wantLen = _VERIFY_DIGEST_LEN[name];
-  // The token's messageImprint MUST be a full-length digest for its algorithm. A short/empty
-  // hashedMessage is not a hash and cannot correspond to any data, so it fails closed here -- a
-  // matching short precomputed imprint must never make it verify (RFC 3161 sec. 2.4.1).
   if (mi.hashedMessage.length !== wantLen) return "tsp/imprint-mismatch";
   var actual;
   if (guard.bytes.isByteSource(data)) {
     actual = nodeCrypto.createHash(nodeAlg).update(guard.bytes.source(data, TspError, "tsp/bad-input", "data")).digest();
   } else if (data && typeof data === "object" && guard.bytes.isByteSource(data.hashedMessage)) {
-    if (data.hashAlgorithm !== name) return "tsp/imprint-mismatch";   // a precomputed imprint under a different algorithm
-    // a caller-supplied precomputed imprint of the wrong length is a config error (the sign path
-    // rejects it identically) -- throw rather than silently mismatch (three-tier: caller input).
+    if (data.hashAlgorithm !== name) return "tsp/imprint-mismatch";
     var dhmLen = guard.bytes.source(data.hashedMessage, TspError, "tsp/bad-input", "precomputed imprint hashedMessage").length;
     if (dhmLen !== wantLen) throw _err("tsp/bad-input", "precomputed imprint hashedMessage length (" + dhmLen + ") does not match the " + name + " digest length (" + wantLen + ")");
     actual = guard.bytes.source(data.hashedMessage, TspError, "tsp/bad-input", "precomputed imprint hashedMessage");
@@ -542,41 +421,29 @@ function _imprintMatches(mi, data) {
   return Buffer.compare(actual, Buffer.from(mi.hashedMessage)) === 0 ? true : "tsp/imprint-mismatch";
 }
 
-// M13 -- the token MUST be bound to the exact signer certificate via the ESS SigningCertificate(V2)
-// signed attribute (RFC 3161 sec. 2.4.2 / RFC 5816): recompute hash(tsaCertDer) under the
-// ESSCertID(V2) hashAlgorithm (v1 implies SHA-1, v2 defaults SHA-256) and compare to certHash.
 function _checkCertBinding(signerInfo, tsaCertDer) {
   var attrs = (signerInfo && signerInfo.signedAttrs) || [];
-  // Prefer the RFC 5816 SigningCertificateV2 (SHA-2) binding over the legacy RFC 2634
-  // SigningCertificate (SHA-1). A token may carry both for compatibility, and the SHA-1 attribute
-  // sorts first in the signed-attribute SET; picking it would fail the SHA-2-only binding pin even
-  // though a usable v2 binding is present. Fall back to the legacy attribute only when no v2 exists.
   var sc = null, scV1 = null;
   for (var i = 0; i < attrs.length; i++) {
     if (attrs[i].type === O("signingCertificateV2")) { sc = attrs[i]; break; }
     if (attrs[i].type === O("signingCertificate") && !scV1) scV1 = attrs[i];
   }
   if (!sc) sc = scV1;
-  if (!sc) return "tsp/missing-signing-certificate";   // parseToken guarantees presence; belt-and-suspenders
+  if (!sc) return "tsp/missing-signing-certificate";
   var decoded;
   try { decoded = smime.decodeAttribute(sc); }
   catch (_e) { return "tsp/bad-signing-certificate"; }
   var essCert = decoded.certs && decoded.certs[0];
   if (!essCert) return "tsp/bad-signing-certificate";
   var nodeAlg = essCert.hashAlgorithm && _BIND_DIGEST[essCert.hashAlgorithm.name];
-  if (!nodeAlg) return "tsp/unsupported-algorithm";   // SHA-1 (or an unknown hash) is not a valid identity pin
+  if (!nodeAlg) return "tsp/unsupported-algorithm";
   var actual = nodeCrypto.createHash(nodeAlg).update(tsaCertDer).digest();
   if (Buffer.compare(actual, Buffer.from(essCert.certHash)) !== 0) return "tsp/cert-binding-mismatch";
-  // RFC 5035 sec. 5: if the ESSCertID(V2) carries the OPTIONAL issuerSerial, it MUST identify the
-  // signer certificate -- confirm its serialNumber. The certHash already pins the exact cert
-  // cryptographically; the serialNumber is that cert's unambiguous identity field.
   if (essCert.issuerSerial) {
     var signerCert;
     try { signerCert = pkiX509.parse(tsaCertDer); }
     catch (_e) { return "tsp/bad-signing-certificate"; }
     if (essCert.issuerSerial.serialNumber !== signerCert.serialNumber) return "tsp/cert-binding-mismatch";
-    // the issuerSerial issuer is a single directoryName (RFC 5035 sec. 5) that MUST canonically
-    // equal the signer cert's issuer DN -- decode it and compare through the shared name guard.
     var names = essCert.issuerSerial.issuer.names || [];
     var gn = null;
     try { if (names.length === 1) gn = schemaTsp.decodeGeneralName(names[0].bytes); }
@@ -588,33 +455,20 @@ function _checkCertBinding(signerInfo, tsaCertDer) {
   return true;
 }
 
-// M11 -- RFC 3161 sec. 2.3: the TSA certificate MUST contain exactly ONE extendedKeyUsage instance
-// whose sole KeyPurposeID is id-kp-timeStamping, and that extension MUST be CRITICAL. path.validate's
-// requiredEku only checks the purpose is ASSERTED (an absent EKU is unrestricted), so this
-// single-purpose + critical gate is layered on top -- the OCSP-delegate precedent for a format gate
-// above the path checks. Additionally (RFC 5280 sec. 4.2.1.3) a keyUsage extension, if present, MUST
-// permit signing for the cert to sign the token. Returns true or a tsp/* code.
 function _checkTsaCertUsage(tsaCertDer) {
   var cert;
   try { cert = pkiX509.parse(tsaCertDer); }
   catch (_e) { return "tsp/bad-tsa-certificate"; }
   var exts = (cert.extensions || []).filter(function (e) { return e.oid === O("extKeyUsage"); });
-  if (exts.length !== 1) return "tsp/bad-eku";   // absent, or a duplicate extension (RFC 5280 -- one instance)
+  if (exts.length !== 1) return "tsp/bad-eku";
   if (!exts[0].critical) return "tsp/eku-not-critical";
   var purposes, ekuNode;
   try { ekuNode = asn1.decode(exts[0].value); }
   catch (_e) { return "tsp/bad-eku"; }
-  // the extnValue MUST be a universal SEQUENCE OF KeyPurposeId -- a non-SEQUENCE constructed wrapper
-  // (e.g. a SET) carrying OID children would otherwise slip through the bare children walk.
   if (ekuNode.tagClass !== "universal" || ekuNode.tagNumber !== asn1.TAGS.SEQUENCE || !ekuNode.children) return "tsp/bad-eku";
   try { purposes = ekuNode.children.map(function (c) { return asn1.read.oid(c); }); }
   catch (_e) { return "tsp/bad-eku"; }
   if (purposes.length !== 1 || purposes[0] !== O("timeStamping")) return "tsp/eku-not-exclusive";
-  // A keyUsage that forbids signing cannot mint a token (RFC 5280 sec. 4.2.1.3); an absent keyUsage
-  // is unrestricted. Require digitalSignature (bit 0) or nonRepudiation/contentCommitment (bit 1) --
-  // the signing bits, the TSA analogue of the OCSP-responder keyUsage gate.
-  // Through the shared reader, which applies the NamedBitList rules (X.690 sec. 11.2.2 minimal
-  // encoding, sec. 4.2.1.3 at least one bit set) this boundary was applying only half of.
   var ku;
   try { ku = pkix.keyUsageOf(_NS, cert, _err, "tsp/bad-key-usage", "TSA certificate"); }
   catch (_e) { return "tsp/bad-key-usage"; }
@@ -622,9 +476,6 @@ function _checkTsaCertUsage(tsaCertDer) {
   return true;
 }
 
-// RFC 5816 sec. 2.2.2: if TSTInfo.tsa is present, it is a hint that MUST correspond to one of the
-// signing certificate's subject names -- its subject DN (a directoryName, compared canonically) or a
-// subjectAltName entry (a byte-exact GeneralName match). `tsaBytes` is the raw tsa GeneralName TLV.
 function _tsaMatchesCert(tsaBytes, signerCert) {
   var gn;
   try { gn = schemaTsp.decodeGeneralName(tsaBytes); }
@@ -635,8 +486,6 @@ function _tsaMatchesCert(tsaBytes, signerCert) {
     var san;
     try { san = asn1.decode(sanExt.value); }
     catch (_e) { return false; }
-    // subjectAltName MUST be a universal SEQUENCE OF GeneralName -- a malformed wrapper (e.g. a SET)
-    // carrying a byte-equal child must not contribute an identity (mirrors the EKU wrapper gate).
     if (san.tagClass === "universal" && san.tagNumber === asn1.TAGS.SEQUENCE && san.children) {
       for (var i = 0; i < san.children.length; i++) {
         if (san.children[i].bytes.equals(tsaBytes)) return true;
@@ -646,28 +495,15 @@ function _tsaMatchesCert(tsaBytes, signerCert) {
   return false;
 }
 
-// Bound on the candidate certification paths enumerated from a token's certificate pool -- a guard
-// against a hostile embed of many same-subject certificates blowing up the search (CWE-834).
 var MAX_TSA_CHAINS = 32;
 
-// Enumerate candidate certification paths for the TSA leaf from a pool of embedded and caller-supplied
-// certificates. path.validate validates a FIXED ordered path (it is not a path builder), so the
-// ordering + backtracking lives here: at every step EVERY unused pool certificate whose subject DN
-// equals the working issuer DN is a candidate issuer -- CA rollover / cross-certification embed
-// several with the same subject, and a same-subject wrong-key certificate must not shadow the real
-// issuer -- and each accumulated prefix is itself a candidate (the anchor may have issued the leaf
-// directly or any intermediate). A certificate is never chained to itself (RFC 5280 identity is
-// issuer + serialNumber, never the serial alone). Each chain is returned anchor-down (highest issuer
-// first, the leaf last) as path.validate takes it; longer chains first so a fully-embedded path is
-// preferred. Bounded by MAX_TSA_CHAINS. The caller (verify) tries each until one validates.
 function _buildTsaChains(leaf, pool) {
   var chains = [];
   function dfs(current, acc, used) {
     if (chains.length >= MAX_TSA_CHAINS) return;
-    chains.push(acc.slice());   // acc is leaf..current; the anchor may validate the path at this length
+    chains.push(acc.slice());
     for (var i = 0; i < pool.length && chains.length < MAX_TSA_CHAINS; i++) {
       if (used[i]) continue;
-      // never chain a certificate to itself (issuer + serialNumber identity, not the serial alone).
       if (pool[i].serialNumberHex === current.serialNumberHex && guard.name.dnEqual(pool[i].issuer.rdns, current.issuer.rdns, _err, "tsp/bad-tsa-certificate", "the TSA certificate issuer")) continue;
       if (guard.name.dnEqual(pool[i].subject.rdns, current.issuer.rdns, _err, "tsp/bad-tsa-certificate", "the TSA certificate subject")) {
         used[i] = true; acc.push(pool[i]);
@@ -742,11 +578,8 @@ function _buildTsaChains(leaf, pool) {
  *   res.valid;     // boolean; pass opts.trustAnchors to also chain the TSA cert to a root
  *   res.genTime;   // Date, read from the verified eContent
  */
-// Every option pki.tsp.verify reads. Adding one here is the only way to make it accepted.
 var _VERIFY_OPTS = { certs: 1, trustAnchors: 1, nonce: 1, reqPolicy: 1, revocationChecker: 1 };
 
-// Does any extension carry the critical flag? The answer IS the unknown-critical-extension gate, so
-// it is decided by comparison instead of by a `some`. See guard-list.
 function _anyCritical(extensions) {
   return guard.list.anyMatches(extensions, function (e) { return !!e && !!e.critical; });
 }
@@ -754,136 +587,60 @@ function _anyCritical(extensions) {
 async function verify(token, data, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.verify options must be an object");
-  // An unrecognized option is refused rather than ignored. The anchor option is `trustAnchors` (an
-  // anchor tuple, or a non-empty array of them), the same spelling pki.cms.verify / pki.cmp.verify use.
-  // A caller who mistyped it would otherwise get no anchoring and no error: the TSA certificate
-  // unchained, `valid: true`, and nothing to notice it by. Naming it at the boundary is cheap.
   guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "tsp/bad-input",
     "pki.tsp.verify has an unknown option (the anchor option is `trustAnchors`) ");
   if (opts.certs != null && (!Array.isArray(opts.certs) || !guard.list.allMatch(opts.certs, function (c) { return guard.bytes.isByteSource(c); }))) {
-    throw _err("tsp/bad-input", "pki.tsp.verify opts.certs must be an array of DER certificate Buffers");   // a bad element is a caller error, never silently dropped
+    throw _err("tsp/bad-input", "pki.tsp.verify opts.certs must be an array of DER certificate Buffers");
   }
-  var tokenDer = _tokenDer(token);   // DER Buffer / PEM -> DER; a non-token input throws tsp/bad-input
-  // M7 -- parseToken enforces the SignedData + id-ct-TSTInfo + single-signer + signing-cert-present
-  // structure and decodes the TSTInfo FROM the raw eContent; a structural defect throws.
+  var tokenDer = _tokenDer(token);
   var parsed = schemaTsp.parseToken(tokenDer);
   var tst = parsed.tstInfo;
-  // `trusted: false` on every refusal too, not only on the accepting return. A caller reading
-  // `res.trusted` must get an answer on both branches -- an undefined on the failure path is the
-  // same "cannot tell what was checked" the field was added to remove, and `!res.trusted` reading
-  // true by accident is not the same as its reading true because nothing anchored the TSA.
-  // What a path established travels with the REFUSAL as well. Hardcoding these to false/null here
-  // would misreport the one case the field matters most for: a path that ran, established the TSA
-  // REVOKED, and refused on that basis did check revocation, and saying it did not is the same
-  // "cannot tell what was checked" the field was added to remove. They stay false/null until a path
-  // actually produces them, which is the honest answer before one runs.
   var revocationChecked = false;
   var anchorConstraints = null;
   function fail(code, reason) {
     return { valid: false, trusted: false, revocationChecked: revocationChecked, anchorConstraints: anchorConstraints, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
   }
-  // M12 -- the CMS signature over the exact RFC 5652 sec. 5.4 preimage (message-digest bound to the
-  // authenticated eContent). cms.verify re-parses the same bytes; a failure is a fail-closed verdict.
-  // Caller-supplied out-of-band certificates (opts.certs) join the signer-certificate candidates, so
-  // a cert-less token (RFC 3161 -- the TSA omits its certificate when certReq was false) can verify.
   var cmsRes = await cmsVerify.verify(tokenDer, { certs: opts.certs });
   var signer = cmsRes.signers[0];
   if (!cmsRes.valid) return fail("tsp/bad-signature", signer && (signer.code || signer.message));
   var tsaCertDer = signer && signer.cert;
   if (!tsaCertDer) return fail("tsp/bad-signature", "the TSA signer certificate was not found");
-  // M10 -- what was timestamped MUST correspond to the data (imprint recompute + match).
   var mi = _imprintMatches(tst.messageImprint, data);
   if (mi !== true) return fail(mi);
-  // M14 -- if a request nonce is supplied, the token MUST echo it (BigInt-exact).
   if (opts.nonce != null) {
     var wantNonce = guard.range.authoredInteger(opts.nonce, _err, "tsp/bad-input", "opts.nonce");
     if (tst.nonce == null || tst.nonce !== wantNonce) return fail("tsp/nonce-mismatch");
   }
-  // M15 -- if the requested policy is supplied, the token's policy MUST equal it.
   if (opts.reqPolicy != null) {
     var wantPolicy = oid.isDottedDecimal(opts.reqPolicy) ? opts.reqPolicy : O(opts.reqPolicy);
     if (tst.policy !== wantPolicy) return fail("tsp/policy-mismatch");
   }
-  // A TSTInfo carrying a CRITICAL extension the verifier cannot process is unusable: RFC 3161 sec.
-  // 2.4.2 defers extension handling to RFC 5280 sec. 4.2, and defines no TSTInfo extension, so any
-  // critical one is unrecognized (the unknown-critical-extension gate the cert path also applies).
-  // The scan for a critical extension IS the gate, so it is a loop rather than a `some`: one
-  // answering false makes the unrecognized critical extension invisible and the token is accepted.
   if (tst.extensions && _anyCritical(tst.extensions)) {
     return fail("tsp/unknown-critical-extension");
   }
-  // M13 -- the ESSCertID(V2) binding: the verifying cert MUST be the one the signer identified.
   var bind = _checkCertBinding(parsed.signerInfo, tsaCertDer);
   if (bind !== true) return fail(bind);
-  // M11 -- the RFC 3161 sec. 2.3 critical single-timeStamping EKU gate + the keyUsage-permits-signing check.
   var usage = _checkTsaCertUsage(tsaCertDer);
   if (usage !== true) return fail(usage);
-  // RFC 5816 sec. 2.2.2 -- the tsa hint, when present, MUST name the signer certificate.
   if (tst.tsa) {
     var sc;
     try { sc = pkiX509.parse(tsaCertDer); }
     catch (_e) { return fail("tsp/bad-tsa-certificate"); }
     if (!_tsaMatchesCert(tst.tsa.bytes, sc)) return fail("tsp/tsa-mismatch");
   }
-  // M18 -- full out-of-path TSA-cert validation (issuer-sig, validity at genTime, unknown-critical,
-  // key-param inheritance, requiredEku, optional revocation), only when trustAnchors is supplied.
-  // The path is ordered from the token's embedded certificates (leaf + any intermediates), so a TSA
-  // issued under an intermediate CA -- not just directly under the anchor -- validates.
-  // `trusted` is the SECOND claim, kept apart from `valid`. `valid` says the token's signature and
-  // its structural bindings hold; whether the timestamp authority is one this caller accepts is
-  // answered only by the chain below, and only when an anchor was supplied. Collapsing the two into
-  // one boolean meant an archived verdict could not be re-read to tell whether the TSA was ever
-  // trusted -- which is exactly what a timestamp is archived to answer. Without an anchor there is
-  // nothing to chain to and `trusted` is false: a definite answer rather than a missing one, the
-  // same shape pki.cms.verify and pki.cmp.verify return.
   var trusted = false;
   if (opts.trustAnchors) {
     var pathRes = null;
-    // tst.genTime floors to millisecond precision. When genTime carries sub-millisecond digits the true
-    // instant lies in (floor, floor+1ms], so fail closed on BOTH validity boundaries: require each
-    // candidate path to validate at the floor AND the ceil. A token minted just after the certificate
-    // expired is rejected at the ceil (floor <= notAfter but ceil > notAfter); one minted just before
-    // notBefore is rejected at the floor (ceil >= notBefore but floor < notBefore). Certificate
-    // validity is seconds-precise (RFC 5280 sec. 4.1.2.5), so this never over-rejects a valid token.
     var floorT = tst.genTime;
     var ceilT = (tst.genTimeFraction != null && _hasNonZeroDigit(tst.genTimeFraction.slice(3))) ? new Date(guard.time.instantOf(floorT) + 1) : floorT;
     try {
-      // parseToken surfaces each embedded cert as { bytes, tagClass, ... }; take the X.509 certs
-      // (universal SEQUENCE), skipping any attribute-certificate choices, and parse their raw bytes.
-      // Caller out-of-band certificates (opts.certs) join the pool so an intermediate absent from the
-      // token can still complete the path.
       var pool = (parsed.certificates || []).filter(function (c) { return c.tagClass === "universal"; }).map(function (c) { return pkiX509.parse(c.bytes); });
       (opts.certs || []).forEach(function (c) { pool.push(pkiX509.parse(c)); });
-      // path.validate validates a FIXED path, so backtracking over same-subject issuer candidates
-      // happens here -- accept the TSA certificate if ANY enumerated chain validates to the anchor at
-      // both window endpoints.
-      //
-      // checkPurpose names timeStamping alongside requiredEku, and the pairing is the point. The EKU
-      // constrains the TSA CERTIFICATE; checkPurpose selects the ANCHOR's own trust metadata, which
-      // pki.path consults only when a purpose is named -- so asking one without the other checks one
-      // end of the chain and not the other, and a root explicitly distrusted for timestamping would
-      // still answer trusted. The purpose is not a caller choice here: this verb validates timestamp
-      // tokens and nothing else, so there is exactly one purpose its anchors can be judged under.
-      // EVERY path result goes through this one function, so none can be produced without being
-      // accumulated. The alternative -- validating in several places and accumulating afterwards --
-      // is what let a result be overwritten before it was counted, first across candidate chains and
-      // then across the two endpoints of one candidate. There is now one door and it always counts.
-      //
-      // The two fields accumulate INDEPENDENTLY because they are independent facts. Whether
-      // revocation was established and which anchor constraints were consulted do not imply each
-      // other: an anchor that rejects the TSA on its own purposes or distrustAfter metadata, with no
-      // revocationChecker configured, establishes constraints while establishing nothing about
-      // revocation.
       async function validateAt(chain, when) {
         var res = await pathValidate.validate(chain, {
           time: when, trustAnchors: opts.trustAnchors, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
         });
-        // The most any attempt ESTABLISHED, kept across every attempt: backtracking tries several
-        // chains for one TSA certificate and a fractional genTime validates each at two endpoints,
-        // so an attempt that fails earlier than another must not erase what that other established.
         if (_moreEstablished(res.revocationChecked, revocationChecked)) revocationChecked = res.revocationChecked;
-        // Every attempt validates against the SAME opts.trustAnchor under the same purpose, so any
-        // non-null value describes that one anchor; the first to report them is as good as the last.
         if (anchorConstraints == null && res.anchorConstraints != null) anchorConstraints = res.anchorConstraints;
         return res;
       }
@@ -893,20 +650,9 @@ async function verify(token, data, opts) {
         if (pathRes.valid && ceilT !== floorT) pathRes = await validateAt(chains[ci], ceilT);
       }
     } catch (e) { return fail("tsp/untrusted-tsa", (e && e.message) || String(e)); }
-    // On a REFUSAL the question is whether ANYTHING established the TSA's revocation status, so the
-    // accumulated best answers it: a candidate that reached the checker and was rejected as revoked
-    // did check revocation, and saying otherwise would misdescribe the reason for the refusal.
     if (!pathRes || !pathRes.valid) return fail("tsp/untrusted-tsa", "the TSA certificate did not validate to the trust anchor at genTime");
-    // On ACCEPTANCE the question is narrower and the accumulated best would OVERCLAIM: what matters
-    // is what was checked on the path actually accepted, not what some rejected candidate managed.
-    // The loop stops at the first valid path, so `pathRes` is that path.
     revocationChecked = pathRes.revocationChecked;
     anchorConstraints = pathRes.anchorConstraints;
-    // Reduced to a bare `trusted: true`, this answered the same way whether the TSA was established
-    // un-revoked or revocation was never consulted at all -- and revocation only runs when a
-    // revocationChecker is supplied, so the second case is the DEFAULT. A caller archiving a
-    // timestamp verdict could not tell the two apart later, which is the distinction the
-    // valid/trusted split exists to keep.
     trusted = true;
   }
   return {