* ⏳ fix: Extend and decouple MCP OAuth flow timeouts
The OAuth auth button disappeared after 2 minutes (the internal OAuth
handling timeout) while the flow state lived for 3 minutes, leaving users
who didn't click immediately stuck in an unrecoverable re-auth loop. The
handling timeouts also reused the connection/init timeout, so a short
initTimeout would shrink the OAuth window further.
- Add MCP_OAUTH_HANDLING_TIMEOUT (10m) and MCP_OAUTH_FLOW_TTL (15m) to mcpConfig
- Decouple the reactive/proactive OAuth waits from initTimeout/connectionTimeout
- Use OAUTH_FLOW_TTL for the FlowStateManager TTL and the UI status window
- Ensure the flow TTL outlives the handling timeout, fixing the
"Flow state not found" race
- Remove dead FLOW_TTL constant and document new env vars
Fixes#13615
* ⏳ fix: Coordinate OAuth pending window with handling timeout
Address Codex review: the extended OAuth wait was still capped by other
timeouts that were not updated.
- Align PENDING_STALE_MS (button validity + pending-flow reuse window)
with MCP_OAUTH_HANDLING_TIMEOUT so a flow stays reusable for the full
wait instead of 2 minutes (Finding 3)
- Clamp MCP_OAUTH_FLOW_TTL to never fall below the handling timeout so a
callback near the deadline still finds its flow state (Finding 2)
- Floor attemptToConnect's timeout to the handling window for OAuth
servers so the reactive in-connect OAuth wait is not killed by the
30s connection timeout (Finding 1)
- Update flow staleness tests to reference the threshold symbolically
* ⏳ fix: Align OAuth window across status, action flows, and client polling
Address Codex round 2: extending the server wait exposed three more
windows that were still capped or now over-extended.
- checkOAuthFlowStatus reports a PENDING flow as active only within the
usable PENDING_STALE_MS window, not the longer Keyv retention TTL, so
the connect button reappears instead of a stuck 'connecting' state
- Give Action (custom tool) OAuth its own FlowStateManager on the prior
3-minute TTL so the longer MCP OAuth TTL can't leave an action tool
call waiting up to 15 minutes
- Extend the MCP server-card client polling to the 10-minute handling
window so a user who completes OAuth after 3 minutes is still picked up
* 🧪 test: Make stale-flow CSRF test track PENDING_STALE_MS
The CSRF-fallback stale-flow test hardcoded a 3-minute age, which is now
within the 10-minute PENDING_STALE_MS window and was wrongly treated as
active. Derive the age from PENDING_STALE_MS so it tracks the constant.
* ⏳ fix: Add grace buffers and surface OAuth timeout to the client
Address Codex round 3 (near-deadline edges):
- Clamp MCP_OAUTH_FLOW_TTL to handling timeout + 60s grace (not equality),
so flow state outlives the wait instead of expiring at the same instant
- Extend attemptToConnect's OAuth floor by a 60s grace so a user who
authorizes near the deadline still gets the post-OAuth reconnect
- Surface OAUTH_HANDLING_TIMEOUT on the connection-status response and
have the client poll for the configured window instead of a hardcoded
10 minutes, so a tuned server deadline isn't capped on the client
* ⏳ fix: Refresh client OAuth timeout from the first status refetch
If the connection-status cache is empty when polling starts, the client
captured the 10-minute fallback and never picked up a tuned oauthTimeout.
Re-read it after each refetch so a longer configured deadline is honored
even on a cold cache.
* 📝 refactor: Type oauthTimeout on MCPConnectionStatusResponse
Declare the oauthTimeout field on the shared response type in
data-provider instead of an ad-hoc inline cast in the client hook, and
replace the pre-existing 'as any' on the status query read with the
typed getQueryData. Type-level only; no runtime change.
* 🔧 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.
* chore: Update @modelcontextprotocol/sdk to version 1.12.3 in package.json and package-lock.json
- Bump version of @modelcontextprotocol/sdk to 1.12.3 to incorporate recent updates.
- Update dependencies for ajv and cross-spawn to their latest versions.
- Add ajv as a new dependency in the sdk module.
- Include json-schema-traverse as a new dependency in the sdk module.
* feat: @librechat/auth
* feat: Add crypto module exports to auth package
- Introduced a new crypto module by creating index.ts in the crypto directory.
- Updated the main index.ts of the auth package to export from the new crypto module.
* feat: Update package dependencies and build scripts for auth package
- Added @librechat/auth as a dependency in package.json and package-lock.json.
- Updated build scripts to include the auth package in both frontend and bun build processes.
- Removed unused mongoose and openid-client dependencies from package-lock.json for cleaner dependency management.
* refactor: Migrate crypto utility functions to @librechat/auth
- Replaced local crypto utility imports with the new @librechat/auth package across multiple files.
- Removed the obsolete crypto.js file and its exports.
- Updated relevant services and models to utilize the new encryption and decryption methods from @librechat/auth.
* feat: Enhance OAuth token handling and update dependencies in auth package
* chore: Remove Token model and TokenService due to restructuring of OAuth handling
- Deleted the Token.js model and TokenService.js, which were responsible for managing OAuth tokens.
- This change is part of a broader refactor to streamline OAuth token management and improve code organization.
* refactor: imports from '@librechat/auth' to '@librechat/api' and add OAuth token handling functionality
* refactor: Simplify logger usage in MCP and FlowStateManager classes
* chore: fix imports
* feat: Add OAuth configuration schema to MCP with token exchange method support
* feat: FIRST PASS Implement MCP OAuth flow with token management and error handling
- Added a new route for handling OAuth callbacks and token retrieval.
- Integrated OAuth token storage and retrieval mechanisms.
- Enhanced MCP connection to support automatic OAuth flow initiation on 401 errors.
- Implemented dynamic client registration and metadata discovery for OAuth.
- Updated MCPManager to manage OAuth tokens and handle authentication requirements.
- Introduced comprehensive logging for OAuth processes and error handling.
* refactor: Update MCPConnection and MCPManager to utilize new URL handling
- Added a `url` property to MCPConnection for better URL management.
- Refactored MCPManager to use the new `url` property instead of a deprecated method for OAuth handling.
- Changed logging from info to debug level for flow manager and token methods initialization.
- Improved comments for clarity on existing tokens and OAuth event listener setup.
* refactor: Improve connection timeout error messages in MCPConnection and MCPManager and use initTimeout for connection
- Updated the connection timeout error messages to include the duration of the timeout.
- Introduced a configurable `connectTimeout` variable in both MCPConnection and MCPManager for better flexibility.
* chore: cleanup MCP OAuth Token exchange handling; fix: erroneous use of flowsCache and remove verbose logs
* refactor: Update MCPManager and MCPTokenStorage to use TokenMethods for token management
- Removed direct token storage handling in MCPManager and replaced it with TokenMethods for better abstraction.
- Refactored MCPTokenStorage methods to accept parameters for token operations, enhancing flexibility and readability.
- Improved logging messages related to token persistence and retrieval processes.
* refactor: Update MCP OAuth handling to use static methods and improve flow management
- Refactored MCPOAuthHandler to utilize static methods for initiating and completing OAuth flows, enhancing clarity and reducing instance dependencies.
- Updated MCPManager to pass flowManager explicitly to OAuth handling methods, improving flexibility in flow state management.
- Enhanced comments and logging for better understanding of OAuth processes and flow state retrieval.
* refactor: Integrate token methods into createMCPTool for enhanced token management
* refactor: Change logging from info to debug level in MCPOAuthHandler for improved log management
* chore: clean up logging
* feat: first pass, auth URL from MCP OAuth flow
* chore: Improve logging format for OAuth authentication URL display
* chore: cleanup mcp manager comments
* feat: add connection reconnection logic in MCPManager
* refactor: reorganize token storage handling in MCP
- Moved token storage logic from MCPManager to a new MCPTokenStorage class for better separation of concerns.
- Updated imports to reflect the new token storage structure.
- Enhanced methods for storing, retrieving, updating, and deleting OAuth tokens, improving overall token management.
* chore: update comment for SYSTEM_USER_ID in MCPManager for clarity
* feat: implement refresh token functionality in MCP
- Added refresh token handling in MCPManager to support token renewal for both app-level and user-specific connections.
- Introduced a refreshTokens function to facilitate token refresh logic.
- Enhanced MCPTokenStorage to manage client information and refresh token processes.
- Updated logging for better traceability during token operations.
* chore: cleanup @librechat/auth
* feat: implement MCP server initialization in a separate service
- Added a new service to handle the initialization of MCP servers, improving code organization and readability.
- Refactored the server startup logic to utilize the new initializeMCP function.
- Removed redundant MCP initialization code from the main server file.
* fix: don't log auth url for user connections
* feat: enhance OAuth flow with success and error handling components
- Updated OAuth callback routes to redirect to new success and error pages instead of sending status messages.
- Introduced `OAuthSuccess` and `OAuthError` components to provide user feedback during authentication.
- Added localization support for success and error messages in the translation files.
- Implemented countdown functionality in the success component for a better user experience.
* fix: refresh token handling for user connections, add missing URL and methods
- add standard enum for system user id and helper for determining app-lvel vs. user-level connections
* refactor: update token handling in MCPManager and MCPTokenStorage
* fix: improve error logging in OAuth authentication handler
* fix: concurrency issues for both login url emission and concurrency of oauth flows for shared flows (same user, same server, multiple calls for same server)
* fix: properly fail shared flows for concurrent server calls and prevent duplication of tokens
* chore: remove unused auth package directory from update configuration
* ci: fix mocks in samlStrategy tests
* ci: add mcpConfig to AppService test setup
* chore: remove obsolete MCP OAuth implementation documentation
* fix: update build script for API to use correct command
* chore: bump version of @librechat/api to 1.2.4
* fix: update abort signal handling in createMCPTool function
* fix: add optional clientInfo parameter to refreshTokensFunction metadata
* refactor: replace app.locals.availableTools with getCachedTools in multiple services and controllers for improved tool management
* fix: concurrent refresh token handling issue
* refactor: add signal parameter to getUserConnection method for improved abort handling
* chore: JSDoc typing for `loadEphemeralAgent`
* refactor: update isConnectionActive method to use destructured parameters for improved readability
* feat: implement caching for MCP tools to handle app-level disconnects for loading list of tools
* ci: fix agent test
- Enhanced the OAuth callback and action creation processes to include the `token_exchange_method` parameter.
- Updated the `TokenService` to handle different token exchange methods, allowing for either 'default_post' or 'basic_auth_header' approaches.
- Improved the handling of access tokens and refresh tokens based on the specified exchange method.
* chore: update @librechat/agents dependency to version 2.4.15
* refactor: Prevent memory leaks by nullifying boundModel.client in disposeClient function
* fix: use of proxy, use undici
* chore: update @librechat/agents dependency to version 2.4.16
* Revert "fix: use of proxy, use undici"
This reverts commit 83153cd582.
* fix: ensure fetch is imported for HTTP requests
* fix: replace direct OpenAI import with CustomOpenAIClient from @librechat/agents
* fix: update keyv peer dependency to version 5.3.2
* fix: update keyv dependency to version 5.3.2
* refactor: replace KeyvMongo with custom implementation and update flow state manager usage
* fix: update @librechat/agents dependency to version 2.4.17
* ci: update OpenAIClient tests to use CustomOpenAIClient from @librechat/agents
* refactor: remove KeyvMongo mock and related dependencies
* feat: Update MCP package version and dependencies; refactor ToolContentPart type
* refactor: Change module type to commonjs and update rollup configuration, remove unused dev dependency
* refactor: Change async calls to synchronous for MCP and FlowStateManager retrieval
* chore: Add eslint disable comment for i18next rule in DropdownPopup component
* fix: improve statefulness of mcp servers selected if some were removed since last session
* feat: implement conversation storage cleanup functions and integrate them into mutation success handlers
* feat: enhance storage condition logic in useLocalStorageAlt to prevent unnecessary local storage writes
* refactor: streamline local storage update logic in useLocalStorageAlt
* ✨feat: OAuth for Actions
* WIP: PoC flow state manager
* refactor: Add identifier field to token model from action schema
* chore: fix potential file type issues
* ci: fix type issue with action metadata auth
* fix: ensure FlowManagerOptions has a default ttl value
* WIP: OAUTH actions
* WIP: first pass OAuth Action
* fix: standardize identifier usage in OAuth flow handling
* fix: update token retrieval to include userId in query and use correct identifier
* refacotr: update token retrieval to use userId for OAuth token query
* feat: Tool Call Auth styling
* fix: streamline token creation and add type field to token schema
* refactor: cleanup OAuth flow by encrypting client credentials and ensuring oauth operations only run under condition
* refactor: use encrypted credentials in OAuth callback
* fix: update Token collection indexes to use expiresAt TTL index and not createdAt legacy index
* refactor: enhance Token index cleanup by improving logging and removing redundant index creation logic
* refactor: remove unused OAuth login route and related logic for improved clarity
* refactor: replace fetch with axios for OAuth token exchange and improve error handling
* refactor: better UX after authentication before oauth tool execution
* refactor: implement cleanup handlers for FlowStateManager intervals to enhance resource management
* refactor: encrypt OAuth tokens before storing and decrypt upon retrieval for enhanced security
* refactor: enhance authentication success page with improved styling and countdown feature
* refactor: add response_type parameter to OAuth redirect URI for improved compatibility
* chore: update translation.json new localizations
* chore: remove unused OGDialog import from OGDialogTemplate component
* refactor: Actions Auth using new Dialog styling, use same component with Agents/Assistants
* refactor: update removeNullishValues function to support removal of empty strings and adjust transform usage in schemas
* chore: bump version of librechat-data-provider to 0.7.6991
* refactor: integrate removeNullishValues function to clean metadata before encryption in agent and assistant routes
* refactor: update OAuth input fields to use 'password' type for better security
* refactor: update localization placeholders for sign-in message to use double curly braces
* refactor: add access_type parameter for offline access in createActionTool function
* refactor: implement handleOAuthToken function for token management and encryption
* feat: refresh token support
* refactor: add default expiration for access token and error handling for missing token
* feat: localizations for ActionAuth
* refactor: set refresh token expiration to null to not expire if expiry never given
* fix: prevent crash fromerror within async handleAbortError in AskController, EditController, and AgentController
* feat: Action Callback URL
* 🌍 i18n: Update translation.json with latest translations
* refactor: handle errors in flow state checking to prevent unhandled promise rejections
* fix: improve flow state concurrency to prevent multiple token creation calls
* refactor: RequestExecutor to use separate axios instance
* refactor: improve concurrency flows by keeping completed state until TTL expiry
* refactor: increase TTL for flow state management and adjust monitoring interval
* ci: mock axios instance creation in actions spec
* feat: add Babel and Jest configuration files; implement FlowStateManager tests with concurrency handling
* chore: add disableOAuth prop to ActionsAuth (not implemented for Assistants yet)
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
