Expose the DNS-free half of SSRF validation, and a transport injection point on the client path

[KonstantinMirin]

Summary

Two pieces of SSRF machinery already exist in the SDK but are not reachable by an application that
wants to use them, so integrators end up either re-implementing the logic or leaving a dial ungated.
Both asks below are "expose what is already there" — no new policy, no behaviour change for existing
callers.

We hit both in a seller implementation where the rule is the application implements no SSRF policy
of its own; every outbound request goes through one seam that delegates to adcp.signing.

---

Ask 1 — resolve_and_validate_host couples four checks, three of which need no DNS

adcp/signing/jwks.py::resolve_and_validate_host (6.6.0) does four things in one call, and the
first three run entirely before socket.getaddrinfo:

1. scheme check (http/https only) — no DNS
2. host present + IDNA canonicalization — no DNS
3. port allowlist — no DNS
4. getaddrinfo, then per-IP checks (BLOCKED_METADATA_IPS, reserved ranges) — needs DNS

validate_jwks_uri is a thin no-return wrapper over the whole composition, so it exposes nothing
additional.

Use case: registration-time validation of a URL that will be dialled later

A buyer registers a webhook / callback URL. We must judge it at registration, when the buyer can
still fix it — but we must NOT resolve DNS at that moment, because a hostname whose DNS has not yet
propagated is legitimate and must be accepted; it is re-checked with DNS when the callback is
actually dialled.

Today the only public entry points resolve unconditionally, so registration either:

• rejects a valid not-yet-propagated hostname (wrong, and a support burden), or
• re-implements steps 1–3 locally — which is what we did, and it is exactly the duplicated
  address-policy the SDK exists to prevent. Our copy has already drifted from yours once.

Note step 4 is also usable without real DNS when the host is an IP literal: getaddrinfo returns
the literal, so literal-address rejection is available with no lookup — it is just entangled with
resolution.

Suggested design

Split, don't flag. Keep resolve_and_validate_host as the composition so no existing caller changes:

def validate_uri_static(uri, *, allowed_ports=None) -> str:
    """Scheme + host/IDNA + port. No DNS. Returns the canonicalized host."""

def validate_resolved_ip(ip, *, allow_private=False) -> None:
    """The per-IP policy: metadata blocklist + reserved ranges."""

def resolve_and_validate_host(uri, *, allow_private=False, allowed_ports=None):
    host = validate_uri_static(uri, allowed_ports=allowed_ports)
    ...  # getaddrinfo, then validate_resolved_ip per address

A resolve_dns: bool = True parameter would also work for us, but the split is nicer: it lets a
caller validate an IP it obtained some other way, and it keeps one definition of each policy.

---

Ask 2 — the client path has no public transport/client-factory injection

adcp/protocols/mcp.py::_streamable_http_client_factory picks the httpx client factory, but the only
way to influence it is signing_request_hook, which is set internally (client.py:571) and is about
request signing, not transport policy. AgentConfig and both client constructors expose nothing.

Use case: force every SDK dial through the same egress policy

We route all outbound HTTP through one seam. Any library that dials on our behalf silently bypasses
it. With ADCPMultiAgentClient we measured this directly: with our egress policy configured to
refuse loopback, a list_creative_formats against http://127.0.0.1:<port> produced three real
requests to that origin (/, /mcp, /mcp/) before an unrelated fallback path refused. The
packets left the process.

We cannot fix that from the outside today. Validate-then-connect is not a fix — it is a TOCTOU
window and it duplicates policy.

The frustrating part is that the SDK already ships the right primitive:
adcp/signing/ip_pinned_transport.py::IpPinnedTransport, whose own docstring says "pass this to
httpx.Client(transport=...) and everything else works unchanged". It just is not wired into the
client path.

Suggested design

Accept an httpx_client_factory (or a transport) on AgentConfig / the client constructors, and use
it in _streamable_http_client_factory when provided. fastmcp's StreamableHttpTransport already
takes exactly this parameter, so there is precedent in the immediate neighbourhood:

StreamableHttpTransport(url=..., httpx_client_factory=my_factory)

With that knob an integrator can hand you a client built on IpPinnedTransport (or their own
policy) and the SDK physically cannot dial around it.

---

Why these are one issue

Both are the same shape: the SDK has the correct logic, and an application that wants to use it
rather than reimplement it has no way in. Ask 1 makes the validation reusable; ask 2 makes the
enforcement unavoidable. Happy to send a PR for either if the shape above looks right.

Environment: adcp==6.6.0, Python 3.12.

[bokelley]

Triage

Classification: Feature request
Bucket(s): signing, client (labels absent from repo — gap noted in run summary)
Status: ready-for-human

What the experts said:

