@blamejs/pki 0.6.28 → 0.6.30

package/lib/sigstore.js

@@ -17,7 +17,7 @@
  *   ephemeral, ~10 minutes); the Rekor inclusion proof folded to a Rekor-signed
  *   tree root; the log entry binding to this exact signature; and the in-toto
  *   subject digest the caller confirms against the published artifact. Verify-only
- *   and offline -- every input is in the bundle or a caller argument. Reuses the
+ *   and offline: every input is in the bundle or a caller argument. Reuses the
  *   shipped X.509 parser, RFC 5280 path validator, RFC 9162 Merkle verifier, and
  *   native crypto engine; the net-new codecs are the DSSE PAE byte-builder and a
  *   fail-closed JSON bundle reader.
@@ -102,7 +102,7 @@ function _jsonParse(input, code, label) {
  * LEN(body) SP body`, where `LEN` is the ASCII-decimal byte length (no leading
  * zeros) and `type` is the UTF-8 `payloadType`. This is the exact preimage a DSSE
  * signature covers; `LEN` is over the decoded body byte length, never the base64
- * length -- any deviation is a signature-verify bypass.
+ * length. Any deviation is a signature-verify bypass.
  *
  * @example
  *   var b = pki.sigstore.pae("application/vnd.in-toto+json", Buffer.from("{}"));

package/lib/smime.js

@@ -12,11 +12,11 @@
  * @intro
  *   RFC 8551 S/MIME assembly + verification + encryption over the shipped CMS
  *   layer. `sign` wraps a MIME entity as a signed S/MIME message and `verify`
- *   unwraps and verifies one, in both forms: `multipart/signed` (clear-signed --
+ *   unwraps and verifies one, in both forms: `multipart/signed` (clear-signed:
  *   the content stays readable, a detached CMS signature rides alongside) and
  *   `application/pkcs7-mime` (opaque, where the whole entity is a base64 CMS
  *   SignedData). `encrypt` envelopes a MIME entity as an opaque
- *   `application/pkcs7-mime` message and `decrypt` opens one -- `authEnveloped-data`
+ *   `application/pkcs7-mime` message and `decrypt` opens one: `authEnveloped-data`
  *   (AES-GCM, confidentiality AND integrity, the default) or `enveloped-data`
  *   (AES-CBC, confidentiality only, so `decrypt` surfaces `authenticated:false`,
  *   the EFAIL / RFC 8551 sec. 3.3 no-integrity caveat). The crypto is entirely
@@ -469,7 +469,7 @@ function _base64Body(der) {
  * Assemble a signed S/MIME message (RFC 8551). `content` is the payload: a raw body wrapped as a
  * `text/plain` entity by default, or the caller's own complete MIME entity when `opts.entity` is set;
  * `signers` is the `pki.cms.sign` signer array (any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA
- * signer -- the S/MIME layer is algorithm-agnostic). Two forms via `opts.form`:
+ * signer: the S/MIME layer is algorithm-agnostic). Two forms via `opts.form`:
  *   - `"multipart"` (default, clear-signed): a `multipart/signed` message carrying the canonical entity
  *     verbatim in the first part and a DETACHED CMS SignedData (`application/pkcs7-signature`) over its
  *     canonical form in the second, with `protocol="application/pkcs7-signature"` + a matching `micalg`.
@@ -490,7 +490,7 @@ function _base64Body(der) {
  * @opts hcp         the Header Confidentiality Policy applied to the OUTER display copies: `"hcp_baseline"` (default) or `"hcp_no_confidentiality"`. A signed message's payload is not encrypted, so this governs presentation, not secrecy; used with `protectHeaders`.
  * @opts sid                       forwarded to cms.sign: the SignerIdentifier form, `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
  * @opts signedAttributes          forwarded: `false` omits the signed-attributes set entirely (a bare-signature SignedData).
- * @opts additionalSignedAttributes forwarded: extra signed attributes to carry, as `[{ oid, values }]`.
+ * @opts additionalSignedAttributes forwarded: extra signed attributes to carry, as `[{ type, values }]`.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
@@ -547,7 +547,7 @@ function _capped(msg) {
  *
  * `valid` and `trusted` are separate claims, exactly as in `cms.verify`: a SignedData carries its own
  * certificates, so `valid` says the signature is sound under one of them and nothing about who signed.
- * Name the roots you accept in `opts.trustAnchors` and `trusted` says every signer chained to one --
+ * Name the roots you accept in `opts.trustAnchors` and `trusted` says every signer chained to one,
  * validated for EMAIL, at both ends of the chain. The signer certificate must carry the
  * `emailProtection` key purpose (RFC 8551 sec. 4.4.4), because a certificate restricted to `serverAuth`
  * chains to its root perfectly well and is still the wrong key to have signed a message; and the anchor's
@@ -557,8 +557,8 @@ function _capped(msg) {
  * A `micalg`
  * that disagrees with the actual digest is advisory unless `opts.strictMicalg` (then `smime/micalg-mismatch`).
  * If the message is header-protected (RFC 9788), `protectedHeaders` is the AUTHENTICATED inner header set (a
- * tampered outer header cannot alter it) and `headerProtection` is `{ present, mode, fromMismatch, confidential, legacy }`
- * -- `present` is `true` only for cryptographically-DECLARED (`hp=`) protection you may trust; `fromMismatch` is
+ * tampered outer header cannot alter it) and `headerProtection` is `{ present, mode, fromMismatch, confidential, legacy }`.
+ * `present` is `true` only for cryptographically-DECLARED (`hp=`) protection you may trust; `fromMismatch` is
  * `true` when the outer From differs from the protected one, `false` when they agree, and `null` when there was
  * no protected From to compare against, which is every message without header protection. Test it against
  * `false` rather than for falsiness: `!fromMismatch` treats the unanswered case as a passed check, and that is
@@ -569,7 +569,7 @@ function _capped(msg) {
  * whose declared `hp` is malformed, invalid, or contradicts the envelope fails closed (`smime/bad-header-protection`),
  * never a silent downgrade. `legacy` is `null` unless `opts.legacyHeaderProtection` detected a legacy RFC 8551
  * `message/rfc822` wrap (see that option), in which case it is its own `{ headers, mode, fromMismatch, confidential }`
- * object (`headers` an ordered `[{ name, value }]` array that retains legally-repeated fields like `Received`) -- a
+ * object (`headers` an ordered `[{ name, value }]` array that retains legally-repeated fields like `Received`). A
  * legacy inference is never placed in `protectedHeaders` and never sets `present: true`, because it is
  * indistinguishable from an ordinary forwarded `message/rfc822`, so a caller keying trust off `present` /
  * `protectedHeaders` cannot mistake the opt-in heuristic for authenticated headers.
@@ -582,12 +582,12 @@ function _capped(msg) {
  * extension carries none, from the subject DN's PKCS #9 `emailAddress` attribute, which RFC 8550 sec. 3
  * requires a receiving agent to recognize. Where both are present the extension wins. Only a signer
  * whose signature verified contributes an identity, so a tampered message cannot report a binding. `match` is THREE-valued and a caller enforcing sender binding tests
- * `match === true` -- `false` means every identity was comparable and none matched, and `null` means the
+ * `match === true`; `false` means every identity was comparable and none matched, and `null` means the
  * question was not answered (no `expectedSender` and no single outer `From`, a signer certificate
  * asserting no readable email identity, or an internationalized address needing an IDNA transform this
  * toolkit does not perform). `null` is not a pass. `sender.identities` lists what the certificate
  * actually asserts, `sender.checked` whether a comparison ran, and `sender.source` which input it ran
- * against -- `"from"` is ADVISORY, because on a message without header protection the outer From is
+ * against. `"from"` is ADVISORY, because on a message without header protection the outer From is
  * attacker-controlled.
  *
  * @opts certs        extra signer certificates (DER `Buffer`s) to match, forwarded to `cms.verify`.
@@ -687,7 +687,7 @@ function _cmsEncryptOpts(opts) {
  * @related    pki.smime.decrypt, pki.cms.encrypt
  *
  * Envelope a MIME entity as an encrypted S/MIME message (RFC 8551 sec. 3.3 / sec. 3.4). `content` is the
- * payload -- a raw body wrapped as a `text/plain` entity by default, or the caller's own complete MIME
+ * payload: a raw body wrapped as a `text/plain` entity by default, or the caller's own complete MIME
  * entity when `opts.entity` is set; `recipients` is the `pki.cms.encrypt` recipient array (any RSA-OAEP
  * ktri / EC or X25519/X448 kari / ML-KEM ori-KEM / password pwri / kek kekri: the S/MIME layer is
  * recipient-agnostic; a single descriptor is accepted and normalized to a one-element array). Enveloping
@@ -697,7 +697,7 @@ function _cmsEncryptOpts(opts) {
  * with `smime-type=enveloped-data` (confidentiality only, no integrity, RFC 8551 sec. 3.3). With
  * `opts.protectHeaders`, the message is header-protected (RFC 9788): the real `opts.headers` are inlined
  * inside the ciphertext (the payload Content-Type gains `hp="cipher"`), and only the Header-Confidentiality-
- * Policy-processed display copies appear outside -- the default `hcp_baseline` obscures Subject to `[...]`
+ * Policy-processed display copies appear outside. The default `hcp_baseline` obscures Subject to `[...]`
  * and removes Comments / Keywords, so those values live only in the ciphertext; `decrypt` recovers the real
  * inner set. Returns the assembled message bytes. Fail-closed with `SmimeError`.
  *
@@ -740,7 +740,7 @@ async function encrypt(content, recipients, opts) {
  * @spec       RFC 8551, RFC 5652, RFC 5083, RFC 9788
  * @related    pki.smime.encrypt, pki.cms.decrypt, pki.smime.verify
  *
- * Open an encrypted S/MIME message (RFC 8551 sec. 3.3 / sec. 3.4) -- an `application/pkcs7-mime` entity
+ * Open an encrypted S/MIME message (RFC 8551 sec. 3.3 / sec. 3.4), an `application/pkcs7-mime` entity
  * whose base64 body is a CMS EnvelopedData or AuthEnvelopedData. `keyMaterial` is the `pki.cms.decrypt`
  * key material (`{ key, cert }`, `{ password }`, or `{ kek, kekId? }`). Returns the recovered inner MIME
  * entity as `content`, the `smimeType`, `authenticated` (true only for AuthEnvelopedData; a CBC
@@ -753,7 +753,7 @@ async function encrypt(content, recipients, opts) {
  * (RFC 9788, `hp="cipher"`), `protectedHeaders` is the recovered real inner header set (the values the outer
  * Header Confidentiality Policy hid) and `headerProtection` is `{ present, mode, fromMismatch, confidential, legacy }`,
  * where `present` is `true` only for a declared `hp=` payload, and `confidential` names the fields the composer
- * kept end-to-end confidential (via the authenticated HP-Outer records, RFC 9788 sec. 4.3) -- so a caller can
+ * kept end-to-end confidential (via the authenticated HP-Outer records, RFC 9788 sec. 4.3), so a caller can
  * reply/forward without leaking them (sec. 6.1); a payload whose `hp` is malformed or contradicts the envelope
  * fails closed (`smime/bad-header-protection`). `legacy` is `null` unless `opts.legacyHeaderProtection` detected a
  * legacy RFC 8551 `message/rfc822` wrap (its own `{ headers, mode, fromMismatch, confidential }` object, where `headers`
@@ -806,7 +806,7 @@ async function decrypt(message, keyMaterial, opts) {
  * @related    pki.smime.decompress, pki.cms.compress
  *
  * Compress a MIME entity as an opaque compressed S/MIME message (RFC 8551 sec. 3.6). `content` is the
- * payload -- a raw body wrapped as a `text/plain` entity by default, or the caller's own complete MIME
+ * payload: a raw body wrapped as a `text/plain` entity by default, or the caller's own complete MIME
  * entity when `opts.entity` is set. The entity is canonicalized (RFC 8551 sec. 3.1) and ZLIB-compressed
  * into a CMS `CompressedData` (`pki.cms.compress`), carried opaque in one `application/pkcs7-mime;
  * smime-type=compressed-data; name=smime.p7z` entity (base64). Compression is a size transform with NO
@@ -838,7 +838,7 @@ async function compress(content, opts) {
  * @spec       RFC 8551, RFC 3274
  * @related    pki.smime.compress, pki.cms.decompress, pki.smime.verify, pki.smime.decrypt
  *
- * Decompress a compressed S/MIME message (RFC 8551 sec. 3.6) -- an `application/pkcs7-mime` entity whose
+ * Decompress a compressed S/MIME message (RFC 8551 sec. 3.6), an `application/pkcs7-mime` entity whose
  * base64 body is a CMS `CompressedData`. Returns the recovered inner MIME entity as `content` plus the
  * inner `contentType` / `contentTypeName` and the `compressionAlgorithm`. The inflate is BOUNDED (a
  * decompression-bomb defense, `cms/decompress-too-large`; `opts.maxOutputBytes` tightens it downward).

package/lib/tls-cert-compress.js

@@ -11,7 +11,7 @@
  *
  * @intro
  *   TLS handshake structures that carry certificates. `decompressCertificate`
- *   and `compressCertificate` are the RFC 8879 `CompressedCertificate` codec --
+ *   and `compressCertificate` are the RFC 8879 `CompressedCertificate` codec:
  *   the compressed form of a TLS 1.3 `Certificate` message, which shrinks the
  *   largest thing a handshake sends and matters most for post-quantum chains,
  *   where certificates grow by kilobytes. `parseCertificateMessage` decodes the
@@ -30,10 +30,10 @@
  *   allocated), and the output must then equal that length exactly (which catches
  *   the under-length direction a cap cannot see). The caller's policy cap applies
  *   independently, so a peer declaring 16 MiB does not get 16 MiB. This module
- *   decodes structure only -- it never verifies a certificate, builds a path, or
+ *   decodes structure only. It never verifies a certificate, builds a path, or
  *   speaks the handshake.
  *
- *   All three registered algorithms -- zlib, brotli and zstd -- are implemented,
+ *   All three registered algorithms (zlib, brotli and zstd) are implemented,
  *   and each is offered only where the running Node can decompress it safely. A
  *   decompressor must fault on a frame it could not finish; where one instead
  *   returns a short result and reports the whole input consumed, a peer could cut
@@ -44,7 +44,7 @@
  *
  * @card
  *   Encode and decode RFC 8879 TLS compressed certificate messages and the
- *   RFC 8446 Certificate message inside them -- a two-sided decompression
+ *   RFC 8446 Certificate message inside them: a two-sided decompression
  *   bound, exact-length enforcement, per-entry certificate DER surfaced raw,
  *   fail-closed. All three registered algorithms are implemented; each is
  *   offered only where the running Node decompresses it safely.
@@ -138,7 +138,7 @@ function _resolveAllowed(opts) {
  * body is a framing violation (`opaque<1..2^24-1>`), not an empty certificate list.
  *
  * Throws `TlsError` with a stable `tls/*` code on any malformed input, never a raw
- * `TypeError`. Structure only -- no certificate here is verified or path-built.
+ * `TypeError`. Structure only: no certificate here is verified or path-built.
  *
  * @opts
  *   maxOutputBytes   - tighten the decompression cap DOWNWARD from the RFC 8446 sec. 4
@@ -221,8 +221,8 @@ function decompressCertificate(bytes, opts) {
  *
  * Decode an RFC 8446 sec. 4.4.2 `Certificate` message into its
  * `certificateRequestContext` (raw, empty in a server's handshake certificate) and its
- * `entries`. Each entry surfaces `certData` -- the certificate DER exactly as it appeared
- * on the wire, ready for `pki.schema.x509.parse` and never re-serialized, plus the raw
+ * `entries`. Each entry surfaces `certData` (the certificate DER exactly as it appeared
+ * on the wire, ready for `pki.schema.x509.parse` and never re-serialized), plus the raw
  * `extensions` bytes that follow it and `extensionList`, those bytes decoded to their
  * RFC 8446 sec. 4.2 records (`type` and raw `data` per extension). The vector's framing is
  * validated and not accepted opaquely, so a vector that cannot be a whole number of

package/lib/trust.js

@@ -24,8 +24,8 @@
  *   Everything is fail-closed and offline: the caller supplies the text (no
  *   network fetch); every malformed or oversized input throws a typed
  *   `trust/*` error before the offending allocation; a certificate object and
- *   its trust object are paired by byte-exact (CKA_ISSUER, CKA_SERIAL_NUMBER)
- *   -- never by adjacency -- and cross-checked against the parsed DER, so
+ *   its trust object are paired by byte-exact (CKA_ISSUER, CKA_SERIAL_NUMBER),
+ *   never by adjacency, and cross-checked against the parsed DER, so
  *   trust metadata can never attach to the wrong root; only
  *   `CKT_NSS_TRUSTED_DELEGATOR` grants a purpose (everything else, including
  *   an absent bit, is untrusted).
@@ -441,9 +441,9 @@ function _dedupAnchors(anchors) {
  * Parse the Mozilla/NSS `certdata.txt` root-store object stream into
  * constraint-carrying trust anchors. Each CKO_CERTIFICATE object's
  * MULTILINE_OCTAL `CKA_VALUE` is decoded and parsed as a DER certificate; the
- * paired CKO_NSS_TRUST object -- joined by byte-exact CKA_ISSUER +
+ * paired CKO_NSS_TRUST object (joined by byte-exact CKA_ISSUER +
  * CKA_SERIAL_NUMBER, never adjacency, and cross-checked against the parsed
- * DER -- contributes the purpose trust bits (only CKT_NSS_TRUSTED_DELEGATOR
+ * DER) contributes the purpose trust bits (only CKT_NSS_TRUSTED_DELEGATOR
  * grants a purpose); the per-purpose distrust-after dates ride in the
  * certificate object as bare ASCII times routed through the strict DER time
  * reader. Every anchor carries the exact `{ name, publicKey, algorithm,
@@ -641,7 +641,7 @@ function _pemCell(cell) {
  * (`Common Name or Certificate Name`, `Trust Bits`, `Distrust for TLS After
  * Date`, `Distrust for S/MIME After Date`, `PEM Info`) fails closed with
  * `trust/bad-csv`. Fields follow RFC 4180 quoting (embedded commas, newlines,
- * doubled-quote escapes -- the PEM Info column depends on it). `Trust Bits`
+ * doubled-quote escapes; the PEM Info column depends on it). `Trust Bits`
  * is set-valued (Websites -> serverAuth, Email -> emailProtection, Code ->
  * codeSigning; absent -> untrusted). A DATE-only distrust cell expands to the
  * end-of-day `...T23:59:59Z` instant, matching the NSS `...235959Z`

package/lib/tsp-sign.js

@@ -96,8 +96,8 @@ function _signingCertV2(certDer, hashName) {
  * @spec       RFC 3161
  * @related    pki.schema.tsp.parseToken, pki.cms.sign
  *
- * Create an RFC 3161 TimeStampToken over `messageImprint` (`{ hashAlgorithm, hashedMessage }`
- * -- the hash of the data being timestamped, computed by the requester). `tsa` is the
+ * Create an RFC 3161 TimeStampToken over `messageImprint` (`{ hashAlgorithm, hashedMessage }`:
+ * the hash of the data being timestamped, computed by the requester). `tsa` is the
  * timestamp authority's `{ cert, key }` (as `pki.cms.sign` takes them). The token is a CMS
  * SignedData whose content is a `TSTInfo` carrying the imprint, the TSA policy, a serial
  * number, and `genTime`; the RFC 3161 sec. 2.4.2 signing-certificate attribute binding the
@@ -110,6 +110,8 @@ function _signingCertV2(certDer, hashName) {
  * @opts  accuracy      The genTime +/- accuracy, as `{ seconds?, millis?, micros? }`.
  * @opts  ordering      Whether tokens from this TSA are strictly ordered in time (boolean).
  * @opts  certHashAlgorithm  The ESSCertIDv2 hash algorithm name. Default `sha256`.
+ * @opts  digestAlgorithm / pss  Passed through to `pki.cms.sign` (the signer digest algorithm, RSA-PSS padding).
+ * @opts  additionalSignedAttributes  Extra signed attributes to carry on the token, as `[{ type, values }]` (forwarded to `pki.cms.sign`).
  * @opts  sid / pem     Passed through to `pki.cms.sign` (signer identifier, PEM output).
  * @example
  *   var pair = await pki.key.generate("Ed25519");
@@ -303,7 +305,7 @@ function request(messageImprint, opts) {
  * @spec       RFC 3161
  * @related    pki.tsp.request, pki.schema.tsp.parseRequest
  *
- * Parse a `TimeStampReq` (DER `Buffer` or PEM) -- the `pki.schema.tsp.parseRequest` decoder on the
+ * Parse a `TimeStampReq` (DER `Buffer` or PEM), the `pki.schema.tsp.parseRequest` decoder on the
  * `pki.tsp` namespace. Returns `{ version, messageImprint, reqPolicy, reqPolicyName, nonce,
  * nonceHex, certReq, extensions }`; a malformed structure throws a typed `TspError`.
  *
@@ -382,7 +384,7 @@ function response(token, opts) {
  * @spec       RFC 3161
  * @related    pki.tsp.response, pki.schema.tsp.parse
  *
- * Parse a `TimeStampResp` (DER `Buffer` or PEM) -- the shipped `pki.schema.tsp.parse` decoder on
+ * Parse a `TimeStampResp` (DER `Buffer` or PEM), the shipped `pki.schema.tsp.parse` decoder on
  * the `pki.tsp` namespace. Returns `{ status, statusString, failInfo, timeStampToken }` with the
  * status-to-token coupling enforced; a granted response's token is decoded via `parseToken`.
  *
@@ -535,7 +537,7 @@ function _buildTsaChains(leaf, pool) {
  * original bytes (hashed under the token's messageImprint algorithm) or a precomputed
  * `{ hashAlgorithm, hashedMessage }`. Returns `{ valid, trusted, revocationChecked,
  * anchorConstraints, genTime, accuracy, serialNumber,
- * serialNumberHex, policy, nonce, tsa, tstInfo, signer, code?, reason? }`. `valid` is true only
+ * serialNumberHex, policy, policyName, nonce, tsa, tstInfo, signer, code?, reason? }`. `valid` is true only
  * when the CMS signature, the imprint match, the eContentType, the ESSCertID(V2) binding, the
  * RFC 3161 sec. 2.3 critical single-`timeStamping` extendedKeyUsage rule, the requested nonce (when
  * supplied), and, when `trustAnchors` is supplied, the full out-of-path TSA-cert path
@@ -603,7 +605,7 @@ async function verify(token, data, opts) {
   var revocationChecked = false;
   var anchorConstraints = null;
   function fail(code, reason) {
-    return { valid: false, trusted: false, revocationChecked: revocationChecked, anchorConstraints: anchorConstraints, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
+    return { valid: false, trusted: false, revocationChecked: revocationChecked, anchorConstraints: anchorConstraints, code: code, reason: reason || null, genTime: tst.genTime, accuracy: tst.accuracy, serialNumber: tst.serialNumber, serialNumberHex: tst.serialNumberHex, policy: tst.policy, policyName: tst.policyName, nonce: tst.nonce, tsa: tst.tsa, tstInfo: tst, signer: null };
   }
   var cmsRes = await cmsVerify.verify(tokenDer, { certs: opts.certs });
   var signer = cmsRes.signers[0];

package/lib/webauthn.js

@@ -17,7 +17,7 @@
  *   `pki.path.validate` is the caller's step: this module verifies the statement, not
  *   the certificate chain. A verifier, not a ceremony client: the relying party
  *   supplies the clientDataHash + any trust anchors; this module never touches a
- *   socket. Fail-closed -- every malformed shape or failed check throws a typed
+ *   socket. Fail-closed: every malformed shape or failed check throws a typed
  *   `WebauthnError`, never a partial verdict.
  * @spec W3C WebAuthn Level 3 sec. 6.5 / 8, RFC 9052 (COSE)
  * @card Verify a WebAuthn / passkey attestation (packed / tpm / android-key / apple / fido-u2f / none).
@@ -119,8 +119,8 @@ function _decodeCoseKey(node) {
  * @spec       RFC 9052, W3C WebAuthn Level 3 sec. 6.5.1
  * @related    pki.webauthn.verify, pki.webauthn.verifyAssertion
  *
- * Decode a bare COSE_Key -- the credential public key a relying party stored at
- * registration -- back into the object `verifyAssertion` takes. `pki.webauthn.verify`
+ * Decode a bare COSE_Key, the credential public key a relying party stored at
+ * 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":[...]}` in place of the object that went in, and existing
@@ -279,7 +279,7 @@ function _findExt(cert, oidName) {
  * authData}`) and its authenticatorData, fail-closed. `authData` carries the decoded
  * rpIdHash / flags / signCount and, when the AT flag is set, the attestedCredentialData
  * (aaguid, credentialId, and the decoded COSE `credentialPublicKey`). `authDataBytes`
- * is the raw authenticatorData -- the exact bytes an attestation signature covers.
+ * is the raw authenticatorData, the exact bytes an attestation signature covers.
  * A malformed object throws `webauthn/bad-attestation-object`.
  *
  * @example
@@ -820,7 +820,7 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  * 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
- * was present -- so an attestation naming another origin's RP ID, with user presence
+ * 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
@@ -834,18 +834,18 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  * The verdict also carries what a relying party must STORE to run a later login:
  * `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
+ * what a credential row should hold. The object carries `Buffer` values, so a JSON round
  * 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.
  *
- * @intro This verifies the attestation STATEMENT -- the signature and the format's
+ * @intro This verifies the attestation STATEMENT: the signature and the format's
  *   structural bindings (the x5c leaf key == credential key, the apple nonce, the tpm
  *   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,
+ *   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
- *   `pki.webauthn.verifyMetadataBlob` result -- and the authenticator's registered
+ *   `pki.webauthn.verifyMetadataBlob` result. 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 and never
  *   reported as verified. Pass `opts.rootCertificates` and the path is required to
@@ -858,7 +858,7 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  *   roots are a stronger claim than a static pin and its status reports can
  *   disqualify a model those roots would still accept. `anchoredTo` reports which
  *   route ran, naming every route that contributed and joining them with `+` when more
- *   than one did -- `"metadata"`, `"rootCertificates"`, and `"safetyNetRoots"` for the
+ *   than one did: `"metadata"`, `"rootCertificates"`, and `"safetyNetRoots"` for the
  *   android-safetynet chain, which anchors through the roots that format requires whether
  *   or not either other route was asked for. It is `null` only when nothing anchored the
  *   path. On the mixed metadata/pinned-root route `metadata` still carries the
@@ -1091,14 +1091,14 @@ void constants;
  * @spec FIDO Metadata Service v3.0 sec. 3.1, RFC 7515
  * @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
+ * Verify a FIDO Metadata Service BLOB (the signed catalogue of every registered
+ * 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.
  *
  * The BLOB is a JWS. Its signature is checked under the certificate in its own header,
  * that chain is validated to one of `opts.rootCertificates`, and only THEN is the
- * payload read -- a BLOB that does not verify never reaches the JSON parser. `no` must
+ * payload read. A BLOB that does not verify never reaches the JSON parser. `no` must
  * exceed `opts.previousNo` (rollback) and `nextUpdate` must not have passed
  * (freshness). Every failure is a typed `webauthn/metadata-*` throw, never a partial
  * result.
@@ -1224,7 +1224,7 @@ var CLIENT_DATA_TYPE = Object.assign(Object.create(null), { "webauthn.create": 1
  * @defends webauthn-ceremony-confusion (CWE-345)
  * @related pki.webauthn.verify, pki.webauthn.verifyAssertion
  *
- * Decode the `clientDataJSON` a ceremony returns -- the half of a WebAuthn response
+ * Decode the `clientDataJSON` a ceremony returns, the half of a WebAuthn response
  * the signature covers by digest but that no signature check ever looks inside.
  * Parsed through the shared fail-closed JSON guard (bounded bytes and depth,
  * fatal UTF-8, duplicate members refused, no prototype pollution), because these
@@ -1233,7 +1233,7 @@ var CLIENT_DATA_TYPE = Object.assign(Object.create(null), { "webauthn.create": 1
  * value; `type`, `origin`, `crossOrigin` and `topOrigin` come back as they were.
  *
  * Supply `expectedType`, `expectedChallenge`, `expectedOrigin` and
- * `expectedTopOrigin` and each is checked here -- the challenge in constant time
+ * `expectedTopOrigin` and each is checked here: the challenge in constant time
  * and by full value, the origins whole and case-sensitively. `checked`
  * reports which ran, so a check that passed is distinguishable from one that never
  * happened. `expectedType` is worth setting on every call: the ceremony a response
@@ -1418,7 +1418,7 @@ var _ASSERT_OPTS = Object.assign(Object.create(null), {
  *
  * Verify an authentication assertion's signature: the authenticator signs
  * `authenticatorData || SHA-256(clientDataJSON)` as raw bytes with the credential
- * key registered earlier -- no COSE_Sign1 wrapper, so a COSE message verifier is
+ * 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
@@ -1428,10 +1428,13 @@ var _ASSERT_OPTS = Object.assign(Object.create(null), {
  * registered credential key produced this response. What makes the response
  * ACCEPTABLE is the sec. 7.2 binding, and the caller owns most of it. Supply
  * `expectedRpId`, `requireUserPresence`, `requireUserVerification` and
- * `allowedAlgorithms` and they are checked here -- `bindingChecked` reports which
+ * `allowedAlgorithms` and they are checked here. `bindingChecked` reports which
  * ones ran, so a check that passed is distinguishable from one that never
- * happened. The CHALLENGE and the ORIGIN stay with the caller: both live in
- * clientDataJSON and are compared against state only the relying party has.
+ * happened. Supply `expectedChallenge`, `expectedOrigin`, or `expectedTopOrigin`
+ * together with `clientDataJSON` and the challenge and origin are checked here
+ * against it; omit them and they stay with the caller to compare against the
+ * clientDataJSON this call surfaces. Passing them with only `clientDataHash`
+ * throws, because there is no clientDataJSON to check them against.
  *
  * Pass `previousSignCount` (the value stored at registration or the last login) and
  * the sec. 7.2 step 21 counter rule is applied: a counter that fails to advance is
@@ -1447,6 +1450,7 @@ var _ASSERT_OPTS = Object.assign(Object.create(null), {
  *   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
+ *   expectedChallenge, expectedOrigin, expectedTopOrigin -- checked against clientDataJSON when supplied (needs clientDataJSON, not clientDataHash)
  *
  * @example
  *   // requires: `assertion` -- credential.response from navigator.credentials.get();

package/lib/webcrypto.js

@@ -20,7 +20,7 @@
  *   Unlike the browser's built-in `crypto.subtle`, this engine is
  *   **PQC-first without being PQC-only**: the FIPS 204 ML-DSA and FIPS
  *   205 SLH-DSA signature suites sit alongside the full classical set PKI
- *   still runs on -- RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH,
+ *   still runs on: RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH,
  *   Ed25519 / Ed448, AES-GCM / CBC / KW, HMAC, HKDF, PBKDF2, the SHA family
  *   (including legacy SHA-1 for old certificates and signatures), and the
  *   SHAKE128 / SHAKE256 extendable-output functions as message digests.
@@ -193,8 +193,8 @@ var SECRET_KEY_NAMES = intrinsic.assign(intrinsic.create(null), { "AES-GCM": tru
  *
  * Opaque handle to key material, matching the W3C `CryptoKey` shape:
  * `{ type, extractable, algorithm, usages }`. The underlying
- * `node:crypto` KeyObject is non-enumerable and never serialized --
- * extract material only through `subtle.exportKey`, and only when the key
+ * `node:crypto` KeyObject is non-enumerable and never serialized.
+ * Extract material only through `subtle.exportKey`, and only when the key
  * was created `extractable`. Instances are produced by
  * `subtle.generateKey` / `subtle.importKey`; the constructor is rarely
  * called directly.

package/lib/x509-sign.js

@@ -195,13 +195,13 @@ function _hasCriticalSan(extSpec) {
  * @defends forged-certificate-issuance (CWE-347)
  * @related pki.schema.x509.parse, pki.path.validate, pki.cms.sign
  *
- * Build, sign, and DER-encode an X.509 certificate. `spec` describes the certificate to issue --
+ * Build, sign, and DER-encode an X.509 certificate. `spec` describes the certificate to issue:
  * `subject` (a string CN, an array of RDNs, or raw Name DER), `subjectPublicKey` (the SPKI DER of the
  * 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 signing key `key` is a WebCrypto `CryptoKey` -- a `pki.key.generate`
- * private key passed directly, without exporting -- or a PKCS#8 private key as DER (`Buffer`) or PEM
+ * issues a CA-signed one. The signing key `key` is a WebCrypto `CryptoKey` (a `pki.key.generate`
+ * private key passed directly, without exporting) or a PKCS#8 private key as DER (`Buffer`) or PEM
  * (`string`); a public or secret CryptoKey, or a `node:crypto` KeyObject, is refused. A `subjectAltName`
  * (or any `GeneralName`) entry may be a form object (`{ dNSName: "..." }`) or a bare string classified
  * fail-closed into its form (`"host.example"`, `"a@b.example"`, `"10.0.0.1"`, `"https://host.example/"`).
@@ -213,8 +213,8 @@ function _hasCriticalSan(extSpec) {
  * (positive, <= 20 octets), the validity UTCTime/GeneralizedTime cutover, the DER DEFAULT omissions
  * (v1 tag, `critical=FALSE`, `cA=FALSE`), and the CA cross-field rules (keyCertSign and
  * pathLenConstraint require cA=TRUE) are all enforced; a violation throws a typed `CertificateError`.
- * Where the spec carries raw DER -- a `Name` Buffer, a pre-encoded `Extension`, an issuer `publicKey`
- * SPKI -- a structural fault throws `CertificateError`, while a malformed leaf inside those bytes
+ * Where the spec carries raw DER (a `Name` Buffer, a pre-encoded `Extension`, an issuer `publicKey`
+ * SPKI), a structural fault throws `CertificateError`, while a malformed leaf inside those bytes
  * throws `Asn1Error`, the same two-error contract the parsers present.
  *
  * @opts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.6.28",
+  "version": "0.6.30",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

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:74721cd1-1687-4508-a102-a5ca6b30f23d",
+  "serialNumber": "urn:uuid:7606eb0a-d4b1-46ef-ab6c-eae467d83dd7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-02T21:18:19.420Z",
+    "timestamp": "2026-09-04T06:04:55.759Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.6.28",
+      "bom-ref": "@blamejs/pki@0.6.30",
       "type": "application",
       "name": "pki",
-      "version": "0.6.28",
+      "version": "0.6.30",
       "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.6.28",
+      "purl": "pkg:npm/%40blamejs/pki@0.6.30",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.6.28",
+      "ref": "@blamejs/pki@0.6.30",
       "dependsOn": []
     }
   ]