DSA verification option (opt-in) for legacy chains

[kjanat]

WebCrypto has no DSA, so DSA-signed chains fail signature verification by design (PKITS 4.1.4/4.1.5 are expected-fail). FIPS 186-5 removed DSA for signature generation, so the boundary is defensible indefinitely.

If demand ever materializes, two additive shapes:

1. Opt-in pure-TS DSA verify (verification only, no generation) behind an explicit option.
2. A pluggable signature-verifier hook on chain verification, letting callers supply their own verifier for algorithms outside WebCrypto — more general, keeps DSA code out of the library.

Either is additive (new optional option). Default recommendation: keep the boundary; close this as wontfix if no demand by 1.0.

[coderabbitai]

Coding Plan

Summary

• Build the ticket's pluggable signature-verifier hook (option 2), keeping all DSA maths out of the library and honouring the zero-dependency, WebCrypto-native philosophy.
• Attach it as a single optional signatureVerifiers field threaded through the existing opt-in-option and path-building plumbing, invoked only at the existing unsupported-algorithm fallback in sig-verify.ts so native verification be never overridden.
• Reuse existing typed outcomes (no new error code), add DSA OID/label recognition for tidy parsing, and cover it with fixture-based tests plus scope/agent/changelog updates.

Arr, and when them PKITS DSA cases finally validate through a caller's own verifier while the default still holds the line — that, me hearties, be the sweet clank of a bug fixed proper. 🏴‍☠️

Design Choices

Design Choice 1: Which additive shape should we build, ye scurvy dogs?

Options Considered:

1. In-library pure-TS DSA verify — write bigint modPow, modular inverse, an arbitrary-precision INTEGER decoder, and the DSA verification equation from scratch inside src/internal/crypto/. Large new crypto surface that directly contradicts the documented "zero-dependency, WebCrypto-native, no DSA by design" philosophy and permanently plants DSA maths in the hull.
2. Pluggable signature-verifier hook — a caller-supplied verify function invoked only when native WebCrypto dispatch reports the algorithm unsupported. More general (works for any non-WebCrypto algorithm), keeps DSA code entirely out of the library, and slots into the existing unsupported fallback seam and the established opt-in-option pattern.

Chosen Option: 2

Rationale: It keeps the library zero-dependency and WebCrypto-native, is strictly additive, and reuses existing patterns rather than smuggling a whole bigint crypto engine aboard.

Design Choice 2: Do we need a new verify error code for the hook?

Options Considered:

1. Add a dedicated external_verifier_error code to VERIFY_ERROR_CODES (forces a matching row in site/guide/verification.md per the conventions test).
2. Reuse existing codes: no matching verifier → keep unsupported_signature_algorithm_parameters; verifier says invalid → ordinary invalid-signature failure path; verifier throws → treated as an invariant/verification error like today.

Chosen Option: 2

Rationale: Reuses existing typed outcomes, avoids widening the error union and the doc-sync churn, and keeps the change minimal.

💡 User Tips

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

Implementation Steps

Phase 1: Define and expose the pluggable verifier hook surface

This phase establishes the new opt-in public contract — a readonly function-typed hook that callers may supply — and threads it as an optional field through the public verification inputs, without touching any verification behaviour yet. The intent be a clean, typed, discoverable API that mirrors how existing opt-in options (policy, revocation) attach.

Task 1: Introduce the external signature-verifier type

Define the hook contract as a plain readonly function-typed struct, echoing the internal VerifyPathCallbacks idiom (no classes, no default exports).

• In src/verify/verify.ts, add a SignatureVerifier type describing an async verify function that receives the signature-algorithm OID (+ raw parameters DER), public-key-algorithm OID (+ parameters OID), the subject public key info DER, the signature bytes, and the signed data bytes, and returns a boolean-ish typed outcome (validated / not-validated / not-handled).
• Keep the shape algorithm-agnostic so a caller can support DSA or any other non-WebCrypto scheme; the library itself carries no DSA logic.
• Document via doc-comments that this hook be consulted only when native WebCrypto dispatch cannot handle the algorithm, and never overrides native verification.

Task 2: Add the opt-in option to public verification inputs

