Support non-directoryName crlIssuer forms in distribution-point matching

[kjanat]

Indirect CRL processing currently matches crlIssuer against certificate distribution points using directoryName only; other GeneralName forms are treated as unsupported, and direct CRLs with an alternate crlIssuer are rejected. Fail-closed, but narrower than full RFC 5280 §4.2.1.13 distribution-point semantics.

Extending this means accepting and comparing additional crlIssuer GeneralName forms (primarily uniformResourceIdentifier) during CRL applicability checks. Rare in practice — most indirect-CRL deployments use directoryName — so demand-driven.

Additive — does not block 1.0.

[coderabbitai]

Coding Plan

Summary

The URI crlIssuer can't be matched against the CRL (DN-only) — so we hand the applicability check the certificate that actually signed the CRL (already in scope) and match non-directoryName forms against that cert's subjectAltName, mirroring the OCSP ResponderID precedent.

Core change is a small, optional signature widening of checkCrlApplicability/matchesIndirectCrlIssuer in src/revocation/crl.ts, reusing the existing compareGeneralNames helper; no changes to chain.ts's resolution loop are needed because the retry already supplies the resolved indirect signer.

Fail-closed stays fail-closed: opaque forms and unresolved signers keep indirect_crl_unsupported; supported-but-non-matching forms become issuer_mismatch. No new public reason code, Gap A (direct-CRL alternate issuer) deliberately left rejected.

Follow-up agents, mark ye chart: primary edits in src/revocation/crl.ts; tests in test/crl.test.ts + test/revocation.test.ts (the existing crl.test.ts:1595 assertion needs reconciling); docs in docs/PKIX-SCOPE.md §12 and CHANGELOG.md; version in package.json + jsr.json. Leave the parseGeneralName duplication between x509/parse.ts and crl.ts alone — it's a separate refactor, and URI already parses fine in crl.ts. Now go fix it clean, ye scurvy dogs. 🏴‍☠️

Design Choices

Design Choice 1: What should a non-directoryName (chiefly URI) crlIssuer actually be compared against?

Options Considered:

1. Accept/echo the URI without any comparison — grants applicability with zero security value (worse than the current fail-closed stance).
2. Compare the crlIssuer GeneralName against the resolved CRL-signing certificate's subjectAltName entries (the cert findIndirectCrlIssuer locates, which is the same cert used for CRL signature verification), mirroring how OCSP ResponderID validates against the resolved signer certificate.
3. Compare against crl.issuer — impossible, it's a DN with no URI form.

Chosen Option: 2

Rationale: It's the only form that carries real security meaning, reuses the signer certificate already resolved for signature verification, and follows the established OCSP ResponderID precedent.

Design Choice 2: Which GeneralName forms should be covered — URI only, or all SAN-comparable forms?

Options Considered:

1. URI only — matches the ticket's literal emphasis but leaves an inconsistent special-case, since dns/email/ip could match a SAN just as naturally.
2. All SAN-comparable forms (uri, dns, email, ip) via one unified comparison, directoryName continuing to match crl.issuer, and truly opaque forms (unknown/otherName/srv) staying fail-closed.

Chosen Option: 2

Rationale: Reuses the existing compareGeneralNames helper, avoids artificial special-casing, and keeps the fail-closed boundary crisp. URI remains the headline motivating case.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Give the applicability check the signer's identity, then broaden the match

Right now checkCrlApplicability be sailing blind — it only sees the CRL's DN issuer and can therefore only reason about directoryName. The objective of this phase be to hand it the certificate that actually signed the CRL (already sitting in scope one function up), then teach the crlIssuer matcher to compare non-directoryName forms against that certificate's subjectAltName, whilst keeping the fail-closed behaviour wherever no trustworthy comparison target exists.

Task 1: Thread the CRL-signing certificate into applicability checking

Make the resolved signer certificate available where crlIssuer matching happens.

