@blamejs/pki 0.5.6 → 0.5.8

package/lib/crl-sign.js

@@ -19,8 +19,8 @@
 // The signature matrix comes from the shared sign-scheme resolver (the same registry pki.x509.sign /
 // pki.cms.sign drive), so a new algorithm is a registry row, never a branch here. The TBSCertList DER is
 // assembled through the canonical asn1.build.* layer + the shared pki-build producing primitives; the
-// strict schema-crl decoder round-trips it and OpenSSL cross-checks it. VERIFY composes the ONE
-// path-validate.verifyCrlSignature engine pki.path.crlChecker uses -- there is no second, weaker verifier.
+// strict schema-crl decoder round-trips it and OpenSSL cross-checks it. Verify composes the single
+// path-validate.verifyCrlSignature engine pki.path.crlChecker uses; there is no second, weaker verifier.
 
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
@@ -51,7 +51,7 @@ function _signE(kind, message, cause) { return new CrlError("crl/" + kind, messa
 function O(n) { return oid.byName(n); }
 
 // The shared PKIX producing primitives (lib/pki-build.js), bound to the crl namespace so they keep the
-// frozen crl/* codes (Hard rule #5 -- one encode definition, no per-format hand-roll).
+// frozen crl/* codes (Hard rule #5: one encode definition, no per-format hand-roll).
 var _b = pkiBuild.makeBuilder({ ErrorClass: CrlError, prefix: "crl", O: O, NS: NS, NAME_SCHEMA: NAME_SCHEMA, SPKI_SCHEMA: SPKI_SCHEMA, EXT_DECODERS: {} });
 var _encodeName = _b.encodeName, _isEmptyName = _b.isEmptyName, _reqDer = _b.reqDer,
   _assertValidSpki = _b.assertValidSpki, _assertValidExtension = _b.assertValidExtension,
@@ -88,16 +88,16 @@ var REQUIRED_ENTRY_CRITICALITY = {};
 
 // certificateIssuer (indirect CRLs) is deferred: pki.path.crlChecker skips a CRL carrying any critical entry
 // extension other than reasonCode (it does not track the per-entry issuer of an indirect CRL), so a CRL
-// signed with certificateIssuer would verify but never be authoritative for revocation. Reject it -- on both
-// the object form and the pre-encoded hatch -- until the checker processes indirect CRLs.
+// signed with certificateIssuer would verify but never be authoritative for revocation. Reject it, on both
+// the object form and the pre-encoded hatch, until the checker processes indirect CRLs.
 var _CERT_ISSUER_DEFERRED = "certificateIssuer (indirect CRLs) is not yet supported -- pki.path.crlChecker skips a CRL carrying any critical entry extension other than reasonCode, so an indirect CRL would never be authoritative for revocation. Re-enabled once the checker processes certificateIssuer / indirect CRLs.";
-// The IDP indirectCRL flag marks the whole CRL as indirect, which crlChecker skips outright -- deferred for
+// The IDP indirectCRL flag marks the whole CRL as indirect, which crlChecker skips outright. Deferred for
 // the same reason as certificateIssuer, on both the object form and the pre-encoded hatch.
 var _INDIRECT_IDP_DEFERRED = "issuingDistributionPoint indirectCRL (indirect CRLs) is not yet supported -- pki.path.crlChecker skips a CRL whose IDP marks it indirect, so it would never be authoritative for revocation. Re-enabled once the checker processes indirect CRLs.";
 
 // ---- shared numeric / reason / key-id helpers ------------------------------
 
-// A non-negative INTEGER (0..MAX) of at most 20 content octets -- cRLNumber (sec. 5.2.3) and
+// A non-negative INTEGER (0..MAX) of at most 20 content octets: cRLNumber (sec. 5.2.3) and
 // deltaCRLIndicator baseCRLNumber (sec. 5.2.4). b.integer has no size cap of its own (unlike serialInteger).
 function _boundedInteger(v, label) {
   var n;
@@ -113,7 +113,7 @@ function _boundedInteger(v, label) {
 }
 
 // Decode a pre-encoded Extension's extnValue (the trailing OCTET STRING's content) to one well-formed DER
-// node, or reject -- so a recognized extension's value is validated on the escape hatch, not emitted opaque.
+// node, or reject, so a recognized extension's value is validated on the escape hatch, not emitted opaque.
 function _extInner(node, label) {
   try { return asn1.decode(asn1.read.octetString(node.children[node.children.length - 1])); }
   catch (e) { throw _err("crl/bad-input", "pre-encoded " + label + " extension value is not valid DER", e); }
@@ -144,7 +144,7 @@ function _resolveReason(reason, isDelta) {
 // The AKI keyIdentifier from the issuer: an explicit Buffer, or true -> the issuer cert's subjectKeyIdentifier,
 // else the SHA-1 of the issuer SPKI (RFC 5280 sec. 5.2.1 key-identifier method).
 function _akiKeyId(val, ctx) {
-  if (Buffer.isBuffer(val)) return val;
+  if (Buffer.isBuffer(val)) return guard.bytes.snapshot(val, CrlError, "crl/bad-input", "the authorityKeyIdentifier keyIdentifier");
   if (val === true) {
     if (ctx.issuerCert) {
       var ski = (ctx.issuerCert.extensions || []).filter(function (e) { return e.oid === OID_SKI; })[0];
@@ -193,7 +193,7 @@ function _validatePreEncodedIdp(inner) {
   if (!inner.children || !inner.children.length) throw _err("crl/bad-idp", "pre-encoded issuingDistributionPoint MUST NOT be empty (RFC 5280 sec. 5.2.5)");
   var f = schema.walk(_PRE_ENCODED_IDP_SCHEMA, inner, NS).fields;
   // A present DEFAULT-FALSE flag encodes a default DER omits (X.690 sec. 11.5), so it is rejected
-  // whichever value it carries rather than counted as the FALSE it spells.
+  // whichever value it carries, never counted as the FALSE it spells.
   ["onlyContainsUserCerts", "onlyContainsCACerts", "onlyContainsAttributeCerts"].forEach(function (name) {
     if (f[name].present && f[name].value !== true) throw _err("crl/bad-idp", "pre-encoded issuingDistributionPoint " + name + " encodes its DEFAULT FALSE, which DER omits (X.690 sec. 11.5)");
   });
@@ -305,7 +305,7 @@ function _buildCrlExtensions(spec, ctx) {
 
 // The revokedCertificates entries (sec. 5.1.2.6 / 5.3). Each entry: serial + revocationDate + optional
 // crlEntryExtensions (reasonCode ENUMERATED, invalidityDate GeneralizedTime-only, certificateIssuer, or a
-// pre-encoded escape hatch). Returns { entries, anyExt } -- anyExt forces v2 (sec. 5.1.2.1).
+// pre-encoded escape hatch). Returns { entries, anyExt }, where anyExt forces v2 (sec. 5.1.2.1).
 function _buildRevoked(entryList, isDelta) {
   if (!Array.isArray(entryList)) throw _err("crl/bad-input", "revoked must be an array of revoked-certificate entries");
   var anyExt = false, seenSerials = {};
@@ -332,7 +332,7 @@ function _buildRevoked(entryList, isDelta) {
     }
     if (e.invalidityDate != null) {
       guard.time.assertValid(e.invalidityDate, _err, "crl/bad-input", "invalidityDate");
-      // sec. 5.3.2 -- ALWAYS GeneralizedTime (never the UTCTime cutover), no fractional seconds.
+      // sec. 5.3.2: always GeneralizedTime (never the UTCTime cutover), no fractional seconds.
       pushE("invalidityDate", false, b.generalizedTime(e.invalidityDate));
     }
     if (e.certificateIssuer != null) throw _err("crl/bad-input", _CERT_ISSUER_DEFERRED);
@@ -482,15 +482,15 @@ function _sign(spec, issuer, opts) {
  *
  * The version is derived from the field set (v2 when any CRL or entry extension is present, else v1). The
  * outer `signatureAlgorithm` is emitted from the same source as `tbsCertList.signature` (sec. 5.1.1.2); an
- * empty revocation list omits `revokedCertificates` rather than emitting an empty SEQUENCE (sec. 5.1.2.6);
+ * empty revocation list omits `revokedCertificates` instead of emitting an empty SEQUENCE (sec. 5.1.2.6);
  * `reasonCode` is an ENUMERATED and `invalidityDate` is always GeneralizedTime (sec. 5.3.1/5.3.2);
  * per-extension criticality is fixed by the RFC; and the produced signature is verified under the issuer
- * key before return. A violation throws a typed `CrlError`; where the spec carries raw DER -- an issuer
- * `Name` Buffer or a pre-encoded `Extension` -- a malformed leaf inside those bytes throws `Asn1Error`.
+ * key before return. A violation throws a typed `CrlError`; where the spec carries raw DER (an issuer
+ * `Name` Buffer or a pre-encoded `Extension`), a malformed leaf inside those bytes throws `Asn1Error`.
  *
  * @opts
  *   - `pem` (boolean) -- return a PEM `X509 CRL` string instead of DER.
- *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
+ *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS instead of PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -507,7 +507,13 @@ function _sign(spec, issuer, opts) {
  *   }, { cert: signerCertDer, key: signerKeyPkcs8 });
  *   pki.schema.crl.parse(der).revokedCertificates[0].serialNumberHex;   // "1234"
  */
-function sign(spec, issuer, opts) { return Promise.resolve().then(function () { return _sign(spec, issuer, opts); }); }
+function sign(spec, issuer, opts) {
+  // Every caller-owned argument copied at entry and released when the call settles -- see the note
+  // on the same call in x509-sign.
+  return guard.bytes.fixedCall(CrlError, "crl/bad-input", [
+    [spec, "the CRL spec"], [issuer, "the issuer"], [opts, "pki.crl.sign options"],
+  ], _sign);
+}
 
 // A CRL these verbs answer from is re-derived from the bytes its parser read. Completeness -- every
 // field present with the right type -- is not enough for a verdict: the signature covers a byte
@@ -578,8 +584,8 @@ function _issuerMaySign(parsed, cert) {
  * EdDSA low-order-point gates -- so there is no second, weaker CRL verifier. It fails closed to `false` on
  * any resolution, import, or verification fault; malformed input throws a typed `CrlError`.
  *
- * Given a CERTIFICATE rather than a bare key, it also asks what only a certificate can answer: that
- * the certificate is the issuer this CRL names, and that its keyUsage -- when it carries one -- asserts
+ * Given a certificate in place of a bare key, it also asks what only a certificate can answer: that
+ * the certificate is the issuer this CRL names, and that its keyUsage, when it carries one, asserts
  * `cRLSign` (RFC 5280 sec. 4.2.1.3, the same rule this module's signing side already enforces). Either
  * failing is `false`: a statement about the CRL, not about the caller's input, so trying each candidate
  * issuer in turn still works. A signature verifying says only that SOME key signed these bytes; without
@@ -598,7 +604,7 @@ function _issuerMaySign(parsed, cert) {
  *     { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var ok = await pki.crl.verify(crlDer, { publicKey: signerSpki });   // true / false
  */
-function verify(crl, issuer) { return Promise.resolve().then(function () { return _verify(crl, issuer); }); }
+function verify(crl, issuer) { return guard.async.deferred(function () { return _verify(crl, issuer); }); }
 function _verify(crl, issuer) {
   var parsed = _coerceCrl(crl);
   var resolved = _resolveIssuer(issuer);
@@ -633,17 +639,17 @@ function _serialHexOf(serial) {
  * PEM string, or a parsed CRL; `serialNumber` is a `BigInt`, a safe integer, a decimal / `0x`-hex string,
  * or a magnitude `Buffer`. Returns the matching revoked-certificate entry (`{ serialNumber, serialNumberHex,
  * revocationDate, crlEntryExtensions }`) or `null` when the serial is not listed. A structural lookup only --
- * it does NOT verify the CRL signature or its currency; call `pki.crl.verify` / `pki.path.crlChecker` for that.
+ * it does not verify the CRL signature or its currency; call `pki.crl.verify` / `pki.path.crlChecker` for that.
  *
- * It does check SCOPE first, because a serial number means something only within the set of
- * certificates a CRL speaks for, and this verb is given a serial and nothing else -- so a CRL that
- * speaks for part of its issuer's certificates is refused rather than answered from:
+ * It does check scope first, because a serial number means something only within the set of
+ * certificates a CRL speaks for, and this verb is given a serial and nothing else. So a CRL that
+ * speaks for part of its issuer's certificates is refused, never answered from:
  *
  * - A DELTA CRL lists changes since a base, so a serial in it may be there to say the certificate
  *   was RELEASED; read alone, the entry meaning "no longer revoked" reads as "revoked"
  *   (`crl/delta-not-authoritative`). Merge it with its base through `pki.path.crlChecker`.
  * - An INDIRECT CRL carries entries for other issuers, whose serials are unrelated to yours
- *   (`crl/indirect-not-supported`) -- as does any CRL carrying `certificateIssuer` on an entry
+ *   (`crl/indirect-not-supported`), as does any CRL carrying `certificateIssuer` on an entry
  *   while not declaring itself indirect, a contradiction about whose certificates it lists.
  * - Any other `issuingDistributionPoint` narrows the CRL to one distribution point, one kind of
  *   certificate, or a subset of revocation reasons (`crl/scope-not-authoritative`). Which part

package/lib/crl-verify.js

@@ -2,12 +2,13 @@
 // Copyright (c) blamejs contributors
 "use strict";
 //
-// @internal -- the ONE CRL signature-verify seam, shared by pki.path.crlChecker and pki.crl.verify so both
-// route through the SAME signature engine (algorithm-confusion + EdDSA low-order + composite gates) and no
-// second, weaker CRL verifier can drift. path-validate owns that engine (_verifyWithSpki) and injects it
-// here at its module load (setEngine). Keeping the seam in this internal module -- rather than on
-// path-validate's module.exports -- keeps it OFF the public pki.path surface (it takes the path-internal
-// SubjectPublicKeyInfo bytes, not a documented issuer shape). NOT wired into index.js; reached only by require.
+// @internal -- the single CRL signature-verify seam, shared by pki.path.crlChecker and pki.crl.verify
+// so both route through one signature engine (algorithm-confusion + EdDSA low-order + composite
+// gates) and no second, weaker CRL verifier can drift. path-validate owns that engine
+// (_verifyWithSpki) and injects it here at its module load (setEngine). The seam lives in this
+// internal module, not on path-validate's module.exports, which keeps it off the public pki.path
+// surface: it takes the path-internal SubjectPublicKeyInfo bytes, not a documented issuer shape.
+// It is not wired into index.js and is reached only by require.
 
 var guard = require("./guard-all");
 

package/lib/crmf-sign.js

@@ -50,8 +50,8 @@ var KNOWN_SPEC_KEYS = { certReqId: 1, certTemplate: 1, controls: 1, regInfo: 1,
 var KNOWN_BATCH_KEYS = { messages: 1 };
 var KNOWN_TEMPLATE_KEYS = { version: 1, subject: 1, publicKey: 1, validity: 1, extensions: 1, issuer: 1 };
 var REVOCATION_TEMPLATE_KEYS = { version: 1, subject: 1, publicKey: 1, validity: 1, extensions: 1, issuer: 1, serialNumber: 1 };
-// The controls (RFC 4211 sec. 6) and regInfo (sec. 7) are DISJOINT AttributeTypeAndValue namespaces --
-// regToken/authenticator/oldCertID/protocolEncrKey are controls; utf8Pairs is regInfo -- so the object
+// The controls (RFC 4211 sec. 6) and regInfo (sec. 7) are disjoint AttributeTypeAndValue namespaces:
+// regToken/authenticator/oldCertID/protocolEncrKey are controls and utf8Pairs is regInfo, so the object
 // form validates each key against its own field's registry (a control name is not a valid regInfo, and
 // vice versa). The key name equals the registered OID name; complex values (pkiPublicationInfo, certReq)
 // ride the pre-encoded escape hatch. Each entry is the value encoder for that OID.
@@ -69,7 +69,7 @@ function _encodeOptionalValidity(validity) {
   var nb = validity.notBefore, na = validity.notAfter;
   if (nb == null && na == null) throw _err("crmf/bad-validity", "validity must contain notBefore or notAfter (RFC 4211 sec. 5)");
   var parts = [];
-  // timeDer validates each instant (guard.time.assertValid throws on an Invalid Date) BEFORE the
+  // timeDer validates each instant (guard.time.assertValid throws on an Invalid Date) before the
   // inverted-window comparison, so getTime() below cannot be NaN.
   if (nb != null) parts.push(b.explicit(0, _b.timeDer(nb, "validity notBefore")));
   if (na != null) parts.push(b.explicit(1, _b.timeDer(na, "validity notAfter")));
@@ -77,13 +77,13 @@ function _encodeOptionalValidity(validity) {
   if (nb != null && na != null && nb.getTime() > na.getTime()) throw _err("crmf/bad-validity", "notBefore must not be after notAfter");
   return b.implicit(4, b.sequence(parts));
 }
-// CertTemplate ::= SEQUENCE { [0..9] all IMPLICIT OPTIONAL }. A REQUEST omits serialNumber [1] / signingAlg
-// [2] / issuerUID [7] / subjectUID [8] (CA-assigned or deprecated, RFC 4211 sec. 5) -- the builder never
+// CertTemplate ::= SEQUENCE { [0..9] all IMPLICIT OPTIONAL }. A request omits serialNumber [1] / signingAlg
+// [2] / issuerUID [7] / subjectUID [8] (CA-assigned or deprecated, RFC 4211 sec. 5), and the builder never
 // emits them. Fields are emitted in ascending tag order.
 function _encodeCertTemplate(tpl, opts) {
   if (!tpl || typeof tpl !== "object" || Buffer.isBuffer(tpl)) throw _err("crmf/bad-cert-template", "certTemplate must be an object");
-  // A REQUEST template omits serialNumber (CA-assigned, RFC 4211 sec. 5); a REVOCATION template (CMP rr,
-  // RFC 9810 sec. 5.3.9) carries serialNumber [1] to name the certificate to revoke -- allowed only then.
+  // A request template omits serialNumber (CA-assigned, RFC 4211 sec. 5); a revocation template (CMP rr,
+  // RFC 9810 sec. 5.3.9) carries serialNumber [1] to name the certificate to revoke, allowed only then.
   var allowed = (opts && opts.revocation) ? REVOCATION_TEMPLATE_KEYS : KNOWN_TEMPLATE_KEYS;
   guard.identifier.assertKnownKeys(tpl, allowed, _err, "crmf/bad-input", "unknown certTemplate field ");
   var fields = [];
@@ -158,8 +158,8 @@ function _encodeCertId(id) {
   return b.sequence([_b.encodeGeneralName(id.issuer), _b.serialInteger(id.serialNumber)]);
 }
 
-// ProofOfPossession. The signature arm (the default when a key is given): when the template carries BOTH
-// subject and publicKey (complete), sign the CertRequest DER and OMIT poposkInput; otherwise build a
+// ProofOfPossession. The signature arm (the default when a key is given): when the template carries both
+// subject and publicKey (complete), sign the CertRequest DER and omit poposkInput; otherwise build a
 // POPOSigningKeyInput (authInfo sender [0] GeneralName + the requested publicKey), sign its SEQUENCE, and
 // carry it as poposkInput [0] (RFC 4211 sec. 4.1). raVerified is emitted only on an explicit opt-in.
 function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
@@ -209,8 +209,8 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  * @related pki.schema.crmf.parse, pki.csr.sign
  *
  * Build and DER-encode an RFC 4211 `CertReqMessages`. `spec` describes one certificate request message (or
- * pass `spec.messages` -- an array of specs -- for a batch): `certReqId` (an integer, default 0; the RFC
- * 9483 `-1` sentinel is allowed), `certTemplate` (the requested certificate fields -- `subject`, `publicKey`
+ * pass `spec.messages`, an array of specs, for a batch): `certReqId` (an integer, default 0; the RFC
+ * 9483 `-1` sentinel is allowed), `certTemplate` (the requested certificate fields: `subject`, `publicKey`
  * (the SPKI DER of the key being certified), `validity` ({ notBefore, notAfter } Dates), `extensions` (an
  * object of subjectAltName / keyUsage / extendedKeyUsage / basicConstraints / certificatePolicies /
  * subjectKeyIdentifier, or pre-encoded Extension DER), and an optional `version` (2)), optional `controls`
@@ -219,14 +219,14 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  * REQUESTER's private key -- the private half of `certTemplate.publicKey`; the message carries a
  * `POPOSigningKey` proof of possession signed with it (verified before the message is returned), exactly
  * as a PKCS#10 CSR proves possession. The signature algorithm is resolved from the requested public key
- * (RSA PKCS#1 v1.5 / PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm). `key` is optional -- omit it
+ * (RSA PKCS#1 v1.5 / PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm). `key` is optional: omit it
  * for a `raVerified` proof (opt in with `pop: { type: 'raVerified', raVerified: true }`). Returns DER, or a
  * PEM block with `opts.pem` (the label is required). Malformed input throws a typed `CrmfError`.
  * Certificate-request-message parsing is `pki.schema.crmf.parse`.
  *
  * @opts
  *   - `pem` (string) -- return a PEM block with this label instead of DER (e.g. "CERTIFICATE REQUEST MESSAGE").
- *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
+ *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS instead of PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -238,7 +238,11 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  *   pki.schema.crmf.parse(msg).messages[0].certReq.certTemplate.subject.dn;   // "CN=device-42"
  */
 function build(spec, key, opts) {
-  return Promise.resolve().then(function () { return _build(spec, key, opts); });
+  // Every caller-owned argument copied at entry and released when the call settles -- see the note
+  // on the same call in x509-sign.
+  return guard.bytes.fixedCall(CrmfError, "crmf/bad-input", [
+    [spec, "the certificate-request-message spec"], [key, "the signing key"], [opts, "pki.crmf.build options"],
+  ], _build);
 }
 
 function _buildCertReqMsg(spec, key, opts) {
@@ -294,7 +298,7 @@ function _build(spec, key, opts) {
  * @spec       RFC 4211
  * @related    pki.crmf.build
  *
- * Encode a bare RFC 4211 `CertTemplate` (the requested-certificate fields -- `subject`, `publicKey`,
+ * Encode a bare RFC 4211 `CertTemplate` (the requested-certificate fields: `subject`, `publicKey`,
  * `validity`, requested `extensions`, an optional `version` 2, `issuer`) to canonical DER. This is the
  * `certTemplate` interior of `pki.crmf.build`, exposed for the RFC 9810 CMP `rr` (revocation request) body,
  * whose `RevDetails.certDetails` carries a `CertTemplate` naming the certificate to revoke. Returns the DER

package/lib/csr-sign.js

@@ -7,8 +7,8 @@
  * @nav        Signing
  * @title      Certification requests
  * @intro The PKCS#10 certification-request producing side. `pki.csr.sign` builds a
- *   `CertificationRequestInfo`, signs it with the SUBJECT's own private key (proof of possession -- a
- *   CSR has no issuer), and emits a `CertificationRequest` (RFC 2986) that `pki.schema.csr.parse`,
+ *   `CertificationRequestInfo`, signs it with the subject's own private key (proof of possession, since
+ *   a CSR has no issuer), and emits a `CertificationRequest` (RFC 2986) that `pki.schema.csr.parse`,
  *   OpenSSL, and a CA enrollment pipeline all accept. Requested v3 extensions ride in a PKCS#9
  *   `extensionRequest` attribute (RFC 2985) a CA copies into the issued certificate. Parsing lives at
  *   `pki.schema.csr.parse`.
@@ -73,22 +73,22 @@ function _challengePassword(pw) {
  * @defends forged-certification-request (CWE-347)
  * @related pki.schema.csr.parse, pki.x509.sign
  *
- * Build, sign, and DER-encode a PKCS#10 certification request. `spec` describes the request -- `subject`
+ * Build, sign, and DER-encode a PKCS#10 certification request. `spec` describes the request: `subject`
  * (a common-name string, an array of RDNs, or raw Name DER; MAY be empty), `subjectPublicKey` (the SPKI
- * DER of the key being certified), and optional `extensionRequest` (requested v3 extensions -- an object
+ * DER of the key being certified), and optional `extensionRequest` (requested v3 extensions, as an object
  * of subjectAltName / keyUsage / extendedKeyUsage / basicConstraints / certificatePolicies /
  * subjectKeyIdentifier, or an array of pre-encoded Extension DER) and `challengePassword`. `key` (or
- * `{ key }`) is the SUBJECT's own PKCS#8 private key / WebCrypto CryptoKey -- the request is self-signed
+ * `{ key }`) is the subject's own PKCS#8 private key / WebCrypto CryptoKey, so the request is self-signed
  * to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the
  * request is returned. The signature algorithm is resolved from the subject key (RSA PKCS#1 v1.5 or PSS,
  * ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm). Returns DER, or a PEM `CERTIFICATE REQUEST` with
- * `opts.pem`. Malformed input throws a typed `CsrError`; where the spec carries raw DER -- a `Name`
- * Buffer, a pre-encoded requested `Extension` or `Attribute` -- a malformed leaf inside those bytes
+ * `opts.pem`. Malformed input throws a typed `CsrError`; where the spec carries raw DER (a `Name`
+ * Buffer, a pre-encoded requested `Extension` or `Attribute`) a malformed leaf inside those bytes
  * throws `Asn1Error` instead. Certificate-request parsing is `pki.schema.csr.parse`.
  *
  * @opts
  *   - `pem` (boolean) -- return a PEM `CERTIFICATE REQUEST` string instead of DER.
- *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
+ *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS instead of PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -101,7 +101,11 @@ function _challengePassword(pw) {
  *   pki.schema.csr.parse(req).subject.dn;   // "CN=req.example.com"
  */
 function sign(spec, key, opts) {
-  return Promise.resolve().then(function () { return _sign(spec, key, opts); });
+  // Every caller-owned argument copied at entry and released when the call settles -- see the note
+  // on the same call in x509-sign.
+  return guard.bytes.fixedCall(CsrError, "csr/bad-input", [
+    [spec, "the certification-request spec"], [key, "the signing key"], [opts, "pki.csr.sign options"],
+  ], _sign);
 }
 
 function _sign(spec, key, opts) {

package/lib/ct.js

@@ -15,19 +15,19 @@
  *   certificate timestamps.
  *
  *   The SCT payload is encoded in the TLS presentation language (RFC 8446 sec. 3 /
- *   RFC 5246 sec. 4 conventions) -- positional, tag-less, fixed-width big-endian
- *   integers and length-prefixed opaque vectors -- NOT ASN.1/DER. So this module
- *   owns a bounded big-endian TLS-struct reader rather than composing the DER
+ *   RFC 5246 sec. 4 conventions): positional, tag-less, fixed-width big-endian
+ *   integers and length-prefixed opaque vectors, never ASN.1/DER. So this module
+ *   owns a bounded big-endian TLS-struct reader instead of composing the DER
  *   schema engine; the only ASN.1 surface is the sec. 3.3 double wrap (the
  *   extension value is a DER OCTET STRING whose content is another DER OCTET
- *   STRING whose content is the TLS list -- the certificate/OCSP layer peels the
+ *   STRING whose content is the TLS list; the certificate/OCSP layer peels the
  *   outer, this module peels the inner).
  *
- *   Structure is decoded, crypto is surfaced RAW: each SCT surfaces its `logId`
- *   (32 raw bytes -- SHA-256 of the log's SPKI, never recomputed), the exact
+ *   Structure is decoded, crypto is surfaced raw: each SCT surfaces its `logId`
+ *   (32 raw bytes, the SHA-256 of the log's SPKI, never recomputed), the exact
  *   `timestamp` as a BigInt, the raw `extensions`, the named-but-not-interpreted
- *   `hashAlg`/`sigAlg` code points, and the raw `signature`. The parser NEVER
- *   verifies a signature, recomputes a LogID, or trusts a log -- a verifier
+ *   `hashAlg`/`sigAlg` code points, and the raw `signature`. The parser never
+ *   verifies a signature, recomputes a LogID, or trusts a log. A verifier
  *   composes `webcrypto` over `reconstructSignedData(...)`, the exact
  *   `digitally-signed` preimage. DER-only carrier, fail-closed.
  *
@@ -58,10 +58,10 @@ var C = constants;
 
 // (code, message[, cause]) -> CtError, the factory the composed guards + the shared transport throw
 // through so a malformed value keeps the ct/* typed verdict (the optional cause carries the underlying
-// transport / evaluation error; existing 2-arg callers pass undefined -- behavior-preserving).
+// transport / evaluation error; existing 2-arg callers pass undefined, so the change preserves behavior).
 function _ctErr(c, m, cause) { return new CtError(c, m, cause); }
 
-// RFC 5246 sec. 7.4.1.4.1 code points -- 1-byte, NOT OIDs. Surfaced named; an
+// RFC 5246 sec. 7.4.1.4.1 code points: 1-byte values, never OIDs. Surfaced named; an
 // unknown code surfaces as its numeric byte with a null name (never rejected --
 // off-profile-pair rejection is a verifier-tier log-conformance concern).
 var HASH_ALGORITHMS = {
@@ -75,7 +75,7 @@ var SCT_MIN_BODY = 47;
 var LOGID_BYTES = 32;
 var MAX_SAFE = 9007199254740991n;   // 2^53 - 1; above this a Number loses precision
 
-// ---- TlsReader -- the RFC 6962 TLS-vector cursor, the shared bounded big-endian
+// ---- TlsReader: the RFC 6962 TLS-vector cursor, the shared bounded big-endian
 // ByteReader engine primitive bound to the ct/* fault domain. A lying inner length
 // can overrun only the current sub-reader's `end`, never the parent buffer, so
 // bounds-before-slice is structural (see lib/byte-reader.js).
@@ -102,7 +102,7 @@ function _toBuffer(v, field) {
 // version this parser does not define is preserved OPAQUE, not rejected: RFC 6962
 // sec. 3.3 gives every SerializedSCT its own length prefix precisely so a client "can
 // still parse old SCTs while skipping over new SCTs whose versions they don't
-// understand" -- so an unknown version yields { unknown, version, rawSct } and the
+// understand", so an unknown version yields { unknown, version, rawSct } and the
 // v1-specific field decode (and the 47-byte floor) is skipped.
 function _parseSct(r, sctLen) {
   var bodyStart = r.pos;
@@ -156,8 +156,8 @@ function _parseSct(r, sctLen) {
  * `extensions` (raw Buffer), `hashAlg` / `sigAlg` (1-byte code points) + a named
  * `signatureAlgorithm`, the raw `signature` Buffer, and `rawSct` (the full
  * SerializedSCT body). A SerializedSCT whose version this parser does not define
- * is preserved OPAQUE in `unknownScts` as `{ version, rawSct }` rather than
- * failing the list -- RFC 6962 sec. 3.3 frames each SerializedSCT with its own length
+ * is preserved opaque in `unknownScts` as `{ version, rawSct }` and does not fail
+ * the list: RFC 6962 sec. 3.3 frames each SerializedSCT with its own length
  * so unknown versions are skippable (forward compatibility). `all` lists every
  * SerializedSCT (known and unknown) in the exact wire order, so
  * `encodeSctList(all)` reproduces the list byte-identically even when the two
@@ -166,7 +166,7 @@ function _parseSct(r, sctLen) {
  * The extension value is a DER `OCTET STRING` wrapping the TLS-encoded list
  * (RFC 6962 sec. 3.3 double wrap); everything below that peel is TLS presentation
  * language, decoded with a bounded cursor. Structure is decoded, crypto is
- * surfaced RAW -- the signature is never verified and the LogID never recomputed.
+ * surfaced raw: the signature is never verified and the LogID never recomputed.
  *
  * Throws `CtError` with a stable `ct/*` code on any malformed input (a bad inner
  * DER wrap is `ct/bad-der` with the `asn1/*` fault as `.cause`), never a raw
@@ -249,7 +249,7 @@ function _u24Bytes(n) {
  * Rebuild the exact `digitally-signed` preimage bytes an external verifier
  * hashes to check an SCT's signature (RFC 6962 sec. 3.2), for a parsed `sct`.
  * `entry` selects the log-entry arm:
- *   - `{ entryType: 0, leafCert: <DER Buffer> }` -- an SCT delivered over TLS /
+ *   - `{ entryType: 0, leafCert: <DER Buffer> }`, an SCT delivered over TLS /
  *     OCSP, signed over `x509_entry(0)` with the leaf certificate.
  *   - `{ entryType: 1, tbsCertificate: <DER Buffer>, issuerKeyHash: <32B> }` --
  *     an SCT EMBEDDED in a certificate, signed over `precert_entry(1)` with the
@@ -378,12 +378,12 @@ function _spkiAlg(spki) {
  * (`{ entryType: 0, leafCert }` or `{ entryType: 1, tbsCertificate, issuerKeyHash }`,
  * as for `reconstructSignedData`), `sct` a decoded v1 SCT from `parseSctList().scts[]`,
  * and `logPublicKey` the log's SubjectPublicKeyInfo (DER `Buffer`). Reconstructs the exact
- * signed data, imports the log key, and verifies the SCT signature -- an ECDSA signature is
+ * signed data, imports the log key, and verifies the SCT signature. An ECDSA signature is
  * routed through the strict DER ECDSA-Sig-Value conformance gate before conversion to the
  * raw r||s WebCrypto expects, an RSA signature verifies directly.
  *
  * Resolves `true` on a valid signature and `false` on a cryptographic mismatch (a false
- * verdict is a verdict). Throws a typed `CtError` on structural failure -- a malformed
+ * verdict is a verdict). Throws a typed `CtError` on structural failure: a malformed
  * entry/SCT, an unusable log key, or an unsupported hash/signature algorithm.
  *
  * @example
@@ -492,12 +492,12 @@ function _encodeSctBody(sct) {
  * @spec       RFC 6962, RFC 5246
  * @related    pki.ct.parseSctList, pki.ct.signSct
  *
- * Build the value of an RFC 6962 SCT-list extension from an array of SCTs -- the exact
+ * Build the value of an RFC 6962 SCT-list extension from an array of SCTs: the exact
  * inverse of `parseSctList`, such that `parseSctList(encodeSctList(list.all))` round-trips to
  * identical bytes. Each element is either a decoded v1 SCT (the shape `parseSctList().scts[]`
  * or `signSct` returns: `version` 0, 32-byte `logId`, `timestamp` BigInt, raw `extensions`,
- * `hashAlg` / `sigAlg` code points, raw `signature`) -- rebuilt from its fields in the RFC
- * 6962 sec. 3.2 field order -- or an opaque non-v1 entry (`{ version, rawSct }`) whose
+ * `hashAlg` / `sigAlg` code points, raw `signature`), rebuilt from its fields in the RFC
+ * 6962 sec. 3.2 field order, or an opaque non-v1 entry (`{ version, rawSct }`) whose
  * `rawSct` is re-emitted verbatim (forward compatibility, sec. 3.3). Pass `parseSctList().all`
  * (not `.scts`) to preserve the exact wire order and every unknown-version entry.
  *
@@ -568,7 +568,7 @@ function _logKeyMaterial(logKey) {
  * @related    pki.ct.verifySct, pki.ct.reconstructSignedData, pki.ct.encodeSctList
  *
  * Perform a Certificate Transparency log's signing step (RFC 6962 sec. 3.2): rebuild the exact
- * `digitally-signed` preimage over `entry` (via `reconstructSignedData`, the SAME builder the
+ * `digitally-signed` preimage over `entry` (via `reconstructSignedData`, the same builder the
  * verifier hashes), sign it with the log's private key, and return a fully-formed v1 SCT that
  * `verifySct` accepts against the log's public key. `entry` is the log entry the SCT covers
  * (`{ entryType: 0, leafCert }` or `{ entryType: 1, tbsCertificate, issuerKeyHash }`, as for
@@ -576,7 +576,7 @@ function _logKeyMaterial(logKey) {
  * or a node `KeyObject`).
  *
  * The log-key profile is RFC 6962 sec. 2.1.4: ECDSA NIST P-256 (`sigAlg` 3) or RSA >= 2048
- * (`sigAlg` 1), SHA-256 only -- an unsupported key fails closed `ct/unsupported-algorithm`. The
+ * (`sigAlg` 1), SHA-256 only; an unsupported key fails closed `ct/unsupported-algorithm`. The
  * `logId` is derived as SHA-256 of the log SPKI (sec. 3.4); a supplied `opts.logId` must match.
  * The returned SCT is the parseSctList/verifySct shape and composes with `encodeSctList`.
  *
@@ -715,17 +715,17 @@ function _logsAgree(a, b) {
  * @related    pki.ct.verifySctWithLogList, pki.ct.verifySct
  *
  * Ingest a Certificate Transparency log-list JSON document (the `log_list.json` browsers consume) into a
- * set of constraint-carrying trusted logs, keyed by log-id. `json` is a Buffer or string -- the caller
+ * set of constraint-carrying trusted logs, keyed by log-id. `json` is a Buffer or string; the caller
  * supplies the already-fetched, already-authenticated bytes (offline, no network fetch). Parsing routes
  * through the bounded, duplicate-member-rejecting JSON reader; for each log it base64-decodes the `key`
  * to its DER SubjectPublicKeyInfo, validates it as a well-formed on-profile key, **recomputes**
- * `SHA-256(SPKI)` and fail-closed **requires** it equal the stated `log_id` (RFC 6962 sec. 3.2 -- a log
+ * `SHA-256(SPKI)` and fail-closed **requires** it equal the stated `log_id` (RFC 6962 sec. 3.2; a log
  * whose stated id disagrees with its key is refused as `ct/log-id-mismatch`), and decodes the `state`
  * (exactly one of pending/qualified/usable/readonly/retired/rejected) and `temporal_interval`. Returns
  * `{ logs, byLogId, version, timestamp }` where each log is `{ logId, logIdHex, key, description, url, mmd,
  * operator, state: { name, since, trusted, conditional }, temporalInterval, trusted }`, `byLogId` is a
  * null-proto `{ logIdHex: log }` map, `version` is the document's version string (or null), and `timestamp`
- * is the parsed `log_list_timestamp` `Date` (or null when absent/unparseable -- the staleness surface, read
+ * is the parsed `log_list_timestamp` `Date` (or null when absent/unparseable; the staleness surface, read
  * leniently, never a throw). Every malformed / oversized / mis-bound input is a typed `CtError`.
  *
  * @example
@@ -810,8 +810,8 @@ function _resolveNotAfter(entry, opts) {
  * the log is resolved by `sct.logIdHex` (an unknown log is `ct/log-not-found`). The log's **state** gates
  * trust (usable/qualified/readonly proceed; a retired log proceeds only for an SCT timestamped before its
  * retirement instant; pending/rejected are `ct/log-untrusted`); its **temporal_interval** gates the
- * covered certificate (the cert's `notAfter` -- from `entry.leafCert` when `entryType` is 0, or
- * `opts.certNotAfter` -- must fall in `[start_inclusive, end_exclusive)`, and a windowed log with no
+ * covered certificate: the cert's `notAfter`, from `entry.leafCert` when `entryType` is 0 or from
+ * `opts.certNotAfter`, must fall in `[start_inclusive, end_exclusive)`, and a windowed log with no
  * resolvable notAfter is `ct/temporal-interval`, never silently skipped). Then the crypto is delegated to
  * the shipped `verifySct(entry, sct, log.key)` (which independently re-checks `logId == SHA-256(key)`).
  * Resolves `true` for a valid signature from a trusted, in-window log; `false` on a cryptographic
@@ -870,9 +870,9 @@ async function verifySctWithLogList(entry, sct, logList, opts) {
  * @related    pki.ct.parseLogList, pki.ct.verifySct
  *
  * Verify the detached signature published alongside the Certificate Transparency log list (the
- * `log_list.sig` over `log_list.json`). `json` is the RAW log-list bytes (a Buffer, or the fetched text
- * as a string -- verified byte-for-byte, never re-serialized), `signature` is the detached signature, and
- * `publicKey` is the caller-PINNED signer SubjectPublicKeyInfo (DER; there is no baked-in key). The scheme
+ * `log_list.sig` over `log_list.json`). `json` is the raw log-list bytes (a Buffer, or the fetched text
+ * as a string, verified byte-for-byte and never re-serialized), `signature` is the detached signature, and
+ * `publicKey` is the caller-pinned signer SubjectPublicKeyInfo (DER; there is no baked-in key). The scheme
  * is RSASSA-PKCS1-v1.5 with SHA-256 over an RSA key (the deployed scheme; an EC P-256 / ECDSA-SHA-256 arm
  * is accepted for future-proofing). Resolves `true` for a valid signature, `false` on a cryptographic
  * mismatch (a verdict). Fail-closed forgery defenses throw before any verify: an RSA public exponent below
@@ -1010,27 +1010,27 @@ function _fetchBody(transport, url, req, label) {
  * @spec       RFC 6962
  * @related    pki.ct.parseLogList, pki.ct.verifyLogListSignature, pki.ct.verifySctWithLogList
  *
- * Fetch the Certificate Transparency log list live and return the trusted-log set ONLY after the detached
+ * Fetch the Certificate Transparency log list live and return the trusted-log set only after the detached
  * signature verifies against the caller-pinned distributor key. It GETs `opts.url` (the `log_list.json`)
  * and the detached `opts.sigUrl` (the `log_list.sig`, by default `opts.url` with a `.json` path suffix
  * rewritten to `.sig`) over the shared, fail-closed `pki.transport` (or an injected `opts.transport`), then
- * verifies the detached signature over the RAW fetched JSON bytes against `opts.signerKey` and only on a
- * strict `true` verdict ingests the SAME bytes through `parseLogList` -- so the client never parses, reads,
+ * verifies the detached signature over the raw fetched JSON bytes against `opts.signerKey` and only on a
+ * strict `true` verdict ingests those same bytes through `parseLogList`, so the client never parses, reads,
  * caches, or surfaces any field of an unverified document (verify-before-parse). No baked-in vendor URL and
- * no baked-in key: the caller pins both out-of-band. Trust is EXPLICIT -- an `opts.tls.anchors` set or an
+ * no baked-in key: the caller pins both out-of-band. Trust is explicit: an `opts.tls.anchors` set or an
  * `opts.tls.useSystemStore` opt-in, `rejectUnauthorized` always on. The returned `timestamp` is surfaced
  * (never policed) so the caller enforces its own freshness policy; chaining a resolved log to an SCT is the
  * caller's `verifySctWithLogList` step. Every fetch / verify / parse failure is a typed `CtError`.
  *
  * @opts url REQUIRED -- the `log_list.json` URL; must be https (no baked-in vendor URL).
- * @opts signerKey REQUIRED, PINNED -- the distributor SubjectPublicKeyInfo as a DER Buffer; no baked-in key.
+ * @opts signerKey REQUIRED and caller-pinned -- the distributor SubjectPublicKeyInfo as a DER Buffer; no baked-in key.
  * @opts sigUrl OPTIONAL -- the detached `log_list.sig` URL (https, must share the log-list URL's origin); default `url` with `.json` -> `.sig` (a non-.json url requires an explicit sigUrl).
  * @opts transport OPTIONAL injectable `transport(request) -> Promise<{status,headers,body}>` (default `pki.transport.https`); the test seam.
  * @opts tls OPTIONAL `{ anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }` threaded to the default transport (ignored when a transport is injected); `rejectUnauthorized` is always on.
  * @opts headers OPTIONAL extra request headers (the request-framing headers are stripped; the verb owns the GET method).
  * @opts timeout OPTIONAL ms budget, default 30s (cap-validated).
  * @opts maxResponseBytes OPTIONAL per-GET size cap, default 4 MiB, tightenable DOWNWARD only.
- * @opts requireJsonContentType OPTIONAL boolean, default false -- opt in to a strict `ct/bad-content-type` gate on the JSON GET.
+ * @opts requireJsonContentType OPTIONAL boolean (default false) -- opt in to a strict `ct/bad-content-type` gate on the JSON GET.
  * @example
  *   // a live distributor uses the default pki.transport.https; here an injected transport returns the pair
  *   var r = await pki.ct.fetchLogList({ url: "https://ct.example/log_list.json", signerKey: googleSignerSpki,

package/lib/edwards-point.js

@@ -6,13 +6,13 @@
 // OKP (Ed25519 / Ed448) credential public-key point.
 //
 // edwards-point -- point validation for the Edwards curves EdDSA uses. node:crypto imports
-// an RFC 8410 OKP SubjectPublicKeyInfo WITHOUT checking the point is a valid, full-order
+// an RFC 8410 OKP SubjectPublicKeyInfo without checking the point is a valid, full-order
 // Edwards point (an all-zeroes Ed25519/Ed448 key parses, and an all-zeroes key with an
-// all-zeroes signature even verifies TRUE -- a trivial forgery), so an OKP credential key
+// all-zeroes signature even verifies true, a trivial forgery), so an OKP credential key
 // needs an explicit check. This decodes the compressed point per RFC 8032 sec. 5.1.3
-// (Ed25519) / sec. 5.2.3 (Ed448) -- which fails closed on an off-curve or non-canonical
-// encoding -- and rejects a low-order point via the cofactor check [8]P == identity (an
-// all-zeroes key is a low-order point ON the curve, so the decode alone does not catch it).
+// (Ed25519) / sec. 5.2.3 (Ed448); the decode fails closed on an off-curve or non-canonical
+// encoding. It then rejects a low-order point via the cofactor check [8]P == identity (an
+// all-zeroes key is a low-order point on the curve, so the decode alone does not catch it).
 // A conformant authenticator never emits a low-order credential key.
 //
 // Pure BigInt modular arithmetic (constant-time is not a goal here: the input is a public
@@ -93,8 +93,8 @@ function validate(raw, crv) {
 // validateSpki(spkiBytes, crv, E, code) -> throws new E(code, ...) unless the
 // SubjectPublicKeyInfo's subjectPublicKey (its BIT STRING body, past the unused-bits octet) is a
 // canonical, on-curve, full-order Edwards point for the OKP curve (6 = Ed25519, 7 = Ed448). This
-// is the one home every EdDSA verify path routes an SPKI through before importKey/verify -- node
-// imports a low-order (e.g. all-zeroes) OKP SPKI without complaint and such a key verifies a
+// is the one home every EdDSA verify path routes an SPKI through before importKey/verify, because
+// node imports a low-order (e.g. all-zeroes) OKP SPKI without complaint and such a key verifies a
 // forged signature. Error-parameterized like the guard family: the caller passes its own typed
 // error CONSTRUCTOR `E` and domain `code`, so the shared gate keeps no error domain of its own.
 function validateSpki(spkiBytes, crv, E, code) {