@blamejs/pki 0.6.29 → 0.6.31

package/lib/schema-cmc.js

@@ -12,7 +12,7 @@
  *   RFC 5272 CMC message-layer decoding, as updated by RFC 6402. A Full PKI
  *   Request (`PKIData`) and a Full PKI Response (`PKIResponse`) both ride inside
  *   a CMS SignedData (or AuthenticatedData) as the encapsulated content, named by
- *   the eContentType `id-cct-PKIData` / `id-cct-PKIResponse` -- so `parse` peels
+ *   the eContentType `id-cct-PKIData` / `id-cct-PKIResponse`, so `parse` peels
  *   the CMS layer, dispatches on that content type, and decodes the message.
  *
  *   Every body part carries a `BodyPartID`, and the identifier MUST be unique
@@ -22,7 +22,7 @@
  *   unrecognized control is data, not a fault, because the rule that a server
  *   fails an unrecognized control binds the server, not the client reading a
  *   response. The status controls (`CMCStatusInfo` v1 and `CMCStatusInfoV2`) are
- *   collected in wire order -- a response may carry several verdicts, and the
+ *   collected in wire order. A response may carry several verdicts, and the
  *   ABSENCE of one means success.
  *
  *   The `reqSequence` byte range is surfaced exactly as it appeared on the wire,

package/lib/schema-cmp.js

@@ -22,7 +22,7 @@
  *   CRMF parser; response, revocation, confirmation, error, general-message,
  *   and polling arms decode structurally (an encrypted certificate's
  *   EnvelopedData decodes via the CMS parser); every other defined arm is
- *   recognized and surfaced raw -- `nested` messages are never auto-recursed.
+ *   recognized and surfaced raw; `nested` messages are never auto-recursed.
  *   Protection is surfaced, not verified: the exact `headerBytes` and
  *   `bodyBytes` wire slices are exposed so an external verifier reconstructs
  *   the virtual ProtectedPart `SEQUENCE { header, body }` and checks the MAC
