@blamejs/pki 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.

package/README.md

@@ -221,7 +221,7 @@ 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` |
@@ -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/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.6",
+  "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:552d3506-7a4d-4927-bd2e-3faadaa00c02",
+  "serialNumber": "urn:uuid:dc01f613-ee62-4b7d-b2d5-42e3bb2f5560",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-17T19:50:12.519Z",
+    "timestamp": "2026-07-18T01:11:02.665Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.6",
+      "bom-ref": "@blamejs/pki@0.3.7",
       "type": "application",
       "name": "pki",
-      "version": "0.3.6",
+      "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.6",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.7",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.6",
+      "ref": "@blamejs/pki@0.3.7",
       "dependsOn": []
     }
   ]