Wire the new hook as a conditional optional field, following the existing opt-in pattern.

• Add an optional signatureVerifiers?: readonly SignatureVerifier[] field to VerifyCertificateChainInput (and to the narrower buildCandidatePath input) in src/verify/verify.ts.
• Spread it conditionally into the inner path-building input exactly as policy/nameConstraints/revocation be spread today (...(input.signatureVerifiers !== undefined && { signatureVerifiers: input.signatureVerifiers })).

Task 3: Barrel and compile-guard review

Expose the new public type through the curated surfaces.

• Add SignatureVerifier to the explicit re-export lists in src/verify/index.ts and the curated root barrel src/index.ts.
• Add a corresponding assertion field in test/root-barrel.types.ts so the compile-time guard covers the new type.

🤖 Prompt for AI agents

Goal: establish the new opt-in public `SignatureVerifier` hook type and thread
it as an optional field through public verification inputs, with zero change to
actual verification behaviour in this phase.

- In `src/verify/verify.ts`, define a `SignatureVerifier` type as a readonly
function-typed struct (no classes, no default exports), following the internal
`VerifyPathCallbacks` idiom. The `verify` function should be async, accept the
signature-algorithm OID and raw parameters DER, the public-key-algorithm OID and
parameters OID, the subject public key info DER, the signature bytes, and the
signed data bytes, and return a typed outcome distinguishing validated /
not-validated / not-handled. Keep it fully algorithm-agnostic. Add doc-comments
explaining it is consulted only as a fallback when native WebCrypto dispatch
cannot handle the algorithm, and never overrides native verification.
- Add an optional `signatureVerifiers?: readonly SignatureVerifier[]` field to
`VerifyCertificateChainInput` and to the narrower `buildCandidatePath` input in
`src/verify/verify.ts`. Spread it conditionally into the inner path-building
input using the same pattern as `policy`/`nameConstraints`/`revocation` (only
include the key when `input.signatureVerifiers !== undefined`).
- Add `SignatureVerifier` to the explicit re-export lists in
`src/verify/index.ts` and in the curated root barrel `src/index.ts`.
- Add a corresponding assertion field in `test/root-barrel.types.ts` to extend
the compile-time guard to cover the new type.

Phase 2: Thread the hook to the crypto choke point and invoke it as a fallback

This phase carries the option down through the internal path-building layer and hooks it into the single signature-verification choke point, so a supplied verifier be consulted precisely when WebCrypto reports the algorithm unsupported. It also teaches the OID tables to recognise DSA so parsed output and hook matching be sensible.

Task 1: Recognise DSA at the ASN.1/label layer

Give parsing and reporting the vocabulary for DSA so callers can match on it, without adding any verification maths.

• Add DSA OID constants to src/internal/asn1/oids.ts (id-dsa 1.2.840.10040.4.1, and the dsa-with-sha1/224/256 signature OIDs), consistent with the already-in-scope RFC 5758 identifiers.
• Add matching human-readable entries to src/internal/crypto/algorithm-names.ts (describeSignatureAlgorithm/describePublicKeyAlgorithm) so parsed certificates label DSA instead of showing a bare OID.

Task 2: Consult the verifier hook at the sig-verify fallback

Invoke supplied verifiers only when native dispatch cannot handle the algorithm.

• Extend verifySignedDataDetailed in src/internal/crypto/sig-verify.ts to accept an optional list of SignatureVerifiers.
• When getVerifySignatureConfigResult returns unsupported, and one or more verifiers be supplied, hand the OIDs/SPKI/signature/signed-data to each in turn: the first that reports "validated" yields { ok: true, valid: true }; one that reports "invalid" yields { ok: true, valid: false }; none that handle the algorithm falls through to the existing unsupported_signature_algorithm_parameters result.
• Guard hook invocation so a thrown error be funnelled through the existing verification_error/invariant handling rather than crashing the walk.
• Preserve the throwing wrapper verifySignedData behaviour unchanged for callers that pass no verifiers.

Task 3: Thread the option through the chain-building path

Carry the verifiers from the public API down to the choke point.

