Inbound verification accepts one expected agent_url, but brand.json declares agents[] as a list

[KonstantinMirin]

Measured against adcp==6.6.0.

The asymmetry

brand_authz already understands that a brand operates several agents — _find_listed_agents iterates agents[], and there is an explicit branch for "Multiple agents[] entries byte-equal the agent URL."

But the verifier's entry point accepts only one:

• VerifyOptions.agent_url: str | None (adcp/signing/verifier.py:148)
• brand_authz.check(agent_url: str, ...) (adcp/signing/brand_authz.py:111)

So a verifier can express "I expect this request to come from this one agent," and cannot express "I expect it from any of these agents of the same counterparty."

Why that is a problem for a seller

A seller onboards a counterparty — a brand — and stores what it knows about them. When a request arrives authenticated by a bearer token, the seller wants to verify the accompanying signature against the agents that counterparty is known to operate. With a single-valued agent_url it has to pick one.

The workarounds are both poor:

• Call the verifier once per candidate URL. N JWKS resolutions, N replay-store interactions, and a refusal that has to be synthesised from N partial failures. The replay checks are the sharp edge: a nonce consumed on the first attempt may make later attempts fail for the wrong reason.
• Pass agent_url=None. The expected-agent check is skipped entirely, which discards exactly the property being verified.

Neither is what a seller wants, and the shape of the data (agents[] is a list) says the library already knows the real cardinality.

What would help

VerifyOptions.agent_url accepting a collection — or a sibling field such as acceptable_agent_urls — with brand_authz.check matching the verified agent against any member and reporting which one matched. BrandAuthorizationResult.matched_agent_url already exists to carry that answer.

If a single expected URL is deliberate and multi-agent verification is meant to be done another way, a note in VerifyOptions' documentation saying so would be just as useful — the current asymmetry between agents[]-as-a-list and agent_url-as-a-scalar reads as an oversight rather than a decision.

Context

Downstream this forces a 1:1 principal↔agent model in a multi-tenant seller, where a brand running staging and production agents, two regional stacks, or migrating endpoints has to be represented as two separate principals — splitting one buyer's identity across credentials, accounts and media buys. Tracked at prebid/salesagent#2276.

[bokelley]

Triage

Classification: Feature request
Bucket(s): signing
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Implementation-gap — the spec is silent on multi-candidate seller-side verification; the scalar agent_url is an SDK choice, not a spec mandate. Adding acceptable_agent_urls is additive and non-breaking; the nonce concern is spec-compliance (wrong error code on second call), not QoL. matched_agent_url already exists on BrandAuthorizationResult with no structural changes needed.
• code-reviewer: VerifyOptions is frozen=True, kw_only=True — new optional field with default is backward-compatible. Identified two design issues: (1) VerifiedSigner.agent_url at line 423 would be None if caller uses acceptable_agent_urls — fix by deriving from getattr(options.jwks_resolver, "agent_url", options.agent_url). (2) BrandJsonJwksResolver is single-agent-scoped by (agent_type, agent_id, brand_id) — multi-agent key lookup needs a composing resolver or the limitation must be documented. Raised mutual exclusivity check and URL canonicalization as required design decisions.

My take: This is a real gap — the nonce-replay sharp edge the reporter describes is a correctness issue, not a preference. The implementation has a bounded scope but requires a second deliverable (a MultiAgentJwksResolver or documented guidance) alongside the VerifyOptions field to be complete; neither part is ambiguous.

Implementation brief:

• src/adcp/signing/verifier.py: Add acceptable_agent_urls: frozenset[str] | None = None to VerifyOptions. Add __post_init__ (or a validator) raising ValueError if both agent_url and acceptable_agent_urls are set. After the JWKS resolution step (~line 291), before the replay claim (~line 402), extract resolved_url = getattr(options.jwks_resolver, "agent_url", options.agent_url) and if acceptable_agent_urls is set, raise SignatureVerificationError(REQUEST_SIGNATURE_KEY_UNKNOWN) when resolved_url is not in the set. At line 423, update VerifiedSigner construction to use resolved_url. URL-canonicalize set members at construction time using the same _canonicalize_url logic in brand_jwks.py to avoid trailing-slash/default-port mismatches against brand.json's agents[].url.

• src/adcp/signing/brand_jwks.py or new src/adcp/signing/multi_agent_jwks.py: Introduce MultiAgentBrandJsonJwksResolver that wraps N BrandJsonJwksResolver instances (one per agent in the set) and routes __call__(kid) to whichever resolver returns a non-None JWK for that kid. Expose a agent_url property returning the URL of the last resolver that matched. This is the missing piece that lets the feature deliver the nonce-single-call guarantee the issue requires.

• tests/test_brand_authz.py / tests/conformance/signing/test_verifier_behaviors.py: Add cases: (a) signer URL in acceptable_agent_urls passes; (b) signer URL not in set raises REQUEST_SIGNATURE_KEY_UNKNOWN; (c) setting both agent_url and acceptable_agent_urls raises ValueError; (d) URL canonicalization matches e.g. https://agent.example.com/ and https://agent.example.com as the same entry.

• Non-breaking rationale: VerifyOptions is kw_only; existing callers constructing it without acceptable_agent_urls get the existing single-URL or no-check behavior unchanged. BrandJsonJwksResolver.check() signature is unchanged. The new MultiAgentBrandJsonJwksResolver is additive.

• Required checks: make lint && make typecheck-all && pytest tests/test_brand_authz.py tests/conformance/signing/

---

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

---

Generated by Claude Code