ADR-0009: One canonical target parser and a versioned address corpus

Status: Historical proposal (original status: Proposed)
Date: 2026-10-08
Original decision makers: Project architecture/security owners; approval still pending in the original proposal.
Requirements: HG-007, HG-008, HG-009, HG-010, HG-011, HG-012
Original supersession: None; a new decision for the proposed product.

Note

This is the full English translation of the historical proposal dated 2026-10-08, originally Proposed. Its pending approval is historical and creates no additional alpha approval gate. Current Security model and limits, Development and tests, Verification report and Requirements and security invariants describe the operative scope and evidence.

The later single-package decision is recorded in ADR-0015: One installable extension.

Context

Parsers interpret noncanonical numeric addresses differently. The Host header and URI may disagree. A coarse private-IP filter does not cover every local or special address class. IANA maintains separate IPv4/IPv6 special-purpose registries.

Sources: [S04, S05, S10, S11].

Decision

The guard normalizes once, then uses a typed Target and applies the same authority to transport. Absolute HTTP/HTTPS URLs are mandatory; userinfo, fragments, control characters, zone IDs, host percent encoding and noncanonical numeric forms are rejected. After normalization, HTTP Host and URI authority must agree. Unicode hostnames are not implicitly converted in v1; ASCII IDNA names already converted canonically are permitted.

IP and CIDR checks use binary representations for both families. IPv4-mapped IPv6 is evaluated against the embedded IPv4 policy. Tunneling/translation ranges are conservatively blocked. The versioned corpus names private ranges, loopback, link-local, metadata relevance, multicast, documentation/benchmark and other special ranges.

The v1 public policy is deliberately more conservative than merely accepting the positive Globally-Reachable marking of individual special addresses. Operator deny can additionally block nominally public ranges routed internally. Registry updates are versioned, never downloaded live for every request.

Rejected alternatives

Regular expressions alone: unsuitable for comprehensive IP/CIDR decisions.
PHP filter flags alone: implicitly couples policy to their particular runtime semantics.
Private IPv4 without IPv6: leaves a second address family open.
Accept every parser correction: increases interpretation differences.

Consequences

There is one testable decision path and traceable dataset versions. Some legitimate special addresses and Unicode inputs are restricted; callers must supply canonical targets. A public IP still does not mean "a server whose content is trustworthy".

Evidence and acceptance in the original proposal

T008, T009, T010, T011, T012, T013, T014, T015, T016, T017, T018, T019, T020, T021. Details and expected results are in Original verification specification. These tests were specified, not executed as part of the original documentation delivery.

Reasons to reconsider

Relaxing a blocked address class or parser form requires a corpus change, justification and boundary tests. New IANA entries are treated like security-relevant dependency changes.