BearerTokenAuthMiddleware × serve(transport="both") — needs A2A sibling + serve(auth=...) shortcut

[bokelley]

What

BearerTokenAuthMiddleware is documented MCP-only (src/adcp/server/auth.py:62-65):

"A2A uses a different transport; wire a2a-sdk's ServerCallContext.user via a2a-sdk auth middleware on that side."

But adopters wiring a unified seller via serve(transport="both") only get the one ASGI middleware list — there's no first-class way to wire matching auth on the A2A leg through the framework.

Concrete blast: when BearerTokenAuthMiddleware is passed via asgi_middleware=[...] on serve(transport="both"), it wraps the whole binary including A2A's public /.well-known/agent-card.json discovery endpoint, so unauthenticated discovery requests get rejected with 401, breaking A2A buyer auto-discovery entirely.

Repro (production-shape, not toy)

salesagent's core/main.py: one binary serving MCP + A2A from the same handler/router, one Principal table, one token validates both transports. Buyer just picks a protocol. We hit the same gap.

Workaround we shipped (with a real security cost)

We wrote a 30-line ScopedAuthMiddleware that runs BearerTokenAuthMiddleware only on /mcp/* paths. A2A is currently unauthenticated in our build. That's a regression we accepted because the framework didn't give us a clean way to wire auth on both legs simultaneously, and we needed /.well-known/agent-card.json reachable for discovery. Filing this so we can drop the workaround.

What we'd want

Option (b) from a chat with @bokelley: add an A2ABearerAuthMiddleware sibling (validates the same token shape but populates ServerCallContext.user rather than reading an HTTP header inline) plus a serve(auth=...) shortcut that wires both legs with one config:

serve(
    handler,
    transport="both",
    auth=BearerTokenAuth(validate_token=_validate_token, header_name="x-adcp-auth"),
    ...,
)

Internally serve mounts BearerTokenAuthMiddleware on the MCP leg and A2ABearerAuthMiddleware on the A2A leg from the single auth= config. Adopters who need transport-specific auth keep the lower-level path (separate middlewares per leg).

Considered alternatives:

• (a) Make BearerTokenAuthMiddleware transport-aware — awkward, A2A's auth model is different in shape (a2a-sdk reads ServerCallContext.user populated upstream, not an HTTP header re-validated on every request). A transport-aware mux either reimplements both auth styles or shells out to two underlying middlewares — at which point you've reinvented (b) inside a wrapper.
• (c) Fail-fast if BearerTokenAuthMiddleware is used as outer ASGI middleware on transport="both" — punts; doesn't actually solve the problem.

Filed by

salesagent kill-nginx/M2 spike — surfaced in core/SDK_FEEDBACK.md round 3.

[bokelley]

Triage

Classification: Feature request (with an active security regression — A2A leg unprotected in salesagent production)
Bucket(s): middleware, client (no matching repo labels; flagging label gap in run summary)
Status: ready-for-human
Milestone: omitted

What the experts said:

• security-reviewer: Option (b) is safe to implement with four concrete mitigations; two are blockers — (1) /.well-known/agent-card.json is served inside a2a_app via create_agent_card_routes and WILL get 401 from A2ABearerAuthMiddleware unless explicitly exempted with a path-based check (not the existing JSON-RPC method check); (2) per-leg auth wrapping must happen before _dispatch captures sub-app references in _build_mcp_and_a2a_app or auth is silently bypassed on the A2A leg. Nit: reuse _parse_bearer_header verbatim on the A2A leg — no new comparison logic.
• ad-tech-protocol-expert: Option (b) is the correct protocol-level approach. The A2A spec (§4.1) mandates /.well-known/agent-card.json be publicly accessible — authenticated discovery is a spec violation, not a valid seller option; the bypass must be unconditional. ServerCallContext.user is the correct a2a-sdk 1.0 injection hook (already used by _tool_context_from_request). Open question: verify the correct a2a-sdk 1.0 ASGI seam for attaching a populated ServerCallContext before DefaultRequestHandler constructs RequestContext.

My take: The bug is real and actively harmful — salesagent shipped a workaround that leaves A2A unprotected in production. Option (b) (A2ABearerAuthMiddleware + serve(auth=BearerTokenAuth(...))) is the right fix: the two blockers are concrete implementation constraints, not design objections. Flagging for human review because this is security-sensitive auth infrastructure; @bokelley is best placed to land it given familiarity with the a2a-sdk 1.0 ServerCallContext injection point.

Implementation notes for the PR author:

1. Wrap a2a_app and mcp_app separately with per-leg auth before defining the _dispatch closure in _build_mcp_and_a2a_app — capturing unwrapped references bypasses auth silently.
2. A2ABearerAuthMiddleware.is_discovery_path must match /.well-known/agent-card.json by URL path (not by JSON-RPC method). /.well-known/adcp-agents.json is served by _wrap_with_discovery outside a2a_app, so it's already beyond the A2A middleware and needs no bypass.
3. Reuse _parse_bearer_header and the existing TokenValidator protocol; no new comparison logic on the A2A leg.
4. BearerTokenAuth config object should be immutable (frozen dataclass); mirror header_name and bearer_prefix_required knobs so non-standard headers work without per-leg overrides.

---

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

---

Generated by Claude Code