@blamejs/pki 0.6.10 → 0.6.11

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.6.11 — 2026-08-31
+
+pki.path.validate and pki.tsp.verify now take the trust store under the option name trustAnchors, the spelling the other verify verbs already use, accepting one anchor or an array; and pki.acme.client gains opts.resignKeys, which re-signs a request under an alternative account-key algorithm when a CA reports badSignatureAlgorithm.
+
+### Added
+
+- pki.acme.client accepts opts.resignKeys, an ordered array of { alg, key } alternatives for the account key (RFC 8555 section 6.2). When a CA rejects the account's JWS algorithm with a badSignatureAlgorithm error and lists the algorithms it supports, the client re-signs the request once with the first listed alternative the CA supports and retries. Each key is a CryptoKey for the same account key material under that algorithm, so the account's registered public key still verifies the re-signed request. The caller's order selects the algorithm and the CA's list only filters it, so a spoofed badSignatureAlgorithm cannot force a weaker algorithm (RFC 8555 section 10). Without the option, or when no listed algorithm is a caller alternative, the error surfaces unchanged.
+
+### Changed
+
+- pki.path.validate and pki.tsp.verify read the trust anchor from opts.trustAnchors, the same option the other verify verbs take. It accepts a single anchor tuple or root certificate, or a non-empty array of them; when several are supplied, pki.path.validate selects the anchor that issued the path's top certificate, and a one-element array reproduces the previous single-anchor result exactly. The former singular opts.trustAnchor is removed and is refused as an unknown option rather than silently ignored, so a stale caller gets a named error instead of an unanchored valid result. To upgrade, pass { trustAnchors: anchor } (or { trustAnchors: [a, b] }) where you passed { trustAnchor: anchor }.
+
 ## v0.6.10 — 2026-08-31
 
 pki.est computes a response body's length from a single read of res.body, shared by one helper across every verb, so a caller-supplied transport whose res.body getter changes between reads cannot desync the type check from the measured length.

package/MIGRATING.md

@@ -14,6 +14,26 @@ The toolkit has no `deprecate()`-marked surface awaiting removal.
 
 Listed newest-first.
 
+### v0.6.11 — `pki.path.validate(path, opts) and pki.tsp.verify(token, data, opts)`
+
+The trust anchor option is now `trustAnchors` (a single anchor or an array); the former singular `trustAnchor` is removed and refused by name.
+
+Both verbs read the trust anchor from `opts.trustAnchors`, the spelling pki.path.build,
+pki.cms.verify, pki.cmp.verify, and pki.smime.verify already use. It accepts a single anchor
+tuple or root certificate, or a non-empty array of them.
+
+```js
+var res = await pki.path.validate(path, { time: t, trustAnchor: anchor });   // removed
+
+var res = await pki.path.validate(path, { time: t, trustAnchors: anchor });          // one anchor
+var res = await pki.path.validate(path, { time: t, trustAnchors: [rootA, rootB] });  // several
+```
+
+With several anchors, pki.path.validate selects the one that issued the path's top certificate,
+and a one-element array reproduces the previous single-anchor result. The removed `trustAnchor`
+is refused as an unknown option (`path/bad-input` or `tsp/bad-input`) naming it, rather than read
+as absent, so a request that was silently unanchored now fails closed with a named error.
+
 ### v0.5.24 — `pki.acme.client(...).downloadCertificate(url, opts)`
 
 The verb needs to be told which certificate the download is allowed to be, and refuses with acme/binding-required when it is not.

package/README.md

