adagents.json discovery: follow same-registrable-domain redirects on .well-known, refuse on authoritative_location (adcp#5450)

[bokelley]

Context

AdCP issue adcontextprotocol/adcp#5450 and merged spec PR adcontextprotocol/adcp#5472 define the redirect policy for adagents.json discovery. The reference validator in adcontextprotocol/adcp is now aligned; this SDK needs the same behavior so all AdCP implementations resolve discovery identically.

The bug this fixes: a publisher whose apex domain 301-redirects to www (the default on most managed hosting / CDNs) is silently reported unauthorized by validators that refuse all redirects on the discovery fetch.

Policy — two hops, deliberately different

Fetch	Redirect policy
Initial https://{domain}/.well-known/adagents.json	Follow same-registrable-domain redirects (apex↔www, HTTPS-preserving, ≤3 hops), re-validating SSRF (reject non-HTTPS, reject reserved/private IPs, pin connect) on every hop, with the same-domain comparison anchored on the originally-requested domain at every hop (not the previous hop). Refuse cross-registrable-domain redirects — that is an unscoped delegation signal; the publisher should declare delegation via authoritative_location instead.
authoritative_location dereference (2nd hop)	Refuse all redirects. The named URL is the declared authoritative location; a redirect away from it changes that declaration and MUST be treated as an error.

⚠️ Security-critical: use the PSL private section

Registrable-domain comparison MUST use the Public Suffix List including its PRIVATE section. Without it, shared-hosting tenants collapse to one registrable domain — victim.github.io and attacker.github.io both reduce to github.io — and a cross-tenant redirect would be wrongly followed and trusted as authoritative. The same applies to *.pages.dev, *.web.app, *.herokuapp.com, *.wordpress.com, etc. The reference impl uses tldts.getDomain(host, { allowPrivateDomains: true }).

Conformance

Gate on the shared cross-SDK vectors: static/test-vectors/adagents-discovery-redirects.json. They cover apex↔www, subdomain, co.uk (ICANN multi-label), *.github.io (PSL private section), same→cross two-hop (origin-anchored), HTTPS downgrade, hop cap, and the authoritative-location refuse-all rule. The normative assertion per vector is result (resolved vs refused).

This SDK (adcp-go)

Locate the adagents.json / .well-known discovery fetch and apply the policy above.

• .well-known fetch → follow same-registrable-domain redirects (≤3 hops, per-hop SSRF, anchored on origin), refuse cross-domain. The Go http.Client follows redirects by default — implement a CheckRedirect that enforces the same-domain + HTTPS + hop-cap rules, or follow manually.
• authoritative_location dereference → set CheckRedirect to refuse (return http.ErrUseLastResponse / an error).
• PSL private section: golang.org/x/net/publicsuffix does not include private-section control; use github.com/weppos/publicsuffix-go with IncludePrivateDomains: true (or equivalent) so shared-hosting tenants are distinct registrants.

Acceptance: the discovery path passes every vector in adagents-discovery-redirects.json.

[bokelley]

Triage

Classification: Bug (non-security) / spec-compliance
Bucket(s): router, cross-repo (neither label exists in this repo — gap noted in run summary)
Status: ready-for-human

What the experts said:

• code-reviewer: The .well-known/adagents.json fetcher doesn't exist yet — this is new code, not a patch; CheckRedirect has Go-specific gotchas (hop-count semantics differ from what most readers expect, http.ErrUseLastResponse behavior for authoritative_location is easy to misread); changing urlutil.Registrable to use a different PSL library is a subtle behavioral breaking change for private-PSL domains for existing callers (e.g. identity agent fcap key derivation); overall risk medium.
• ad-tech-protocol-expert: Spec-correct — two-tier policy is intentional and aligns with existing denyCrossOriginRedirect / noFollow layering; origin-anchored semantics are the only safe reading but adcp#5472 prose is ambiguous on this point and warrants a normative MUST; hop cap of 3 must be confirmed as a spec-derived constant (existing denyCrossOriginRedirect in tmproto/keystore_remote.go:118 uses 5 — a mismatch causes cross-SDK conformance failures on chains of exactly 4 hops); PSL private section may already be handled correctly by golang.org/x/net/publicsuffix embedded data.
• security-reviewer: PSL cross-tenant trust-anchor injection confirmed as a real attack (medium severity — requires attacker to share a multi-tenant hosting platform with the victim publisher); per-hop SSRF re-validation in CheckRedirect is a genuinely distinct control from safeDialContext (URL-level check before dial, catches literal-IPv6 SSRF vectors the dial layer may miss); any new PSL dep should land in a new urlutil sub-module following the urlcanon pattern, not the root module, to preserve TEE dep isolation; scheme-downgrade rejection and hard hop-cap of 3 are both required mitigations alongside PSL.

My take: Two always-Flag gates are active: the implementation will require a go.mod change (new dep or new sub-module) and it touches the publisher authorization trust anchor. There is also a material expert disagreement that needs resolution before implementation begins: security-reviewer states golang.org/x/net/publicsuffix lacks private-PSL support and recommends weppos/publicsuffix-go; ad-tech-protocol-expert asserts the existing golang.org/x/net embedded data already covers private PSL entries — confirming which is correct (e.g. testing EffectiveTLDPlusOne("victim.github.io") vs "attacker.github.io" in v0.54.0) determines whether a new dep is needed at all.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01Goi7BpRv626jK3rkFX8yDH

---

Generated by Claude Code