fix(x509): reject RFC 5280 MUST-NOT builder constructions

[kjanat]

What

Resolves the three certificate/extension builder findings from the spec audit, all RFC 5280 MUST-NOT constructions the builders emitted.

pathLenConstraint without keyCertSign (§4.2.1.9)

"CAs MUST NOT include the pathLenConstraint field unless the cA boolean is asserted and the key usage extension asserts the keyCertSign bit." Only the cA conjunct was checked, so { basicConstraints: { ca: true, pathLength: 0 }, keyUsage: ['digitalSignature'] } emitted a certificate this library's own verifier rejects. assertPathLengthKeyUsage returns early only when pathLength is absent; an absent, empty, or keyCertSign-less keyUsage all throw path_length_requires_key_cert_sign, on both the certificate path (buildCertificateExtensions) and the CSR path (appendConstraintExtensions).

Empty subject requires a present, critical SAN (§4.2.1.6)

The clause carries two conjoined MUSTs; only criticality was implemented, so subject: {} signed a certificate with no identity at all. buildCertificateExtensions now throws empty_subject_requires_subject_alt_name when subjectIsEmpty and no SAN is configured. A customExtensions SAN counts only when critical: true, and a present-but-empty subjectAltNames array counts as absent. createCertificate delegates, so one guard covers both entry points; buildRequestedExtensions is untouched.

relativeName with multiple cRLIssuer DNs (§4.2.1.13)

"The DistributionPointName MUST NOT use the nameRelativeToCRLIssuer alternative when cRLIssuer contains more than one distinguished name." Lines 88-91 of the same clause make the DN-only requirement unconditional ("If present, the cRLIssuer MUST only contain the distinguished name"), so encodeDistributionPoint rejects any non-directoryName cRLIssuer entry with distribution_point_crl_issuer_not_directory_name, and additionally rejects nameRelativeToCRLIssuer past one DN with distribution_point_relative_name_multiple_crl_issuers.

Citation riders (audit Medium)

The ParsedBitFlags docs claimed non-canonical padding is recorded "so verification layers can decide", but no caller can observe it because requireCanonicalBitFlags throws first; the docs now state rejection. decodeBoolean's doc cited the BER any-non-zero rule while the function enforces X.690 11.1 DER (0xff/0x00 only). The audit's remaining two Medium citation errors (X.690 §11.2.2 six sites, name-constraints step labels) were verified already fixed on master.

Test fixture correction

Three verifier tests built their deliberately-invalid intermediate (ca: true, keyUsage without keyCertSign) with pathLength: 0, which the builder now refuses. Dropping pathLength keeps those chains constructible and verifier-rejected (key_cert_sign_required / ca_required unchanged).

Tests

Encoder level: path_length_requires_key_cert_sign (accepted with keyCertSign, rejected when keyUsage is absent or lacks it), empty_subject_requires_subject_alt_name (empty array rejected, populated accepted), distribution_point_crl_issuer_not_directory_name (a URI cRLIssuer rejected under both fullName and relativeName), distribution_point_relative_name_multiple_crl_issuers (two DNs rejected, one accepted). Public API: createSelfSignedCertificate and createCertificateSigningRequest reject the pathLen case; createCertificate rejects an empty subject without a SAN and accepts one carried as a critical custom extension.

Gate: typecheck, biome, docs:lint, 1482 tests (PKITS in-suite, 249 standalone), and 76 OpenSSL differential cases (11 deterministic in test/differential.test.ts plus 65 generated in test/differential-fuzz.test.ts, both run by test:differential). Green on stable Bun 1.3.14 and on the bun-35433 build.

Canonical extension OIDs and custom payload validation

pushExtension keyed its duplicate set by raw OID text and appendCustomExtensions looked the registry up the same way. 2.5.029.17 and 2.5.29.17 encode to identical DER, so typed subjectAltNames plus a custom 2.5.029.17 emitted two wire-identical SAN OIDs that the parser then rejected, and a custom 2.5.029.18 evaded the certificate-only restriction on issuerAltName. Both keys are now the canonical form via canonicalizeOid; the diagnostic still quotes the OID as submitted.

The effective-value resolvers swallowed DER decode failures and returned undefined, so a customExtensions entry carrying a known OID with a malformed payload passed every cross-field guard and reached the wire unchecked. assertCustomExtensionsValid now decodes known payloads ahead of those guards and throws malformed_known_extension_value, which also lets the three resolvers drop their catch clauses.

