@blamejs/pki 0.5.7 → 0.5.9

package/lib/schema-smime.js

@@ -11,23 +11,23 @@
  * @intro
  *   S/MIME Enhanced Security Services signed-attribute values per RFC 5035 (ESS)
  *   and RFC 8551 (S/MIME 4.0). These are the DER-decoded VALUES of CMS signed
- *   attributes -- they ride inside a `SignerInfo.signedAttrs`, so this is a
- *   companion decoder a CMS consumer invokes by attribute OID, NOT a top-level
+ *   attributes: they ride inside a `SignerInfo.signedAttrs`, so this is a
+ *   companion decoder a CMS consumer invokes by attribute OID, not a top-level
  *   format the schema orchestrator auto-routes.
  *
  *   `parseSigningCertificate` / `parseSigningCertificateV2` decode the ESS
  *   signing-certificate attributes that bind a signature to the exact certificate
- *   that made it: each surfaces its list of `ESSCertID`(v2) -- the certificate hash
+ *   that made it: each surfaces its list of `ESSCertID`(v2) (the certificate hash
  *   (raw), the hash algorithm (decoded for v2, or the implied SHA-1 for v1), and
  *   the optional `issuerSerial` (issuer `GeneralNames` validated + surfaced raw,
- *   serial as a BigInt + hex) -- plus the optional certificate policies.
+ *   serial as a BigInt + hex)) plus the optional certificate policies.
  *   `parseSmimeCapabilities` decodes the ordered `SMIMECapabilities` list (each a
  *   capability OID + raw parameters). `decodeAttribute` takes a CMS-shaped
  *   `{ type, values }` attribute, enforces the single-`AttributeValue` rule
  *   (RFC 8551 sec. 2.5.2), routes on the attribute OID, and recognize-and-defers an
  *   unknown attribute type with its raw values intact.
  *
- *   Structure is decoded; verification is the consumer's -- the parser surfaces
+ *   Structure is decoded; verification is the consumer's. The parser surfaces
  *   `certHash` + `hashAlgorithm` + `issuerSerial` so a verifier recomputes the
  *   certificate hash (compose `webcrypto`) and matches the issuer/serial against
  *   the actual signing certificate; it never recomputes a hash or trusts a cert.
@@ -62,15 +62,15 @@ var OID_SIGNING_CERTIFICATE_V2 = oid.byName("signingCertificateV2");
 var OID_SMIME_CAPABILITIES = oid.byName("smimeCapabilities");
 
 // IssuerSerial ::= SEQUENCE { issuer GeneralNames, serialNumber CertificateSerialNumber }
-// (RFC 5035 App A). A bare universal SEQUENCE of exactly two fields -- distinct
+// (RFC 5035 App A). A bare universal SEQUENCE of exactly two fields, distinct
 // from the RFC 5755 attribute-certificate IssuerSerial (three fields, reached
 // IMPLICIT-tagged), so declared per-format. `issuer` composes the shared
 // GeneralNames factory (every CHOICE arm validated + surfaced raw, SIZE 1..MAX)
 // and is surfaced unchanged here: the RFC 5035 sec. 5 directoryName narrowing applies
 // only to a non-attribute (public-key) certificate reference, and an ESSCertID
 // entry may reference an attribute certificate whose issuer is a full GeneralNames.
