@blamejs/pki 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.3.7 — 2026-07-17
+
+Certification path building arrives as pki.path.build, and pki.lint gains seven RFC 5280 extension-criticality and CA-scope lints.
+
+### Added
+
+- pki.path.build(leaf, opts) discovers the ordered certification path from a leaf up to a trust anchor over an untrusted pool of candidate CA certificates, then validates it -- the discovering complement of pki.path.validate. Candidates are matched by RFC 5280 name chaining, prioritized by the RFC 4158 heuristics (subjectKeyIdentifier/authorityKeyIdentifier match, anchor-adjacent issuer, CA and keyCertSign, validity), and searched depth-first with backtracking; every accept flows through pki.path.validate, so a name or key-identifier match is only an ordering hint and building never weakens a path-validation check. The search is bounded (a chain-length cap, a total-work cap on candidate expansions, and an identity-tuple visited-set) so a cross-certificate cycle or Bridge-CA fan-out terminates deterministically; the trust store accepts anchor tuples or self-signed root certificates, opts.validate:false returns the ordered path unvalidated, and the verdict is cross-checked against openssl verify. AIA caIssuers fetching is offline-only (supply fetched issuers in opts.candidates). RFC 4158 / RFC 5280.
+- pki.lint.certificate flags seven RFC 5280 extension-criticality and CA-scope violations that parse but breach the certificate profile: basicConstraints (on a certificate-signing CA), nameConstraints, policyConstraints, and inhibitAnyPolicy must be marked critical (error); keyUsage should be critical (warn); nameConstraints must appear only in a CA certificate (error); and an end-entity certificate should carry a subjectKeyIdentifier (notice). The basicConstraints criticality rule applies only when the CA key validates certificate signatures (RFC 5280 4.2.1.9), so a CRL-signing-only CA carrying a non-critical basicConstraints is not falsely flagged.
+
+## v0.3.6 — 2026-07-17
+
+pki.cmp.build gains the CA/responder side -- certificate, revocation, key-recovery, general, error, poll, and confirmation responses complete the RFC 9810 message surface.
+
+### Added
+
+- pki.cmp.build message.body now accepts the CA/responder-side arms: ip / cp / kup / ccp (a CertRepMessage -- caPubs plus a response of CertResponse entries, each carrying a PKIStatusInfo and, under a granting status, a certifiedKeyPair), rp (a RevRepContent), krp (a KeyRecRepContent), genp (a general response), error (an ErrorMsgContent), pollRep (a poll response), and pkiconf (the final confirmation). They reuse the request-side header, envelope, ProtectedPart, and signature / PBMAC1 protection, and round-trip through pki.schema.cmp.parse. The RFC 9810 section 5.3.4 rules are enforced (a certifiedKeyPair only under a granting status and never with a failInfo, a validated certificate CHOICE, a single-response ccp). The private-key-transport / KEM encrypted forms ride a pre-encoded escape hatch.
+
 ## v0.3.5 — 2026-07-17
 
 pki.cmp.build assembles protected RFC 9810 CMP PKIMessages -- certificate requests, confirmations, revocations, and general messages, protected by a sender-key signature or a PBMAC1 shared secret.

package/README.md

