Cross-link/relocate initial-fetch redirect policy; define it for brand.json too

[LukasGoTom]

Human: it's a bit confusing. Are 3XX redirects allowed or not. LLMs say no, but actually yes.

Addie:

Confirmed and it's a direct contradiction, not just a locality gap:

adagents. json Tech Spec (the primary doc): "Validators reject any HTTP redirect... The URL must resolve directly to the JSON file with a 200 response — no 301, 302, or other redirect chain. "
Managed Network Deployment doc: "Same-registrable-domain redirects MUST be followed on the /. well-known/adagents. json fetch... Capping the chain at 3 hops. "
These are opposite normative statements about the same fetch. One says reject all redirects, the other says MUST follow same-eTLD+1 redirects. That's not a "hard to find" problem — it's a real spec conflict, and no implementer reading both docs can satisfy both.

Context

The redirect policy for the initial fetch of a well-known file (before any authoritative_location variant is known) already exists for adagents.json, in the Managed Network Deployment doc:

"Same-registrable-domain redirects MUST be followed on the /.well-known/adagents.json fetch — apex ↔ www, and any redirect that stays on the same registrable domain (eTLD+1) — re-validating the SSRF controls on every hop, refusing any redirect to a non-HTTPS scheme, and capping the chain at 3 hops. Refusing these silently reports a correctly-configured publisher as unauthorized."

This matches the leashed-redirect approach implementers (e.g. ssrfSafeFetchAdAgents in adcp-client) already use: ≤3 hops, same registrable domain, HTTPS-only, per-hop SSRF revalidation.

Problem

1. This rule lives only in the "Managed Network Deployment" doc, not in the primary adagents.json Tech Spec fetch-reference steps. An implementer reading the adagents.json spec top-to-bottom will not find it and may reasonably conclude (as we did) that initial-fetch redirects are unaddressed — leading verifiers to refuse redirects at hop zero and fail-open on the authorized_operators check for any publisher doing an ordinary apex↔www redirect.
2. The equivalent rule does not appear to exist for brand.json's initial /.well-known/brand.json fetch at all.

Ask

• Cross-link (or relocate) the same-registrable-domain redirect rule from Managed Network Deployment into the adagents.json Tech Spec's fetch-reference steps, so it's visible where implementers actually look.
• State explicitly whether the same rule (≤3 hops, same registrable domain, HTTPS-only, per-hop SSRF revalidation) applies to the initial brand.json fetch, and if so, add it to the brand.json spec.

Affected docs: governance/property/adagents, governance/property/managed-networks, brand-protocol/brand-json.

[bokelley]

Triage

Classification: Spec question (docs locality gap + policy gap)
Bucket(s): registry / discovery, spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Locality gap, not a real contradiction. The troubleshooting text's "Validators reject any HTTP redirect" is scoped to the authoritative_location URL (post-fetch JSON level), not the initial /.well-known/adagents.json fetch — both statements are correct in context. Ask Welcome to adcp Discussions! #1 (cross-link the Managed Networks rule into the primary adagents.json spec) is docs-only, non-breaking, no new implementer obligations. Ask Remove targeting_template and add pluggable product catalog system #2 (brand.json initial-fetch policy) is a new normative statement on a separate spec — needs WG ratification before it lands.
• adtech-product-expert: Apex↔www redirect is table stakes for any publisher on standard CDN infrastructure; this is a real pain point, not theoretical. The leashed-redirect policy (same eTLD+1, HTTPS-only, ≤3 hops, per-hop SSRF revalidation) is operationally correct for brand.json's initial fetch too. But the SSRF revalidation requirement is security-load-bearing and shouldn't land as normative text without fast-track WG review.

My take: The conflict Addie identified is a locality gap — the adagents.json primary spec's "reject redirect" statement is narrowly scoped to authoritative_location resolution, not the initial well-known fetch. Both statements are correct; they just govern different fetches. Part 1 (cross-linking the Managed Networks rule into the primary adagents.json fetch-reference section) is a non-breaking docs clarification — implementation brief below. Part 2 (brand.json initial-fetch redirect policy) is a genuinely new normative statement that warrants a WG decision before landing.

---

Ready to implement — Part 1: adagents.json cross-link (non-breaking docs)

• In docs/governance/property/adagents.mdx "File Location" section, cross-link or inline the same-registrable-domain redirect rule: initial /.well-known/adagents.json fetches MUST follow same-eTLD+1 redirects (apex ↔ www), HTTPS-only, ≤3 hops, per-hop SSRF revalidation. Reference the existing Managed Networks doc as the canonical source.
• In the "Troubleshooting authoritative_location failures" section (currently line ~468), add a scoping note clarifying that "Validators reject any HTTP redirect" applies to the authoritative_location URL specifically — not the initial well-known fetch — so implementers reading the troubleshooting section don't infer the wrong rule for the discovery step.
• No schema change; no changeset (non-normative docs only). Validate with npm run docs:check.
• Non-breaking rationale: codifies behavior already implemented in ssrfSafeFetchAdAgents in adcp-client; no conformant implementation needs to change code.

Ready for human — Part 2: brand.json initial-fetch policy

Does the same leashed-redirect policy (same eTLD+1, HTTPS-only, ≤3 hops, per-hop SSRF revalidation) apply to the initial /.well-known/brand.json fetch? Both experts say yes operationally, but the SSRF revalidation clause is security-load-bearing and this would be a new normative statement in docs/brand-protocol/brand-json.mdx (the current Resolution algorithm's "3 hops" refers to JSON-level variant hops, not HTTP-level 3XX). Needs WG confirmation before implementation.

---

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

---

Generated by Claude Code