@blamejs/pki 0.6.28 → 0.6.30

package/lib/crl-sign.js

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

package/lib/crmf-sign.js

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

package/lib/csr-sign.js

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

package/lib/ct.js

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

package/lib/est.js

@@ -11,15 +11,15 @@
  *
  * @intro
  *   Enrollment over Secure Transport (RFC 7030, updated by RFC 8951 and RFC 9908).
- *   The network verbs -- `cacerts`, `simpleenroll`, `simplereenroll` -- run the thin
+ *   The network verbs (`cacerts`, `simpleenroll`, `simplereenroll`) run the thin
  *   RFC 7030 client: they compose the codecs below over the shared `pki.transport`
  *   (a caller MAY inject `opts.transport`; the default is a fail-closed
  *   `pki.transport.https`). This module opens no socket itself: the sole socket
  *   choke point is `pki.transport`, so the verbs stay a thin, fail-closed shell:
  *   https-only (`est/insecure-url`), an explicit trust anchor required
  *   (`est/no-trust-anchors`), same-origin redirects followed but a downgrade / loop
- *   refused, a 202 Retry-After SURFACED and never slept, HTTP Basic answered only
- *   after the transport authenticated the server, and the issued certificate chosen
+ *   refused, a 202 Retry-After SURFACED and never slept, HTTP Basic or Digest answered
+ *   only after the transport authenticated the server, and the issued certificate chosen
  *   by public-key match. Under them sit the transport-agnostic codecs, validators, and
  *   request builders over the shipped CMS / CSR / PKCS#8 / X.509 parsers:
  *   `transferDecode` / `transferEncode` are the RFC 8951
@@ -30,9 +30,9 @@
  *   `parseServerKeygenResponse` dispatches the two-part key + certificate
  *   response with recipient-arm coherence; `classifyResponse` is the HTTP status
  *   / content-type / Retry-After state machine (202 accepted-not-ready surfaces
- *   `retryAfterSeconds` -- never an internal sleep; 204/404 on /csrattrs is a
+ *   `retryAfterSeconds`, never an internal sleep; 204/404 on /csrattrs is a
  *   "none available" verdict, not an error). The builders assemble the CSR
- *   attributes EST adds -- a channel-binding challengePassword, the
+ *   attributes EST adds: a channel-binding challengePassword, the
  *   out-of-band-key identifiers, SMIMECapabilities, and the RFC 9908
  *   template-priority enroll plan.
  *
@@ -100,7 +100,7 @@ var OPERATIONS = ["cacerts", "simpleenroll", "simplereenroll", "fullcmc", "serve
 
 var CLIENT_OPTS = {
   transport: 1, tls: 1, label: 1, timeout: 1, maxResponseBytes: 1, maxRedirects: 1, now: 1,
-  auth: 1, username: 1, password: 1, allowCrossOriginRedirect: 1,
+  auth: 1, username: 1, password: 1, allowCrossOriginRedirect: 1, proxy: 1,
 };
 function _withClient(extra) {
   var out = {};
@@ -133,6 +133,9 @@ function _knownOpts(opts, known, verb) {
   });
 }
 