@@ -221,12 +221,12 @@ is callable today; nothing below is a stub.
 | `pki.acme` | RFC 8555 / 8737 / 8738 / 9773 ACME message layer over `pki.jose` — resource-object validators (closed status enums, conditional-required fields, unknown fields ignored), the three §7.1.6 state machines, request builders (newAccount + EAB, newOrder + `replaces`, finalize with 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/ip identifier validators, and the ARI certID (serial sign-padding preserved). A message layer, not an HTTP client — transport-injectable, fail-closed — `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
-| `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. Pure and re-entrant, fail-closed — `validate`, `crlChecker`, `ocspChecker` |
+| `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. `build(leaf, opts)` is the discovering complement (RFC 4158): from a leaf, an untrusted pool of candidate CA certificates, and a trust store, it finds the ordered leaf→anchor path `validate` accepts — name chaining plus the RFC 4158 §3.5 sort hints (AKI/SKI match, anchor-adjacent issuer, CA + keyCertSign, validity), a depth-first search with backtracking so the first path `validate` accepts wins, and a bounded search (chain-length cap, candidate-expansion cap, identity-tuple visited-set) so a cross-certificate cycle or Bridge-CA fan-out terminates deterministically; every accept flows through `validate` and its verdict is cross-checked against `openssl verify`. Pure and re-entrant, fail-closed — `validate`, `build`, `crlChecker`, `ocspChecker` |
 | `pki.x509` | X.509 certificate issuance (RFC 5280 §4) — `sign(spec, issuer, opts)` builds and signs a certificate: a `spec` of subject (a common-name string, an array of RDNs, or raw Name DER), the public key being certified, the validity window, an optional serial, and an optional `extensions` object; an `issuer` that is a key alone (self-signed — issuer equals subject, signed with that key) or a name + public key + key, or an issuing certificate + key (CA-signed). The signature algorithm is resolved from the signing key through the shared registry, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA P-256/384/521, Ed25519, Ed448, ML-DSA-44/65/87, the twelve SLH-DSA sets, and the composite arms all issue without a per-algorithm branch. It encodes basic constraints, key usage, extended key usage, subject and authority key identifiers (the SKI auto-derived by SHA-1 of the subject key), subject alternative names, and certificate policies from the spec — any other extension supplied as pre-encoded DER — derives the version from the field set, and enforces the serial bounds, the UTCTime/GeneralizedTime cutover, the DER default omissions, and the CA cross-field rules; a violation throws a typed `CertificateError`. Returns DER, or a PEM `CERTIFICATE` with `opts.pem`; every arm is independently verified by OpenSSL. Parsing stays at `pki.schema.x509.parse` — `sign` |
 | `pki.csr` | PKCS#10 certification-request issuance (RFC 2986 / RFC 2985) — `sign(spec, key, opts)` builds and signs a `CertificationRequest`: a `spec` of subject (a common-name string, an array of RDNs, or raw Name DER; may be empty), the public key being certified, an optional `extensionRequest` (requested v3 extensions — subject alternative names, key usage, extended key usage, basic constraints, certificate policies, subject key identifier, or an array of pre-encoded Extension DER — that a CA copies into the issued certificate), and an optional `challengePassword`. `key` (or `{ key }`) is the subject's own private key: the request is self-signed to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the request is returned (what `openssl req -verify` checks). The signature algorithm is resolved from the subject key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. Returns DER, or a PEM `CERTIFICATE REQUEST` with `opts.pem`; malformed input throws a typed `CsrError`. Parsing stays at `pki.schema.csr.parse` — `sign` |
 | `pki.attrcert` | RFC 5755 attribute-certificate issuance — `sign(spec, issuer, opts)` builds and signs an `AttributeCertificate` as an Attribute Authority: a `spec` of `holder` (exactly one of an entity name, a `baseCertificateID` public-key-certificate reference, a `fromCertificate` binding derived from a certificate, or an object digest), the validity window (GeneralizedTime), an optional serial (positive, ≤ 20 octets; randomly generated when omitted), the `attributes` (the privilege syntaxes — role, clearance, group, chargingIdentity, accessIdentity, authenticationInfo — or pre-encoded Attribute DER), and optional `extensions` (auditIdentity, targetInformation, noRevAvail, aaControls, acProxying, authorityKeyIdentifier, or pre-encoded Extension DER, each with its RFC 5755 criticality). An attribute certificate is never self-signed — the `issuer` is the signing AA, supplied as `{ cert, key }` or `{ name, publicKey, key }`. The signature algorithm is resolved from the AA key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch, and the signature is verified under the AA public key before the certificate is returned. Returns DER, or a PEM `ATTRIBUTE CERTIFICATE` with `opts.pem`; malformed input throws a typed `AttrCertError`. Parsing stays at `pki.schema.attrcert.parse` — `sign` |
 | `pki.crmf` | RFC 4211 certificate-request-message issuance — `build(spec, key, opts)` assembles a `CertReqMessages`: a `spec` of `certReqId` (default 0; the RFC 9483 `-1` sentinel allowed), a `certTemplate` of the requested certificate fields (`subject`, `publicKey` — the SPKI DER of the key being certified — `validity`, requested `extensions`, an optional `version` 2), optional `controls` and `regInfo` (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 message carries a `POPOSigningKey` proof of possession signed with the private half of `certTemplate.publicKey` (verified before the message is returned), exactly as a PKCS#10 CSR proves possession; a complete template signs the `CertRequest`, an incomplete one signs a `POPOSigningKeyInput`. The signature algorithm is resolved from the requested public key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. `key` is optional for a `raVerified` proof. Pass an array of specs for a batch; the CA-assigned template fields are never emitted. Returns DER, or a PEM block with `opts.pem`; malformed input throws a typed `CrmfError`. Parsing stays at `pki.schema.crmf.parse` — `build` |
-| `pki.cmp` | RFC 9810 Certificate Management Protocol message building — `build(message, opts)` assembles a protected `PKIMessage`. `message.header` carries the `sender` / `recipient` GeneralNames (including the anonymous NULL-DN) plus optional transaction metadata (`transactionID`, `senderNonce` / `recipNonce`, `messageTime` as a GeneralizedTime, `senderKID` / `recipKID`, `freeText`, `generalInfo`); `message.body` is a single-key object naming the request or transaction arm — `ir` / `cr` / `kur` (a `CertReqMessages` spec delegated to `pki.crmf.build`), `p10cr` (a PKCS#10 `CertificationRequest`), `certConf`, `pollReq`, `genm`, or `rr`. Protection is exactly one of `opts.{ key, cert }` — a signature over the message under the sender key, the algorithm resolved from the signer certificate so RSA (PKCS#1 v1.5 / PSS), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch — or `opts.mac` — a PBMAC1 shared-secret HMAC (RFC 9481 / 9579, PBKDF2-derived). The protection covers the exact DER of the virtual `ProtectedPart` (the header and body) and is self-verified before the message is returned; the `protectionAlg` is derived, never caller-set, so the message the parser accepts is coherent by construction. Returns DER, or a PEM `CMP` block with `opts.pem`; malformed input throws a typed `CmpError`. Parsing stays at `pki.schema.cmp.parse` — `build` |
+| `pki.cmp` | RFC 9810 Certificate Management Protocol message building — `build(message, opts)` assembles a protected `PKIMessage`. `message.header` carries the `sender` / `recipient` GeneralNames (including the anonymous NULL-DN) plus optional transaction metadata (`transactionID`, `senderNonce` / `recipNonce`, `messageTime` as a GeneralizedTime, `senderKID` / `recipKID`, `freeText`, `generalInfo`); `message.body` is a single-key object naming the arm. Request-side: `ir` / `cr` / `kur` (a `CertReqMessages` spec delegated to `pki.crmf.build`), `p10cr` (a PKCS#10 `CertificationRequest`), `certConf`, `pollReq`, `genm`, `rr`. CA/responder-side: `ip` / `cp` / `kup` / `ccp` (a `CertRepMessage` — `caPubs` and `response` entries carrying a `PKIStatusInfo` and, under a granting status, a `certifiedKeyPair`), `rp` (revocation response), `genp`, `error`, `pollRep`, `krp` (key-recovery response), `pkiconf`. Protection is exactly one of `opts.{ key, cert }` — a signature over the message under the sender key, the algorithm resolved from the signer certificate so RSA (PKCS#1 v1.5 / PSS), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch — or `opts.mac` — a PBMAC1 shared-secret HMAC (RFC 9481 / 9579, PBKDF2-derived). The protection covers the exact DER of the virtual `ProtectedPart` (the header and body) and is self-verified before the message is returned; the `protectionAlg` is derived, never caller-set, so the message the parser accepts is coherent by construction. Returns DER, or a PEM `CMP` block with `opts.pem`; malformed input throws a typed `CmpError`. Parsing stays at `pki.schema.cmp.parse` — `build` |
 | `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA, the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814), and composite ML-DSA (pairing ML-DSA with a traditional RSA / ECDSA / EdDSA — accepted only when **both** components verify — draft-ietf-lamps-cms-composite-sigs)); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: when signed attributes are present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. **Content encryption** (RFC 5652/5083/5084/9629): `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData — recipients auto-dispatch off the certificate key to key-transport (RSAES-OAEP; v1.5 never emitted), key-agreement (ephemeral-static ECDH over P-256/384/521 with the X9.63 KDF, and X25519/X448 with HKDF), symmetric key-wrap, password (PBKDF2 + RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936) — one fresh content key wrapped for every recipient. `decrypt(input, keyMaterial, opts)` recovers the content through the matching arm and returns it with an `authenticated` flag; every secret-dependent failure collapses to one uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL / password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. **Compression** (RFC 3274): `compress(content, opts)` / `decompress(input, opts)` produce and consume a CompressedData (ZLIB, version 0, id-alg-zlibCompress); decompress bounds the uncompressed output at 16 MiB and stops before it is materialized, so a decompression bomb fails closed as `cms/decompress-too-large` — a size transform with no integrity/confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.smime` | RFC 8551 S/MIME message assembly, verification, encryption, and compression over the CMS layer — `sign(content, signers, opts)` wraps a MIME entity as a signed S/MIME message in either form: `multipart/signed` (clear-signed — the content stays readable in any MUA, a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`) or `application/pkcs7-mime; smime-type=signed-data` (opaque — the whole entity is a base64 CMS SignedData). The signed bytes are the entity's RFC 8551 §3.1.1 canonical form (CRLF line endings); `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies and a tampered part fails. `encrypt(content, recipients, opts)` envelopes a MIME entity as an opaque `application/pkcs7-mime` message and `decrypt(message, keyMaterial, opts)` opens one — `smime-type=authEnveloped-data` (AES-GCM, confidentiality and integrity, the default) or `smime-type=enveloped-data` (AES-CBC, confidentiality only, so `decrypt` reports `authenticated: false`, the §3.3 no-integrity caveat); the `smime-type` is derived from the CMS body, not the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt` — any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA signer and any RSA-OAEP / ECDH / X25519 / X448 / AES-KW / PBKDF2 / ML-KEM recipient carries through (algorithm-agnostic). Like `cms.verify`, `verify` returns the per-signer cryptographic verdict plus the recovered content; chaining a signer to a trust anchor is the caller's `pki.path.validate` step. `compress(content, opts)` / `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (RFC 8551 §3.6, RFC 3274) — a size transform with no integrity/confidentiality (§2.4.5), decompress bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. Bidirectionally interoperable with `openssl smime` / `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.tsp` | RFC 3161 Time-Stamp Protocol — `sign(messageImprint, tsa, opts)` produces a TimeStampToken: a CMS SignedData (over `pki.cms.sign`) whose content is a `TSTInfo` carrying the timestamped message imprint, the TSA policy, a serial number, and `genTime` (with optional accuracy / nonce / ordering), plus the RFC 3161 §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). `request` / `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq), `response` / `parseResponse` the TimeStampResp a TSA returns — a granted status wrapping a token, or a rejection with PKIStatus and failure info, the §2.4.2 status↔token coupling enforced in both directions. `verify(token, data, opts)` verifies a token fail-closed: the CMS signature over the exact signed bytes, the message imprint recomputed from the data, the TSTInfo content type, the ESSCertID(V2) binding to the TSA certificate, the §2.3 critical timeStamping-only extendedKeyUsage, the request nonce when used, and — with a trust anchor supplied — full certification-path validation of the TSA certificate at the token's `genTime`, returning `{ valid, genTime, serialNumber, tstInfo, … }` — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |
@@ -239,7 +239,7 @@ is callable today; nothing below is a stub.
 | `pki.sigstore` | Offline verifier for a Sigstore bundle — the exact artifact `npm publish --provenance` produces and the registry serves. `verifyBundle` composes five fail-closed legs against caller-pinned trust (Fulcio CA roots + Rekor log keys, never trusted from the bundle): the DSSE signature over its PAE preimage under the Fulcio leaf key; the ephemeral Fulcio certificate chain, validated as of the Rekor log time; the RFC 9162 inclusion proof folded to a Rekor-signed tree root; the log entry bound to this exact signature; and the in-toto SLSA subject digest the caller confirms against the published artifact. Zero runtime deps — reuses the X.509 parser, RFC 5280 path validator, and Merkle verifier; the net-new codecs are the DSSE PAE byte-builder and a fail-closed JSON reader. `pae`, `parseBundle`, `verifyBundle` |
 | `pki.inspect` | Human-readable certificate inspection — the pure-JS equivalent of `openssl x509 -text`. `certificate(pem \| der \| parsed)` renders a familiar OpenSSL-style report: version, serial, signature algorithm, issuer/subject distinguished names, validity, public-key details (curve or modulus size + the raw point/modulus), every decoded extension with its critical flag, and the signature. Built over the strict parser and the two-way OID registry, so it names extension and algorithm OIDs an OpenSSL build shows only as raw bytes. No OpenSSL dependency; the format is stable and OpenSSL-familiar rather than pinned to one OpenSSL version; a malformed extension falls back to a hex dump rather than throwing — `certificate` |
 | `pki.webauthn` | WebAuthn / passkey attestation verification — offline trust evaluation of a W3C WebAuthn (Level 3) attestation. `parseAttestationObject(bytes)` decodes the CBOR attestation object + authenticatorData + COSE credential key over the strict `pki.cbor` codec; `verify(attestationObject, clientDataHash, opts)` checks the attestation-statement signature and each format's structural bindings for **packed / tpm / android-key / apple / fido-u2f / none** — the x5c leaf key, the apple nonce, the tpm `certInfo` Name/`extraData` over the `pubArea`, the android `KeyDescription`, the fido-u2f `verificationData` — binding the credential public key to each attestation (via the signed authenticatorData for packed/fido-u2f, or a cert/`pubArea`-key equality check for android-key/apple/tpm) and enforcing each leaf's certificate requirements. The credential-key check covers the full WebAuthn COSE algorithm set — ES256/384/512, RS256/384/512, PS256, EdDSA (Ed25519), and the RFC 9864 fully-specified identifiers **ESP256/384/512, Ed25519, and Ed448** — validating the public-key point on its curve, rejecting the compressed EC point form, and enforcing a minimally-encoded DER ECDSA signature. A verifier, not a ceremony client; fail-closed with typed `webauthn/*` errors. Chaining the returned trust path to a pinned root (and aaguid→root via FIDO MDS) is the caller's step through `pki.path.validate` — `parseAttestationObject`, `verify` |
-| `pki.lint` | Certificate linting — the zlint / pkilint of JavaScript. `certificate(pem \| der \| parsed, opts)` walks a parsed certificate and emits graded, advisory findings — each with a stable id, a severity (`fatal` > `error` > `warn` > `notice`), a source, a spec-clause citation, and a message — against the RFC 5280 profile plus a representative CA/Browser Forum TLS BR subset (serial sign/size, validity ordering + the the SC081v3 reducing validity schedule, keyCertSign coherence, unknown critical extensions, empty-subject SAN, SKI/AKI presence, SAN required + CN-in-SAN, dNSName syntax, serverAuth EKU, weak keys). Unlike every other entry the DATA path never throws: hostile bytes return a `fatal` `lint/unparseable` finding (with the strict parser's code) so a whole directory lints without a try/catch; only config-time misuse throws a typed `LintError`. `certificate`, `rules`, `profiles` |
+| `pki.lint` | Certificate linting — the zlint / pkilint of JavaScript. `certificate(pem \| der \| parsed, opts)` walks a parsed certificate and emits graded, advisory findings — each with a stable id, a severity (`fatal` > `error` > `warn` > `notice`), a source, a spec-clause citation, and a message — against the RFC 5280 profile plus a representative CA/Browser Forum TLS BR subset (serial sign/size, validity ordering + the SC081v3 reducing validity schedule, keyCertSign coherence, extension criticality — basicConstraints/nameConstraints/policyConstraints/inhibitAnyPolicy must be critical and keyUsage should be, nameConstraints CA-scope, unknown critical extensions, empty-subject SAN, SKI/AKI presence including the end-entity subjectKeyIdentifier, SAN required + CN-in-SAN, dNSName syntax, serverAuth EKU, weak keys). Unlike every other entry the DATA path never throws: hostile bytes return a `fatal` `lint/unparseable` finding (with the strict parser's code) so a whole directory lints without a try/catch; only config-time misuse throws a typed `LintError`. `certificate`, `rules`, `profiles` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
 | `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError` / `LintError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>`, `pki inspect <cert>`, `pki lint <cert>`, `pki convert <file> --to der\|pem`, `pki verify <cert>... --anchor <cert>`, `pki sign <file> --cert <c> --key <k>` |

package/lib/cmp-build.js

@@ -32,6 +32,7 @@ var oid = require("./oid");
 var cmp = require("./schema-cmp");
 var crmf = require("./crmf-sign");
 var csr = require("./schema-csr");
+var crl = require("./schema-crl");
 var x509 = require("./schema-x509");
 var signScheme = require("./sign-scheme");
 var pkix = require("./schema-pkix");
@@ -58,10 +59,17 @@ var KNOWN_HEADER_KEYS = {
   sender: 1, recipient: 1, pvno: 1, messageTime: 1, senderKID: 1, recipKID: 1,
   transactionID: 1, senderNonce: 1, recipNonce: 1, freeText: 1, generalInfo: 1,
 };
-var KNOWN_BODY_KEYS = { ir: 1, cr: 1, kur: 1, p10cr: 1, certConf: 1, pollReq: 1, genm: 1, rr: 1 };
+var KNOWN_BODY_KEYS = {
+  ir: 1, cr: 1, kur: 1, p10cr: 1, certConf: 1, pollReq: 1, genm: 1, rr: 1,   // request-side
+  ip: 1, cp: 1, kup: 1, ccp: 1, krp: 1, rp: 1, genp: 1, error: 1, pollRep: 1, pkiconf: 1,   // CA/responder-side
+};
 // The PKIBody arm -> its EXPLICIT context tag number (schema-cmp.js BODY_ARMS). rr is [11], NOT [15].
-var BODY_TAG = { ir: 0, cr: 2, p10cr: 4, kur: 7, rr: 11, genm: 21, certConf: 24, pollReq: 25 };
+var BODY_TAG = {
+  ir: 0, cr: 2, p10cr: 4, kur: 7, rr: 11, genm: 21, certConf: 24, pollReq: 25,
+  ip: 1, cp: 3, kup: 8, krp: 10, rp: 12, ccp: 14, pkiconf: 19, genp: 22, error: 23, pollRep: 26,
+};
 var CRMF_BODY = { ir: 1, cr: 1, kur: 1 };   // arms whose content is a CertReqMessages via pki.crmf.build
+var CERT_REP_ARM = { ip: 1, cp: 1, kup: 1, ccp: 1 };   // arms carrying a CertRepMessage
 var KNOWN_OPTS_KEYS = { key: 1, cert: 1, mac: 1, extraCerts: 1, pem: 1, pss: 1, digestAlgorithm: 1 };
 var KNOWN_MAC_KEYS = { secret: 1, salt: 1, iterationCount: 1, prf: 1, keyLength: 1, algorithm: 1 };
 
@@ -186,20 +194,23 @@ function _reqIdInt(v, code, what) {
 }
 
 // PKIFailureInfo ::= BIT STRING (named bits, RFC 9810 sec. 5.2.3) -- a minimal NamedBitList from bit names.
-function _encodeFailInfo(names) {
-  if (!Array.isArray(names)) throw _err("cmp/bad-cert-status", "statusInfo.failInfo must be an array of PKIFailureInfo bit names");
+function _encodeFailInfo(names, code) {
+  if (!Array.isArray(names)) throw _err(code, "statusInfo.failInfo must be an array of PKIFailureInfo bit names");
   return b.namedBitString(names.map(function (n) {
-    if (typeof n !== "string" || FAIL_INFO_INDEX[n] === undefined) throw _err("cmp/bad-cert-status", "unknown PKIFailureInfo bit " + JSON.stringify(n));
+    if (typeof n !== "string" || FAIL_INFO_INDEX[n] === undefined) throw _err(code, "unknown PKIFailureInfo bit " + JSON.stringify(n));
     return FAIL_INFO_INDEX[n];
   }));
 }
 
-// PKIStatusInfo ::= SEQUENCE { status PKIStatus INTEGER, statusString PKIFreeText OPTIONAL, failInfo BIT STRING OPTIONAL }.
-function _encodePkiStatusInfo(si) {
-  if (typeof si.status !== "number" || !Number.isInteger(si.status)) throw _err("cmp/bad-cert-status", "statusInfo.status must be a PKIStatus integer");
+// PKIStatusInfo ::= SEQUENCE { status PKIStatus INTEGER, statusString PKIFreeText OPTIONAL, failInfo BIT STRING
+// OPTIONAL }. `code` is the caller's typed error (default cmp/bad-status-info; certConf passes cmp/bad-cert-status).
+function _encodePkiStatusInfo(si, code) {
+  code = code || "cmp/bad-status-info";
+  if (!si || typeof si !== "object" || Buffer.isBuffer(si)) throw _err(code, "a PKIStatusInfo must be an object { status, statusString?, failInfo? }");
+  if (typeof si.status !== "number" || !Number.isInteger(si.status) || si.status < 0 || si.status > 6) throw _err(code, "statusInfo.status must be a PKIStatus 0..6 (RFC 9810 sec. 5.2.3)");
   var children = [b.integer(BigInt(si.status))];
-  if (si.statusString != null) children.push(_encodePkiFreeText(si.statusString, "cmp/bad-cert-status", "statusInfo.statusString"));
-  if (si.failInfo != null) children.push(_encodeFailInfo(si.failInfo));   // strict order: status -> statusString -> failInfo (both optionals untagged)
+  if (si.statusString != null) children.push(_encodePkiFreeText(si.statusString, code, "statusInfo.statusString"));
+  if (si.failInfo != null) children.push(_encodeFailInfo(si.failInfo, code));   // strict order: status -> statusString -> failInfo (both optionals untagged)
   return b.sequence(children);
 }
 
@@ -211,7 +222,7 @@ function _encodeCertStatus(cs, state) {
     _reqOctets(cs.certHash, "certConf certHash"),
     b.integer(_reqIdInt(cs.certReqId, "cmp/bad-cert-status", "CertStatus certReqId")),   // signed, -1 legal, unbounded
   ];
-  if (cs.statusInfo != null) children.push(_encodePkiStatusInfo(cs.statusInfo));
+  if (cs.statusInfo != null) children.push(_encodePkiStatusInfo(cs.statusInfo, "cmp/bad-cert-status"));
   if (cs.hashAlg != null) {
     if (typeof cs.hashAlg !== "string" || !CERT_CONF_HASH_ALGS[cs.hashAlg]) throw _err("cmp/bad-name", "certConf hashAlg must be a hash algorithm (sha256 / sha384 / sha512 / sha3-256 / sha3-512 / sha1); got " + JSON.stringify(cs.hashAlg));
     children.push(b.explicit(0, _algIdNoParams(cs.hashAlg)));
@@ -264,6 +275,146 @@ function _encodeRevReqContent(list) {
   return b.sequence(list.map(_encodeRevDetails));
 }
 
+// ---- response-side (CA/responder) PKIBody arm content encoders ----
+
+// CertOrEncCert ::= CHOICE { certificate [0] EXPLICIT CMPCertificate, encryptedCert [1] EXPLICIT EncryptedKey }.
+function _encodeCertOrEncCert(coec, state) {
+  if (!coec || typeof coec !== "object" || Buffer.isBuffer(coec)) throw _err("cmp/bad-cert-response", "certifiedKeyPair must carry certificate or encryptedCert");
+  if (coec.certificate != null && coec.encryptedCert != null) throw _err("cmp/bad-cert-response", "certOrEncCert is a CHOICE: supply exactly one of certificate or encryptedCert, not both");
+  if (coec.certificate != null) {
+    var certDer = _b.reqDer(coec.certificate, "certifiedKeyPair.certificate (a Certificate DER)");
+    try { x509.parse(certDer); } catch (e) { if (e instanceof CmpError) throw e; throw _err("cmp/bad-cert-response", "certifiedKeyPair.certificate is not a valid X.509 certificate", e); }
+    return b.explicit(0, b.raw(certDer));   // certificate [0] EXPLICIT
+  }
+  if (coec.encryptedCert != null) {
+    // encryptedCert [1] wraps an EncryptedKey (pre-encoded DER hatch in v1). Like the privateKey, only the
+    // EnvelopedData [0] form is cmp2021 -- the deprecated EncryptedValue (a universal SEQUENCE) is cmp2000.
+    var ec = _b.reqDer(coec.encryptedCert, "certifiedKeyPair.encryptedCert (a pre-encoded EncryptedKey DER)");
+    var ecNode;
+    try { ecNode = asn1.decode(ec); } catch (e) { throw _err("cmp/bad-cert-response", "certifiedKeyPair.encryptedCert is not valid DER", e); }
+    if (ecNode.tagClass === "context" && ecNode.tagNumber === 0) state.usesCmp2021 = true;
+    return b.explicit(1, b.raw(ec));
+  }
+  throw _err("cmp/bad-cert-response", "certifiedKeyPair must carry certificate or encryptedCert");
+}
+
+// CertifiedKeyPair ::= SEQUENCE { certOrEncCert, privateKey [0] EXPLICIT OPTIONAL, publicationInfo [1] EXPLICIT OPTIONAL }.
+function _encodeCertifiedKeyPair(ckp, state) {
+  if (!ckp || typeof ckp !== "object" || Buffer.isBuffer(ckp)) throw _err("cmp/bad-cert-response", "certifiedKeyPair must be an object");
+  var children = [_encodeCertOrEncCert(ckp, state)];   // certificate / encryptedCert are direct keys (the parse-result shape)
+  if (ckp.privateKey != null) {
+    var pk = _b.reqDer(ckp.privateKey, "certifiedKeyPair.privateKey (a pre-encoded EncryptedKey DER)");
+    children.push(b.explicit(0, b.raw(pk)));
+    // EncryptedKey ::= CHOICE { encryptedValue EncryptedValue (a universal SEQUENCE, the deprecated cmp2000
+    // form), envelopedData [0] (a cmp2021 feature). Only the envelopedData form bumps pvno to cmp2021(3).
+    var pkNode;
+    try { pkNode = asn1.decode(pk); } catch (e) { throw _err("cmp/bad-cert-response", "certifiedKeyPair.privateKey is not valid DER", e); }
+    if (pkNode.tagClass === "context" && pkNode.tagNumber === 0) state.usesCmp2021 = true;
+  }
+  if (ckp.publicationInfo != null) children.push(b.explicit(1, b.raw(_b.reqDer(ckp.publicationInfo, "certifiedKeyPair.publicationInfo (a pre-encoded DER)"))));
+  return b.sequence(children);
+}
+
+// CertResponse ::= SEQUENCE { certReqId INTEGER, status PKIStatusInfo, certifiedKeyPair OPTIONAL, rspInfo OCTET STRING OPTIONAL }.
+function _encodeCertResponse(cr, state) {
+  if (!cr || typeof cr !== "object" || Buffer.isBuffer(cr)) throw _err("cmp/bad-cert-response", "each CertResponse must be an object");
+  if (cr.status == null) throw _err("cmp/bad-cert-response", "CertResponse.status (a PKIStatusInfo) is required");
+  var hasCkp = cr.certifiedKeyPair != null;
+  // RFC 9810 sec. 5.3.4: failInfo XOR certifiedKeyPair; a certifiedKeyPair is allowed only under a granting
+  // status (accepted 0 / grantedWithMods 1).
+  if (hasCkp && cr.status.failInfo != null) throw _err("cmp/bad-cert-response", "a CertResponse must not carry both failInfo and certifiedKeyPair");
+  if (hasCkp && cr.status.status !== 0 && cr.status.status !== 1) throw _err("cmp/bad-cert-response", "a CertResponse certifiedKeyPair is allowed only under a granting status (accepted / grantedWithMods)");
+  var children = [b.integer(_reqIdInt(cr.certReqId, "cmp/bad-cert-response", "CertResponse certReqId")), _encodePkiStatusInfo(cr.status, "cmp/bad-cert-response")];
+  if (hasCkp) children.push(_encodeCertifiedKeyPair(cr.certifiedKeyPair, state));
+  if (cr.rspInfo != null) children.push(_reqOctets(cr.rspInfo, "CertResponse.rspInfo"));
+  return b.sequence(children);
+}
+
+// CertRepMessage ::= SEQUENCE { caPubs [1] EXPLICIT SEQUENCE OF CMPCertificate OPTIONAL, response SEQUENCE OF CertResponse }.
+function _encodeCertRepMessage(spec, state, arm) {
+  if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("cmp/bad-cert-rep", arm + " must be an object { caPubs?, response }");
+  if (!Array.isArray(spec.response)) throw _err("cmp/bad-cert-rep", arm + ".response must be an array of CertResponse");
+  if (arm === "ccp" && spec.response.length !== 1) throw _err("cmp/bad-cert-rep", "a ccp CertRepMessage carries exactly one CertResponse (RFC 9810 App. D)");
+  var children = [];
+  if (spec.caPubs != null) {   // caPubs [1] PRECEDES response (the optional-first x509-version shape)
+    if (!Array.isArray(spec.caPubs) || !spec.caPubs.length) throw _err("cmp/bad-cert-rep", arm + ".caPubs must be a non-empty array of certificate DERs");
+    children.push(b.explicit(1, b.sequence(spec.caPubs.map(function (c) { return _certRaw(c, "cmp/bad-cert-rep", "a caPubs entry"); }))));
+  }
+  children.push(b.sequence(spec.response.map(function (cr) { return _encodeCertResponse(cr, state); })));
+  return b.sequence(children);
+}
+
+// A raw Certificate DER, validated via the real parser before it is embedded.
+function _certRaw(c, code, what) {
+  var der = _b.reqDer(c, what + " (a Certificate DER)");
+  try { x509.parse(der); } catch (e) { if (e instanceof CmpError) throw e; throw _err(code, what + " is not a valid X.509 certificate", e); }
+  return b.raw(der);
+}
+
+// RevRepContent ::= SEQUENCE { status SEQ OF PKIStatusInfo (min 1), revCerts [0] EXPLICIT SEQ OF CertId OPTIONAL, crls [1] EXPLICIT SEQ OF CertificateList OPTIONAL }.
+function _encodeCertIdRr(cid) {
+  if (!cid || typeof cid !== "object" || Buffer.isBuffer(cid) || cid.issuer == null || cid.serialNumber == null) throw _err("cmp/bad-rev-rep", "each revCerts CertId must be { issuer, serialNumber }");
+  return b.sequence([_b.encodeGeneralName(cid.issuer), b.integer(_reqIdInt(cid.serialNumber, "cmp/bad-rev-rep", "CertId serialNumber"))]);
+}
+function _encodeRevRepContent(spec) {
+  if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("cmp/bad-rev-rep", "rp must be an object { status, revCerts?, crls? }");
+  if (!Array.isArray(spec.status) || !spec.status.length) throw _err("cmp/bad-rev-rep", "rp.status must be a non-empty array of PKIStatusInfo");
+  var children = [b.sequence(spec.status.map(function (si) { return _encodePkiStatusInfo(si, "cmp/bad-rev-rep"); }))];
+  if (spec.revCerts != null) {
+    if (!Array.isArray(spec.revCerts) || !spec.revCerts.length) throw _err("cmp/bad-rev-rep", "rp.revCerts must be a non-empty array of CertId");
+    children.push(b.explicit(0, b.sequence(spec.revCerts.map(_encodeCertIdRr))));
+  }
+  if (spec.crls != null) {
+    if (!Array.isArray(spec.crls) || !spec.crls.length) throw _err("cmp/bad-rev-rep", "rp.crls must be a non-empty array of CertificateList DERs");
+    children.push(b.explicit(1, b.sequence(spec.crls.map(function (c) {
+      var der = _b.reqDer(c, "crls entry (a CertificateList DER)");
+      try { crl.parse(der); }   // each crls entry MUST be a valid X.509 CRL (CertificateList)
+      catch (e) { if (e instanceof CmpError) throw e; throw _err("cmp/bad-rev-rep", "a crls entry is not a valid CRL (CertificateList)", e); }
+      return b.raw(der);
+    }))));
+  }
+  return b.sequence(children);
+}
+
+// ErrorMsgContent ::= SEQUENCE { pKIStatusInfo, errorCode INTEGER OPTIONAL, errorDetails PKIFreeText OPTIONAL }.
+function _encodeErrorMsgContent(spec) {
+  if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("cmp/bad-error", "error must be an object { pKIStatusInfo, errorCode?, errorDetails? }");
+  if (spec.pKIStatusInfo == null) throw _err("cmp/bad-error", "error.pKIStatusInfo is required");
+  var children = [_encodePkiStatusInfo(spec.pKIStatusInfo, "cmp/bad-error")];
+  if (spec.errorCode != null) children.push(b.integer(_reqIdInt(spec.errorCode, "cmp/bad-error", "error.errorCode")));
+  if (spec.errorDetails != null) children.push(_encodePkiFreeText(spec.errorDetails, "cmp/bad-error", "error.errorDetails"));
+  return b.sequence(children);
+}
+
+// PollRepContent ::= SEQUENCE OF SEQUENCE { certReqId INTEGER, checkAfter INTEGER (seconds, >= 0), reason PKIFreeText OPTIONAL }.
+function _encodePollRepContent(list) {
+  if (!Array.isArray(list) || !list.length) throw _err("cmp/bad-poll-rep", "pollRep must be a non-empty array of { certReqId, checkAfter, reason? }");
+  return b.sequence(list.map(function (pr) {
+    if (!pr || typeof pr !== "object" || Buffer.isBuffer(pr)) throw _err("cmp/bad-poll-rep", "each pollRep entry must be an object");
+    if (typeof pr.checkAfter !== "number" || !Number.isInteger(pr.checkAfter) || pr.checkAfter < 0 || pr.checkAfter > 0x7fffffff) throw _err("cmp/bad-poll-rep", "pollRep checkAfter must be a non-negative uint31 delay in seconds (RFC 9810 sec. 5.3.22)");
+    var kids = [b.integer(_reqIdInt(pr.certReqId, "cmp/bad-poll-rep", "pollRep certReqId")), b.integer(BigInt(pr.checkAfter))];
+    if (pr.reason != null) kids.push(_encodePkiFreeText(pr.reason, "cmp/bad-poll-rep", "pollRep reason"));
+    return b.sequence(kids);
+  }));
+}
+
+// KeyRecRepContent ::= SEQUENCE { status PKIStatusInfo, newSigCert [0] EXPLICIT CMPCertificate OPTIONAL, caCerts [1] EXPLICIT SEQ OF CMPCertificate OPTIONAL, keyPairHist [2] EXPLICIT SEQ OF CertifiedKeyPair OPTIONAL }.
+function _encodeKeyRecRepContent(spec, state) {
+  if (!spec || typeof spec !== "object" || Buffer.isBuffer(spec)) throw _err("cmp/bad-key-rec-rep", "krp must be an object { status, newSigCert?, caCerts?, keyPairHist? }");
+  if (spec.status == null) throw _err("cmp/bad-key-rec-rep", "krp.status is required");
+  var children = [_encodePkiStatusInfo(spec.status, "cmp/bad-key-rec-rep")];
+  if (spec.newSigCert != null) children.push(b.explicit(0, _certRaw(spec.newSigCert, "cmp/bad-key-rec-rep", "krp.newSigCert")));
+  if (spec.caCerts != null) {
+    if (!Array.isArray(spec.caCerts) || !spec.caCerts.length) throw _err("cmp/bad-key-rec-rep", "krp.caCerts must be a non-empty array of certificate DERs");
+    children.push(b.explicit(1, b.sequence(spec.caCerts.map(function (c) { return _certRaw(c, "cmp/bad-key-rec-rep", "a krp.caCerts entry"); }))));
+  }
+  if (spec.keyPairHist != null) {
+    if (!Array.isArray(spec.keyPairHist) || !spec.keyPairHist.length) throw _err("cmp/bad-key-rec-rep", "krp.keyPairHist must be a non-empty array of CertifiedKeyPair");
+    children.push(b.explicit(2, b.sequence(spec.keyPairHist.map(function (ckp) { return _encodeCertifiedKeyPair(ckp, state); }))));
+  }
+  return b.sequence(children);
+}
+
 // Dispatch the single-key body object to its EXPLICIT-tagged arm. Returns { bodyTLV, usesCmp2021 }.
 function _encodeBody(bodySpec, key, opts) {
   if (!bodySpec || typeof bodySpec !== "object" || Buffer.isBuffer(bodySpec)) throw _err("cmp/bad-input", "message.body must be a single-key object");
@@ -299,8 +450,23 @@ function _encodeBody(bodySpec, key, opts) {
     inner = _encodePollReqContent(bodySpec.pollReq);
   } else if (arm === "genm") {
     inner = _encodeGenMsgContent(bodySpec.genm);
-  } else {   // rr
+  } else if (arm === "rr") {
     inner = _encodeRevReqContent(bodySpec.rr);
+  } else if (CERT_REP_ARM[arm]) {   // ip / cp / kup / ccp -- CertRepMessage
+    inner = _encodeCertRepMessage(bodySpec[arm], state, arm);
+  } else if (arm === "rp") {
+    inner = _encodeRevRepContent(bodySpec.rp);
+  } else if (arm === "genp") {   // GenRepContent == GenMsgContent
+    inner = _encodeGenMsgContent(bodySpec.genp);
+  } else if (arm === "error") {
+    inner = _encodeErrorMsgContent(bodySpec.error);
+  } else if (arm === "pollRep") {
+    inner = _encodePollRepContent(bodySpec.pollRep);
+  } else if (arm === "krp") {
+    inner = _encodeKeyRecRepContent(bodySpec.krp, state);
+  } else {   // pkiconf -- PKIConfirmContent ::= NULL
+    if (bodySpec.pkiconf !== null && bodySpec.pkiconf !== true) throw _err("cmp/bad-input", "pkiconf takes null or true (PKIConfirmContent is NULL)");
+    inner = b.nullValue();
   }
   return Promise.resolve({ bodyTLV: b.explicit(tag, inner), usesCmp2021: state.usesCmp2021 });
 }
@@ -463,9 +629,13 @@ function _collectExtraCerts(opts, protCertDer) {
  * Build an RFC 9810 CMP `PKIMessage` -- the producing-side inverse of `pki.schema.cmp.parse`. `message` is
  * `{ header, body }`: `header` carries the `sender` / `recipient` GeneralNames plus optional transaction
  * metadata (`transactionID`, `senderNonce`, `messageTime`, `freeText`, `generalInfo`, ...); `body` is a
- * single-key object naming the request or transaction arm -- `{ ir }` / `{ cr }` / `{ kur }` (a
- * `CertReqMessages` spec delegated to `pki.crmf.build`), `{ p10cr }` (a PKCS#10 CertificationRequest DER),
- * `{ certConf }`, `{ pollReq }`, `{ genm }`, or `{ rr }`. The message is protected: `opts` carries EXACTLY
+ * single-key object naming the arm. Request-side: `{ ir }` / `{ cr }` / `{ kur }` (a `CertReqMessages` spec
+ * delegated to `pki.crmf.build`; the proof-of-possession key is `key` on the arm spec), `{ p10cr }` (a PKCS#10
+ * CertificationRequest DER), `{ certConf }`, `{ pollReq }`, `{ genm }`, `{ rr }`. CA/responder-side: `{ ip }` /
+ * `{ cp }` / `{ kup }` / `{ ccp }` (a `CertRepMessage` -- `caPubs` + `response` of `CertResponse` each with a
+ * `PKIStatusInfo` and, under a granting status, a `certifiedKeyPair`), `{ rp }` (`RevRepContent`), `{ genp }`,
+ * `{ error }` (`ErrorMsgContent`), `{ pollRep }`, `{ krp }` (`KeyRecRepContent`), `{ pkiconf }` (NULL). The
+ * message is protected: `opts` carries EXACTLY
  * ONE of `{ key, cert }` (a signature under the sender key over the message -- any registry algorithm, RSA
  * / ECDSA / EdDSA / ML-DSA / SLH-DSA / composite, resolved from the certificate) or `{ mac }` (a PBMAC1
  * shared-secret MAC). The protection is computed over the exact DER of the virtual

package/lib/constants.js

@@ -204,6 +204,17 @@ var LIMITS = {
   // chain's tree holds a handful of nodes; the operator may override via
   // opts.maxPolicyNodes.
   PATH_MAX_POLICY_NODES: 4096,
+  // Certification-path BUILDING bounds (pki.path.build). The pool of candidate
+  // issuers is untrusted, so a cross-certificate cycle or Bridge-CA fan-out can
+  // grow the number and length of candidate paths without bound (RFC 4158 sec.
+  // 8.1). PATH_BUILD_MAX_DEPTH caps the chain length explored from the leaf --
+  // well under PATH_MAX_CERTS so a built path clears the validator's own bound
+  // on hand-off; a real hierarchy is a handful of hops. PATH_BUILD_MAX_CANDIDATES
+  // is the total-work ceiling: the builder ticks it once per candidate-issuer
+  // expansion, so a hostile mesh terminates deterministically. Both are operator
+  // overridable (opts.maxDepth / opts.maxCandidatesConsidered).
+  PATH_BUILD_MAX_DEPTH: 20,
+  PATH_BUILD_MAX_CANDIDATES: 1000,
   // PKCS#12 container ceilings. A PFX carries lists at three altitudes
   // (ContentInfos per AuthenticatedSafe, SafeBags per SafeContents,
   // attributes per bag) and can chain fresh DER blobs inside OCTET STRINGs,

package/lib/lint.js

@@ -297,6 +297,18 @@ function _ecCurveName(spki) {
   } catch (_e) { return null; }   // explicit / invalid EC parameters are not an approved named curve
 }
 
+// RFC 5280 marks several extensions MUST (error) or SHOULD (warn) be critical. The shape is
+// uniform: applies when the extension is present, fires when its raw `critical` flag is not
+// true. The rule reads `ctx.raw(name).critical` WITHOUT decoding the value -- criticality is
+// a structural property of the extension, independent of its contents.
+function _criticalityRule(name, id, severity, citation, message) {
+  return {
+    id: id, severity: severity, source: "rfc5280", citation: citation, message: message,
+    appliesTo: function (cert, ctx) { return !!ctx.raw(name); },
+    check: function (cert, ctx) { var e = ctx.raw(name); return (e && e.critical !== true) ? true : null; },
+  };
+}
+
 var RFC5280_RULES = [
   {
     id: "lint/rfc5280/serial-not-positive", severity: "error", source: "rfc5280", citation: "RFC 5280 4.1.2.2",
@@ -379,6 +391,51 @@ var RFC5280_RULES = [
     appliesTo: function (cert) { return !!(cert.issuer && cert.subject && cert.issuer.dn !== cert.subject.dn); },
     check: function (cert, ctx) { return ctx.raw("authorityKeyIdentifier") ? null : true; },
   },
+  {
+    // 4.2.1.9: MUST mark basicConstraints critical "in all CA certificates that contain
+    // public keys used to validate digital signatures on certificates" (keyCertSign). A CA
+    // key used exclusively for other purposes (CRL signing, key management) MAY carry a
+    // non-critical basicConstraints, so the rule applies only when keyCertSign is asserted
+    // (or keyUsage is absent) -- gating on cA alone would false-positive on a CRL-signing CA.
+    id: "lint/rfc5280/basic-constraints-not-critical", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.9",
+    message: "a CA certificate that validates certificate signatures must mark basicConstraints critical",
+    appliesTo: function (cert, ctx) {
+      var bc = ctx.decode("basicConstraints");
+      if (!(bc && bc.value && bc.value.cA === true)) return false;
+      var ku = ctx.decode("keyUsage");
+      return !ku || !ku.value || ku.value.keyCertSign === true;
+    },
+    check: function (cert, ctx) { var e = ctx.raw("basicConstraints"); return (e && e.critical !== true) ? true : null; },
+  },
+  _criticalityRule("nameConstraints", "lint/rfc5280/name-constraints-not-critical", "error",
+    "RFC 5280 4.2.1.10", "the nameConstraints extension must be marked critical"),
+  {
+    // 4.2.1.10: "The name constraints extension ... MUST be used only in a CA certificate."
+    id: "lint/rfc5280/name-constraints-not-ca", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.10",
+    message: "the nameConstraints extension must appear only in a CA certificate",
+    appliesTo: function (cert, ctx) { return !!ctx.raw("nameConstraints"); },
+    check: function (cert, ctx) { var bc = ctx.decode("basicConstraints"); return (bc && bc.value && bc.value.cA === true) ? null : true; },
+  },
+  _criticalityRule("policyConstraints", "lint/rfc5280/policy-constraints-not-critical", "error",
+    "RFC 5280 4.2.1.11", "the policyConstraints extension must be marked critical"),
+  _criticalityRule("inhibitAnyPolicy", "lint/rfc5280/inhibit-any-policy-not-critical", "error",
+    "RFC 5280 4.2.1.14", "the inhibitAnyPolicy extension must be marked critical"),
+  // 4.2.1.3: "When present, conforming CAs SHOULD mark this extension as critical." The
+  // recommendation directs the ISSUING CA whenever it includes keyUsage -- in ANY certificate,
+  // including an end-entity leaf -- and does NOT restrict it to certificates whose subject is
+  // itself a CA. So the rule is present-gated (matching zlint's w_ext_key_usage_not_critical),
+  // not CA-subject-gated; a SHOULD, hence warn.
+  _criticalityRule("keyUsage", "lint/rfc5280/key-usage-not-critical", "warn",
+    "RFC 5280 4.2.1.3", "the keyUsage extension should be marked critical"),
+  {
+    // 4.2.1.2: the SKI "SHOULD be included in all end entity certificates" (a SHOULD -> notice).
+    // The CA case is the separate ski-missing rule; this rule gates on the non-CA (leaf) path so
+    // the two are mutually exclusive and every certificate is covered by exactly one.
+    id: "lint/rfc5280/ski-missing-ee", severity: "notice", source: "rfc5280", citation: "RFC 5280 4.2.1.2",
+    message: "an end-entity certificate should carry a subjectKeyIdentifier extension",
+    appliesTo: function (cert, ctx) { var bc = ctx.decode("basicConstraints"); return !(bc && bc.value && bc.value.cA === true); },
+    check: function (cert, ctx) { return ctx.raw("subjectKeyIdentifier") ? null : true; },
+  },
 ];
 
 function _isTls(cert, ctx) { return ctx.isTlsServerCert; }

package/lib/path-validate.js

@@ -75,6 +75,8 @@ var OID = {
   extKeyUsage: oid.byName("extKeyUsage"),
   anyExtendedKeyUsage: oid.byName("anyExtendedKeyUsage"),
   cRLDistributionPoints: oid.byName("cRLDistributionPoints"),
+  subjectKeyIdentifier: oid.byName("subjectKeyIdentifier"),
+  authorityKeyIdentifier: oid.byName("authorityKeyIdentifier"),
 };
 
 // The set of extension OIDs the validator PROCESSES -- an unrecognized critical
@@ -2024,8 +2026,300 @@ function verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts) {
   });
 }
 
+// ---- certification path BUILDING (pki.path.build, RFC 4158) ----------------
+
+// A soft extension decode for the RFC 4158 sec. 3.5 SORT hints (AKI/SKI/
+// basicConstraints/keyUsage): a present-but-undecodable extension on an
+// UNTRUSTED pool candidate degrades to "no hint", never a hard fail -- the sort
+// weight is advisory, the branch is still tried, and validate is the authority.
+function softDecode(cert, extOid) {
+  try { return decodeExt(cert, extOid); }
+  catch (_e) { return null; }
+}
+
+// dnEqual that fails a control-byte DN (CVE-2009-2408) closed to "not a match"
+// rather than rejecting the whole build -- one malformed pool cert must not
+// poison a buildable path (parity with selfIssued's swallow). The hard
+// name-chaining gate remains validate's own dnEqual over the chosen path.
+function nameMatchSoft(rdnsA, rdnsB) {
+  try { return dnEqual(rdnsA, rdnsB); }
+  catch (_e) { return false; }
+}
+
+// A parsed extension entry the search's findExt dereferences by .oid and, for
+// the subjectAltName, by .value (a Buffer in the identity key).
+function _isExtensionEntry(e) { return !!e && typeof e.oid === "string" && Buffer.isBuffer(e.value); }
+
+// The complete parsed-certificate shape build produces AND hands to validate --
+// every top-level field this module dereferences (grep-verified), each with the
+// type the code assumes. A claimed-parsed object satisfying this cannot throw a
+// raw TypeError anywhere in the search or the validate hand-off.
+function _isParsedCert(o) {
+  return Buffer.isBuffer(o.tbsBytes) &&
+    typeof o.serialNumberHex === "string" &&
+    !!o.signatureAlgorithm && typeof o.signatureAlgorithm.oid === "string" &&
+    !!o.signatureValue && Buffer.isBuffer(o.signatureValue.bytes) &&
+    !!o.validity && o.validity.notBefore instanceof Date && o.validity.notAfter instanceof Date &&
+    !!o.issuer && Array.isArray(o.issuer.rdns) &&
+    !!o.subject && Array.isArray(o.subject.rdns) && Buffer.isBuffer(o.subject.bytes) &&
+    !!o.subjectPublicKeyInfo && Buffer.isBuffer(o.subjectPublicKeyInfo.bytes) &&
+    !!o.subjectPublicKeyInfo.algorithm && typeof o.subjectPublicKeyInfo.algorithm.oid === "string" &&
+    !!o.subjectPublicKeyInfo.publicKey && Buffer.isBuffer(o.subjectPublicKeyInfo.publicKey.bytes) &&
+    typeof o.subjectPublicKeyInfo.publicKey.unusedBits === "number" &&
+    Array.isArray(o.extensions) && o.extensions.every(_isExtensionEntry);
+}
+
+function coerceCert(input) {
+  // An already-parsed certificate is passed through; a DER Buffer / PEM string is
+  // parsed (and its typed error normalized by the caller). A claimed-parsed object
+  // (a truthy tbsBytes) must carry the COMPLETE parsed-certificate shape build and
+  // the validate hand-off dereference -- a bare { tbsBytes } object, or any partial
+  // shape, fails closed here as a typed PathError rather than a raw TypeError deeper
+  // in the walk or inside validate.
+  if (input && typeof input === "object" && !Buffer.isBuffer(input) && input.tbsBytes !== undefined) {
+    if (!_isParsedCert(input)) throw E("path/bad-input", "build: an input has tbsBytes but is not a well-formed parsed certificate");
+    return input;
+  }
+  return x509.parse(input);
+}
+
+// A trust-store entry is either a ready anchor tuple { name, publicKey,
+// algorithm, parameters? } or a self-signed root certificate reduced to that
+// tuple. The algorithm is the SPKI KEY-algorithm OID (the sec. 6.1.4(f)
+// parameter-inheritance value), mirroring trust.js _mkAnchor -- NOT the
+// signature OID. The anchor is an input to validate, never one of the path certs.
+function toAnchor(entry) {
+  if (entry && typeof entry === "object" && !Buffer.isBuffer(entry) && entry.name && entry.publicKey && entry.algorithm) {
+    // A ready anchor tuple: validate the shape build + validate consume -- name.rdns
+    // (name matching), publicKey bytes and the algorithm OID (the sec. 6.1.4 key
+    // hand-off). trustAnchors is a caller option, so a malformed tuple is a config
+    // error and fails closed at entry, not a downstream no-path / soft verdict.
+    if (!Array.isArray(entry.name.rdns) || !Buffer.isBuffer(entry.publicKey) || typeof entry.algorithm !== "string") {
+      throw E("path/bad-input", "build: a trustAnchor tuple must be { name: { rdns: [...] }, publicKey: Buffer, algorithm: OID string }");
+    }
+    return entry;
+  }
+  var cert;
+  try { cert = coerceCert(entry); }
+  catch (e) { throw E("path/bad-input", "build: a trustAnchor entry must be a { name, publicKey, algorithm } tuple or a certificate", e); }
+  var spki = cert.subjectPublicKeyInfo;
+  return { name: cert.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters, subjectDer: cert.subject.bytes };
+}
+
+// RFC 4158 sec. 2.4.2 loop key: the (subject DN + subjectAltName + subject
+// public key) tuple, NOT the DN alone. DN-alone keying wrongly prunes a
+// legitimate distinct cross-cert (cross-certs share a DN) and misses a same-key
+// loop; the key differentiates a rollover (same DN, new key) from a true repeat.
+function identityKey(cert) {
+  var san = findExt(cert, OID.subjectAltName);
+  return cert.subject.bytes.toString("hex") + "|" + (san ? san.value.toString("hex") : "") + "|" +
+    cert.subjectPublicKeyInfo.bytes.toString("hex");
+}
+
+function childAkiKeyId(cert) {
+  var d = softDecode(cert, OID.authorityKeyIdentifier);
+  return (d && d.value && d.value.keyIdentifier) ? d.value.keyIdentifier : null;
+}
+
+// RFC 4158 sec. 3.5 candidate prioritization -- a SORT weight, never a gate.
+// Higher = tried first (fewer validate calls to reach a valid path). Every term
+// is a hint: a KID match, an anchor-adjacent issuer, CA + keyCertSign presence,
+// and validity at the check time all raise priority, but a lower-scoring
+// candidate is STILL attempted, and validate makes every accept decision.
+function scoreCandidate(cand, childAki, anchors, time) {
+  var score = 0;
+  if (childAki) {
+    var d = softDecode(cand, OID.subjectKeyIdentifier);
+    if (d && Buffer.isBuffer(d.value) && d.value.equals(childAki)) score += 1000;   // sec. 3.5.12 KID match: heaviest
+  }
+  for (var i = 0; i < anchors.length; i++) {
+    if (nameMatchSoft(cand.issuer.rdns, anchors[i].name.rdns)) { score += 100; break; }   // sec. 3.5.15/.16 anchor-adjacent
+  }
+  var bc = softDecode(cand, OID.basicConstraints);
+  if (bc && bc.value && bc.value.cA === true) score += 10;                          // sec. 3.5.1 basicConstraints cA
+  var ku = softDecode(cand, OID.keyUsage);
+  if (ku && ku.value && ku.value.keyCertSign === true) score += 10;                 // sec. 3.5.3 keyUsage keyCertSign
+  var v = cand.validity;
+  // allow:nan-date-comparison-unguarded -- cand.validity dates are codec-parsed (asn1 readTime rejects a NaN instant) and time is guard.time.assertValid'd at entry; the validity term is a fail-safe sort hint regardless.
+  if (v && v.notBefore instanceof Date && v.notAfter instanceof Date &&
+    v.notBefore.getTime() <= time.getTime() && time.getTime() <= v.notAfter.getTime()) score += 5;   // sec. 3.5.4 validity
+  return score;
+}
+
+/**
+ * @primitive  pki.path.build
+ * @signature  pki.path.build(leaf, opts) -> Promise<{ valid, path, trustAnchor, result, candidatesConsidered }>
+ * @since       0.3.7
+ * @status      experimental
+ * @spec        RFC 4158, RFC 5280
+ * @related     pki.path.validate, pki.schema.x509.parse, pki.trust.parseCertdata
+ *
+ * Discover the ordered certification path from a leaf certificate up to a trust anchor, over an
+ * untrusted pool of candidate CA certificates, then validate it. `build` is the discovering
+ * complement of `validate`: `validate` takes an already-ordered path and a trust anchor and runs
+ * the 6.1 state machine; `build` takes a leaf, an unordered pool of candidate issuers, and a
+ * trust store, and searches for the ordered leaf->anchor path `validate` accepts.
+ *
+ * Candidate issuers are matched by RFC 5280 7.1 name chaining, prioritized by the RFC 4158 3.5
+ * heuristics (a subjectKeyIdentifier/authorityKeyIdentifier match, an anchor-adjacent issuer,
+ * CA + keyCertSign, validity at the check time -- all hints, never filters), and searched
+ * depth-first with backtracking: the first ordered path that `pki.path.validate` accepts wins. A
+ * name or key-identifier match is only an ordering hint; every accept flows through `validate`,
+ * so `build` never weakens or duplicates a 6.1 check. The search over the untrusted pool is
+ * bounded -- a depth cap on chain length, a total-work cap on candidate expansions, and a
+ * visited-set keyed on the (subject, subjectAltName, public key) tuple -- so a cross-certificate
+ * cycle or Bridge-CA fan-out terminates deterministically rather than growing without bound.
+ *
+ * `leaf` is a DER `Buffer`, a PEM string, or an already-parsed `pki.schema.x509` object. Returns
+ * `{ valid, path, trustAnchor, result, candidatesConsidered }`, where `path` is the ordered array
+ * `validate` consumes (anchor-proximal first, leaf last, the anchor excluded). Fail-closed: bad
+ * options throw `path/bad-input`; no chain to any anchor throws `path/no-path`; chains that
+ * assemble but none validate return `{ valid:false }` with the best failing `validate` result;
+ * the search bound throws `path/build-limit`. AIA caIssuers fetching is out of scope -- `build` is
+ * offline (zero network); supply fetched issuers in `opts.candidates`.
+ *
+ * @opts  candidates             The untrusted candidate CA pool (array of DER/PEM/parsed certs; alias `intermediates`).
+ * @opts  trustAnchors           The trust store (non-empty array of `{ name, publicKey, algorithm }` tuples or self-signed root certificates).
+ * @opts  time                   The check date (`Date`, required); forwarded to every internal `validate` call.
+ * @opts  maxDepth               Chain-length depth cap (default `C.LIMITS.PATH_BUILD_MAX_DEPTH`).
+ * @opts  maxCandidatesConsidered  Total-work cap on candidate expansions (default `C.LIMITS.PATH_BUILD_MAX_CANDIDATES`).
+ * @opts  validate               `false` returns the ordered path without validating (pure-builder mode; default `true`).
+ * @opts  (validate options)     Every `pki.path.validate` option (`requiredEku`, `revocationChecker`, `checkPurpose`, the initial policy inputs, ...) is forwarded unchanged.
+ * @example
+ *   var result = await pki.path.build(pemString, {
+ *     candidates: [],              // untrusted intermediates (the openssl -untrusted set)
+ *     trustAnchors: [pemString],   // a self-signed root, or a { name, publicKey, algorithm } tuple
+ *     time: new Date(),
+ *   });
+ *   result.valid;                  // true when a path to a trust anchor was found and validated
+ */
+async function build(leaf, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw E("path/bad-input", "build: opts must be an object");
+  var leafCert;
+  try { leafCert = coerceCert(leaf); }
+  catch (e) { throw E("path/bad-input", "build: the leaf certificate did not parse", e); }
+
+  var poolInput = opts.candidates !== undefined ? opts.candidates : opts.intermediates;
+  if (poolInput === undefined) poolInput = [];
+  if (!Array.isArray(poolInput)) throw E("path/bad-input", "build: opts.candidates must be an array of certificates");
+  // A pool larger than the absolute ceiling is rejected at entry (bounds the
+  // parse work on an untrusted bundle) -- distinct from the per-search tick
+  // budget below, which an operator may set lower to cap the DFS.
+  var poolCeiling = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES;
+  if (poolInput.length > poolCeiling) throw E("path/bad-input", "build: the candidate pool has " + poolInput.length + " certificates, exceeding the " + poolCeiling + " ceiling");
+  var pool;
+  try { pool = poolInput.map(coerceCert); }
+  catch (e) { throw E("path/bad-input", "build: a candidate certificate did not parse", e); }
+
+  if (!Array.isArray(opts.trustAnchors) || opts.trustAnchors.length === 0) throw E("path/bad-input", "build: opts.trustAnchors must be a non-empty array of anchor tuples or root certificates");
+  var anchors = opts.trustAnchors.map(toAnchor);
+
+  guard.time.assertValid(opts.time, E, "path/bad-input", "build: opts.time (the validity-window check date, forwarded to validate)");
+  // The chain-length bound is tied to the EFFECTIVE maxPathCerts the interleaved
+  // validate uses: a built path holds hop + 1 certificates (the leaf plus each
+  // intermediate), so capping hops at maxPathCerts - 1 keeps every path validate
+  // sees within its own per-path ceiling -- otherwise a maxDepth of maxPathCerts
+  // would assemble a maxPathCerts + 1 path that validate rejects with
+  // path/bad-input. The same cap value is computed the way validate computes it
+  // (opts.maxPathCerts forwarded), and the explicit-stack search below carries no
+  // native-recursion stack risk regardless of the depth.
+  var effectiveMaxCerts = guard.limits.cap(opts.maxPathCerts, "build: opts.maxPathCerts", constants.LIMITS.PATH_MAX_CERTS, { E: E, code: "path/bad-input", min: 1 });
+  // depthCeiling is 0 when maxPathCerts is 1: the only path within the limit is a
+  // single leaf directly under an anchor (a zero-hop search). maxDepth's minimum
+  // is therefore 0, not 1 -- a zero-hop search is legitimate and a maxPathCerts of
+  // 1 must not throw before the anchor is even checked.
+  var depthCeiling = effectiveMaxCerts - 1;
+  var maxDepth = guard.limits.cap(opts.maxDepth, "build: opts.maxDepth", Math.min(constants.LIMITS.PATH_BUILD_MAX_DEPTH, depthCeiling), { E: E, code: "path/bad-input", min: 0, max: depthCeiling });
+  var maxConsidered = guard.limits.cap(opts.maxCandidatesConsidered, "build: opts.maxCandidatesConsidered", poolCeiling, { E: E, code: "path/bad-input", min: 1 });
+  var doValidate = opts.validate !== false;
+
+  // The build-specific options are consumed here; every remaining validate
+  // option is forwarded unchanged to the interleaved validate call. Object.keys
+  // enumerates only own enumerable properties, so no prototype-pollution belt.
+  var BUILD_ONLY_OPT = { candidates: 1, intermediates: 1, trustAnchors: 1, maxDepth: 1, maxCandidatesConsidered: 1, validate: 1 };
+  var forwarded = {};
+  Object.keys(opts).forEach(function (k) { if (!BUILD_ONLY_OPT[k]) forwarded[k] = opts[k]; });
+  function validateOpts(anchor) {
+    var vo = {};
+    Object.keys(forwarded).forEach(function (f) { vo[f] = forwarded[f]; });
+    vo.trustAnchor = anchor;
+    return vo;
+  }
+
+  // The DoS terminator: tick() once per candidate-issuer expansion so a hostile
+  // mesh cannot fan the search without bound (RFC 4158 8.1). A breach throws
+  // path/build-limit. candidatesConsidered mirrors the tick count for the caller.
+  var counter = guard.limits.counter(maxConsidered, E, "path/build-limit", "build: candidate-issuer expansion");
+  var considered = 0;
+  var anyChainAssembled = false;
+  var bestFail = null;
+  var success = null;
+
+  // A bounded, EXPLICIT-stack forward DFS from the leaf toward an anchor -- no
+  // native recursion, so an operator-raised maxDepth cannot overflow the stack
+  // over an untrusted graph. Each frame is a candidate chain [top, ...toward the
+  // leaf] (leaf last) plus the identity keys already on it; a frame is expanded
+  // by prepending a name-chaining issuer. Highest-priority candidates are pushed
+  // LAST so they are popped (explored) FIRST -- depth-first in priority order.
+  // Caps are enforced before every expansion; a candidate whose (subject, SAN,
+  // public key) tuple is already on the chain is a loop and is pruned.
+  var stack = [{ chain: [leafCert], hop: 0, keys: new Set([identityKey(leafCert)]) }];
+  while (stack.length && !success) {
+    var frame = stack.pop();
+    var current = frame.chain[0];
+
+    // Terminate: is `current` issued by a configured anchor? An anchor-adjacent
+    // cert completes a candidate path; validate is the authority on acceptance.
+    // A found path breaks out here and the enclosing while exits on !success.
+    for (var ai = 0; ai < anchors.length; ai++) {
+      if (!nameMatchSoft(current.issuer.rdns, anchors[ai].name.rdns)) continue;
+      if (!doValidate) { success = { path: frame.chain.slice(), trustAnchor: anchors[ai] }; break; }
+      anyChainAssembled = true;
+      var res = await validate(frame.chain, validateOpts(anchors[ai]));
+      if (res.valid) { success = { valid: true, path: frame.chain.slice(), trustAnchor: anchors[ai], result: res }; break; }
+      if (!bestFail) bestFail = { path: frame.chain.slice(), trustAnchor: anchors[ai], result: res };
+    }
+    if (success || frame.hop >= maxDepth) continue;   // depth cap: this branch is exhausted
+
+    var childAki = childAkiKeyId(current);
+    var scored = [];
+    for (var pi = 0; pi < pool.length; pi++) {
+      if (nameMatchSoft(pool[pi].subject.rdns, current.issuer.rdns)) {
+        scored.push({ cand: pool[pi], score: scoreCandidate(pool[pi], childAki, anchors, opts.time) });
+      }
+    }
+    // Ascending sort -> push lowest priority first so the highest is on top.
+    scored.sort(function (a, bb) { return a.score - bb.score; });
+    for (var ci = 0; ci < scored.length; ci++) {
+      counter.tick();          // breadth / total-work cap -> throws path/build-limit
+      considered += 1;
+      var cand = scored[ci].cand;
+      var candKey = identityKey(cand);
+      if (frame.keys.has(candKey)) continue;   // the (subject,SAN,key) tuple is already on this branch -> a loop, prune
+      var childKeys = new Set(frame.keys);
+      childKeys.add(candKey);
+      stack.push({ chain: [cand].concat(frame.chain), hop: frame.hop + 1, keys: childKeys });
+    }
+  }
+
+  if (success) {
+    if (doValidate) return { valid: true, path: success.path, trustAnchor: success.trustAnchor, result: success.result, candidatesConsidered: considered };
+    return { path: success.path, trustAnchor: success.trustAnchor, candidatesConsidered: considered };
+  }
+  if (anyChainAssembled) {
+    // Chains reached an anchor but none validated -> the soft verdict carrying
+    // the best failing validate result (parity with validate; never a throw).
+    return { valid: false, path: bestFail.path, trustAnchor: bestFail.trustAnchor, result: bestFail.result, candidatesConsidered: considered };
+  }
+  // No chain to any configured anchor could even be assembled -- a permanent
+  // structural verdict (name/key chaining dead-ended before the trust store).
+  throw E("path/no-path", "build: no certification path from the leaf to any configured trust anchor could be assembled");
+}
+
 module.exports = {
   validate: validate,
+  build: build,
   crlChecker: crlChecker,
   ocspChecker: ocspChecker,
   verifyOcspResponse: verifyOcspResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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:9ded865a-a922-4de1-a8f0-bd02d3b29a2e",
+  "serialNumber": "urn:uuid:dc01f613-ee62-4b7d-b2d5-42e3bb2f5560",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-17T19:09:09.529Z",
+    "timestamp": "2026-07-18T01:11:02.665Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.5",
+      "bom-ref": "@blamejs/pki@0.3.7",
       "type": "application",
       "name": "pki",
-      "version": "0.3.5",
+      "version": "0.3.7",
       "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.3.5",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.7",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.5",
+      "ref": "@blamejs/pki@0.3.7",
       "dependsOn": []
     }
   ]