@blamejs/pki 0.6.29 → 0.6.30

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.6.30 — 2026-09-04
+
+Reference documentation is corrected across the toolkit: a mistyped signed-attribute field name, and options and return fields the code accepts or returns that the reference had omitted.
+
+### Changed
+
+- Options and return fields the code accepts or returns are now documented across pki.cms, pki.tsp, pki.pkcs12, pki.hpke, pki.path, pki.ocsp, pki.asn1, pki.est, pki.acme, and pki.webauthn. In particular, pki.webauthn.verifyAssertion is documented as checking the challenge and origin when expectedChallenge / expectedOrigin / expectedTopOrigin are supplied with clientDataJSON.
+- Reference prose across the toolkit and the documentation site is reworded for consistency.
+
+### Fixed
+
+- pki.smime.sign documented additionalSignedAttributes as [{ oid, values }]; the code reads the type field, so a caller following the reference would pass an unrecognized field. The correct form is [{ type, values }].
+- pki.ocsp.buildErrorResponse is documented as returning a Buffer; the signature previously showed Buffer | string, but the verb has no PEM option and every path returns DER.
+- The pki.schema.all example output lists csrattrs, which the enumeration returns between cmp and ocsp-request.
+- The pki.acme.client method list documents updateAccount and listOrders, which the client returns.
+- pki.tsp.verify now includes policyName on a failure verdict; it already returned the resolved policy name on a valid verdict and the raw policy on both, so a refused token carries the same descriptive fields as a valid one.
+
 ## v0.6.29 — 2026-09-03
 
 The EST, ACME, and CMP clients reach a CA through a forward HTTP proxy, with the same opts.proxy the SCEP client already accepts.

package/lib/acme.js