+function _snapProxy(opts) { return httpTransport.snapshotProxy(opts.proxy); }
+function _rej(e) { return Promise.reject(e); }
+
 
 /**
  * @primitive  pki.est.transferDecode
@@ -533,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);
@@ -846,7 +849,7 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
     return hh;
   }
   function step() {
-    return transport({ method: method, url: url.href, headers: _headersFor(url), body: body, tls: _tlsFor(url), timeout: budgets.timeout, maxResponseBytes: budgets.maxResponseBytes }).then(function (res) {
+    return transport({ method: method, url: url.href, headers: _headersFor(url), body: body, tls: _tlsFor(url), proxy: budgets.proxy, timeout: budgets.timeout, maxResponseBytes: budgets.maxResponseBytes }).then(function (res) {
       res = res || {};
       var blen = _bodyLen(res);
       if (blen > budgets.maxResponseBytes) throw E("est/response-too-large", "the response body (" + blen + " bytes) exceeds the " + budgets.maxResponseBytes + "-byte cap (RFC 7030 sec. 6)");
@@ -909,7 +912,7 @@ function _drive(method, url, body, headers, opts, transport, budgets) {
   return step();
 }
 
-function _client(op, method, baseUrl, body, headers, opts) {
+function _client(op, method, baseUrl, body, headers, opts, proxySnap) {
   var base;
   try { base = new URL(String(baseUrl)); }
   catch (e) { throw E("est/bad-url", "the EST base URL did not parse: " + guard.text.showValue(baseUrl), e); }
@@ -924,6 +927,7 @@ function _client(op, method, baseUrl, body, headers, opts) {
   }
   var budgets = {
     tls: _tlsForRequest(opts),
+    proxy: proxySnap,
     timeout: guard.limits.cap(opts.timeout, "timeout", DEFAULT_TIMEOUT, { E: E, code: "est/bad-input", min: 1, max: MAX_TIMEOUT }),
     maxResponseBytes: guard.limits.cap(opts.maxResponseBytes, "maxResponseBytes", constants.LIMITS.HTTP_MAX_RESPONSE_BYTES, { E: E, code: "est/bad-input", min: 1, max: constants.LIMITS.HTTP_MAX_RESPONSE_BYTES }),
     maxRedirects: guard.limits.cap(opts.maxRedirects, "maxRedirects", 5, { E: E, code: "est/bad-input", min: 0, max: 32 }),
@@ -1002,7 +1006,7 @@ function _certsResult(op, res, opts, csrSpki) {
  * surfaced as `issuedCertificates` (with `certificate` the first), distinct from `certificates`,
  * which is the whole returned bag including any chain. Where the requested keys are distinct that
  * list is in request order; where several requests deliberately SHARE one key it is not, and does
- * not claim to be -- the public key is the only identification sec. 4.1 sanctions, so when it is
+ * not claim to be: the public key is the only identification sec. 4.1 sanctions, so when it is
  * shared nothing in the response says which of those requests a given certificate answers. That arm reports `signatureVerified: false`: a certs-only body is
  * a degenerate SignedData with no signers by definition, so its security rests on the authenticated
  * TLS channel, not on a signature.
@@ -1012,7 +1016,7 @@ function _certsResult(op, res, opts, csrSpki) {
  * response is SURFACED, never acted on (RFC 5272 sec. 6.15 makes accepting one a manual decision).
  *
  * @opts
- *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now`, as in pki.est.cacerts.
+ *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `proxy` / `now`, as in pki.est.cacerts.
  *   - `transactionId` / `senderNonce` / `dataReturn`: what the request sent. The values are read out
  *     of the request itself; supplying them here cross-checks that, and a disagreement is refused.
  *   - `responderCerts`: extra certificates for CMC signer lookup, for a response that does not carry
@@ -1049,16 +1053,18 @@ function fullcmc(baseUrl, request, opts) {
   try {
     if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw E("est/bad-input", "pki.est.fullcmc options must be an object");
     _knownOpts(opts, FULLCMC_OPTS, "fullcmc");
+    var proxySnap;
+    try { proxySnap = _snapProxy(opts); } catch (_pe) { throw E("est/bad-input", "the options object could not be read", _pe); }
     der = _cmcRequestDer(request);
     wanted = _requestedPublicKeys(der);
     sent = _cmcSent(opts, der);
     opts = _shallowCopy(opts);
     var body = transferEncode(der);
     return _client("fullcmc", "POST", baseUrl, body,
-      { accept: "application/pkcs7-mime", "content-type": "application/pkcs7-mime; smime-type=CMC-request" }, opts)
+      { accept: "application/pkcs7-mime", "content-type": "application/pkcs7-mime; smime-type=CMC-request" }, opts, proxySnap)
       .then(function (res) { return _fullcmcResult(res, opts, wanted, sent); });
   } catch (e) {
-    return Promise.reject(e);
+    return _rej(e);
   }
 }
 
@@ -1357,11 +1363,11 @@ function _tryDecodeCmcFault(res, sent) {
   }).then(null, function () { return null; });
 }
 
-function _enroll(op, baseUrl, csrInput, opts) {
+function _enroll(op, baseUrl, csrInput, opts, proxySnap) {
   var csrDer = _csrDer(csrInput);
   var spki = csr.parse(csrDer).subjectPublicKeyInfo;
   var body = transferEncode(csrDer);
-  return _client(op, "POST", baseUrl, body, { accept: "application/pkcs7-mime", "content-type": "application/pkcs10" }, opts)
+  return _client(op, "POST", baseUrl, body, { accept: "application/pkcs7-mime", "content-type": "application/pkcs10" }, opts, proxySnap)
     .then(function (res) { return _certsResult(op, res, opts, spki); });
 }
 
@@ -1386,6 +1392,7 @@ function _enroll(op, baseUrl, csrInput, opts) {
  *   - `transport`: an injected transport(request) -> {status, headers, body, tls}; default pki.transport.https.
  *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity }.
  *   - `label` -- an OPTIONAL CA label path segment; `timeout` / `maxResponseBytes` / `maxRedirects` -- budgets.
+ *   - `proxy` -- reach the CA through a forward HTTP proxy (`{ url, auth?, tls? }`; see pki.transport).
  *   - `now` -- receipt time (epoch ms) to render a 202 Retry-After HTTP-date as seconds.
  *   - `auth` -- HTTP authentication: `{ scheme: "basic" | "digest", username, password, allowMD5, allowLegacyQop, maxStaleRetries }`.
  *     There is no `"auto"`: the scheme is chosen here, not by whatever a server offers. `username` / `password`
@@ -1399,9 +1406,10 @@ function _enroll(op, baseUrl, csrInput, opts) {
  */
 function cacerts(baseUrl, opts) {
   opts = opts || {};
+  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
   return Promise.resolve().then(function () {
     _knownOpts(opts, CACERTS_OPTS, "cacerts");
-    return _client("cacerts", "GET", baseUrl, null, { accept: "application/pkcs7-mime" }, opts);
+    return _client("cacerts", "GET", baseUrl, null, { accept: "application/pkcs7-mime" }, opts, proxySnap);
   }).then(function (res) { return _certsResult("cacerts", res, opts, null); });
 }
 
