[Task]: Prepare URL validation infrastructure for agent card and webhook SSRF protection

[ishymko]

Context

We have two places which can benefit from SSRF protection:

1. Client: fetching agent cards and using URLs to make A2A calls (brought in fix(security): SSRF via AgentCard URL and context ID Injection (A2A-SSRF-01, A2A-INJ-01) #895, filed a separate issue [Feat]: Agent card validation hook #975).
2. Push notification webhooks URLs (Security Improvement: Add SSRF protection for Push Notification webhooks and authorization checks for Task operations #786): there is a spec statement about SSRF protection there.

Description

Both cases above can share domain agnostic machinery for URL validation.

The following requirements apply:

1. Composable: local addresses are perfectly fine for some deployments.
2. Validation should happen before the actual invocation and invocation should use "pinned" IP to protect from DNS rebinding.
3. Built-in rules: RequireScheme (to restrict HTTP(S)-only or HTTPS-only), BlockPrivateNetworks (with allowlist for deployments where using private networks is a legitimate use-case).

This issue scopes to UrlValidator only and should be a foundation for #975 and #786 where appropriate domain validators are going to be implemented.

flowchart TB
    subgraph Wrappers["Domain wrappers (own which fields to validate + domain error type)"]
        direction LR
        PN["PushNotificationUrlValidator"]
        AC["AgentCardUrlValidator"]
    end
    V["UrlValidator<br/>parse → resolve → run rules in order<br/>(rule raises = reject, returns = continue)"]
    subgraph Rules["Composable rules"]
        direction LR
        RS["RequireScheme"]
        BPN["BlockPrivateNetworks<br/>(allow_hosts, allow_cidrs)"]
        CR["…custom…"]
    end
    PN --> V
    AC --> V
    V --> Rules
    class PN,AC wrap
    class V core
    class RS,BPN,HD,CR rule

Loading

Sketch:

class InvalidUrlError(ValueError):
    """Raised by UrlValidator.validate when a URL is rejected."""

class UrlValidationRule(ABC):
    @abstractmethod
    async def check(self, url: ResolvedUrl) -> None:
        """Raise InvalidUrlError to reject url."""

class ResolvedUrl:
    raw: str
    parsed: SplitResult
    addresses: tuple[IpAddress, ...]


class UrlValidator:
    def __init__(
        self,
        rules: Sequence[UrlValidationRule] = (),
        resolve: bool = True,
    ) -> None:    
    . . .

    async def validate(self, url: str) -> ResolvedUrl:
        # Conditionally resolves IPs via getaddrinfo
        resolved = await self._build(url)

        # Just runs all rules one by one, they throw to stop
        for rule in self._rules:
            await rule.check(resolved)

        # Returns URL so that pinned address can be used
        return resolved

[Ryujiyasu]

Thanks for spinning this out, @ishymko — happy to see the shared infrastructure land before the per-domain wrappers. A few thoughts from the threat-modeling side of #786:

1. How does ResolvedUrl.addresses actually get used by the caller?

The sketch returns the resolved addresses but doesn't pin httpx to them. Without an explicit pinning mechanism (e.g., a custom httpx.BaseTransport that rewrites request.url.host to the validated IP while preserving the Host header and TLS SNI — see Drawbridge for prior art), there's still a TOCTOU window between getaddrinfo and the actual socket.connect. Worth making this part of the contract, not an exercise for downstream implementers.

2. Redirect handling.

The current design is silent on redirects. Established practice (GitLab, Drawbridge, Advocate) is to re-validate every hop, not disable redirects. pyload-ng's CVE-2026-35459 is a recent reminder of what happens when this is skipped. Suggest the validator either owns the redirect loop or documents that callers MUST run each Location back through validate().

3. BlockPrivateNetworks is not enough on its own.

ipaddress.IPv6Address.is_private has known gaps that an SSRF-focused blocklist needs to handle explicitly:

• NAT64 64:ff9b::/96 (64:ff9b::a9fe:a9fe reaches AWS IMDS but is_private=False)
• 6to4 2002::/16 (embedded IPv4 not extracted by .ipv4_mapped)
• CGNAT 100.64.0.0/10 (covers Alibaba metadata 100.100.100.200)

And cloud metadata endpoints worth treating as first-class blocks even though some are technically link-local:

• AWS ECS task credentials 169.254.170.2
• Oracle Cloud 192.0.0.192 (RFC 7600 — not link-local!)
• Alibaba 100.100.100.200 (CGNAT — not RFC 1918)

A BlockCloudMetadata rule alongside BlockPrivateNetworks might be worth surfacing given how often this is the actual exploit target.

4. getaddrinfo resolution policy.

Suggest getaddrinfo(host, None, AF_UNSPEC) and rejecting if any returned address fails — Craft CMS GHSA-v2gc-rm6g-wrw9 is the canonical example of what goes wrong when only the v4 record is checked.

---

Happy to help draft the test matrix for the Push Notification wrapper once the core validator lands. Also happy to take a stab at a PR for either side if that's useful — let me know what would fit your workflow.