ADR-0005: Bind the checked address set directly to the connection

Status: Default-resolution proposal superseded by ADR-0017: Controlled DNS queries for the default resolver (original status: Proposed); connection-pinning principles retained.
Date: 2026-10-08
Original decision makers: Project architecture/security owners; approval still pending in the original proposal.
Requirements: HG-013, HG-014, HG-015, HG-016, HG-027, HG-044
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.

ADR-0017: Controlled DNS queries for the default resolver replaces the historical default-resolution proposal with the implemented DNS wire backend. The original address-set checks and connection-pinning principles are retained.

Context

A precheck and independent transport resolution can return different IPs. Vault addressed this with CURLOPT_RESOLVE and subsequently treated empty answers as failure. It nevertheless retains a literal allowlist exception. DNS and NSS/hosts resolution are not equivalent.

Sources: [S05-S07, S09, S19].

Decision

After normalization and policy checks, every attempt creates an immutable ConnectionPlan. All usable A/AAAA addresses are checked; one prohibited candidate rejects the entire attempt. No usable answer means denial, even for an approved host. Static host mappings also supply addresses that must be checked, not blanket permission.

The transport receives exactly that set in a multi-address pin for each host/port pair. The original hostname, TLS SNI and certificate validation are preserved. An unreachable pin must not trigger unchecked DNS fallback. Invalid records, pin formats or failed option setters must not be silently ignored.

Resolution scope and memoization are bounded. Synchronous dns_get_record() is not presented as a resolver that can be forcibly interrupted; operating-system limits and measured behavior form part of qualification.

Rejected alternatives

Fresh DNS before every send alone: still leaves a check-to-connect window.
Filter out only dangerous IPs: hides mixed trust zones and is rejected for v1.
Let an explicit host continue uncontrolled on DNS failure: violates the connection-bound guarantee.
Replace the URL with an IP: complicates correct host/TLS semantics.

Consequences

Selection is traceable and testable. Split-DNS configurations with mixed allowed/prohibited answers are deliberately denied. Names unknown to DNS need a static mapping or a resolver adapter certified later.

Evidence and acceptance in the original proposal

T022, T023, T024, T025, T026, T027, T028, T029, T030, T031, T032, T033, T078. 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

Additional resolvers may be included if they deliver candidates completely and within bounds, and never release transport resolution without control.