---
title: "ADR-0005: Bind the checked address set directly to the connection"
manual: "HTTP Guard"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-0005@main"
source: "Adr/ADR-0005-DnsAndConnectionPlan.rst"
rendered: "2026-10-18T14:31:38+00:00"
---

# ADR-0005: Bind the checked address set directly to the connection {#adr-0005}

-   *Status:*

    Default-resolution proposal superseded by [ADR-0017: Controlled DNS queries for the default resolver](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-0017@main)
    (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](https://docs.typo3.org/permalink/netresearch/nr-http-guard:security@main), [Development and tests](https://docs.typo3.org/permalink/netresearch/nr-http-guard:development@main), [Verification report](https://docs.typo3.org/permalink/netresearch/nr-http-guard:verification-report@main) and
> [Requirements and security invariants](https://docs.typo3.org/permalink/netresearch/nr-http-guard:development-requirements@main) describe the operative scope and evidence.
>
> The later single-package decision is recorded in [ADR-0015: One installable extension](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-0015@main).
>
> [ADR-0017: Controlled DNS queries for the default resolver](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-0017@main) replaces the historical default-resolution proposal with
> the implemented DNS wire backend. The original address-set checks and
> connection-pinning principles are retained.

## Context {#adr-0005-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 {#adr-0005-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 {#adr-0005-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 {#adr-0005-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 {#adr-0005-verification-and-acceptance}

`T022, T023, T024, T025, T026, T027, T028, T029, T030, T031, T032, T033, T078`.
Details and expected results are in [Original verification specification](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/06-verification.md).
These tests were specified, not executed as part of the original documentation
delivery.

## Reasons to reconsider {#adr-0005-reassessment-trigger}

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

## Related documents {#adr-0005-related-documents}

[Original ADR](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/adr/ADR-0005-dns-und-connection-plan.md), [Original product requirements](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/01-product-requirements.md), [Original security model](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/02-security-model.md),
[Original architecture](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/03-architecture.md) and [Original source catalogue](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/specification/specs/08-evidence-and-sources.md) (`S01-S23`),
plus the [ADR index](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-index@main). [Original sources](https://docs.typo3.org/permalink/netresearch/nr-http-guard:adr-original-sources@main) explains
the immutable source index.