⚠️ fix: OAuth Error and Token Expiry Detection and Reporting Improvements (#10922)

* fix: create new flows on invalid_grant errors

* chore: fix failing test

* chore: keep isOAuthError test function in sync with implementation

* test: add tests for OAuth error detection on invalid grant errors

* test: add tests for creating new flows when token expires

* test: add test for flow clean up prior to creation

* refactor: consolidate token expiration handling in FlowStateManager

- Removed the old token expiration checks and replaced them with a new method, `isTokenExpired`, to streamline the logic.
- Introduced `normalizeExpirationTimestamp` to handle timestamp normalization for both seconds and milliseconds.
- Updated tests to ensure proper functionality of flow management with token expiration scenarios.

* fix: conditionally setup cleanup handlers in FlowStateManager

- Updated the FlowStateManager constructor to only call setupCleanupHandlers if the ci parameter is not set, improving flexibility in flow management.

* chore: enhance OAuth token refresh logging

- Introduced a new method, `processRefreshResponse`, to streamline the processing of token refresh responses from the OAuth server.
- Improved logging to provide detailed information about token refresh operations, including whether new tokens were received and if the refresh token was rotated.
- Updated existing token handling logic to utilize the new method, ensuring consistency and clarity in token management.

* chore: enhance logging for MCP server reinitialization

- Updated the logging in the reinitMCPServer function to provide more detailed information about the response, including success status, OAuth requirements, presence of the OAuth URL, and the count of tools involved. This improves the clarity and usefulness of logs for debugging purposes.

---------

Co-authored-by: Danny Avila <danny@librechat.ai>

packages/api/src/mcp/oauth/handler.ts

@@ -558,6 +558,39 @@ export class MCPOAuthHandler {
       : `${baseUrl}/api/mcp/oauth/callback`;
   }
 
+  /**
+   * Processes and logs a token refresh response from an OAuth server.
+   * Normalizes the response to MCPOAuthTokens format and logs debug info about refresh token rotation.
+   */
+  private static processRefreshResponse(
+    tokens: Record<string, unknown>,
+    serverName: string,
+    source: string,
+  ): MCPOAuthTokens {
+    const hasNewRefreshToken = !!tokens.refresh_token;
+
+    logger.debug(`[MCPOAuth] Token refresh response (${source})`, {
+      serverName,
+      has_new_access_token: !!tokens.access_token,
+      has_new_refresh_token: hasNewRefreshToken,
+      refresh_token_rotated: hasNewRefreshToken,
+      expires_in: tokens.expires_in,
+    });
+
+    if (!hasNewRefreshToken) {
+      logger.debug(
+        `[MCPOAuth] OAuth server did not return new refresh_token for ${serverName} - existing refresh token remains valid (normal for non-rotating providers)`,
+      );
+    }
+
+    return {
+      ...tokens,
+      obtained_at: Date.now(),
+      expires_at:
+        typeof tokens.expires_in === 'number' ? Date.now() + tokens.expires_in * 1000 : undefined,
+    } as MCPOAuthTokens;
+  }
+
   /**
    * Refreshes OAuth tokens using a refresh token
    */
@@ -687,12 +720,7 @@ export class MCPOAuthHandler {
         }
 
         const tokens = await response.json();
-
-        return {
-          ...tokens,
-          obtained_at: Date.now(),
-          expires_at: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined,
-        };
+        return this.processRefreshResponse(tokens, metadata.serverName, 'stored client info');
       }
 
       // Fallback: If we have pre-configured OAuth settings, use them
@@ -771,12 +799,7 @@ export class MCPOAuthHandler {
         }
 
         const tokens = await response.json();
-
-        return {
-          ...tokens,
-          obtained_at: Date.now(),
-          expires_at: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined,
-        };
+        return this.processRefreshResponse(tokens, metadata.serverName, 'pre-configured OAuth');
       }
 
       /** For auto-discovered OAuth, we need the server URL */
@@ -828,12 +851,7 @@ export class MCPOAuthHandler {
       }
 
       const tokens = await response.json();
-
-      return {
-        ...tokens,
-        obtained_at: Date.now(),
-        expires_at: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined,
-      };
+      return this.processRefreshResponse(tokens, metadata.serverName, 'auto-discovered OAuth');
     } catch (error) {
       logger.error(`[MCPOAuth] Failed to refresh tokens for ${metadata.serverName}`, error);
       throw error;