@blamejs/pki 0.6.29 → 0.6.31

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);
@@ -643,6 +643,38 @@ function paths(baseUrl, opts) {
 
 function _attr(typeOid, valueNodes) { return asn1.build.sequence([asn1.build.oid(typeOid), asn1.build.set(valueNodes)]); }
 
+/**
+ * @primitive  pki.est.challengePasswordFromTlsUnique
+ * @signature  pki.est.challengePasswordFromTlsUnique(channelBinding) -> Buffer
+ * @since      0.6.31
+ * @originated 0.1.24
+ * @status     stable
+ * @spec       RFC 7030, RFC 5929, RFC 2985
+ * @related    pki.csr.sign, pki.transport.https, pki.est.simpleenroll
+ *
+ * Encode RFC 5929 tls-unique channel-binding bytes as the RFC 7030 sec. 3.5
+ * challengePassword, binding an enrollment request to the TLS session it is sent over.
+ * The returned Buffer is a DER `Attribute` (`SEQUENCE { type OID, SET { PrintableString } }`)
+ * carrying the base64 of the binding, for a caller assembling certification-request
+ * attributes directly. Empty or non-byte input is `est/bad-input`; a base64 value longer
+ * than 255 octets is `est/tls-unique-too-long`.
+ *
+ * To sign a channel-bound request with `pki.csr.sign`, pass the base64 string as
+ * `spec.challengePassword` instead: that signer builds this same attribute itself and
+ * REFUSES a pre-encoded challengePassword in `spec.attributes` (`csr/bad-input`), so the
+ * two forms are alternatives, never combined. `pki.transport.https` supplies the binding
+ * as `tls.tlsUnique`, and a request body given as a function receives it before the body
+ * is written, which is the point at which the request can still be signed over it.
+ *
+ * @example
+ *   // the binding comes from the connection; pki.transport surfaces it as tls.tlsUnique
+ *   var binding = Buffer.from("9f86d081884c7d65", "hex");
+ *   var attr = pki.est.challengePasswordFromTlsUnique(binding);
+ *   attr[0] === 0x30;                                  // a DER Attribute SEQUENCE
+ *   // to SIGN a channel-bound request, hand pki.csr.sign the same value as a string
+ *   // via spec.challengePassword; it builds this identical attribute itself.
+ *   var challengePassword = binding.toString("base64");
+ */
 function challengePasswordFromTlsUnique(channelBinding) {
   if (!guard.bytes.isByteSource(channelBinding)) throw E("est/bad-input", "challengePasswordFromTlsUnique requires the channel-binding bytes");
   var _cb = guard.bytes.source(channelBinding, EstError, "est/bad-input", "the channel-binding bytes");
@@ -1006,7 +1038,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 +1466,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

package/lib/http-transport.js

@@ -16,15 +16,28 @@
  *   composes it (or an injected substitute) through one contract:
  *   `transport(request) -> Promise<{ status, headers, body, tls }>`. The first three are
  *   exactly what a message layer's classifier consumes, so no protocol semantics leak
- *   into the socket layer -- the transport owns socket lifecycle, the TLS trust policy,
+ *   into the socket layer: the transport owns socket lifecycle, the TLS trust policy,
  *   the streaming size cap, and the timeout budget; the caller owns HTTP status,
  *   content-type, redirect, and authentication decisions. `tls` reports the negotiated
- *   channel -- `{ protocol, cipher, peerCertificate }` -- which is the one fact a caller
- *   cannot recover from the response bytes. An INJECTED substitute should return it too:
+ *   channel, `{ protocol, cipher, peerCertificate, tlsUnique }`, facts a caller cannot
+ *   recover from the response bytes. `tlsUnique` is the RFC 5929 channel binding (the first
+ *   TLS Finished) on a TLS 1.2 connection, which `pki.est.challengePasswordFromTlsUnique`
+ *   base64-encodes into an EST challengePassword (RFC 7030 sec. 3.5); it is `null` on TLS 1.3,
+ *   where RFC 5929 defines no tls-unique. An INJECTED substitute should return these too:
  *   `pki.est.serverkeygen` asserts the negotiated cipher can protect the private key it
  *   is about to accept, and a transport that reports no cipher is trusted instead of
  *   refused (so a loopback test channel works), which means omitting the field silently
- *   skips that assertion.
+ *   skips that assertion. Because `tlsUnique` on the response arrives after the request
+ *   body was already sent, a request `body` MAY instead be a function `(tls) -> bytes`.
+ *   The transport invokes it once the handshake completes and before it writes the body,
+ *   passing the same `{ protocol, cipher, peerCertificate, tlsUnique }` object, so the
+ *   caller builds the request body (a channel-bound CSR) from `tlsUnique` on the very
+ *   connection the request is sent over. The callback returns bytes or a string, or a
+ *   promise of either, so the CSR can be signed with the toolkit's own asynchronous
+ *   signer while the connection is held open. A throw, a rejection, a missing return,
+ *   `null`, or any other value fails the request closed, so a callback that forgets to
+ *   return cannot post an empty enrollment to a CA. An explicit empty string is an
+ *   intentional empty body, and the request budget still bounds the whole exchange.
  *
  *   `pki.transport.https(defaults?)` binds TLS + budget defaults and returns a
  *   transport. Trust is EXPLICIT and fail-closed: a request is refused unless it
@@ -40,7 +53,7 @@
  * @card
  *   The shared fail-closed node:https transport (est / acme / cmp): explicit trust
  *   anchors, rejectUnauthorized always on, a TLS floor, a streaming response-size cap,
- *   and a timeout -- behind one `transport(request) -> {status, headers, body, tls}` seam.
+ *   and a timeout, behind one `transport(request) -> {status, headers, body, tls}` seam.
  */
 
 var nodeHttps = require("node:https");
@@ -80,6 +93,17 @@ function _stripIpv6Brackets(s) {
   return (s.length >= 2 && s.charAt(0) === "[" && s.charAt(s.length - 1) === "]") ? s.slice(1, s.length - 1) : s;
 }
 
+function _tlsInfo(socket) {
+  var proto = socket && socket.getProtocol ? socket.getProtocol() : null;
+  var cipher = socket && socket.getCipher ? socket.getCipher() : null;
+  var peer = socket && socket.getPeerCertificate ? socket.getPeerCertificate() : null;
+  var reused = socket && socket.isSessionReused ? socket.isSessionReused() : false;
+  var tlsUnique = (socket && socket.getFinished && socket.getPeerFinished && proto === "TLSv1.2")
+    ? (reused ? socket.getPeerFinished() : socket.getFinished()) : null;
+  if (tlsUnique != null && tlsUnique.length === 0) tlsUnique = null;
+  return { protocol: proto, cipher: cipher, peerCertificate: peer && peer.raw ? peer.raw : null, tlsUnique: tlsUnique };
+}
+
 function _pemifyAnchor(a) {
   if (typeof a === "string") return a;
   if (Buffer.isBuffer(a)) {
@@ -351,7 +375,7 @@ function _proxyErrorClass(e, C) {
  * (`transport/server-auth-failed`) all fail closed; `rejectUnauthorized` is always on.
  * A protocol client passes its own error factory (`defaults.E`) + `defaults.errPrefix`
  * to surface domain codes (`est/...`). The transport owns no HTTP/redirect/auth
- * semantics -- those live in the message layer that consumes the response triple.
+ * semantics; those live in the message layer that consumes the response triple.
  *
  * @opts
  *   - `tls.anchors` -- Explicit trust anchor(s): a DER/PEM Buffer, an array, or PEM string(s) (node `ca`).
@@ -393,11 +417,14 @@ function httpsTransport(defaults) {
     if (minVersion !== "TLSv1.2" && minVersion !== "TLSv1.3") throw E(C("bad-input"), "tls.minVersion must be 'TLSv1.2' or 'TLSv1.3' (never below the floor), got " + minVersion);
 
     var body = request.body;
-    if (guard.bytes.isByteSource(body)) body = guard.bytes.source(body, E, C("bad-input"), "the request body");
+    var bodyIsFn = typeof body === "function";
+    if (!bodyIsFn && guard.bytes.isByteSource(body)) body = guard.bytes.source(body, E, C("bad-input"), "the request body");
 
     var reqHeaders = Object.assign({}, request.headers || {});
     Object.keys(reqHeaders).forEach(function (k) { var lk = k.toLowerCase(); if (lk === "proxy-authorization" || lk === "proxy-connection") delete reqHeaders[k]; });
-    if (body != null && body !== "") {
+    if (bodyIsFn) {
+      Object.keys(reqHeaders).forEach(function (k) { var lk = k.toLowerCase(); if (lk === "content-length" || lk === "transfer-encoding" || lk === "expect") delete reqHeaders[k]; });
+    } else if (body != null && body !== "") {
       Object.keys(reqHeaders).forEach(function (k) { var lk = k.toLowerCase(); if (lk === "content-length" || lk === "transfer-encoding") delete reqHeaders[k]; });
       reqHeaders["Content-Length"] = Buffer.byteLength(body);
     }
@@ -484,9 +511,7 @@ function httpsTransport(defaults) {
       function issue(options) {
         try {
           req = nodeHttps.request(options, function (res) {
-            var proto = res.socket && res.socket.getProtocol ? res.socket.getProtocol() : null;
-            var cipher = res.socket && res.socket.getCipher ? res.socket.getCipher() : null;
-            var peer = res.socket && res.socket.getPeerCertificate ? res.socket.getPeerCertificate() : null;
+            var tlsInfo = _tlsInfo(res.socket);
             var declared = parseInt((res.headers || {})["content-length"], 10);
             if (Number.isFinite(declared) && declared > prep.maxBytes) { fail(C("response-too-large"), "the declared content-length " + declared + " exceeds the " + prep.maxBytes + "-byte cap (RFC 7030 sec. 6)"); return; }
             var buf = Buffer.allocUnsafe(0);
@@ -514,14 +539,36 @@ function httpsTransport(defaults) {
                 status: res.statusCode,
                 headers: lower,
                 body: Buffer.from(buf.subarray(0, len)),
-                tls: { protocol: proto, cipher: cipher, peerCertificate: peer && peer.raw ? peer.raw : null },
+                tls: tlsInfo,
               });
             });
             res.on("error", function (e) { fail(C("transport-error"), "the response stream failed", e); });
           });
           req.on("error", function (e) { fail(_classifyError(e, C), "the request failed: " + ((e && e.message) || String(e)), e); });
-          if (prep.body != null && prep.body !== "") req.write(prep.body);
-          req.end();
+          if (typeof prep.body === "function") {
+            req.once("socket", function (socket) {
+              function _writeBoundBody() {
+                if (settled) return;
+                var info = _tlsInfo(socket);
+                Promise.resolve().then(function () { return prep.body(info); }).then(function (b) {
+                  if (settled) return;
+                  try {
+                    if (guard.bytes.isByteSource(b)) b = guard.bytes.source(b, E, C("bad-input"), "the channel-binding body");
+                    else if (typeof b !== "string") { fail(C("bad-input"), "the request body callback must return bytes or a string; a missing return, null, or any other value is refused"); return; }
+                  } catch (ve) { _settleReject(ve); return; }
+                  try {
+                    if (b !== "") { req.setHeader("Content-Length", Buffer.byteLength(b)); req.write(b); }
+                    req.end();
+                  } catch (e2) { fail(C("transport-error"), "the request body could not be written: " + ((e2 && e2.message) || String(e2)), e2); }
+                }, function (e) { fail(C("transport-error"), "the channel-binding body callback failed", e); });
+              }
+              if (socket.getFinished && socket.getFinished()) { _writeBoundBody(); return; }
+              socket.once("secureConnect", _writeBoundBody);
+            });
+          } else {
+            if (prep.body != null && prep.body !== "") req.write(prep.body);
+            req.end();
+          }
         } catch (e) { fail(C("transport-error"), "the request could not be initiated: " + ((e && e.message) || String(e)), e); }
       }
 

package/lib/inspect.js

@@ -795,7 +795,7 @@ var _INSPECT_BY_FORMAT = { x509: certificate, crl: crlReport, csr: csrReport, cm
  * @related pki.schema.detectFormat, pki.inspect.certificate
  *
  * Detect which PKI format `input` (a PEM string or DER Buffer) encodes and render
- * it with the matching report -- the inspect analogue of `pki.schema.parse`. Routes
+ * it with the matching report, the inspect analogue of `pki.schema.parse`. Routes
  * a certificate / CRL / CSR / CMS to `certificate` / `crl` / `csr` / `cms`; a
  * detected but out-of-scope format (OCSP, TSP, PKCS#8/#12, CRMF, CMP, ...) throws
  * `inspect/unsupported-format` naming it, and an unrecognized input

package/lib/jose.js

@@ -294,7 +294,7 @@ function assertPublicJwk(jwk) {
  * or the message is refused with `jose/key-mismatch`. They are compared as RFC 7638
  * thumbprints, so member order and members outside the key itself cannot make equal
  * keys look different. Without `opts.key` the embedded `jwk` is used where the
- * profile permits one -- which verifies that the message is internally consistent,
+ * profile permits one, which verifies that the message is internally consistent,
  * not that any particular signer produced it. `keySource` reports which of the two
  * answered, so a signature checked against a caller-named key is distinguishable
  * from one checked against the key the message brought with it.

package/lib/key.js

@@ -12,7 +12,7 @@
  *   `publicFromPrivate` over every algorithm the WebCrypto engine drives: RSA, EC, Ed25519/Ed448,
  *   X25519/X448, and the FIPS post-quantum ML-DSA / ML-KEM. Unencrypted export / import DELEGATES to the
  *   WebCrypto `exportKey` / `importKey` PKCS#8 / SPKI encoders (which already emit each algorithm's
- *   `AlgorithmIdentifier.parameters` correctly -- RSA NULL, EC namedCurve, Ed/X ABSENT), so the wrapper
+ *   `AlgorithmIdentifier.parameters` correctly: RSA NULL, EC namedCurve, Ed/X ABSENT), so the wrapper
  *   never re-encodes an AlgorithmIdentifier. PBES2 encrypt / decrypt composes the one shared `lib/pbes2.js`
  *   home (the same PBKDF2 + AES-CBC primitives `pki.cms` uses). Parsing lives at `pki.schema.pkcs8.parse`.
  * @spec RFC 5958, RFC 8018, RFC 5280
@@ -73,8 +73,8 @@ async function _toPrivateKeyDer(input) {
  * (never encrypt opaque bytes), and the produced `EncryptedPrivateKeyInfo` is re-parsed before return.
  *
  * The PBKDF2 `prf` equal to the default (`hmacWithSHA1`) is omitted from the parameters (X.690 sec. 11.5),
- * `keyLength` is omitted (the AES cipher OID fixes the key size), and the salt / iteration count are bounded
- * -- so the output is byte-exact with OpenSSL's `pkcs8 -topk8 -v2`. A bad input throws a typed `KeyError`.
+ * `keyLength` is omitted (the AES cipher OID fixes the key size), and the salt / iteration count are bounded,
+ * so the output is byte-exact with OpenSSL's `pkcs8 -topk8 -v2`. A bad input throws a typed `KeyError`.
  *
  * @opts
  *   - `cipher` (string) -- `aes-256-cbc` (default), `aes-192-cbc`, or `aes-128-cbc`.
@@ -187,13 +187,13 @@ function _decryptPbes2(encAlg, ciphertext, password, opts) {
  *
  * Export an extractable `CryptoKey` to DER (or PEM): a private key as PKCS#8 `OneAsymmetricKey`, a public
  * key as SubjectPublicKeyInfo. The encoding is delegated to the WebCrypto `exportKey` PKCS#8 / SPKI encoder,
- * so the algorithm-specific `AlgorithmIdentifier.parameters` are byte-correct -- RSA carries an explicit
+ * so the algorithm-specific `AlgorithmIdentifier.parameters` are byte-correct: RSA carries an explicit
  * NULL, EC a namedCurve OID, and Ed25519 / Ed448 / X25519 / X448 omit parameters (RFC 8410 sec. 3); the
  * wrapper never re-encodes the AlgorithmIdentifier.
  *
  * The key need not have been created by this toolkit's own WebCrypto: one from the platform's, or from a
- * separately-installed copy of this toolkit, is exported through whichever of them holds its material,
- * since neither can read the other's. A key created non-extractable is refused with that as the reason,
+ * separately-installed copy of this toolkit, is exported through whichever of them holds its material.
+ * A key created non-extractable is refused with that as the reason,
  * as is one whose implementation keeps its material out of this process's reach entirely.
  *
  * @opts
@@ -231,7 +231,7 @@ async function export_(key, opts) {
  * @related pki.key.export, pki.key.decrypt
  *
  * Import a DER / PEM PKCS#8 private key, SPKI public key, or (with `opts.password`) an `ENCRYPTED PRIVATE
- * KEY` -- auto-detecting the structure -- into a `CryptoKey`. The WebCrypto algorithm is inferred from the
+ * KEY`, auto-detecting the structure, into a `CryptoKey`. The WebCrypto algorithm is inferred from the
  * key's OID for the algorithms that name exactly one (Ed25519 / Ed448 / X25519 / X448 / ML-DSA / ML-KEM /
  * SLH-DSA); RSA and EC are ambiguous between signing and key agreement, so `opts.algorithm` must be supplied
  * for them (without it the import fails closed). Default key usages follow the algorithm and key type.

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,

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