• Add the optional signatureVerifiers field to the internal path input types in src/internal/verify/verify-path.ts and pass it through buildChainInternal into verifyCertificateSignature and matchTrustAnchor, which in turn forward it to verifySignedDataDetailed.
• Ensure the other internal callers of verifySignedDataDetailed that be not part of chain building (CSR self-signature, CRL/OCSP, PKCS#7) remain untouched — they simply omit the new argument and keep today's behaviour.

🤖 Prompt for AI agents

Goal: carry the `signatureVerifiers` option down through internal chain-building
into the single crypto choke point, and invoke supplied verifiers only as a
fallback when native WebCrypto dispatch cannot handle the algorithm. Also add
DSA OID/label recognition for tidy parsing output.

- Add DSA OID constants to `src/internal/asn1/oids.ts`: `id-dsa`
(`1.2.840.10040.4.1`) and the `dsa-with-sha1/224/256` signature OIDs, consistent
with the already-in-scope RFC 5758 identifiers.
- Add matching human-readable entries to
`src/internal/crypto/algorithm-names.ts`
(`describeSignatureAlgorithm`/`describePublicKeyAlgorithm`) so parsed
certificates label DSA instead of showing a bare OID.
- Extend `verifySignedDataDetailed` in `src/internal/crypto/sig-verify.ts` to
accept an optional list of `SignatureVerifier`s. When
`getVerifySignatureConfigResult` returns `unsupported` and one or more verifiers
are supplied, pass the OIDs/SPKI/signature/signed-data to each verifier in turn:
the first reporting "validated" yields `{ ok: true, valid: true }`; one
reporting "invalid" yields `{ ok: true, valid: false }`; if none handle the
algorithm, fall through to the existing
`unsupported_signature_algorithm_parameters` result.
- Guard hook invocation so any thrown error is funnelled through the existing
`verification_error`/invariant handling rather than crashing the walk.
- Preserve the throwing wrapper `verifySignedData` behaviour unchanged for
callers that pass no verifiers.
- Add the optional `signatureVerifiers` field to the internal path input types
in `src/internal/verify/verify-path.ts` and pass it through `buildChainInternal`
into `verifyCertificateSignature` and `matchTrustAnchor`, which forward it on to
`verifySignedDataDetailed`.
- Leave the other internal callers of `verifySignedDataDetailed` that are not
part of chain building (CSR self-signature, CRL/OCSP, PKCS#7) untouched — they
simply omit the new argument and keep today's behaviour.

Phase 3: Tests, documentation, and scope reconciliation

This phase proves the seam works, updates the claim-boundary and agent docs to reflect the new opt-in escape hatch, and records the change — because a fix that isn't documented and tested be no fix at all, and I'll not have it.

Task 1: Add hook verification tests

Exercise the new option with real fixtures and assert typed outcomes.

• In test/verify.test.ts (or a focused new test module alongside it), add a test that supplies a trivial stub SignatureVerifier and confirms a chain the library would otherwise reject with unsupported_signature_algorithm_parameters now validates; add a negative test where the verifier reports "invalid" and the chain fails via the ordinary invalid-signature path.
• Use the established static-DER fixture approach (as test/pkits.test.ts does) rather than WebCrypto key generation, since DSA keys cannot be generated in-process.
• In test/pkits.test.ts, keep the default it.failing markers for 4.1.4/4.1.5 (default behaviour unchanged), and add a separate case that runs those DSA vectors with a supplied verifier to demonstrate the hook path — proving the boundary flips only when a caller opts in.

Task 2: Update scope and agent documentation

Keep the claims aligned with shipped behaviour.

• Update docs/PKIX-SCOPE.md to record that DSA (and other non-WebCrypto algorithms) remain unsupported by default, with an explicit note that a caller-supplied signatureVerifiers hook exists as an opt-in escape hatch; retain the WebCrypto-boundary framing for 4.1.4/4.1.5.
• Update AGENTS.md (root) and src/AGENTS.md to record the new public extensibility mechanism in the verify domain, since it introduces a caller-supplied injectable option — a genuinely new cross-cutting seam that the agent docs require flagging.
• Note in site/reference/algorithms.md that DSA stays under "not supported" natively but can be handled via the hook.

Task 3: Record the change

Add an entry under ## [Unreleased] in CHANGELOG.md describing the new opt-in signatureVerifiers hook and reaffirming that the WebCrypto-native default be unchanged (no version bump unless a release be cut).

🤖 Prompt for AI agents

Goal: prove the new hook seam works with real tests, and reconcile documentation
and changelog with the shipped behaviour.

- In `test/verify.test.ts` (or a focused new test module alongside it), add a
test that supplies a trivial stub `SignatureVerifier` and confirms a chain the
library would otherwise reject with `unsupported_signature_algorithm_parameters`
now validates. Add a negative test where the verifier reports "invalid" and the
chain fails via the ordinary invalid-signature path. Use the established
static-DER fixture approach (as `test/pkits.test.ts` does), not WebCrypto key
generation, since DSA keys cannot be generated in-process.
- In `test/pkits.test.ts`, keep the default `it.failing` markers for
`4.1.4`/`4.1.5` (default behaviour must remain unchanged), and add a separate
case running those DSA vectors *with* a supplied verifier to demonstrate the
hook path, proving the boundary flips only when a caller opts in.
- Update `docs/PKIX-SCOPE.md` to record that DSA (and other non-WebCrypto
algorithms) remain unsupported by default, with an explicit note that a
caller-supplied `signatureVerifiers` hook exists as an opt-in escape hatch;
retain the WebCrypto-boundary framing for 4.1.4/4.1.5.
- Update `AGENTS.md` (root) and `src/AGENTS.md` to record the new public
extensibility mechanism in the verify domain, flagging it as a new
cross-cutting, caller-supplied injectable option.
- Note in `site/reference/algorithms.md` that DSA stays under "not supported"
natively but can be handled via the hook.
- Add an entry under `## [Unreleased]` in `CHANGELOG.md` describing the new
opt-in `signatureVerifiers` hook and reaffirming that the WebCrypto-native
default is unchanged (no version bump unless a release is cut).

Research

micro509 be a zero-dependency, ESM-only, WebCrypto-native X.509 library, savvy? All signature maths funnels through one choke point, verifySignedDataDetailed in src/internal/crypto/sig-verify.ts, whose getVerifySignatureConfigResult switch maps signature-algorithm OIDs to WebCrypto verify params and emits unsupported_signature_algorithm_parameters for anything unknown (DSA lands here today, arr). The public verifyCertificateChain in src/verify/verify.ts composes candidate-path building (buildCandidatePath → internal buildChainInternal/verifyCertificateSignature/matchTrustAnchor in src/internal/verify/verify-path.ts) with opt-in typed options. Opt-in features be plain optional fields threaded down into narrower inner inputs; injectable behaviour uses readonly function-typed structs (see internal VerifyPathCallbacks), never classes — we don't sail with classes here. Barrels (src/verify/index.ts, curated src/index.ts) and a compile guard (test/root-barrel.types.ts) govern the public surface, and site/guide/verification.md must mirror VERIFY_ERROR_CODES exactly, or there'll be mutiny.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Goal: establish the new opt-in public `SignatureVerifier` hook type and thread
it as an optional field through public verification inputs, with zero change to
actual verification behaviour in this phase.

- In `src/verify/verify.ts`, define a `SignatureVerifier` type as a readonly
function-typed struct (no classes, no default exports), following the internal
`VerifyPathCallbacks` idiom. The `verify` function should be async, accept the
signature-algorithm OID and raw parameters DER, the public-key-algorithm OID and
parameters OID, the subject public key info DER, the signature bytes, and the
signed data bytes, and return a typed outcome distinguishing validated /
not-validated / not-handled. Keep it fully algorithm-agnostic. Add doc-comments
explaining it is consulted only as a fallback when native WebCrypto dispatch
cannot handle the algorithm, and never overrides native verification.
- Add an optional `signatureVerifiers?: readonly SignatureVerifier[]` field to
`VerifyCertificateChainInput` and to the narrower `buildCandidatePath` input in
`src/verify/verify.ts`. Spread it conditionally into the inner path-building
input using the same pattern as `policy`/`nameConstraints`/`revocation` (only
include the key when `input.signatureVerifiers !== undefined`).
- Add `SignatureVerifier` to the explicit re-export lists in
`src/verify/index.ts` and in the curated root barrel `src/index.ts`.
- Add a corresponding assertion field in `test/root-barrel.types.ts` to extend
the compile-time guard to cover the new type.
===============================================================================

Task: 2

Goal: carry the `signatureVerifiers` option down through internal chain-building
into the single crypto choke point, and invoke supplied verifiers only as a
fallback when native WebCrypto dispatch cannot handle the algorithm. Also add
DSA OID/label recognition for tidy parsing output.

- Add DSA OID constants to `src/internal/asn1/oids.ts`: `id-dsa`
(`1.2.840.10040.4.1`) and the `dsa-with-sha1/224/256` signature OIDs, consistent
with the already-in-scope RFC 5758 identifiers.
- Add matching human-readable entries to
`src/internal/crypto/algorithm-names.ts`
(`describeSignatureAlgorithm`/`describePublicKeyAlgorithm`) so parsed
certificates label DSA instead of showing a bare OID.
- Extend `verifySignedDataDetailed` in `src/internal/crypto/sig-verify.ts` to
accept an optional list of `SignatureVerifier`s. When
`getVerifySignatureConfigResult` returns `unsupported` and one or more verifiers
are supplied, pass the OIDs/SPKI/signature/signed-data to each verifier in turn:
the first reporting "validated" yields `{ ok: true, valid: true }`; one
reporting "invalid" yields `{ ok: true, valid: false }`; if none handle the
algorithm, fall through to the existing
`unsupported_signature_algorithm_parameters` result.
- Guard hook invocation so any thrown error is funnelled through the existing
`verification_error`/invariant handling rather than crashing the walk.
- Preserve the throwing wrapper `verifySignedData` behaviour unchanged for
callers that pass no verifiers.
- Add the optional `signatureVerifiers` field to the internal path input types
in `src/internal/verify/verify-path.ts` and pass it through `buildChainInternal`
into `verifyCertificateSignature` and `matchTrustAnchor`, which forward it on to
`verifySignedDataDetailed`.
- Leave the other internal callers of `verifySignedDataDetailed` that are not
part of chain building (CSR self-signature, CRL/OCSP, PKCS#7) untouched — they
simply omit the new argument and keep today's behaviour.
===============================================================================

Task: 3

Goal: prove the new hook seam works with real tests, and reconcile documentation
and changelog with the shipped behaviour.

- In `test/verify.test.ts` (or a focused new test module alongside it), add a
test that supplies a trivial stub `SignatureVerifier` and confirms a chain the
library would otherwise reject with `unsupported_signature_algorithm_parameters`
now validates. Add a negative test where the verifier reports "invalid" and the
chain fails via the ordinary invalid-signature path. Use the established
static-DER fixture approach (as `test/pkits.test.ts` does), not WebCrypto key
generation, since DSA keys cannot be generated in-process.
- In `test/pkits.test.ts`, keep the default `it.failing` markers for
`4.1.4`/`4.1.5` (default behaviour must remain unchanged), and add a separate
case running those DSA vectors *with* a supplied verifier to demonstrate the
hook path, proving the boundary flips only when a caller opts in.
- Update `docs/PKIX-SCOPE.md` to record that DSA (and other non-WebCrypto
algorithms) remain unsupported by default, with an explicit note that a
caller-supplied `signatureVerifiers` hook exists as an opt-in escape hatch;
retain the WebCrypto-boundary framing for 4.1.4/4.1.5.
- Update `AGENTS.md` (root) and `src/AGENTS.md` to record the new public
extensibility mechanism in the verify domain, flagging it as a new
cross-cutting, caller-supplied injectable option.
- Note in `site/reference/algorithms.md` that DSA stays under "not supported"
natively but can be handled via the hook.
- Add an entry under `## [Unreleased]` in `CHANGELOG.md` describing the new
opt-in `signatureVerifiers` hook and reaffirming that the WebCrypto-native
default is unchanged (no version bump unless a release is cut).

💡 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!