Semantic matching for otherName/x400Address/ediPartyName/registeredID name constraints

[kjanat]

Name constraints for otherName, x400Address, ediPartyName, and registeredID are currently handled fail-closed per RFC 5280 §4.2.1.10: a critical constraint of one of these forms rejects a subsequent certificate only when a SAN of that form actually appears (unsupported_name_constraints). That is spec-sanctioned and safe, but not semantic evaluation.

Semantic matching would mean actually comparing constraint subtrees against SAN values for these forms (e.g. registeredID OID equality, otherName type-id + value comparison). Real-world demand is near zero outside niche PKIs (e.g. UPN constraints in Microsoft environments via otherName), so this is demand-driven.

Additive — fail-closed behavior stays the fallback for anything still unsupported.

[coderabbitai]

Coding Plan

Summary

• Split the work cleanly along the existing x509 (parse/encode the forms) vs verify (compare them) boundary, addin' structured otherName/registeredID and promoting the four into the enforced constraint model.
• Match by exact equality — OID equality for registeredID and otherName type-ids, byte-equality for otherName values / x400Address / ediPartyName — because RFC 5280 defines no richer semantics.
• Key otherName relevance on type-id to prevent spurious cross-form rejection, and keep the fail-closed path as the genuine fallback for anything still un-decodable.
• Keep it additive and honest: update the scope matrix, changelog, and tests so shipped behaviour and documentation stay perfectly in step. A tidy hold at last. 🏴‍☠️

Design Choices

Design Choice 1: What "semantic matching" means for forms RFC 5280 never defines, arrr

Options Considered:

1. Exact equality — OID string equality for registeredID and for the otherName type-id, raw DER byte-equality for the otherName value / x400Address / ediPartyName payloads.
2. Attempt structured/normalised comparison per form (e.g. decode UPN UTF8String, canonicalise x.400 ORAddress).

Chosen Option: 1

Rationale: Exact equality be the only interpretation the RFC sanctions, matches the near-zero demand profile, and avoids inventin' normalisation rules no spec agrees on. A tidy choice, this be!

Design Choice 2: How otherName subtrees decide which SANs they constrain

Options Considered:

1. Key otherName relevance on the type-id OID as well, so a subtree only constrains SANs bearing the same type-id.
2. Treat every otherName as one bucket (any otherName SAN must match some otherName subtree).

Chosen Option: 1

Rationale: Treatin' distinct type-ids as distinct namespaces mirrors how the different top-level name forms never cross-constrain, and prevents surprise over-rejection (e.g. an SRV-ID SAN under a UPN-only constraint). Shipshape logic, that.

Design Choice 3: First-class SAN variants for the exotic pair

Options Considered:

1. Keep them flowing through the existing unknown SAN variant (tags 0xa3/0xa5) and map them to checkable byte-equality forms only at evaluation time.
2. Add first-class x400Address/ediPartyName SubjectAltName variants.

Chosen Option: 1

Rationale: Avoids widenin' the public SAN union for forms nobody encodes, preserves round-trip fidelity, and keeps byte-equality matchin' trivial. New first-class variants be added only for otherName/registeredID, which carry real structure and demand.

💡 User Tips

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

Implementation Steps

Phase 1: Chart the waters — parser and type model (x509 domain)

This phase teaches the x509 layer to recognise the four forms instead of dumpin' them into raw buckets. The objective be a faithful, round-trippable typed representation: otherName split into type-id + value, registeredID decoded to an OID string, and the exotic pair carried as opaque bytes — all so the verify layer has something meaningful to compare. All decoding stays inside parse.ts/extensions.ts per the "no ad-hoc extension decoding elsewhere" rule.

Task 1: Give SubjectAltName typed otherName and registeredID variants

Extend the public SAN union so real, structured otherName/registeredID SANs stop collapsing into unknown.

• In src/x509/extensions.ts, add two discriminated variants to SubjectAltName/GeneralName: { type: 'otherName', oid: string, value: Uint8Array } (value = raw DER of the otherName value element) and { type: 'registeredID', value: string } (decoded dotted-OID), mirroring how ParsedNameConstraintForm already models these.
• Update encodeSubjectAltName with matching cases: rebuild otherName [0] { type-id OID, <raw value TLV> } generically (the existing hardcoded srv case is the template) and encode registeredID [8] as a primitive OID; extend the exhaustive never guard.
• Keep srv and unknown intact for backward compatibility and for genuinely unknown tags.

Task 2: Promote the four forms from "unsupported" to enforceable constraint forms

Move the four constraint forms into the enforced model so the engine can match them, and enrich otherName with its type-id.