• In src/revocation/crl.ts, widen the internal checkCrlApplicability signature to accept an optional CRL-signing certificate (the same ParsedCertificate already used for signature verification in checkCertificateRevocationAgainstCrl).
• Pass that certificate down from checkCertificateRevocationAgainstCrl's existing issuer parameter — no new resolution logic is needed; the cert is already in hand at that call site.
• Keep the parameter optional so any legacy/absent-signer path falls back to today's directoryName-only behaviour (fail-closed by default).
• No changes required in chain.ts's findIndirectCrlIssuer or its retry loop — the retry already re-invokes with the resolved indirect signer, so the correct certificate arrives naturally on the second pass. The standalone revocation.ts path benefits too, since it already supplies the signer as issuerCertificate.

Task 2: Broaden crlIssuer matching to SAN-comparable GeneralName forms

Teach the matcher to accept uri (and other SAN-comparable forms) by comparing against the signer's subjectAltNames.

• Extend matchesIndirectCrlIssuer in src/revocation/crl.ts to take the optional signer certificate. Retain the existing directoryName-against-crl.issuer comparison unchanged.
• For uri/dns/email/ip entries: when a signer certificate is present, compare each crlIssuer GeneralName against the signer's subjectAltNames entries. Reuse the existing compareGeneralNames helper for value-equality rather than reimplementing per-form logic.
• Treat a match against the signer's SAN as an authoritative true; this is the security-bearing step (it proves the CRL was signed by a certificate carrying the named identity).
• Leave genuinely opaque forms (unknown/otherName/srv, and anything with no resolvable target) on the existing 'unsupported' fail-closed path.
• Consider applying the same treatment to the sibling matchesRevokedEntryIssuer (CRL-entry certificateIssuer) for consistency, but only if it can be done without expanding scope; if the entry-level path lacks a resolvable signer target, leave it as-is and note it.

Task 3: Keep the fail-closed semantics and map reason codes correctly

Ensure the reason codes reflect the new, sharper distinction between "unsupported form" and "supported form that simply didn't match".

• In checkCrlApplicability, distinguish three outcomes for non-directoryName crlIssuer entries:
  • resolvable form + signer SAN contains it → applicable;
  • resolvable form + signer present but SAN has no match → a genuine mismatch, surfacing as issuer_mismatch;
  • opaque form, or no signer certificate available to compare against → remains indirect_crl_unsupported (fail-closed as today).
• Do not add a new member to the exported CrlApplicabilityFailureReason union — reuse issuer_mismatch and indirect_crl_unsupported. This avoids widening a public union and forcing exhaustive-switch updates in chain.ts.
• Explicitly out of scope: Gap A (a direct CRL, not flagged indirectCrl, whose certificate DP names an alternate crlIssuer). That's a CRL-scope mismatch independent of GeneralName form and stays rejected/fail-closed. Note this deliberate exclusion in the CHANGELOG entry.

🤖 Prompt for AI agents

Implement the widened indirect-CRL `crlIssuer` matching in
`src/revocation/crl.ts`.

1. Widen the internal `checkCrlApplicability` signature to accept an
**optional** CRL-signing certificate (the same `ParsedCertificate` used for
signature verification in `checkCertificateRevocationAgainstCrl`). Pass it down
from `checkCertificateRevocationAgainstCrl`'s existing issuer parameter — no new
resolution logic needed. Keep the parameter optional so absent-signer paths fall
back to today's `directoryName`-only, fail-closed behaviour. No changes needed
in `chain.ts`'s `findIndirectCrlIssuer` or retry loop (the retry already
supplies the resolved indirect signer); `revocation.ts` already passes
`issuerCertificate` too.

2. Extend `matchesIndirectCrlIssuer` to accept the optional signer certificate.
Keep the existing `directoryName`-vs-`crl.issuer` comparison unchanged. For
`uri`/`dns`/`email`/`ip` `crlIssuer` entries, when a signer certificate is
present, compare each entry against the signer's `subjectAltNames` using the
existing `compareGeneralNames` helper (do not reimplement per-form logic). A SAN
match is authoritative (`true`). Leave opaque forms
(`unknown`/`otherName`/`srv`) and anything with no resolvable target on the
existing `'unsupported'` fail-closed path. Optionally, if scope permits without
expansion, apply the same treatment to `matchesRevokedEntryIssuer`; otherwise
leave it as-is and note it.

