fix(auth): A2A cannot express task-level discovery access — spec designates three operations publicly accessible

[numarasSigmaSoftware]

---

AdCP 3.1.1 designates a set of low-risk discovery operations as publicly accessible:

dist/docs/3.1.1/building/by-layer/L1/security.mdx — "### Low-Risk Operations (Discovery) / These operations are publicly accessible:" listing get_adcp_capabilities (agent capability discovery), get_products (public inventory discovery), and list_creative_formats (public format catalog).

The MCP leg can express this — BearerTokenAuth.mcp_discovery_tools is a per-tool allowlist (adcp/server/auth.py:1018, documented at :917-932). The A2A leg has no equivalent: A2ABearerAuthMiddleware exempts only the two well-known agent-card paths (auth.py:1411-1414, _A2A_DISCOVERY_PATHS at :1334-1340) and never inspects the JSON-RPC body to see which skill is being invoked. The only other lever, allow_unauthenticated, is all-or-nothing for the whole endpoint (auth.py:1420-1422).

So on A2A an adopter must choose between:

• authenticating everything — a buyer cannot discover capabilities, products, or formats without credentials, contrary to the spec text above; or
• authenticating nothing on /a2a — every mutating skill becomes unauthenticated.

Neither is conformant for an agent that wants spec-correct discovery plus protected writes.

Proposed change: an a2a_discovery_skills allowlist mirroring mcp_discovery_tools, evaluated against the skill name(s) in the request body. Two semantics worth deciding explicitly, from our own implementation experience: a message may carry more than one skill (any non-discovery skill should require auth), and an unauthenticated rejection should still carry a spec-shaped AdCP error envelope rather than only an HTTP-level 401, so buyers get a machine-readable AUTH_REQUIRED code.

Verified present on 6.6.0 and v7.0.0-rc (the A2A module is byte-identical between them).

Happy to contribute the implementation if the shape sounds right.

[bokelley]

Triage

Classification: Bug — spec conformance gap
Bucket(s): middleware (label absent from repo — noted for gap tracking)
Status: ready-for-human
Milestone: omitted

What the experts said:

• ad-tech-protocol-expert: Gap confirmed real. DISCOVERY_TOOLS is frozenset({"get_adcp_capabilities"}) — adopters extend MCP coverage via mcp_discovery_tools, A2A has no parallel. a2a_discovery_skills mirroring the same dataclass field is the correct fix. Key implementation blocker: A2ABearerAuthMiddleware is raw ASGI (no body cache abstraction), so skill-level bypass requires buffering the receive async generator and replaying it downstream — substantially more complex than the MCP leg. Fail-closed multi-skill invariant (any non-discovery skill in the batch → require auth) is the right rule; current a2a-sdk parser surfaces one skill per message, but encoding the invariant now is the safe call. Non-breaking: None default preserves current path-only bypass for all existing adopters.
• security-reviewer / code-reviewer: running async; key concerns expected to align with receive-replay safety and boot-time validation parity.

My take: The conformance gap is verified in code and the proposed approach is structurally sound. However, auth middleware is security-sensitive — triage policy routes these to human review regardless of expert convergence. The ASGI body-buffering pattern and the exact boot-time validation rules deserve a maintainer decision on implementation approach before the API surface is committed.

Implementation scope when authorized:

• Add a2a_discovery_skills: Collection[str] | None = None to BearerTokenAuth (mirrors mcp_discovery_tools; None = current path-only bypass)
• Add __post_init__ validation matching mcp_discovery_tools: reject mutating skill names via validate_discovery_set, reject empty sets, reject bare strings
• Extend A2ABearerAuthMiddleware.__call__ to buffer/parse/replay the receive body when a2a_discovery_skills is set; extract skill name(s); pass through only if every skill in the message is in the allowlist, reject otherwise
• Update _send_unauthenticated to include a machine-readable code field in the 401 body (not an AdCP task-level error envelope — those are a different transport layer)
• Tests: unauthenticated discovery skill passes; mutating skill rejected at HTTP level; mixed-skill batch rejected; boot-time validation errors; body-replay correctness under large payloads

@bokelley — flagging for your review. The spec mandate is clear; the main design decision is whether to accept the ASGI body-buffering approach in the middleware or pursue an alternative path (e.g., a2a-sdk ServerCallContextBuilder hook).

---

Triaged by Claude Code. Session: https://claude.ai/code/caa969c7-236d-5dd6-88d3-2830adff2409

---

Generated by Claude Code

[bokelley]

Security reviewer addendum (arrived after initial triage comment):

Two blockers and one nit worth flagging explicitly before implementation begins:

Blocker — parser divergence. A2A skill names are not at the JSON-RPC method level — they're inside a DataPart payload ({"skill": "...", "parameters": {...}}), extracted by a pluggable MessageParser. If the middleware reimplements this extraction independently, an attacker can craft a message where the middleware reads a discovery skill name but the inner app dispatches a mutating one. The implementation must import and run the same _default_parse_request logic (or the configured MessageParser) rather than a parallel parser.

Blocker — boot-time validation. a2a_discovery_skills needs the same validate_discovery_set gate as mcp_discovery_tools. Without it, an operator can silently add create_media_buy to the allowlist at startup. Since A2A skills share the same name space as MCP tools, validate_discovery_set from adcp.server.mcp_tools can be reused directly.

Nit — error envelope. The 401 body should not echo the requested skill name (enables unauthenticated probing of which skills are outside the discovery set). Keep the body static as it is today, or add only a code field.

---

Triaged by Claude Code. Session: https://claude.ai/code/caa969c7-236d-5dd6-88d3-2830adff2409

---

Generated by Claude Code

[bokelley]

Code reviewer addendum — additional blockers and one expert disagreement:

Blocker — expert disagreement on boot-time validation. The security reviewer recommended reusing validate_discovery_set from adcp.server.mcp_tools. The code reviewer says do not: that function validates against the MCP tool registry and will behave unpredictably on A2A skill names. The code reviewer's position: boot-time validation for a2a_discovery_skills should be format-only (non-empty strings, no bare-string foot-gun, no empty collection) with an explicit comment explaining why the MCP spec-validator is not used. Human call needed: is the skill name space truly 1-to-1 with the MCP tool name space for all handlers, or not?

Blocker — body replay must forward disconnect events. A naive one-shot receive closure returning only the buffered body will hang a2a-sdk SSE streaming paths when the client disconnects mid-stream. The correct pattern already exists in _size_limit.py:144–156 (the existing ASGI size-limit middleware): after the buffer is returned, subsequent await receive() calls must return {"type": "http.disconnect"}. Reuse that function rather than inlining a new variant.

Blocker — skill extraction is four levels deep. The A2A JSON-RPC method is message/send; the ADCP skill name lives at body.params.message.parts[N].data.skill. There is also a TextPart JSON fallback in _default_parse_request. The middleware extraction must mirror that function exactly, or the allowlist silently 401s skills sent as TextParts.

Issue — gate body buffering on a2a_discovery_skills is not None. Unconditional buffering in __call__ adds memory overhead and pre-auth memory-exhaustion risk to all A2A deployments, not just those with an allowlist. The current zero-copy path must be preserved when the field is None (the default).

---

Triaged by Claude Code. Session: https://claude.ai/code/caa969c7-236d-5dd6-88d3-2830adff2409

---

Generated by Claude Code