fix(auth): drift-guard _A2A_DISCOVERY_PATHS against a2a-sdk route renames

Reviewer flagged that the hardcoded /.well-known/agent-card.json
literal could silently leak auth on a renamed route if a2a-sdk's
canonical path moves. Two changes:

1. Reference a2a.utils.constants.AGENT_CARD_WELL_KNOWN_PATH directly
   so the 1.0 path tracks a2a-sdk automatically. Legacy 0.3 alias
   /.well-known/agent.json stays as a literal (no constant for it).
2. New test_discovery_paths_match_a2a_sdk_routes inspects every path
   that create_agent_card_routes registers and asserts each is in
   _A2A_DISCOVERY_PATHS. If a future a2a-sdk version adds a new
   well-known route (extensions, capability descriptor, etc.), this
   test fails first — adopters update the frozenset rather than
   silently 401'ing on the renamed/added route.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

src/adcp/server/auth.py

@@ -559,9 +559,20 @@ class BearerTokenAuth:
 # satisfied even if a future a2a-sdk refactor merges the routes.
 
 
+# Canonical 1.0 path is sourced from a2a-sdk's own constant — if a
+# future a2a-sdk release renames the well-known URI, the import-time
+# reference here lifts to the new value automatically and
+# ``test_discovery_paths_match_a2a_sdk_routes`` verifies that the
+# frozenset still covers every route ``create_agent_card_routes``
+# actually registers. Hardcoding the string would silently leak auth
+# on the renamed route until someone notices.
+from a2a.utils.constants import (  # noqa: E402  (intentional placement after BearerTokenAuth definition)
+    AGENT_CARD_WELL_KNOWN_PATH as _A2A_AGENT_CARD_PATH,
+)
+
 _A2A_DISCOVERY_PATHS: frozenset[str] = frozenset(
     {
-        "/.well-known/agent-card.json",
+        _A2A_AGENT_CARD_PATH,  # 1.0 canonical: ``/.well-known/agent-card.json``.
         "/.well-known/agent.json",  # Legacy 0.3 alias retained by enable_v0_3_compat=True.
     }
 )

tests/test_serve_auth_both.py

@@ -485,6 +485,64 @@ def test_public_exports_include_new_symbols() -> None:
     assert "A2ABearerAuthMiddleware" in srv.__all__
 
 
+# ===========================================================================
+# Structural drift guard: a2a-sdk well-known route renames break loud
+# ===========================================================================
+
+
+def test_discovery_paths_match_a2a_sdk_routes() -> None:
+    """Catch silent drift between :data:`_A2A_DISCOVERY_PATHS` and
+    a2a-sdk's actual agent-card routes. If a future a2a-sdk release
+    renames ``/.well-known/agent-card.json`` (or removes the v0.3
+    alias), the frozenset would leave the renamed route
+    unauthenticated until someone noticed. This test fails first.
+
+    Walks ``create_agent_card_routes`` against a real ``AgentCard``
+    and asserts every registered path is in the frozenset.
+    """
+    from a2a.server.routes import create_agent_card_routes
+
+    from adcp.server.a2a_server import _build_agent_card
+    from adcp.server.auth import _A2A_DISCOVERY_PATHS
+
+    handler = _OkHandler()
+    agent_card = _build_agent_card(
+        handler,
+        name="drift-guard",
+        port=0,
+        description=None,
+        version="1.0.0",
+        extra_skills=None,
+        advertise_all=False,
+        push_notifications_supported=False,
+    )
+    routes = create_agent_card_routes(agent_card=agent_card)
+
+    registered_paths = [r.path for r in routes]
+    assert registered_paths, "a2a-sdk returned no agent-card routes"
+
+    missing = [p for p in registered_paths if p not in _A2A_DISCOVERY_PATHS]
+    assert not missing, (
+        f"a2a-sdk registers agent-card route(s) {missing!r} that are NOT in "
+        f"_A2A_DISCOVERY_PATHS={_A2A_DISCOVERY_PATHS!r}. Update the frozenset "
+        f"in adcp.server.auth to include the new path(s) — otherwise A2A "
+        f"discovery silently 401s on the renamed/added route."
+    )
+
+
+def test_a2a_agent_card_constant_referenced_directly() -> None:
+    """The 1.0 path uses ``a2a.utils.constants.AGENT_CARD_WELL_KNOWN_PATH``
+    rather than a string literal. If a2a-sdk changes the constant,
+    our frozenset rebases without code changes. This test pins the
+    indirection so a future maintainer doesn't accidentally inline
+    the string."""
+    from a2a.utils.constants import AGENT_CARD_WELL_KNOWN_PATH
+
+    from adcp.server.auth import _A2A_DISCOVERY_PATHS
+
+    assert AGENT_CARD_WELL_KNOWN_PATH in _A2A_DISCOVERY_PATHS
+
+
 # ===========================================================================
 # RFC 6750 / RFC 7235 compliance: 401 must carry WWW-Authenticate
 # ===========================================================================