• In src/x509/extensions.ts, fold otherName (now { oid, value }), x400Address, ediPartyName, and registeredID into NameConstraintForm; shrink/retire UnsupportedNameConstraintForm accordingly while keeping ParsedNameConstraintForm coherent.
• Update the inlined default generic unions on GeneralSubtree and NameConstraints to include the newly-enforced forms (this is what widens InitialNameConstraintsInput).
• Extend encodeNameConstraintForm's exhaustive switch to serialise the four forms.

Task 3: Decode the forms during parsing

Make the parser split otherName into type-id + value on both the SAN and constraint sides, and decode registeredID.

• In src/x509/parse.ts, update parseOtherName/parseGeneralName so a non-SRV otherName [0] decodes to the generic otherName variant (type-id OID + raw value element bytes) instead of falling through to unknown, and add a 0x88 case decoding registeredID to an OID string.
• Update parseNameConstraintGeneralName's 0xa0 branch to decode the type-id + value (matching the SAN shape) rather than storing the whole element as raw bytes; leave 0xa3/0xa5 as raw bytes and 0x88 as the already-decoded OID.
• Preserve the srv special-case (id-on-dnsSRV) and the throw for genuinely unassigned tags.

🤖 Prompt for AI agents

Implement the parser and type-model changes in the `x509` domain so the four
cursed name-constraint forms (`otherName`, `x400Address`, `ediPartyName`,
`registeredID`) are recognised and round-trippable, rather than falling into raw
catch-all buckets. All decoding logic stays confined to
`parse.ts`/`extensions.ts`.

1. In `src/x509/extensions.ts`:
- Add two new discriminated `SubjectAltName`/`GeneralName` variants: `{ type:
'otherName', oid: string, value: Uint8Array }` (value holds the raw DER of the
otherName value element) and `{ type: 'registeredID', value: string }` (a
decoded dotted-OID string), mirroring the existing `ParsedNameConstraintForm`
modelling.
- Update `encodeSubjectAltName` with matching encode cases: generically rebuild
`otherName [0] { type-id OID, <raw value TLV> }` (use the existing hardcoded
`srv` case as the template), and encode `registeredID [8]` as a primitive OID.
Extend the exhaustive `never` guard accordingly.
- Keep the existing `srv` and `unknown` variants intact for backward
compatibility and genuinely unknown tags.
- Fold `otherName` (now `{ oid, value }`), `x400Address`, `ediPartyName`, and
`registeredID` into `NameConstraintForm`, shrinking/retiring
`UnsupportedNameConstraintForm` accordingly while keeping
`ParsedNameConstraintForm` coherent.
- Update the inlined default generic unions on `GeneralSubtree` and
`NameConstraints` to include the newly enforced forms (this widens
`InitialNameConstraintsInput`).
- Extend `encodeNameConstraintForm`'s exhaustive switch to serialise the four
forms.

2. In `src/x509/parse.ts`:
- Update `parseOtherName`/`parseGeneralName` so a non-SRV `otherName [0]`
decodes into the new generic `otherName` variant (type-id OID + raw value
element bytes) instead of falling through to `unknown`.
   - Add a `0x88` case decoding `registeredID` into an OID string.
- Update `parseNameConstraintGeneralName`'s `0xa0` branch to decode the type-id
+ value (matching the SAN shape) instead of storing the whole element as raw
bytes; leave `0xa3`/`0xa5` as raw bytes and `0x88` as the already-decoded OID.
- Preserve the `srv` special-case (id-on-dnsSRV) and keep throwing for genuinely
unassigned tags.

Phase 2: Man the guns — semantic matching engine (verify domain)

This phase makes the engine actually compare constraints against SANs usin' the exact-equality rules, while keepin' the fail-closed path as the fallback for anything that still can't be reduced to a checkable form. Objective: correct, conservative matching that neither over-widens trust nor spuriously rejects unrelated forms.

Task 1: Add a shared byte-equality helper

Provide one pure comparison utility for raw-DER equality instead of a fifth private copy.

• Add a small, pure bytesEqual helper under src/internal/shared/ (e.g. a new bytes.ts), keeping to the "pure and deterministic, no policy" rule for that folder.
• This backs otherName value, x400Address, and ediPartyName comparison.

Task 2: Teach the matcher the new forms

Flip the support gate and add per-form matchers plus their dispatch and formatting.

• In src/internal/verify/name-constraints-engine.ts, update isSupportedNameConstraintForm to return true for the four forms (and drop them from the "unsupported" arm).
• Add per-type matchers: registeredID (OID string equality via the idiomatic decodeObjectIdentifier(...) === OIDS.foo style), otherName (type-id OID equality and value byte-equality), x400Address/ediPartyName (byte-equality); wire them into nameMatchesConstraint.
• Extend formatConstraintForm with human-readable labels for the four forms for error messages.

