@blamejs/pki 0.6.13 → 0.6.15

package/lib/sigstore.js

@@ -44,40 +44,32 @@ function _err(code, message, cause) { return new SigstoreError(code, message, ca
 var JSON_MAX = C.LIMITS.JSON_MAX_BYTES;
 var SP = Buffer.from(" ", "ascii");
 var DSSEV1 = Buffer.from("DSSEv1", "ascii");
-// The checkpoint signature-line marker is EM DASH (U+2014) + space; built at runtime so the source
-// file stays pure ASCII. The line is parsed by character scan (no regex): "<EM DASH> <keyId> <sig>",
-// two whitespace-separated non-empty tokens, nothing after.
 var _EM_DASH = String.fromCharCode(0x2014);
 
-// The \S token scan uses the shared JS regex \s code-point predicate (pkix.isJsWhitespace) so the
-// note-line grammar stays exactly the /\S/ complement without a second copy of the code-point set.
 function _parseNoteSig(line) {
   var prefix = _EM_DASH + " ";
   if (line.slice(0, prefix.length) !== prefix) return null;
   var p = prefix.length, n = line.length;
   var t1s = p;
   while (p < n && !pkix.isJsWhitespace(line.charCodeAt(p))) p += 1;
-  if (p === t1s) return null;                     // \S+ requires at least one character
+  if (p === t1s) return null;
   var keyId = line.slice(t1s, p);
-  if (line.charAt(p) !== " ") return null;        // the literal single space between the tokens
+  if (line.charAt(p) !== " ") return null;
   p += 1;
   var t2s = p;
   while (p < n && !pkix.isJsWhitespace(line.charCodeAt(p))) p += 1;
   if (p === t2s) return null;
   var sig = line.slice(t2s, p);
-  if (p !== n) return null;                        // $ -- nothing after the second token
+  if (p !== n) return null;
   return { keyId: keyId, sig: sig };
 }
 
-// A run of trailing "=" removed (the /=+$/ base64-padding strip).
 function _stripTrailingEquals(s) {
   var i = s.length;
   while (i > 0 && s.charAt(i - 1) === "=") i -= 1;
   return s.slice(0, i);
 }
 
-// The recognized bundle media types (draft: the inline ".v0.N+json" form and the
-// "+json;version=0.N" form, N in 1..3) -- an explicit set in place of the anchored alternation regex.
 var _BUNDLE_MEDIA_TYPES = {
   "application/vnd.dev.sigstore.bundle.v0.1+json": 1,
   "application/vnd.dev.sigstore.bundle.v0.2+json": 1,
@@ -90,7 +82,6 @@ function _isBundleMediaType(mt) {
   return typeof mt === "string" && Object.prototype.hasOwnProperty.call(_BUNDLE_MEDIA_TYPES, mt);
 }
 
-// Parse untrusted JSON through the bounded, duplicate-member-rejecting guard.
 function _jsonParse(input, code, label) {
   return guard.json.parse(input, _err, {
     maxBytes: JSON_MAX, maxDepth: 64,
@@ -98,7 +89,6 @@ function _jsonParse(input, code, label) {
   });
 }
 
-// ---- DSSE PAE (secure-systems-lab/dsse protocol.md) --------------------------
 
 /**
  * @primitive pki.sigstore.pae
@@ -129,10 +119,7 @@ function pae(payloadType, payloadBytes) {
   ]);
 }
 
-// ---- strict base64 decode (fail-closed, canonical) ---------------------------
 
-// Sigstore fields are standard (padded) base64; DSSE permits URL-safe. Decode
-// either, but reject a non-canonical re-encoding (an encoding-malleability guard).
 function _b64(s, label) {
   if (typeof s !== "string") throw _err("sigstore/bad-bundle", label + " must be a base64 string");
   var urlSafe = s.indexOf("-") !== -1 || s.indexOf("_") !== -1;
@@ -144,7 +131,6 @@ function _b64(s, label) {
   return buf;
 }
 
-// ---- JSON bundle reader (fail-closed) ----------------------------------------
 
 /**
  * @primitive pki.sigstore.parseBundle
@@ -176,9 +162,6 @@ function parseBundle(input) {
     throw _err("sigstore/bad-bundle", "bundle must be a JSON object, string, or Buffer");
   }
   if (!obj || typeof obj !== "object" || Array.isArray(obj)) throw _err("sigstore/bad-bundle", "bundle must be a JSON object");
-  // Accept only the bundle versions this verifier actually handles (v0.1-v0.3);
-  // a newer version is recognized-and-deferred, never accepted by an over-broad
-  // match (the inline `.v0.N+json` form and the `+json;version=0.N` form).
   var mt = obj.mediaType;
   if (!_isBundleMediaType(mt)) {
     throw _err("sigstore/bad-bundle-version", "unsupported or unknown bundle media type: " + (mt === undefined ? "(none)" : mt));
@@ -200,10 +183,7 @@ function parseBundle(input) {
   return obj;
 }
 
-// ---- leaf-key + signature primitives (node:crypto, sync) ---------------------
 
-// A bundle X509Certificate element is `{ rawBytes: <base64 DER> }`; a null /
-// non-object / non-string element fails closed, never a raw property deref.
 function _certBytes(c, label) {
   if (!c || typeof c !== "object" || typeof c.rawBytes !== "string") throw _err("sigstore/bad-bundle", label + " is not a { rawBytes } certificate");
   return _b64(c.rawBytes, label);
@@ -222,14 +202,9 @@ function _chainDers(vm) {
   return [_leafCertDer(vm)];
 }
 
-// Verify a DER ECDSA / Ed25519 signature over `data` under a node public key.
 function _rawVerify(keyObj, data, derSig) {
   var t = keyObj.asymmetricKeyType;
   if (t === "ed25519" || t === "ed448") {
-    // Defense in depth at the verify SINK (not only at _pubFromSpki): node imports a low-order /
-    // off-curve OKP key without complaint and such a key verifies a FORGED EdDSA signature, so re-gate
-    // the point here regardless of how keyObj was obtained -- no verify sink may hand an unvalidated
-    // Edwards key to node's verify.
     edwardsPoint.validateSpki(keyObj.export({ type: "spki", format: "der" }), t === "ed25519" ? 6 : 7, SigstoreError, "sigstore/bad-key");
     return nodeCrypto.verify(null, data, keyObj, derSig);
   }
@@ -241,35 +216,21 @@ function _pubFromSpki(spkiDer, label) {
   var key;
   try { key = nodeCrypto.createPublicKey({ key: spkiDer, format: "der", type: "spki" }); }
   catch (e) { throw _err("sigstore/bad-key", "invalid " + label + " public key", e); }
-  // node imports a low-order (e.g. all-zeroes) OKP public key without complaint, and such a key
-  // verifies a FORGED EdDSA signature -- route an Ed25519/Ed448 SPKI through the shared full-order,
-  // on-curve Edwards-point gate (as the webauthn and path-validation EdDSA paths already do) before it
-  // can be handed to verify.
   var t = key.asymmetricKeyType;
   if (t === "ed25519" || t === "ed448") {
     edwardsPoint.validateSpki(spkiDer, t === "ed25519" ? 6 : 7, SigstoreError, "sigstore/bad-key");
   }
   return key;
 }
-// Parse a certificate, re-typing a malformed-DER fault to a sigstore/* error so
-// the caller never sees a raw certificate/* / asn1/* leak from this boundary.
 function _parseCert(der, label) {
   try { return x509.parse(der); }
   catch (e) { throw _err("sigstore/bad-certificate", "invalid " + label, e); }
 }
 
-// ---- Rekor leg (RFC 9162 inclusion + Rekor-signed root + entry binding) -------
 
 function _sha256(buf) { return nodeCrypto.createHash("sha256").update(buf).digest(); }
 
-// Select the caller Rekor key whose logId.keyId matches the entry's logId (full
-// 32-byte id) or a 4-byte checkpoint keyhint. Never trust a key from the bundle.
-// A key carrying a validFor window is used only if `timeMs` (the entry's log
-// time) falls inside it -- a rotated-out key must not verify a later entry.
-// A validFor bound is an epoch-ms number, a Date, or an ISO-8601 string (the form
-// a Sigstore trusted_root carries). Returns null for absent/unparseable.
 function _toMs(x) {
-  // Coverage residual -- _inWindow gates every _toMs call behind a != null check; the null guard is dead defensive code.
   if (x == null) return null;
   if (typeof x === "number") return Number.isFinite(x) ? x : null;
   if (guard.time.isDate(x)) { var d = guard.time.instantOf(x); return isNaN(d) ? null : d; }
@@ -278,8 +239,6 @@ function _toMs(x) {
 }
 function _inWindow(timeMs, vf) {
   if (!vf) return true;
-  // A present-but-unparseable bound fails closed (the key/CA is not used) rather
-  // than silently disabling the window it configures.
   if (vf.start != null) { var s = _toMs(vf.start); if (s === null || !(timeMs >= s)) return false; }
   if (vf.end != null) { var e = _toMs(vf.end); if (e === null || !(timeMs <= e)) return false; }
   return true;
@@ -294,15 +253,12 @@ function _rekorKey(rekorKeys, keyIdBuf, hint, timeMs) {
   return null;
 }
 
-// Verify the checkpoint (C2SP signed-note): ECDSA-P256-SHA256 over the note body
-// (bytes up to and including the newline before the blank-line separator).
 function _verifyCheckpoint(envelope, ip, rekorKeys, timeMs) {
   var buf = Buffer.from(envelope, "utf8");
   var sep = buf.indexOf("\n\n");
   if (sep < 0) throw _err("sigstore/bad-checkpoint", "the checkpoint has no note/signature separator");
   var body = buf.subarray(0, sep + 1);
   var lines = body.toString("utf8").split("\n");
-  // The note body's third line is the base64 tree root; it MUST equal the proof root.
   if (_b64(lines[2], "checkpoint root").toString("hex") !== _b64(ip.rootHash, "inclusionProof.rootHash").toString("hex")) {
     throw _err("sigstore/inclusion-proof-mismatch", "the checkpoint root does not match the inclusion-proof root");
   }
@@ -320,8 +276,6 @@ function _verifyCheckpoint(envelope, ip, rekorKeys, timeMs) {
   return false;
 }
 
-// Verify the SET (inclusionPromise.signedEntryTimestamp): ECDSA over the RFC 8785
-// canonical JSON { body, integratedTime, logID, logIndex } (keys sorted).
 function _verifySet(te, rekorKeys, timeMs) {
   var promise = te.inclusionPromise;
   if (!promise || typeof promise.signedEntryTimestamp !== "string") return false;
@@ -338,9 +292,6 @@ function _verifySet(te, rekorKeys, timeMs) {
   return _rawVerify(_pubFromSpki(k.spki, "Rekor log"), Buffer.from(canonical, "utf8"), sig);
 }
 
-// Bind the tlog entry to THIS bundle's signature: the dsse-kind body's embedded
-// signature + payload hash must be the envelope's (RFC 9162 proves the body is
-// logged; this proves the body is OUR envelope, not some other logged entry).
 function _bindEntry(te, envelope, leafDer) {
   var body = _jsonParse(_b64(te.canonicalizedBody, "canonicalizedBody"), "sigstore/bad-tlog-entry", "Rekor entry body");
   if (!body || typeof body !== "object" || Array.isArray(body)) throw _err("sigstore/bad-tlog-entry", "the Rekor entry body is not a JSON object");
@@ -353,16 +304,10 @@ function _bindEntry(te, envelope, leafDer) {
   var bodySig = _b64(spec.signatures[0].signature, "Rekor entry signature");
   if (!envSig.equals(bodySig)) throw _err("sigstore/entry-mismatch", "the Rekor entry signature does not match the bundle signature");
   var payload = _b64(envelope.payload, "dsseEnvelope.payload");
-  // payloadHash is a required binding field: bind it to the envelope payload
-  // rather than skipping the check when it is absent.
   if (!spec.payloadHash || typeof spec.payloadHash.value !== "string") throw _err("sigstore/bad-tlog-entry", "the Rekor dsse entry is missing its payloadHash");
   if (spec.payloadHash.value !== _sha256(payload).toString("hex")) {
     throw _err("sigstore/entry-mismatch", "the Rekor entry payloadHash does not match the bundle payload");
   }
-  // The dsse entry's verifier certificate is REQUIRED and MUST be the bundle's
-  // leaf cert -- otherwise a valid inclusion proof for an entry signed by a
-  // DIFFERENT Fulcio cert could be paired with this envelope (the signature match
-  // alone leaves cert substitution).
   var vf = spec.signatures[0].verifier;
   if (typeof vf !== "string") throw _err("sigstore/bad-tlog-entry", "the Rekor dsse entry is missing its verifier certificate");
   var vDer;
@@ -376,13 +321,9 @@ function _verifyRekor(te, envelope, rekorKeys, leafDer) {
   if (!ip || typeof ip.rootHash !== "string" || !Array.isArray(ip.hashes)) {
     throw _err("sigstore/bad-inclusion-proof", "the transparency-log entry has no inclusion proof");
   }
-  // The entry's CLAIMED log time selects which caller Rekor key is in its validity
-  // window; the SET (required below) re-confirms it by signing it.
   var claimedSec = Number(te.integratedTime);
   var claimedMs = Number.isFinite(claimedSec) ? C.TIME.seconds(claimedSec) : NaN;
-  // Bind the entry to this signature FIRST (a proof for another entry is not evidence).
   _bindEntry(te, envelope, leafDer);
-  // Fold the audit path to the tree root (RFC 9162), reusing pki.merkle.
   var included;
   try {
     included = merkle.verifyInclusion({
@@ -396,33 +337,19 @@ function _verifyRekor(te, envelope, rekorKeys, leafDer) {
     throw _err("sigstore/bad-inclusion-proof", "the inclusion proof is malformed: " + e.message, e);
   }
   if (!included) throw _err("sigstore/inclusion-proof-mismatch", "the inclusion proof does not reconstruct the tree root");
-  // The inclusion proof above only reconstructs the attacker-supplied
-  // inclusionProof.rootHash; that root is trust ONLY once the Rekor-signed
-  // checkpoint (which signs the tree root) verifies over it -- so the checkpoint
-  // is REQUIRED, or the inclusion check is theater against an unsigned root.
   var checkpointOk = ip.checkpoint && typeof ip.checkpoint.envelope === "string" && _verifyCheckpoint(ip.checkpoint.envelope, ip, rekorKeys, claimedMs);
   if (!checkpointOk) throw _err("sigstore/unsigned-root", "the Rekor checkpoint (the signed tree root) did not verify under the caller Rekor key -- the inclusion-proof root is not attested");
-  // The integratedTime dates the ephemeral (~10-min) Fulcio cert, so it too must
-  // be Rekor-attested: ONLY the SET signs it (the checkpoint signs the root, not
-  // the time). Without a verified SET the time is attacker-controlled and could
-  // date an expired cert into validity -- require it (the RFC 3161 timestamp
-  // source is the deferred alternative).
   var setOk = _verifySet(te, rekorKeys, claimedMs);
   if (!setOk) throw _err("sigstore/unattested-time", "the Rekor SET (the signed source of integratedTime) did not verify -- the log time is not attested and cannot date the Fulcio certificate");
   var t = Number(te.integratedTime);
   if (!Number.isFinite(t) || t < 0) throw _err("sigstore/bad-tlog-entry", "the transparency-log entry has a malformed integratedTime");
-  // Surface which attested Rekor log entry this is: the global log index and the log's key id (hex), so a
-  // caller can locate the exact transparency-log record for an audit rather than re-deriving it.
   var li = Number(te.logIndex);
   return { integratedTime: t, logIndex: Number.isFinite(li) ? li : null, logId: te.logId && te.logId.keyId ? _b64(te.logId.keyId, "logId.keyId").toString("hex") : null };
 }
 
-// ---- Fulcio chain leg (RFC 5280 path validation, as-of the log time) ----------
 
 function _dn(cert, which) { return cert[which] && cert[which].dn; }
 
-// Normalize a caller Fulcio root: a raw DER Buffer, or { der|rawBytes, validFor }
-// (the shape carried by a Sigstore trusted_root certificateAuthorities entry).
 function _normRoots(fulcioRoots) {
   return fulcioRoots.map(function (r, i) {
     var der = Buffer.isBuffer(r) ? r : (r && (r.der || r.rawBytes));
@@ -431,12 +358,6 @@ function _normRoots(fulcioRoots) {
   });
 }
 
-// Build the ordered path body [intermediates..., leaf] from the leaf up to (not
-// including) a cert issued by `anchor`, drawing intermediates from `intBySubject`
-// (caller certs AND bundle links -- all get cryptographically re-checked by
-// path.validate). `anchor` itself is never placed in the body. Returns null if no
-// such path exists. The terminal trust anchor is always a caller cert; a bundle
-// cert can appear only here, as a non-terminal path step.
 function _pathToAnchor(leaf, anchor, intBySubject) {
   var anchorSubj = _dn(anchor, "subject");
   var path = [leaf], cur = leaf, seen = {}, guardN = 0;
@@ -460,15 +381,10 @@ function _pathToAnchor(leaf, anchor, intBySubject) {
 async function _verifyChain(leaf, chainDers, fulcioRoots, timeMs) {
   var roots = _normRoots(fulcioRoots);
   var bundleLinks = chainDers.slice(1).map(function (d, i) { return _parseCert(d, "bundle intermediate [" + i + "]"); });
-  // Path-body intermediates: caller certs (trusted) + bundle intermediates (path
-  // steps only). The terminal anchor is chosen ONLY from the caller roots below.
   var intBySubject = {};
   function addInt(c) { (intBySubject[_dn(c, "subject")] = intBySubject[_dn(c, "subject")] || []).push(c); }
   roots.forEach(function (r) { addInt(r.cert); });
   bundleLinks.forEach(addInt);
-  // Try each caller anchor within its validity window (the trusted_root carries
-  // several CA rotations, some sharing a subject DN); accept the first that both
-  // yields a path and cryptographically validates as of the log time.
   var candidates = roots.filter(function (r) { return _inWindow(timeMs, r.validFor); });
   var lastErr = _err("sigstore/chain-incomplete", "no caller-supplied Fulcio anchor (within its validity window) issues the chain");
   for (var i = 0; i < candidates.length; i++) {
@@ -486,29 +402,18 @@ async function _verifyChain(leaf, chainDers, fulcioRoots, timeMs) {
       if (res.valid) return;
       lastErr = _err("sigstore/chain-invalid", "the Fulcio certificate chain is not valid as of the log time");
     } catch (e) {
-      // Coverage residual -- pathValidate.validate is fail-safe (builtinVerify never throws; every decodeExt wrapped), so no raw throw escapes for a well-formed path; the catch is a defensive re-type.
       lastErr = _err("sigstore/chain-invalid", "the Fulcio certificate chain failed validation: " + e.message, e);
     }
   }
   throw lastErr;
 }
 
-// ---- Fulcio identity leg -----------------------------------------------------
 
-// Decode the identity the Fulcio cert commits to: the SAN plus the Fulcio
-// extension arc (Issuer .1.8, SourceRepositoryURI .1.12, etc). `.1.8`+ values are
-// DER UTF8String; the legacy `.1.1`-`.1.6` are raw strings (never DER).
-// Derive the OIDs from the registry (never a dotted-decimal literal in source):
-// the SAN, and the Fulcio arc base (the parent of the `.7` otherName member).
 var SAN_OID = oid.byName("subjectAltName");
 var FULCIO_PREFIX = oid.byName("otherName").split(".").slice(0, -1).join(".") + ".";
 function _identity(leaf) {
   var out = { san: null, extensions: {} };
-  // The identity is security-relevant: an undecodable SAN / Fulcio member is a
-  // malformed certificate and fails closed with a named reason (never a silent
-  // drop that would hide an identity claim a caller policy relies on).
   try {
-    // Coverage residual -- x509.parse always surfaces extensions as an array.
     (leaf.extensions || []).forEach(function (ext) {
       if (ext.oid === SAN_OID) { out.san = _sanValue(ext); return; }
       if (ext.oid.indexOf(FULCIO_PREFIX) === 0) {
@@ -521,86 +426,52 @@ function _identity(leaf) {
   }
   return out;
 }
-// The SAN GeneralNames the OIDC identity is carried in: a context-tagged
-// [1] rfc822Name / [2] dNSName / [6] uniformResourceIdentifier. Return the URI
-// (a machine identity) preferentially, else the first name, with its type.
 var GN_TYPE = { 1: "rfc822Name", 2: "dNSName", 6: "uri" };
 function _sanValue(ext) {
   var seq = asn1.decode(ext.value);
   var names = [];
-  // Coverage residual -- path.validate's GeneralName gate (context-only, SEQUENCE SAN, strict otherName [0]) rejects the shapes that would trigger these fallbacks before _identity; asn1.decode guarantees a children array on any constructed node.
   for (var i = 0; i < (seq.children || []).length; i++) {
     var n = seq.children[i];
     if (n.tagClass !== "context") continue;
     var val = null;
     if (!n.constructed && GN_TYPE[n.tagNumber]) {
-      // A primitive IMPLICIT IA5String name: rfc822Name / dNSName / URI.
       val = { type: GN_TYPE[n.tagNumber], value: asn1.read.octetStringImplicit(n, n.tagNumber).toString("utf8") };
     } else if (n.constructed && n.tagNumber === 0 && (n.children || []).length >= 2) {
-      // otherName ::= SEQUENCE { type-id OID, [0] EXPLICIT value } -- Fulcio carries
-      // machine identities here (type-id .1.7, value a UTF8String).
       var inner = (n.children[1].children || [])[0] || n.children[1];
       var v;
-      // Coverage residual -- asn1.decode gives every node a (truthy) Buffer content, so the || [] fallback is unreachable; the catch itself runs for a non-string otherName inner value.
-      try { v = asn1.read.string(inner); } catch (_e) { v = Buffer.from(inner.content || []).toString("utf8"); }
+      try {
+        v = asn1.read.string(inner);
+      } catch (_e) {
+        v = null;
+      }
       val = { type: "otherName", oid: asn1.read.oid(n.children[0]), value: v };
     }
     if (val) names.push(val);
   }
-  // A Fulcio certificate binds exactly one identity; more than one SAN lets a
-  // mis-issued cert pair the expected identity with a smuggled extra one, so a
-  // caller policy that matches the wrong entry cannot be relied on -- reject.
   if (names.length > 1) throw _err("sigstore/bad-certificate", "the Fulcio certificate carries multiple SAN identities");
   return names[0] || null;
 }
 function _fulcioExtValue(ext, leafArc) {
-  // Coverage residual -- ext.value is read.octetString output, always a Buffer.
   if (!Buffer.isBuffer(ext.value)) throw _err("sigstore/bad-certificate", "Fulcio extension " + ext.oid + " has no value");
-  // The raw-vs-DER split by member (Fulcio oid-info): .1-.6 legacy are raw UTF-8
-  // strings; .8+ are DER UTF8String -- the arc is open-ended past .22. An
-  // undecodable member throws (caught by _identity) rather than dropping silently.
   if (leafArc >= 1 && leafArc <= 6) return ext.value.toString("utf8");
   return asn1.read.string(asn1.decode(ext.value));
 }
 
-// The fields an identity policy may constrain. Named once so the check, the refusal of an
-// unknown key, and the report of what ran cannot drift apart.
 var IDENTITY_FIELDS = ["san", "issuer", "sourceRepositoryURI"];
-// The guard tests membership with hasOwnProperty, so the permitted set is a lookup object --
-// an array would treat "0"/"1" as the known keys and reject every real field name.
 var IDENTITY_KEYS = { san: 1, issuer: 1, sourceRepositoryURI: 1 };
-// Every option pki.sigstore.verifyBundle reads. Adding one here is the only way to make it
-// accepted, so a capability cannot arrive with its option silently ignored at this boundary.
 var _VERIFY_BUNDLE_OPTS = { fulcioRoots: 1, rekorKeys: 1, identity: 1, predicateType: 1, time: 1 };
 
-// Returns WHICH fields were actually compared. A bundle verifies its own signature and log
-// inclusion whoever signed it -- Fulcio issues to anyone who completes an OIDC flow -- so
-// `verified: true` without an identity policy says the artifact was signed and logged, not that
-// a trusted party signed it. The caller cannot tell those apart from a bare boolean.
 function _checkIdentity(id, policy) {
   var ran = { san: false, issuer: false, sourceRepositoryURI: false };
   if (policy === undefined || policy === null) return ran;
   if (typeof policy !== "object" || Array.isArray(policy)) {
     throw _err("sigstore/bad-input", "opts.identity must be an object naming the identity fields to pin (" + IDENTITY_FIELDS.join(", ") + ")");
   }
-  // An unknown key is refused, not ignored: cosign spells this `certificateIdentity`, and a
-  // swallowed spelling checks nothing under a name the operator believes pins the signer.
-  // The guard rejects through a (code, message) FACTORY. Handing it the error CLASS raises
-  // "class constructor cannot be invoked without new" -- a raw, untyped throw escaping a public
-  // verb, on the branch a valid-input test never takes.
   guard.identifier.assertKnownKeys(policy, IDENTITY_KEYS, _err, "sigstore/bad-input", "opts.identity has an unknown key ");
-  // A policy that constrains NOTHING is a configuration mistake, and the most dangerous input on
-  // this surface: every guard below is falsy, so it accepts every signer while reading as though
-  // an identity policy is in force. Refused at the boundary rather than answered.
   var asked = IDENTITY_FIELDS.filter(function (f) { return policy[f] !== undefined; });
   if (!asked.length) {
     throw _err("sigstore/bad-input", "opts.identity constrains nothing -- name at least one of " + IDENTITY_FIELDS.join(", ") + ", or omit it to state that the signer is not being checked");
   }
-  // A named field must carry a value that can actually be compared. The comparisons below are
-  // truthiness-guarded, so an empty string or a null would be skipped while the field had been
-  // named -- reporting a signer check that never ran, which is the exact confusion this report
-  // exists to remove. Deciding "asked" and deciding "compared" must be the SAME test, so a value
-  // that cannot be compared is refused here rather than quietly becoming "not asked".
   asked.forEach(function (f) {
     if (typeof policy[f] !== "string" || policy[f] === "") {
       throw _err("sigstore/bad-input", "opts.identity." + f + " must be a non-empty string -- a value that cannot be compared would leave the signer unchecked under a policy that names it");
@@ -609,14 +480,11 @@ function _checkIdentity(id, policy) {
   });
   var sanValue = id.san && id.san.value;
   if (policy.san && sanValue !== policy.san) throw _err("sigstore/identity-mismatch", "the certificate SAN " + JSON.stringify(sanValue) + " does not match the expected identity");
-  // The OIDC issuer is carried by the current Issuer V2 (.1.8) or, on older certs,
-  // only by the deprecated raw-string issuer (.1.1); match against either.
   if (policy.issuer && policy.issuer !== id.extensions.issuer && policy.issuer !== id.extensions.issuerLegacy) throw _err("sigstore/identity-mismatch", "the certificate OIDC issuer does not match the expected issuer");
   if (policy.sourceRepositoryURI && id.extensions.sourceRepositoryURI !== policy.sourceRepositoryURI) throw _err("sigstore/identity-mismatch", "the certificate source-repository URI does not match");
   return ran;
 }
 
-// ---- in-toto Statement leg ---------------------------------------------------
 
 function _statement(payload, payloadType, expectedPredicate) {
   if (payloadType !== "application/vnd.in-toto+json") {
@@ -625,16 +493,12 @@ function _statement(payload, payloadType, expectedPredicate) {
   var st = _jsonParse(payload, "sigstore/bad-statement", "in-toto statement");
   if (!st || typeof st !== "object" || st._type !== "https://in-toto.io/Statement/v1") throw _err("sigstore/bad-statement", "the payload is not an in-toto Statement v1");
   if (!Array.isArray(st.subject) || !st.subject.length) throw _err("sigstore/bad-statement", "the in-toto statement has no subject");
-  // The verdict carries predicateType for the caller's own gate; when the caller
-  // pins one (opts.predicateType), a mismatch fails closed so a non-SLSA
-  // attestation (e.g. an SBOM) is not mistaken for the expected provenance.
   if (expectedPredicate && st.predicateType !== expectedPredicate) {
     throw _err("sigstore/predicate-mismatch", "the statement predicateType " + JSON.stringify(st.predicateType) + " does not match the expected " + JSON.stringify(expectedPredicate));
   }
   return st;
 }
 
-// ---- orchestrator ------------------------------------------------------------
 
 /**
  * @primitive pki.sigstore.verifyBundle
@@ -685,12 +549,6 @@ async function verifyBundle(bundle, opts) {
     throw new TypeError("verifyBundle: bundle must be an object, JSON string, or Buffer");
   }
   opts = opts || {};
-  // An unrecognized option is refused, not swallowed. The identity policy one level down already
-  // closes this door for exactly the reason it needs closing here too: cosign spells the signer pin
-  // `certificateIdentity`, and a swallowed spelling checks nothing under a name the operator
-  // believes pins the signer. At the top level the same slip loses the SLSA predicate pin as well,
-  // and `predicateType` has no `identityChecked`-style field, so nothing in the verdict reveals
-  // that the pin never ran.
   guard.identifier.assertKnownKeys(opts, _VERIFY_BUNDLE_OPTS, _err, "sigstore/bad-input", "pki.sigstore.verifyBundle has an unknown option ");
   var b = parseBundle(bundle);
   var vm = b.verificationMaterial;
@@ -698,7 +556,6 @@ async function verifyBundle(bundle, opts) {
   var rekorKeys = opts.rekorKeys || [];
   var fulcioRoots = opts.fulcioRoots || [];
 
-  // Leg 1 -- DSSE signature over PAE under the Fulcio leaf public key.
   var leafDer = _leafCertDer(vm);
   var leaf = _parseCert(leafDer, "Fulcio leaf certificate");
   var payload = _b64(env.payload, "dsseEnvelope.payload");
@@ -707,9 +564,6 @@ async function verifyBundle(bundle, opts) {
   var leafKey = _pubFromSpki(leaf.subjectPublicKeyInfo.bytes, "Fulcio leaf");
   if (!_rawVerify(leafKey, preimage, derSig)) throw _err("sigstore/dsse-verify-failed", "the DSSE signature does not verify under the Fulcio leaf key");
 
-  // Leg 2 -- Rekor inclusion + Rekor-signed root + entry binding (yields the
-  // trusted time). Try every transparency-log entry; accept the first that fully
-  // verifies (and binds this signature), rejecting only if none do.
   var tlogs = Array.isArray(vm.tlogEntries) ? vm.tlogEntries : [];
   if (!tlogs.length) throw _err("sigstore/bad-bundle", "a keyless bundle requires at least one transparency-log entry");
   var rekor = null, lastErr = null;
@@ -721,22 +575,15 @@ async function verifyBundle(bundle, opts) {
   if (rekor === null) throw lastErr;
   var integratedTime = rekor.integratedTime;
 
-  // Leg 3 -- Fulcio chain, validated as of the (trusted) log time; then identity.
-  // The instant comes through the time guard's intrinsic read. `getTime` is an ordinary method a
-  // subclass answers, and the slot predicate above accepts a subclass from any realm, so reading
-  // the method off the value let a caller name the moment the Fulcio chain is validated at --
-  // epoch zero, say, where every certificate in it is still unissued.
   var checkTime = guard.time.isDate(opts.time) ? guard.time.instantOf(opts.time) : C.TIME.seconds(integratedTime);
   await _verifyChain(leaf, _chainDers(vm), fulcioRoots, checkTime);
   var identity = _identity(leaf);
   var identityChecked = _checkIdentity(identity, opts.identity);
 
-  // Leg 4 -- the in-toto SLSA statement + subject binding (with an optional
-  // caller-pinned predicateType).
   var st = _statement(payload, env.payloadType, opts.predicateType);
 
   return {
-    valid: true,   // canonical toolkit-wide verdict alias, beside the verb's own `verified`
+    valid: true,
     verified: true,
     payload: payload,
     statement: st,
@@ -744,16 +591,9 @@ async function verifyBundle(bundle, opts) {
     predicateType: st.predicateType,
     predicate: st.predicate,
     identity: identity,
-    // Which identity fields were actually compared. `verified` says the artifact was signed and
-    // logged; only these say a signer the caller named was the one who signed it.
     identityChecked: identityChecked,
-    // Whether the caller pinned a predicateType (opts.predicateType) that was checked. The verdict is
-    // only reached when a pinned predicate matched (a mismatch throws sigstore/predicate-mismatch), so
-    // a caller that omitted the pin gets `false` and knows the SLSA predicate went unverified.
     predicateTypeChecked: opts.predicateType != null,
     integratedTime: integratedTime,
-    // The attested Rekor entry this verdict rests on: `logIndex` is its global log index and `logId` the
-    // log's key id (hex), so a caller can fetch or audit the exact transparency-log record.
     logIndex: rekor.logIndex,
     logId: rekor.logId,
   };

package/lib/sleep.js

@@ -1,16 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- the shared bounded poll sleeper for the stateful network clients (pki.acme.client and
-// pki.cmp.session). A delay above Node's 32-bit setTimeout ceiling is SPLIT into chained maximum-size
-// chunks: a bare setTimeout(fn, > 2^31-1) is silently clamped to 1 ms (a TimeoutOverflowWarning) and would
-// then rapidly re-poll instead of waiting the full interval. Each client's opts.sleep overrides this in
-// tests, so this default, the one sleeper that touches a real timer, is never driven by a test wait.
+// @internal
 
-var SETTIMEOUT_MAX_MS = 2147483647;   // 2^31 - 1: Node's setTimeout delay ceiling
+var SETTIMEOUT_MAX_MS = 2147483647;
 
-// sleep(ms) -> Promise resolved after `ms` milliseconds, chunking a delay past the timer ceiling.
 function sleep(ms) {
   return new Promise(function (resolve) {
     (function step(remaining) {