3. In `checkCrlApplicability`, map outcomes to reason codes: resolvable form +
SAN match → applicable; resolvable form + signer present but no SAN match →
`issuer_mismatch`; opaque form or no signer available →
`indirect_crl_unsupported`. Do NOT add a new member to the exported
`CrlApplicabilityFailureReason` union — reuse `issuer_mismatch` and
`indirect_crl_unsupported` to avoid widening the public union and forcing
exhaustive-switch updates in `chain.ts`. Explicitly leave Gap A (a direct,
non-`indirectCrl`-flagged CRL whose DP names an alternate `crlIssuer`) out of
scope — it remains rejected/fail-closed.

Phase 2: Prove it with tests

The objective here is to lock in the new positive behaviour and, just as importantly, prove the fail-closed edges still hold — because a broadened matcher that quietly over-accepts would be a security regression.

Task 1: Add positive URI-based crlIssuer matching tests

Cover the happy path that does not exist today.

• In test/crl.test.ts, synthesise (via the existing createCertificate/createCertificateRevocationList helpers, following the pattern around lines 1399+) an indirect CRL whose signing certificate carries a uniformResourceIdentifier in its subjectAltName, and a leaf whose crlDistributionPoints[].crlIssuer names that same URI. Assert the CRL is deemed applicable.
• Add a companion higher-level assertion in test/revocation.test.ts mirroring the existing directoryName indirect-CRL test (~line 269), so both the low-level and orchestrated paths are exercised.

Task 2: Add and update fail-closed / negative tests

Guard the boundaries and reconcile the existing rejection test whose reason code shifts.

• Add a test where the URI crlIssuer is not present in the signer's SAN → expect a mismatch (issuer_mismatch), not applicability.
• Add a test where no signer certificate can be resolved → expect the unchanged indirect_crl_unsupported fail-closed result.
• Update the existing test at test/crl.test.ts:1595 ("rejects indirect CRLs when cRLIssuer uses unsupported GeneralName types"): with the broadened matcher, a dns/uri form that has no SAN match now yields issuer_mismatch rather than indirect_crl_unsupported. Adjust the assertion, or repoint the test to a genuinely opaque form (e.g. unknown) to keep asserting the indirect_crl_unsupported path.
• Assert on typed reason codes throughout (per test/AGENTS.md), never strings/booleans.

🤖 Prompt for AI agents

Add tests covering both the new positive matching behaviour and the fail-closed
boundaries.

1. In `test/crl.test.ts`, using the existing
`createCertificate`/`createCertificateRevocationList` helpers (pattern around
lines 1399+), build an indirect CRL whose signing certificate carries a
`uniformResourceIdentifier` in its `subjectAltName`, and a leaf whose
`crlDistributionPoints[].crlIssuer` names that same URI. Assert the CRL is
deemed applicable. Mirror this at the orchestrated level in
`test/revocation.test.ts` alongside the existing `directoryName` indirect-CRL
test (~line 269).

2. Add a negative test where the URI `crlIssuer` is NOT present in the signer's
SAN, asserting the typed `issuer_mismatch` reason (not applicability).

3. Add a negative test where no signer certificate can be resolved, asserting
the unchanged `indirect_crl_unsupported` fail-closed reason.