Task 3: Feed SANs into matching and preserve the fail-closed fallback

Convert SAN variants to checkable forms, key otherName relevance on type-id, and keep the fallback intact.

• In sanToConstraintCheckable, map the new otherName/registeredID SAN variants to checkable forms; fold srv into an otherName checkable form (type-id = id-on-dnsSRV) so SRV-ID SANs participate coherently; map unknown SANs with tags 0xa3/0xa5 to x400Address/ediPartyName byte forms.
• Refine isNamePermitted so otherName "relevance" also matches on the type-id OID (per Assumption 2), preventing unrelated otherName type-ids from over-constraining one another.
• Keep sanUnsupportedFormType + unsupportedCriticalForms wiring so a genuinely un-decodable unknown-tag SAN meeting a critical unprocessable constraint still fails closed — the fallback the ticket insists on.

🤖 Prompt for AI agents

Implement semantic matching for the four forms in the `verify` domain engine,
comparing constraint subtrees against certificate SAN values by exact equality,
while keeping the fail-closed path as the genuine fallback for anything still
un-decodable.

1. Add a shared pure helper: create `src/internal/shared/bytes.ts` exporting a
`bytesEqual` function for raw-DER byte comparison, following the "pure and
deterministic, no policy" rule for that folder. This backs `otherName` value,
`x400Address`, and `ediPartyName` comparison.

2. In `src/internal/verify/name-constraints-engine.ts`:
- Update `isSupportedNameConstraintForm` to return `true` for the four forms
(`otherName`, `x400Address`, `ediPartyName`, `registeredID`), removing them from
the "unsupported" arm.
- Add per-form matchers: `registeredID` uses OID string equality (idiomatic
`decodeObjectIdentifier(...) === OIDS.foo` style); `otherName` requires both
type-id OID equality AND value byte-equality; `x400Address`/`ediPartyName` use
byte-equality. Wire all of these into `nameMatchesConstraint`.
- Extend `formatConstraintForm` with human-readable labels for the four forms,
for use in error messages.
- In `sanToConstraintCheckable`, map the new `otherName`/`registeredID` SAN
variants to checkable forms. Fold `srv` into an `otherName` checkable form
(using type-id = id-on-dnsSRV) so SRV-ID SANs participate coherently. Map
`unknown` SANs with tags `0xa3`/`0xa5` to `x400Address`/`ediPartyName` byte
forms.
- Refine `isNamePermitted` so `otherName` relevance also matches on the type-id
OID, per the assumption that distinct type-ids are distinct namespaces — this
prevents unrelated otherName type-ids from over-constraining each other.
- Keep the `sanUnsupportedFormType` + `unsupportedCriticalForms` wiring intact
so a genuinely un-decodable `unknown`-tag SAN meeting a critical unprocessable
constraint still fails closed.

Phase 3: Log the voyage — inputs, tests, docs

Wire the caller-facing initial-constraints validation, prove the behaviour with tests (the bit that makes a perfectionist genuinely happy), and keep the scope docs honest so we don't over- or under-claim.

Task 1: Accept the new forms as initial constraint inputs

Let callers seed trust-anchor-level constraints of these forms.

• Update describeInvalidInitialNameConstraintForm in src/verify/verify.ts to validate/accept the four forms' field shapes at runtime (otherName oid+value, registeredID oid string, x400/ediParty bytes), so valid inputs reach the engine instead of being rejected as malformed.
• Widen the hand-written leafSubjectAltNames helper union in test/helpers.ts so tests can attach the new SAN variants.

Task 2: Prove it with tests

Cover semantic accept/reject and the retained fallback.

• Add semantic cases to test/name-constraints.test.ts: registeredID OID match/mismatch, otherName (UPN-style) type-id + value match/mismatch and type-id mismatch (should not cross-constrain), and x400Address/ediPartyName byte match/mismatch — asserting ok: true on match and name_constraints_violated on mismatch.
• Update the affected fail-closed cases in test/verify.test.ts to reflect that these forms now match semantically, while retaining/adding a case that still yields unsupported_name_constraints for a genuinely un-decodable unknown-tag SAN under a critical unprocessable constraint.
• Add parser round-trip assertions in test/parse.test.ts for the new SAN decoding.

Task 3: Keep the scope docs and changelog shipshape

Align the claim doc and record the change.

