reconcile PR #387 remediation — A2A hardened (PR-B, best of both + review 4638092590)

[plauzy]

Why (answer before "what")

1. What outcome are we trying to change?
   The reconciled PR-B: both blocking findings of the upstream feat: AG-UI protocol adapter + agentic protocol surface & generative UI (#386) awslabs/cli-agent-orchestrator#387 review closed with the objectively better implementation per axis from the two independent remediations (PRs remediate PR #387 review — A2A hardened (PR-B shape, Claude implementation) #12/[DRAFT][Kiro] remediate PR #387 review — A2A hardened (PR-B shape) #13), per the approved plan (#17) — plus the two findings of review 4638092590 that post-dated both remediations.

2. What would have to be true for that outcome to look different than today?
   Per-method auth verified against real JWTs with the strictest enforcement order; capacity refusals that HTTP-native infrastructure understands; a mount guard that is both unit-testable and integration-tested; peer-supplied task ids that can never overwrite existing tasks; and a diff that rebases cleanly onto a landed PR-A.

3. What is the smallest change that makes those things true?
   Start from claude/pr387-a2a-hardened (real-JWT test foundation, auth-before-parse + WWW-Authenticate, the reset_jwks_cache repair) and port the Kiro implementation's adjudicated wins (429/RESOURCE_EXHAUSTED, extracted guard + decision table, router-level stream dependency, the admin/unknown-method matrix cases) as five focused commits, adding the 4638092590 fixes.

4. How will we know it worked?
   The union auth matrix (~40 real-JWT cases, nothing in the token path stubbed), the id-integrity suite, the 8-case guard decision table + 3 lifespan integration tests, and the authenticated e2e roundtrip — all green (below).

---

Summary of changes (on top of the claude/pr387-a2a-hardened history)

• No dependency changes (Kiro's sequencing): the pyproject/uv.lock hygiene hunk is reverted — authlib→dev and the multipart removal land exactly once, in the core PR, so this branch rebases cleanly onto a landed PR-A per the agreed core-first order.
• Store-full = RESOURCE_EXHAUSTED at HTTP 429 + Retry-After: 30 (Kiro's semantics): capacity is a transport/backoff condition — proxies and retry middleware react to 429 without understanding A2A codes — while domain errors still ride 200; this matches how 401/403 already carry their HTTP statuses here. The JSON-RPC error body is kept for clients that ignore transport status. TaskLimitExceeded → TaskStoreFull.
• Tolerant env bounds: from_env survives malformed or non-positive CAO_A2A_MAX_TASKS/CAO_A2A_TASK_TTL values — default + warning, never a startup crash, and never "disable the bound" (a zero cap would silently reopen the DoS; previously int('abc') raised and 0 meant refuse-everything, both undocumented).
• Review 4638092590 (post-dated both remediations): task.send is now idempotent-create — a resubmitted id is refused with INVALID_PARAMS and the stored task is untouched (previously any peer could overwrite/cancel another peer's in-flight task by resubmitting its id); Task.from_dict uses data.get("id", "") so an omitted id takes the server-UUID path instead of raising KeyError. test/a2a/test_task_id_integrity.py pins both.
• Mount guard (both implementations): the fail-closed decision is a pure _should_mount_a2a() again (Kiro's shape) with the 8-case parametrized decision table, while the three lifespan integration tests (real listener + caplog on the refusal) keep covering the wiring.
• Router-level stream auth (Kiro): the cao:read gate moves to the APIRouter so any future /a2a/v1 route inherits it instead of shipping unauthenticated by omission.
• Auth matrix completion: the sibling's unique cases re-minted as real RS256 JWTs (their originals ran on a stubbed token layer) — cao:admin satisfies every method; authenticated unknown-method → METHOD_NOT_FOUND (404 + JSON-RPC body) while anonymous callers learn nothing — plus the bearer edges neither suite covered: case-insensitive scheme, empty bearer → 401, duplicate Authorization headers pinned to first-wins.
• Docs: docs/auth.md merges the per-method scope table with the curl walkthrough, updated for 429/Retry-After and create-only ids; the CHANGELOG bullet matches the final behavior with a precise anchor.

Unchanged from the base history: per-method enforcement resolved before any body parse (WWW-Authenticate: Bearer on 401), real-JWKS test fixtures, the reset_jwks_cache() repair, timestamp-based oldest-terminal eviction, and the authenticated e2e roundtrip.

Test plan

• Unit / integration tests pass — 3,609 passed / 21 skipped / 0 failed (uv run pytest; one environmental failure in an earlier run was a stale :9890 listener from manual demo servers, not reproducible with clean ports)
• Authenticated e2e round-trip (pytest -m e2e test/e2e/test_a2a_roundtrip.py → 2 passed): 401 untokened, then the full send→poll lifecycle with real JWTs
• mypy strict passes (uv run mypy src/ → no issues, 142 files); black + isort clean
• Auth suite 17, store bounds 8, id-integrity 4, mount guard 11 (3 integration + 8 decision-table) — all real-token paths, nothing stubbed
• Default-off unchanged: auth layer off → untokened behavior byte-identical; non-loopback + no-auth → task routes refuse to mount (unit + integration)

Provider tier

• Tier 1 — unit/integration, no provider boot needed

🤖 Generated with Claude Code

https://claude.ai/code/session_0123WW42FsCBRwQrK2uwF27s

---

Generated by Claude Code