@@ -1424,9 +1432,9 @@ function cacerts(baseUrl, opts) {
  * the transport already authenticated the server.
  *
  * @opts
- *   - `transport` / `tls` / `label` / `timeout` / `maxResponseBytes` / `maxRedirects` / `now`, as in pki.est.cacerts.
+ *   - `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 });
@@ -1437,9 +1445,10 @@ function cacerts(baseUrl, opts) {
  */
 function simpleenroll(baseUrl, csrInput, opts) {
   opts = opts || {};
+  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
   return Promise.resolve().then(function () {
     _knownOpts(opts, SIMPLEENROLL_OPTS, "simpleenroll");
-    return _enroll("simpleenroll", baseUrl, csrInput, opts);
+    return _enroll("simpleenroll", baseUrl, csrInput, opts, proxySnap);
   });
 }
 
@@ -1470,11 +1479,12 @@ function simpleenroll(baseUrl, csrInput, opts) {
  */
 function simplereenroll(baseUrl, csrInput, opts) {
   opts = opts || {};
+  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
   return Promise.resolve().then(function () {
     _knownOpts(opts, SIMPLEREENROLL_OPTS, "simplereenroll");
     if (!opts.oldCert) throw E("est/bad-input", "simplereenroll requires opts.oldCert (the certificate being renewed, RFC 7030 sec. 4.2.2)");
     reenrollGuard(opts.oldCert, _csrDer(csrInput));
-    return _enroll("simplereenroll", baseUrl, csrInput, opts);
+    return _enroll("simplereenroll", baseUrl, csrInput, opts, proxySnap);
   });
 }
 
@@ -1613,6 +1623,7 @@ async function _serverkeygenResult(res, opts, derived) {
  */
 function serverkeygen(baseUrl, csrInput, opts) {
   opts = opts || {};
+  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
   return Promise.resolve().then(function () {
     _knownOpts(opts, SERVERKEYGEN_OPTS, "serverkeygen");
     var csrDer = _csrDer(csrInput);
@@ -1631,7 +1642,7 @@ function serverkeygen(baseUrl, csrInput, opts) {
     if ((opts.expectedRecipientKeyId !== undefined || opts.expectedRecipientIssuerSerial != null) && !derived.requestedEncryption) {
       throw E("est/bad-input", "a recipient expectation (expectedRecipientKeyId / expectedRecipientIssuerSerial) implies an encrypted key, but the CSR advertised no DecryptKeyIdentifier / AsymmetricDecryptKeyIdentifier attribute (RFC 7030 sec. 4.4.1)");
     }
-    return _client("serverkeygen", "POST", baseUrl, transferEncode(csrDer), { accept: "multipart/mixed", "content-type": "application/pkcs10" }, opts)
+    return _client("serverkeygen", "POST", baseUrl, transferEncode(csrDer), { accept: "multipart/mixed", "content-type": "application/pkcs10" }, opts, proxySnap)
       .then(function (res) { return _serverkeygenResult(res, opts, derived); });
   });
 }
@@ -1673,9 +1684,10 @@ function _csrattrsResult(res, opts) {
  */
 function csrattrs(baseUrl, opts) {
   opts = opts || {};
+  var proxySnap; try { proxySnap = _snapProxy(opts); } catch (_pe) { return _rej(E("est/bad-input", "the options object could not be read", _pe)); }
   return Promise.resolve().then(function () {
     _knownOpts(opts, CSRATTRS_OPTS, "csrattrs");
-    return _client("csrattrs", "GET", baseUrl, null, { accept: "application/csrattrs" }, opts);
+    return _client("csrattrs", "GET", baseUrl, null, { accept: "application/csrattrs" }, opts, proxySnap);
   }).then(function (res) { return _csrattrsResult(res, opts); });
 }
 

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/guard-identifier.js

@@ -309,11 +309,27 @@ function _isBuiltinExotic(v) {
     t.isBoxedPrimitive(v) || t.isNativeError(v) || t.isArgumentsObject(v) || t.isGeneratorObject(v);
 }
 
+function _proxyInChain(v) {
+  if (v === null || typeof v !== "object") return false;
+  var visited = new _Set();
+  for (var o = v; o && !_setHas(visited, o); o = _getPrototypeOf(o)) {
+    _setAdd(visited, o);
+    if (util.types.isProxy(o)) return true;
+  }
+  return false;
+}
+function isPlainRecord(v) {
+  if (v === null || typeof v !== "object") return false;
+  if (_proxyInChain(v)) return false;
+  if (_isNodeBuffer(v) || _isArray(v)) return false;
+  return !_isBuiltinExotic(v);
+}
 // @enforced-by behavioral -- a plain-record refusal has no single rename-proof code shape worth a
 function assertPlainRecord(v, E, code, label) {
   _requireFactory(E);
-  if (v === null || typeof v !== "object" || _isNodeBuffer(v) || _isArray(v)) throw E(code, label + " must be a plain object");
+  if (v === null || typeof v !== "object") throw E(code, label + " must be a plain object");
   _refuseUnenumerable(v, E, code, label);
+  if (_isNodeBuffer(v) || _isArray(v)) throw E(code, label + " must be a plain object");
   if (_isBuiltinExotic(v)) throw E(code, label + " must be a plain object (a built-in exotic such as a Date or Map is refused)");
 }
 
@@ -378,6 +394,7 @@ module.exports = intrinsic.freeze({
   assertCanonicalOid: assertCanonicalOid,
   assertKnownKeys: assertKnownKeys,
   assertPlainRecord: assertPlainRecord,
+  isPlainRecord: isPlainRecord,
   optionsObject: optionsObject,
   refuseAccessorFields: refuseAccessorFields,
   readableNames: readableNames,

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,10 +16,10 @@
  *   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
+ *   channel, `{ protocol, cipher, peerCertificate }`, which is the one fact a caller
  *   cannot recover from the response bytes. An INJECTED substitute should return it 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
@@ -40,7 +40,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");
@@ -48,6 +48,7 @@ var nodeHttp = require("node:http");
 var nodeNet = require("node:net");
 var nodeTls = require("node:tls");
 var nodeDns = require("node:dns");
+var nodeUtil = require("node:util");
 var constants = require("./constants");
 var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
@@ -197,13 +198,70 @@ var PROXY_KEYS = _keySet(["url", "auth", "tls"]);
 var PROXY_AUTH_KEYS = _keySet(["scheme", "username", "password"]);
 var PROXY_TLS_KEYS = _keySet(["anchors", "useSystemStore", "servername", "minVersion"]);
 
+function _copyAnchor(a) { return (a !== null && typeof a === "object" && nodeUtil.types.isProxy(a)) ? a : (Buffer.isBuffer(a) ? Buffer.from(a) : a); }
+function _noopProxyErr(code, message) { var e = new Error(message); e.code = code; e.isPkiError = true; return e; }
+function _copyableRecord(p) {
+  if (!guard.identifier.isPlainRecord(p)) return false;
+  var proto = Object.getPrototypeOf(p);
+  if (proto !== Object.prototype && proto !== null) return false;
+  if (Object.getOwnPropertySymbols(p).length !== 0) return false;
+  var ownEnumData = 0;
+  var names = Object.getOwnPropertyNames(p);
+  for (var i = 0; i < names.length; i++) {
+    var d = Object.getOwnPropertyDescriptor(p, names[i]);
+    if (!d.enumerable || d.get || d.set) return false;
+    ownEnumData++;
+  }
+  var readable = guard.identifier.readableNames(p, _noopProxyErr, "transport/bad-proxy", "opts.proxy");
+  if (readable.length !== ownEnumData) return false;
+  for (var j = 0; j < readable.length; j++) {
+    var rd = Object.getOwnPropertyDescriptor(p, readable[j]);
+    if (!rd || !rd.enumerable || rd.get || rd.set) return false;
+  }
+  return true;
+}
+function _copyableArray(a) {
+  if (a === null || typeof a !== "object" || nodeUtil.types.isProxy(a) || !Array.isArray(a) || Object.getPrototypeOf(a) !== Array.prototype) return false;
+  if (a.length > constants.LIMITS.PROXY_MAX_TLS_ANCHORS) return false;
+  if (Object.getOwnPropertySymbols(a).length !== 0) return false;
+  var names = Object.getOwnPropertyNames(a);
+  for (var i = 0; i < names.length; i++) {
+    var d = Object.getOwnPropertyDescriptor(a, names[i]);
+    if (d.get || d.set) return false;
+  }
+  return true;
+}
+function snapshotProxy(p) {
+  try {
+    if (!_copyableRecord(p)) return p;
+    var out = Object.assign(Object.create(null), p);
+    if (_copyableRecord(p.auth)) out.auth = Object.assign(Object.create(null), p.auth);
+    if (_copyableRecord(p.tls)) {
+      out.tls = Object.assign(Object.create(null), p.tls);
+      var a = p.tls.anchors;
+      if (_copyableArray(a)) {
+        var copied = [];
+        for (var i = 0; i < a.length; i++) copied[i] = _copyAnchor(a[i]);
+        out.tls.anchors = copied;
+      } else if (typeof a === "string") out.tls.anchors = a;
+      else if (a !== null && typeof a === "object" && !nodeUtil.types.isProxy(a) && Buffer.isBuffer(a)) out.tls.anchors = Buffer.from(a);
+    }
+    return out;
+  } catch (_e) {
+    // allow:swallow-unverified an input whose introspection throws (a revoked Proxy, a throwing trap) returns unchanged for _validateProxy to refuse
+    return p;
+  }
+}
+
 function _validateProxy(request, defaults, E, C, url) {
   var proxy = request.proxy !== undefined ? request.proxy : defaults.proxy;
   if (proxy === undefined || proxy === null) return null;
   guard.identifier.assertPlainRecord(proxy, E, C("bad-proxy"), "opts.proxy");
+  if (!_copyableRecord(proxy)) throw E(C("bad-proxy"), "opts.proxy must be a plain object with only own enumerable data properties");
   guard.identifier.assertKnownKeys(proxy, PROXY_KEYS, E, C("bad-proxy"), "opts.proxy has an unknown option ");
+  if (typeof proxy.url !== "string") throw E(C("bad-proxy"), "opts.proxy.url must be a string, got " + guard.text.showValue(proxy.url));
   var purl;
-  try { purl = new URL(String(proxy.url)); }
+  try { purl = new URL(proxy.url); }
   catch (e) { throw E(C("bad-proxy"), "opts.proxy.url did not parse: " + guard.text.showValue(proxy.url), e); }
   if (purl.protocol !== "http:" && purl.protocol !== "https:") throw E(C("bad-proxy"), "opts.proxy.url must be an http or https URL, got " + purl.protocol);
   if (purl.username || purl.password) throw E(C("bad-proxy"), "opts.proxy.url must not carry credentials in its userinfo; supply opts.proxy.auth over an https proxy");
@@ -214,6 +272,7 @@ function _validateProxy(request, defaults, E, C, url) {
   if (proxy.auth !== undefined && proxy.auth !== null) {
     if (!secure) throw E(C("proxy-auth-requires-tls"), "proxy credentials cannot be sent over a plaintext http proxy, where the proxy hop would expose them; use an https proxy URL");
     guard.identifier.assertPlainRecord(proxy.auth, E, C("bad-proxy"), "opts.proxy.auth");
+    if (!_copyableRecord(proxy.auth)) throw E(C("bad-proxy"), "opts.proxy.auth must be a plain object with only own enumerable data properties");
     guard.identifier.assertKnownKeys(proxy.auth, PROXY_AUTH_KEYS, E, C("bad-proxy"), "opts.proxy.auth has an unknown option ");
     var scheme = proxy.auth.scheme;
     if (scheme === "digest") throw E(C("proxy-unsupported-scheme"), "Digest proxy authentication is not supported in this release; use 'basic' over an https proxy");
@@ -228,22 +287,25 @@ function _validateProxy(request, defaults, E, C, url) {
     var ptls = proxy.tls;
     if (ptls !== undefined && ptls !== null) {
       guard.identifier.assertPlainRecord(ptls, E, C("bad-proxy"), "opts.proxy.tls");
+      if (!_copyableRecord(ptls)) throw E(C("bad-proxy"), "opts.proxy.tls must be a plain object with only own enumerable data properties");
       guard.identifier.assertKnownKeys(ptls, PROXY_TLS_KEYS, E, C("bad-proxy"), "opts.proxy.tls has an unknown option ");
       if (ptls.servername !== undefined && ptls.servername !== null && typeof ptls.servername !== "string") throw E(C("bad-proxy"), "opts.proxy.tls.servername must be a string");
     }
     var pAnchors = ptls ? ptls.anchors : undefined;
+    if (pAnchors !== undefined && pAnchors !== null && typeof pAnchors === "object" && nodeUtil.types.isProxy(pAnchors)) throw E(C("bad-proxy"), "opts.proxy.tls.anchors must not be a Proxy");
     var pUseSystem = ptls ? ptls.useSystemStore === true : false;
     var pHasAnchors = pAnchors !== undefined && pAnchors !== null && !(Array.isArray(pAnchors) && pAnchors.length === 0);
     if (!pHasAnchors && !pUseSystem) throw E(C("bad-proxy"), "an https proxy requires explicit tls trust: set proxy.tls.anchors or proxy.tls.useSystemStore");
     if (pHasAnchors) {
+      if (Array.isArray(pAnchors) && !_copyableArray(pAnchors)) throw E(C("bad-proxy"), "opts.proxy.tls.anchors must be a plain array of PEM strings or DER Buffers");
       var pAnchorList = Array.isArray(pAnchors) ? pAnchors : [pAnchors];
       for (var pai = 0; pai < pAnchorList.length; pai++) {
         var pan = pAnchorList[pai];
-        if (typeof pan !== "string" && !Buffer.isBuffer(pan)) throw E(C("bad-proxy"), "opts.proxy.tls.anchors must be a PEM string or a DER Buffer (or an array of them)");
+        if ((pan !== null && typeof pan === "object" && nodeUtil.types.isProxy(pan)) || (typeof pan !== "string" && !Buffer.isBuffer(pan))) throw E(C("bad-proxy"), "opts.proxy.tls.anchors must be a PEM string or a DER Buffer (or an array of them)");
       }
     }
-    var pMinVersion = (ptls && ptls.minVersion) || DEFAULT_MIN_VERSION;
-    if (pMinVersion !== "TLSv1.2" && pMinVersion !== "TLSv1.3") throw E(C("bad-proxy"), "proxy.tls.minVersion must be 'TLSv1.2' or 'TLSv1.3', got " + pMinVersion);
+    var pMinVersion = (ptls && ptls.minVersion !== undefined && ptls.minVersion !== null) ? ptls.minVersion : DEFAULT_MIN_VERSION;
+    if (pMinVersion !== "TLSv1.2" && pMinVersion !== "TLSv1.3") throw E(C("bad-proxy"), "proxy.tls.minVersion must be 'TLSv1.2' or 'TLSv1.3', got " + guard.text.showValue(pMinVersion));
     var pCa = [];
     if (pHasAnchors) pCa = pCa.concat(_pemifyAnchors(pAnchors));
     if (pUseSystem) pCa = pCa.concat(_systemCa());
@@ -289,7 +351,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`).
@@ -370,7 +432,17 @@ function httpsTransport(defaults) {
         return callerCsi(host, cert2);
       };
     }