• Update docs/PKIX-SCOPE.md §5: change the four matrix rows' "Validator role" from "fail closed when critical and form appears" to the new enforce semantics (with fail-closed noted as the fallback), and reword the checklist bullet's parenthetical accordingly.
• Add an ### Added entry under ## [Unreleased] in CHANGELOG.md describing the new semantic matching (leave the version bump to release time per the crew's checklist).
• No AGENTS.md edits expected — logic stays within its established domain modules; touch them only if responsibilities actually shift.

🤖 Prompt for AI agents

Wire caller-facing initial-constraints validation, add thorough test coverage,
and update scope/changelog documentation to reflect the new semantic matching
behaviour.

1. In `src/verify/verify.ts`, update `describeInvalidInitialNameConstraintForm`
to validate/accept the four forms' field shapes at runtime (otherName oid+value,
registeredID oid string, x400/ediParty bytes) so valid inputs reach the engine
instead of being rejected as malformed.

2. In `test/helpers.ts`, widen the hand-written `leafSubjectAltNames` helper
union so tests can attach the new SAN variants.

3. Add tests:
- In `test/name-constraints.test.ts`, add semantic cases: registeredID OID
match/mismatch; otherName (UPN-style) type-id + value match/mismatch and a
type-id mismatch case (must not cross-constrain); x400Address/ediPartyName byte
match/mismatch. Assert `ok: true` on match and `name_constraints_violated` on
mismatch.
- In `test/verify.test.ts`, update the affected fail-closed cases to reflect
that these forms now match semantically, while retaining or adding a case that
still yields `unsupported_name_constraints` for a genuinely un-decodable
`unknown`-tag SAN under a critical unprocessable constraint.
- In `test/parse.test.ts`, add parser round-trip assertions for the new SAN
decoding.

4. Update documentation:
- In `docs/PKIX-SCOPE.md` §5, change the four matrix rows' "Validator role" from
"fail closed when critical and form appears" to the new enforce semantics
(noting fail-closed as the fallback), and reword the checklist bullet's
parenthetical accordingly.
- In `CHANGELOG.md`, add an `### Added` entry under `## [Unreleased]` describing
the new semantic matching (leave the version bump to release time).
- Do not edit `AGENTS.md` unless responsibilities actually shift out of their
established domain modules.

Research

Name-form parsing lives in the x509 domain (src/x509/parse.ts, src/x509/extensions.ts), while constraint evaluation lives in verify (src/verify/verify.ts wiring, with the real engine at src/internal/verify/name-constraints-engine.ts) — a boundary the crew's AGENTS.md guards jealously.

Today SubjectAltName decodes only dns/ip/email/uri/srv/directoryName plus an unknown raw-bytes catch-all; the constraint model splits forms into an enforced NameConstraintForm (five forms) and a parse-only UnsupportedNameConstraintForm (the four in this ticket).

The engine's isSupportedNameConstraintForm gate keeps the four out of matching, and checkCertificateNames fails closed via sanUnsupportedFormType + unsupportedCriticalForms when a critical unsupported form meets a matching SAN.

RFC 5280 deliberately leaves comparison semantics for these forms undefined, so "semantic matching" here means exact equality. Scope claims are pinned in docs/PKIX-SCOPE.md §5; no barrel/convention test snapshots the union variants, so the compiler's exhaustive never switches are the real guardrails.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the parser and type-model changes in the `x509` domain so the four
cursed name-constraint forms (`otherName`, `x400Address`, `ediPartyName`,
`registeredID`) are recognised and round-trippable, rather than falling into raw
catch-all buckets. All decoding logic stays confined to
`parse.ts`/`extensions.ts`.

1. In `src/x509/extensions.ts`:
- Add two new discriminated `SubjectAltName`/`GeneralName` variants: `{ type:
'otherName', oid: string, value: Uint8Array }` (value holds the raw DER of the
otherName value element) and `{ type: 'registeredID', value: string }` (a
decoded dotted-OID string), mirroring the existing `ParsedNameConstraintForm`
modelling.
- Update `encodeSubjectAltName` with matching encode cases: generically rebuild
`otherName [0] { type-id OID, <raw value TLV> }` (use the existing hardcoded
`srv` case as the template), and encode `registeredID [8]` as a primitive OID.
Extend the exhaustive `never` guard accordingly.
- Keep the existing `srv` and `unknown` variants intact for backward
compatibility and genuinely unknown tags.
- Fold `otherName` (now `{ oid, value }`), `x400Address`, `ediPartyName`, and
`registeredID` into `NameConstraintForm`, shrinking/retiring
`UnsupportedNameConstraintForm` accordingly while keeping
`ParsedNameConstraintForm` coherent.
- Update the inlined default generic unions on `GeneralSubtree` and
`NameConstraints` to include the newly enforced forms (this widens
`InitialNameConstraintsInput`).
- Extend `encodeNameConstraintForm`'s exhaustive switch to serialise the four
forms.

