feat(testing): runtime user-persona impersonation via X-Test-* headers

[larsgeorge-db]

Summary

Adds a per-request user impersonation mechanism gated on a server-side TEST_USER_TOKEN shared secret. Lets developers and Playwright tests exercise the app as different personas (Admin / Producer / Consumer / Steward / etc.) against a single running backend — no restarts, works with or without Vite fronting FastAPI.

Complements (does not replace) the existing MOCK_USER_* env vars (process-wide, require restarts) and the in-process app.dependency_overrides[get_user_details_from_sdk] pattern used by integration tests.

What's new

Backend

• Settings.TEST_USER_TOKEN + typed Settings.TESTING fields, with a model_validator warning when TEST_USER_TOKEN is set in PROD.
• _try_resolve_test_override(request, settings, manager) in common/authorization.py:
  • Gated on TEST_USER_TOKEN being set and X-Test-Token matching it exactly.
  • Requires X-Test-User-Email; missing email → 400.
  • X-Test-User-Groups optional (JSON array or CSV). When omitted, falls back to a real SCIM lookup so the persona mirrors actual workspace state.
  • Optional refinement headers: X-Test-User-{Username,Name,Ip}.
  • Audit-logs every active override; no-op when the token is unset.
• Wired at highest precedence into get_user_details_from_sdk, get_user_groups (now accepts optional request), and user_routes.get_user_info_from_headers.
• comments_routes threaded request through all 7 get_user_groups call sites so audience checks honor the override.
• src/backend/src/data/test_personas.yaml with canned personas (admin, governance, steward, producer, consumer, security, anon) aligned with seeded roles.
• GET /api/test/personas route — 404s when TEST_USER_TOKEN is unset; never returns the token itself.

Frontend

• stores/test-persona-store.ts Zustand store: fetches personas, reads VITE_TEST_USER_TOKEN (or localStorage.ucapp.testToken), persists the selected persona, and installs a global window.fetch interceptor that injects X-Test-* headers on every /api request when a persona is active.
• app.tsx initializes the store + installs the interceptor early.
• user-info.tsx adds a "Test persona" dropdown section (visible only when the backend feature is enabled) and a yellow ring/dot on the avatar so testers don't forget they're impersonating.

Tests + docs

• tests/integration/test_user_header_override.py covering:
  • Header groups (JSON + CSV), SCIM fallback, /api/test/personas.
  • Permission resolution from the overridden identity.
  • Wrong-token → ignored (impersonated email NOT honored).
  • Missing email when token matches → 400.
  • Feature fully disabled when token unset.
• CONTRIBUTING.md, CLAUDE.md, backend + frontend .env.example updated with setup, usage from UI/curl, and security notes.

Security

• Feature is fully inert unless TEST_USER_TOKEN is set server-side.
• Token must be left unset in production (warning logged otherwise).
• Token is never returned by any API; /api/test/personas returns 404 when the feature is disabled.
• Frontend UI picker is also gated on the backend reporting the feature is enabled.

Test plan

• CI: backend pytest suite (incl. the new test_user_header_override.py).
• CI: frontend lint + unit tests.
• Manual: set TEST_USER_TOKEN + VITE_TEST_USER_TOKEN locally, pick personas from the avatar dropdown, confirm the persona's permissions take effect across views.
• Manual: hit a feature-gated endpoint with curl -H "X-Test-Token: …" -H "X-Test-User-Email: consumer@test.local" -H "X-Test-User-Groups: [\"data-consumers\"]" — confirm response reflects the impersonated identity.
• Manual: wrong X-Test-Token — confirm impersonation is silently ignored (regular identity resolution wins).
• Manual: unset TEST_USER_TOKEN, confirm /api/test/personas returns 404 and the UI picker disappears.