fix(auth): ask for re-authorization when the OAuth2 refresh token is revoked - #7731

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: OAuth2: after a refresh fails with invalid_grant, the expired token is returned forever and the user is never asked to re-authorize #7730

Problem

When the token endpoint rejects an OAuth2 refresh with invalid_grant (the refresh token was revoked or expired), OAuth2CredentialRefresher.refresh logs the error and returns the stale credential, and CredentialManager.get_auth_credential returns and re-saves it. Authenticated tools (AuthenticatedFunctionTool, MCP toolset auth) only call request_credential when get_auth_credential returns None, so they keep sending a dead access token and the user is never asked to re-authorize.

Solution

• OAuth2CredentialRefresher.refresh raises a new CredentialRevokedError (a CredentialRefresherError subclass) when the authlib/requests error is invalid_grant.
• CredentialManager.get_auth_credential catches it and returns None without saving, so the existing request_credential flow asks for authorization again. If the dead credential came from the credential store, a fresh auth response from the user is still preferred, exchanged and saved, so a revoked stored credential cannot shadow the new authorization.
• Every other failure (network errors, 5xx, other OAuth2 errors) keeps the stale token as before. ToolAuthHandler._refresh_and_store already wraps refresher.refresh in except Exception, so the RestApiTool 401 recovery is unchanged.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

New cases: invalid_grant (both InvalidGrantError and OAuth2Error(error="invalid_grant")) raises in the refresher, server_error keeps the stale token, a revoked credential returns None and is not saved, a fresh auth response wins over a revoked stored credential, and _refresh_credential propagates the error.

• With the credential_manager.py and oauth2_credential_refresher.py changes reverted: 4 failed, 73 passed.
• With the fix: tests/unittests/auth 346 passed, tests/unittests/tools 3310 passed.

Manual End-to-End (E2E) Tests:

Local HTTP token endpoint, a real CredentialManager and authlib session, stored credential expired with access_token=STALE:

BEFORE  invalid_grant (400): result=STALE, saved=True
BEFORE  transient 503:       result=STALE, saved=True
AFTER   invalid_grant (400): result=None,  saved=False
AFTER   transient 503:       result=STALE, saved=True

Not run: the full repo suite, and a live Google OAuth flow.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

• invalid_grant is detected through the .error attribute authlib parses from the token response. A provider that signals it in a non-standard body stays on the old keep-stale path.
• The dead stored credential is not deleted from the credential service. Each turn tries one refresh until the user re-authorizes.
• A sibling PR for BaseAuthenticatedTool saves invalid credentials #3016 (stored credential rejected with 401/403) also touches credential_manager.py. The two branches merge cleanly.

Authored by Mihir Inamdar.