@blamejs/pki 0.5.7 → 0.5.8

package/lib/inspect.js

@@ -5,19 +5,19 @@
  * @module pki.inspect
  * @nav        Tooling
  * @title      Inspect
- * @intro Human-readable inspection of a parsed certificate -- the pure-JS
+ * @intro Human-readable inspection of a parsed certificate: the pure-JS
  *   equivalent of `openssl x509 -text`. `certificate(input)` ingests a PEM string,
  *   a DER Buffer, or an already-parsed certificate and returns a familiar
  *   OpenSSL-style report: version, serial, signature algorithm, the issuer and
  *   subject distinguished names, the validity window, the public-key details
  *   (curve or modulus size plus the raw point/modulus), every decoded extension
  *   with its critical flag, and the signature. It renders purely from the toolkit's
- *   own strict parser and two-way OID registry -- no OpenSSL dependency, and no
- *   drift-prone second naming table -- so it names extension and algorithm OIDs an
- *   OpenSSL build shows only as raw bytes. The format is stable and OpenSSL-*familiar*
- *   rather than byte-identical to any one OpenSSL version (those disagree across
+ *   own strict parser and two-way OID registry, with no OpenSSL dependency and no
+ *   drift-prone second naming table, so it names extension and algorithm OIDs an
+ *   OpenSSL build shows only as raw bytes. The format is stable and OpenSSL-*familiar*,
+ *   never byte-identical to any one OpenSSL version (those disagree across
  *   releases). Rendering is best-effort: a malformed extension falls back to a hex
- *   dump rather than throwing.
+ *   dump and does not throw.
  * @spec RFC 5280
  * @card Read a certificate like `openssl x509 -text`, in pure JS.
  */
@@ -70,10 +70,10 @@ function _hexColon(buf, opts) {
   return lines.join("\n");
 }
 
-// Coverage residual -- two _hexColon default arms are unreachable through the public API:
-//   * `opts = opts || {}` -- all call sites pass an explicit opts object literal, so the
+// Coverage residual: two _hexColon default arms are unreachable through the public API.
+//   * `opts = opts || {}`. All call sites pass an explicit opts object literal, so the
 //     `|| {}` default never fires.
-//   * `" ".repeat(opts.indent || 0)` -- every wrap-mode caller passes a positive indent
+//   * `" ".repeat(opts.indent || 0)`. Every wrap-mode caller passes a positive indent
 //     (pad.length + 8 >= 8, or inner.length == 16), so `opts.indent` is never falsy.
 
 // Control-byte neutralization for a GeneralName string value routes through the
@@ -83,7 +83,7 @@ var _clean = guard.name.escapeControlBytes;
 
 // The DN display string. pki.schema.pkix already assembles a fully RFC 4514-escaped
 // dn (short names from pki.C.NAMES.DN_SHORT, values escaped via guard.name.escapeDnValue,
-// with the '#'-hex / leading-'\' sentinel handled), so reuse it rather than re-escaping
+// with the '#'-hex / leading-'\' sentinel handled), so reuse it and never re-escape
 // the already-escaped values (which would double-escape a leading '#' / '\').
 function _dnString(name) { return (name && name.dn) || ""; }
 
@@ -108,7 +108,7 @@ function _serial(cert, indent) {
   if (hex.length % 2) hex = "0" + hex;
   var buf = Buffer.from(hex, "hex");
   // Strip a single DER positive-sign 00 byte (present when the value's high bit is
-  // set) so the printed serial is the integer VALUE, matching OpenSSL -- not the
+  // set) so the printed serial is the integer value, matching OpenSSL, and not the
   // encoding's leading octet.
   if (buf.length > 1 && buf[0] === 0x00 && (buf[1] & 0x80)) buf = buf.subarray(1);
   // Small non-negative serials render inline as decimal (0xhex), like OpenSSL;
@@ -122,9 +122,9 @@ function _serial(cert, indent) {
 
 var CURVE_BITS = { "P-256": 256, "P-384": 384, "P-521": 521, "prime256v1": 256, "secp384r1": 384, "secp521r1": 521 };
 var NIST_NAME = NAMES.NIST_CURVE;
-// Every RSA-family key algorithm carries the same SPKI subjectPublicKey -- an
+// Every RSA-family key algorithm carries the same SPKI subjectPublicKey, an
 // RSAPublicKey SEQUENCE { modulus, publicExponent } (RFC 4055 sec. 1.2 for
-// id-RSASSA-PSS / id-RSAES-OAEP) -- so all decode to modulus + exponent, not raw bytes.
+// id-RSASSA-PSS / id-RSAES-OAEP), so all decode to modulus + exponent, not raw bytes.
 var RSA_KEY_ALGS = { rsaEncryption: 1, rsassaPss: 1, rsaesOaep: 1 };
 function _keyBlock(spki, pad) {
   var algName = _algName(spki.algorithm);
@@ -200,8 +200,8 @@ function _ipString(buf) {
 // RFC 4514-equivalent escaping profile, and escaping a legitimate comma in a URI
 // would misrepresent it).
 // The DN of a decoded directoryName GeneralName value. Shared so every renderer that meets this
-// form -- the SAN/AKI GeneralName path and the AIA/SIA accessLocation path, which carry different
-// decoded shapes -- prints the same DN rather than one of them falling back to a bare tag number.
+// form (the SAN/AKI GeneralName path and the AIA/SIA accessLocation path, which carry different
+// decoded shapes) prints the same DN, with neither falling back to a bare tag number.
 function _gnDn(value) {
   return (value && Array.isArray(value.rdns)) ? _dnString(value) : ((value && value.dn) || "");
 }
@@ -219,7 +219,7 @@ function _gn(g) {
 }
 
 // Format a GeneralName still in its raw DER TLV (a CRL distribution point leaves
-// its fullName entries undecoded) -- decode the context tag and render its content.
+// its fullName entries undecoded): decode the context tag and render its content.
 function _gnRaw(buf) {
   if (!Buffer.isBuffer(buf)) return "";
   try {
@@ -233,26 +233,26 @@ function _gnRaw(buf) {
   } catch (_e) { return _hexColon(buf, {}); }
 }
 
-// Coverage residual -- the GeneralName render fallbacks are unreachable because the strict
+// Coverage residual: the GeneralName render fallbacks are unreachable because the strict
 // generalName decoder and each caller already narrow the shape (the _gnRaw catch above is
-// separately documented):
-//   * _ipString `if (!Buffer.isBuffer(buf)) return "";` -- every caller passes a Buffer (the
+// separately documented).
+//   * _ipString `if (!Buffer.isBuffer(buf)) return "";`. Every caller passes a Buffer (the
 //     recursion slices a Buffer, _gn guards Buffer.isBuffer(g.value), _gnRaw passes
 //     asn1.decode(...).content).
-//   * _ipString trailing `return _hexColon(buf, {});` -- generalName enforces iPAddress to
+//   * _ipString trailing `return _hexColon(buf, {});`. generalName enforces iPAddress to
 //     4/16 octets (8/32 for a name-constraints subtree base), so length is only ever 4/8/16/32.
-//   * _gn `if (!g || typeof g !== "object") return "";` -- every _gn call maps a decoder-produced
+//   * _gn `if (!g || typeof g !== "object") return "";`. Every _gn call maps a decoder-produced
 //     GeneralName object; the decoders never emit a null element.
-//   * _gn directoryName `: ((g.value && g.value.dn) || "")` -- a decoded directoryName [4] always
+//   * _gn directoryName `: ((g.value && g.value.dn) || "")`. A decoded directoryName [4] always
 //     carries a Name with an rdns array, so the rdns arm is always taken.
-//   * _gn otherName `: "<unsupported>"` -- a decoded GeneralName always carries its raw bytes TLV.
-//   * _gn `|| ("tag" + t)` -- GeneralName CHOICE tags are 0..8, all mapped in NAMES.GENERAL_NAME;
+//   * _gn otherName `: "<unsupported>"`. A decoded GeneralName always carries its raw bytes TLV.
+//   * _gn `|| ("tag" + t)`. GeneralName CHOICE tags are 0..8, all mapped in NAMES.GENERAL_NAME;
 //     generalName rejects a tag outside 0..8.
-//   * _gn `? _hexColon(g.value, {})` -- iPAddress [7] is the only choice whose decoded value is a
+//   * _gn `? _hexColon(g.value, {})`. iPAddress [7] is the only choice whose decoded value is a
 //     Buffer, handled at the t === 7 branch before this ternary; other tags' value is string or null.
-//   * _gn trailing `: ""` -- a decoded GeneralName always carries a bytes Buffer, so the
+//   * _gn trailing `: ""`. A decoded GeneralName always carries a bytes Buffer, so the
 //     Buffer.isBuffer(g.bytes) arm is always taken.
-//   * _gnRaw `if (!Buffer.isBuffer(buf)) return "";` -- the sole caller (the CRL-DP fullName loop)
+//   * _gnRaw `if (!Buffer.isBuffer(buf)) return "";`. The sole caller (the CRL-DP fullName loop)
 //     guards Buffer.isBuffer(nm) before calling _gnRaw.
 
 // Shared value renderers reused by more than one extension key.
@@ -281,7 +281,7 @@ function _renderCrlDp(decoded, inner) {
       if (rf.length) { dpLines.push(inner + "Reasons: " + rf.join(", ")); wrote = true; }
     }
     // A DistributionPoint may carry only cRLIssuer (an indirect CRL, no
-    // distributionPoint) -- render the issuer GeneralNames rather than dropping them.
+    // distributionPoint): render the issuer GeneralNames, never drop them.
     if (dp.cRLIssuer && Array.isArray(dp.cRLIssuer.names)) {
       dpLines.push(inner + "CRL Issuer:");
       dp.cRLIssuer.names.forEach(function (g) { dpLines.push(inner + "  " + _gn(g)); });
@@ -296,17 +296,17 @@ function _renderCrlDp(decoded, inner) {
 // strict decoders already narrow the shape:
 //   * _renderAltName `(decoded.names || [])` -- the subjectAltName/issuerAltName decoder always
 //     yields a names array.
-//   * _renderCrlDp `(decoded || [])` -- the cRLDistributionPoints/freshestCRL decoder always
+//   * _renderCrlDp `(decoded || [])`. The cRLDistributionPoints/freshestCRL decoder always
 //     yields an array.
-//   * _renderCrlDp `: _gn(nm)` -- distributionPointName surfaces fullName entries as raw
+//   * _renderCrlDp `: _gn(nm)`. distributionPointName surfaces fullName entries as raw
 //     GeneralName Buffers, so Buffer.isBuffer(nm) is always true.
-//   * _renderCrlDp `if (!wrote) ... "(distribution point)"` -- crlDistributionPoints throws unless
+//   * _renderCrlDp `if (!wrote) ... "(distribution point)"`. crlDistributionPoints throws unless
 //     a distributionPoint (always fullName/rdn) or cRLIssuer (sets wrote) is present, so !wrote
 //     never holds.
 
 // Declarative extension-value renderer registry: extension name -> (decoded, inner) ->
 // text. Data-driven dispatch (the schema family's "registry, not switch" shape) so a
-// new extension is a row rather than another hand-coded branch, and the set an
+// new extension is a row, never another hand-coded branch, and the set an
 // operator sees rendered is visible in one place. An extension with no row here
 // hex-dumps its raw value (best-effort); each row's output is pinned by an
 // inspect.test.js conformance vector.
@@ -366,7 +366,7 @@ var EXT_RENDERERS = {
       lines.push(inner + "Policy: " + p.policyIdentifier);
       if (!Buffer.isBuffer(p.qualifiersBytes)) return;
       // Render each PolicyQualifierInfo { policyQualifierId, qualifier }: a printable
-      // qualifier (a CPS URI is an IA5String) shows as text, else a hex dump -- never
+      // qualifier (a CPS URI is an IA5String) shows as text, else a hex dump, and is never
       // dropped (which would make a qualified policy look unqualified).
       try {
         (asn1.decode(p.qualifiersBytes).children || []).forEach(function (pqi) {
@@ -379,9 +379,9 @@ var EXT_RENDERERS = {
           // qualifier exists to display. Render its DisplayText members through the shared pkix
           // reader (the same one pki.lint measures), so both agree on what the notice says.
           if (qid === OID_UNOTICE) {
-            // Render only when EVERY member decoded under its declared string type. A null text means
+            // Render only when every member decoded under its declared string type. A null text means
             // the value did not, and showing the members that happened to decode would present a
-            // partial notice as a complete one -- so the whole qualifier falls through to the hex
+            // partial notice as a complete one, so the whole qualifier falls through to the hex
             // dump, where the operator sees the bytes the certificate actually holds.
             // A null noticeNumbers means the reference did not fully decode, and is refused for the
             // same reason as a null text: a partially decoded notice must not be shown as a whole one.
@@ -414,15 +414,15 @@ var EXT_RENDERERS = {
   authorityInfoAccess: function (decoded, inner) {
     // AccessDescription list: <accessMethod> - <accessLocation>. The method resolves to its name (caIssuers /
     // ocsp); the accessLocation is a GeneralName (a URI in the common case). An unregistered method / an
-    // uncommon accessLocation tag falls back to the raw OID / bracketed tag rather than dropping the entry.
+    // uncommon accessLocation tag falls back to the raw OID / bracketed tag, and the entry is never dropped.
     var LABEL = { caIssuers: "CA Issuers", ocsp: "OCSP" };
     return (decoded || []).map(function (ad) {
       var m = null;
       try { m = oid.name(ad.accessMethod); } catch (_e) { /* allow:swallow-unverified display best-effort: an unregistered accessMethod OID falls back to the raw dotted OID below (inspection is best-effort, never a verdict) */ }
       var loc = ad.accessLocation || {}, lv;
       // The string choices (URI/DNS/email) are IA5String values already control-byte-rejected at decode by the
-      // CVE-2009-2408 guard, so they are safe to emit directly. The iPAddress choice is a RAW 4/16-byte Buffer --
-      // render it through _ipString (never raw), so a byte such as 0x0a cannot inject a line and spoof a field.
+      // CVE-2009-2408 guard, so they are safe to emit directly. The iPAddress choice is a raw 4/16-byte Buffer,
+      // so render it through _ipString (never raw) and a byte such as 0x0a cannot inject a line and spoof a field.
       if (loc.tag === 6) lv = "URI:" + loc.value;
       else if (loc.tag === 2) lv = "DNS:" + loc.value;
       else if (loc.tag === 1) lv = "email:" + loc.value;
@@ -477,7 +477,7 @@ var EXT_RENDERERS = {
   },
   authorityKeyIdentifier: function (decoded, inner) {
     // Any of the three fields may be present; the issuer+serial form carries no
-    // keyIdentifier, so render whichever the decoder populated rather than claiming
+    // keyIdentifier, so render whichever the decoder populated, never claiming
     // "keyid:(none)" and dropping the certificate's real authority identifier.
     var akiLines = [];
     if (Buffer.isBuffer(decoded.keyIdentifier)) akiLines.push(inner + "keyid:" + _hexColon(decoded.keyIdentifier, { upper: true }));
@@ -499,29 +499,29 @@ EXT_RENDERERS.msApplicationPolicies = EXT_RENDERERS.certificatePolicies;
 // Coverage residual -- the EXT_RENDERERS entry fallbacks are unreachable because each shared
 // decoder (and asn1.read.oid) already narrows the shape before the renderer runs:
 //   * extKeyUsage `catch (_e) { /* unregistered EKU OID */ }` and certificatePolicies
-//     `catch (_e) { /* unregistered qualifier */ }` -- oid.name returns undefined (never throws)
+//     `catch (_e) { /* unregistered qualifier */ }`. oid.name returns undefined (never throws)
 //     for a well-formed unregistered OID; it throws only on a non-dotted argument, and both OIDs
 //     come from asn1.read.oid (always a valid dotted OID).
-//   * certificatePolicies `(asn1.decode(p.qualifiersBytes).children || [])` -- asn1.decode of the
+//   * certificatePolicies `(asn1.decode(p.qualifiersBytes).children || [])`. asn1.decode of the
 //     assertPolicyQualifiers-validated qualifiers SEQUENCE always yields a children array.
-//   * certificatePolicies `: Buffer.alloc(0)` -- assertPolicyQualifiers requires every
+//   * certificatePolicies `: Buffer.alloc(0)`. assertPolicyQualifiers requires every
 //     PolicyQualifierInfo to be a 2-child SEQUENCE, so pqi.children[1] is always a present node
 //     carrying a bytes Buffer.
-//   * certificatePolicies outer `catch (_e) { ... _hexColon(p.qualifiersBytes, {}) ... }` --
+//   * certificatePolicies outer `catch (_e) { ... _hexColon(p.qualifiersBytes, {}) ... }`.
 //     certificatePolicies already validated qualifiersBytes as a SEQUENCE of 2-child PQIs each
 //     leading with a valid OID, so the re-decode + asn1.read.oid cannot throw.
-//   * policyConstraints `: inner + "(empty)"` -- policyConstraints rejects an empty SEQUENCE
+//   * policyConstraints `: inner + "(empty)"`. policyConstraints rejects an empty SEQUENCE
 //     (>= 1 context field), so requireExplicitPolicy or inhibitPolicyMapping is non-null;
 //     pc.length is never 0.
-//   * SCT `(decoded.scts || [])` / `(decoded.unknownScts || [])` -- ct.parseSctList always returns
+//   * SCT `(decoded.scts || [])` / `(decoded.unknownScts || [])`. ct.parseSctList always returns
 //     both arrays.
-//   * SCT `: 0` -- every scts entry is a decoded v1 SCT with numeric version 0 (unknown-version
+//   * SCT `: 0`. Every scts entry is a decoded v1 SCT with numeric version 0 (unknown-version
 //     SCTs go to unknownScts and are not iterated here).
-//   * SCT `: inner + "(empty SCT list)"` -- ct.parseSctList rejects an empty list and routes every
+//   * SCT `: inner + "(empty SCT list)"`. ct.parseSctList rejects an empty list and routes every
 //     SerializedSCT into scts/unknownScts, so at least one line is always emitted.
-//   * subjectKeyIdentifier `: (decoded.bytes || Buffer.alloc(0))` -- the subjectKeyIdentifier
+//   * subjectKeyIdentifier `: (decoded.bytes || Buffer.alloc(0))`. The subjectKeyIdentifier
 //     decoder returns the KeyIdentifier as a Buffer, so Buffer.isBuffer(decoded) is always true.
-//   * authorityKeyIdentifier `: BigInt(decoded.authorityCertSerialNumber)` -- the AKI decoder reads
+//   * authorityKeyIdentifier `: BigInt(decoded.authorityCertSerialNumber)`. The AKI decoder reads
 //     authorityCertSerialNumber via asn1.read.integerImplicit (a bigint), so typeof === "bigint"
 //     is always true.
 
@@ -535,7 +535,7 @@ function _renderExtValue(ext, decoded, inner) {
 // string; a DER-wrapped character string is decoded and shown; otherwise a hex
 // dump. Never throws.
 var _STRING_TAGS = { 12: 1, 19: 1, 22: 1, 20: 1, 26: 1, 27: 1, 30: 1 }; // UTF8/Printable/IA5/Teletex/Visible/General/BMP
-// A value renders as text only when EVERY byte is a printable, non-control ASCII
+// A value renders as text only when every byte is a printable, non-control ASCII
 // character. A control byte (a bare CR / LF / TAB, etc.) is rejected here so a
 // hostile private-extension value cannot forge or overwrite report lines in a
 // terminal or log -- such a value falls through to the hex dump instead.
@@ -573,7 +573,7 @@ function _extension(ext, pad) {
 
 // A genuine pki.schema.x509.parse result carries this whole shape. The fast path
 // accepts a pre-parsed certificate to skip re-parsing, but a bare or partial object
-// with only a tbsBytes property is NOT a certificate: without this check the renderer
+// with only a tbsBytes property is not a certificate: without this check the renderer
 // would dereference a missing field (c.validity.notBefore, ...) and throw a raw
 // TypeError instead of the documented typed inspect/bad-input (the API's error contract).
 function _looksParsed(o) {
@@ -615,7 +615,7 @@ function _parse(input) {
  * is a PEM string, a DER Buffer, or a `pki.schema.x509.parse` result. A value that
  * is none of those throws `inspect/bad-input`; a malformed certificate throws
  * `inspect/bad-certificate`; but a malformed individual extension is rendered as a
- * hex dump rather than failing the whole report. Pure -- no OpenSSL dependency.
+ * hex dump and does not fail the whole report. Pure, with no OpenSSL dependency.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -766,7 +766,7 @@ function _crlExtension(ext, pad) {
  * revocation date, entry extensions), and the signature. `input` is a PEM string, a
  * DER Buffer, or a `pki.schema.crl.parse` result; a non-CRL throws
  * `inspect/bad-crl`, a wrong-type input `inspect/bad-input`. A malformed individual
- * extension renders as hex rather than failing the report.
+ * extension renders as hex and does not fail the report.
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");

package/lib/ip-utils.js

@@ -10,7 +10,7 @@
 // sec. 2.2 (8 groups of 1-4 hex, one "::" run compressing a contiguous zero run) plus the
 // RFC 4291 sec. 2.5.5.2 / RFC 5952 sec. 5 IPv4-mapped + dual-stack "::ffff:1.2.3.4" tail.
 // This mirrors the vetted validation in the sibling blamejs framework (lib/ip-utils.js);
-// this toolkit keeps its own copy rather than take a runtime dependency (Hard rule #1).
+// this toolkit keeps its own copy, since Hard rule #1 rules out a runtime dependency.
 
 // Strict RFC 791 dotted-quad: four 0-255 octets. Anchored + per-octet repeat-capped (no
 // ReDoS on unbounded input).
@@ -56,7 +56,7 @@ function expandIpv6Hex(ip) {
 // Is `s` a syntactically valid IPv4 or IPv6 textual literal?
 function isIpLiteral(s) { return isIPv4(s) || expandIpv6Hex(s) !== null; }
 
-// Pack an IPv4/IPv6 textual literal to its network-order octets -- 4 for IPv4, 16 for IPv6 --
+// Pack an IPv4/IPv6 textual literal to its network-order octets (4 for IPv4, 16 for IPv6),
 // or null when `s` is not a valid literal. The binary inverse of the textual forms isIPv4 /
 // expandIpv6Hex validate, so a SAN/GeneralName iPAddress (RFC 5280 sec. 4.2.1.6, always a bare
 // host address of 4 or 16 octets) can be given as a string instead of a pre-packed Buffer.

package/lib/jose.js

@@ -11,12 +11,12 @@
  * @intro
  *   The JOSE message envelope (RFC 7515 JWS, RFC 7518 JWA, RFC 7638 JWK
  *   thumbprint), profiled for RFC 8555 ACME but usable on its own. A JWS here
- *   is the Flattened JSON Serialization only -- `{ protected, payload,
- *   signature }` -- with the multi-signature `signatures` member, the
+ *   is the Flattened JSON Serialization only, `{ protected, payload,
+ *   signature }`, with the multi-signature `signatures` member, the
  *   unprotected `header` member, and the RFC 7797 unencoded-payload `b64`
  *   option all structurally forbidden. Every base64url field is decoded by a
- *   STRICT codec (Node's `Buffer.from(s, "base64url")` accepts padding,
- *   whitespace, and non-canonical trailing bits -- all of which are rejected
+ *   strict codec (Node's `Buffer.from(s, "base64url")` accepts padding,
+ *   whitespace, and non-canonical trailing bits, all of which are rejected
  *   here), and every JSON document is read by a bounded reader that rejects a
  *   duplicate member at any nesting depth (the parser-differential smuggling
  *   class `JSON.parse` silently allows).
@@ -24,10 +24,10 @@
  *   Algorithms resolve through an `alg`-keyed registry (ES256/384/512,
  *   RS256/384/512, PS256/384/512, EdDSA, and the RFC 9964 ML-DSA-44/65/87 PQC
  *   rows), never a switch: the registry binds `alg` to a key type and pins the
- *   exact signature byte length BEFORE any crypto call, so `alg:"none"`, a MAC
+ *   exact signature byte length before any crypto call, so `alg:"none"`, a MAC
  *   algorithm on the outer profile, an ES256/RSA-key confusion, and a DER-vs-raw
- *   ECDSA signature all fail closed. `sign` and `verify` are driven by ONE
- *   declarative profile table each -- the same data drives both directions.
+ *   ECDSA signature all fail closed. `sign` and `verify` are each driven by one
+ *   declarative profile table, so the same data drives both directions.
  *
  * @card
  *   RFC 7515 Flattened JWS sign/verify + RFC 7638 JWK thumbprints, ACME-profiled:
@@ -306,10 +306,10 @@ var PRIVATE_JWK_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "k", "priv"];
  * @spec       RFC 7517, RFC 7518
  * @related    pki.jose.sign, pki.jose.thumbprint
  *
- * Assert that a JWK is PUBLIC-ONLY before it is published (embedded in a JWS
+ * Assert that a JWK is public-only before it is published (embedded in a JWS
  * protected header or an ACME External Account Binding payload). A JWK carrying any
  * private member (`d`, the RSA CRT parameters `p`/`q`/`dp`/`dq`/`qi`, the symmetric
- * `k`, or the AKP `priv`) throws `jose/private-key-material` -- so an accidentally
+ * `k`, or the AKP `priv`) throws `jose/private-key-material`, so an accidentally
  * exported private JWK is never sent to a server. Returns the JWK.
  *
  * @example
@@ -334,13 +334,13 @@ function assertPublicJwk(jwk) {
  * @related    pki.jose.sign, pki.jose.parseJson
  *
  * Verify a Flattened JSON JWS against a profile (`opts.profile`, default
- * `"acme-outer"`). Structural rules fail closed BEFORE any crypto: the
+ * `"acme-outer"`). Structural rules fail closed before any crypto: the
  * `signatures`/`header` members and a detached payload are rejected, the
  * protected header is validated against the profile (alg registry, nonce, url,
  * exactly-one-of jwk/kid, crit), and the signature byte length is pinned per alg.
  *
  * `opts.key` names the key the message must be signed under, and it governs: where
- * the profile also permits an embedded header `jwk`, the two must be the SAME key
+ * the profile also permits an embedded header `jwk`, the two must be the same key
  * or the message is refused with `jose/key-mismatch`. They are compared as RFC 7638
  * thumbprints, so member order and members outside the key itself cannot make equal
  * keys look different. Without `opts.key` the embedded `jwk` is used where the
@@ -545,7 +545,7 @@ var THUMBPRINT_MEMBERS = {
  * @spec       RFC 7638, RFC 8037, RFC 9964
  * @related    pki.jose.verify
  *
- * The RFC 7638 JWK SHA-256 thumbprint as base64url: the canonical JSON of ONLY
+ * The RFC 7638 JWK SHA-256 thumbprint as base64url: the canonical JSON of just
  * the key type's required members, lexicographically ordered, no whitespace,
  * hashed. Optional members (`alg`, `use`, `kid`) are excluded, so the same key
  * always yields the same thumbprint (the ACME key-authorization anchor).
@@ -593,7 +593,7 @@ async function thumbprint(jwk) {
  * listing it beside `RS256` is how the HMAC key-confusion class starts. `none`
  * does not exist here at all.
  *
- * Each call returns a fresh array of fresh rows -- the registry that drives
+ * Each call returns a fresh array of fresh rows. The registry that drives
  * verification is never handed out, so nothing a caller does to the result can
  * widen what a signature check accepts.
  *

package/lib/key.js

@@ -8,7 +8,7 @@
  * @intro The key-material lifecycle: export / import a private key as PKCS#8 (`OneAsymmetricKey`,
  *   RFC 5958) or a public key as SPKI (RFC 5280 sec. 4.1.2.7), encrypt / decrypt a private key under
  *   RFC 8018 PBES2 (`EncryptedPrivateKeyInfo`, PBKDF2 + AES-CBC-Pad), and `generate` /
- *   `publicFromPrivate` over every algorithm the WebCrypto engine drives -- RSA, EC, Ed25519/Ed448,
+ *   `publicFromPrivate` over every algorithm the WebCrypto engine drives: RSA, EC, Ed25519/Ed448,
  *   X25519/X448, and the FIPS post-quantum ML-DSA / ML-KEM. Unencrypted export / import DELEGATES to the
  *   WebCrypto `exportKey` / `importKey` PKCS#8 / SPKI encoders (which already emit each algorithm's
  *   `AlgorithmIdentifier.parameters` correctly -- RSA NULL, EC namedCurve, Ed/X ABSENT), so the wrapper
@@ -18,15 +18,15 @@
  * @card Export / import PKCS#8 and SPKI keys and encrypt a private key under RFC 8018 PBES2.
  */
 //
-// PBES2 is composed from lib/pbes2.js (the ONE PBKDF2 + AES-CBC home shared with pki.cms), bound to the key
+// PBES2 is composed from lib/pbes2.js (the single PBKDF2 + AES-CBC home shared with pki.cms), bound to the key
 // namespace through the `_err` error FACTORY + the "key" domain prefix so every reject keeps a key/* code.
-// A MAC-less PBES2-CBC decrypt is not a padding oracle (RFC 8018 sec. 8): every post-derivation failure --
-// a bad PKCS#7 pad OR a valid pad that does not re-parse as a PrivateKeyInfo -- collapses into ONE uniform
+// A MAC-less PBES2-CBC decrypt is not a padding oracle (RFC 8018 sec. 8): every post-derivation failure
+// (a bad PKCS#7 pad, or a valid pad that does not re-parse as a PrivateKeyInfo) collapses into one uniform
 // key/decrypt-failed; the structural pre-derivation faults (a non-PBKDF2 KDF, a non-AES-CBC scheme, an
 // over-cap salt / iteration count, a wrong-length IV, a malformed parameter SEQUENCE) stay distinct and are
-// thrown BEFORE any key derivation, so they leak nothing password-dependent. Unencrypted export / import
-// and publicFromPrivate DELEGATE to the WebCrypto / node key engines rather than re-serialize an
-// AlgorithmIdentifier -- a re-encode is exactly where a params-absent-vs-NULL divergence sneaks back in.
+// thrown before any key derivation, so they leak nothing password-dependent. Unencrypted export / import
+// and publicFromPrivate delegate to the WebCrypto / node key engines and re-serialize no
+// AlgorithmIdentifier. A re-encode is exactly where a params-absent-vs-NULL divergence sneaks back in.
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
@@ -43,17 +43,17 @@ var subtle = webcrypto.webcrypto.subtle;
 var KeyError = frameworkError.KeyError;
 var PemError = frameworkError.PemError;
 function O(n) { return oid.byName(n); }
-// The guard / pbes2 error convention: a (code, msg, cause) FACTORY, never the KeyError class -- pbes2 and
-// the guards invoke it as E(code, msg) with no `new` (a class there crashes on the error path).
+// The guard / pbes2 error convention: a (code, msg, cause) factory, never the KeyError class, because pbes2
+// and the guards invoke it as E(code, msg) with no `new` (a class there crashes on the error path).
 function _err(code, msg, cause) { return new KeyError(code, msg, cause); }
 
 // The operator-facing node cipher name <-> the AES-CBC registry name the PBES2 home speaks.
 var CIPHER_NAME = { "aes-128-cbc": "aes128-CBC", "aes-192-cbc": "aes192-CBC", "aes-256-cbc": "aes256-CBC" };
 
-// import inference: the algorithm OIDs that name exactly ONE WebCrypto algorithm and need no parameters --
+// import inference: the algorithm OIDs that name exactly one WebCrypto algorithm and need no parameters --
 // the Edwards/Montgomery curves and the FIPS post-quantum ML-DSA, ML-KEM, and SLH-DSA (all signing-only or
-// agreement-only, so unambiguous). RSA (sign vs OAEP) and EC (ECDSA vs ECDH) are deliberately ABSENT -- they
-// are ambiguous, so import fails closed and asks for opts.algorithm rather than guess a plausible use.
+// agreement-only, so unambiguous). RSA (sign vs OAEP) and EC (ECDSA vs ECDH) are deliberately absent. Each
+// is ambiguous, so import fails closed there and asks for opts.algorithm.
 var INFER_ALG = {};
 ["Ed25519", "Ed448", "X25519", "X448"].forEach(function (n) { INFER_ALG[O(n)] = { name: n }; });
 [["id-ml-dsa-44", "ML-DSA-44"], ["id-ml-dsa-65", "ML-DSA-65"], ["id-ml-dsa-87", "ML-DSA-87"],
@@ -153,9 +153,9 @@ async function encrypt(privateKey, password, opts) {
  * PBKDF2 key-derivation function and an AES-CBC encryption scheme is accepted; PBES1, PBMAC1, scrypt, and any
  * other `encryptionAlgorithm` fail closed with `key/unsupported-algorithm`.
  *
- * The salt and iteration count are attacker-controlled work: both caps are enforced BEFORE any derivation
+ * The salt and iteration count are attacker-controlled work: both caps are enforced before any derivation
  * (`opts.maxIterations` may lower the cap, never raise it), and a wrong-length IV or malformed parameter set
- * is a typed `key/bad-algorithm-parameters`. A MAC-less PBES2-CBC decrypt is not a padding oracle -- a wrong
+ * is a typed `key/bad-algorithm-parameters`. A MAC-less PBES2-CBC decrypt is not a padding oracle: a wrong
  * password and a valid-pad-but-not-a-PrivateKeyInfo both surface the single uniform `key/decrypt-failed`.
  *
  * @opts
@@ -252,7 +252,7 @@ async function export_(key, opts) {
  * KEY` -- auto-detecting the structure -- into a `CryptoKey`. The WebCrypto algorithm is inferred from the
  * key's OID for the algorithms that name exactly one (Ed25519 / Ed448 / X25519 / X448 / ML-DSA / ML-KEM /
  * SLH-DSA); RSA and EC are ambiguous between signing and key agreement, so `opts.algorithm` must be supplied
- * for them (import fails closed rather than guess a use). Default key usages follow the algorithm and key type.
+ * for them (without it the import fails closed). Default key usages follow the algorithm and key type.
  *
  * @opts
  *   - `algorithm` (string | object) -- the WebCrypto algorithm (required for RSA / EC; overrides inference).
@@ -324,7 +324,7 @@ async function generate(algorithm, opts) {
  *
  * Derive the SubjectPublicKeyInfo (SPKI) public key from a PKCS#8 private key (DER `Buffer`, `PRIVATE KEY`
  * PEM, or extractable private `CryptoKey`). The derivation is delegated to the node key engine, which infers
- * the algorithm from the key structure, so no `AlgorithmIdentifier` is re-encoded -- Ed25519 stays
+ * the algorithm from the key structure, so no `AlgorithmIdentifier` is re-encoded: Ed25519 stays
  * parameters-absent, RSA keeps its NULL, EC keeps its namedCurve.
  *
  * @opts