4. Update the existing test at `test/crl.test.ts:1595` ("rejects indirect CRLs
when cRLIssuer uses unsupported GeneralName types"): since a `dns`/`uri` form
with no SAN match now yields `issuer_mismatch` rather than
`indirect_crl_unsupported`, either adjust the assertion accordingly or repoint
the test to a genuinely opaque form (e.g. `unknown`) to keep asserting
`indirect_crl_unsupported`.

5. Throughout, assert on typed reason codes only (per `test/AGENTS.md`) — never
plain strings or booleans.

Phase 3: Keep the charts honest — docs, changelog, version

Because docs/PKIX-SCOPE.md is currently silent on indirect CRLs and crlIssuer entirely, and because a public reason-code behaviour has shifted, the docs and manifests must be brought into line or the whole thing drifts.

Task 1: Document the new crlIssuer form coverage

Record what is now supported and what remains fail-closed.

• Extend docs/PKIX-SCOPE.md §12 (CRL checklist) with a short statement (or a small matrix) noting that indirect-CRL crlIssuer matching now supports directoryName (against the CRL issuer DN) and SAN-comparable forms (uri/dns/email/ip, matched against the resolved CRL-signing certificate's subjectAltName), whilst opaque forms and unresolved signers remain fail-closed. Note that network dereferencing of URIs is explicitly not performed.
• Add a ## [Unreleased] (or new version header, per Task 3.2) entry in CHANGELOG.md in the established present-tense, backtick-identifier style, describing the broadened matching, the reason-code semantics shift (issuer_mismatch vs indirect_crl_unsupported), and the deliberately-excluded Gap A.

Task 2: Bump the version manifests

Honour the repo convention that non-doc/test source changes require a version bump.

• Bump the version in both package.json and jsr.json in lockstep (minor bump — additive with a public reason-code semantics shift).
• Promote the CHANGELOG.md [Unreleased] block under a dated ## [X.Y.Z] - YYYY-MM-DD header and repoint the compare-link references at the bottom of the file, per the release checklist comment.

🤖 Prompt for AI agents

Update documentation and version manifests to reflect the behaviour change.

1. Extend `docs/PKIX-SCOPE.md` §12 (CRL checklist) with a short statement or
small matrix noting that indirect-CRL `crlIssuer` matching now supports
`directoryName` (matched against the CRL issuer DN) and SAN-comparable forms
(`uri`/`dns`/`email`/`ip`, matched against the resolved CRL-signing
certificate's `subjectAltName`), while opaque forms and unresolved signers
remain fail-closed. Explicitly note that network dereferencing of URIs is NOT
performed.

2. Add a `## [Unreleased]` (or new dated version header) entry to
`CHANGELOG.md`, following the established present-tense, backtick-identifier
style, describing: the broadened matching capability, the reason-code semantics
shift (`issuer_mismatch` vs `indirect_crl_unsupported`), and the
deliberately-excluded Gap A (direct CRL with alternate `crlIssuer`).

3. Bump the version in both `package.json` and `jsr.json` in lockstep — a minor
bump, since the change is additive but shifts public reason-code semantics.

4. Promote the `CHANGELOG.md` `[Unreleased]` block under a dated `## [X.Y.Z] -
YYYY-MM-DD` header and repoint the compare-link references at the bottom of the
file, per the repo's release checklist comment.

Research

Ahoy, here be the lay of the land, charted proper-like: All the revocation grog lives in src/revocation/. The whole crlIssuer/indirect-CRL matching surface sits in src/revocation/crl.ts (checkCrlApplicability, matchesIndirectCrlIssuer, compareGeneralNames, directoryNameDerHexMatchesParsedName). The chain-level orchestration in src/revocation/chain.ts resolves the actual signing certificate via findIndirectCrlIssuer (AKI/SKI, then DN) and re-runs the validate→apply cycle. The lower-level src/revocation/revocation.ts API takes a caller-supplied issuer certificate straight through.

Crucially — and this be the crux of it — the CRL-signing certificate is already in hand inside checkCertificateRevocationAgainstCrl (it's the cert used for signature verification) but is never passed down to the applicability check. Public reason codes live in the exported CrlApplicabilityFailureReason union in crl.ts. Scope claims live in docs/PKIX-SCOPE.md (which is currently silent on indirect CRLs entirely).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the widened indirect-CRL `crlIssuer` matching in
`src/revocation/crl.ts`.

1. Widen the internal `checkCrlApplicability` signature to accept an
**optional** CRL-signing certificate (the same `ParsedCertificate` used for
signature verification in `checkCertificateRevocationAgainstCrl`). Pass it down
from `checkCertificateRevocationAgainstCrl`'s existing issuer parameter — no new
resolution logic needed. Keep the parameter optional so absent-signer paths fall
back to today's `directoryName`-only, fail-closed behaviour. No changes needed
in `chain.ts`'s `findIndirectCrlIssuer` or retry loop (the retry already
supplies the resolved indirect signer); `revocation.ts` already passes
`issuerCertificate` too.

2. Extend `matchesIndirectCrlIssuer` to accept the optional signer certificate.
Keep the existing `directoryName`-vs-`crl.issuer` comparison unchanged. For
`uri`/`dns`/`email`/`ip` `crlIssuer` entries, when a signer certificate is
present, compare each entry against the signer's `subjectAltNames` using the
existing `compareGeneralNames` helper (do not reimplement per-form logic). A SAN
match is authoritative (`true`). Leave opaque forms
(`unknown`/`otherName`/`srv`) and anything with no resolvable target on the
existing `'unsupported'` fail-closed path. Optionally, if scope permits without
expansion, apply the same treatment to `matchesRevokedEntryIssuer`; otherwise
leave it as-is and note it.

3. In `checkCrlApplicability`, map outcomes to reason codes: resolvable form +
SAN match → applicable; resolvable form + signer present but no SAN match →
`issuer_mismatch`; opaque form or no signer available →
`indirect_crl_unsupported`. Do NOT add a new member to the exported
`CrlApplicabilityFailureReason` union — reuse `issuer_mismatch` and
`indirect_crl_unsupported` to avoid widening the public union and forcing
exhaustive-switch updates in `chain.ts`. Explicitly leave Gap A (a direct,
non-`indirectCrl`-flagged CRL whose DP names an alternate `crlIssuer`) out of
scope — it remains rejected/fail-closed.
===============================================================================

Task: 2

Add tests covering both the new positive matching behaviour and the fail-closed
boundaries.

1. In `test/crl.test.ts`, using the existing
`createCertificate`/`createCertificateRevocationList` helpers (pattern around
lines 1399+), build an indirect CRL whose signing certificate carries a
`uniformResourceIdentifier` in its `subjectAltName`, and a leaf whose
`crlDistributionPoints[].crlIssuer` names that same URI. Assert the CRL is
deemed applicable. Mirror this at the orchestrated level in
`test/revocation.test.ts` alongside the existing `directoryName` indirect-CRL
test (~line 269).

2. Add a negative test where the URI `crlIssuer` is NOT present in the signer's
SAN, asserting the typed `issuer_mismatch` reason (not applicability).

3. Add a negative test where no signer certificate can be resolved, asserting
the unchanged `indirect_crl_unsupported` fail-closed reason.

4. Update the existing test at `test/crl.test.ts:1595` ("rejects indirect CRLs
when cRLIssuer uses unsupported GeneralName types"): since a `dns`/`uri` form
with no SAN match now yields `issuer_mismatch` rather than
`indirect_crl_unsupported`, either adjust the assertion accordingly or repoint
the test to a genuinely opaque form (e.g. `unknown`) to keep asserting
`indirect_crl_unsupported`.

5. Throughout, assert on typed reason codes only (per `test/AGENTS.md`) — never
plain strings or booleans.
===============================================================================

Task: 3

Update documentation and version manifests to reflect the behaviour change.

1. Extend `docs/PKIX-SCOPE.md` §12 (CRL checklist) with a short statement or
small matrix noting that indirect-CRL `crlIssuer` matching now supports
`directoryName` (matched against the CRL issuer DN) and SAN-comparable forms
(`uri`/`dns`/`email`/`ip`, matched against the resolved CRL-signing
certificate's `subjectAltName`), while opaque forms and unresolved signers
remain fail-closed. Explicitly note that network dereferencing of URIs is NOT
performed.

2. Add a `## [Unreleased]` (or new dated version header) entry to
`CHANGELOG.md`, following the established present-tense, backtick-identifier
style, describing: the broadened matching capability, the reason-code semantics
shift (`issuer_mismatch` vs `indirect_crl_unsupported`), and the
deliberately-excluded Gap A (direct CRL with alternate `crlIssuer`).

3. Bump the version in both `package.json` and `jsr.json` in lockstep — a minor
bump, since the change is additive but shifts public reason-code semantics.

4. Promote the `CHANGELOG.md` `[Unreleased]` block under a dated `## [X.Y.Z] -
YYYY-MM-DD` header and repoint the compare-link references at the bottom of the
file, per the repo's release checklist comment.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!