• security-reviewer: Blocker — when signing hook + custom factory are both active, signing event hook is silently dropped with no warning; needs composition or explicit error. Concerns: validate_uri_static name doesn't signal "incomplete SSRF check"; validate_resolved_ip must internally handle IPv4-mapped unwrapping (Python 3.10 bpo-44269 regression) and must be invoked on every resolved IP — not just the chosen one — to preserve reject-any-private semantics; injected factory can silently unset trust_env=False/follow_redirects=False.
• ad-tech-protocol-expert: Blocker — AgentConfig is the wrong seam; Pydantic raises PydanticSerializationError on JSON serialization of a non-None callable. Correct seam is ADCPClient.__init__(httpx_client_factory=...), mirroring signing=SigningConfig. Open question: IpPinnedTransport subclasses httpx.AsyncHTTPTransport but the MCP path uses httpx2.AsyncClient — type compatibility unverified.
• code-reviewer: Confirms both blockers. Ask 1 extraction is a clean refactor. validate_resolved_ip should accept ipaddress.IPv4Address | ipaddress.IPv6Address only (drop str to keep scope-id and unwrap responsibility clear). Both new functions need explicit wiring in signing/__init__.py (__all__ + import block) and dedicated unit tests — existing conformance tests go through the composition and would miss regressions in the split helpers.

My take: Both asks are architecturally sound and the SDK already has all the right primitives. Two design decisions need a human call before implementation: (1) injection seam — AgentConfig vs ADCPClient.__init__; (2) signing + factory composition strategy when both are active.

Flagging for @bokelley: security-sensitive surface (SSRF primitives), one blocker on signing composition, one blocker on serialization seam, and httpx vs httpx2 transport compatibility needs empirical verification.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[KonstantinMirin]

Fresh evidence for this, from reviewing the five security PRs (#999–#1003) — the drift you describe has now happened a second time, inside the SDK.

#1002 adds a fourth validator that reopens what #974 closed

src/adcp/server/a2a_push_security.py:26-52 gates destinations on not address.is_global:

>>> import ipaddress
>>> [ipaddress.ip_address(a).is_global for a in
...  ("192.88.99.1", "192.31.196.1", "192.52.193.1", "192.175.48.1", "2001:20::1")]
[True, True, True, True, True]

All five are in _EXTRA_BLOCKED_NETWORKS, added in #974 precisely because the interpreter's flags do not classify them as reserved. jwks.py:83-85 says so in this repo, verbatim:

not ip.is_global is NOT a usable substitute: it reports True (i.e. globally reachable) for the 6to4-relay, AS112, AMT and ORCHIDv2 ranges on every supported version, so it would close none of these holes.

The new module also skips DNS resolution, control-character and fragment rejection, enforces a 443-only port policy the pinned schema tells publishers not to enforce by default, and raises bare ValueError that a2a-sdk turns into -32603 InternalError — all of which adcp.webhooks.validate_webhook_destination_url already handles for this exact field.

The second consumer is the SDK's own server/ package

Your report is from an integrator outside the SDK. #1002 shows the same wrong turn taken from inside it, for the same reason:

• the classifier lives in a feature module — _EXTRA_BLOCKED_NETWORKS and resolve_and_validate_host are in signing/jwks.py, neither exported from adcp.signing.__init__, so nothing in server/ can discover them;
• validate_webhook_destination_url is exported and correct, and has 2 callers;
• src/adcp/server/ routes through neither guard, and A2A push was the first outbound surface to land there.

Writing a fresh check is easier than finding the existing one. That is the argument for Ask 1 restated from the other side of the boundary: it is not only integrators who cannot reach the DNS-free half.

src/adcp/canonical_formats/references.py:509-514 carries the same not ip.is_global predicate and predates all of this — a third site, in-tree, today.

One question on scope

Would you want the enforcement half in this issue, or separately? Ask 1 and Ask 2 give a caller the seam; nothing stops the next feature from skipping it. This repo already has the mechanism that makes a boundary hold — tests/test_import_layering.py enumerates the modules allowed to import generated_poc/, and it has not been re-litigated because it fails. The same shape here would be something like: no module outside the validation leaf may reference is_global / is_private / is_reserved, and no module may construct a bare httpx.AsyncClient.

Happy to take Ask 1 + Ask 2 as a PR if useful — Ask 1 is a pure split with no behaviour change for existing callers, which makes it a safe first step. Ordering note: it touches files #1002 also touches, so it is worth deciding which lands first.

[bokelley]

Triage (updated — new comment from @KonstantinMirin)

Classification: Feature request + Bug (existing, on main)
Bucket(s): signing, validation
Status: ready-for-human (unchanged)

Verified from code:
references.py:_validate_public_ip (lines 509–514) is a confirmed third in-tree bug site. It imports BLOCKED_METADATA_IPS from signing.jwks but uses not ip.is_global rather than _EXTRA_BLOCKED_NETWORKS. jwks.py:83–85 documents verbatim why is_global is insufficient for the 6to4-relay, AS112, AMT, and ORCHIDv2 ranges on every supported Python version. The function also skips the IPv4-mapped unwrap (bpo-44269) applied at jwks.py:304–309. Both gaps exist on main today. _EXTRA_BLOCKED_NETWORKS is not in signing/__init__.__all__, which explains why sibling modules can't reach it.

PR #1002 is claimed to add a2a_push_security.py with the same is_global pattern. The file is not on main and cannot be verified here, but the claim is fully consistent with the discoverability problem.

Scope update: Beyond Ask 1 + Ask 2 (API design, still needs a human call on seam and composition), there is a concrete pre-existing correctness bug in references.py:_validate_public_ip that does not depend on the seam decisions. It is security-sensitive and fixable independently.

@bokelley: two items — (1) references.py:509–514 bug confirmed on main; (2) worth checking the a2a_push_security.py claim before #1002 merges.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code