feat(auth): add dormant BFF token-handler backend infra (Phase 2)

[philmerrell]

Summary

• Phase 2 of the Bearer→cookie BFF migration. Lands the server-side plumbing dormant — no behavior change until a session cookie exists, which won't happen until Phase 3 ships the /auth/* routes.
• Adds apis/shared/sessions_bff/ package: BFFConfig (env-driven, gated by is_enabled()), SessionRepository (DDB CRUD with TTL semantics), CookieCodec (KMS GenerateDataKey → AES-GCM seal of session id), CSRF double-submit helpers, TTL cache, per-session asyncio.Lock registry for refresh-storm coalescing, and CognitoRefreshClient (InitiateAuth REFRESH_TOKEN_AUTH with cached SECRET_HASH).
• Adds SessionRefreshMiddleware and CSRFMiddleware registered on app-api in main.py. Both are registered unconditionally so a Phase 1 env-var deploy can flip them on without a code redeploy. They short-circuit when BFFConfig.is_enabled() is False (local dev, environments before Phase 1 deployed) and when no __Host-bff_session cookie is present (Bearer-token requests).
• Adds get_current_user_from_session dependency in apis/shared/auth/dependencies.py for Phase 6 router cutover. No router consumes it yet — intentional per the Phase 2 scope.

Design choices worth flagging

• Cookie name __Host-bff_session — the prefix forbids Domain= and requires Secure + Path=/, giving same-origin-only delivery for free once CloudFront /api/* lands in Phase 6.
• Envelope encryption, cached DEK — at first use, kms:GenerateDataKey returns a 256-bit AES key; plaintext is cached in process memory, wrapped blob discarded. Matches the Phase 1 CDK comment. Key rotation requires a task restart, which is on the Phase 7 hardening list.
• Refresh storm coalescing — per-session asyncio.Lock prevents N parallel tab refreshes from tumbling each other's refresh tokens via Cognito rotation. In-process only (Phase 7 will extend to multi-task with a DDB conditional write).
• CSRF only enforced when a session is bound — Bearer-token requests bypass entirely, so this PR doesn't break the existing SPA.

Test plan

• pytest tests/apis/shared/sessions_bff/ -v — 46 new tests all pass
  • Cookie codec: round-trip, tampered ciphertext rejected, garbage rejected, unknown-version rejected, wrong-key rejected
  • Repository: CRUD round-trip via moto, TTL-expired row treated as missing, disabled repo is inert
  • CSRF: helper validation, middleware exempts safe methods + Bearer requests, rejects mismatched/missing/forged tokens, exempts /auth/login|callback|logout
  • SessionRefreshMiddleware: pass-through when disabled, pass-through when no cookie, valid cookie attaches state, unrecoverable cookie cleared, refresh-failure cookie cleared
  • Storm coalescing test (the one called out in the migration plan): 5 concurrent requests against an httpx.AsyncClient(ASGITransport) for the same near-expiry session → exactly one Cognito refresh exchange
• pytest tests/apis/shared/ tests/architecture/ — 92/92 pass, no import-boundary violations
• pytest tests/apis/app_api/ tests/auth/ — 102/102 pass, no regressions from dependencies.py changes
• python -c "from apis.app_api import main" — app-api imports cleanly with 4 middlewares registered (CORS → AgentCoreContext → SessionRefresh → CSRF)
• No infrastructure or runtime change to verify in cloud — this PR is dormant code

🤖 Generated with Claude Code