🛡️ fix: Secure MCP/Actions OAuth Flows, Resolve Race Condition & Tool Cache Cleanup (#11756)

* 🔧 fix: Update OAuth error message for clarity

- Changed the default error message in the OAuth error route from 'Unknown error' to 'Unknown OAuth error' to provide clearer context during authentication failures.

* 🔒 feat: Enhance OAuth flow with CSRF protection and session management

- Implemented CSRF protection for OAuth flows by introducing `generateOAuthCsrfToken`, `setOAuthCsrfCookie`, and `validateOAuthCsrf` functions.
- Added session management for OAuth with `setOAuthSession` and `validateOAuthSession` middleware.
- Updated routes to bind CSRF tokens for MCP and action OAuth flows, ensuring secure authentication.
- Enhanced tests to validate CSRF handling and session management in OAuth processes.

* 🔧 refactor: Invalidate cached tools after user plugin disconnection

- Added a call to `invalidateCachedTools` in the `updateUserPluginsController` to ensure that cached tools are refreshed when a user disconnects from an MCP server after a plugin authentication update. This change improves the accuracy of tool data for users.

* chore: imports order

* fix: domain separator regex usage in ToolService

- Moved the declaration of `domainSeparatorRegex` to avoid redundancy in the `loadActionToolsForExecution` function, improving code clarity and performance.

* chore: OAuth flow error handling and CSRF token generation

- Enhanced the OAuth callback route to validate the flow ID format, ensuring proper error handling for invalid states.
- Updated the CSRF token generation function to require a JWT secret, throwing an error if not provided, which improves security and clarity in token generation.
- Adjusted tests to reflect changes in flow ID handling and ensure robust validation across various scenarios.

packages/api/src/mcp/MCPConnectionFactory.ts

@@ -298,38 +298,45 @@ export class MCPConnectionFactory {
     const oauthHandler = async (data: { serverUrl?: string }) => {
       logger.info(`${this.logPrefix} oauthRequired event received`);
 
-      // If we just want to initiate OAuth and return, handle it differently
       if (this.returnOnOAuth) {
         try {
           const config = this.serverConfig;
-          const { authorizationUrl, flowId, flowMetadata } =
-            await MCPOAuthHandler.initiateOAuthFlow(
-              this.serverName,
-              data.serverUrl || '',
-              this.userId!,
-              config?.oauth_headers ?? {},
-              config?.oauth,
+          const flowId = MCPOAuthHandler.generateFlowId(this.userId!, this.serverName);
+          const existingFlow = await this.flowManager!.getFlowState(flowId, 'mcp_oauth');
+
+          if (existingFlow?.status === 'PENDING') {
+            logger.debug(
+              `${this.logPrefix} PENDING OAuth flow already exists, skipping new initiation`,
             );
+            connection.emit('oauthFailed', new Error('OAuth flow initiated - return early'));
+            return;
+          }
 
-          // Delete any existing flow state to ensure we start fresh
-          // This prevents stale codeVerifier issues when re-authenticating
-          await this.flowManager!.deleteFlow(flowId, 'mcp_oauth');
+          const {
+            authorizationUrl,
+            flowId: newFlowId,
+            flowMetadata,
+          } = await MCPOAuthHandler.initiateOAuthFlow(
+            this.serverName,
+            data.serverUrl || '',
+            this.userId!,
+            config?.oauth_headers ?? {},
+            config?.oauth,
+          );
 
-          // Create the flow state so the OAuth callback can find it
-          // We spawn this in the background without waiting for it
-          // Pass signal so the flow can be aborted if the request is cancelled
-          this.flowManager!.createFlow(flowId, 'mcp_oauth', flowMetadata, this.signal).catch(() => {
-            // The OAuth callback will resolve this flow, so we expect it to timeout here
-            // or it will be aborted if the request is cancelled - both are fine
-          });
+          if (existingFlow) {
+            await this.flowManager!.deleteFlow(newFlowId, 'mcp_oauth');
+          }
+
+          this.flowManager!.createFlow(newFlowId, 'mcp_oauth', flowMetadata, this.signal).catch(
+            () => {},
+          );
 
           if (this.oauthStart) {
             logger.info(`${this.logPrefix} OAuth flow started, issuing authorization URL`);
             await this.oauthStart(authorizationUrl);
           }
 
-          // Emit oauthFailed to signal that connection should not proceed
-          // but OAuth was successfully initiated
           connection.emit('oauthFailed', new Error('OAuth flow initiated - return early'));
           return;
         } catch (error) {
@@ -391,11 +398,9 @@ export class MCPConnectionFactory {
     logger.error(`${this.logPrefix} Failed to establish connection.`);
   }
 
-  // Handles connection attempts with retry logic and OAuth error handling
   private async connectTo(connection: MCPConnection): Promise<void> {
     const maxAttempts = 3;
     let attempts = 0;
-    let oauthHandled = false;
 
     while (attempts < maxAttempts) {
       try {
@@ -408,22 +413,6 @@ export class MCPConnectionFactory {
         attempts++;
 
         if (this.useOAuth && this.isOAuthError(error)) {
-          // For returnOnOAuth mode, let the event handler (handleOAuthEvents) deal with OAuth
-          // We just need to stop retrying and let the error propagate
-          if (this.returnOnOAuth) {
-            logger.info(
-              `${this.logPrefix} OAuth required (return on OAuth mode), stopping retries`,
-            );
-            throw error;
-          }
-
-          // Normal flow - wait for OAuth to complete
-          if (this.oauthStart && !oauthHandled) {
-            oauthHandled = true;
-            logger.info(`${this.logPrefix} Handling OAuth`);
-            await this.handleOAuthRequired();
-          }
-          // Don't retry on OAuth errors - just throw
           logger.info(`${this.logPrefix} OAuth required, stopping connection attempts`);
           throw error;
         }
@@ -499,26 +488,15 @@ export class MCPConnectionFactory {
       /** Check if there's already an ongoing OAuth flow for this flowId */
       const existingFlow = await this.flowManager.getFlowState(flowId, 'mcp_oauth');
 
-      // If any flow exists (PENDING, COMPLETED, FAILED), cancel it and start fresh
-      // This ensures the user always gets a new OAuth URL instead of waiting for stale flows
       if (existingFlow) {
         logger.debug(
-          `${this.logPrefix} Found existing OAuth flow (status: ${existingFlow.status}), cancelling to start fresh`,
+          `${this.logPrefix} Found existing OAuth flow (status: ${existingFlow.status}), cleaning up to start fresh`,
         );
         try {
-          if (existingFlow.status === 'PENDING') {
-            await this.flowManager.failFlow(
-              flowId,
-              'mcp_oauth',
-              new Error('Cancelled for new OAuth request'),
-            );
-          } else {
-            await this.flowManager.deleteFlow(flowId, 'mcp_oauth');
-          }
+          await this.flowManager.deleteFlow(flowId, 'mcp_oauth');
         } catch (error) {
-          logger.warn(`${this.logPrefix} Failed to cancel existing OAuth flow`, error);
+          logger.warn(`${this.logPrefix} Failed to clean up existing OAuth flow`, error);
         }
-        // Continue to start a new flow below
       }
 
       logger.debug(`${this.logPrefix} Initiating new OAuth flow for ${this.serverName}...`);