@@ -725,7 +725,7 @@ var readName = _valueParser("Name", pkix.name(NS));
  * Parse a DER `Buffer` or a PEM string into a structured PKIMessage:
  * `{ header, headerBytes, body, bodyBytes, protection, extraCerts }`.
  * `header` carries `pvno` (1..3), `sender` / `recipient` (validated
- * GeneralNames -- the anonymous NULL-DN form included), and the optional
+ * GeneralNames, the anonymous NULL-DN form included), and the optional
  * `messageTime`, `protectionAlg`, `senderKID` / `recipKID`,
  * `transactionID`, `senderNonce` / `recipNonce`, `freeText`, and
  * `generalInfo` (recognized id-it types value-checked: implicitConfirm is
@@ -734,14 +734,14 @@ var readName = _valueParser("Name", pkix.name(NS));
  * (`ir` / `cr` / `kur` / `krr` / `ccr`) decode via the CRMF parser;
  * `ip` / `cp` / `kup` / `ccp` decode to `{ caPubs, response }` (an encrypted
  * certificate's EnvelopedData decodes via the CMS parser; the deprecated
- * EncryptedValue arm and `caPubs` surface raw -- the parser confers no
+ * EncryptedValue arm and `caPubs` surface raw; the parser confers no
  * trust); `krp` decodes to `{ status, newSigCert, caCerts, keyPairHist }`;
  * `rr` / `rp`, `genm` / `genp`, `error`, `certConf` (an empty
  * confirmation is the legal reject-all), and `pollReq` / `pollRep` decode
- * structurally; `pkiconf` decodes to `null`; every other defined arm --
- * `p10cr` (feed `body.bytes` to `pki.schema.csr.parse`), the
- * challenge-response and announcement arms, and `nested` (never
- * auto-recursed) surfaces raw with `decoded` absent. `certReqId` values
+ * structurally; `pkiconf` decodes to `null`; every other defined arm
+ * surfaces raw with `decoded` absent: `p10cr` (feed `body.bytes` to
+ * `pki.schema.csr.parse`), the challenge-response and announcement arms,
+ * and `nested` (never auto-recursed). `certReqId` values
  * are BigInt and accept the protocol's -1 sentinel.
  *
  * Protection is surfaced, not verified: `protection` carries the raw,
@@ -785,8 +785,7 @@ var parse = pkix.makeParser({
  * @related    pki.schema.cmp.parse
  *
  * Extract the DER bytes from a PEM block (default label `CMP`). CMP is
- * wire-DER over HTTP (RFC 9811) -- the PEM path is a convenience for
- * messages that transit text channels.
+ * wire-DER over HTTP (RFC 9811).
  *
  * @example
  *   var pair = await pki.key.generate("Ed25519");

package/lib/schema-cms.js

@@ -10,7 +10,7 @@
  *
  * @intro
  *   CMS handling per RFC 5652 (sec. 3 ContentInfo envelope). `parse` turns a DER or PEM
- *   (`CMS`) message into a structured object and is an OID-dispatch envelope --
+ *   (`CMS`) message into a structured object and is an OID-dispatch envelope:
  *   ContentInfo reads its `contentType` and structurally decodes SignedData (sec. 5),
  *   EnvelopedData (sec. 6, with all five RecipientInfo kinds: key-transport,
  *   key-agreement per RFC 5753, KEK, password, and other, including the RFC 9629
@@ -38,8 +38,8 @@
  *   parse but an out-of-set element does. DER-only, fail-closed.
  *
  * @card
- *   Parse DER / PEM CMS (RFC 5652 / 5083 / 9629) into structured, validated fields
- *   -- signed, enveloped, encrypted, authenticated, and auth-enveloped content;
+ *   Parse DER / PEM CMS (RFC 5652 / 5083 / 9629) into structured, validated fields:
+ *   signed, enveloped, encrypted, authenticated, and auth-enveloped content;
  *   raw attribute bytes for external verification; certificates/CRLs kept raw,
  *   fail-closed.
  */

package/lib/schema-crmf.js

@@ -10,7 +10,7 @@
  *
  * @intro
  *   Certificate Request Message Format handling per RFC 4211. `parse` decodes a
- *   `CertReqMessages` -- the request body CMP and EST enrollment carry -- into an
+ *   `CertReqMessages`, the request body CMP and EST enrollment carry, into an
  *   array of messages, each with its `CertRequest` (certReqId, a `CertTemplate`
  *   of the requested certificate fields, and any registration controls), an
  *   optional proof-of-possession, and optional registration info.
@@ -327,7 +327,7 @@ var CERT_REQ_MESSAGES = schema.seqOf(CERT_REQ_MSG, {
  * surfaced. `popo` is
  * `null`, `{ type: "raVerified" }`, `{ type: "signature", poposkInput,
  * algorithmIdentifier, signature }`, or `{ type: "keyEncipherment" |
- * "keyAgreement", method, bytes }` (where `method` is the POPOPrivKey alternative --
+ * "keyAgreement", method, bytes }` (where `method` is the POPOPrivKey alternative:
  * `thisMessage` / `subsequentMessage` / `dhMAC` / `agreeMAC` / `encryptedKey`, each
  * structurally validated, the `encryptedKey` EnvelopedData included). When present, `poposkInput` is
  * `{ bytes, signedBytes, publicKey }`, where `bytes` is the raw wire `[0]` TLV,
@@ -385,7 +385,7 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || null, Pem
  * @related    pki.schema.crmf.pemDecode
  *
  * Wrap DER bytes in a PEM envelope. RFC 4211 registers no RFC 7468 label, so
- * `label` is REQUIRED -- the operator names the envelope explicitly (mirroring
+ * `label` is REQUIRED: the operator names the envelope explicitly (mirroring
  * `pemDecode`, which accepts any label). Omitting it throws `pem/bad-label`.
  *
  * @example

package/lib/schema-csr.js

@@ -21,7 +21,7 @@
  *   A CSR is self-signed only in the sense that the requester proves possession of
  *   the private key; unlike a certificate or CRL there is no inner signature
  *   algorithm to agree with, the subject MAY be empty, and the attribute set has
- *   no uniqueness constraint -- the parser deliberately omits those three
+ *   no uniqueness constraint: the parser deliberately omits those three
  *   certificate/CRL guards.
  *
  * @card

package/lib/schema-csrattrs.js

@@ -24,7 +24,7 @@
  *   and `id-aa-certificationRequestInfoTemplate` -> a fully-decoded `template`.
  *
  *   Structure is strict-DER throughout, but UNKNOWN OIDs and attribute types
- *   are TOLERATED -- surfaced raw, never a parse fault ("the client MUST ignore
+ *   are TOLERATED: surfaced raw, never a parse fault ("the client MUST ignore
  *   any OID or attribute it does not recognize", RFC 8951 sec. 4.5.2). The
  *   RFC 9908 semantic MUSTs that ARE enforced fail closed with a typed
  *   `csrattrs/*` code: at most one `id-ExtensionReq` attribute, its values a SET

package/lib/schema-engine.js

@@ -9,7 +9,7 @@
  * @order      60
  *
  * @intro
- *   L2 of the ASN.1 stack -- a declarative structure-schema engine. A schema is
+ *   L2 of the ASN.1 stack: a declarative structure-schema engine. A schema is
  *   plain data (`{kind, ...}` descriptors built by the combinators here) and
  *   `walk(schema, node, ctx)` interprets it against a decoded DER node. The
  *   engine is where every cross-cutting structural rule lives ONCE: the shape
@@ -179,7 +179,7 @@ function implicitSeqOf(tag, item, opts) {
  * Interpret a declarative schema against a decoded DER node, enforcing the
  * schema's structural rules (shape assertion, arity, optional / context-tagged
  * fields in increasing tag order, SET-OF uniqueness) and returning the built
- * value -- or the match tree (`{ node, fields | items }`, with the build output
+ * value, or the match tree (`{ node, fields | items }`, with the build output
  * on `.result`) for a structure with no build fn. `ctx = { E, prefix, oid }`
  * supplies the typed-error constructor, the error-code family prefix, and the
  * OID registry a build fn resolves names through.
@@ -464,8 +464,8 @@ function _encodeChoice(schema, value, ctx) {
  * @related    pki.schema.engine.walk, pki.asn1.decode
  *
  * Decode a fresh DER (or, with `ber: true`, BER) blob carried inside an
- * already-decoded value -- an OCTET STRING whose content is itself an encoded
- * structure -- and walk it against a schema. A codec failure is wrapped in the
+ * already-decoded value (an OCTET STRING whose content is itself an encoded
+ * structure) and walk it against a schema. A codec failure is wrapped in the
  * caller's typed `code`; a schema rejection keeps its own code. This is the
  * one named form of the re-decode idiom, so the caps that a fresh
  * `pki.asn1.decode` would restart from zero can be carried across re-decode

package/lib/schema-ocsp.js

@@ -29,7 +29,7 @@
  *
  * @card
  *   Parse DER / PEM OCSP requests and responses (RFC 6960) into structured,
- *   validated fields -- per-certificate status, responder identity, raw tbs bytes for
+ *   validated fields: per-certificate status, responder identity, raw tbs bytes for
  *   external verification, certificates kept raw, fail-closed.
  */
 

package/lib/schema-pkcs12.js

@@ -27,7 +27,7 @@
  *   MAC-less store surfaces `integrityMode: "none"` for the caller's policy
  *   to judge. RFC 7292
  *   sec. 4.1 encodes content in BER, so parsing this one format accepts exactly
- *   two BER shapes -- indefinite lengths and constructed OCTET STRINGs --
+ *   two BER shapes (indefinite lengths and constructed OCTET STRINGs)
  *   anywhere in the store; every other strictness verdict, and every other
  *   format, stays strict DER, fail-closed.
  *
@@ -406,7 +406,7 @@ function _buildBag(rec, state, ctx) {
  * Parse a DER / BER `Buffer` or a PEM string into a structured PFX:
  * `{ version, integrityMode, mac, macedBytes, authSafeSigned, safeBags,
  * encryptedSafes }`. `integrityMode` is `"password"` (id-data authSafe with
- * MacData -- `mac` carries `{ kind, hashOid, hashName, hashParameters,
+ * MacData: `mac` carries `{ kind, hashOid, hashName, hashParameters,
  * pbmac1, macValue, macSalt, iterations }`, where `kind` distinguishes the
  * RFC 9579 PBMAC1 arm; for PBMAC1 the required parameters are validated and
  * decoded onto `pbmac1` (`{ kdf: { salt, iterationCount, keyLength, prfOid,

package/lib/schema-pkcs8.js

@@ -19,7 +19,7 @@
  *
  *   A PKCS#8 key is a container, not a signed structure: it has no signature, no
  *   distinguished name, and no to-be-signed region. The private-key OCTET STRING
- *   content is kept raw -- the algorithm-specific inner key (an RSAPrivateKey, an
+ *   content is kept raw: the algorithm-specific inner key (an RSAPrivateKey, an
  *   ECPrivateKey, a CurvePrivateKey) is decoded by the caller using the surfaced
  *   algorithm OID, so an unknown or future key type never fails the parse. An
  *   `ENCRYPTED PRIVATE KEY` (EncryptedPrivateKeyInfo, RFC 5958 sec. 3) is recognized
@@ -28,7 +28,7 @@
  *
  * @card
  *   Parse DER / PEM PKCS#8 private keys (RFC 5208 / 5958) into structured,
- *   validated fields -- algorithm, raw key bytes, attributes, optional public key,
+ *   validated fields: algorithm, raw key bytes, attributes, optional public key,
  *   fail-closed. Encrypted keys are recognized, not decrypted.
  */
 

package/lib/schema-smime.js

@@ -37,7 +37,7 @@
  *
  * @card
  *   Decode RFC 5035 ESS SigningCertificate / SigningCertificateV2 and RFC 8551
- *   SMIMECapabilities signed-attribute values -- cert-hash binding, validated
+ *   SMIMECapabilities signed-attribute values: cert-hash binding, validated
  *   issuer GeneralNames, ordered capability list, OID-dispatched, fail-closed.
  */
 

package/lib/schema-tsp.js

@@ -11,7 +11,7 @@
  *
  * @intro
  *   RFC 3161 Time-Stamp Protocol handling. A `TimeStampResp` is what a client
- *   receives from a TSA -- a `PKIStatusInfo` plus, on success, a `TimeStampToken`;
+ *   receives from a TSA: a `PKIStatusInfo` plus, on success, a `TimeStampToken`;
  *   `parse` decodes it and enforces the status-to-token coupling (a granted
  *   response carries a token, a rejection does not). A `TimeStampToken` is itself a
  *   CMS SignedData whose encapsulated content is a `TSTInfo`, so `parseToken`
@@ -279,8 +279,8 @@ var parseRequest = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorCl
  * @spec       RFC 3161
  * @related    pki.schema.tsp.parseToken, pki.schema.tsp.parse
  *
- * Parse a bare `TSTInfo` payload (a DER `Buffer`) -- the structure a timestamp token
- * encapsulates -- into `{ version, policy, messageImprint, serialNumber, genTime,
+ * Parse a bare `TSTInfo` payload (a DER `Buffer`, the structure a timestamp token
+ * encapsulates) into `{ version, policy, messageImprint, serialNumber, genTime,
  * accuracy, ordering, nonce, tsa, extensions }`. `messageImprint.hashedMessage` is
  * the raw digest; `serialNumber` / `nonce` are lossless (BigInt + hex); `genTime` is
  * a `Date` with sub-second precision. A malformed structure throws a typed
@@ -312,7 +312,7 @@ var parseTstInfo = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorCl
  *
  * Parse a DER `Buffer` or a PEM string into a `TimeStampResp`: `{ status,
  * statusString, failInfo, timeStampToken }`. The status-to-token coupling is
- * enforced -- a granted response (status 0/1) carries `timeStampToken` (surfaced raw
+ * enforced: a granted response (status 0/1) carries `timeStampToken` (surfaced raw
  * for `parseToken`), any other status does not. `failInfo` decodes the
  * `PKIFailureInfo` named bits. A malformed structure throws a typed `TspError`.
  *
@@ -340,7 +340,7 @@ var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: Ts
  * @spec       RFC 3161, RFC 5652
  * @related    pki.schema.tsp.parse, pki.schema.cms.parse
  *
- * Parse a `TimeStampToken` (a DER `Buffer` or PEM) -- a CMS SignedData whose
+ * Parse a `TimeStampToken` (a DER `Buffer` or PEM): a CMS SignedData whose
  * encapsulated content is a `TSTInfo`. Composes `pki.schema.cms.parse`, asserts the
  * `id-ct-TSTInfo` content type (`tsp/wrong-econtent-type`), that the content is
  * attached (`tsp/detached-token`), the single-signer rule (`tsp/multi-signer`,
@@ -434,7 +434,7 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || null, Pem
  * @related    pki.schema.tsp.pemDecode
  *
  * Wrap DER bytes in a PEM envelope. RFC 3161 defines no standard PEM label, so
- * `label` is REQUIRED -- the operator names the envelope explicitly (mirroring
+ * `label` is REQUIRED: the operator names the envelope explicitly (mirroring
  * `pemDecode`, which accepts any label). Omitting it throws `pem/bad-label`.
  *
  * @example

package/lib/schema-x509.js

@@ -12,7 +12,7 @@
  *
  * @intro
  *   X.509 certificate handling per RFC 5280. The seed surface is
- *   `parse` -- turn a DER or PEM certificate into a structured,
+ *   `parse`, which turns a DER or PEM certificate into a structured,
  *   fully-decoded object: version, serial, signature algorithm, issuer
  *   and subject distinguished names, validity window (as real `Date`s),
  *   subject public-key info, and the extension list. The parser composes
@@ -49,7 +49,7 @@ var PemError = frameworkError.PemError;
  * @related    pki.schema.x509.pemEncode
  *
  * Extract the DER bytes from a PEM block (default label `CERTIFICATE`, the
- * RFC 7468 sec. 5 armor -- the canonical-label default every sibling format
+ * RFC 7468 sec. 5 armor, the canonical-label default every sibling format
  * applies). Pass a `label` to enforce a different block type, or an explicit
  * `null` to take the first block of any type. Throws `PemError` on a
  * missing / mismatched envelope or a non-base64 body.

package/lib/shbs.js

@@ -6,10 +6,9 @@
  * @nav        Signatures
  * @title      Stateful hash-based
  * @fullname   Stateful hash-based signatures: LMS and XMSS
- * @intro Stateful hash-based signature VERIFICATION -- HSS/LMS (RFC 8554),
+ * @intro Stateful hash-based signature VERIFICATION: HSS/LMS (RFC 8554),
  *   carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST
- *   SP 800-208. Verify only, by deliberate design: stateful hash-based signing
- *   is catastrophic to get wrong. Each one-time key must be used exactly once,
+ *   SP 800-208. Verify only. Each one-time key must be used exactly once,
  *   so the private key embeds a monotonic index whose state must advance and
  *   persist atomically across every signature and every process restart. A single
  *   index reuse (a restored VM snapshot, a crashed writer, a concurrent signer)
@@ -222,7 +221,7 @@ function _asBytes(x, label) { return guard.bytes.source(x, ShbsError, "shbs/bad-
  * @related pki.shbs.verifyLms
  *
  * Verify an HSS (Hierarchical Signature System) signature over `message` under
- * `publicKey` -- the wire form RFC 9802 (X.509) and RFC 9708 (CMS) carry for
+ * `publicKey`, the wire form RFC 9802 (X.509) and RFC 9708 (CMS) carry for
  * `id-alg-hss-lms-hashsig`. The public key and signature are the raw HSS octet
  * blobs the certificate / CMS parsers already surface (no ASN.1 wrapping). Every
  * level of the hierarchy must verify: a single failing level yields false.

package/lib/sign-scheme.js

@@ -46,7 +46,7 @@ var MLDSA_SUITABLE_DIGEST = {
   "ML-DSA-65": { sha384: 1, sha512: 1, shake256: 1 },
   "ML-DSA-87": { sha512: 1, shake256: 1 },
 };
-// @enforced-by behavioral -- an own-property table read has no rename-proof shape distinct from a
+// @enforced-by behavioral -- an own-property table read has no rename-proof shape distinct from a legitimate lookup, so a RED conformance vector is the guard
 function mldsaDigestSuitable(mlName, md) {
   if (!intrinsic.hasOwn(MLDSA_SUITABLE_DIGEST, mlName)) return false;
   var row = MLDSA_SUITABLE_DIGEST[mlName];

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];