Severity: High
Category: Error handling · Concurrency · Robustness
Source: internal audit (docs/issues/oauth-refresh-error-body-token-leak.md)

The MCP OAuth refresh path in crates/librefang-kernel/src/mcp_oauth_provider.rs rolls up four sub-findings. The log-sanitization sub-finding already landed in #5526 (closes #5525). This issue tracks the remaining three, which #5526 explicitly left for follow-up.

Sub-findings (remaining)

Affected code

• crates/librefang-kernel/src/mcp_oauth_provider.rs — try_refresh body and the load_token caller that collapses errors to Ok(None); no single-flight lock.
• crates/librefang-api/src/oauth.rs — find_any_with_refresh returning Option<(String, StoredTokens)> and the entry.refresh_token.unwrap() at the auth_refresh callsite.

Why grouped

All three live inside the same function or its immediate call chain; any fix touches the same code. Tracking them separately would force multiple PRs against one function — see the rollup doc.

Combined fix

1. Error classification — introduce RefreshError { Revoked, Transient, Permanent }. Classify: 400 invalid_grant -> Revoked (the only outcome that flips back to a re-auth prompt, Ok(None)); 5xx / timeout / transport -> Transient (keep the refresh token, retry later); else -> Permanent. Transient/Permanent surface as a new McpOAuthError::RefreshFailed so the connection layer keeps the refresh token instead of discarding it. Only the short OAuth error code is parsed from the body — never the token-shaped fields.
2. Single-flight — process-global per-server_url lock (KernelOAuthProvider is stateless and rebuilt per request, so the lock must be static to serialize across instances). After acquiring the lock, re-read expires_at from the vault and return the peer's freshly-stored token without a second refresh POST.
3. Eliminate the unwrap — find_any_with_refresh returns the refresh token as a non-optional String; the Some(..) arm becomes the type-level proof.

PR closing this issue follows.