Empty IA5 GeneralNames reject on parse

parseGeneralName accepted a zero-length dNSName, rfc822Name, or uniformResourceIdentifier, which RFC 5280 §4.2.1.6 forbids. An external certificate could carry an empty subjectAltName value and parse, leaving chain verification to accept a certificate with no usable identity when no identity match was requested. Certificate and CRL parsing share the decoder, so this covers subjectAltName, issuerAltName, authorityInfoAccess locations, CRL distribution points, cRLIssuer, the issuing distribution point, and certificateIssuer. Name constraints keep their own decoder, where an empty base is meaningful.

Builder strictness means parser-strictness fixtures can no longer be built through the builder, so test/helpers.ts gains raw-extension variants of createCertificate, createSelfSignedCertificate, and createCertificateSigningRequest that splice extensions into the signed structure and re-sign.

Known-extension profiles apply to custom payloads

Decoding a payload proves its structure, not that it obeys the RFC 5280 profile, because the parser is deliberately tolerant. ExtensionDefinition now requires an assertProfile hook that delegates to the encoder owning each rule, and the builders run it over the decoded value of any customExtensions entry carrying a known OID. Parsing never calls it, so the parser and the CRL scanner stay tolerant.

That closes every rule the decoder does not already carry: duplicate policy OIDs and an over-long DisplayText in certificatePolicies, a non-URI OCSP location in authorityInfoAccess, a nameConstraints with neither subtree, a keyUsage with no bit set, and the §4.2.1.13 cRLIssuer rules. Every other registered extension (basicConstraints, extendedKeyUsage, subjectAltName, issuerAltName, policyMappings, policyConstraints, inhibitAnyPolicy, SKI, AKI) was audited: their decoders already reject what their encoders reject, and each still declares the hook so the two paths cannot drift apart later.

The payload decodes once, inside the coded-error boundary. A profile violation keeps its own code. A decode failure maps to malformed_known_extension_value.

The §4.2.1.13 rules now live in assertCrlDistributionPointsProfile, shared by encodeCrlDistributionPoints and the hook. encodeDistributionPointName consumes the resolved name choice, so it has no unreachable branch.

Coded OID errors on every encoding path

encodeExtension is public and called objectIdentifier directly, so encodeExtension('3.1', ...) threw a bare Error. The encodeCertificatePolicies duplicate scan encoded each policy OID before validating it, with the same result. Both validate first and return invalid_oid, alongside the builder paths, for an OID that parses as decimals but breaks the X.660 arc bounds. encodeBasicConstraints gains path_length_requires_ca in place of its bare throw.

Round-two regression matrices

cRLDistributionPoints: a URI cRLIssuer and a relativeName beside two wire-tagged ([4]) DNs are rejected as profile violations; a NULL payload, an empty cRLIssuer, and an empty points SEQUENCE are rejected as malformed; a fullName URI, a relativeName with one DN, a relativeName with no cRLIssuer, and a fullName beside a [4] DN are accepted. Each runs on the certificate and CSR paths under both 2.5.29.31 and 2.5.029.31, and every profile-invalid payload is asserted to still parse.

Profile hooks: one rejecting case per rule the decoder does not carry, one accepting case per registered extension, and one malformed case per rule the decoder does carry, all on both builder paths. Every new guard was reverted in turn to confirm its test fails without it.

Canonical OID comparison on the typed path

getAuthorityInfoAccessMethodOid and getExtendedKeyUsageOid validated a custom OID and then returned the string as submitted, and encodePolicyMappings compared its input by string. Both rules keyed on OID equality were therefore dodgeable by an alias that encodes to the same DER: { method: { type: 'oid', value: '1.3.6.1.5.5.7.048.1' }, location: { type: 'dns', ... } } emitted a non-URI OCSP location, and 2.5.29.032.0 passed the policyMappings anyPolicy check. All three now resolve through validateOid, which returns the canonical spelling. The custom-payload route was already safe, since an OID decoded from DER is canonical by construction.

Criticality is part of the profile

assertProfile saw only the decoded payload, so a customExtensions entry could carry a criticality RFC 5280 forbids while the typed field could not. The hook now takes the flag as well. nameConstraints (§4.2.1.10), policyConstraints (§4.2.1.11), and inhibitAnyPolicy (§4.2.1.14) must be critical; authorityKeyIdentifier (§4.2.1.1), subjectKeyIdentifier (§4.2.1.2), and authorityInfoAccess (§4.2.2.1) must not.

