🔌 fix: Resolve MCP OAuth flow state race condition (#11941)

* 🔌 fix: Resolve MCP OAuth flow state race condition

The OAuth callback arrives before the flow state is stored because
`createFlow()` returns a long-running Promise that only resolves on
flow COMPLETION, not when the initial PENDING state is persisted.
Calling it fire-and-forget with `.catch(() => {})` meant the redirect
happened before the state existed, causing "Flow state not found"
errors.

Changes:
- Add `initFlow()` to FlowStateManager that stores PENDING state and
  returns immediately, decoupling state persistence from monitoring
- Await `initFlow()` before emitting the OAuth redirect so the
  callback always finds existing state
- Keep `createFlow()` in the background for monitoring, but log
  warnings instead of silently swallowing errors
- Increase FLOWS cache TTL from 3 minutes to 10 minutes to give
  users more time to complete OAuth consent screens

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* 🔌 refactor: Revert FLOWS cache TTL change

The race condition fix (initFlow) is sufficient on its own.
TTL configurability should be a separate enhancement via
librechat.yaml mcpSettings rather than a hardcoded increase.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* 🔌 fix: Address PR review — restore FLOWS TTL, fix blocking-path race, clean up dead args

- Restore FLOWS cache TTL to 10 minutes (was silently dropped back to 3)
- Add initFlow before oauthStart in blocking handleOAuthRequired path
  to guarantee state persistence before any redirect
- Pass {} to createFlow metadata arg (dead after initFlow writes state)
- Downgrade background monitor .catch from logger.warn to logger.debug
- Replace process.nextTick with Promise.resolve in test (correct semantics)
- Add initFlow TTL assertion test
- Add blocking-path ordering test (initFlow → oauthStart → createFlow)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

packages/api/src/mcp/MCPConnectionFactory.ts

@@ -328,9 +328,14 @@ export class MCPConnectionFactory {
             await this.flowManager!.deleteFlow(newFlowId, 'mcp_oauth');
           }
 
-          this.flowManager!.createFlow(newFlowId, 'mcp_oauth', flowMetadata, this.signal).catch(
-            () => {},
-          );
+          // Store flow state BEFORE redirecting so the callback can find it
+          await this.flowManager!.initFlow(newFlowId, 'mcp_oauth', flowMetadata);
+
+          // Start monitoring in background — createFlow will find the existing PENDING state
+          // written by initFlow above, so metadata arg is unused (pass {} to make that explicit)
+          this.flowManager!.createFlow(newFlowId, 'mcp_oauth', {}, this.signal).catch((error) => {
+            logger.debug(`${this.logPrefix} OAuth flow monitor ended`, error);
+          });
 
           if (this.oauthStart) {
             logger.info(`${this.logPrefix} OAuth flow started, issuing authorization URL`);
@@ -512,6 +517,9 @@ export class MCPConnectionFactory {
         this.serverConfig.oauth,
       );
 
+      // Store flow state BEFORE redirecting so the callback can find it
+      await this.flowManager.initFlow(newFlowId, 'mcp_oauth', flowMetadata as FlowMetadata);
+
       if (typeof this.oauthStart === 'function') {
         logger.info(`${this.logPrefix} OAuth flow started, issued authorization URL to user`);
         await this.oauthStart(authorizationUrl);
@@ -521,13 +529,9 @@ export class MCPConnectionFactory {
         );
       }
 
-      /** Tokens from the new flow */
-      const tokens = await this.flowManager.createFlow(
-        newFlowId,
-        'mcp_oauth',
-        flowMetadata as FlowMetadata,
-        this.signal,
-      );
+      // createFlow will find the existing PENDING state written by initFlow above,
+      // so metadata arg is unused (pass {} to make that explicit)
+      const tokens = await this.flowManager.createFlow(newFlowId, 'mcp_oauth', {}, this.signal);
       if (typeof this.oauthEnd === 'function') {
         await this.oauthEnd();
       }