-// The FIRST cert is known to be the signing public-key cert (RFC 5035 sec. 3), so the
-// directoryName rule is enforced there -- in the SigningCertificate build -- not here.
+// The first cert is known to be the signing public-key cert (RFC 5035 sec. 3), so the
+// directoryName rule is enforced in the SigningCertificate build and not here.
 var GENERAL_NAME_DIRECTORY = 4;
 var ISSUER_SERIAL = schema.seq([
   schema.field("issuer", pkix.generalNames(NS, { code: "smime/bad-general-names" })),
@@ -111,7 +111,7 @@ var POLICY_INFORMATION = schema.seq([
     var qualifiers = null;
     if (m.fields.policyQualifiers.present) {
       // The qualifier body stays raw (per the ESS scope), but the RFC 5280
-      // sec. 4.2.1.4 structure is validated fail-closed by the shared assertion -- the
+      // sec. 4.2.1.4 structure is validated fail-closed by the shared assertion, the
       // same PolicyInformation shape the certificatePolicies decoder enforces.
       var q = m.fields.policyQualifiers.node;
       pkix.assertPolicyQualifiers(q, function (msg, cause) { throw ctx.E("smime/bad-policy-information", msg, cause); });
@@ -132,8 +132,8 @@ var POLICIES = schema.seqOf(POLICY_INFORMATION, {
 });
 
 // ESSCertID ::= SEQUENCE { certHash Hash, issuerSerial IssuerSerial OPTIONAL }
-// (RFC 5035 sec. 5.4.2). Hash ::= OCTET STRING -- for v1 it is the SHA-1 hash of the
-// whole certificate with NO algorithm field, so the hash algorithm is SYNTHESIZED
+// (RFC 5035 sec. 5.4.2). Hash ::= OCTET STRING; for v1 it is the SHA-1 hash of the
+// whole certificate with no algorithm field, so the hash algorithm is synthesized
 // as the implied SHA-1 to make v1 shape-compatible with v2 for a verifier.
 var ESS_CERT_ID = schema.seq([
   schema.field("certHash", schema.octetString()),
@@ -169,7 +169,7 @@ var ESS_CERT_ID_V2 = schema.seq([
       // to it is a non-canonical DEFAULT and is rejected fail-closed (the
       // structured-value analogue of the primitive-DEFAULT rejection the toolkit
       // already enforces). A present hashAlgorithm carrying a redundant NULL
-      // parameters is NOT byte-equal to the params-absent default and decodes.
+      // parameters is not byte-equal to the params-absent default and decodes.
       if (alg.oid === OID_SHA256 && alg.parameters === null) {
         throw ctx.E("smime/non-canonical-default",
           "ESSCertIDv2 hashAlgorithm equal to the DEFAULT {algorithm id-sha256} MUST be omitted (X.690 sec. 11.5)");
@@ -188,8 +188,8 @@ var ESS_CERT_ID_V2 = schema.seq([
 
 // SigningCertificate ::= SEQUENCE { certs SEQUENCE OF ESSCertID,
 //   policies SEQUENCE OF PolicyInformation OPTIONAL } (RFC 5035 sec. 5.4.2). certs is
-// order-preserving -- RFC 5035 sec. 3 makes the FIRST element the signing certificate
-// -- and non-empty (an empty certs cannot name a signing cert).
+// order-preserving (RFC 5035 sec. 3 makes the first element the signing certificate)
+// and non-empty (an empty certs cannot name a signing cert).
 function signingCertificateSchema(essCertId, code, what) {
   return schema.seq([
     schema.field("certs", schema.seqOf(essCertId, { assert: "sequence", min: 1, code: "smime/bad-certs", what: "certs" })),
@@ -226,7 +226,7 @@ var SMIME_CAPABILITY = schema.seq([
     };
   },
 });
-// SMIMECapabilities ::= SEQUENCE OF SMIMECapability -- ordered by preference
+// SMIMECapabilities ::= SEQUENCE OF SMIMECapability, ordered by preference
 // (RFC 8551 sec. 2.5.2), never sorted; an empty list is legal.
 var SMIME_CAPABILITIES = schema.seqOf(SMIME_CAPABILITY, {
   assert: "sequence", min: 0, code: "smime/bad-capabilities", what: "SMIMECapabilities",
@@ -241,7 +241,7 @@ var SMIME_CAPABILITIES = schema.seqOf(SMIME_CAPABILITY, {
  * @spec       RFC 5035, RFC 2634
  * @related    pki.schema.smime.parseSigningCertificateV2, pki.schema.smime.decodeAttribute
  *
- * Decode an ESS v1 `SigningCertificate` attribute value (RFC 5035 sec. 5.4.2) -- the
+ * Decode an ESS v1 `SigningCertificate` attribute value (RFC 5035 sec. 5.4.2): the
  * raw `AttributeValue` a CMS consumer plucks off `SignerInfo.signedAttrs`. Returns
  * `{ certs, policies }`: each `certs` entry is `{ certHash, hashAlgorithm,
  * issuerSerial }` in wire order (the first is the signing certificate), where
@@ -291,7 +291,7 @@ var parseSigningCertificateV2 = pkix.makeParser({ pemLabel: null, PemError: PemE
  * @related    pki.schema.smime.decodeAttribute
  *
  * Decode an `SMIMECapabilities` attribute value (RFC 8551 sec. 2.5.2) into
- * `{ capabilities }` -- an ORDERED list (preference order, never sorted), each
+ * `{ capabilities }`, an ordered list (preference order, never sorted), each
  * `{ capabilityID, name, parameters }` with `parameters` the raw
  * `ANY DEFINED BY capabilityID` bytes (or `null`). Throws a typed `smime/*` error
  * on malformed input.
@@ -315,8 +315,8 @@ var parseSmimeCapabilities = pkix.makeParser({ pemLabel: null, PemError: PemErro
  * OID-dispatch convenience over the three value decoders for a CMS-shaped
  * `{ type, values }` attribute (the shape `cms.parse` surfaces on
  * `signerInfos[i].signedAttrs`). Enforces the single-`AttributeValue` rule
- * (RFC 8551 sec. 2.5.2 / sec. 2.5) -- a `values` length other than 1 is rejected
- * `smime/multi-valued-attribute` -- then routes on `attr.type`:
+ * (RFC 8551 sec. 2.5.2 / sec. 2.5), so a `values` length other than 1 is rejected
+ * `smime/multi-valued-attribute`, then routes on `attr.type`:
  * `signingCertificate` / `signingCertificateV2` / `smimeCapabilities` decode to
  * `{ kind, ...result }`; any other type is recognize-and-deferred
  * `smime/unsupported-attribute` (its `type`, registry `name`, and raw `values`

package/lib/schema-tsp.js

@@ -28,7 +28,7 @@
  *   verification-layer concerns above parse altitude. DER-only, fail-closed.
  *
  * @card
- *   Parse DER / PEM RFC 3161 timestamp responses and tokens -- per-response status,
+ *   Parse DER / PEM RFC 3161 timestamp responses and tokens: per-response status,
  *   the TSTInfo payload (imprint, genTime, serial, nonce, accuracy), raw verifier
  *   inputs, single-signer token composition over CMS, fail-closed.
  */
@@ -48,7 +48,7 @@ var NS = pkix.makeNS("tsp", TspError, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var EXTENSION = pkix.extension(NS);
 
-// TSTInfo.version is INTEGER { v1(1) } -- the only legal value is 1.
+// TSTInfo.version is INTEGER { v1(1) }; the only legal value is 1.
 var VERSION = pkix.versionReader(NS, { "1": 1 });
 
 // id-ct-TSTInfo is the eContentType that identifies a timestamp token (RFC 3161
@@ -77,7 +77,7 @@ var FAILURE_BITS = {
 // RFC 3161 genTime may carry sub-second precision (X.690 sec. 11.7 fractional profile).
 var GEN_TIME = pkix.generalizedTime(NS, { code: "tsp/bad-gentime", message: "genTime must be a GeneralizedTime (RFC 3161 sec. 2.4.2)", allowFractional: true });
 
-// tsa [0] EXPLICIT GeneralName (RFC 3161 sec. 2.4.2) -- validated + surfaced raw via the
+// tsa [0] EXPLICIT GeneralName (RFC 3161 sec. 2.4.2), validated and surfaced raw via the
 // shared pkix.generalName primitive (RFC 5280 sec. 4.2.1.6), which checks the chosen
 // alternative's form and content so a malformed GeneralName fails closed.
 var GENERAL_NAME_RAW = pkix.generalName(NS, { code: "tsp/bad-tsa" });
@@ -88,7 +88,7 @@ var UTF8_TEXT = pkix.utf8Text(NS, { code: "tsp/bad-status-info", message: "PKIFr
 // ---- MessageImprint --------------------------------------------------
 
 // MessageImprint ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, hashedMessage
-// OCTET STRING } (RFC 3161 sec. 2.4.1). hashedMessage is a digest -- surfaced RAW.
+// OCTET STRING } (RFC 3161 sec. 2.4.1). hashedMessage is a digest, surfaced raw.
 var MESSAGE_IMPRINT = schema.seq([
   schema.field("hashAlgorithm", ALGORITHM_IDENTIFIER),
   schema.field("hashedMessage", schema.octetString()),
@@ -224,9 +224,9 @@ function _assertMinimalNamedBits(unusedBits, bytes) {
 }
 
 // Decode the set NamedBitList bits to their RFC 3161 names (bit 0 = MSB of byte 0).
-// A set bit outside the defined set is an unsupported PKIFailureInfo value -- a client
+// A set bit outside the defined set is an unsupported PKIFailureInfo value, and a client
 // MUST error on a failInfo it does not understand (RFC 3161 sec. 2.4.2), so reject it
-// rather than surfacing an opaque "bitN".
+// instead of surfacing an opaque "bitN".
 function _namedBits(bytes) {
   var out = [];
   for (var i = 0; i < bytes.length * 8; i++) {
@@ -257,11 +257,11 @@ var TIME_STAMP_RESP = schema.seq([
     var granted = status.status === 0 || status.status === 1;
     if (granted && !present) throw NS.E("tsp/missing-token", "a granted TimeStampResp must carry a timeStampToken (RFC 3161 sec. 2.4.2)");
     if (!granted && present) throw NS.E("tsp/unexpected-token", "a non-granted TimeStampResp must not carry a timeStampToken (RFC 3161 sec. 2.4.2)");
-    // failInfo is the reason a request was rejected, so it is present ONLY when the
-    // status is rejection(2) -- not on granted(0/1) nor on waiting / revocation* (3/4/5).
+    // failInfo is the reason a request was rejected, so it is present only when the
+    // status is rejection(2), never on granted(0/1) nor on waiting / revocation* (3/4/5).
     if (status.status !== 2 && status.failInfo) throw NS.E("tsp/unexpected-failinfo", "failInfo is present only when the status is rejection(2) (RFC 3161 sec. 2.4.2)");
-    // A granted response's timeStampToken MUST be a well-formed TimeStampToken --
-    // decode it (composing the CMS parser) rather than surfacing arbitrary SEQUENCE
+    // A granted response's timeStampToken MUST be a well-formed TimeStampToken, so
+    // decode it (composing the CMS parser) instead of surfacing arbitrary SEQUENCE
     // bytes as a token; a malformed token fails the response parse.
     return {
       status: status.status,
@@ -407,9 +407,9 @@ var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: Ts
  * attached (`tsp/detached-token`), the single-signer rule (`tsp/multi-signer`,
  * RFC 3161 sec. 2.4.2), and that the signerInfo carries a SigningCertificate or
  * SigningCertificateV2 signed attribute (`tsp/missing-signing-certificate`,
- * RFC 3161 sec. 2.4.2 / RFC 5816 -- the hash-vs-certificate binding stays a
+ * RFC 3161 sec. 2.4.2 / RFC 5816; the hash-vs-certificate binding stays a
  * verification-layer concern), then decodes the inner `TSTInfo`. Returns
- * `{ tstInfo, eContent, signerInfo, certificates }` -- the decoded payload, the raw
+ * `{ tstInfo, eContent, signerInfo, certificates }`: the decoded payload, the raw
  * eContent bytes a verifier hashes for the CMS message-digest, and the CMS signer
  * material.
  *

package/lib/schema-x509.js

@@ -20,9 +20,9 @@
  *   is named where the registry knows it.
  *
  *   The raw `tbsCertificate` bytes are returned alongside the parsed
- *   fields so a signature-verification layer can hash exactly the bytes
- *   that were signed rather than re-encoding and hoping for round-trip
- *   fidelity.
+ *   fields. A signature-verification layer hashes exactly the bytes that
+ *   were signed, with no re-encoding step whose round-trip fidelity it
+ *   would have to trust.
  *
  * @card
  *   Parse DER / PEM X.509 certificates into structured, validated fields

package/lib/shbs.js

@@ -7,14 +7,14 @@
  * @title      Stateful hash-based
  * @intro Stateful hash-based signature VERIFICATION -- HSS/LMS (RFC 8554),
  *   carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST
- *   SP 800-208. VERIFY ONLY, by deliberate design: stateful hash-based SIGNING
- *   is catastrophic to get wrong -- each one-time key must be used exactly once,
+ *   SP 800-208. Verify only, by deliberate design: stateful hash-based signing
+ *   is catastrophic to get wrong. Each one-time key must be used exactly once,
  *   so the private key embeds a monotonic index whose state must advance and
  *   persist atomically across every signature and every process restart. A single
  *   index reuse (a restored VM snapshot, a crashed writer, a concurrent signer)
  *   forfeits security and can leak enough one-time-key material to forge, which is
  *   why SP 800-208 sec. 8 constrains signing-state handling to hardware. So this
- *   module NEVER mints a signature -- it verifies signatures produced in an HSM
+ *   module never mints a signature; it verifies signatures produced in an HSM
  *   elsewhere. Verification is pure public-input SHA-256 / SHAKE256 hashing
  *   (no secret, no side-channel surface), so a pure-JavaScript verifier is safe.
  * @spec RFC 8554, RFC 9802, RFC 9708, NIST SP 800-208
@@ -104,8 +104,8 @@ function _hash(family, n, parts) {
 }
 
 // ---- bounded big-endian reader (bounds-before-slice; the ct.js TlsReader model
-// for a non-DER positional wire, kept shbs-local -- shbs needs u32 typecodes +
-// fixed-n reads, not CT's length-prefixed vector helpers) --------------------
+// for a non-DER positional wire, kept shbs-local because shbs needs u32 typecodes
+// and fixed-n reads, not CT's length-prefixed vector helpers) ----------------
 
 function Reader(buf, code, label) { this.buf = buf; this.pos = 0; this.code = code; this.label = label; }
 Reader.prototype._need = function (k) {
@@ -177,7 +177,7 @@ function _lmsVerify(pubBytes, message, sigBytes) {
   var T1 = pr.take(m);
 
   // -- signature (RFC 8554 Algorithm 6a). q first, then the LM-OTS signature,
-  //    then the LMS typecode (AFTER the LM-OTS sig), then the auth path. --
+  //    then the LMS typecode (after the LM-OTS sig), then the auth path. --
   if (sigBytes.length < 8) throw _err("shbs/bad-signature", "LMS signature is shorter than 8 bytes");
   var sr = new Reader(sigBytes, "shbs/bad-signature", "LMS signature");
   var q = sr.u32();
@@ -185,14 +185,14 @@ function _lmsVerify(pubBytes, message, sigBytes) {
   // The public key -- never the attacker-controlled signature -- is the authority
   // (downgrade defense): a signature whose OTS typecode does not equal the one the
   // public key commits to cannot verify against it. RFC 8554 Algorithm 6a checks
-  // the typecode (step 2c, and 2g for the LMS type below) BEFORE the length (steps
-  // 2d / 2i), and returns INVALID -- a verification FAILURE (false), not a
-  // structural error. So a mismatch is `false` at this point EVEN for a blob too
+  // the typecode (step 2c, and 2g for the LMS type below) before the length (steps
+  // 2d / 2i), and returns INVALID, a verification failure (false) and not a
+  // structural error. So a mismatch is `false` at this point even for a blob too
   // short to be a complete signature: the mismatch is decidable once q + typecode
   // are read (the bounded reader already threw if those 8 bytes are absent). A
   // matching typecode with a truncated body still throws below (bounds-before-
-  // slice). Re-sizing the body by the signature's own mismatched typecode -- to
-  // "fully validate before returning false" -- would violate this order and reject
+  // slice). Re-sizing the body by the signature's own mismatched typecode, so as to
+  // "fully validate before returning false", would violate this order and reject
   // a legitimate typecode-mutation test vector as malformed instead of INVALID.
   if (otsSigType !== otsSet.code) return false;
   var n = otsSet.n, p = otsSet.p;
@@ -204,10 +204,10 @@ function _lmsVerify(pubBytes, message, sigBytes) {
   var path = [];
   for (var pi = 0; pi < h; pi++) path.push(sr.take(m));
   if (!sr.atEnd()) throw _err("shbs/bad-signature", "LMS signature has " + sr.remaining() + " trailing byte(s)");
-  // RFC 8554 Algorithm 6a step 2i: a leaf index q >= 2^h is INVALID -- a
-  // verification FAILURE (false), NOT a structural error. Checked here, AFTER the
-  // exact-length validation above (a truncated / trailing blob already threw
-  // typed), against the REGISTRY height, never the blob. 2^h fits Number (h<=25).
+  // RFC 8554 Algorithm 6a step 2i: a leaf index q >= 2^h is INVALID, a
+  // verification failure (false) and not a structural error. Checked here, after
+  // the exact-length validation above (a truncated or trailing blob already threw
+  // typed), against the registry height and never the blob. 2^h fits Number (h<=25).
   if (q >= Math.pow(2, h)) return false;
 
   // -- recompute the LM-OTS public-key candidate, then fold the Merkle path --
@@ -272,7 +272,7 @@ function _hssVerify(pubBytes, message, sigBytes) {
 
   var sr = new Reader(sigBytes, "shbs/bad-signature", "HSS signature");
   var Nspk = sr.u32();
-  // The level-count gate, checked BEFORE parsing any component (RFC 8554 sec. 6.3).
+  // The level-count gate, checked before parsing any component (RFC 8554 sec. 6.3).
   if (Nspk + 1 !== L) throw _err("shbs/bad-signature", "HSS Nspk+1 (" + (Nspk + 1) + ") does not equal the public-key level count L (" + L + ")");
 
   var key = topKey;
@@ -312,7 +312,7 @@ function _asBytes(x, label) { return guard.bytes.source(x, ShbsError, "shbs/bad-
  * Returns true for a valid signature, false for a well-formed signature that does
  * not verify; a malformed blob (bad length, unknown or unapproved typecode,
  * truncation, a typecode disagreeing between the key and the signature) throws a
- * typed `ShbsError`. VERIFY ONLY -- this module never signs.
+ * typed `ShbsError`. Verification only: this module never signs.
  *
  * @example
  *   // throws: shbs/bad-public-key -- an Ed25519 key is not an HSS public key, and
@@ -337,7 +337,7 @@ function verify(publicKey, message, signature) {
  * @spec RFC 8554 sec. 5
  * @related pki.shbs.verify
  *
- * Verify a single-tree LMS (Leighton-Micali Signature) over `message` -- the
+ * Verify a single-tree LMS (Leighton-Micali Signature) over `message`: the
  * component an HSS hierarchy composes at each level, and a standalone algorithm
  * in its own right. Same verdict contract as `pki.shbs.verify`: true / false for
  * a well-formed signature, a typed `ShbsError` for a malformed blob.

package/lib/sign-scheme.js

@@ -4,10 +4,10 @@
 //
 // @internal -- no operator-facing namespace. The signature-scheme resolver + signer shared by
 // every producer that signs a raw preimage with a certificate's key: pki.cms.sign (SignerInfo),
-// pki.ocsp.sign (BasicOCSPResponse), and future X.509 / CRL issuance. It owns the ONE key ->
+// pki.ocsp.sign (BasicOCSPResponse), and future X.509 / CRL issuance. It owns the single key ->
 // { signatureAlgorithm, WebCrypto import/sign params } dispatch across the whole algorithm set
 // (RSA-PKCS1 / RSA-PSS / ECDSA P-256/384/521 / Ed25519 / Ed448 / ML-DSA / SLH-DSA / composite
-// ML-DSA), so a new signer surface inherits the full registry -- PQC included -- instead of
+// ML-DSA), so a new signer surface inherits the full registry, PQC included, instead of
 // re-deriving a partial, drifting copy (Hard rule #2: registry not switch; and no second signer).
 //
 // Error-parameterized like the guard / validator families: the caller passes its typed error
@@ -31,8 +31,8 @@ var HASH = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", shake128: "shake128", shake256: "shake256" };
 var PSS_SALT = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };
 var ECDSA_ALG = { sha256: "ecdsaWithSHA256", sha384: "ecdsaWithSHA384", sha512: "ecdsaWithSHA512" };
-// RSA-PKCS1 signatures fold the digest into a combined signature OID when there is NO separate
-// digestAlgorithm field to carry it (X.509 / CRL / OCSP -- RFC 5280 sec. 4.1.1.2, RFC 6960). CMS
+// RSA-PKCS1 signatures fold the digest into a combined signature OID when there is no separate
+// digestAlgorithm field to carry it (X.509 / CRL / OCSP; RFC 5280 sec. 4.1.1.2, RFC 6960). CMS
 // SignerInfo has that field, so it signs under the bare rsaEncryption key OID instead.
 var RSA_PKCS1_SIG = { sha256: "sha256WithRSAEncryption", sha384: "sha384WithRSAEncryption", sha512: "sha512WithRSAEncryption" };
 var HASH_NAME_BY_OID = {};
@@ -115,8 +115,8 @@ function _pssHashFromSpki(cert, E) {
 function pssSpkiPinnedHash(cert, E) {
   var d = _pssHashFromSpki(cert, E);
   if (!d) return null;
-  // A pin this toolkit has no WebCrypto hash for -- SHA-1, which RSASSA-PSS-params names by DEFAULT
-  // -- is still a pin. Returning undefined here would hand the caller a falsy value it reads as
+  // A pin this toolkit has no WebCrypto hash for (SHA-1, which RSASSA-PSS-params names by DEFAULT)
+  // is still a pin. Returning undefined here would hand the caller a falsy value it reads as
   // "unrestricted", which is the same fail-open the DEFAULT reading above exists to close, one
   // layer up.
   if (!HASH[d]) throw E("unsupported-algorithm", "the id-RSASSA-PSS key is restricted to " + d + ", which this toolkit does not verify with");
@@ -124,7 +124,7 @@ function pssSpkiPinnedHash(cert, E) {
 }
 
 // resolveSignScheme(cert, so, noSignedAttrs, E) -> the signature scheme from the signer cert's
-// public-key algorithm + per-signer opts (so.digestAlgorithm / so.pss / so.combinedRsaSig -- the
+// public-key algorithm + per-signer opts (so.digestAlgorithm / so.pss / so.combinedRsaSig, the
 // last folds the digest into a combined RSA signature OID for a caller with no digestAlgorithm
 // field). Returns
 // { composite?, digest, digestAlgId, sigAlgId, imp?, sign?, ecdsaDer?, coordLen? }. `digest`/
@@ -188,14 +188,14 @@ function resolveSignScheme(cert, so, noSignedAttrs, E) {
 // A CryptoKey's algorithm must match the resolved scheme (name / hash / curve).
 function _assertKeyMatchesScheme(key, imp, E) {
   var ka = key.algorithm || {};
-  // WebCrypto algorithm names are ASCII-case-insensitive (RSASSA-PKCS1-v1_5 == RSASSA-PKCS1-V1_5 is the SAME
-  // algorithm), so compare case-folded -- a genuine mismatch (e.g. RSASSA-PKCS1-v1_5 vs ECDSA) still fails.
+  // WebCrypto algorithm names are ASCII-case-insensitive (RSASSA-PKCS1-v1_5 and RSASSA-PKCS1-V1_5 are one
+  // algorithm), so compare case-folded; a genuine mismatch (e.g. RSASSA-PKCS1-v1_5 vs ECDSA) still fails.
   if (String(ka.name).toUpperCase() !== String(imp.name).toUpperCase()) throw E("bad-input", "the signer CryptoKey algorithm (" + ka.name + ") does not match the certificate's key algorithm (" + imp.name + ")");
   if (imp.hash && (!ka.hash || ka.hash.name !== imp.hash)) throw E("bad-input", "the signer CryptoKey hash (" + (ka.hash && ka.hash.name) + ") does not match the signing digest (" + imp.hash + ")");
   if (imp.namedCurve && ka.namedCurve !== imp.namedCurve) throw E("bad-input", "the signer CryptoKey curve (" + ka.namedCurve + ") does not match the certificate curve (" + imp.namedCurve + ")");
 }
 function _normPkcs8(k, label, E) {
-  // A caller's own Buffer is BORROWED, not copied -- the same rule _importKey states below. Every
+  // A caller's own Buffer is borrowed, not copied, the same rule _importKey states below. Every
   // other form is copied, and neither copy is duplicated further, so a private key never gains a
   // plaintext duplicate this module cannot account for.
   if (Buffer.isBuffer(k)) return guard.bytes.view(k, E, "bad-input", label);
@@ -217,8 +217,8 @@ function _importKey(key, imp, E) {
     // signs with. One whose material this process cannot reach is refused with that as the reason.
     return webcrypto.adoptKey(key, imp, ["sign"], E, "bad-input");
   }
-  // A Uint8Array is copied here and a PEM string is decoded here, so both leave a SECOND copy of a
-  // private key that nothing else can reach -- wiped once the engine has imported it, which is the
+  // A Uint8Array is copied here and a PEM string is decoded here, so both leave a second copy of a
+  // private key that nothing else can reach, wiped once the engine has imported it, which is the
   // only thing that reads it. A caller's own Buffer is passed through untouched: they hold a live
   // reference and will use it again, so clearing it would destroy their key.
   var der, owned = false;
@@ -243,7 +243,7 @@ function _importKey(key, imp, E) {
 
 // signOverTbs(scheme, key, signedBytes, E) -> Promise<Buffer> the raw signature over signedBytes.
 // The classical path imports the key + signs (re-encoding ECDSA to canonical DER); the composite
-// path signs BOTH component keys and returns mldsaSig || tradSig (composite-sig.js owns it).
+// path signs both component keys and returns mldsaSig || tradSig (composite-sig.js owns it).
 function signOverTbs(scheme, key, signedBytes, E) {
   if (scheme.composite) {
     return compositeSig.compositeSign(scheme.composite, _normCompositeKeys(key, scheme.composite, E), signedBytes).then(function (sig) { return Buffer.from(sig); });

package/lib/sigstore.js

@@ -5,7 +5,7 @@
  * @module pki.sigstore
  * @nav        Supply chain
  * @title      Sigstore
- * @intro Zero-dependency verifier for a Sigstore bundle -- the exact artifact
+ * @intro Zero-dependency verifier for a Sigstore bundle, the exact artifact
  *   `npm publish --provenance` produces and the npm registry serves at its
  *   attestations API. A bundle is a keyless (Fulcio) signature over a DSSE-wrapped
  *   in-toto SLSA provenance attestation, with a Rekor transparency-log inclusion
@@ -114,7 +114,7 @@ function _b64(s, label) {
  * Buffer) fail-closed: a non-object, malformed JSON, an oversize input, an
  * unknown `mediaType`, or a missing required member throws a typed
  * `sigstore/bad-bundle` / `sigstore/bad-bundle-version`. Returns the validated
- * bundle object (structure only -- no cryptographic verification).
+ * bundle object (structure only, no cryptographic verification).
  *
  * @example
  *   // requires: `bundle` -- a Sigstore bundle as cosign or npm provenance emits it
@@ -604,18 +604,17 @@ function _statement(payload, payloadType, expectedPredicate) {
  * the log entry bound to this exact signature; and the in-toto SLSA statement.
  * Any leg failing throws a typed `sigstore/*` error. On success returns
  * `{ verified: true, payload, statement, subjects, predicateType, predicate,
- * identity, identityChecked, integratedTime }` -- `payload` is the RAW verified
+ * identity, identityChecked, integratedTime }`. `payload` is the raw verified
  * envelope bytes (never a re-serialization), and the caller confirms a
  * `subjects[].digest` matches the published artifact.
  *
- * `verified: true` says the artifact was signed and logged -- not that a party you
- * trust signed it. Fulcio issues a certificate to anyone who completes an OIDC
- * flow, so WHO signed is decided only by `opts.identity`, and `identityChecked`
- * reports which of its fields were compared (`{ san, issuer, sourceRepositoryURI }`,
- * each a boolean). An `identity` naming none of them is refused rather than
- * satisfied, since it would accept every signer while reading as a policy; so is an
- * unrecognized field name, which would otherwise pin nothing under a spelling the
- * operator believes constrains the signer.
+ * `verified: true` says the artifact was signed and logged; it says nothing about
+ * who. Fulcio issues a certificate to anyone who completes an OIDC flow, so who
+ * signed is decided only by `opts.identity`, and `identityChecked` reports which of
+ * its fields were compared (`{ san, issuer, sourceRepositoryURI }`, each a boolean).
+ * An `identity` naming none of them is refused, since it would accept every signer
+ * while reading as a policy; so is an unrecognized field name, which would otherwise
+ * pin nothing under a spelling the operator believes constrains the signer.
  *
  * @opts
  *   fulcioRoots:   Array,      // the Fulcio CA anchors: a DER Buffer or { der, validFor } each

package/lib/sleep.js

@@ -6,7 +6,7 @@
 // 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 ONLY sleeper that touches a real timer -- is never driven by a test wait.
+// tests, so this default, the one sleeper that touches a real timer, is never driven by a test wait.
 
 var SETTIMEOUT_MAX_MS = 2147483647;   // 2^31 - 1: Node's setTimeout delay ceiling