§4.2.1.9 conditions basicConstraints criticality on the certificate being a CA whose key validates signatures on certificates. Neither conjunct is in the extension itself, so that check sits beside assertPathLengthKeyUsage, where the effective basicConstraints and keyUsage are already resolved across the typed field and customExtensions. §4.2.1.3 restricts a key only through a keyUsage extension that reaches the wire, so an absent keyUsage, and an empty one the builder omits, both leave the key free to validate certificate signatures and require a critical basicConstraints; only an emitted keyUsage lacking keyCertSign takes the certificate out of the clause's scope.

A single test runs every registered definition's hook at its own defaultCritical with a conformant payload, so a default that contradicts its profile fails, and a new extension added without a fixture fails too. test/verify.test.ts built its non-critical name-constraints tolerance fixture through the builder; it moves to createSelfSignedCertificateWithRawExtensions.

RFC 1421 PEM header parsing is tracked separately in #92; it is out of scope here.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	micro509	517fc1c	Commit Preview URL Branch Preview URL	Jul 25 2026, 12:49 AM

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 40 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f6daf994-5e35-4059-8705-3024f3d7b05e

📥 Commits

Reviewing files that changed from the base of the PR and between 702d82c and 517fc1c.

📒 Files selected for processing (6)

• test/AGENTS.md
• test/certificate.test.ts
• test/crl.test.ts
• test/csr.test.ts
• test/helpers.ts
• test/parse.test.ts

📝 Walkthrough

Walkthrough

Certificate and CSR builders now enforce RFC 5280 constraints for path length, key usage, empty subjects, GeneralName values, criticality, OIDs, AIA, and CRL distribution points. Extension registries provide profile assertions, parsers reject empty IA5String GeneralNames, and tests can inject raw extensions to exercise malformed inputs. Tooling, documentation, changelog entries, and fixtures were also updated.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CertificateOrCSRBuilder
  participant ExtensionRegistry
  participant ExtensionProfileValidator
  participant Parser
  CertificateOrCSRBuilder->>ExtensionRegistry: resolve configured or custom extension
  ExtensionRegistry->>ExtensionProfileValidator: validate payload and criticality
  ExtensionProfileValidator-->>CertificateOrCSRBuilder: accept or return coded error
  Parser->>Parser: decode GeneralName and extension DER
  Parser-->>CertificateOrCSRBuilder: reject empty IA5String GeneralName

Loading

Possibly related issues

• KAJ-332 — The new RFC 5280 test coverage overlaps with the proposed clause-addressable conformance-suite organisation.

Possibly related PRs

• kjanat/micro509#78 — Shares AIA GeneralName handling affected by the new validation.
• kjanat/micro509#79 — Overlaps with stricter AIA and CRL distribution-point encoder profiles.
• kjanat/micro509#80 — Shares stricter SAN and GeneralName parsing behaviour.

Suggested labels: bug, rfc-conformance, security, tests

Poem

RFC rules now guard the sea,
Empty names flee the decree.
OIDs sail in canonical line,
Key-cert signs make paths align,
Arrr, malformed certs walk the plank!

🚥 Pre-merge checks | ✅ 6 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Semver Version Bump Validation	⚠️ Warning	Source files changed, but package.json stayed at 0.13.0 in base and PR; these additive fixes need a SemVer MINOR bump.	Bump package.json to 0.14.0 (MINOR) or otherwise update the repo’s version field to match the code changes.
Agents.Md Documentation Updated	⚠️ Warning	src/internal and test AGENTS were updated, but package.json script/workflow changes lack a matching root AGENTS.md update.	Update the root AGENTS.md to document the new package.json scripts/CLI workflow changes, then re-run the check.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	It clearly describes the PR's X.509 RFC 5280 rejection fixes.
Description check	✅ Passed	The description directly matches the builder, parser, and test changes in the patch.
Docstring Coverage	✅ Passed	Docstring coverage is 85.07% which is sufficient. The required threshold is 30.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Changelog Update	✅ Passed	Source files changed, package.json stayed at 0.13.0, and CHANGELOG.md adds the new fixes under the existing [Unreleased] section.

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

• micro509-vite-demo

  npm i https://pkg.pr.new/micro509@88
  

  pnpm add https://pkg.pr.new/micro509@88
  

  bun add https://pkg.pr.new/micro509@88
  

commit: 517fc1c