-    var proxyInfo = _validateProxy(request, defaults, E, C, url);
+    var proxyInfo;
+    try { proxyInfo = _validateProxy(request, defaults, E, C, url); }
+    catch (e) {
+      var typedProxyError = false;
+      try {
+        var ec = (e instanceof Error) && !nodeUtil.types.isProxy(e) ? e.code : undefined;
+        typedProxyError = ec === C("bad-proxy") || ec === C("proxy-auth-requires-tls") || ec === C("proxy-unsupported-scheme");
+      } catch (_ie) { /* allow:swallow-unverified reading .code on a hostile error object can throw; treat any such failure as untyped */ }
+      if (typedProxyError) throw e;
+      throw E(C("bad-proxy"), "opts.proxy could not be validated", e);
+    }
     var blockPrivate = (request.blockPrivateAddresses !== undefined ? request.blockPrivateAddresses : defaults.blockPrivateAddresses) === true;
     if (blockPrivate && proxyInfo) throw E(C("bad-proxy"), "blockPrivateAddresses cannot be enforced through a forward proxy, which resolves the origin itself and would reach a private origin the transport never checks; use a direct connection for a private-address-blocked fetch");
     if (blockPrivate) {
@@ -526,4 +598,4 @@ function httpsTransport(defaults) {
   return _transportFn;
 }
 
-module.exports = { https: httpsTransport, isBlockedIp: _isBlockedIp, _makeGuardedLookup: _makeGuardedLookup, MAX_TIMEOUT: MAX_TIMEOUT };
+module.exports = { https: httpsTransport, isBlockedIp: _isBlockedIp, _makeGuardedLookup: _makeGuardedLookup, MAX_TIMEOUT: MAX_TIMEOUT, snapshotProxy: snapshotProxy };

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.