@@ -225,7 +225,7 @@ comment blocks, is at [pkijs.com](https://pkijs.com).
 | `pki.scep` | SCEP pkiMessage codec (RFC 8894), the client side of Simple Certificate Enrollment. `build(spec)` assembles a `PKCSReq` or `RenewalReq` request: it verifies the PKCS#10 certification request's own proof-of-possession, encrypts it to the CA as the inner EnvelopedData (`pkcsPKIEnvelope`, AES-128-CBC), and signs that under the transaction attributes RFC 8894 §3.2 defines, a messageType, a caller-unique transactionId, and a 16-byte senderNonce. The recipient CA certificate must assert `keyEncipherment`. `parse(bytes, opts?)` reads a `PKCSReq`, `RenewalReq`, or `CertRep` back (the `CertPoll`, `GetCert`, and `GetCRL` client queries are refused): it verifies the outer signature first and refuses a message whose signature does not check, so the transaction attributes it returns come only from a verified signer, never alongside a false verdict. Because a valid signature only proves self-consistency with the embedded certificate, pass `opts.signerCert` to authenticate a CA response against the CA certificate you hold (a public-key mismatch is refused, `signerAuthenticated` reports the result); a caller that omits it gets a crypto-only verdict and must authenticate the surfaced `signerCert` itself. It maps the messageType, pkiStatus, failInfo, and the nonces from their RFC 8894 enumerants and refuses an unknown one; given `recipientKey` it decrypts the `pkcsPKIEnvelope` to the messageData, and given `expectedSenderNonce` it refuses a response whose recipientNonce does not echo it. It reads a CA's CertRep in full. `getCACaps(baseUrl, opts?)`, `getCACert(baseUrl, opts?)`, `enroll(baseUrl, opts)`, and `renew(baseUrl, opts)` carry that codec to a live CA over HTTP (RFC 8894 §4) through an injectable transport (`pki.transport.https` by default): `getCACaps` reports the CA's advertised capabilities and never lowers the client's algorithm choice on the unauthenticated response, `getCACert` pins the CA certificate to an out-of-band `expectedFingerprint` a returned certificate must match, and `enroll` and `renew` POST a PKCSReq or RenewalReq, authenticate the CertRep against the CA certificate and its nonce echo, select the issued certificate by public-key match, throw on a FAILURE with the CA's failInfo, and return a PENDING to retry. Issuing a CertRep, `GetNextCACert`, and automatic polling are not yet built — `build`, `parse`, `getCACaps`, `getCACert`, `enroll`, `renew` |
 | `pki.transport` | The shared, fail-closed `node:https` transport the enrollment clients drive. `pki.transport.https(defaults)` returns a `transport(request) → { status, headers, body, tls }`, where `tls` carries the negotiated `protocol`, `cipher`, and raw `peerCertificate`. This is the toolkit's only socket choke point: an explicit trust anchor (or an opt-in to the system store) is required, `rejectUnauthorized` is always on, TLS is floored at 1.2, the response body is capped while it streams, and a stalled socket times out. The EST, ACME, and CMP clients reuse it verbatim. If you inject your own transport, return `tls` too: `pki.est.serverkeygen` asserts the negotiated cipher can protect the delivered private key, and a transport that reports no cipher is trusted rather than refused, so omitting the field silently skips that check — `https` |
 | `pki.jose` | Flattened JWS (RFC 7515) and JWK thumbprints (RFC 7638). `sign` and `verify` run a Flattened JWS against declarative profiles (ACME outer, EAB inner, keyChange inner) that carry the required and forbidden header rules as data. `base64url` is the strict RFC 4648 §5 codec, rejecting padding, non-alphabet characters, and non-canonical trailing bits. `parseJson` is a bounded reader that refuses duplicate members at any depth. `thumbprint` is the RFC 7638 / 8037 / 9964 canonical digest. The algorithm registry binds each `alg` to its key type (ES/RS/PS/EdDSA/ML-DSA), leaving no code path for `alg:none`, an RS256→HS256 key confusion, or an all-zero ECDSA signature; `assertPublicJwk` refuses a JWK carrying private material, so an exported private key is never published. `opts.key` names the key a message must be signed under and governs: where the profile also permits an embedded header `jwk`, the two must be the same key — compared as RFC 7638 thumbprints, so member order cannot make equal keys differ — and a disagreement is refused rather than resolved in the message's favor. `keySource` reports which key answered, since a signature checked against a key you named is a different claim from one checked against the key the message carried — `sign`, `verify`, `base64url`, `parseJson`, `thumbprint`, `assertPublicJwk` |
-| `pki.acme` | ACME (RFC 8555 / 8737 / 8738 / 9773). `client(directoryUrl, opts)` is a stateful client driving a live CA directory over `pki.transport`: `newAccount`, `newOrder`, `newAuthz`, `getOrder`, `getAuthorization`, `getChallenge`, `respondToChallenge`, `finalize`, `pollOrder`, `pollAuthorization`, and `downloadCertificate` walk the issuance flow, with `newAuthz` pre-authorizing a single identifier (§7.4.1) and `downloadCertificate` binding the issued certificate to the order — its key, its identifiers, or both; at least one is required by default and the result reports `boundToKey` / `boundToIdentifiers` — before choosing among alternate chains (`Link rel="alternate"`, §7.4.2, via a `selectChain` predicate bounded by `maxAlternates`). `revokeCert` (account-key or certificate-key signed), `keyChange`, `updateAccount` (change the account contacts, §7.3.2), `listOrders` (the account's orders list, following the §7.1.2.1 `Link rel="next"` pagination bounded by a page cap and confined to the orders origin), `deactivateAccount`, `deactivateAuthorization`, `renewalInfo` (ARI), and `renewalWindow` (the RFC 9773 §4.2/4.3 renewal decision) complete the lifecycle. Every URL is HTTPS only, an explicit trust anchor is required, each request carries a fresh single-use nonce with a bounded badNonce retry, reads are POST-as-GET, polling is bounded and sleeps on a Retry-After via an injectable sleeper capped by a poll count and a total-wait budget, and every response body is size-capped. The transport is injectable via `opts.transport`. Over the message layer it composes resource-object validators (closed status enums, conditional-required fields, unknown fields ignored), the three §7.1.6 state machines, the request builders (newAccount with External Account Binding, newOrder with `replaces`, finalize with a CSR identifier-set match and account-key-reuse rejection, challenge responses, deactivation, revokeCert in both key modes, the keyChange nested JWS, POST-as-GET), the http-01 / dns-01 / tls-alpn-01 challenge computations, the dns and ip identifier validators, and the ARI certID with serial sign-padding preserved — `client`, `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
+| `pki.acme` | ACME (RFC 8555 / 8737 / 8738 / 9773). `client(directoryUrl, opts)` is a stateful client driving a live CA directory over `pki.transport`: `newAccount`, `newOrder`, `newAuthz`, `getOrder`, `getAuthorization`, `getChallenge`, `respondToChallenge`, `finalize`, `pollOrder`, `pollAuthorization`, and `downloadCertificate` walk the issuance flow, with `newAuthz` pre-authorizing a single identifier (§7.4.1) and `downloadCertificate` binding the issued certificate to the order — its key, its identifiers, or both; at least one is required by default and the result reports `boundToKey` / `boundToIdentifiers` — before choosing among alternate chains (`Link rel="alternate"`, §7.4.2, via a `selectChain` predicate bounded by `maxAlternates`). `revokeCert` (account-key or certificate-key signed), `keyChange`, `updateAccount` (change the account contacts, §7.3.2), `listOrders` (the account's orders list, following the §7.1.2.1 `Link rel="next"` pagination bounded by a page cap and confined to the orders origin), `deactivateAccount`, `deactivateAuthorization`, `renewalInfo` (ARI), and `renewalWindow` (the RFC 9773 §4.2/4.3 renewal decision) complete the lifecycle. Every URL is HTTPS only, an explicit trust anchor is required, each request carries a fresh single-use nonce with a bounded badNonce retry (and, when `opts.resignKeys` supplies caller-approved alternative account-key algorithms, a bounded RFC 8555 §6.2 badSignatureAlgorithm re-sign that the CA's advertised list can only filter, never widen, so it cannot force a weaker algorithm), reads are POST-as-GET, polling is bounded and sleeps on a Retry-After via an injectable sleeper capped by a poll count and a total-wait budget, and every response body is size-capped. The transport is injectable via `opts.transport`. Over the message layer it composes resource-object validators (closed status enums, conditional-required fields, unknown fields ignored), the three §7.1.6 state machines, the request builders (newAccount with External Account Binding, newOrder with `replaces`, finalize with a CSR identifier-set match and account-key-reuse rejection, challenge responses, deactivation, revokeCert in both key modes, the keyChange nested JWS, POST-as-GET), the http-01 / dns-01 / tls-alpn-01 challenge computations, the dns and ip identifier validators, and the ARI certID with serial sign-padding preserved — `client`, `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
 | `pki.schema.smime` | S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551). `parseSigningCertificate` and `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` and serial); `parseSmimeCapabilities` decodes the ordered capability list; `decodeAttribute` dispatches a CMS attribute by OID, enforcing the single-value rule and deferring on unknown types. A companion decoder for CMS signed attributes rather than an auto-routed format — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `pki.cmc` | Build and interpret CMC messages (RFC 5272). `build(spec, signer)` assembles a Full PKI Request across all three request arms (PKCS#10, CRMF, other) and signs it through `pki.cms.sign` under `id-cct-PKIData`. A PKCS#10 (`tcr`) request is verified against its own proof-of-possession before signing, so a request whose self-signature does not verify under its subject public key is refused rather than signed into a message a CA would reject. Body-part identifiers are unique across the whole message and never the reserved 0; a caller's clash is refused rather than renumbered, since a control may already reference it. An Identity Proof V2 witness is computed over the `reqSequence` bytes exactly as emitted (§6.2.1 step 1) rather than a re-serialization, a POP Link Witness is emitted only alongside the POP Link Random control §6.3.1.1 requires beside it, and a renewal carries neither Identification nor Identity Proof in either version. `verify(response, sent)` takes what the CA returned plus the state the client retained and reduces it to one terminal outcome: `issued`, `pending`, `confirm-required`, `pop-required`, or `rejected`. It binds the exchange first — Transaction Identifier, the Sender and Recipient Nonce echo compared in constant time and by full value so a truncation cannot match, and the Data Return echo — with each check applying only if the client sent that half, and, once sent, an absent or differing echo being a refusal, which is the replay defense. `bodyPartIDs` extends the same rule to what the response is about: a status reporting on a body part the request never sent is refused, which the transaction and nonce cannot catch, because a server can echo both correctly while answering about a different message. Several status controls are permitted and the worst governs, so a failure cannot hide behind an earlier success; the absence of any status control is success, per §6.1.2. The carrier's signature must verify (§3.2.1.3.4): a conforming SignedData carries its own signer certificate, so the ordinary build-then-verify flow needs nothing extra and the verdict reports `signatureVerified: true`. Where the signer is found nowhere the posture is fail-closed with a named opt-out — supply `certs` with the responder's certificate, or `allowUnverified: true`, in which case the verdict reports `signatureVerified: false`. Doing neither is refused, the opt-out never excuses a signature that is present and wrong, and a carrier with no signer at all is refused outright. The response's own `cmsSequence` and `otherMsgs` come back raw, since a request whose only arm was the other-message form has no certificate to return and §4.1 puts its answer there. Nothing is trusted: issued certificates are read from the CMS certificate bag (§4.2) and surfaced raw for `pki.path.validate`, and a Publish Trust Anchors control is surfaced with `trusted: false` rather than added to a store — `build`, `verify` |
 | `pki.schema.cmc` | Decode CMC messages (RFC 5272 as updated by RFC 6402): a Full PKI Request (`PKIData`) or Full PKI Response (`PKIResponse`) riding inside a CMS SignedData, reached by the encapsulated content type (`id-cct-PKIData` / `id-cct-PKIResponse`). Controls are surfaced in wire order with their values raw, so an unrecognized one is data rather than a fault. Tagged requests decode across all three arms. The status verdicts (`CMCStatusInfo` v1 and `CMCStatusInfoV2`) are collected as an ordered list, and the RFC 6402 two-module `OtherStatusInfo` ambiguity — `pendInfo` and `extendedFailInfo` are both untagged SEQUENCEs in the 1988 module, told apart only by their first element — is resolved by inspection and refused when it cannot be told apart. Body-part identity is unique across the whole message rather than per sequence, 0 is reserved as the reference to the enclosing PKIData, and the `reqSequence` bytes are surfaced exactly as they appeared so an Identity Proof witness is computed over the wire bytes. A companion decoder for CMS content rather than an auto-routed format — `parse`, `parsePkiData`, `parsePkiResponse` |
@@ -245,7 +245,7 @@ comment blocks, is at [pkijs.com](https://pkijs.com).
 | `pki.ocsp` | Online Certificate Status Protocol (RFC 6960), both the responder and relying-party surface. `buildRequest(query, opts)` builds an OCSPRequest for one or more `{ cert, issuer }` pairs, with the CertID hashed under SHA-1 by default per the RFC 5019 lightweight profile or under SHA-2, plus an optional RFC 9654 nonce and an optional requestor signature. `sign(responseData, responder, opts)` produces a signed BasicOCSPResponse over the exact `ResponseData` DER, from the issuing CA directly or a delegated responder, under any `pki.cms.sign` key including the post-quantum ML-DSA and SLH-DSA sets, with `good`, `revoked` (reason and time), or `unknown` per-certificate status. `buildErrorResponse(status)` produces the unsigned §2.3 error (`tryLater`, `unauthorized`, and the rest). `verify(response, opts)` verifies a response fail-closed against the same hardened gates `pki.path.ocspChecker` runs: the CertID binding, responder authorization (the issuing CA, or a CA-issued delegate bearing id-kp-OCSPSigning and id-pkix-ocsp-nocheck and passing the full out-of-path certificate gates), the signature over `tbsResponseDataBytes`, currency against `thisUpdate` and `nextUpdate`, and the request-nonce echo. It returns `{ status: "good" / "revoked" / "unknown", ... }` and never silently accepts. `verifyRequest(request, opts)` is the responder-side inverse of `buildRequest`: it verifies a client's signed request (RFC 6960 §4.1.1) under the requestor certificate the request carries, trying each embedded certificate since the field is unordered, and reports `signed`, `signatureValid`, every certificate whose key verified (`signerCerts`, so a key carried under an expired certificate beside its renewal is not hidden behind ordering) with the first one's decoded subject, the full embedded certificate bag (`certs`, including intermediates for path building), and the request's CertIDs; an unsigned request is reported with `signed: false` rather than refused. Transport-free — `buildRequest`, `sign`, `buildErrorResponse`, `verify`, `verifyRequest` |
 | `pki.ct` | Certificate Transparency (RFC 6962). `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries, a TLS-presentation-language payload inside the §3.3 double DER wrap, into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature. `reconstructSignedData` rebuilds the exact `digitally-signed` preimage, and `verifySct` verifies an SCT signature against a log's public key, routing an ECDSA signature through the strict DER-conformance gate and verifying through the crypto engine, resolving true or false and throwing a typed error on a structural fault. On the producing side, `encodeSctList` builds the extension value byte for byte as the exact inverse of `parseSctList`, and `signSct` performs a log's signing step. For trust, `parseLogList` ingests the CT log-list JSON into constraint-carrying trusted logs, recomputing each log's id as SHA-256 of its key and refusing a disagreeing id (a swapped key, §3.2) and decoding the state and temporal-interval constraints; `verifySctWithLogList` resolves the log key from an SCT's log id, enforces the state (usable, qualified, and readonly trusted; retired only before retirement; pending and rejected refused) and the temporal-interval window, then delegates the signature check to `verifySct`. `verifyLogListSignature(json, signature, publicKey)` verifies the detached `log_list.sig` over the raw log-list bytes against a caller-pinned signer key (RSASSA-PKCS1-v1.5/SHA-256 and an EC P-256 arm, with forgeable-key defenses failing closed), cross-checked against `openssl dgst`. `fetchLogList(opts)` turns that chain into a live client: it GETs the `log_list.json` and its detached `log_list.sig` over `pki.transport`, verifies the detached signature over the raw fetched bytes against a caller-pinned distributor key before parsing, so an unverified document is never parsed, read, cached, or surfaced, then ingests the same bytes through `parseLogList` and returns the trusted-log set plus the surfaced `version` and `timestamp`. Above the per-SCT layer, `verifySctList` renders a certificate-level verdict over every SCT a certificate carries (§3.3), reporting how many distinct trusted logs verified an SCT (so a duplicated SCT cannot inflate the count) and from how many distinct trusted operators against a caller's CT policy (`minScts` and `minOperators`, both defaulting to the RFC floor of one), where a policy shortfall is a verdict and a per-SCT failure is a recorded row rather than a thrown call; `x509CertEntry` reconstructs the precertificate log entry from a final certificate by removing the SCT-list extension from its TBSCertificate as byte surgery, so its embedded SCTs verify end to end (§3.2). The toolkit bakes in no vendor URL or key, TLS trust is explicit with `rejectUnauthorized` always on, each response is size-capped before the trust chain, and the transport is injectable so the whole path is testable offline — `parseSctList`, `reconstructSignedData`, `verifySct`, `encodeSctList`, `signSct`, `parseLogList`, `verifySctWithLogList`, `verifySctList`, `x509CertEntry`, `verifyLogListSignature`, `fetchLogList` |
 | `pki.merkle` | Merkle-tree proof verification (RFC 6962 / RFC 9162). `leafHash`, `nodeHash`, and `emptyRootHash` build the domain-separated (0x00 leaf, 0x01 node) SHA-256 tree hashes. `verifyInclusion` folds an audit proof back to a root, and `verifyConsistency` reconstructs both the old and new root, which is the append-only guarantee; each is constant-time-compared to a trusted checkpoint root. Fail-closed on bad geometry, sync hashing, transport-free — `leafHash`, `nodeHash`, `emptyRootHash`, `verifyInclusion`, `verifyConsistency` |
-| `pki.trust` | Mozilla and CCADB trust-store ingestion. `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export, both into one constraint-carrying anchor shape: the per-purpose trust bits, where only `CKT_NSS_TRUSTED_DELEGATOR` grants, and the per-purpose distrust-after dates the bare root list omits. Certificate and trust objects pair by byte-exact issuer and serial rather than adjacency and are cross-checked against the parsed DER, so metadata cannot attach to the wrong root. `anchor()` hands an entry to `pki.path.validate({ trustAnchor, checkPurpose })`. Offline, fail-closed, bounded — `parseCertdata`, `parseCcadbCsv`, `anchor` |
+| `pki.trust` | Mozilla and CCADB trust-store ingestion. `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export, both into one constraint-carrying anchor shape: the per-purpose trust bits, where only `CKT_NSS_TRUSTED_DELEGATOR` grants, and the per-purpose distrust-after dates the bare root list omits. Certificate and trust objects pair by byte-exact issuer and serial rather than adjacency and are cross-checked against the parsed DER, so metadata cannot attach to the wrong root. `anchor()` hands an entry to `pki.path.validate({ trustAnchors, checkPurpose })`. Offline, fail-closed, bounded — `parseCertdata`, `parseCcadbCsv`, `anchor` |
 | `pki.shbs` | 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 for CNSA 2.0 firmware signing. `verify` checks an HSS signature, where every level must pass, and `verifyLms` a single-tree LMS, over the raw public-key and signature blobs the parsers already surface. Pure public-input SHA-256 and SHAKE256 hashing, a data-driven typecode registry, and bounds-before-slice reads; a malformed blob throws a typed `ShbsError` while a well-formed but wrong signature returns `false`. Verification only by design, since stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |
 | `pki.hpke` | Hybrid Public Key Encryption (RFC 9180), the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS` and `setupR` establish a sender or recipient context (KEM encapsulation plus the HKDF key schedule); the context's `seal` and `open` AEAD-encrypt with a sequence-counter nonce, and `export` derives further secrets; the module-level `seal` and `open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) by HKDF-SHA256/SHA512 by AES-GCM / ChaCha20Poly1305 / export-only, across all four modes, proven against the RFC 9180 Appendix A vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered but Appendix A ships no vector for them, so they fail closed until an authoritative KAT exists. Pure composition over `node:crypto`; ML-KEM and X-Wing are a registry data-row extension pending stable drafts — `suites`, `setupS`, `setupR`, `seal`, `open` |
 | `pki.kem` | Composite ML-KEM key establishment (draft-ietf-lamps-pq-composite-kem), a post-quantum ML-KEM hybridized with a traditional RSA-OAEP, ECDH, X25519, or X448 so the established secret holds if either component is later broken. `encapsulate` turns a recipient's composite `SubjectPublicKeyInfo` into a 256-bit shared secret and a ciphertext; `decapsulate` recovers the same secret from the ciphertext and the composite PKCS#8 private key. Each component KEM runs independently and the two secrets are mixed through a SHA3-256 combiner that binds the traditional ciphertext, the traditional public key, and a per-algorithm label. The twelve algorithms pair ML-KEM-768 and ML-KEM-1024 with RSA-OAEP 2048/3072/4096, ECDH over P-256/P-384/P-521 and brainpoolP256r1/P384r1, X25519, and X448, each verified against the draft Appendix G known-answer vectors; a malformed key or ciphertext, an unsupported algorithm, or a component decapsulation failure throws a typed `KemError` — `encapsulate`, `decapsulate` |

package/bin/pki.js

@@ -190,7 +190,7 @@ function cmdVerify(args) {
   var spki = anchor.subjectPublicKeyInfo;
   return pki.path.validate(certs, {
     time: time,
-    trustAnchor: { name: anchor.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters },
+    trustAnchors: { name: anchor.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters },
   }).then(function (res) {
     process.stdout.write(res.valid ? "valid\n" : "invalid\n");
     if (!res.valid) {

package/lib/acme.js

@@ -43,7 +43,8 @@ var csr = require("./schema-csr");
 var pkix = require("./schema-pkix");
 var constants = require("./constants");
 var rfc3339 = require("./rfc3339");
-var webcrypto = require("./webcrypto").webcrypto;
+var wcEngine = require("./webcrypto");
+var webcrypto = wcEngine.webcrypto;
 var subtle = webcrypto.subtle;
 var frameworkError = require("./framework-error");
 var httpTransport = require("./http-transport");
@@ -2259,6 +2260,7 @@ function _parseLinkNext(headers, base) { var m = _parseLinkRelation(headers, bas
  *   - `tls` -- { anchors, useSystemStore, cert, key, minVersion, servername, checkServerIdentity } for the default transport.
  *   - `timeout` / `maxResponseBytes` / `maxRedirects` -- transport budgets; `maxNonceRetries` -- badNonce retry cap (default 1).
  *   - `maxPolls` / `maxTotalWait` / `sleep` -- poll-loop budgets + an injectable sleeper; `clock` -- an injectable receipt clock (default Date.now) for a Retry-After HTTP-date.
+ *   - `resignKeys` -- optional ordered `[{ alg, key }]` enabling the RFC 8555 sec. 6.2 badSignatureAlgorithm re-sign. When a CA rejects the account `alg` and advertises the algs it supports, the first entry whose `alg` the CA advertised re-signs the request once and retries. Each `key` is a CryptoKey for the SAME account key material under that `alg`: an RSA account key signs RS256 and PS256 from one key, and its registered public JWK verifies either. The caller's order selects and the CA's list only filters, so a spoofed badSignatureAlgorithm cannot force a weaker alg (sec. 10). Absent, or with no advertised match, the badSignatureAlgorithm surfaces unchanged.
  *   - `newAuthz(identifier)` -- pre-authorize a single identifier (RFC 8555 sec. 7.4.1) -> { authorization, url }.
  *   - `downloadCertificate(url, { expectedSpki, identifiers, requireBinding, selectChain, maxAlternates })` -- bind the issued certificate to this order, then pick among RFC 8555 sec. 7.4.2 alternate chains. `expectedSpki` (the DER SubjectPublicKeyInfo this order's CSR asked to have certified) and `identifiers` (the order's own identifier array) are what the returned end-entity certificate is checked against: a different key is `acme/certificate-key-mismatch`, a different identifier set `acme/certificate-identifier-mismatch`. Only `dns` and `ip` identifiers map to a name a certificate carries, so an order identifier of another registered type, a certificate `subjectAltName` that is neither a dNSName nor an iPAddress, and a subject common name that is neither a dns name nor a canonical IP address, are each refused as `acme/unsupported-identifier-type` rather than dropped from the comparison. The certificate's alternative names are its identity; its common name is read only where it asserts none. At least one is required (`acme/binding-required`) unless `requireBinding: false`, which waives the requirement to supply material and never the check on material that is supplied. The result reports `boundToKey` / `boundToIdentifiers`. `selectChain({certificate, chain, certificates})` returns the first truthy candidate (primary first, then bounded `Link rel="alternate"` chains, confined to the download's own origin); the result adds `alternates` (the resolved alternate URLs).
  *   - `renewalWindow(certDer, { random, clock, replaced, previous })` -- the RFC 9773 ARI renewal decision: composes `renewalInfo`, selects a uniform-random instant in the suggested window -> { suggestedWindow, selectedTime, renewNow, retryAfterSeconds, explanationURL }. Pass a prior result back as `previous` to REUSE its selectedTime while the CA's window is unchanged (RFC 9773 sec. 4.2), so repeated refreshes keep one stable renewal instant.
@@ -2272,7 +2274,7 @@ function _parseLinkNext(headers, base) { var m = _parseLinkRelation(headers, bas
 // defaulted -- a mistyped `maxRedirects` or `transport` would otherwise change the client's behavior with
 // no error. The per-request options each returned method takes are checked in those methods, not here.
 var _CLIENT_OPTS = {
-  accountKey: 1, accountJwk: 1, alg: 1, transport: 1, tls: 1, timeout: 1, maxResponseBytes: 1,
+  accountKey: 1, accountJwk: 1, alg: 1, resignKeys: 1, transport: 1, tls: 1, timeout: 1, maxResponseBytes: 1,
   maxRedirects: 1, maxNonceRetries: 1, maxPolls: 1, maxTotalWait: 1, sleep: 1, clock: 1,
 };
 // The per-request options each client method reads. A near-miss spelling in a method's own bag is
@@ -2299,6 +2301,49 @@ function _gateOpts(bag, whitelist, name) {
   guard.identifier.assertKnownKeys(bag, whitelist, E, "acme/bad-input", "unknown " + name + " option ");
   return bag;
 }
+// Validate + snapshot opts.resignKeys (config-time, fail closed). Absent -> null (the feature is OFF and
+// a badSignatureAlgorithm surfaces to the caller unchanged). Present -> a non-empty array of { alg, key }
+// where alg is a JWS alg string and key is a CryptoKey; each pair is read ONCE into a frozen copy so a
+// caller getter cannot rewrite it between this check and the re-sign, and the caller's order is preserved.
+function _resignKeysOf(raw) {
+  if (raw == null) return null;
+  if (!_isArrayI(raw) || raw.length === 0) throw E("acme/bad-input", "resignKeys, when set, must be a non-empty array of { alg, key } (RFC 8555 sec. 6.2)");
+  var out = [];
+  for (var i = 0; i < raw.length; i++) {
+    var e = raw[i];
+    if (!_isObject(e)) throw E("acme/bad-input", "each resignKeys entry must be { alg: string, key: CryptoKey } (RFC 8555 sec. 6.2); entry " + i + " is not");
+    // Read each field ONCE into the frozen snapshot: a caller getter cannot then answer the validation
+    // and the re-sign with different values (the alg checked is the alg signed, the key checked is signed).
+    var a = e.alg, k = e.key;
+    if (!_isString(a) || !wcEngine.isCryptoKeyLike(k)) throw E("acme/bad-input", "each resignKeys entry must be { alg: string, key: CryptoKey } (RFC 8555 sec. 6.2); entry " + i + " is not");
+    out[i] = intrinsic.freeze({ alg: a, key: k });   // index-write, not a live-prototype .push
+  }
+  return intrinsic.freeze(out);
+}
+// Pick the re-sign entry to use for a badSignatureAlgorithm: the FIRST caller-listed entry whose alg the
+// server advertised as supported. Caller order selects and the server's array only filters, so a bogus
+// badSignatureAlgorithm cannot steer the client to the server's weakest alg (RFC 8555 sec. 10). Returns
+// null when no caller entry matches (the badSignatureAlgorithm then surfaces, fail closed).
+function _chooseResign(resignKeys, serverAlgs) {
+  if (!resignKeys || !_isArrayI(serverAlgs)) return null;
+  for (var i = 0; i < resignKeys.length; i++) {
+    for (var j = 0; j < serverAlgs.length; j++) {
+      if (serverAlgs[j] === resignKeys[i].alg) return resignKeys[i];
+    }
+  }
+  return null;
+}
+// A copy of a public JWK with its optional `alg` member set to the alg actually being signed. A
+// WebCrypto-exported RSA JWK carries the key's native alg (e.g. RS256), so embedding it unchanged under a
+// re-sign alg (PS256) would advertise a JWK whose declared alg contradicts the JWS header, which a strict
+// ACME server may reject. Own members are copied through captured intrinsics (no live prototype read).
+function _jwkForAlg(jwk, alg) {
+  var out = {};
+  var keys = intrinsic.ownKeys(jwk);
+  for (var i = 0; i < keys.length; i++) { out[keys[i]] = jwk[keys[i]]; }
+  out.alg = alg;
+  return out;
+}
 function client(directoryUrl, opts) {
   opts = guard.identifier.optionsObject(opts, E, "acme/bad-input", "pki.acme.client options");
   guard.identifier.assertKnownKeys(opts, _CLIENT_OPTS, E, "acme/bad-input", "unknown pki.acme.client option ");
@@ -2308,6 +2353,12 @@ function client(directoryUrl, opts) {
   jose.assertPublicJwk(opts.accountJwk);
   var dirUrl = _clientUrl(directoryUrl);
   var accountKey = opts.accountKey, accountJwk = opts.accountJwk, alg = opts.alg;
+  // Optional badSignatureAlgorithm re-sign material (RFC 8555 sec. 6.2). Each entry pairs an alternative
+  // JWS alg with a CryptoKey for the SAME account key material under that alg (an RSA public JWK is
+  // padding-agnostic, so the registered account key still verifies a re-signed request). Snapshotted here
+  // so a caller getter cannot rewrite the pairs between validation and use, and ordered by CALLER
+  // preference: on a badSignatureAlgorithm the caller's order selects, never the server's (sec. 10).
+  var resignKeys = _resignKeysOf(opts.resignKeys);
 
   var transport = opts.transport;
   if (!transport) {
@@ -2472,11 +2523,12 @@ function client(directoryUrl, opts) {
   // with the error response's fresh nonce (RFC 8555 sec. 6.5 -- _takeNonce's LIFO pool surfaces it).
   // `accept` is the media type the request advertises (default application/json). This is the single
   // home of the badNonce retry, so every signed POST -- account-key or certificate-key -- inherits it.
-  function _postJws(url, makeJws, accept, okStatuses) {
+  function _postJws(url, makeJws, accept, okStatuses, allowResign) {
     var ok = okStatuses || [200];
     var attempt = 0;
-    function once() {
-      return _takeNonce().then(makeJws).then(function (jws) {
+    var resignAttempt = 0;
+    function once(override) {
+      return _takeNonce().then(function (nonce) { return makeJws(nonce, override); }).then(function (jws) {
         return _send("POST", url, { "content-type": "application/jose+json", "accept": accept || "application/json" }, JSON.stringify(jws));
       }).then(function (res) {
         // An application/problem+json body is an ERROR regardless of the HTTP status -- a CA / proxy
@@ -2486,7 +2538,17 @@ function client(directoryUrl, opts) {
             var prob = null;
             try { prob = jose.parseJson(_jsonInput(res)); }
             catch (_e) { /* allow:swallow-unverified a non-JSON problem body is not a badNonce; prob stays null, falling through to the typed acme/server-problem throw */ }
-            if (prob && typeof prob.type === "string" && _endsWith(prob.type, ":badNonce") && attempt < maxNonceRetries) { attempt++; return once(); }
+            // A badNonce retry keeps the CURRENT signing override (a re-sign is not undone by a following
+            // badNonce), so it re-signs with the same alg the request already switched to.
+            if (prob && typeof prob.type === "string" && _endsWith(prob.type, ":badNonce") && attempt < maxNonceRetries) { attempt++; return once(override); }
+            // A badSignatureAlgorithm (RFC 8555 sec. 6.2): if the caller supplied resignKeys and one of its
+            // algs is in the server's advertised `algorithms`, re-sign ONCE with that caller-preferred key.
+            // The caller's order selects (never the server's), so a bogus badSignatureAlgorithm cannot force
+            // a downgrade (sec. 10); no match, or no resignKeys, falls through to the fail-closed throw.
+            if (allowResign && resignKeys && prob && typeof prob.type === "string" && _endsWith(prob.type, ":badSignatureAlgorithm") && resignAttempt < 1) {
+              var pick = _chooseResign(resignKeys, prob.algorithms);
+              if (pick) { resignAttempt++; return once(pick); }
+            }
           }
           throw _serverProblem(res);
         }
@@ -2501,14 +2563,18 @@ function client(directoryUrl, opts) {
   }
   // Build an account-key JWS (kid or jwk mode) with a fresh nonce and POST it through the retrying _postJws.
   function _post(url, builder, extra, mode, accept, okStatuses) {
-    return _postJws(url, function (nonce) {
+    return _postJws(url, function (nonce, override) {
       // The client-owned JWS session fields (signing key, alg, single-use nonce, protected url) are applied
       // AFTER the caller's payload options, so a payload carrying key/alg/nonce/url cannot override them and
-      // desynchronize the protected header from the actual request (or reuse a nonce).
-      var base = Object.assign({}, extra || {}, { key: accountKey, alg: alg, nonce: nonce, url: url });
-      if (mode === "jwk") base.jwk = accountJwk; else base.kid = _requireKid();
+      // desynchronize the protected header from the actual request (or reuse a nonce). On a badSignatureAlgorithm
+      // re-sign `override` carries the caller's chosen { alg, key } (the SAME account material under another alg);
+      // the embedded jwk stays accountJwk, which still verifies it (an RSA public JWK is padding-agnostic).
+      var base = Object.assign({}, extra || {}, { key: override ? override.key : accountKey, alg: override ? override.alg : alg, nonce: nonce, url: url });
+      // On a re-sign the embedded jwk's declared alg must follow the alg being signed, not the account
+      // key's native one, so the published JWK and the JWS header agree (jwk mode / newAccount).
+      if (mode === "jwk") base.jwk = override ? _jwkForAlg(accountJwk, override.alg) : accountJwk; else base.kid = _requireKid();
       return builder(base);
-    }, accept, okStatuses);
+    }, accept, okStatuses, true);
   }
   function _postAsGet(url) { return _post(url, postAsGet, null, "kid"); }
 
@@ -2863,6 +2929,11 @@ function client(directoryUrl, opts) {
         // sync -- a bodyless or malformed account body must NOT leave the client on the old key while the
         // server holds the new one. The account object is optional + informational: parse it best-effort.
         accountKey = o.newKey; accountJwk = o.newJwk; alg = o.newAlg;
+        // The resignKeys alternatives are CryptoKeys for the OLD account key material, so they no longer
+        // match the rotated account key. Drop them: re-signing with a stale-key alternative under the new
+        // kid would be rejected by the CA. With them cleared, a later badSignatureAlgorithm surfaces (the
+        // conformant default) rather than retrying with obsolete key material.
+        resignKeys = null;
         var acct = null;
         if (_bodyText(res).trim() !== "") {
           try { acct = validate("account", _json(res)); }

package/lib/path-validate.js

@@ -1214,8 +1214,10 @@ function validateCriticalExtensionStructure(cert) {
  * Validate an ordered certification `path` (anchor->target) against a trust
  * anchor per RFC 5280 6.1. `path` is an array of `pki.schema.x509.parse`
  * objects (or DER/PEM the function parses); `opts` carries `time` (the
- * always-on window check), `trustAnchor` ({ name, publicKey, algorithm,
- * parameters? }), the 6.1.1 user-initial inputs (`initialExplicitPolicy`,
+ * always-on window check), `trustAnchors` (a single { name, publicKey,
+ * algorithm, parameters? } anchor or a non-empty array of them; with several,
+ * the one that issued the path terminus is selected), the 6.1.1 user-initial
+ * inputs (`initialExplicitPolicy`,
  * `initialAnyPolicyInhibit`, `initialPolicyMappingInhibit`,
  * `userInitialPolicySet`, and `initialPermittedSubtrees` /
  * `initialExcludedSubtrees` -- arrays of `{ tag, base }` where `tag` is the
@@ -1263,16 +1265,14 @@ function validateCriticalExtensionStructure(cert) {
  *   var res = await pki.path.validate([cert], {
  *     time: new Date("2020-01-01T00:00:00Z"),
  *     // the anchor's own key algorithm, not the algorithm its issuer signed it with
- *     trustAnchor: { name: cert.issuer, publicKey: cert.subjectPublicKeyInfo.bytes,
- *       algorithm: cert.subjectPublicKeyInfo.algorithm.oid },
+ *     trustAnchors: [{ name: cert.issuer, publicKey: cert.subjectPublicKeyInfo.bytes,
+ *       algorithm: cert.subjectPublicKeyInfo.algorithm.oid }],
  *   });
  *   res.valid;  // boolean; res.results[0].checks carries the per-check codes
  */
-// Every option pki.path.validate reads. The anchor option here is the singular `trustAnchor`,
-// while pki.path.build in this same module spells it `trustAnchors` and takes a list. A caller
-// moving between the two verbs carries the wrong spelling without leaving the namespace, and
-// before this it bought them no anchoring and no error, just "a trustAnchor is required" about
-// an option they believed they had passed.
+// Every option pki.path.validate reads. The anchor option is `trustAnchors` (plural), the same
+// spelling pki.path.build / pki.cms.verify / pki.cmp.verify use, and it takes a single anchor or a
+// non-empty array of them. A one-element array reproduces the single-anchor behavior exactly.
 // Derived from three sources, because no one of them is complete: the `opts.*` reads in this
 // function, the `params.*` reads in the RFC 5280 6.1.1 state it is passed down to, and the
 // documented prose above, which is the only place `requiredEku` and the three initial-policy
@@ -1282,7 +1282,7 @@ var _VALIDATE_OPTS = {
   checkPurpose: 1, ctLogList: 1, ctPolicy: 1, historicalMode: 1, initialAnyPolicyInhibit: 1,
   initialExcludedSubtrees: 1, initialExplicitPolicy: 1, initialPermittedSubtrees: 1,
   initialPolicyMappingInhibit: 1, maxPathCerts: 1, maxPolicyNodes: 1, requireRevocation: 1,
-  requiredEku: 1, revocationChecker: 1, softFail: 1, time: 1, trustAnchor: 1,
+  requiredEku: 1, revocationChecker: 1, softFail: 1, time: 1, trustAnchors: 1,
   userInitialPolicySet: 1, verifier: 1
 };
 
@@ -1328,8 +1328,7 @@ async function ctGateCheck(leaf, certs, anchor, ctLogList, ctPolicy, n, at) {
 async function validate(path, opts) {
   opts = guard.identifier.optionsObject(opts, E, "path/bad-input", "validate: opts");
   guard.identifier.assertKnownKeys(opts, _VALIDATE_OPTS, E, "path/bad-input",
-    "pki.path.validate has an unknown option. The anchor here is `trustAnchor`, singular; " +
-    "pki.path.build takes `trustAnchors`. The unknown option was: ");
+    "pki.path.validate has an unknown option (the anchor option is `trustAnchors`, a single anchor or an array). The unknown option was: ");
   // A CT policy without a log-list cannot be enforced -- refuse it at entry rather than silently
   // skipping the CT gate and returning a valid path the caller believes was CT-checked (fail-closed).
   if (opts.ctPolicy != null && opts.ctLogList == null) throw E("path/bad-input", "validate: opts.ctPolicy requires opts.ctLogList (the trusted CT log-list to verify the certificate's SCTs against)");
@@ -1358,11 +1357,52 @@ async function validate(path, opts) {
   var certs = path.map(function (c, ci) { return coerceCert(c, "validate: path[" + ci + "]"); });
   var n = certs.length;
   if (n < 1) throw E("path/empty-path", "validate: the certification path is empty");
-  if (!opts.trustAnchor) throw E("path/bad-input", "validate: a trustAnchor is required");
-  // Normalize the anchor at the door: a parsed root CERTIFICATE becomes a { name, publicKey, algorithm }
-  // tuple, and a mis-shaped tuple fails closed with path/bad-input rather than seeding an undefined
-  // working key that a self-describing SPKI could still validate against (a soft-verdict fail-open).
-  var anchor = toAnchor(opts.trustAnchor, "validate");
+  // trustAnchors is a single anchor OR a non-empty array of them. Normalize each at the door: a parsed
+  // root CERTIFICATE becomes a { name, publicKey, algorithm } tuple, and a mis-shaped tuple fails closed
+  // with path/bad-input rather than seeding an undefined working key a self-describing SPKI could still
+  // validate against (a soft-verdict fail-open). With more than one anchor, select the one whose subject
+  // issued the top path cert (certs[0], anchor->target order); a one-element list reproduces the
+  // single-anchor behavior exactly, and no match falls to the first so the name-chaining check below
+  // fails closed (an untrusted chain is never validated against a non-matching root).
+  var rawAnchors = opts.trustAnchors;
+  var anchorList = intrinsic.isArray(rawAnchors) ? rawAnchors : [rawAnchors];
+  if (rawAnchors == null || anchorList.length === 0) throw E("path/bad-input", "validate: trustAnchors is required (a single anchor or a non-empty array of anchors)");
+  // With more than one anchor, validate the SAME path against each and accept if ANY yields a valid path
+  // (the trust-store "does this chain lead to any of my roots" question). Two anchors can share a subject
+  // DN with different keys (a rotated or cross-signed root), so choosing by name alone would reject a
+  // valid chain when the wrong same-name anchor is tried first: try each, order-independent for validity.
+  // Each recursion carries exactly one anchor, so it runs the single-anchor body below (no further fan-out).
+  if (anchorList.length > 1) {
+    // Normalize the COMPLETE array up front: toAnchor validates each tuple exactly as the single-anchor
+    // path does, so a malformed anchor is refused (path/bad-input) regardless of its position, never
+    // silently accepted because a valid anchor happened to be tried first.
+    var tuples = [];
+    for (var ti = 0; ti < anchorList.length; ti++) { tuples[ti] = toAnchor(anchorList[ti], "validate"); }
+    // One anchor per recursion, so each runs the single-anchor body below (no further fan-out).
+    var singleOpts = function (a) {
+      var keys = intrinsic.ownKeys(opts);
+      var o = {};
+      for (var ki = 0; ki < keys.length; ki++) { o[keys[ki]] = opts[keys[ki]]; }
+      o.trustAnchors = a;
+      return o;
+    };
+    // Only an anchor whose subject issued certs[0] can complete this path, so try each such candidate and
+    // skip unrelated roots: the cost does not scale with a whole trust store. Same-subject anchors with
+    // different keys (a rotated or cross-signed root) ALL match the terminus and are each tried, so validity
+    // is order-independent.
+    var lastMatched = null, anyMatched = false;
+    for (var ai = 0; ai < tuples.length; ai++) {
+      if (!dnEqual(tuples[ai].name.rdns, certs[0].issuer.rdns)) continue;
+      anyMatched = true;
+      var oneRes = await validate(path, singleOpts(tuples[ai]));
+      if (oneRes && oneRes.valid) return oneRes;
+      lastMatched = oneRes;
+    }
+    // No supplied anchor's subject matched the path terminus: the chain leads to none of them. Run one to
+    // produce the fail-closed valid:false verdict (the name-chaining check reports it) rather than null.
+    return anyMatched ? lastMatched : validate(path, singleOpts(tuples[0]));
+  }
+  var anchor = toAnchor(anchorList[0], "validate");
   // The validity-window check is always on (6.1.3(a)(2)); a missing/invalid
   // check date must fail closed, never silently disable it.
   guard.time.assertValid(opts.time, E, "path/bad-input", "validate: opts.time (the always-on validity-window check date)");
@@ -3214,8 +3254,8 @@ function toAnchor(entry, verb) {
  * @status     stable
  * @spec       RFC 5280 sec. 6.1.1
  *
- * Turn a parsed certificate into the trust-anchor tuple `pki.path.validate` (`opts.trustAnchor`) and
- * `pki.path.build` (`opts.trustAnchors`) consume, so a root can be pinned directly instead of
+ * Turn a parsed certificate into the trust-anchor tuple `pki.path.validate` and `pki.path.build` consume
+ * as `opts.trustAnchors` (a single anchor or an array), so a root can be pinned directly instead of
  * hand-building `{ name, publicKey, algorithm }`. The subject becomes the anchor name and its
  * SubjectPublicKeyInfo the anchor key and algorithm. A value that is neither a parsed certificate nor a
  * ready anchor tuple is refused with `path/bad-input`. `validate` and `build` already normalize a
@@ -3226,7 +3266,7 @@ function toAnchor(entry, verb) {
  *   var rootDer = await pki.x509.sign({ subject: "Root CA", subjectPublicKey: await pki.key.export(pair.publicKey),
  *     notBefore: new Date(0), notAfter: new Date("2999-01-01") }, { key: pair.privateKey });
  *   var anchor = pki.path.anchorFromCert(pki.schema.x509.parse(rootDer));
- *   // anchor is { name, publicKey, algorithm, ... } -- pass it as opts.trustAnchor to pki.path.validate
+ *   // anchor is { name, publicKey, algorithm, ... } -- pass it as opts.trustAnchors to pki.path.validate
  */
 function anchorFromCert(cert) { return toAnchor(cert, "anchorFromCert"); }
 
@@ -3489,11 +3529,8 @@ async function _fetchAiaIssuers(current, aia) {
 // pki.path.build takes its own options AND forwards every pki.path.validate option to each
 // internal validate() call. The documented contract above says so, and validateOpts() copies
 // them wholesale. So the accepted set is the union, derived from _VALIDATE_OPTS. Retyping it
-// would let the two lists drift the first time validate gains an option.
-//
-// `trustAnchor` is removed from the union on purpose: build assigns it per candidate anchor,
-// so a caller passing the singular would have it overwritten and silently ignored. Refusing it
-// is what makes the singular/plural message below actionable rather than trivia.
+// would let the two lists drift the first time validate gains an option. Both verbs now spell the
+// anchor option `trustAnchors`, so the union carries one key and build applies its own per-candidate.
 var _BUILD_OPTS = (function () {
   var o = {
     aiaTimeout: 1, candidates: 1, fetchAia: 1, intermediates: 1, maxAiaFetches: 1,
@@ -3501,15 +3538,13 @@ var _BUILD_OPTS = (function () {
     maxResponseBytes: 1, time: 1, tls: 1, transport: 1, trustAnchors: 1, validate: 1
   };
   Object.keys(_VALIDATE_OPTS).forEach(function (k) { o[k] = 1; });
-  delete o.trustAnchor;
   return o;
 })();
 
 async function build(leaf, opts) {
   opts = guard.identifier.optionsObject(opts, E, "path/bad-input", "build: opts");
   guard.identifier.assertKnownKeys(opts, _BUILD_OPTS, E, "path/bad-input",
-    "pki.path.build has an unknown option. The anchors here are `trustAnchors`, plural; " +
-    "pki.path.validate takes `trustAnchor`. The unknown option was: ");
+    "pki.path.build has an unknown option (the anchor option is `trustAnchors`). The unknown option was: ");
   var leafCert;
   try { leafCert = coerceCert(leaf); }
   catch (e) { throw E("path/bad-input", "build: the leaf certificate did not parse", e); }
@@ -3635,7 +3670,7 @@ async function build(leaf, opts) {
     // apply the method rule a second time and drop a function-valued option all over again;
     // forwarding less than was validated is worse than refusing the bag.
     Object.keys(forwarded).forEach(function (f) { vo[f] = forwarded[f]; });
-    vo.trustAnchor = anchor;
+    vo.trustAnchors = anchor;   // one anchor per candidate; validate accepts a single anchor or an array
     return vo;
   }
 

package/lib/sigstore.js

@@ -477,7 +477,7 @@ async function _verifyChain(leaf, chainDers, fulcioRoots, timeMs) {
       var res = await pathValidate.validate(path, {
         time: new Date(timeMs),
         historicalMode: true,
-        trustAnchor: { name: anchor.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters },
+        trustAnchors: { name: anchor.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters },
         requiredEku: ["codeSigning"],
       });
       if (res.valid) return;

package/lib/trust.js

@@ -875,7 +875,7 @@ function parseCcadbCsv(text) {
  *   var entry = pki.trust.parseCcadbCsv(csv).anchors[0];
  *   var anchor = pki.trust.anchor(entry, { purpose: "serverAuth" });
  *   await pki.path.validate([pki.schema.x509.parse(der)],
- *     { time: new Date("2026-06-01T00:00:00Z"), trustAnchor: anchor, checkPurpose: "serverAuth" });
+ *     { time: new Date("2026-06-01T00:00:00Z"), trustAnchors: anchor, checkPurpose: "serverAuth" });
  */
 // `purpose` is the only option, and it gates the authorization itself, so a near-miss spelling must not
 // pass silently: a caller who wrote the plural `purposes` (or carried a sibling's word) would otherwise get

package/lib/tsp-sign.js

@@ -697,13 +697,13 @@ function _buildTsaChains(leaf, pool) {
  * serialNumberHex, policy, nonce, tsa, tstInfo, signer, code?, reason? }`. `valid` is true only
  * when the CMS signature, the imprint match, the eContentType, the ESSCertID(V2) binding, the
  * RFC 3161 sec. 2.3 critical single-`timeStamping` extendedKeyUsage rule, the requested nonce (when
- * supplied), and, when a `trustAnchor` is supplied, the full out-of-path TSA-cert path
+ * supplied), and, when `trustAnchors` is supplied, the full out-of-path TSA-cert path
  * validation all pass. A conformance / trust failure of a well-formed token is a
  * `{ valid:false, code }` verdict; malformed or config input throws a typed `TspError`.
  *
  * `trusted` is the second claim and is kept apart from the first. `valid` says the token's
  * signature and structural bindings hold; `trusted` says the timestamp authority chained to an
- * anchor this caller named. Without `trustAnchor` there is nothing to chain to and `trusted` is
+ * anchor this caller named. Without `trustAnchors` there is nothing to chain to and `trusted` is
  * `false`: every branch, refusing and accepting alike, carries the field with a definite
  * value. A timestamp is archived precisely to be re-read years later, and one boolean
  * cannot answer both questions then.
@@ -714,8 +714,8 @@ function _buildTsaChains(leaf, pool) {
  * un-revoked. It is `false` whenever no path ran at all. `anchorConstraints` carries whatever the anchor
  * itself constrained, from `pki.path.validate`.
  *
- * @opts  trustAnchor   Anchor `{ name, publicKey, algorithm }`. Runs `pki.path.validate` on the
- *                       TSA certificate chain ordered from the token's embedded certificates
+ * @opts  trustAnchors  Anchor `{ name, publicKey, algorithm }`, or a non-empty array of them. Runs
+ *                       `pki.path.validate` on the TSA certificate chain from the token's certificates
  *                       (validity at genTime, requiredEku timeStamping, and revocation when a
  *                       `revocationChecker` is supplied, with `revocationChecked` reporting which),
  *                       so a TSA under an intermediate CA validates, not only one directly under
@@ -739,11 +739,11 @@ function _buildTsaChains(leaf, pool) {
  *   var imprint = { hashAlgorithm: "sha256", hashedMessage: sha256Digest };
  *   var token = await pki.tsp.sign(imprint, { cert: signerCertDer, key: signerKeyPkcs8 }, { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
  *   var res = await pki.tsp.verify(token, Buffer.from("hello"), {});
- *   res.valid;     // boolean; pass opts.trustAnchor to also chain the TSA cert to a root
+ *   res.valid;     // boolean; pass opts.trustAnchors to also chain the TSA cert to a root
  *   res.genTime;   // Date, read from the verified eContent
  */
 // Every option pki.tsp.verify reads. Adding one here is the only way to make it accepted.
-var _VERIFY_OPTS = { certs: 1, trustAnchor: 1, nonce: 1, reqPolicy: 1, revocationChecker: 1 };
+var _VERIFY_OPTS = { certs: 1, trustAnchors: 1, nonce: 1, reqPolicy: 1, revocationChecker: 1 };
 
 // Does any extension carry the critical flag? The answer IS the unknown-critical-extension gate, so
 // it is decided by comparison instead of by a `some`. See guard-list.
@@ -754,13 +754,12 @@ function _anyCritical(extensions) {
 async function verify(token, data, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.verify options must be an object");
-  // An unrecognized option is refused rather than ignored. This verb spells its anchor option
-  // SINGULAR -- `trustAnchor`, an anchor tuple -- while pki.cms.verify and pki.cmp.verify spell it
-  // `trustAnchors` and take certificate DER. A caller carrying the plural spelling here would
-  // otherwise get no anchoring and no error: the TSA certificate unchained, `valid: true`, and
-  // nothing to notice it by. Naming the difference at the boundary is the only place it is cheap.
+  // An unrecognized option is refused rather than ignored. The anchor option is `trustAnchors` (an
+  // anchor tuple, or a non-empty array of them), the same spelling pki.cms.verify / pki.cmp.verify use.
+  // A caller who mistyped it would otherwise get no anchoring and no error: the TSA certificate
+  // unchained, `valid: true`, and nothing to notice it by. Naming it at the boundary is cheap.
   guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "tsp/bad-input",
-    "pki.tsp.verify has an unknown option (note the anchor option here is `trustAnchor`, singular, an anchor tuple -- not the `trustAnchors` certificate list pki.cms.verify takes) ");
+    "pki.tsp.verify has an unknown option (the anchor option is `trustAnchors`) ");
   if (opts.certs != null && (!Array.isArray(opts.certs) || !guard.list.allMatch(opts.certs, function (c) { return guard.bytes.isByteSource(c); }))) {
     throw _err("tsp/bad-input", "pki.tsp.verify opts.certs must be an array of DER certificate Buffers");   // a bad element is a caller error, never silently dropped
   }
@@ -827,7 +826,7 @@ async function verify(token, data, opts) {
     if (!_tsaMatchesCert(tst.tsa.bytes, sc)) return fail("tsp/tsa-mismatch");
   }
   // M18 -- full out-of-path TSA-cert validation (issuer-sig, validity at genTime, unknown-critical,
-  // key-param inheritance, requiredEku, optional revocation), only when a trustAnchor is supplied.
+  // key-param inheritance, requiredEku, optional revocation), only when trustAnchors is supplied.
   // The path is ordered from the token's embedded certificates (leaf + any intermediates), so a TSA
   // issued under an intermediate CA -- not just directly under the anchor -- validates.
   // `trusted` is the SECOND claim, kept apart from `valid`. `valid` says the token's signature and
@@ -838,7 +837,7 @@ async function verify(token, data, opts) {
   // nothing to chain to and `trusted` is false: a definite answer rather than a missing one, the
   // same shape pki.cms.verify and pki.cmp.verify return.
   var trusted = false;
-  if (opts.trustAnchor) {
+  if (opts.trustAnchors) {
     var pathRes = null;
     // tst.genTime floors to millisecond precision. When genTime carries sub-millisecond digits the true
     // instant lies in (floor, floor+1ms], so fail closed on BOTH validity boundaries: require each
@@ -877,7 +876,7 @@ async function verify(token, data, opts) {
       // revocation.
       async function validateAt(chain, when) {
         var res = await pathValidate.validate(chain, {
-          time: when, trustAnchor: opts.trustAnchor, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
+          time: when, trustAnchors: opts.trustAnchors, requiredEku: ["timeStamping"], checkPurpose: "timeStamping", revocationChecker: opts.revocationChecker,
         });
         // The most any attempt ESTABLISHED, kept across every attempt: backtracking tries several
         // chains for one TSA certificate and a fractional genTime validates each at two endpoints,

package/lib/webauthn-mds.js

@@ -506,7 +506,7 @@ function _chainToAnchor(chain, anchors, at, what, code) {
         // carries these forward as the working public key, and a certificate below the anchor may
         // inherit its key parameters from them (the DSA-style parameter-inheritance case), so
         // supplying the signature OID leaves such a key unreconstructable and refuses a valid chain.
-        trustAnchor: { name: anchor.subject, publicKey: anchor.subjectPublicKeyInfo.bytes,
+        trustAnchors: { name: anchor.subject, publicKey: anchor.subjectPublicKeyInfo.bytes,
           algorithm: anchor.subjectPublicKeyInfo.algorithm.oid,
           parameters: anchor.subjectPublicKeyInfo.algorithm.parameters },
       }).then(function (r) { return !!(r && r.valid); }, function (e) { lastFault = e; return false; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:bf09eeaa-91f9-4b51-807c-b6184d2dfdce",
+  "serialNumber": "urn:uuid:bfbe087f-30ed-484a-ba11-142da30522a8",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-31T16:54:53.965Z",
+    "timestamp": "2026-08-31T23:06:26.187Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.6.10",
+      "bom-ref": "@blamejs/pki@0.6.11",
       "type": "application",
       "name": "pki",
-      "version": "0.6.10",
+      "version": "0.6.11",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.6.10",
+      "purl": "pkg:npm/%40blamejs/pki@0.6.11",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.6.10",
+      "ref": "@blamejs/pki@0.6.11",
       "dependsOn": []
     }
   ]