2. In `src/x509/parse.ts`:
- Update `parseOtherName`/`parseGeneralName` so a non-SRV `otherName [0]`
decodes into the new generic `otherName` variant (type-id OID + raw value
element bytes) instead of falling through to `unknown`.
   - Add a `0x88` case decoding `registeredID` into an OID string.
- Update `parseNameConstraintGeneralName`'s `0xa0` branch to decode the type-id
+ value (matching the SAN shape) instead of storing the whole element as raw
bytes; leave `0xa3`/`0xa5` as raw bytes and `0x88` as the already-decoded OID.
- Preserve the `srv` special-case (id-on-dnsSRV) and keep throwing for genuinely
unassigned tags.
===============================================================================

Task: 2

Implement semantic matching for the four forms in the `verify` domain engine,
comparing constraint subtrees against certificate SAN values by exact equality,
while keeping the fail-closed path as the genuine fallback for anything still
un-decodable.

1. Add a shared pure helper: create `src/internal/shared/bytes.ts` exporting a
`bytesEqual` function for raw-DER byte comparison, following the "pure and
deterministic, no policy" rule for that folder. This backs `otherName` value,
`x400Address`, and `ediPartyName` comparison.

2. In `src/internal/verify/name-constraints-engine.ts`:
- Update `isSupportedNameConstraintForm` to return `true` for the four forms
(`otherName`, `x400Address`, `ediPartyName`, `registeredID`), removing them from
the "unsupported" arm.
- Add per-form matchers: `registeredID` uses OID string equality (idiomatic
`decodeObjectIdentifier(...) === OIDS.foo` style); `otherName` requires both
type-id OID equality AND value byte-equality; `x400Address`/`ediPartyName` use
byte-equality. Wire all of these into `nameMatchesConstraint`.
- Extend `formatConstraintForm` with human-readable labels for the four forms,
for use in error messages.
- In `sanToConstraintCheckable`, map the new `otherName`/`registeredID` SAN
variants to checkable forms. Fold `srv` into an `otherName` checkable form
(using type-id = id-on-dnsSRV) so SRV-ID SANs participate coherently. Map
`unknown` SANs with tags `0xa3`/`0xa5` to `x400Address`/`ediPartyName` byte
forms.
- Refine `isNamePermitted` so `otherName` relevance also matches on the type-id
OID, per the assumption that distinct type-ids are distinct namespaces — this
prevents unrelated otherName type-ids from over-constraining each other.
- Keep the `sanUnsupportedFormType` + `unsupportedCriticalForms` wiring intact
so a genuinely un-decodable `unknown`-tag SAN meeting a critical unprocessable
constraint still fails closed.
===============================================================================

Task: 3

Wire caller-facing initial-constraints validation, add thorough test coverage,
and update scope/changelog documentation to reflect the new semantic matching
behaviour.

1. In `src/verify/verify.ts`, update `describeInvalidInitialNameConstraintForm`
to validate/accept the four forms' field shapes at runtime (otherName oid+value,
registeredID oid string, x400/ediParty bytes) so valid inputs reach the engine
instead of being rejected as malformed.

2. In `test/helpers.ts`, widen the hand-written `leafSubjectAltNames` helper
union so tests can attach the new SAN variants.

3. Add tests:
- In `test/name-constraints.test.ts`, add semantic cases: registeredID OID
match/mismatch; otherName (UPN-style) type-id + value match/mismatch and a
type-id mismatch case (must not cross-constrain); x400Address/ediPartyName byte
match/mismatch. Assert `ok: true` on match and `name_constraints_violated` on
mismatch.
- In `test/verify.test.ts`, update the affected fail-closed cases to reflect
that these forms now match semantically, while retaining or adding a case that
still yields `unsupported_name_constraints` for a genuinely un-decodable
`unknown`-tag SAN under a critical unprocessable constraint.
- In `test/parse.test.ts`, add parser round-trip assertions for the new SAN
decoding.

4. Update documentation:
- In `docs/PKIX-SCOPE.md` §5, change the four matrix rows' "Validator role" from
"fail closed when critical and form appears" to the new enforce semantics
(noting fail-closed as the fallback), and reword the checklist bullet's
parenthetical accordingly.
- In `CHANGELOG.md`, add an `### Added` entry under `## [Unreleased]` describing
the new semantic matching (leave the version bump to release time).
- Do not edit `AGENTS.md` unless responsibilities actually shift out of their
established domain modules.

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