Return *oauth2.RetrieveError from tokenexchange

[jhrozek]

Summary

• Why: Token exchange currently returns a private oAuthError whose only output is a formatted string. Callers cannot inspect the RFC 6749 §5.2 fields without parsing the message. This PR aligns the error shape with the upcoming JWT Bearer grant, both of which will share helpers in pkg/oauth — *oauth2.RetrieveError from golang.org/x/oauth2 is the library-standard surface for non-2xx token endpoint responses.
• What: Replace oAuthError with *oauth2.RetrieveError. validateResponseStatus now takes *http.Response so it can attach the full response and best-effort-parse the body. On non-conformant bodies (no error field, e.g. proxy HTML 5xx), the raw body is logged at debug level and cleared from the returned error so RetrieveError.Error() cannot interpolate arbitrary upstream content (HTML, hostnames, stack traces) into wrapped log strings — same two-tier pattern already used by formatOAuth2Error in pkg/authserver. parseTokenExchangeResponse wraps json.Unmarshal failures with %w.

Type of change

• Refactoring (no behavior change)

(Note: the body-redaction defense above is a deliberate hardening of an information-disclosure path the previous code already had via the implicit fmt error string; user-visible structured behavior is unchanged.)

Test plan

• Unit tests (task test) — pkg/auth/tokenexchange passes; two pre-existing failures on main in unrelated packages (pkg/skills/client hardcoded port, pkg/workloads empty-group filter) are not introduced by this PR.
• Linting (task lint-fix) — 0 issues.

TestExchangeToken_HTTPErrorResponses was migrated from substring matching on err.Error() to errors.As(err, &*oauth2.RetrieveError{}) and now asserts on Response.StatusCode, ErrorCode, ErrorDescription, and Body (preserved on conformant responses, cleared on the 503 non-JSON case).

API Compatibility

• This PR does not break the v1beta1 API.

Does this introduce a user-facing change?

No. Internal error type change. Operators who scrape the existing slog.Debug log fields (oauth_error_code, description, status, body_length) will see identical field names; the body-content debug field is new and additive.

Special notes for reviewers

• The commit is intentionally narrow and isolated from the pkg/oauth shared-helpers migration (subsequent commits 5b/5c) so a future bisect can distinguish "error shape regressed" from "plumbing regressed."
• Upstream caller pkg/vmcp/auth/strategies/tokenexchange.go:142 wraps with %w, so errors.As continues to work and the leading "token exchange failed: " prefix is preserved.
• The body-redaction behavior was added in response to review feedback on the original commit — see commit message for rationale and the formatOAuth2Error precedent.

Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.19%. Comparing base (a98c991) to head (e8109cc).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5082      +/-   ##
==========================================
- Coverage   67.19%   67.19%   -0.01%     
==========================================
  Files         598      598              
  Lines       60258    60260       +2     
==========================================
+ Hits        40493    40494       +1     
- Misses      16691    16696       +5     
+ Partials     3074     3070       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.