feat: implement identity.brand_json_url resolver + verifier (resolve_agent / verify_request_signature) + CLI

[bokelley]

Summary

AdCP 3.x adds identity.brand_json_url to get_adcp_capabilities (PR adcontextprotocol/adcp#3690). Verifiers can now bootstrap from an agent URL to that agent's signing keys without out-of-band knowledge of the operator domain. This issue tracks the Python SDK port.

Spec references

• Wire change: top-level identity.brand_json_url field on get_adcp_capabilities response.
• Verifier algorithm: 8 steps in security.mdx §"Discovering an agent's signing keys via brand_json_url".
• Design doc: specs/capabilities-brand-url.md.

API to implement

from adcp import resolve_agent, get_agent_jwks, verify_request_signature

result = resolve_agent("https://buyer.example.com/mcp")
# result: AgentResolution { agent_url, brand_json_url, agent_entry, jwks_uri,
#                          jwks, identity_posture, consistency, freshness, trace }

verified = verify_request_signature(
    request,                                  # httpx.Request
    agent_url="https://buyer.example.com/mcp",
    allowed_algs=("EdDSA",),
)
# Raises typed exceptions matching the spec's request_signature_* error codes.

CLI

python -m adcp resolve <agent-url> — same output format as the TypeScript CLI (npx @adcp/client resolve). Flags: --json, --fresh, --quiet. Output portable across SDKs so shell pipelines work either way.

Implementation notes

• SSRF hardening: HTTPS only, address-family filter before DNS-pin, IPv4 RFC 1918 + IPv6 ULA + cloud-metadata IP blocks, body cap 256 KiB on brand.json / 16 KiB JWKS / 64 KiB capabilities, no redirects, connect 5s / total 10s. httpx provides hooks for connect-time IP filtering.
• PSL: use publicsuffixlist or tldextract with a pinned snapshot. Don't fetch the PSL at runtime.
• Cache: brand.json TTL bounded above by JWKS revocation polling interval. Negative-cache ≤ 60s. No SWR on JWKS.
• Error class: AgentResolverError(Exception) with code and detail matching the spec's taxonomy. Subclasses keyed by error code for except clarity.
• Pydantic models for AgentResolution, Trace, IdentityPosture, etc.
• Reference design: see adcontextprotocol/adcp@bd89c62ff4 for the dropped Node.js reference implementation — the algorithm/structure ports cleanly.

Tests

• Unit: pure-function consistency tests covering every storyboard variant
• Integration: spin up a fixture HTTP server with brand.json + JWKS, drive the resolver and assert wire shape, error codes, JOSE round-trip via python-jose
• E2E gated by env var against a known-good agent

Acceptance

• resolve_agent, get_agent_jwks, verify_request_signature exported from adcp
• CLI python -m adcp resolve <url> printing the chain + trace
• All 8 request_signature_* codes surface as typed exceptions
• SSRF hardening covers the full list from security.mdx §"Quickstart"

[bokelley]

Triage

Classification: Feature request
Bucket(s): signing (label not in repo — noted in run summary), client
Status: ready-for-human

What the experts said:

• security-reviewer: SSRF redirect block must be explicit on all 3 hops (capabilities → brand.json → JWKS) — not just JWKS; github.io-style PSL edge case is a domain-consistency bypass path; python-jose not needed, use existing jws.py (cryptography-backed). Blockers.
• ad-tech-protocol-expert: identity_posture/consistency lack spec provenance in generated types — must confirm they're normative AdCP terms before use in interop --json output. Prefer a verify_request_signature_from_agent_url() factory over activating the dormant VerifyOptions.agent_url field. Blockers.
• code-reviewer: publicsuffixlist/tldextract belongs in a new [identity] optional extra, not mandatory deps. CLI resolve as a positional subcommand collides with saved agent aliases (e.g., adcp resolve get_info dispatches wrongly). Blockers.
• dx-expert: async_resolve_agent is missing — all existing agent-discovery ops are async; sync-only breaks async call graphs. get_agent_jwks duplicates CachingJwksResolver infra and should be dropped (surface via AgentResolution.jwks instead). Blockers.

My take: Well-scoped, spec-grounded feature with substantial SSRF infra already in place — but five blocker-level design questions need owner decisions before implementation. Flagging for @bokelley per security-sensitive triage policy.

Open design questions:

1. Are identity_posture / consistency normative AdCP terms (cite security.mdx enum values) or SDK-level constructs to exclude from --json?
2. [identity] optional extra or mandatory dep for PSL library?
3. async_resolve_agent as primary + sync wrapper (matching sign_request / async_sign_request pattern)?
4. Drop get_agent_jwks from public surface?
5. CLI: flag (--resolve) or subcommand with alias collision-check?

---

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

---

Generated by Claude Code

[bokelley]

Blocked on schema availability — re-checked 2026-05-02

After the 3.0.4 schema sync (#367), identity.brand_json_url is still not in the pinned schema bundle — schemas/cache/protocol/get-adcp-capabilities-response.json defines identity.{per_principal_key_isolation, key_origins, compromise_notification} but no brand_json_url field.

Timeline:

• adcp v3.0.4 published: 2026-05-02T11:35:07Z
• adcp#3690 merged: 2026-05-02T16:04:34Z (4.5h after 3.0.4 cut)

So 3690's wire change is in upstream main but not in any tagged release the SDK can pin to. Implementing resolve_agent against 3.0.4 would require either (a) reading the field via model_extra raw-JSON tolerance — viable but feels like premature scaffolding, or (b) pinning to a pre-release tarball — drift risk.

Plus the 5 expert blockers in the original triage still need owner decisions (SSRF on all 3 hops, identity_posture/consistency provenance, PSL extra, async-first surface, CLI alias collision).

Recommend: defer until either (a) 3.0.5 / 3.1 ships with adcp#3690 in a tagged tarball, or (b) the design questions are settled enough to start with raw-field tolerance. Re-triage on either trigger.

@bokelley

[bokelley]

Triage — status refresh 2026-05-02

Classification: Feature request
Bucket(s): signing, client
Status: deferred — blocked on schema availability + design decisions

New blocker (schema availability): identity.brand_json_url is absent from the 3.0.4 schema bundle — adcp#3690 merged 4.5 h after the 3.0.4 tag cut, so the wire field has no pinnable upstream release. Implementing against 3.0.4 would require model_extra raw-field tolerance as scaffolding — a path the prior expert panel would likely flag given the SSRF surface already in scope.

Prior blockers (unchanged, 5 open): SSRF coverage on all 3 fetch hops, identity_posture/consistency spec provenance, PSL optional-extra vs. mandatory dep, async_resolve_agent as primary surface, CLI alias collision.

Defer triggers — either unlocks:

1. adcp 3.0.5 / 3.1 ships with adcp#3690 in a tagged release (schema sync chore(schemas): sync to AdCP 3.0.4 + AUTH_REQUIRED recovery alignment (#306) #367 picks it up cleanly).
2. Owner decisions on all 5 design questions above, enabling a model_extra-tolerant interim implementation path.

---

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

---

Generated by Claude Code

[bokelley]

Design decisions — settling the 5 blockers

Codebase-grounded findings on the original triage blockers, with concrete recommendations to unblock implementation. Spec-side gate already cleared by #374 (3.0.5 sync — identity.additionalProperties: true).

Blocker 1 — SSRF on all 3 hops

Finding: Two of three hops are already pinned.

• brand.json hop: brand_jwks.py:_fetch_brand_json (line 369+) calls build_async_ip_pinned_transport per redirect (line 430). IP-pinned, redirect-capped, body-capped, HTTPS-validated.
• JWKS hop: jwks.py:async_default_jwks_fetcher uses the same IP-pinned transport.
• Capabilities hop (gap): capability_priming.ensure_capability_loaded accepts an injected fetch_raw callable; the SDK ships no default SSRF-pinned capability fetcher. The natural wiring ADCPClient.get_adcp_capabilities() (client.py:2159) goes through MCP/A2A protocol adapters using plain httpx — that's appropriate for trusted-counterparty traffic but not safe to use against an attacker-supplied agent_url.

Decision: async_resolve_agent ships its own SSRF-pinned capability fetcher in agent_resolver.py using the existing build_async_ip_pinned_transport factory. Redirect cap + body cap + HTTPS-only mirror the brand.json fetcher. Do not route through ADCPClient — the threat model differs.

Blocker 2 — identity_posture / consistency provenance

Finding: grep identity_posture schemas/cache/ src/adcp/ → zero matches. grep consistency schemas/cache/ → only unrelated contexts (brand visual consistency, validation-error consistency). Neither term has normative AdCP provenance.

Decision: Drop both from AgentResolution. --json output is cross-SDK interop surface and SDK-invented terms don't belong there. AgentResolution carries: agent_url, brand_json_url, agent_entry, jwks_uri, jwks, freshness (Cache-Control / fetched_at), trace (per-hop record). All grounded in observable wire state.

Blocker 3 — PSL dependency

Finding: No tldextract / publicsuffixlist in pyproject.toml or src/. BrandJsonJwksResolver doesn't currently do eTLD+1 binding (that's the Tier-3 #350 concern, gated on adcp#3690 closing).

Decision: Add tldextract as an optional [identity] extra alongside the existing [pg] / [dev] extras. Bundles its own PSL snapshot, updates lazily. Adopters opt in with pip install adcp-client[identity]. The verifier raises a clean import error with the install command if the extra is missing.

Blocker 3b — CLI alias collision

Finding: __main__.py:528 defines agent as a positional. adcp resolve https://x/mcp would parse as agent="resolve", tool="https://x/mcp". resolve_agent_config("resolve") first looks up an alias named "resolve", then falls back to URL parsing — would silently misdispatch on collision.

Decision: Ship --resolve <agent-url> as a flag (matches existing --save-auth / --list-agents pattern). No alias collision risk. Keeps the spec wording in the issue body achievable — agents/scripts run python -m adcp --resolve <url> --json.

Blocker 4 — async-first surface

Finding: signer.py ships sign_request (sync, takes raw PrivateKey) AND async_sign_request (takes SigningProvider for KMS round-trip) as separate entry points with different signatures, not a sync wrapper around async. Resolving an agent is pure I/O, no KMS analogue, so the canonical pattern matches differently.

Decision: async_resolve_agent(...) is the canonical entrypoint. resolve_agent(...) is a thin sync wrapper: asyncio.run(async_resolve_agent(...)). Documented as "sync convenience for CLI / scripts; library code should use async". Matches the precedent in brand_jwks.py where the resolver itself is async-only.

Blocker 5 — get_agent_jwks redundancy

Finding: BrandJsonJwksResolver exposes __call__(kid) -> JWK | None, resolve(kid), agent_url property, force_refresh(). Does not expose a full-JWK-set accessor. The full set lives inside an AsyncCachingJwksResolver (self._inner) that's also kid-keyed only.

Decision: Drop get_agent_jwks as a separate top-level function (dx-expert is right about that). But surface the data via AgentResolution.jwks (the JWK set captured during resolve_agent's walk) and AgentResolution.jwks_uri. The CLI --json output includes both. No new cache layer; AgentResolution is a snapshot of the resolution moment, not a long-lived resolver — adopters who want ongoing rotation handling instantiate BrandJsonJwksResolver directly with the resolved brand_json_url.

Out-of-scope clarifications (not blockers, but pinning intent)

• verify_request_signature_from_agent_url factory: ship as adcp.signing.verify_from_agent_url(request, agent_url, *, agent_type, ...), internally composing async_resolve_agent + the existing verify_starlette_request / verify_request_signature. Per ad-tech-protocol-expert, this is preferable to activating the dormant VerifyOptions.agent_url field.
• 8 request_signature_* error codes: map them in agent_resolver.errors; subclasses keyed by code, matching the existing BrandJsonResolverError / BrandJsonResolverErrorCode pattern in brand_jwks.py.
• Forward-compat brand_json_url read: as of 3.0.5, identity is additionalProperties: true, so the field flows through validation. Resolver reads it via response.identity.model_extra.get("brand_json_url") until a typed schema field lands in 3.1.

---

Five blockers settled. With these decisions in place, implementation is well-scoped — happy to start the build whenever you greenlight.