fix(xai-oauth): echo code_challenge in token POST so PKCE exchange succeeds (#26990)

[xxxigm]

What does this PR do?

Fixes hermes auth add xai-oauth getting stuck at the token-exchange step with code_challenge is required.

Issue #26990 reported a P1 regression where the loopback OAuth flow succeeds at the browser-side authorize step (callback comes back with a valid code), but the follow-up POST to xAI's token endpoint fails with code_challenge is required — even though Hermes was already sending a valid code_verifier exactly as RFC 7636 §4.5 prescribes.

Root cause — xAI's OAuth implementation at auth.x.ai re-validates the PKCE code_challenge at the token endpoint, not just at the authorize step. A standards-compliant client that sends only code_verifier (the canonical RFC 7636 token-step input) is rejected. This is a known quirk of permissive OAuth implementations: while RFC 7636 doesn't require the client to echo the challenge at the token endpoint, it also doesn't forbid it, and many home-rolled servers cross-validate.

Fix — extract the token POST into a dedicated, unit-testable _xai_oauth_exchange_code_for_tokens helper and:

1. Send code_verifier as before (unchanged contract).
2. Also echo the original code_challenge and code_challenge_method=S256 in the form body. Strict RFC-compliant servers ignore extras at the token endpoint; xAI's permissive server accepts the exchange. This is the standard defensive-echo workaround used by every OAuth client targeting a server with this quirk.
3. Refuse to fire the POST when code_verifier is empty — leaking an auth code to a server that can't redeem it is worse than failing locally with an actionable error (new code: xai_pkce_verifier_missing, message points at xai-oauth token exchange fails: code_challenge is required (PKCE code_verifier missing) #26990).
4. Surface the HTTP status code prominently in 4xx errors (xAI token exchange failed (HTTP 400). Response: …) so users / maintainers can tell a 400 (PKCE / bad request) from a 403 (tier denied, see [Bug]: xAI OAuth (xai-oauth) returns HTTP 403 for standard SuperGrok subscribers — backend enforcing Heavy-only despite docs claiming all tiers #26847) at a glance instead of parsing the JSON body by eye.

Related Issue

Closes #26990

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• hermes_cli/auth.py — extract token POST into _xai_oauth_exchange_code_for_tokens(...); echo code_challenge + code_challenge_method=S256 alongside code_verifier; refuse to POST with empty code_verifier (raises xai_pkce_verifier_missing); embed HTTP status code in 4xx error messages. _xai_oauth_loopback_login now delegates to the helper — 40 lines of inline httpx replaced with one call.
• tests/hermes_cli/test_xai_oauth_pkce_token_exchange.py — 14 new regression tests covering:
  • code_verifier is on the wire (RFC 7636 §4.5).
  • code_challenge + code_challenge_method=S256 are echoed (the xai-oauth token exchange fails: code_challenge is required (PKCE code_verifier missing) #26990 defense-in-depth).
  • Static fields locked: grant_type, code, redirect_uri, client_id.
  • Content-Type is form-urlencoded; Accept is JSON.
  • Supplied token_endpoint used verbatim (no hard-coded constant).
  • timeout_seconds forwarded; floored at 20s.
  • Empty code_verifier raises locally without sending — and NOTHING is POSTed.
  • Empty code_challenge keeps the standards-compliant request flowing (defensive echo is opt-in).
  • 4xx responses surface both HTTP <status> and the response body.
  • Transport errors wrap as AuthError with the right code.
  • Non-dict JSON payloads raise xai_token_exchange_invalid.
  • 200 happy path returns the parsed dict verbatim.
  • End-to-end wire-format guard via a real httpx.Client + stub transport that captures the bytes and parses them — catches a future refactor that swaps data= for json= (which xAI would silently reject).

How to Test

# 1. New regression suite passes
python -m pytest tests/hermes_cli/test_xai_oauth_pkce_token_exchange.py -q
# expected: 14 passed

# 2. All existing xAI OAuth tests still pass (no regression to refresh,
#    discovery, 403-entitlement handling, or recovery paths)
python -m pytest tests/hermes_cli/test_auth_xai_oauth_provider.py \
                 tests/run_agent/test_codex_xai_oauth_recovery.py -q
# expected: 87 passed

# 3. Combined sweep
python -m pytest tests/hermes_cli/test_auth_xai_oauth_provider.py \
                 tests/hermes_cli/test_xai_oauth_pkce_token_exchange.py \
                 tests/run_agent/test_codex_xai_oauth_recovery.py -q
# expected: 101 passed

Why "defensive echo" and not "switch to a different flow"?

• RFC 7636 §4.5 explicitly only requires code_verifier at the token endpoint — so the pre-fix code was technically correct.
• But xAI's server rejects the technically-correct request, and the issue is P1 (login is broken).
• Echoing code_challenge at the token endpoint is harmless for strict servers (they MUST ignore unknown parameters per RFC 6749 §3.2) and necessary for xAI.
• Switching to device-code or PAR-style flows would require xAI registering us for a different OAuth profile — out of our control.
• The same defensive echo is used by other production OAuth clients targeting servers with this quirk (Spotify-style cross-validation, certain Auth0 deployments, etc.).

[teknium1]

Salvaged into main via #27560 — your commits were cherry-picked onto current main with your authorship preserved in git log. The defensive code_challenge echo + 14 regression tests landed verbatim. Thanks for the fix and the thorough test coverage!