@blamejs/pki 0.5.7 → 0.5.8

package/lib/webauthn.js

@@ -9,7 +9,7 @@
  *   the attestation object + authenticatorData, decode the COSE credential public
  *   key, and verify each defined attestation-statement format (packed, tpm,
  *   android-key, apple, fido-u2f, none, compound, and android-safetynet behind an
- *   opt-in) -- the attestation-statement signature and each format's structural
+ *   opt-in): the attestation-statement signature and each format's structural
  *   bindings. The attestation CBOR is decoded by the strict,
  *   fail-closed `pki.cbor` codec (WebAuthn keys are CTAP2-canonical), the signature by
  *   `pki.webcrypto`. Chaining the returned x5c trust path to a caller-pinned root via
@@ -66,8 +66,8 @@ function _ucmp(a, b) {
 // A decoded node is a primitive universal INTEGER (so `.content` is a real buffer,
 // not null as it is for a constructed node).
 function _isInteger(node) { return !!node && !node.constructed && node.tagClass === "universal" && node.tagNumber === asn1.TAGS.INTEGER; }
-// alg -> the digest a TPM attestation's certInfo.extraData is taken under (the ONLY
-// consumer). Every ECDSA/RSA algorithm a TPM AIK may sign with -- including the RFC 9864
+// alg -> the digest a TPM attestation's certInfo.extraData is taken under (its only
+// consumer). Every ECDSA/RSA algorithm a TPM AIK may sign with, including the RFC 9864
 // fully-specified ECDSA ids (ESP256/384/512) -- MUST appear here, or the TPM extraData
 // step rejects the attestation before the signature is evaluated. EdDSA (-8/-19/-53) is
 // absent by design: a TPM 2.0 AIK never signs with EdDSA, so such an attestation is
@@ -83,7 +83,7 @@ function _coseAlgHash(alg, E) {
 
 // authData = rpIdHash[32] || flags[1] || signCount[4 BE] || (AT? attestedCredentialData) || (ED? extensions CBOR).
 // A bounded big-endian read: every slice is length-checked before it is taken, so a
-// truncated / oversize field fails closed rather than reading past the buffer.
+// truncated / oversize field fails closed and never reads past the buffer.
 var AAGUID_LEN = 16;
 function _parseAuthData(buf, E) {
   if (!Buffer.isBuffer(buf) || buf.length < 37) throw E("webauthn/bad-auth-data", "authenticatorData is shorter than the 37-byte minimum (RFC WebAuthn sec. 6.1)");
@@ -98,7 +98,7 @@ function _parseAuthData(buf, E) {
   // "backed up" if it is not "backup eligible" (WebAuthn sec. 6.1).
   if (out.flags.bs && !out.flags.be) throw E("webauthn/bad-auth-data", "authenticatorData sets Backup State (BS) without Backup Eligibility (BE) (WebAuthn sec. 6.1)");
   // The reserved flag bits (bit 1 = 0x02, bit 5 = 0x20) are undefined; a conforming
-  // authenticator leaves them 0. Reject a set reserved bit rather than ignore an
+  // authenticator leaves them 0. Reject a set reserved bit; never ignore an
   // unknown flag (WebAuthn sec. 6.1, fail-closed on undefined structure).
   if (flags & 0x22) throw E("webauthn/bad-auth-data", "authenticatorData sets a reserved (RFU) flag bit (WebAuthn sec. 6.1)");
   var off = 37;
@@ -129,7 +129,7 @@ function _parseAuthData(buf, E) {
   } else if (off < buf.length) {
     // authenticatorData is fixed-layout: with the ED flag clear there MUST be no
     // bytes after the attestedCredentialData (RFC WebAuthn sec. 6.1). Trailing
-    // bytes are a malformed structure -- fail closed rather than ignore them.
+    // bytes are a malformed structure, so fail closed and never ignore them.
     throw E("webauthn/bad-auth-data", "authenticatorData has trailing bytes after attestedCredentialData with the ED flag clear");
   }
   return out;
@@ -156,16 +156,16 @@ function _decodeCoseKey(node) {
  * registration -- back into the object `verifyAssertion` takes. `pki.webauthn.verify`
  * returns that object, but the durable form is bytes: the object carries `Buffer`
  * values, so a JSON round trip through a datastore yields
- * `{"type":"Buffer","data":[...]}` rather than the object that went in, and existing
+ * `{"type":"Buffer","data":[...]}` in place of the object that went in, and existing
  * credential stores already hold COSE bytes whoever wrote them. Without this the only
  * routes into the decoder were `parseAttestationObject` and `parseAuthenticatorData`,
- * both of which parse a CONTAINING structure -- so recovering a stored key meant
+ * both of which parse a containing structure, so recovering a stored key meant
  * fabricating an authenticatorData that never existed.
  *
  * The same validation the attestation path applies: the key type, the algorithm, the
  * curve, and the coordinates are checked, and anything that is not a credential COSE
  * key is refused with `webauthn/bad-cose-key`. `verifyAssertion` accepts either form
- * for `credentialPublicKey`, so calling this first is a convenience rather than a step.
+ * for `credentialPublicKey`, so calling this first is a convenience, not a required step.
  *
  * @example
  *   // requires: `attestationObject` / `clientDataHash` -- what a browser returns from a
@@ -1283,23 +1283,23 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *
  * Give it the client data in exactly one of the two forms, neither inferred from the
  * other's absence: the raw `opts.clientDataJSON`, or the SHA-256 digest of it as the
- * second argument. Given the JSON, this reads it -- the ceremony TYPE is checked
+ * second argument. Given the JSON, this reads it: the ceremony type is checked
  * unconditionally, because which ceremony a response belongs to is fixed by the
- * specification rather than chosen by a caller, and a login response replayed into a
+ * specification and never chosen by a caller, and a login response replayed into a
  * registration is exactly what that check stops. The challenge, origin and top-level
  * origin are checked when you supply what you issued, and `clientData.checked` reports
  * which ran. Given only the digest, nothing reads it and `clientData` is null.
  *
  * The verdict field is `attestationVerified`, and the name is the point: a sound
  * attestation statement is not the same claim as an acceptable registration. The
- * statement says nothing about WHICH relying party asked for it, or whether a user
+ * statement says nothing about which relying party asked for it, or whether a user
  * was present -- so an attestation naming another origin's RP ID, with user presence
  * clear, is perfectly sound and must not be registered. Supply `expectedRpId`,
  * `requireUserPresence`, `requireUserVerification` and `allowedAlgorithms` and those
  * are checked here; `bindingChecked` reports which ran, so a check that passed can be
  * told from one that never happened.
  *
- * Four more fields appear only where they mean something, rather than as nulls on every
+ * Four more fields appear only where they mean something, never as nulls on every
  * verdict: `metadata` when the catalogue governed, `anchoredElements` when a trust path
  * was anchored, `compound` for a sec. 8.9 statement's per-element results, and
  * `safetyNet` with `chainValidatedAt` for an android-safetynet response.
@@ -1308,7 +1308,7 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  * `credentialId`, `credentialPublicKey` and the initial `signCount`. The credential key
  * comes back in both forms: the decoded object, and `credentialPublicKeyBytes`, which is
  * what a credential row should hold -- the object carries `Buffer` values, so a JSON round
- * trip through a datastore returns `{"type":"Buffer","data":[...]}` rather than the object
+ * trip through a datastore returns `{"type":"Buffer","data":[...]}` in place of the object
  * that went in. `pki.webauthn.parseCoseKey` reads those bytes back, and
  * `verifyAssertion` accepts either form.
  *
@@ -1317,10 +1317,10 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *   certInfo Name/extraData, the android KeyDescription, the fido-u2f verificationData).
  *   Chaining the returned `trustPath` (the x5c certificates in `pki.path.validate`
  *   order -- anchor-adjacent first, leaf last) to a trusted root is a separate step,
- *   and there are three ways to take it. Pass `opts.metadata` -- a
+ *   and there are three ways to take it. Pass `opts.metadata`, a
  *   `pki.webauthn.verifyMetadataBlob` result -- and the authenticator's registered
  *   attestation roots are resolved from its own identifier and the trust path is
- *   required to reach one, so an unlisted or revoked model is refused rather than
+ *   required to reach one, so an unlisted or revoked model is refused and never
  *   reported as verified. Pass `opts.rootCertificates` and the path is required to
  *   validate to a root you pin: this is what anchors the formats the catalogue does
  *   not cover, since Apple does not publish its authenticators to the FIDO Metadata
@@ -1343,7 +1343,7 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *   but it does mean "anchored" covered fewer elements than the statement holds.
  *
  * @opts
- *   clientDataJSON    -- the RAW clientDataJSON bytes; supply this OR the digest argument
+ *   clientDataJSON    the raw clientDataJSON bytes; supply this or the digest argument
  *   expectedChallenge -- the challenge bytes this ceremony issued (needs clientDataJSON)
  *   expectedOrigin    -- the origin string, or an array of acceptable origins
  *   expectedTopOrigin -- the acceptable top-level origin(s), or null to require an
@@ -1802,7 +1802,7 @@ void constants;
  * @related pki.webauthn.verify, pki.webauthn.metadataFor
  *
  * Verify a FIDO Metadata Service BLOB -- the signed catalogue of every registered
- * authenticator model, its attestation roots, and its certification status -- and
+ * authenticator model, its attestation roots, and its certification status, and
  * return its entries indexed by aaguid for lookup. `blob` is caller-supplied bytes or
  * a string; retrieval is out of scope, so this never touches the network.
  *
@@ -1817,7 +1817,7 @@ void constants;
  * still answer for itself: `stale` and `allowStale` for freshness, `rollbackChecked` and
  * the `previousNo` it was compared against for rollback, `statusPolicy` and
  * `rejectUnknownStatus` for the status reading every later lookup will use. A rule that
- * did not run reads as not-run rather than as passed.
+ * did not run reads as not-run, never as passed.
  *
  * @intro No FIDO root ships with this toolkit and there is no trust-on-first-use:
  *   which metadata authority to trust is the operator's decision, exactly as a root
@@ -1833,12 +1833,12 @@ void constants;
  *     rollback check by forgetting to pass it.
  *   - `allowStale` -- accept a BLOB past its `nextUpdate`. Off by default.
  *   - `statusPolicy` -- which status reports disqualify an authenticator: `"any"`
- *     (default -- any disqualifying report ever filed), `"latest-by-date"` (only the
+ *     (the default; any disqualifying report ever filed), `"latest-by-date"` (only the
  *     most recent report counts, so a later remediation clears an earlier revocation),
  *     or a function receiving the raw report array and returning true to deny.
  *   - `rejectUnknownStatus` -- treat a status this toolkit does not recognise as
  *     disqualifying. Off by default: the specification requires an unknown status be
- *     ignored rather than failed on.
+ *     ignored, never failed on.
  *
  * @example
  *   // requires: `mdsBlobBytes` -- the signed BLOB from https://mds3.fidoalliance.org/
@@ -1862,13 +1862,13 @@ void constants;
  * @related pki.webauthn.verifyMetadataBlob, pki.webauthn.metadataAnchors
  *
  * The verified metadata entry for an authenticator model, or `null` when the BLOB
- * lists none. `metadata` is a `verifyMetadataBlob` RESULT, never raw bytes -- so a
+ * lists none. `metadata` is a `verifyMetadataBlob` result, never raw bytes, so a
  * lookup can never be answered out of a BLOB nobody verified.
  *
  * `identifier` is whichever of the catalogue's two key spaces names the authenticator:
- * its aaguid, or -- for a U2F authenticator, which carries none -- the key identifier
+ * its aaguid, or, for a U2F authenticator which carries none, the key identifier
  * of its attestation certificate (RFC 5280 sec. 4.2.1.2 method 1, 40 hex digits). The
- * two are disjoint by shape, so the form is dispatched on rather than guessed at, and
+ * two are disjoint by shape, so the form is dispatched on and never guessed at, and
  * anything matching neither is a miss. The all-zero aaguid means "this authenticator
  * declares no model identity" and matches nothing.
  *
@@ -1889,7 +1889,7 @@ void constants;
  * @defends webauthn-revoked-authenticator-accepted (CWE-299)
  * @related pki.webauthn.metadataFor, pki.path.validate
  *
- * The parsed attestation root certificates a metadata entry registers -- the anchors an
+ * The parsed attestation root certificates a metadata entry registers: the anchors an
  * attestation from that model must chain to. An entry whose status reports disqualify
  * the model registers none: the catalogue exists to say which authenticators are still
  * trusted, so handing back the roots of one it has revoked would answer a different
@@ -1899,11 +1899,11 @@ void constants;
  * does not: pass the verified `metadata` and its own `statusPolicy` governs and its
  * freshness is re-checked, pass `time` and reports are judged as of that instant, pass
  * the `certificate` an attestation actually presented and a report naming a single
- * certificate is judged against that one rather than denying every device the entry
+ * certificate is judged against that one, so the entry does not deny every device it
  * covers. With none of them: any disqualifying report denies, judged now.
  *
- * Decoding is per entry rather than for the
- * whole BLOB on purpose: a handful of certificates in the live metadata do not parse
+ * Decoding is per entry, and deliberately not for the
+ * whole BLOB: a handful of certificates in the live metadata do not parse
  * under a strict decoder, and decoding everything up front would let one vendor's
  * malformed root refuse the entire catalogue for every other authenticator in it.
  *
@@ -1959,7 +1959,7 @@ var CLIENT_DATA_TYPE = Object.assign(Object.create(null), { "webauthn.create": 1
  * the page that framed it, so a relying party that allows framing at all should say
  * which pages may do it. `expectedTopOrigin: null` requires an unframed ceremony,
  * which an origin list cannot express. Whether a ceremony was framed is stated by
- * BOTH `crossOrigin` and `topOrigin` and is only usable when they agree: a response
+ * both `crossOrigin` and `topOrigin` and is only usable when they agree: a response
  * declaring itself cross-origin does not satisfy `null` by omitting the origin, and
  * one that does not declare itself cross-origin makes no framing claim for an origin
  * list to accept.
@@ -2125,7 +2125,7 @@ var _CLIENT_DATA_OPTS = Object.assign(Object.create(null), {
  * @spec W3C WebAuthn Level 3 sec. 6.1
  * @related pki.webauthn.verifyAssertion, pki.webauthn.parseAttestationObject
  *
- * Decode a BARE authenticatorData, fail-closed -- the form an authentication
+ * Decode a bare authenticatorData, fail-closed: the form an authentication
  * assertion returns, with no attestation-object wrapper around it. Same parser the
  * registration path uses: the 37-byte minimum, the reserved (RFU) flag bits, the
  * Backup State / Backup Eligibility rule, the 1..1023 credentialId bound, a
@@ -2165,12 +2165,12 @@ var _ASSERT_OPTS = Object.assign(Object.create(null), {
  * @related pki.webauthn.parseAuthenticatorData, pki.webauthn.verify
  *
  * Verify an authentication assertion's signature: the authenticator signs
- * `authenticatorData || SHA-256(clientDataJSON)` as RAW bytes with the credential
+ * `authenticatorData || SHA-256(clientDataJSON)` as raw bytes with the credential
  * key registered earlier -- no COSE_Sign1 wrapper, so a COSE message verifier is
  * the wrong tool and fails on structure before it ever reaches the signature. An
  * ES256 assertion signature is an ASN.1 DER `SEQUENCE { r, s }`, converted here
  * with the same order-aware reader the attestation path uses, so an r or s outside
- * `[1, n-1]` is refused rather than normalized.
+ * `[1, n-1]` is refused, never normalized.
  *
  * `signatureVerified`, not `verified`: this establishes that the holder of the
  * registered credential key produced this response. What makes the response
@@ -2194,7 +2194,7 @@ var _ASSERT_OPTS = Object.assign(Object.create(null), {
  *   signature         -- the assertion signature bytes
  *   credentialPublicKey -- the stored COSE key (as parseAttestationObject surfaced it)
  *   previousSignCount -- the stored counter, enabling the sec. 7.2 step 21 rule
- *   expectedRpId, requireUserPresence, requireUserVerification, allowedAlgorithms -- the bindings above
+ *   expectedRpId, requireUserPresence, requireUserVerification, allowedAlgorithms: the bindings above
  *
  * @example
  *   // requires: `assertion` -- credential.response from navigator.credentials.get();

package/lib/webcrypto.js

@@ -13,8 +13,8 @@
  *   A zero-dependency W3C Web Cryptography API (`Crypto` / `SubtleCrypto`
  *   / `CryptoKey`) built directly on Node's native `node:crypto`. It is
  *   the toolkit's injectable crypto engine, presented in the standard
- *   WebCrypto shape so operators -- and every higher structure (X.509,
- *   CMS, OCSP) -- reach for one familiar surface.
+ *   WebCrypto shape, so operators, and every higher structure (X.509,
+ *   CMS, OCSP), reach for one familiar surface.
  *
  *   Unlike the browser's built-in `crypto.subtle`, this engine is
  *   **PQC-first without being PQC-only**: the FIPS 204 ML-DSA and FIPS
@@ -31,7 +31,7 @@
  *
  * @card
  *   A zero-dep, PQC-first W3C WebCrypto (`SubtleCrypto`) engine over
- *   `node:crypto` -- ML-DSA + SLH-DSA signatures alongside the full
+ *   `node:crypto`: ML-DSA and SLH-DSA signatures alongside the full
  *   classical algorithm set.
  */
 
@@ -62,7 +62,7 @@ function _toArrayBuffer(buf) {
 
 function _wcErr(code, msg) { return new WebCryptoError(code, msg); }
 // STRICT base64url decode via the shared encoding guard: a missing / non-canonical
-// / non-alphabet value throws webcrypto/data rather than silently importing WRONG
+// / non-alphabet value throws webcrypto/data instead of silently importing wrong
 // key material (the lenient Buffer.from(String(undefined),"base64url") returned a
 // bogus 6-byte key). Node's own canonical JWK export (_rawPublic) round-trips
 // cleanly, so the strictness is benign there and fail-closed on untrusted import.
@@ -82,7 +82,7 @@ function _normalizeAlg(algorithm, who) {
 
 // The counterpart to _normalizeAlg's upper-casing: _normalizeAlg upper-cases every algorithm name for
 // case-insensitive INTERNAL matching, but the name a CryptoKey EMITS on `.algorithm.name` MUST carry the
-// WebCrypto-registered casing, which for a few algorithms is not all-upper -- "RSASSA-PKCS1-v1_5" (lowercase
+// WebCrypto-registered casing, which for a few algorithms is not all-upper: "RSASSA-PKCS1-v1_5" (lowercase
 // v), "Ed25519" / "Ed448" (mixed). Every emitted algorithm.name passes through here so a consumer that
 // compares against the standard name (e.g. a signer matching a CryptoKey to a certificate key) matches.
 var _STD_ALG_NAME = { "RSASSA-PKCS1-V1_5": "RSASSA-PKCS1-v1_5", "ED25519": "Ed25519", "ED448": "Ed448" };
@@ -102,8 +102,8 @@ var HASH_NODE = {
 };
 
 // FIPS 202 extendable-output functions, as message digests. Deliberately a
-// SEPARATE table from HASH_NODE rather than rows added to it: an XOF's output
-// length is a parameter rather than a property of its name, and node:crypto
+// separate table from HASH_NODE, not rows added to it: an XOF's output
+// length is a parameter and not a property of its name, and node:crypto
 // refuses an XOF at every other HASH_NODE consumer (signature, HMAC, HKDF,
 // PBKDF2, OAEP). Widening the shared table would turn those consumers' typed
 // "unsupported hash" rejection into a raw error from the underlying library.
@@ -126,7 +126,7 @@ function _hashNode(h, who) {
 // W3C HMAC get-key-length: an explicit `length` is used as given (validated
 // to a positive multiple of 8, so the byte-level key material is exact and
 // never a raw RangeError out of randomBytes); an OMITTED length defaults to
-// the BLOCK size of the hash -- the HMAC key-pad width -- NOT the digest
+// the block size of the hash, the HMAC key-pad width, and not the digest
 // size. A digest-size default would mint different key material than every
 // conforming WebCrypto for identical inputs, so MACs keyed through this
 // engine would fail to verify elsewhere.
@@ -163,7 +163,7 @@ var SLH_DSA_NODE = {};
 ].forEach(function (s) { SLH_DSA_NODE["SLH-DSA-" + s.toUpperCase()] = "slh-dsa-" + s; });
 
 // The algorithm names each keyed operation recognizes. Membership is checked
-// BEFORE the algorithm/key name binding so an unrecognized algorithm reports
+// before the algorithm/key name binding so an unrecognized algorithm reports
 // NotSupportedError while a recognized-but-wrong-for-this-key one reports
 // InvalidAccessError, matching the W3C error ordering.
 var SIGN_VERIFY_NAMES = {};
@@ -173,9 +173,9 @@ var SIGN_VERIFY_NAMES = {};
 var ENCRYPT_DECRYPT_NAMES = { "RSA-OAEP": true, "AES-GCM": true, "AES-CBC": true, "AES-CTR": true };
 var DERIVE_NAMES = { "ECDH": true, "X25519": true, "X448": true, "HKDF": true, "PBKDF2": true, "X963KDF": true };
 // The secret-key / KDF algorithms whose key material is raw octets (imported via "raw" or a
-// JWK "oct"), NEVER an SPKI / PKCS#8 asymmetric-key structure. importKey("spki"|"pkcs8", ...)
-// under one of these names is unsupported (W3C: NotSupportedError) -- and, without this gate, it
-// would mint a mislabeled CryptoKey wrapping an asymmetric handle AND dodge the algorithm-keyed
+// JWK "oct"), never an SPKI / PKCS#8 asymmetric-key structure. importKey("spki"|"pkcs8", ...)
+// under one of these names is unsupported (W3C: NotSupportedError) and, without this gate, it
+// would mint a mislabeled CryptoKey wrapping an asymmetric handle and dodge the algorithm-keyed
 // pkcs8 pre-validation (e.g. the RFC 9935 ML-KEM CHOICE guard).
 var SECRET_KEY_NAMES = { "AES-GCM": true, "AES-CBC": true, "AES-CTR": true, "AES-KW": true, "HMAC": true, "HKDF": true, "PBKDF2": true, "X963KDF": true };
 
@@ -1197,8 +1197,8 @@ function _curveFromKey(ko) {
  * (either), or `raw` (symmetric, or an uncompressed EC / OKP public
  * point). Throws unless the key was created `extractable`.
  *
- * `raw` is defined for public and secret keys only -- asking for it on a private
- * key throws `webcrypto/not-supported` rather than answering with the public half.
+ * `raw` is defined for public and secret keys only; asking for it on a private
+ * key throws `webcrypto/not-supported` instead of answering with the public half.
  * This matters through `wrapKey`, which forwards the caller's format here: wrapping
  * a private key as `raw` would otherwise escrow the public key, and unwrapping it
  * returns a handle announcing `usages: ["sign"]` that cannot sign, with the private
@@ -1206,7 +1206,7 @@ function _curveFromKey(ko) {
  *
  * A private `jwk` round-trips as a private key for every algorithm, ML-DSA, ML-KEM
  * and SLH-DSA included: those are `kty: "AKP"` and carry the private half in `priv`
- * rather than the `d` an EC or OKP key uses.
+ * in place of the `d` an EC or OKP key uses.
  *
  * @example
  *   var keyPair = await pki.webcrypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);

package/lib/x509-sign.js

@@ -8,18 +8,18 @@
  * @title      Certificates
  * @intro The X.509 certificate-issuance producing side. `pki.x509.sign` builds a `TBSCertificate`,
  *   signs it, and emits a `Certificate` (RFC 5280 sec. 4) that `pki.schema.x509.parse`,
- *   `pki.path.validate`, and OpenSSL all accept -- self-signed or CA-signed, over any signature
+ *   `pki.path.validate`, and OpenSSL all accept, self-signed or CA-signed, over any signature
  *   algorithm the toolkit registry resolves: RSA (PKCS#1 v1.5 / PSS), ECDSA, EdDSA, ML-DSA, SLH-DSA,
  *   and the composite (hybrid) arms. Parsing lives at `pki.schema.x509.parse`.
  * @spec RFC 5280
- * @card Build and sign an X.509 certificate -- self-signed or CA-signed, over any registry algorithm.
+ * @card Build and sign an X.509 certificate, self-signed or CA-signed, over any registry algorithm.
  */
 //
 // The whole algorithm matrix comes from the shared sign-scheme resolver (the same registry
 // pki.cms.sign / pki.tsp.sign drive), so a new algorithm is a registry row, never a branch here. The
 // TBS + extension DER is hand-assembled through the canonical asn1.build.* layer (the shipped
 // cms/tsp/ocsp producing pattern); the strict schema-x509 decoder round-trips it, and that round-trip
-// -- plus OpenSSL interop -- is the divergence guard.
+// (plus OpenSSL interop) is the divergence guard.
 
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
@@ -32,12 +32,12 @@ var pkix = require("./schema-pkix");
 var pkiBuild = require("./pki-build");
 
 var CertificateError = frameworkError.CertificateError;
-// The x509 schema namespace + Name parser -- the SAME RDNSequence parser pki.schema.x509.parse uses, so
+// The x509 schema namespace and Name parser: the same RDNSequence parser pki.schema.x509.parse uses, so
 // a raw Name DER is validated fully (structure, DirectoryString types) with the frozen x509/* codes.
 var NS = pkix.makeNS("x509", CertificateError, oid);
 var NAME_SCHEMA = pkix.name(NS);
 var SPKI_SCHEMA = pkix.spki(NS);
-// The SAME RFC 5280 sec. 4.2.1 extension value decoders pki.schema.x509.parse uses, so a recognized
+// The same RFC 5280 sec. 4.2.1 extension value decoders pki.schema.x509.parse uses, so a recognized
 // pre-encoded (array-form) extension is fully validated with the frozen x509/* codes.
 var EXT_DECODERS = pkix.certExtensionDecoders(NS).byOid;
 var b = asn1.build;
@@ -60,7 +60,7 @@ var KNOWN_EXT_KEYS = {
 
 // The shared PKIX producing primitives (lib/pki-build.js), bound to the x509 namespace so they keep the
 // frozen x509/* codes. Thin local aliases let the x509 call sites read unchanged. csr-sign binds the same
-// builder to its own namespace (Hard rule #5 -- one encode definition, no per-format hand-roll).
+// builder to its own namespace: one encode definition, no per-format hand-roll.
 var _b = pkiBuild.makeBuilder({ ErrorClass: CertificateError, prefix: "x509", O: O, NS: NS, NAME_SCHEMA: NAME_SCHEMA, SPKI_SCHEMA: SPKI_SCHEMA, EXT_DECODERS: EXT_DECODERS });
 var _encodeName = _b.encodeName, _isEmptyName = _b.isEmptyName, _reqDer = _b.reqDer,
   _assertValidSpki = _b.assertValidSpki, _assertValidExtension = _b.assertValidExtension,
@@ -91,7 +91,7 @@ function _akiKeyId(val, ctx) {
 function _buildExtensions(extSpec, ctx) {
   if (extSpec == null) return [];
   if (Array.isArray(extSpec)) {
-    // Validate each pre-encoded extension, reject a duplicate extnID (RFC 5280 sec. 4.2 -- at most one
+    // Validate each pre-encoded extension, reject a duplicate extnID (RFC 5280 sec. 4.2 allows at most one
     // instance of an extension), and decode basicConstraints + keyUsage to apply the same CA
     // cross-field rules the object form enforces (below), so the array escape hatch cannot bypass them.
     var seenExt = {}, arrCa = false, arrKeyCertSign = false, arrPathLen = false;
@@ -129,7 +129,7 @@ function _buildExtensions(extSpec, ctx) {
     return arr;
   }
   if (typeof extSpec !== "object") throw _err("x509/bad-input", "extensions must be an object or an array of pre-encoded Extension DER");
-  // Reject a typo'd / unsupported extension key at config-time rather than silently dropping it (a
+  // Reject a typo'd or unsupported extension key at config-time instead of silently dropping it (a
   // misspelled `keyUsag` would otherwise omit keyUsage). A custom extension goes in the array form.
   guard.identifier.assertKnownKeys(extSpec, KNOWN_EXT_KEYS, _err, "x509/bad-input", function (k) {
     return "unknown extension " + JSON.stringify(k) + " in the extensions spec; pass a pre-encoded Extension DER via the array form for a custom extension";
@@ -169,8 +169,8 @@ function _buildExtensions(extSpec, ctx) {
 // thin wrapper here so the certificate validity label reads "certificate notBefore/notAfter".
 function _timeDer(date, which) { return _b.timeDer(date, "certificate " + which); }
 // A supplied issuer certificate MUST be a CA that may sign certificates: basicConstraints present AND
-// critical AND cA=TRUE (RFC 5280 sec. 4.2.1.9), and -- when a keyUsage extension is present -- the
-// keyCertSign bit (sec. 4.2.1.3). Refuse a non-CA issuer rather than mint a certificate that will not
+// critical AND cA=TRUE (RFC 5280 sec. 4.2.1.9), plus, when a keyUsage extension is present, the
+// keyCertSign bit (sec. 4.2.1.3). Refuse a non-CA issuer instead of minting a certificate that will not
 // chain. Returns the issuer's pathLenConstraint (or null) so the caller can honor it.
 function _assertIssuerIsCa(issuerCert) {
   var exts = issuerCert.extensions || [];
@@ -237,8 +237,8 @@ function _hasCriticalSan(extSpec) {
  * key being certified), `notBefore` / `notAfter` (`Date`s), an optional `serialNumber`, and an optional
  * `extensions` object. `issuer` is the signing side: `{ key }` alone issues a self-signed certificate
  * (issuer = subject, signed with the subject's own key); `{ name, publicKey, key }` or `{ cert, key }`
- * issues a CA-signed one. The signature algorithm is resolved from the signing key -- RSA (PKCS#1 v1.5
- * or PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm -- so every algorithm the
+ * issues a CA-signed one. The signature algorithm is resolved from the signing key: RSA (PKCS#1 v1.5
+ * or PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm, so every algorithm the
  * toolkit signs with is available here without a per-algorithm branch.
  *
  * The version is derived from the field set (v3 when extensions are present, else v1). Serial bounds
@@ -251,7 +251,7 @@ function _hasCriticalSan(extSpec) {
  *
  * @opts
  *   - `pem` (boolean) -- return a PEM `CERTIFICATE` 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -70,6 +70,7 @@
     "fuzz": "npm ci --prefix fuzz && npx --prefix fuzz jazzer fuzz/asn1-der.fuzz.js -- -max_total_time=60",
     "gates": "node test/layer-0-primitives/codebase-patterns.test.js && node scripts/validate-source-comment-blocks.js && node scripts/check-api-snapshot.js",
     "coverage": "c8 --include=lib/** --include=index.js --reporter=text-summary --reporter=lcov node test/smoke.js",
+    "check:prose": "node scripts/check-operator-prose.js",
     "check:swallows": "node scripts/check-swallow-coverage.js",
     "coverage:gated": "npm run coverage && npm run check:swallows",
     "coverage:unified": "node scripts/coverage-unified.js",
@@ -79,7 +80,7 @@
   },
   "devDependencies": {
     "c8": "12.0.0",
-    "esbuild": "0.28.1",
+    "esbuild": "0.28.2",
     "eslint": "10.8.1"
   }
 }

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:a8c014a2-3631-443a-b33d-f10501d992fb",
+  "serialNumber": "urn:uuid:7e436b38-9f18-4222-a517-c69211740ba0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-16T09:48:05.398Z",
+    "timestamp": "2026-08-18T02:52:33.662Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.7",
+      "bom-ref": "@blamejs/pki@0.5.8",
       "type": "application",
       "name": "pki",
-      "version": "0.5.7",
+      "version": "0.5.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.5.7",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.7",
+      "ref": "@blamejs/pki@0.5.8",
       "dependsOn": []
     }
   ]