feat(replay): single-use claim on consent + callback state

[babs]

Summary

Closes T1.2 + T2.1 from misc/next-steps.md. Wires the existing replay store into two sealed-blob redemption sites that previously relied on TTL alone:

• Consent token (POST /consent) — single-use claim on a per-render jti. Each GET /authorize render mints a fresh jti, so back-button = re-consent (a new claim slot) rather than a stuck-state error.
• Callback state (GET /callback) — single-use claim on a per-session sid before the upstream OIDC exchange. A replayed /callback URL never fans out to the IdP token endpoint and never produces audit-log noise.

Eliminates the only "deliberate trade-off" footnote in specs.md (the consent-replay paragraph at the old line 337) and ships the audit-noise / IdP-fan-out fix the runbook called out for /callback.

Behavior when the replay store is wired (REDIS_URL set)

Site	Replay detected	Store error
POST /consent	400 invalid_request + error_code=consent_replay + mcp_auth_replay_detected_total{kind="consent"}++	503 server_error + error_code=replay_store_unavailable + mcp_auth_access_denied_total{reason="replay_store_unavailable"}++
GET /callback	400 invalid_request + error_code=callback_state_replay + mcp_auth_replay_detected_total{kind="callback_state"}++	(same shape)

Reuses the existing mcp_auth_access_denied_total{reason="replay_store_unavailable"} counter from /token so one alert rule covers every claim site. All four replay_store_error log lines now carry an op field (claim_authz_code / claim_refresh_family / claim_consent / claim_callback_state) for site-level correlation.

Backwards compatibility

• nil replay store → stateless fallback (configured opt-out, matches /token).
• Empty JTI / SessionID on tokens sealed by older binaries → stateless fallback. Lets a rolling deploy avoid 503-ing active users for the duration of consentTTL (5 min) / sessionTTL (10 min).

Deliberate non-claim

The /callback IdP-error redirect path (RFC 6749 §4.1.2.1) does NOT claim — the redirect is idempotent (no IdP fan-out, no token issuance) and claiming would burn the state on a transient IdP error and force re-auth on every legit retry. Documented inline in handlers/callback.go.

Test plan

• CI green (test, lint, keycloak-e2e, fuzz-smoke, manifest-prod, govulncheck, build).
• 10 new handler tests in handlers/single_use_replay_test.go:
  • TestConsent_SingleUse_ReplayDetected — second POST → 400 consent_replay, replay metric +1, approved counter does NOT double-count.
  • TestConsent_SingleUse_ClaimsBeforeDeny — Deny is also one-shot.
  • TestConsent_SingleUse_NilStoreFallback — nil store keeps the prior stateless behavior.
  • TestConsent_SingleUse_LegacyEmptyJTI — token with empty JTI succeeds (in-flight rollout).
  • TestConsent_SingleUse_StoreErrorFailClosed — 503 + replay_store_unavailable metric.
  • TestCallback_SingleUse_ReplayDetected — second /callback → 400 callback_state_replay, replay metric +1.
  • TestCallback_SingleUse_LegacyEmptySID — empty sid does NOT hit the replay branch.
  • TestCallback_SingleUse_StoreErrorFailClosed — 503 + metric, verifyFunc not called.
  • TestAuthorize_RenderConsent_PopulatesJTI — GET /authorize (consent fork) seals a non-empty jti.
  • TestAuthorize_SilentRedirect_PopulatesSessionID — silent path seals a non-empty sid.
• No existing test broke (full suite + -race runs locally).

Docs

• specs.md — /consent paragraph reworked from "Why no replay-store integration" → "Single-use replay defense"; /callback step list grew step 3 ("Single-use claim on sid"); subsequent steps renumbered.
• README.md — mcp_auth_replay_detected_total{kind} documentation extended with consent and callback_state.