@@ -513,7 +513,7 @@ function validate(kind, obj) {
  * @related    pki.acme.validate
  *
  * Classify an ACME JSON object into exactly one kind by its discriminating
- * member set -- `"jws"`, `"problem"`, `"directory"`, `"order"`, `"authorization"`,
+ * member set: `"jws"`, `"problem"`, `"directory"`, `"order"`, `"authorization"`,
  * `"challenge"`, `"account"`, `"renewalInfo"`, or `"unknown"`. The discriminators
  * are proven mutually exclusive; a DER structure identifies as `"unknown"`.
  *
@@ -1109,7 +1109,7 @@ async function finalize(o) {
  * @related    pki.acme.http01, pki.acme.dns01
  *
  * Build a challenge-response POST (RFC 8555 sec. 7.5.1): a kid-signed JWS whose
- * payload is the type-defined response object -- `{}` for the three registered
+ * payload is the type-defined response object: `{}` for the three registered
  * challenge types (http-01 / dns-01 / tls-alpn-01), which is DISTINCT from a
  * POST-as-GET empty payload. `opts` = `{ key, alg, nonce, url, kid, payload? }`
  * (payload default `{}`; pass a custom object for a future challenge type).
@@ -1139,7 +1139,7 @@ function challengeResponse(o) {
  * @related    pki.acme.validate
  *
  * Build a deactivation POST (RFC 8555 sec. 7.3.6 account / sec. 7.5.2
- * authorization): a kid-signed JWS with the payload `{"status":"deactivated"}` --
+ * authorization): a kid-signed JWS with the payload `{"status":"deactivated"}`,
  * the only client-settable status. `opts` = `{ key, alg, nonce, url, kid }`.
  *
  * @example
@@ -1196,7 +1196,7 @@ function updateAccount(o) {
  * Build a revokeCert request (RFC 8555 sec. 7.6): a JWS whose payload `certificate`
  * is the base64url of the DER certificate and optional `reason` is an assigned
  * RFC 5280 CRLReason (0-6, 8-10; 7 is unassigned). Signed EITHER by the account key (`kid` mode) OR by the
- * certificate key (`jwk` mode) -- pass exactly one. `opts` = `{ key, alg, nonce,
+ * certificate key (`jwk` mode). Pass exactly one. `opts` = `{ key, alg, nonce,
  * url, certificate (DER Buffer), reason?, kid? | jwk? }`.
  *
  * @example
@@ -1347,7 +1347,7 @@ function parseAriCertId(certId) {
  *
  * Validate an ARI RenewalInfo object (RFC 9773 sec. 4.2): a `suggestedWindow` with
  * RFC 3339 `start` and `end`, `end` strictly after `start` (an inverted or
- * zero-width window throws `acme/bad-renewal-window` -- the client treats it as no
+ * zero-width window throws `acme/bad-renewal-window`: the client treats it as no
  * response, defusing a renewal stampede), and an optional `explanationURL`.
  * Returns the object.
  *
@@ -1758,7 +1758,7 @@ function _parseLinkNext(headers, base) { var m = _parseLinkRelation(headers, bas
  * capped by a poll count and a total-wait budget. Returns a client
  * object: `directory`, `newAccount`, `newOrder`, `newAuthz`, `getOrder` / `getAuthorization` / `getChallenge`,
  * `respondToChallenge`, `finalize`, `pollOrder` / `pollAuthorization`, `downloadCertificate`,
- * `revokeCert`, `deactivateAccount` / `deactivateAuthorization`, `keyChange`, `renewalInfo`, `renewalWindow`, `scheduleRenewal`.
+ * `revokeCert`, `deactivateAccount` / `deactivateAuthorization`, `updateAccount`, `listOrders`, `keyChange`, `renewalInfo`, `renewalWindow`, `scheduleRenewal`.
  *
  * @opts
  *   - `accountKey` / `accountJwk` / `alg` -- REQUIRED: the account private key, its public JWK, and the JWS alg.

package/lib/asn1-der.js

@@ -23,8 +23,8 @@
  *   turn a node into a JS value (BigInt, dotted OID, Date, string); the
  *   `build.*` helpers construct canonical DER from JS values. Because DER
  *   is canonical, each value the `build.*` helpers emit has exactly one
- *   valid encoding -- byte-identical to any other conformant DER encoder's
- *   output -- and decoding it reproduces the value it was built from.
+ *   valid encoding, byte-identical to any other conformant DER encoder's
+ *   output, and decoding it reproduces the value it was built from.
  *
  * @card
  *   Strict, fail-closed DER decode / encode with a navigable node tree
@@ -112,9 +112,10 @@ function _asBuffer(input, who) {
  *
  * Parse DER into a node tree. Each node is
  * `{ tagClass, constructed, tagNumber, header, length, content, children,
- * bytes }`, where `content` is the primitive value slice, `children` the
- * decoded sub-nodes of a constructed node, and `bytes` the full TLV slice
- * (all zero-copy views over the input).
+ * bytes, contentStart, contentEnd }`, where `content` is the primitive value slice, `children` the
+ * decoded sub-nodes of a constructed node, `bytes` the full TLV slice, and
+ * `contentStart` / `contentEnd` the content slice's byte offsets in the input
+ * (all slices are zero-copy views over the input).
  *
  * Throws `Asn1Error` on any non-DER shape: indefinite length, a
  * non-minimal length or a length that overruns the buffer, trailing bytes
@@ -124,13 +125,14 @@ function _asBuffer(input, who) {
  * `ber: true` is a scoped relaxation for formats whose content regions are
  * normatively BER (RFC 7292 PKCS#12): it accepts an indefinite length on a
  * constructed value and a constructed OCTET STRING, whose segments are
- * reassembled into one primitive `content`. Nothing else is relaxed --
+ * reassembled into one primitive `content`. Nothing else is relaxed:
  * definite lengths stay minimal, an indefinite length on a primitive value
  * and a foreign-type segment still reject, and the size / depth caps hold.
  *
  * @opts
  *   maxBytes:       number,   // default: C.LIMITS.DER_MAX_BYTES (16 MiB)
  *   maxDepth:       number,   // default: C.LIMITS.DER_MAX_DEPTH (64)
+ *   maxItems:       number,   // default: C.LIMITS.DER_MAX_ITEMS (total decoded node cap)
  *   allowTrailing:  boolean,  // default false; allow bytes after the top TLV
  *   ber:            boolean,  // default false; accept indefinite lengths +
  *                             // constructed OCTET STRINGs (BER content regions)
@@ -680,7 +682,7 @@ function encodeIdentifier(classBits, constructed, tagNumber) {
  * @spec       X.690, ISO/IEC 8825-1
  * @related    pki.asn1.decode
  *
- * Low-level TLV encoder -- prepend the identifier + DER length to a content
+ * Low-level TLV encoder: prepend the identifier + DER length to a content
  * buffer. Most callers use the higher-level `build.*` helpers; this is the
  * escape hatch for context-tagged and implicitly-tagged constructions.
  *

package/lib/attrcert-sign.js

@@ -583,17 +583,17 @@ function _unsupportedCritical(ac) {
  * @defends attribute-certificate-forgery (CWE-347)
  * @related pki.attrcert.sign, pki.path.validate, pki.schema.attrcert.parse
  *
- * Verify an RFC 5755 attribute certificate. An AC carries privilege attributes -- a role, a group, a
- * clearance -- so a consumer that reads them without this grants privileges on unauthenticated
+ * Verify an RFC 5755 attribute certificate. An AC carries privilege attributes (a role, a group, a
+ * clearance), so a consumer that reads them without this grants privileges on unauthenticated
  * input. `ac` is a DER `Buffer`, a PEM string, or a parsed attribute certificate; `issuer` is
  * `{ name, publicKey }`, the AC issuer this verifier trusts as an AC issuer, which section 5 item 4
  * makes the verifier's own configuration and this verb therefore refuses to infer from the AC.
- * `issuer.name` takes every form `pki.attrcert.sign` accepts for the issuing AA -- a string, an
- * array of RDNs, or raw `Name` DER -- and is compared as a distinguished name (RFC 5280 section
+ * `issuer.name` takes every form `pki.attrcert.sign` accepts for the issuing AA (a string, an
+ * array of RDNs, or raw `Name` DER) and is compared as a distinguished name (RFC 5280 section
  * 7.1), so an AC issued under a multi-RDN authority name is verifiable under that same name.
  *
  * Both options are read at the call, before signature verification suspends it, so a caller that
- * reuses or rewrites its options object -- including calling `setTime` on the `Date` it passed in --
+ * reuses or rewrites its options object (including calling `setTime` on the `Date` it passed in)
  * cannot change the verdict that call returns.
  *
  * The checks it performs are section 5's items 2, 4, 5, 6 and 7: the signature over the exact
@@ -613,7 +613,7 @@ function _unsupportedCritical(ac) {
  * (RFC 5280 sec. 7.2), a mailbox matches its local-part exactly and its host-part case-insensitively
  * (sec. 7.5), and a directoryName goes through the same distinguished-name comparison the rest of
  * the toolkit uses (sec. 7.1). A URI compares as encoded, because sec. 7.4 makes URI equality a full
- * RFC 3987 normalization -- percent-encoding, path segments and scheme-based rules -- and a partial
+ * RFC 3987 normalization (percent-encoding, path segments and scheme-based rules) and a partial
  * one could match a URI it should not. A form with no comparison here (otherName, ediPartyName,
  * x400Address) leaves `targetingChecked: false` and never a pass. Every one of those limits can
  * refuse a target a fuller comparison would accept, and none can accept one it would refuse.
@@ -627,8 +627,8 @@ function _unsupportedCritical(ac) {
  *
  * Revocation is section 6, outside the seven. This verb implements that section's "never revoke"
  * scheme, which AC users MUST support: it holds no revocation evidence and follows no pointer out
- * of the certificate. The section states the consequence -- "If only the 'never revoke' scheme is
- * supported, then all ACs that do not contain a noRevAvail extension, MUST be rejected" -- because
+ * of the certificate. The section states the consequence, "If only the 'never revoke' scheme is
+ * supported, then all ACs that do not contain a noRevAvail extension, MUST be rejected", because
  * an issuer that omits noRevAvail is stating that revocation status checks are supported, and a
  * verdict that skipped one would grant privileges the issuer expected to be able to withdraw. So an
  * AC carrying `noRevAvail` verifies with `revocationChecked: true` and `noRevAvail: true`, and one

package/lib/byte-reader.js

@@ -3,7 +3,7 @@
 "use strict";
 /**
  * @internal
- * lib/byte-reader.js -- a bounded big-endian byte cursor: the shared ENCODING-layer
+ * lib/byte-reader.js: a bounded big-endian byte cursor, the shared ENCODING-layer
  * primitive under the toolkit's non-ASN.1 length-prefixed wire formats (TLS-vector
  * SCTs in pki.ct, the packed big-endian TPM2B_* / authenticatorData structures in
  * pki.webauthn). Every read is length-checked against a hard [pos, end) window

package/lib/byte-writer.js

@@ -3,7 +3,7 @@
 "use strict";
 /**
  * @internal
- * lib/byte-writer.js -- a growable big-endian byte sink: the ENCODING-layer twin of
+ * lib/byte-writer.js: a growable big-endian byte sink, the ENCODING-layer twin of
  * lib/byte-reader.js, the shared producer under the toolkit's non-ASN.1 length-prefixed
  * wire formats (the TLS-vector SCT list pki.ct emits; any future TLS-presentation
  * producer). Every fixed-width integer is range-checked against its field width and

package/lib/cmc-verify.js

@@ -200,11 +200,11 @@ function _governingStatus(statuses, outcome) {
  * Interpret a Full PKI Response into one terminal verdict. `response` is the DER or a PEM `CMS`
  * block; an already-parsed message is interpreted too, but only under `allowUnverified: true`,
  * because both carriers authenticate over BYTES and a parsed object the caller still owns pins
- * none. `sent` is what the client retained from its request --
+ * none. `sent` is what the client retained from its request:
  * `transactionId`, `senderNonce`, `dataReturn`, and `bodyPartIDs` (every identifier the request
  * carried). Each of those is checked only if it was sent, and once sent an absent or differing
  * echo is a refusal: that asymmetry is the replay defense. `bodyPartIDs` is the same rule applied
- * to what the response is ABOUT -- a status naming a body part the request never sent is refused
+ * to what the response is ABOUT: a status naming a body part the request never sent is refused
  * with `cmc/body-part-unknown`, which the transaction and nonce cannot catch, since a server can
  * echo both correctly while reporting on something else.
  *
@@ -229,7 +229,7 @@ function _governingStatus(statuses, outcome) {
  * The carrier's signature MUST be verified (RFC 5272 sec. 3.2.1.3.4). A conforming SignedData
  * carries its own signer certificate, so the ordinary case needs nothing from the caller: the
  * signature is checked and the verdict reports `signatureVerified: true`. Where the signer cannot be
- * found -- not embedded and not supplied -- the posture is fail-closed with a NAMED opt-out rather
+ * found (not embedded and not supplied), the posture is fail-closed with a NAMED opt-out rather
  * than a silent one: pass `certs` with the responder's certificate, or `allowUnverified: true` and
  * the verdict reports `signatureVerified: false`. Doing neither is refused, because that is the case
  * where a caller would otherwise assume a check happened. The opt-out covers "could not check",
@@ -245,7 +245,7 @@ function _governingStatus(statuses, outcome) {
  * who holds the key gets an authenticated verdict instead of the unauthenticated opt-out.
  *
  * Nothing is trusted here. `certificates` is the CMS certificate bag, where RFC 5272 sec. 4.2
- * puts the issued certificates -- surfaced raw for the caller to run through `pki.path.validate`,
+ * puts the issued certificates, surfaced raw for the caller to run through `pki.path.validate`,
  * and a Publish Trust Anchors control is surfaced as `publishTrustAnchors` with `trusted: false`,
  * never added to any store (RFC 5272 sec. 6.15 makes accepting one a four-part manual decision).
  * The CMS signature is likewise the caller's to verify through `pki.cms.verify`.

package/lib/cmp-build.js

@@ -8,7 +8,7 @@
  * @title      Certificate management protocol messages
  * @fullname   CMP (Certificate Management Protocol, RFC 4210)
  * @intro The RFC 9810 Certificate Management Protocol producing side. `pki.cmp.build` assembles a
- *   `PKIMessage` -- a `PKIHeader` (sender / recipient / transaction metadata), a `PKIBody` carrying one
+ *   `PKIMessage`: a `PKIHeader` (sender / recipient / transaction metadata), a `PKIBody` carrying one
  *   request or transaction (an `ir` / `cr` / `kur` certificate request via `pki.crmf.build`, a `p10cr`
  *   PKCS#10 via `pki.csr.sign`, a `certConf` / `pollReq` / `genm` / `rr`, or a `nested` wrapper of other
  *   PKIMessages an RA forwards), and an optional
@@ -682,7 +682,7 @@ function _collectExtraCerts(opts, protCertDer) {
  * @spec       RFC 9810, RFC 9481, RFC 9579
  * @related    pki.schema.cmp.parse
  *
- * Build an RFC 9810 CMP `PKIMessage` -- the producing-side inverse of `pki.schema.cmp.parse`. `message` is
+ * Build an RFC 9810 CMP `PKIMessage`, the producing-side inverse of `pki.schema.cmp.parse`. `message` is
  * `{ header, body }`: `header` carries the `sender` / `recipient` GeneralNames plus optional transaction
  * metadata (`transactionID`, `senderNonce`, `messageTime`, `freeText`, `generalInfo`, ...); `body` is a
  * single-key object naming the arm. Request-side: `{ ir }` / `{ cr }` / `{ kur }` / `{ krr }` (key recovery,
@@ -924,7 +924,7 @@ function wellKnownUrl(base, opts) {
  *
  * Build an RFC 9811 sec. 3.4 CMP request-URI under the `/.well-known/cmp` prefix (RFC 8615). The four forms:
  * `<base>/.well-known/cmp`, `.../<operation>`, `.../p/<label>`, and `.../p/<label>/<operation>`. A pure string
- * builder over an authority-rooted well-known path (RFC 8615) -- https vs http is left to the transport (both
+ * builder over an authority-rooted well-known path (RFC 8615): https vs http is left to the transport (both
  * forms are accepted, RFC 9811 sec. 3.4), but the `base` MUST be an http(s) URL. It rejects (`cmp/bad-url`) an
  * unparseable `base`, a non-http(s) scheme (`file:`/`data:`/a custom scheme has an opaque origin), a `base`
  * carrying a path / query / fragment (a well-known URI is authority-rooted; a path would capture it), and a

package/lib/cmp-session.js

@@ -265,14 +265,14 @@ function _certConfHash(certDer) {
  * requirements, whose template must omit `publicKey`, `serialNumber`, `signingAlg`, `issuerUID` and
  * `subjectUID`, and whose `keySpec` states key requirements as `algId` (a non-RSA AlgorithmIdentifier) or
  * `rsaKeyLen` (a positive integer); and `{ crlUpdate: { issuer, dpn?, thisUpdate? } }` for a CRL from a
- * named source, held to that source -- the issuer under the RFC 5280 sec. 7.1 rule, a distribution point
- * against the CRL's own `issuingDistributionPoint` where it states one -- and to the supplied `thisUpdate`.
+ * named source, held to that source (the issuer under the RFC 5280 sec. 7.1 rule, a distribution point
+ * against the CRL's own `issuingDistributionPoint` where it states one) and to the supplied `thisUpdate`.
  * A request naming both sends the dpn (sec. 4.3.4: the dpn choice when a distribution point name is
  * available) and holds the answer to the issuer as well. The issuer is REQUIRED, since a distribution
  * point name alone leaves the answer unbound: a complete CRL states no scope to compare it against.
  * Terminal `outcome`: `answered` (with `operation`, `present`, and the decoded `value`),
  * `rejected`, or `poll-timeout`. An absent response value is `present: false` with a null `value`, which is
- * how each of the four says "nothing available" -- never conflated with an empty result. Delayed delivery
+ * how each of the four says "nothing available", never conflated with an empty result. Delayed delivery
  * for both verbs arrives as an error message carrying the `waiting` status (sec. 4.4) and drives the same
  * bounded poll loop, with the `pollReq` referring to the whole message.
  *

package/lib/cms-verify.js

@@ -6,7 +6,7 @@
  * @nav        Verification
  * @title      CMS
  * @fullname   CMS (Cryptographic Message Syntax) signing and verification
- * @intro Verify a CMS SignedData signature (RFC 5652 sec. 5) -- the structure S/MIME signed
+ * @intro Verify a CMS SignedData signature (RFC 5652 sec. 5), the structure S/MIME signed
  *   mail, RFC 3161 timestamp tokens, and code-signing all rest on. `verify(cms, opts)` parses
  *   the SignedData (over the strict `pki.schema.cms` codec), locates each SignerInfo's signer
  *   certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature
@@ -406,7 +406,7 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
 
 /**
  * @primitive  pki.cms.verify
- * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, trusted, eContentType, signers }>
+ * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, trusted, eContentType, eContent, signers }>
  * @since      0.2.14
  * @status     stable
  * @spec       RFC 5652
@@ -416,15 +416,16 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * @related    pki.schema.cms.parse, pki.path.validate
  *
  * Verify a CMS SignedData signature (RFC 5652 sec. 5). `input` is a PEM string, a DER
- * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, trusted, eContentType, signers }`
- * where each `signers[i]` is `{ ok, sid, cert, trusted, signedAttributesPresent }` (`cert` the
- * matched signer certificate DER) or carries a `code` on a structural failure; `valid` is true when
+ * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, trusted, eContentType, eContent, signers }`
+ * (`eContent` the encapsulated content when present, else null) where each `signers[i]` is
+ * `{ ok, sid, cert, trusted, signedAttributesPresent, signedAttributes, unsignedAttrs, digestAlgorithm, countersignatures }`
+ * (`cert` the matched signer certificate DER) or carries a `code` on a structural failure; `valid` is true when
  * there is at least one signer and every signer verified.
  *
  * `eContentType` and `signedAttributesPresent` are there for a caller whose profile is stricter
- * than RFC 5652's. Signing WITH attributes and signing the content directly are different claims --
+ * than RFC 5652's. Signing WITH attributes and signing the content directly are different claims:
  * attributes bind a content type and a signing time alongside the digest, content-only binds
- * nothing but the bytes -- and one message may carry a signer of each. A profile that requires
+ * nothing but the bytes. One message may carry a signer of each. A profile that requires
  * attributes (RFC 8551 S/MIME does) or a particular content type can enforce it from the verdict,
  * with no need to parse the message a second time.
  *
@@ -434,9 +435,8 @@ async function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * certificate, sign with it, and embed it, so that says nothing about WHO signed. `trusted` says
  * every signer chained to a root named in `opts.trustAnchors`, validated through the same RFC 5280
  * path engine `pki.path.validate` uses. Without anchors there is nothing to chain to and `trusted`
- * is `false` -- a definite answer, not a missing one. Anchors that cannot be read are a
- * configuration fault and throw. Absorbing them into `trusted: false` would report a verdict
- * about the message for a check that never ran.
+ * is `false`, a definite answer, not a missing one. Anchors that cannot be read are a
+ * configuration fault and throw.
  *
  * Trust is decided from the certificate the SignerInfo selected, the one reported as
  * `signers[i].cert`, never from another certificate that happens to share its key. A
@@ -706,6 +706,9 @@ function _addCert(out, der) {
  * @opts  eContentType      The encapsulated content type (an OID name). Default `data`.
  * @opts  signedAttributes  Include signed attributes (content-type, message-digest, signing-time);
  *                          false signs the content directly. Default true.
+ * @opts  additionalSignedAttributes  Extra signed attributes to add to every SignerInfo, each
+ *                          `{ type, values }` (`type` an OID name or dotted string, `values` an
+ *                          array of DER value `Buffer`s). Covered by the signature.
  * @opts  signingTime       A `Date` for the signing-time attribute, or false to omit it.
  * @opts  sid               `"issuerAndSerial"` (default) or `"ski"` (subjectKeyIdentifier).
  * @opts  certificates      Embed the signer certificates in the output. Default true.
@@ -739,7 +742,7 @@ var sign = cmsSign.sign;
  * Add one or more countersignatures to an existing CMS SignedData (RFC 5652 sec. 11.4). A
  * countersignature is itself a `SignerInfo` whose signature covers the CONTENTS of the countersigned
  * SignerInfo's signature value (not the content), attached as the `id-countersignature` unsigned
- * attribute -- the construction Authenticode timestamps and signature-attestation workflows rest on.
+ * attribute, the construction Authenticode timestamps and signature-attestation workflows rest on.
  * `cms` is the SignedData (a DER `Buffer` or a PEM `CMS` string; the wire bytes are preserved, so
  * the countersigned primary still verifies byte-for-byte). Each `signers[i]` is the same descriptor
  * `pki.cms.sign` takes (`{ cert, key, digestAlgorithm?, pss? }`, any RSA / RSASSA-PSS / ECDSA /
@@ -784,7 +787,7 @@ var countersign = cmsSign.countersign;
  * Encrypt content as a CMS EnvelopedData (CBC content), AuthEnvelopedData (AEAD content, the
  * default), or EncryptedData. `recipients` is an ARRAY of recipient descriptors for the enveloped
  * family, each wrapping the same fresh content-encryption key: `{ cert }` auto-dispatches off the
- * recipient certificate's public-key algorithm -- RSA yields a ktri with RSAES-OAEP-SHA256 (PKCS#1
+ * recipient certificate's public-key algorithm: RSA yields a ktri with RSAES-OAEP-SHA256 (PKCS#1
  * v1.5 is never emitted); EC P-256/384/521 a kari with ephemeral-static ECDH and the X9.63 KDF;
  * X25519/X448 a kari per RFC 8418 (HKDF); ML-KEM-512/768/1024 an ori/KEMRecipientInfo per RFC
  * 9629 + 9936; a composite ML-KEM (id-MLKEM768-* / id-MLKEM1024-*, draft-lamps-pq-composite-kem) the
@@ -827,7 +830,7 @@ var encrypt = cmsEncrypt.encrypt;
  * @spec RFC 5652, RFC 2104, RFC 4231, RFC 3370
  * @related pki.cms.decrypt, pki.schema.cms.parse
  *
- * Produce a CMS AuthenticatedData (RFC 5652 sec. 9): CLEARTEXT content plus a MAC (HMAC-SHA-2) --
+ * Produce a CMS AuthenticatedData (RFC 5652 sec. 9): CLEARTEXT content plus a MAC (HMAC-SHA-2),
  * authenticated but not encrypted, the authenticated-only sibling of AuthEnvelopedData. A single
  * fresh MAC key is minted and wrapped for every recipient with the same RecipientInfo model
  * `pki.cms.encrypt` uses for a content-encryption key, so `recipients` is the identical array of
@@ -835,8 +838,8 @@ var encrypt = cmsEncrypt.encrypt;
  * `{ password }` (pwri), or `{ kek, kekId }` (kekri). By default the MAC covers the authenticated
  * attributes (a content-type and a message-digest = digest of the content) re-tagged to the EXPLICIT
  * SET OF (RFC 5652 sec. 9.2); with `authenticatedAttributes: false` (id-data content only) it covers
- * the content octets directly. `pki.cms.decrypt` recovers the MAC key, recomputes the MAC, and --
- * with authenticated attributes -- independently confirms the message-digest before releasing the
+ * the content octets directly. `pki.cms.decrypt` recovers the MAC key, recomputes the MAC, and
+ * (with authenticated attributes) independently confirms the message-digest before releasing the
  * content, returning `authenticated: true`. Malformed input throws a typed `CmsError`.
  *
  * @opts macAlgorithm `"hmac-sha256"` (default) / `"hmac-sha384"` / `"hmac-sha512"`.
@@ -847,6 +850,8 @@ var encrypt = cmsEncrypt.encrypt;
  * @opts authAttrs Extra authenticated attributes appended to the content-type + message-digest pair.
  * @opts contentType The encapsulated content type (an OID name). Default `data`.
  * @opts keyIdentifier `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
+ * @opts oaepHash The RSAES-OAEP hash for ktri recipients wrapping the MAC key: `"sha256"` (default) / `"sha384"` / `"sha512"`.
+ * @opts ukm User keying material (a Buffer) for kari / kemri recipients.
  * @opts pem Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
  * @example
  *   // authenticate a message to an RSA recipient, then verify the MAC via decrypt
@@ -890,7 +895,7 @@ var authenticate = cmsEncrypt.authenticate;
  * recipient type: a `ktri` or ephemeral-static `kari` message is minted by anyone holding the recipient's
  * PUBLIC key, and a `pwri` or `kekri` message by any co-recipient sharing the secret. Read
  * `authenticated: true` as "these bytes were not altered after the key was chosen", and do not read it as
- * a sender identity -- to bind one, verify a signature (`pki.cms.verify`) over the plaintext.
+ * a sender identity. To bind one, verify a signature (`pki.cms.verify`) over the plaintext.
  * `authenticatedBy` names what the integrity rests on (`"content-encryption-key"` for AEAD,
  * `"message-authentication-key"` for AuthenticatedData, `null` for an unauthenticated cipher).
  * `originatorInfo` is surfaced as the sender supplied it and is UNAUTHENTICATED: it sits outside the
@@ -958,7 +963,7 @@ var compress = cmsCompress.compress;
  * decompression-bomb / resource-exhaustion defense (CWE-409): a cap breach throws
  * `cms/decompress-too-large`, and every malformed / truncated / corrupt stream collapses to the uniform
  * `cms/decompress-failed`. `opts.maxOutputBytes` tightens the cap DOWNWARD only. The verdict carries NO
- * `authenticated` / `valid` field -- CompressedData is not a security assertion (RFC 8551 sec. 2.4.5).
+ * `authenticated` / `valid` field. CompressedData is not a security assertion (RFC 8551 sec. 2.4.5).
  *
  * @opts maxOutputBytes Lower the decompressed-output cap (a DoS bound; downward only).
  * @example

package/lib/composite-kem.js

@@ -13,8 +13,8 @@
  *   recovers the same secret from that ciphertext and the composite private key. Each component KEM
  *   runs independently, and the two secrets are mixed through the SHA3-256 combiner that also binds the
  *   traditional ciphertext, the traditional public key, and a per-algorithm label. All twelve registered
- *   algorithms -- ML-KEM-768 and ML-KEM-1024 paired with RSA-OAEP 2048/3072/4096, ECDH over
- *   P-256/P-384/P-521 and brainpool, X25519, and X448 -- are verified against the draft Appendix G
+ *   algorithms (ML-KEM-768 and ML-KEM-1024 paired with RSA-OAEP 2048/3072/4096, ECDH over
+ *   P-256/P-384/P-521 and brainpool, X25519, and X448) are verified against the draft Appendix G
  *   known-answer vectors.
  * @spec draft-ietf-lamps-pq-composite-kem
  * @card Establish a shared secret with a hybrid post-quantum plus traditional KEM.

package/lib/crl-sign.js

@@ -9,7 +9,7 @@
  * @fullname   CRLs (certificate revocation lists): read, sign and shard
  * @intro The X.509 CRL producing side. `pki.crl.sign` builds a `TBSCertList`, signs it, and emits a
  *   `CertificateList` (RFC 5280 sec. 5) that `pki.schema.crl.parse`, `pki.path.crlChecker`, and OpenSSL
- *   all accept -- over any signature algorithm the toolkit registry resolves: RSA (PKCS#1 v1.5 / PSS),
+ *   all accept, 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. `pki.crl.verify` checks a CRL
  *   signature through the one path-validation signature engine, and `pki.crl.isRevoked` looks a serial up
  *   in a parsed CRL. Parsing lives at `pki.schema.crl.parse`.
@@ -413,7 +413,7 @@ function _sign(spec, issuer, opts) {
  * @defends crl-forgery (CWE-347)
  * @related pki.schema.crl.parse, pki.crl.verify, pki.path.crlChecker
  *
- * Build, sign, and DER-encode an X.509 certificate revocation list. `spec` describes the CRL --
+ * Build, sign, and DER-encode an X.509 certificate revocation list. `spec` describes the CRL:
  * `thisUpdate` / `nextUpdate` (`Date`s), an optional `crlNumber`, a `revoked` array (each entry a
  * `serialNumber` + `revocationDate` with an optional `reason` or `invalidityDate`),
  * and an optional `extensions` object (`authorityKeyIdentifier`, `issuingDistributionPoint`,
@@ -491,8 +491,8 @@ function _issuerMaySign(parsed, cert) {
  * Verify a CRL's signature over its exact parsed `tbsCertList` bytes under the issuer public key. `crl`
  * is a DER `Buffer`, a PEM string, or a parsed CRL; `issuer` is `{ cert }` (DER/PEM/parsed), `{ publicKey }`
  * (SPKI DER), or a raw SPKI `Buffer`. Verification composes the one path-validation signature engine
- * `pki.path.crlChecker` uses -- the same algorithm-confusion (RFC 9814 sec. 4 key-OID == sig-OID) and
- * EdDSA low-order-point gates -- so there is no second, weaker CRL verifier. The verdict's `valid` is
+ * `pki.path.crlChecker` uses, the same algorithm-confusion (RFC 9814 sec. 4 key-OID == sig-OID) and
+ * EdDSA low-order-point gates, so there is no second, weaker CRL verifier. The verdict's `valid` is
  * `false` on any verification fault, and `signatureValid` reports the signature check on its own; malformed
  * input throws a typed `CrlError`.
  *
@@ -571,7 +571,7 @@ function _serialHexOf(serial) {
  * refused rather than answered from (`crl/not-current`): one whose `thisUpdate` is later, one whose
  * `nextUpdate` has passed, and one carrying no `nextUpdate` at all, which states no window and so cannot
  * be told from a replayed copy. Without `opts.time` currency goes unasked and the verb is the structural
- * lookup it has always been -- `null` then means "not listed on this CRL", which is weaker than "not
+ * lookup it has always been; `null` then means "not listed on this CRL", which is weaker than "not
  * revoked". `pki.path.crlChecker` decides currency against the material it fetched and is the verb to
  * reach for when the answer has to mean the stronger thing.
  *

package/lib/crmf-sign.js

@@ -8,7 +8,7 @@
  * @title      Certificate request messages
  * @fullname   CRMF (Certificate Request Message Format, RFC 4211)
  * @intro The RFC 4211 certificate-request-message producing side. `pki.crmf.build` assembles a
- *   `CertReqMessages` -- one or more `CertReqMsg`, each a `CertRequest` (a `CertTemplate` of the requested
+ *   `CertReqMessages`: one or more `CertReqMsg`, each a `CertRequest` (a `CertTemplate` of the requested
  *   certificate fields plus optional controls) paired with a proof of possession. The common proof is a
  *   `POPOSigningKey` signature over the `CertRequest`, made with the private half of the key being
  *   certified (the requester proves possession, exactly as a PKCS#10 CSR does). The message drops into a
@@ -355,7 +355,7 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  * subjectKeyIdentifier, or pre-encoded Extension DER), and an optional `version` (2)), optional `controls`
  * and `regInfo` (an object of regToken / authenticator / utf8Pairs / oldCertID / protocolEncrKey, or
  * pre-encoded AttributeTypeAndValue DER), and an optional `pop` selector. `key` (or `{ key }`) is the
- * REQUESTER's private key -- the private half of `certTemplate.publicKey`; the message carries a
+ * REQUESTER's private key, the private half of `certTemplate.publicKey`; the message carries a
  * `POPOSigningKey` proof of possession signed with it (verified before the message is returned), exactly
  * as a PKCS#10 CSR proves possession. The signature algorithm is resolved from the requested public key
  * (RSA PKCS#1 v1.5 / PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or a composite arm). `key` is optional: omit it
@@ -373,7 +373,7 @@ function _buildProofOfPossession(pop, certReqDer, template, signingKey, opts) {
  *   content type is `id-ct-encKeyWithID`. RFC 9810 sec. 5.2.8.3.1 permits it only where archival is
  *   intended, so it takes `pop.archive: true`; `pop.privateKey` is the PKCS#8 DER, `pop.recipients` the CMS
  *   recipients to envelope it to, and `pop.identifier` (a string or GeneralName) is required, because
- *   sec. 4.2.1 makes it mandatory whenever the purpose is proving possession -- without it a decrypting
+ *   sec. 4.2.1 makes it mandatory whenever the purpose is proving possession: without it a decrypting
  *   agent cannot tell whose key it holds. `pop.contentEncryptionAlgorithm` defaults to `aes-256-cbc`; an
  *   AEAD algorithm is refused, since it would produce an `AuthEnvelopedData` this field cannot carry.
  *

package/lib/csr-sign.js

@@ -179,8 +179,8 @@ function _coerceCsr(request) {
  * requested extension, so none of them were altered after signing. It says nothing about who the
  * producer is: the key is self-asserted, the name is self-asserted, and a requester free to choose
  * both can prove possession of a key they generated a moment ago under any name they like. Binding
- * that name to an identity is the enrollment protocol's job -- `pki.est`, `pki.cmc`, `pki.cmp`, or
- * an out-of-band check -- and remains one after this returns `true`.
+ * that name to an identity is the enrollment protocol's job (`pki.est`, `pki.cmc`, `pki.cmp`, or
+ * an out-of-band check), and remains one after this returns `true`.
  *
  * Verification composes the one path-validation signature engine, with the same algorithm-confusion
  * (RFC 9814 sec. 4 key-OID == sig-OID) and EdDSA low-order-point gates, rather than the self-check

package/lib/ct.js

@@ -34,7 +34,7 @@
  *
  * @card
  *   Parse RFC 6962 Certificate Transparency SCT lists from a certificate or OCSP
- *   extension -- per-SCT logId / timestamp (BigInt) / algorithm / raw signature,
+ *   extension: per-SCT logId / timestamp (BigInt) / algorithm / raw signature,
  *   the signed-preimage reconstruction surfaced for external verification,
  *   bounded TLS-struct decode, fail-closed.
  */
@@ -230,13 +230,13 @@ function _u24Bytes(n) {
  * `entry` selects the log-entry arm:
  *   - `{ entryType: 0, leafCert: <DER Buffer> }`, an SCT delivered over TLS /
  *     OCSP, signed over `x509_entry(0)` with the leaf certificate.
- *   - `{ entryType: 1, tbsCertificate: <DER Buffer>, issuerKeyHash: <32B> }` --
+ *   - `{ entryType: 1, tbsCertificate: <DER Buffer>, issuerKeyHash: <32B> }`,
  *     an SCT EMBEDDED in a certificate, signed over `precert_entry(1)` with the
  *     issuer key hash + the precertificate TBS (the TBS with only the SCT
  *     extension removed). `issuerKeyHash` is SHA-256 of the issuer's SPKI DER.
  *
  * The preimage reuses the parsed SCT's raw `extensions` byte-for-byte and
- * re-emits the fixed-width scalars canonically. This never verifies anything --
+ * re-emits the fixed-width scalars canonically. This never verifies anything;
  * a verifier hashes the returned bytes and checks the signature with the log's
  * public key (compose `webcrypto`). Throws `CtError` (`ct/bad-entry-type`,
  * `ct/bad-issuer-key-hash`, `ct/bad-tbs-length`) on a malformed entry, and

package/lib/est.js

@@ -11,15 +11,15 @@
  *
  * @intro
  *   Enrollment over Secure Transport (RFC 7030, updated by RFC 8951 and RFC 9908).
- *   The network verbs -- `cacerts`, `simpleenroll`, `simplereenroll` -- run the thin
+ *   The network verbs (`cacerts`, `simpleenroll`, `simplereenroll`) run the thin
  *   RFC 7030 client: they compose the codecs below over the shared `pki.transport`
  *   (a caller MAY inject `opts.transport`; the default is a fail-closed
  *   `pki.transport.https`). This module opens no socket itself: the sole socket
  *   choke point is `pki.transport`, so the verbs stay a thin, fail-closed shell:
  *   https-only (`est/insecure-url`), an explicit trust anchor required
  *   (`est/no-trust-anchors`), same-origin redirects followed but a downgrade / loop
- *   refused, a 202 Retry-After SURFACED and never slept, HTTP Basic answered only
- *   after the transport authenticated the server, and the issued certificate chosen
+ *   refused, a 202 Retry-After SURFACED and never slept, HTTP Basic or Digest answered
+ *   only after the transport authenticated the server, and the issued certificate chosen
  *   by public-key match. Under them sit the transport-agnostic codecs, validators, and
  *   request builders over the shipped CMS / CSR / PKCS#8 / X.509 parsers:
  *   `transferDecode` / `transferEncode` are the RFC 8951
@@ -30,9 +30,9 @@
  *   `parseServerKeygenResponse` dispatches the two-part key + certificate
  *   response with recipient-arm coherence; `classifyResponse` is the HTTP status
  *   / content-type / Retry-After state machine (202 accepted-not-ready surfaces
- *   `retryAfterSeconds` -- never an internal sleep; 204/404 on /csrattrs is a
+ *   `retryAfterSeconds`, never an internal sleep; 204/404 on /csrattrs is a
  *   "none available" verdict, not an error). The builders assemble the CSR
- *   attributes EST adds -- a channel-binding challengePassword, the
+ *   attributes EST adds: a channel-binding challengePassword, the
  *   out-of-band-key identifiers, SMIMECapabilities, and the RFC 9908
  *   template-priority enroll plan.
  *
@@ -536,7 +536,7 @@ var NOT_IMPLEMENTED_OPS = { fullcmc: 1 };
  *
  * Classify an EST HTTP response into a verdict or a typed fault. A 200 requires
  * the operation's exact content-type (`est/bad-content-type`); a 202 requires a
- * Retry-After (absent -> `est/missing-retry-after`) -- a delay-seconds value is
+ * Retry-After (absent -> `est/missing-retry-after`): a delay-seconds value is
  * surfaced as bounded `retryAfterSeconds`, an HTTP-date as absolute
  * `retryAfterDate` (epoch ms; `retryAfterSeconds` too when `opts.now` is given),
  * and any other value is `est/bad-retry-after` (never slept on either way);
@@ -1006,7 +1006,7 @@ function _certsResult(op, res, opts, csrSpki) {
  * surfaced as `issuedCertificates` (with `certificate` the first), distinct from `certificates`,
  * which is the whole returned bag including any chain. Where the requested keys are distinct that
  * list is in request order; where several requests deliberately SHARE one key it is not, and does
- * not claim to be -- the public key is the only identification sec. 4.1 sanctions, so when it is
+ * not claim to be: the public key is the only identification sec. 4.1 sanctions, so when it is
  * shared nothing in the response says which of those requests a given certificate answers. That arm reports `signatureVerified: false`: a certs-only body is
  * a degenerate SignedData with no signers by definition, so its security rests on the authenticated
  * TLS channel, not on a signature.
@@ -1434,7 +1434,7 @@ function cacerts(baseUrl, opts) {
  * @opts
  *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `proxy` / `now`, as in pki.est.cacerts.
  *   - `strict`: reject an enroll response that carries more than the single issued certificate.
- *   - `username` / `password` -- HTTP Basic credentials, answered only after server authorization (empty username allowed).
+ *   - `username` / `password` / `auth` -- HTTP credentials: top-level `username` / `password` mean Basic; `auth` (`{ scheme: "basic" | "digest", username, password, ... }`, as in pki.est.cacerts) selects Basic or Digest. Answered only after server authorization (empty username allowed).
  *   - `allowCrossOriginRedirect` -- opt in to following a cross-origin redirect on this POST.
  * @example
  *   var req = await pki.csr.sign({ subject: "device.example", subjectPublicKey: signerSpki }, { key: signerKeyPkcs8 });

package/lib/framework-error.js

@@ -90,8 +90,8 @@ class PkiError extends Error {
  * @status     stable
  * @spec       internal (design: error-class factory)
  *
- * Factory that produces a `PkiError` subclass with the standard shape --
- * eliminating the per-domain boilerplate. The returned constructor takes
+ * Factory that produces a `PkiError` subclass with the standard shape. The
+ * returned constructor takes
  * `(code, message)`, stamps `name`, sets an `is<Name>` flag, and exposes
  * a `.factory` static for the common `var _err = XxxError.factory` shape.
  * The `code` must be a `domain/reason` string (the base-class contract);

package/lib/hpke.js

@@ -6,7 +6,7 @@
  * @nav        Protocols
  * @title      HPKE
  * @fullname   HPKE (Hybrid Public Key Encryption, RFC 9180)
- * @intro Hybrid Public Key Encryption (RFC 9180) -- the standard construction
+ * @intro Hybrid Public Key Encryption (RFC 9180): the standard construction
  *   behind TLS Encrypted Client Hello, MLS, and OHTTP that turns a recipient KEM
  *   public key into an encapsulated key plus an AEAD-encrypting context. This is
  *   the RFC 9180 base construction: the DHKEM suites P-256, P-521, X25519, and
@@ -358,7 +358,7 @@ var suites = {
 
 /**
  * @primitive pki.hpke.setupS
- * @signature pki.hpke.setupS(suiteIds, recipientPublicKey, opts?) -> { enc, context }
+ * @signature pki.hpke.setupS(suiteIds, recipientPublicKey, opts?) -> { enc, context, sharedSecret }
  * @since 0.2.2
  * @status stable
  * @spec RFC 9180