@blamejs/pki 0.6.28 → 0.6.30

package/lib/lint.js

@@ -6,7 +6,7 @@
  * @nav        Tooling
  * @title      Lint
  * @fullname   Certificate linting against CA/Browser Forum requirements
- * @intro The certificate LINTING engine -- the zlint / pkilint of JavaScript. It walks an
+ * @intro The certificate LINTING engine, the zlint / pkilint of JavaScript. It walks an
  *   ALREADY-PARSED certificate (from `pki.schema.x509.parse`, whose extension values it
  *   decodes with the shared RFC 5280 decoders) and emits graded, advisory FINDINGS: each
  *   with a stable id, a severity (`fatal` > `error` > `warn` > `notice` > `pass`), a source,

package/lib/merkle.js

@@ -11,7 +11,7 @@
  *
  * @intro
  *   RFC 6962 (Certificate Transparency) / RFC 9162 (CT 2.0) Merkle-tree hash
- *   and proof-verification core -- the load-bearing primitive a static-CT
+ *   and proof-verification core: the load-bearing primitive a static-CT
  *   client, a Merkle-Tree-Certificates relying party, and a sigstore / Rekor
  *   inclusion check all compose. Every verb is strict verification over
  *   SHA-256: zero new crypto.
@@ -234,11 +234,7 @@ function verifyInclusion(opts) {
  * `merkle/no-consistency-claim`. RFC 6962 sec. 2.1.2 defines the proof for
  * `0 < oldSize < newSize`: the empty tree is a prefix of every tree by
  * definition, so there is no proof to check and nothing at all binds `newRoot`.
- * Returning `true` there would say a step was proven append-only when nothing had
- * been proven, and a monitor written `if (!verifyConsistency(...)) alarm()` would
- * take that silence for evidence. A caller with no prior tree has an inclusion
- * question about the new one, or should start from a checkpoint it already
- * trusts. Two empty trees are still answered:
+ * Two empty trees are still answered:
  * that is the degenerate identity case, and both roots must be `emptyRootHash()`.
  *
  * A malformed input throws a typed `merkle/*` error: `oldSize > newSize`, a

package/lib/mime.js

@@ -3,11 +3,11 @@
 "use strict";
 /**
  * @internal
- * lib/mime.js -- a minimal MIME entity framer + canonicalizer, the message-layer engine primitive
+ * lib/mime.js: a minimal MIME entity framer + canonicalizer, the message-layer engine primitive
  * under pki.smime (RFC 8551 S/MIME) and any future MIME-carrying feature. It parses an entity into
  * its headers + body, canonicalizes a text entity to the RFC 8551 sec. 3.1.1 form (CRLF line endings),
  * splits a multipart body on its boundary, and builds an entity/multipart back. There is NO crypto
- * here -- the CMS layer signs/verifies the canonical bytes this module produces.
+ * here. The CMS layer signs/verifies the canonical bytes this module produces.
  *
  * The load-bearing rule is canonicalization: the detached signature over a multipart/signed first part
  * is computed over that part's canonical MIME form, so the signer and verifier MUST share one

package/lib/ocsp.js

@@ -352,14 +352,14 @@ function _certStatusNode(status, opts) {
 
 /**
  * @primitive pki.ocsp.buildErrorResponse
- * @signature pki.ocsp.buildErrorResponse(status) -> Buffer | string
+ * @signature pki.ocsp.buildErrorResponse(status) -> Buffer
  * @since 0.2.22
  * @status stable
  * @spec RFC 6960
  * @related pki.ocsp.sign
  *
- * Build an UNSIGNED error OCSPResponse -- `malformedRequest` / `internalError` / `tryLater` /
- * `sigRequired` / `unauthorized` -- carrying only the responseStatus and no responseBytes (RFC 6960
+ * Build an UNSIGNED error OCSPResponse, one of `malformedRequest` / `internalError` / `tryLater` /
+ * `sigRequired` / `unauthorized`, carrying only the responseStatus and no responseBytes (RFC 6960
  * sec. 2.3: an error message conveys no certificate status and is not signed).
  *
  * @example
@@ -374,7 +374,7 @@ function buildErrorResponse(status) {
 
 /**
  * @primitive pki.ocsp.verify
- * @signature pki.ocsp.verify(response, opts) -> Promise<{ status, responderAuthorized, signatureValid, thisUpdate, nextUpdate, revocationReason?, revocationTime?, nonceMatched?, reason }>
+ * @signature pki.ocsp.verify(response, opts) -> Promise<{ status, responderAuthorized, signatureValid, matched, thisUpdate, nextUpdate, revocationReason?, revocationTime?, nonceMatched?, reason }>
  * @since 0.2.22
  * @status stable
  * @spec RFC 6960, RFC 9654, RFC 5019
@@ -524,9 +524,9 @@ function _signerVerdict(parsed, found, failReason) {
  * request carried (or opts.certs supplied), including intermediates that do not sign and so are absent
  * from `signerCerts`: the responder passes it as the `opts.candidates` pool to `pki.path.build`, which
  * discovers and validates the ordered path from a `signerCerts` entry (leaf) up to a trust anchor.
- * The responder then confirms that certificate is authorized to sign the request -- its `keyUsage`,
+ * The responder then confirms that certificate is authorized to sign the request: its `keyUsage`,
  * where present, must assert `digitalSignature` (RFC 5280 sec. 4.2.1.3, since the certificate signed
- * the request) -- and compares its subject to the `requestorName` it expects. The decoded
+ * the request). It also compares the certificate's subject to the `requestorName` it expects. The decoded
  * `requestList`, `requestExtensions` and `version` are
  * returned so the CertIDs being asked about need no re-parse.
  *

package/lib/oid.js

@@ -446,7 +446,7 @@ function register(dotted, n) {
  *
  * Register a whole OID family in one call. `base` is the shared arc prefix
  * (the starting variable a class of OIDs has in common) and `members` maps
- * each name to its trailing arc -- a number, or a short arc array for a
+ * each name to its trailing arc: a number, or a short arc array for a
  * multi-level leaf. Each full OID is derived as `base` followed by the leaf,
  * so a family is declared as its hierarchy and no full path is re-spelled.
  * This is the primitive the built-in seed set itself is built from.

package/lib/path-validate.js

@@ -10,9 +10,9 @@
  * @intro
  * RFC 5280 6 certification-path validation as a pure, re-entrant algorithm
  * over already-parsed certificates. `pki.path.validate(path, opts)` runs the
- * 6.1 state machine -- signature chaining, validity windows, name chaining,
+ * 6.1 state machine (signature chaining, validity windows, name chaining,
  * basic constraints and path length, key usage, name constraints, and the
- * certificate-policy tree -- and returns a structured verdict with a per-check
+ * certificate-policy tree) and returns a structured verdict with a per-check
  * reason code for every step. Validity-window enforcement is always on, with
  * the check date an explicit input; the trust anchor is an input, never one of
  * the validated certificates, and no input object is mutated.
@@ -20,12 +20,12 @@
  * Revocation is a pluggable hook: `pki.path.crlChecker(crls)` ships a CRL
  * consultation built on `pki.schema.crl.parse`; an OCSP checker satisfies the
  * same interface. Signature verification derives its algorithm from the
- * certificate and the issuer key -- never from a value the message controls --
+ * certificate and the issuer key, never from a value the message controls,
  * and fails closed on an unknown critical extension, an undetermined
  * revocation status, or any structural fault.
  *
  * @card
- *   RFC 5280 6 certification-path validation -- run the 6.1 state machine over
+ *   RFC 5280 6 certification-path validation: run the 6.1 state machine over
  *   an ordered path and a trust anchor for a structured, fail-closed verdict
  *   with per-check reason codes. Pure and re-entrant.
  */
@@ -836,7 +836,7 @@ function validateCriticalExtensionStructure(cert) {
  * inputs (`initialExplicitPolicy`,
  * `initialAnyPolicyInhibit`, `initialPolicyMappingInhibit`,
  * `userInitialPolicySet`, and `initialPermittedSubtrees` /
- * `initialExcludedSubtrees` -- arrays of `{ tag, base }` where `tag` is the
+ * `initialExcludedSubtrees`: arrays of `{ tag, base }` where `tag` is the
  * GeneralName tag number and `base` that form's constraint value), an
  * optional `requiredEku` (key purposes the target's extendedKeyUsage must
  * assert, given as registered OID names or dotted OID strings; an absent
@@ -846,9 +846,9 @@ function validateCriticalExtensionStructure(cert) {
  * are validated at the entry point. A mis-shaped value throws `path/bad-input`,
  * so it cannot silently go unapplied. Returns `{ valid, revocationChecked, anchorConstraints,
  * path, results, workingPublicKey, workingPublicKeyAlgorithm,
- * workingPublicKeyParameters, validPolicyTree }` where `results[i].checks`
+ * workingPublicKeyParameters, validPolicyTree, userConstrainedPolicySet }` where `results[i].checks`
  * carries a per-check reason code (`path/*`) for every step. Pure and
- * re-entrant -- no input object is mutated. An empty path or a missing anchor
+ * re-entrant: no input object is mutated. An empty path or a missing anchor
  * throws a typed `PathError`.
  *
  * `valid` alone cannot say whether revocation was ever established, so
@@ -1365,7 +1365,7 @@ function selectDelta(candidates) {
  * (`thisUpdate`/`nextUpdate`), and reports `{ status: "good"|"revoked"|
  * "unknown" }`. A partitioned/sharded CRL (a critical IDP naming a
  * distribution point) establishes "good" when it corresponds to one of the
- * certificate's own cRLDistributionPoints -- at least one identically-encoded
+ * certificate's own cRLDistributionPoints: at least one identically-encoded
  * name in common (RFC 5280 sec. 6.3.3). Reason-sharded CRLs ACCUMULATE: each
  * corresponding CRL contributes its interim reason mask (sec. 6.3.3(d)) and the
  * certificate is "good" once the shards together cover all eight revocation
@@ -1713,21 +1713,21 @@ function ocspChecker(responses) {
  * directly, or a CA-issued delegate bearing both id-kp-OCSPSigning and
  * id-pkix-ocsp-nocheck and passing the full out-of-path certificate gates),
  * verifies the response signature over `tbsResponseDataBytes`, and checks
- * currency (`thisUpdate`/`nextUpdate`) -- there is no weaker second OCSP verify
+ * currency (`thisUpdate`/`nextUpdate`). There is no weaker second OCSP verify
  * path. It is fail-closed and never throws on an unauthorized, stale, or
  * unverifiable response: those yield `{ status: "unknown" }` with the granular
  * `responderAuthorized`/`signatureValid`/`matched` flags and a `reason`; a
  * `revoked` status surfaces its `revocationReason`. Setting `opts.historicalMode`
  * treats a revocation whose `revocationTime` is strictly after `time` as not-yet-
- * revoked (`good`) -- for validating a signature as of a past `time`, before the
+ * revoked (`good`): for validating a signature as of a past `time`, before the
  * certificate was later revoked; the responder certificate is still validated at
  * `time` either way. `time` must be a valid `Date`. A malformed response's parse
  * fault surfaces as the parser's typed `ocsp/*` / `asn1/*` error.
  *
  * The response is its DER bytes, a PEM string, or an unmodified
  * `pki.schema.ocsp.parseResponse` result. A REBUILT parsed response is refused. A
- * signature check has three parts -- the signature, the algorithm that verifies it,
- * and the bytes it covers -- and on a parsed object all three are separate properties:
+ * signature check has three parts (the signature, the algorithm that verifies it,
+ * and the bytes it covers) and on a parsed object all three are separate properties:
  * a genuine CA signature over a certificate that CA issued, relabeled, verifies as a
  * ResponseData signature for a response that never existed. The parser marks what it
  * returns, so those three are known to have been derived together from one byte
@@ -2285,7 +2285,7 @@ async function _fetchAiaIssuers(current, aia) {
  * from a certificate's Authority Information Access `caIssuers` URL (RFC 5280 sec. 4.2.2.1) over
  * `pki.transport`: the fetch triggers only on a pool miss, every fetched certificate is UNTRUSTED pool material
  * that still flows through `validate` when validation is on (never a trust anchor), and the whole surface is
- * SSRF/amplification bounded -- https-only, a total fetch budget (a SILENT cap, never a throw that denies a
+ * SSRF/amplification bounded: https-only, a total fetch budget (a SILENT cap, never a throw that denies a
  * buildable path), a per-cert URL cap, a build-wide URL dedupe, a response size + certificate-count cap, and no
  * redirect following; every fetch fault is a silent skip. `aiaFetches` reports how many network GETs the build
  * performed (`0` when `fetchAia` is off). NOTE: with `opts.validate:false` (pure-builder mode) a fetched cert is

package/lib/pkcs12-build.js

@@ -7,7 +7,7 @@
  * @title      PKCS#12
  * @fullname   PKCS#12 keystores (.p12 and .pfx): build and open
  * @intro The PKCS#12 (.p12 / .pfx) producing side (RFC 7292, RFC 9579). `pki.pkcs12.build` assembles a
- *   password-integrity PFX -- key, certificate, CRL, and secret bags (shrouded keys and cert safes encrypted
+ *   password-integrity PFX: key, certificate, CRL, and secret bags (shrouded keys and cert safes encrypted
  *   under RFC 8018 PBES2) wrapped in an AuthenticatedSafe, protected by either a classic Appendix B HMAC or
  *   an RFC 9579 PBMAC1 (PBKDF2 + HMAC) MAC, over AES-128/192/256-CBC and SHA-256/384/512. Every password is
  *   encoded the PKCS#12 way (BMPString + NULL, Appendix B.1), so a file it emits opens in OpenSSL and NSS.
@@ -427,7 +427,7 @@ function _normalizeSpec(spec, opts, form) {
  *
  * @opts
  *   - `password` -- the shared privacy + integrity password (string / Buffer / Uint8Array).
- *   - `mac` -- `false` for a MAC-less store, or `{ algorithm: 'hmac'(default)|'pbmac1', hash: 'sha256'(default)|'sha1'|'sha384'|'sha512', salt?, iterations? }`. `keyLength` is a `pbmac1` field: the classic Appendix B derivation produces a key at the hash's own output length, and naming one under `hmac` is refused.
+ *   - `mac` -- `false` for a MAC-less store, or `{ algorithm: 'hmac'(default)|'pbmac1', hash: 'sha256'(default)|'sha1'|'sha384'|'sha512', salt?, iterations?, password? }`. `password` overrides the shared integrity password for the MAC. `keyLength` is a `pbmac1` field: the classic Appendix B derivation produces a key at the hash's own output length, and naming one under `hmac` is refused.
  *   - `integrity` -- `{ mode: 'public-key', signer: { cert, key, digestAlgorithm?, pss? } | signers: [ ... ], sid?, signingTime?, certificates? }` for public-key integrity (a CMS SignedData authSafe over any `pki.cms.sign` signer algorithm, no MacData). Combining it with a truthy `mac` is rejected.
  *   - `recipientCerts` -- (public-key privacy convenience) `[certDer|PEM, ...]`; the convenience-form cert + key are placed in one recipient-enveloped safe (a plaintext keyBag). For the full form, set per-`safeContents` `recipients: [{ cert }, ...]` -- CERTIFICATE recipients only (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM, dispatched off the cert key); a password or KEK recipient is not public-key privacy and is rejected -- with an optional `contentEncryptionAlgorithm` (`aes-128|192|256-cbc`, default 256; GCM/AEAD rejected). `encrypt` (password) and `recipients` (public-key) on the same safe is rejected; privacy is independent of integrity.
  *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
@@ -534,7 +534,7 @@ async function _build(spec, opts) {
  * a byte range the object carries, and the parser's mark is what says that range and the store it describes
  * came from one place. `Object.assign`, spread and a JSON round-trip drop the mark. The password is BMPString+NULL encoded (RFC 7292 App. B.1), the MAC is
  * recomputed over the store's exact AuthenticatedSafe byte range (`macedBytes`) using the store's own MAC
- * parameters -- the classic Appendix B (ID=3) HMAC or the RFC 9579 PBMAC1 -- and constant-time-compared to
+ * parameters, the classic Appendix B (ID=3) HMAC or the RFC 9579 PBMAC1, and constant-time-compared to
  * the stored MAC value. The verdict's `valid` is the password match, and `macAlgorithm` (`hmac` or `pbmac1`),
  * `macAlgorithmName` (the digest / scheme, e.g. `sha1`, `sha256`), and `iterationCount` name the integrity
  * algorithm the store used, so a caller can reject a legacy SHA-1 MAC by inspecting them rather than
@@ -617,7 +617,7 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  * SignedData signature, per RFC 7292 sec. 4 / 5.1, so no bag from a store whose integrity check fails is trusted),
  * then decrypt every PBES2 privacy safe and pkcs8ShroudedKeyBag with the password, and every id-envelopedData
  * (public-key privacy) safe with `opts.recipientKey` (RFC 7292 sec. 3.1, via `pki.cms.decrypt`), returning a
- * structured bundle `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` with each private key as PKCS#8
+ * structured bundle `{ valid, integrityMode, macVerified, signers, keys, certs, crls, secrets }` with each private key as PKCS#8
  * `PrivateKeyInfo` DER (re-validated), each certificate / CRL / secret as raw DER, all carrying their
  * `friendlyName` / `localKeyId` for pairing. `pfx` is the store's DER `Buffer`, a PEM string, or an
  * unmodified `pki.schema.pkcs12.parse` result; a rebuilt parsed store is refused, since the bytes whose

package/lib/rfc3339.js

@@ -3,10 +3,10 @@
 "use strict";
 /**
  * @internal
- * lib/rfc3339.js -- RFC 3339 date-time parsing + validation, a fail-closed engine primitive shared by
+ * lib/rfc3339.js: RFC 3339 date-time parsing + validation, a fail-closed engine primitive shared by
  * pki.acme (a boolean field-validator over server-supplied JSON) and pki.ct (parse a CT log-list
  * timestamp / temporal-interval bound to a comparable Date). Beyond the grammar it enforces CALENDAR
- * validity -- a syntactically well-formed but impossible instant (month 13, February 30, hour 25, a
+ * validity: a syntactically well-formed but impossible instant (month 13, February 30, hour 25, a
  * :60 leap second, a +25:00 offset) is rejected, so a downstream expiry / window comparison never runs
  * on a value JS `Date` would silently roll over or `Date.parse` would NaN. Like the byte-reader / guard
  * family, `parse` takes the caller's `(code, message) -> error` factory so every consumer keeps its own

package/lib/scep.js

@@ -14,7 +14,7 @@
  *   issued certificate) in two nested CMS layers: an inner EnvelopedData
  *   (`pkcsPKIEnvelope`) that encrypts the messageData to the recipient, and an
  *   outer SignedData that signs it under a set of authenticated transaction
- *   attributes -- messageType, transactionID, pkiStatus, failInfo, and the
+ *   attributes: messageType, transactionID, pkiStatus, failInfo, and the
  *   sender/recipient nonces (RFC 8894 sec. 3). `pki.scep.build` assembles a
  *   request pkiMessage (PKCSReq, RenewalReq, CertPoll, GetCert, or GetCRL) or a
  *   CA-side CertRep response; `pki.scep.parse` verifies the
@@ -520,7 +520,7 @@ async function parse(bytes, opts) {
   var messageType = MESSAGE_TYPE_BY_CODE[messageTypeCode];
   if (messageType == null) throw _err("scep/bad-message-type", "unknown messageType " + JSON.stringify(messageTypeCode) + " (RFC 8894 sec. 3.2.1.2)");
   if (_PARSE_SUPPORTED[messageType] !== 1) {
-    throw _err("scep/unsupported-message-type", "pki.scep.parse reads PKCSReq, RenewalReq, and CertRep; " + messageType + " is not read in this release");
+    throw _err("scep/unsupported-message-type", "pki.scep.parse reads " + Object.keys(_PARSE_SUPPORTED).join(", ") + "; " + messageType + " is not read in this release");
   }
   var out = {
     signatureValid: true, signerAuthenticated: signerAuthenticated, signerCert: signer.cert,
@@ -717,19 +717,7 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
   }
   return step(url);
 }
-function _copyAnchor(a) { return Buffer.isBuffer(a) ? Buffer.from(a) : a; }
-function _snapshotProxy(p) {
-  if (p == null || typeof p !== "object" || Array.isArray(p)) return p;
-  var out = Object.assign({}, p);
-  if (p.auth != null && typeof p.auth === "object" && !Array.isArray(p.auth)) out.auth = Object.assign({}, p.auth);
-  if (p.tls != null && typeof p.tls === "object" && !Array.isArray(p.tls)) {
-    out.tls = Object.assign({}, p.tls);
-    var a = p.tls.anchors;
-    if (Array.isArray(a)) out.tls.anchors = a.map(_copyAnchor);
-    else if (a != null) out.tls.anchors = _copyAnchor(a);
-  }
-  return out;
-}
+function _snapshotProxy(p) { return httpTransport.snapshotProxy(p); }
 function _client(method, url, body, headers, opts) {
   var transport = opts.transport || httpTransport.https({ E: _err, errPrefix: "scep" });
   var budgets = {

package/lib/schema-all.js

@@ -153,7 +153,7 @@ var FORMATS = [
  * The names of every registered format, in detection order.
  *
  * @example
- *   pki.schema.all();  // -> ["cms", "tsp", "crmf", "cmp", "ocsp-request", "ocsp-response", "pkcs12", "pkcs8", "csr", "attrcert", "attrcert-v1", "crl", "x509"]
+ *   pki.schema.all();  // -> ["cms", "tsp", "crmf", "cmp", "csrattrs", "ocsp-request", "ocsp-response", "pkcs12", "pkcs8", "csr", "attrcert", "attrcert-v1", "crl", "x509"]
  */
 function all() { return FORMATS.map(function (f) { return f.name; }); }
 

package/lib/schema-attrcert.js

@@ -11,7 +11,7 @@
  * @intro
  *   X.509 Attribute Certificate handling per RFC 5755. An attribute certificate
  *   binds a holder to a set of privilege attributes (role, group, clearance)
- *   without carrying a public key -- the authorization counterpart to an identity
+ *   without carrying a public key, the authorization counterpart to an identity
  *   certificate. `parse` decodes a v2 `AttributeCertificate` into its holder,
  *   issuer, validity window (real `Date`s), attributes, and extensions, reusing
  *   the shared signed-envelope so the raw `tbsBytes` (the exact signed region) and

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