Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔒 fix: Refresh MCP OBO Tokens From the Live OpenID Session (#15334)
Danny Avilafa913148fb8b
diff --git a/api/app/clients/tools/util/handleTools.js b/api/app/clients/tools/util/handleTools.jsindex aa20ba06c8..ec75adea76 100644--- a/api/app/clients/tools/util/handleTools.js+++ b/api/app/clients/tools/util/handleTools.js@@ -1,9 +1,10 @@-const { logger } = require('@librechat/data-schemas');+const { logger, getTenantId } = require('@librechat/data-schemas');const { Calculator, createSearchTool, createCodeExecutionTool } = require('@librechat/agents');const {checkAccess,toolkitParent,createSafeUser,+ createAuthIdentityContext,mcpToolPattern,loadWebSearchAuth,splitMCPToolKey,@@ -56,6 +57,7 @@ const {resolveCollisionAuditNames,} = require('~/server/services/MCP');const { getMCPRequestContext } = require('~/server/services/MCPRequestContext');+const { createOpenIDSessionTokenProvider } = require('~/server/services/OpenIDSessionRefresh');const { createFileSearchTool, primeFiles: primeSearchFiles } = require('./fileSearch');const { primeFiles: primeCodeFiles } = require('~/server/services/Files/Code/process');const { getUserPluginAuthValue } = require('~/server/services/PluginService');@@ -593,6 +595,24 @@ const loadTools = async ({const safeUser = createSafeUser(options.req?.user);const requestScopedConnections =options.requestScopedConnections ?? getMCPRequestContext(options.req, options.res);+ /**+ * Build the OBO upstream-token closure once at the request boundary (where+ * `req`/`res` are in scope) and thread the function into MCP handling, so the+ * MCP layer never receives the raw Express request. The closure reads/refreshes+ * the live `req.session.openidTokens` at tool-call time and mirrors rotations+ * to the `refreshToken` cookie when the response is still writable.+ */+ const oboIdentityContext = createAuthIdentityContext({+ user: options.req?.user,+ tenantId: getTenantId(),+ });+ const upstreamTokenProvider = createOpenIDSessionTokenProvider({+ req: options.req,+ res: options.res,+ user: options.req?.user,+ identityContext: oboIdentityContext,+ tokenPreference: 'access_token',+ });for (const [serverName, toolConfigs] of Object.entries(requestedMCPTools)) {index++;@@ -613,6 +633,8 @@ const loadTools = async ({requestBody: options.requestBody ?? options.req?.body,requestScopedConnections,res: options.res,+ upstreamTokenProvider,+ oboIdentityContext,streamId: options.req?._resumableStreamId || null,jobCreatedAt: options.jobCreatedAt,model: agent?.model ?? model,diff --git a/api/server/controllers/AuthController.js b/api/server/controllers/AuthController.jsindex 2445991ecc..10cd6766a3 100644--- a/api/server/controllers/AuthController.js+++ b/api/server/controllers/AuthController.js@@ -1,33 +1,38 @@const cookies = require('cookie');const jwt = require('jsonwebtoken');-const openIdClient = require('openid-client');+const crypto = require('node:crypto');const { logger } = require('@librechat/data-schemas');const {math,isEnabled,- findOpenIDUser,- getOpenIdIssuer,- buildOpenIDRefreshParams,+ createAuthIdentityContext,+ createOpenIDRefreshOwnershipError,+ isOpenIDRefreshOwnershipError,+ isOpenIDSessionIdentityMatch,OPENID_EXPIRY_BUFFER_SECONDS,} = require('@librechat/api');const {requestPasswordReset,- setOpenIDAuthTokens,- storeOpenIDSession,+ clearOpenIDAuthTokens,setCloudFrontAuthCookies,resetPassword,setAuthTokens,registerUser,} = require('~/server/services/AuthService');-const {- deleteAllUserSessions,- getUserById,- findSession,- updateUser,- findUser,-} = require('~/models');+const { deleteAllUserSessions, getUserById, findSession, updateUser } = require('~/models');const { getGraphApiToken } = require('~/server/services/GraphTokenService');-const { getOpenIdConfig, getOpenIdEmail } = require('~/strategies');+const { getRefreshTokenBridge } = require('~/server/services/RefreshTokenBridge');+const {+ recoverOpenIDRefreshBridge,+ refreshOpenIDUser,+ sendOpenIDAuthResponse,+} = require('~/server/services/OpenIDRefreshRecovery');+const {+ assertOpenIDRefreshFlightDeliveryAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ claimOpenIDRefreshFlightDelivery,+ releaseOpenIDRefreshFlightDelivery,+} = require('~/server/services/OpenIDRefreshFlight');const AUTH_REFRESH_USER_PROJECTION = '-password -__v -totpSecret -backupCodes -federatedTokens';/**@@ -67,7 +72,7 @@ const sanitizeUserForAuthResponse = (user) => {return safeUser;};-const getValidOpenIDReuseUserId = (parsedCookies) => {+const getValidOpenIDReuseUserId = (parsedCookies, refreshToken) => {const openidUserId = parsedCookies.openid_user_id;if (!openidUserId || !process.env.JWT_REFRESH_SECRET) {return null;@@ -75,14 +80,51 @@ const getValidOpenIDReuseUserId = (parsedCookies) => {try {const payload = jwt.verify(openidUserId, process.env.JWT_REFRESH_SECRET);- return typeof payload === 'object' && payload != null && typeof payload.id === 'string'- ? payload.id- : null;+ if (typeof payload !== 'object' || payload == null || typeof payload.id !== 'string') {+ return null;+ }+ if (refreshToken == null) {+ return payload.id;+ }+ if (typeof payload.refreshTokenHash !== 'string') {+ return null;+ }+ const refreshTokenHash = crypto.createHash('sha256').update(refreshToken).digest('base64url');+ return payload.refreshTokenHash === refreshTokenHash ? payload.id : null;} catch {return null;}};+const selectOpenIDRefreshToken = (openidTokens, parsedCookies) => {+ const sessionRefreshToken = openidTokens?.refreshToken;+ const browserRefreshToken = parsedCookies.refreshToken;+ const lastSyncedBrowserRefreshToken = openidTokens?.browserRefreshToken;+ const hasKnownBrowserRefreshTokenMarker =+ typeof lastSyncedBrowserRefreshToken === 'string' && lastSyncedBrowserRefreshToken.length > 0;+ const driftReference = hasKnownBrowserRefreshTokenMarker+ ? lastSyncedBrowserRefreshToken+ : sessionRefreshToken;++ if (browserRefreshToken && driftReference && browserRefreshToken !== driftReference) {+ logger.info('[refreshController] OpenID refresh token cookie differs from session state');+ return {+ refreshToken: sessionRefreshToken || browserRefreshToken,+ fallbackRefreshToken:+ sessionRefreshToken && browserRefreshToken !== sessionRefreshToken+ ? browserRefreshToken+ : null,+ cookieDiffersFromSession: true,+ };+ }++ return {+ refreshToken: sessionRefreshToken || browserRefreshToken,+ fallbackRefreshToken: null,+ cookieDiffersFromSession: false,+ };+};+const isRecentOpenIDSessionRefresh = (openidTokens) => {const lastRefreshedAt = Number(openidTokens?.lastRefreshedAt);const elapsed = Date.now() - lastRefreshedAt;@@ -91,6 +133,40 @@ const isRecentOpenIDSessionRefresh = (openidTokens) => {);};+const isInvalidGrantError = (error) => {+ const values = [+ error?.message,+ error?.error,+ error?.code,+ error?.response?.data?.error,+ error?.response?.data?.error_description,+ error?.body?.error,+ error?.body?.error_description,+ ];++ return values.some(+ (value) => typeof value === 'string' && value.toLowerCase().includes('invalid_grant'),+ );+};++const getAuthIdentitySource = (user) =>+ typeof user?.toObject === 'function' ? user.toObject() : user;++const isReusableOpenIDSessionIdentity = (openidTokens, user) => {+ const identitySource = getAuthIdentitySource(user);+ const expectedIdentity = createAuthIdentityContext({ user: identitySource });+ const matches = isOpenIDSessionIdentityMatch(openidTokens, expectedIdentity);+ if (!matches) {+ logger.warn('[refreshController] OpenID session token identity mismatch; forcing refresh', {+ userId: expectedIdentity.appUserId,+ has_session_user_id: Boolean(openidTokens?.appUserId),+ has_session_subject: Boolean(openidTokens?.openidSubject),+ has_session_issuer: Boolean(openidTokens?.openidIssuer),+ });+ }+ return matches;+};+const getReusableOpenIDSessionToken = (openidTokens) => {if (!isRecentOpenIDSessionRefresh(openidTokens)) {return null;@@ -120,6 +196,89 @@ const getReusableOpenIDSessionToken = (openidTokens) => {return null;};+const assertReusableOpenIDSessionGeneration = async (openidTokens) =>+ assertOpenIDRefreshSessionGenerationAvailable({+ key: openidTokens?.publicationFlightKey,+ ownerId: openidTokens?.publicationFlightOwnerId,+ });++/**+ * Serializes response delivery for one durable OpenID publication generation. A logout that+ * reaches the same flight either tombstones it before this claim or waits for the response to+ * finish before returning. The send callback keeps the final authorization check adjacent to the+ * synchronous Express write while allowing callers to do slow preparation under the lease.+ */+const withOpenIDResponseDelivery = async ({ res, openidTokens, context }, operation) => {+ let delivery;+ let responseSent = false;+ let releaseStarted = false;+ let listenersArmed = false;+ const releaseDelivery = async () => {+ if (!delivery || releaseStarted) {+ return;+ }+ releaseStarted = true;+ for (let attempt = 1; attempt <= 3; attempt++) {+ try {+ await releaseOpenIDRefreshFlightDelivery(delivery);+ return;+ } catch (error) {+ if (attempt === 3) {+ logger.warn(`[${context}] Failed to release OpenID response delivery`, {+ error: error instanceof Error ? error.message : error,+ });+ return;+ }+ await new Promise((resolve) => setTimeout(resolve, 25));+ }+ }+ };++ try {+ await assertReusableOpenIDSessionGeneration(openidTokens);+ if (openidTokens?.publicationFlightKey && openidTokens?.publicationFlightOwnerId) {+ const claimed = await claimOpenIDRefreshFlightDelivery({+ key: openidTokens.publicationFlightKey,+ ownerId: openidTokens.publicationFlightOwnerId,+ createdAt: openidTokens.publicationFlightCreatedAt,+ });+ if (!claimed.deliveryId) {+ throw new Error('OpenID response delivery claim returned no owner');+ }+ delivery = {+ key: openidTokens.publicationFlightKey,+ ownerId: openidTokens.publicationFlightOwnerId,+ deliveryId: claimed.deliveryId,+ };+ }++ const sendAuthorized = async (send) => {+ if (delivery) {+ await assertOpenIDRefreshFlightDeliveryAvailable(delivery);+ if (!listenersArmed && typeof res.once === 'function') {+ listenersArmed = true;+ res.once('finish', () => void releaseDelivery());+ res.once('close', () => void releaseDelivery());+ }+ } else {+ await assertReusableOpenIDSessionGeneration(openidTokens);+ }+ const response = send();+ responseSent = true;+ if (delivery && typeof res.once !== 'function') {+ await releaseDelivery();+ }+ return response;+ };++ return await operation(sendAuthorized);+ } finally {+ if (delivery && !responseSent) {+ await releaseDelivery();+ }+ }+};+const resetPasswordRequestController = async (req, res) => {try {const resetService = await requestPasswordReset(req);@@ -158,8 +317,9 @@ const refreshController = async (req, res) => {const token_provider = parsedCookies.token_provider;if (token_provider === 'openid' && isEnabled(process.env.OPENID_REUSE_TOKENS)) {- /** For OpenID users, read refresh token from session to avoid large cookie issues */- const refreshToken = req.session?.openidTokens?.refreshToken || parsedCookies.refreshToken;+ /** Prefer session refresh tokens unless the browser cookie proves the session is stale. */+ const { refreshToken, fallbackRefreshToken, cookieDiffersFromSession } =+ selectOpenIDRefreshToken(req.session?.openidTokens, parsedCookies);if (!refreshToken) {return res.status(200).send('Refresh token not provided');@@ -171,56 +331,91 @@ const refreshController = async (req, res) => {* Stale, missing, or near-expiry tokens fall through to refreshTokenGrant so* upstream revocations and cookie/session extension are checked regularly.*/- const reusableSessionToken = getReusableOpenIDSessionToken(req.session?.openidTokens);+ const reusableSessionToken = cookieDiffersFromSession+ ? null+ : getReusableOpenIDSessionToken(req.session?.openidTokens);const reuseUserId = reusableSessionToken ? getValidOpenIDReuseUserId(parsedCookies) : null;if (reuseUserId) {- const user = await getUserById(reuseUserId, AUTH_REFRESH_USER_PROJECTION);- if (user) {- const cloudFrontCookiesSet = setCloudFrontAuthCookies(req, res, user);- logger.debug('[refreshController] OpenID session token reused', {- token_type: reusableSessionToken.type,- has_id_token: Boolean(req.session?.openidTokens?.idToken),- has_access_token: Boolean(req.session?.openidTokens?.accessToken),- cloudfront_cookies_set: cloudFrontCookiesSet,- });- return res.status(200).send({- token: reusableSessionToken.token,- user: sanitizeUserForAuthResponse(user),- });+ const reuseSessionTokens = req.session?.openidTokens;+ try {+ const response = await withOpenIDResponseDelivery(+ {+ res,+ openidTokens: reuseSessionTokens,+ context: 'refreshController',+ },+ async (sendAuthorized) => {+ const user = await getUserById(reuseUserId, AUTH_REFRESH_USER_PROJECTION);+ if (!user || !isReusableOpenIDSessionIdentity(reuseSessionTokens, user)) {+ return undefined;+ }+ return sendAuthorized(() => {+ const cloudFrontCookiesSet = setCloudFrontAuthCookies(req, res, user);+ logger.debug('[refreshController] OpenID session token reused', {+ token_type: reusableSessionToken.type,+ has_id_token: Boolean(reuseSessionTokens?.idToken),+ has_access_token: Boolean(reuseSessionTokens?.accessToken),+ cloudfront_cookies_set: cloudFrontCookiesSet,+ });+ return res.status(200).send({+ token: reusableSessionToken.token,+ user: sanitizeUserForAuthResponse(user),+ });+ });+ },+ );+ if (response !== undefined) {+ return response;+ }+ } catch (error) {+ if (!isOpenIDRefreshOwnershipError(error)) {+ throw error;+ }+ clearOpenIDAuthTokens(req, res, reuseUserId, reuseSessionTokens?.tenantId);+ return res.status(403).send('Invalid OpenID refresh token');}}- const openIdConfig = getOpenIdConfig();- const refreshParams = buildOpenIDRefreshParams();- logger.debug('[refreshController] OpenID refresh params', {- has_scope: Boolean(process.env.OPENID_SCOPE),- has_refresh_audience: Boolean(process.env.OPENID_REFRESH_AUDIENCE),- });- const tokenset = await openIdClient.refreshTokenGrant(- openIdConfig,- refreshToken,- refreshParams,- );- logger.debug('[refreshController] OpenID refresh succeeded', {- has_access_token: Boolean(tokenset.access_token),- has_id_token: Boolean(tokenset.id_token),- has_refresh_token: Boolean(tokenset.refresh_token),- expires_in: tokenset.expires_in,- });- const claims = tokenset.claims();- const openidIssuer = getOpenIdIssuer(claims, openIdConfig);- const { user, error, migration } = await findOpenIDUser({- findUser,- email: getOpenIdEmail(claims),- openidId: claims.sub,- openidIssuer,- idOnTheSource: claims.oid,- strategyName: 'refreshController',- });+ const refreshUserId =+ req.session?.openidTokens?.appUserId ?? getValidOpenIDReuseUserId(parsedCookies);+ const refreshUser = refreshUserId+ ? await getUserById(refreshUserId, AUTH_REFRESH_USER_PROJECTION)+ : null;+ if (!refreshUser) {+ return res.status(403).send('Invalid OpenID refresh token');+ }- logger.debug(- `[refreshController] findOpenIDUser result: user=${user?.email ?? 'null'}, error=${error ?? 'null'}, migration=${migration}, userOpenidId=${user?.openidId ?? 'null'}, claimsSub=${claims.sub}`,- );+ let successfulRefreshToken = refreshToken;+ let refreshResult;+ try {+ refreshResult = await refreshOpenIDUser({+ req,+ res,+ user: refreshUser,+ refreshToken,+ browserRefreshToken: parsedCookies.refreshToken,+ strategyName: 'refreshController',+ deferPublication: true,+ });+ } catch (error) {+ if (!fallbackRefreshToken || !isInvalidGrantError(error)) {+ throw error;+ }+ logger.info(+ '[refreshController] Session refresh token was rejected; retrying the distinct browser token',+ );+ successfulRefreshToken = fallbackRefreshToken;+ refreshResult = await refreshOpenIDUser({+ req,+ res,+ user: refreshUser,+ refreshToken: fallbackRefreshToken,+ browserRefreshToken: parsedCookies.refreshToken,+ strategyName: 'refreshController (browser fallback)',+ deferPublication: true,+ });+ }+ const { tokenset, claims, openidIssuer, user, error, migration } = refreshResult;if (error || !user) {logger.warn(@@ -243,22 +438,118 @@ const refreshController = async (req, res) => {);}- const activeRefreshToken = tokenset.refresh_token || refreshToken;- await storeOpenIDSession(- user._id.toString(),- activeRefreshToken,- user.tenantId,- refreshToken,- );- const token = setOpenIDAuthTokens(tokenset, req, res, {- userId: user._id.toString(),- existingRefreshToken: refreshToken,- tenantId: user.tenantId,- });+ if (+ successfulRefreshToken !== refreshToken &&+ req.session?.openidTokens?.refreshToken === refreshToken+ ) {+ delete req.session.openidTokens;+ }- return res.status(200).send({ token, user: sanitizeUserForAuthResponse(user) });+ const token = await sendOpenIDAuthResponse({+ tokenset,+ user,+ existingRefreshToken: successfulRefreshToken,+ openidSubject: claims?.sub,+ openidIssuer,+ predecessorIdentity: {+ userId: refreshUser._id.toString(),+ tenantId: refreshUser.tenantId,+ openidIssuer: refreshUser.openidIssuer,+ },+ rejectedRefreshTokens: successfulRefreshToken === refreshToken ? [] : [refreshToken],+ req,+ res,+ });+ return await withOpenIDResponseDelivery(+ {+ res,+ openidTokens: req.session?.openidTokens,+ context: 'refreshController',+ },+ (sendAuthorized) =>+ sendAuthorized(() =>+ res.status(200).send({ token, user: sanitizeUserForAuthResponse(user) }),+ ),+ );} catch (error) {+ if (isOpenIDRefreshOwnershipError(error)) {+ clearOpenIDAuthTokens(+ req,+ res,+ req.session?.openidTokens?.appUserId,+ req.session?.openidTokens?.tenantId,+ );+ }logger.error('[refreshController] OpenID token refresh error', error);++ /**+ * Detect and recover from stale refresh-token cookie after SSE-triggered rotation.+ * If the initial refresh with the cookie fails with invalid_grant, check if a+ * recovery bridge exists. Bridges are stored when an OBO refresh rotates the token+ * but cannot set the browser cookie (headers already sent during SSE streaming).+ */+ const bridgeSourceToken = parsedCookies.refreshToken;+ if (isInvalidGrantError(error) && bridgeSourceToken) {+ // Bridge lookup uses the signed user-id cookie because /refresh is unauthenticated.+ const userId = getValidOpenIDReuseUserId(parsedCookies, bridgeSourceToken);+ if (userId) {+ try {+ const bridgeUser = await getUserById(userId, AUTH_REFRESH_USER_PROJECTION);+ if (!bridgeUser) {+ return res.status(403).send('Invalid OpenID refresh token');+ }++ const bridgedRefreshToken = await getRefreshTokenBridge({+ oldRefreshToken: bridgeSourceToken,+ userId,+ tenantId: bridgeUser.tenantId,+ openidIssuer: bridgeUser.openidIssuer,+ });++ if (bridgedRefreshToken) {+ logger.info(+ '[refreshController] Recovered via refresh-token bridge after invalid_grant',+ {+ userId,+ },+ );++ try {+ const { appAuthToken } = await recoverOpenIDRefreshBridge({+ req,+ res,+ refreshToken: bridgeSourceToken,+ bridgedRefreshToken,+ bridgeUser,+ });++ return await withOpenIDResponseDelivery(+ {+ res,+ openidTokens: req.session?.openidTokens,+ context: 'refreshController',+ },+ (sendAuthorized) =>+ sendAuthorized(() =>+ res.status(200).send({+ token: appAuthToken,+ user: sanitizeUserForAuthResponse(bridgeUser),+ }),+ ),+ );+ } catch (retryError) {+ logger.error('[refreshController] Bridge recovery retry failed', retryError);+ // Fall through to generic error response+ }+ }+ } catch (bridgeError) {+ logger.warn('[refreshController] Refresh-token bridge lookup failed', {+ error: bridgeError instanceof Error ? bridgeError.message : bridgeError,+ });+ }+ }+ }+return res.status(403).send('Invalid OpenID refresh token');}}@@ -340,12 +631,37 @@ const graphTokenController = async (req, res) => {});}- const tokenResponse = await getGraphApiToken(req.user, accessToken, scopes);-- res.json(tokenResponse);+ const sessionTokens = req.session?.openidTokens;+ const usesSessionToken = Boolean(+ sessionTokens?.accessToken && sessionTokens.accessToken === accessToken,+ );+ const requestBearer = req.headers?.authorization?.match(/^Bearer\s+(.+)$/i)?.[1];+ if (req.session && !usesSessionToken && requestBearer !== accessToken) {+ throw createOpenIDRefreshOwnershipError('OpenID session tokens are no longer available');+ }+ const exchangeAndSend = async (sendAuthorized) => {+ const tokenResponse = await getGraphApiToken(req.user, accessToken, scopes);+ return sendAuthorized(() => res.json(tokenResponse));+ };+ if (usesSessionToken) {+ return await withOpenIDResponseDelivery(+ {+ res,+ openidTokens: sessionTokens,+ context: 'graphTokenController',+ },+ exchangeAndSend,+ );+ }+ return await exchangeAndSend((send) => send());} catch (error) {+ if (isOpenIDRefreshOwnershipError(error)) {+ const userId = req.user?.id ?? req.user?._id?.toString?.();+ clearOpenIDAuthTokens(req, res, userId, req.session?.openidTokens?.tenantId);+ return res.status(401).json({ message: 'OpenID session is no longer authorized' });+ }logger.error('[graphTokenController] Failed to obtain Graph API token:', error);- res.status(500).json({+ return res.status(500).json({message: 'Failed to obtain Microsoft Graph token',});}diff --git a/api/server/controllers/AuthController.spec.js b/api/server/controllers/AuthController.spec.jsindex 7524df63d0..b9fd676bae 100644--- a/api/server/controllers/AuthController.spec.js+++ b/api/server/controllers/AuthController.spec.js@@ -5,6 +5,8 @@ jest.mock('~/server/services/GraphTokenService', () => ({getGraphApiToken: jest.fn(),}));jest.mock('~/server/services/AuthService', () => ({+ clearOpenIDAuthTokens: jest.fn(),+ getOpenIDAppAuthToken: jest.fn(),requestPasswordReset: jest.fn(),setOpenIDAuthTokens: jest.fn(),storeOpenIDSession: jest.fn(),@@ -16,18 +18,69 @@ jest.mock('~/server/services/AuthService', () => ({jest.mock('~/strategies', () => ({ getOpenIdConfig: jest.fn(), getOpenIdEmail: jest.fn() }));jest.mock('openid-client', () => ({ refreshTokenGrant: jest.fn() }));jest.mock('~/models', () => ({+ deleteSession: jest.fn(),deleteAllUserSessions: jest.fn(),getUserById: jest.fn(),findSession: jest.fn(),updateUser: jest.fn(),findUser: jest.fn(),}));+jest.mock('~/server/services/RefreshTokenBridge', () => ({+ OPENID_REFRESH_BRIDGE_GRACE_MS: 60 * 1000,+ createRefreshTokenBridgeFlightKey: jest.fn(() => 'bridge-flight-key'),+ deleteRefreshTokenBridges: jest.fn(),+ getRefreshTokenBridge: jest.fn(),+ storeRefreshTokenBridge: jest.fn(),+}));+jest.mock('~/server/services/OpenIDRefreshFlight', () => ({+ acquireOpenIDRefreshFlight: jest.fn(),+ assertOpenIDRefreshFlightDeliveryAvailable: jest.fn(),+ assertOpenIDRefreshFlightAvailable: jest.fn(),+ assertOpenIDRefreshSessionGenerationAvailable: jest.fn(),+ claimOpenIDRefreshFlightDelivery: jest.fn(),+ completeOpenIDRefreshFlight: jest.fn(),+ createOpenIDRefreshFlightKey: jest.fn(),+ failOpenIDRefreshFlight: jest.fn(),+ releaseOpenIDRefreshFlightDelivery: jest.fn(),+ revokeOpenIDRefreshFlights: jest.fn(),+ waitForOpenIDRefreshFlight: jest.fn(),+ withOpenIDRefreshFlightLease: jest.fn(),+}));+jest.mock('~/server/services/OpenIDSessionRefresh', () => ({+ refreshOpenIDSession: jest.fn(),+}));jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),OPENID_EXPIRY_BUFFER_SECONDS: 30,math: jest.fn((value, fallback) => fallback),isEnabled: jest.fn(),findOpenIDUser: jest.fn(),getOpenIdIssuer: jest.fn(() => 'https://issuer.example.com'),+ createAuthIdentityContext: jest.fn(({ user }) => ({+ appUserId: user?._id?.toString?.() ?? user?.id,+ openidSubject: user?.openidId,+ tenantId: user?.tenantId,+ openidIssuer: user?.openidIssuer,+ })),+ isOpenIDSessionIdentityMatch: jest.fn((sessionIdentity, expectedIdentity) => {+ const normalize = (value) => {+ if (value == null) {+ return undefined;+ }+ const normalized = typeof value === 'string' ? value.trim() : value.toString().trim();+ return normalized || undefined;+ };+ const normalizeIssuer = (value) => normalize(value)?.replace(/\/+$/, '');+ return (+ Boolean(normalize(sessionIdentity?.appUserId)) &&+ Boolean(normalize(sessionIdentity?.openidSubject)) &&+ normalize(sessionIdentity?.appUserId) === normalize(expectedIdentity?.appUserId) &&+ normalize(sessionIdentity?.openidSubject) === normalize(expectedIdentity?.openidSubject) &&+ normalize(sessionIdentity?.tenantId) === normalize(expectedIdentity?.tenantId) &&+ normalizeIssuer(sessionIdentity?.openidIssuer) ===+ normalizeIssuer(expectedIdentity?.openidIssuer)+ );+ }),buildOpenIDRefreshParams: jest.fn(() => {const params = {};if (process.env.OPENID_SCOPE) {@@ -40,6 +93,7 @@ jest.mock('@librechat/api', () => ({}),}));+const { createHash } = require('node:crypto');const openIdClient = require('openid-client');const jwt = require('jsonwebtoken');const { logger } = require('@librechat/data-schemas');@@ -47,25 +101,143 @@ const { isEnabled, findOpenIDUser, buildOpenIDRefreshParams } = require('@librecconst { graphTokenController, refreshController } = require('./AuthController');const { getGraphApiToken } = require('~/server/services/GraphTokenService');const {+ clearOpenIDAuthTokens,+ getOpenIDAppAuthToken,setOpenIDAuthTokens,storeOpenIDSession,setCloudFrontAuthCookies,setAuthTokens,} = require('~/server/services/AuthService');const { getOpenIdConfig, getOpenIdEmail } = require('~/strategies');-const { getUserById, findSession, updateUser } = require('~/models');+const { deleteSession, getUserById, findSession, updateUser } = require('~/models');+const {+ createRefreshTokenBridgeFlightKey,+ deleteRefreshTokenBridges,+ getRefreshTokenBridge,+ storeRefreshTokenBridge,+} = require('~/server/services/RefreshTokenBridge');+const {+ acquireOpenIDRefreshFlight,+ assertOpenIDRefreshFlightDeliveryAvailable,+ assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ claimOpenIDRefreshFlightDelivery,+ completeOpenIDRefreshFlight,+ createOpenIDRefreshFlightKey,+ failOpenIDRefreshFlight,+ releaseOpenIDRefreshFlightDelivery,+ revokeOpenIDRefreshFlights,+ waitForOpenIDRefreshFlight,+ withOpenIDRefreshFlightLease,+} = require('~/server/services/OpenIDRefreshFlight');+const { refreshOpenIDSession } = require('~/server/services/OpenIDSessionRefresh');+const { revokeOpenIDRefreshTokenChain } = require('~/server/services/OpenIDRefreshRecovery');const ORIGINAL_OPENID_SCOPE = process.env.OPENID_SCOPE;const ORIGINAL_OPENID_REFRESH_AUDIENCE = process.env.OPENID_REFRESH_AUDIENCE;const ORIGINAL_JWT_REFRESH_SECRET = process.env.JWT_REFRESH_SECRET;const ORIGINAL_NODE_ENV = process.env.NODE_ENV;+const { createOpenIDRefreshOwnershipError } = jest.requireActual('@librechat/api');+const ownershipLost = (message) => createOpenIDRefreshOwnershipError(message);++describe('OpenID logout refresh chain', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ createOpenIDRefreshFlightKey.mockImplementation(+ ({ refreshToken }) => `session:${refreshToken}`,+ );+ createRefreshTokenBridgeFlightKey.mockImplementation(+ ({ oldRefreshToken }) => `bridge:${oldRefreshToken}`,+ );+ });++ afterEach(() => {+ createRefreshTokenBridgeFlightKey.mockImplementation(() => 'bridge-flight-key');+ });++ it('tombstones every discovered successor generation before logout completes', async () => {+ createOpenIDRefreshFlightKey.mockImplementation(+ ({ refreshToken, identityContext }) =>+ `session:${identityContext.openidSubject}:${refreshToken}`,+ );+ createRefreshTokenBridgeFlightKey.mockImplementation(+ ({ oldRefreshToken, userId, openidIssuer }) =>+ `bridge:${userId}:${openidIssuer}:${oldRefreshToken}`,+ );+ const acceptedIdentity = {+ appUserId: 'user-2',+ openidSubject: 'subject-2',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer-2.example.com',+ };+ revokeOpenIDRefreshFlights+ .mockResolvedValueOnce([{ refresh_token: 'rt-successor-1', acceptedIdentity }, null])+ .mockResolvedValueOnce([{ tokenset: { refresh_token: 'rt-successor-2' } }, null, null, null])+ .mockResolvedValueOnce([null, null, null, null]);+ const req = { user: { _id: 'user-1', openidId: 'subject-1' } };+ const user = req.user;+ const identityContext = {+ appUserId: 'user-1',+ openidSubject: 'subject-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ };++ await expect(+ revokeOpenIDRefreshTokenChain({+ req,+ user,+ identityContext,+ refreshTokens: ['rt-predecessor'],+ publicationKeys: ['recorded-publication-key'],+ ttl: 60_000,+ }),+ ).resolves.toEqual(['rt-predecessor', 'rt-successor-1', 'rt-successor-2']);++ expect(revokeOpenIDRefreshFlights).toHaveBeenNthCalledWith(1, {+ keys: [+ 'recorded-publication-key',+ 'session:subject-1:rt-predecessor',+ 'bridge:user-1:https://issuer.example.com:rt-predecessor',+ ],+ ttl: 60_000,+ });+ expect(revokeOpenIDRefreshFlights).toHaveBeenNthCalledWith(2, {+ keys: [+ 'session:subject-1:rt-successor-1',+ 'bridge:user-1:https://issuer.example.com:rt-successor-1',+ 'session:subject-2:rt-successor-1',+ 'bridge:user-2:https://issuer-2.example.com:rt-successor-1',+ ],+ ttl: 60_000,+ });+ expect(revokeOpenIDRefreshFlights).toHaveBeenNthCalledWith(3, {+ keys: [+ 'session:subject-1:rt-successor-2',+ 'bridge:user-1:https://issuer.example.com:rt-successor-2',+ 'session:subject-2:rt-successor-2',+ 'bridge:user-2:https://issuer-2.example.com:rt-successor-2',+ ],+ ttl: 60_000,+ });+ });+});+describe('graphTokenController', () => {let req, res;beforeEach(() => {jest.clearAllMocks();isEnabled.mockReturnValue(true);+ assertOpenIDRefreshSessionGenerationAvailable.mockResolvedValue(true);+ claimOpenIDRefreshFlightDelivery.mockResolvedValue({+ status: 'completed',+ ownerId: 'publication-owner',+ deliveryId: 'delivery-1',+ });+ assertOpenIDRefreshFlightDeliveryAvailable.mockResolvedValue(undefined);+ releaseOpenIDRefreshFlightDelivery.mockResolvedValue(undefined);req = {user: {@@ -117,6 +289,99 @@ describe('graphTokenController', () => {});});+ it('leases the session generation across a Graph OBO exchange and response delivery', async () => {+ req.user.federatedTokens.access_token = 'session-access-token';+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ appUserId: 'user-1',+ tenantId: 'tenant-1',+ publicationFlightKey: 'publication-key',+ publicationFlightOwnerId: 'publication-owner',+ publicationFlightCreatedAt: 1000,+ },+ };++ await graphTokenController(req, res);++ expect(claimOpenIDRefreshFlightDelivery).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ createdAt: 1000,+ });+ expect(assertOpenIDRefreshFlightDeliveryAvailable).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ deliveryId: 'delivery-1',+ });+ expect(getGraphApiToken).toHaveBeenCalled();+ expect(res.json).toHaveBeenCalledWith(+ expect.objectContaining({ access_token: 'graph-access-token' }),+ );+ expect(releaseOpenIDRefreshFlightDelivery).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ deliveryId: 'delivery-1',+ });+ });++ it('does not exchange a session-backed Graph token after logout tombstones its generation', async () => {+ req.user.federatedTokens.access_token = 'session-access-token';+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ appUserId: 'user-1',+ tenantId: 'tenant-1',+ publicationFlightKey: 'publication-key',+ publicationFlightOwnerId: 'publication-owner',+ },+ };+ assertOpenIDRefreshSessionGenerationAvailable.mockRejectedValueOnce(+ ownershipLost('revoked by logout'),+ );++ await graphTokenController(req, res);++ expect(getGraphApiToken).not.toHaveBeenCalled();+ expect(clearOpenIDAuthTokens).toHaveBeenCalledWith(req, res, undefined, 'tenant-1');+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('does not fall back to a stale Graph token snapshot after the Express session is cleared', async () => {+ req.session = {};++ await graphTokenController(req, res);++ expect(getGraphApiToken).not.toHaveBeenCalled();+ expect(clearOpenIDAuthTokens).toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('withholds a minted Graph token when logout revokes its delivery lease', async () => {+ req.user.federatedTokens.access_token = 'session-access-token';+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ appUserId: 'user-1',+ tenantId: 'tenant-1',+ publicationFlightKey: 'publication-key',+ publicationFlightOwnerId: 'publication-owner',+ },+ };+ assertOpenIDRefreshFlightDeliveryAvailable.mockRejectedValueOnce(+ ownershipLost('logout requested revocation'),+ );++ await graphTokenController(req, res);++ expect(getGraphApiToken).toHaveBeenCalled();+ expect(res.json).not.toHaveBeenCalledWith(+ expect.objectContaining({ access_token: 'graph-access-token' }),+ );+ expect(releaseOpenIDRefreshFlightDelivery).toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });+it('should return 403 when user is not authenticated via Entra ID', async () => {req.user.provider = 'google';req.user.openidId = undefined;@@ -196,6 +461,8 @@ describe('refreshController – OpenID path', () => {_id: 'user-db-id',email: baseClaims.email,openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,password: '$2b$10$hashedpassword',__v: 0,totpSecret: 'encrypted-totp-secret',@@ -215,8 +482,19 @@ describe('refreshController – OpenID path', () => {idpSigningSecret,);- const makeSignedUserId = (id = 'user-db-id', options = { expiresIn: '1h' }) =>- jwt.sign({ id }, process.env.JWT_REFRESH_SECRET, options);+ const makeSignedUserId = (+ id = 'user-db-id',+ options = { expiresIn: '1h' },+ refreshToken = 'stored-refresh',+ ) =>+ jwt.sign(+ {+ id,+ refreshTokenHash: createHash('sha256').update(refreshToken).digest('base64url'),+ },+ process.env.JWT_REFRESH_SECRET,+ options,+ );const setOpenIDReuseCookies = (signedUserId = makeSignedUserId()) => {req.headers.cookie = [@@ -238,18 +516,83 @@ describe('refreshController – OpenID path', () => {mockTokenset.claims.mockReturnValue(baseClaims);getOpenIdEmail.mockReturnValue(baseClaims.email);setOpenIDAuthTokens.mockReturnValue('new-app-token');+ getOpenIDAppAuthToken.mockReturnValue('new-app-token');storeOpenIDSession.mockResolvedValue(true);setCloudFrontAuthCookies.mockReturnValue(true);findOpenIDUser.mockResolvedValue({ user: { ...defaultUser }, error: null, migration: false });+ getRefreshTokenBridge.mockResolvedValue(null);+ storeRefreshTokenBridge.mockResolvedValue('bridge-version-1');+ acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: true, ownerId: 'bridge-owner' });+ assertOpenIDRefreshFlightAvailable.mockResolvedValue({+ status: 'completed',+ ownerId: 'bridge-owner',+ });+ assertOpenIDRefreshFlightDeliveryAvailable.mockResolvedValue(undefined);+ assertOpenIDRefreshSessionGenerationAvailable.mockResolvedValue(true);+ claimOpenIDRefreshFlightDelivery.mockResolvedValue({+ status: 'completed',+ ownerId: 'publication-owner',+ deliveryId: 'delivery-1',+ });+ completeOpenIDRefreshFlight.mockResolvedValue({ status: 'completed' });+ failOpenIDRefreshFlight.mockResolvedValue({ status: 'failed' });+ releaseOpenIDRefreshFlightDelivery.mockResolvedValue(undefined);+ waitForOpenIDRefreshFlight.mockResolvedValue(null);+ withOpenIDRefreshFlightLease.mockImplementation(({ operation }) =>+ operation({+ assertLeaseOwned: jest.fn().mockResolvedValue(true),+ markLeaseSettled: jest.fn(),+ }),+ );+ refreshOpenIDSession.mockImplementation(+ async (refreshReq, _res, _user, _preference, _identity, options = {}) => {+ const activeRefreshToken = refreshReq.session.openidTokens.refreshToken;+ const refreshParams = buildOpenIDRefreshParams();+ logger.debug('[refreshController] OpenID refresh params', {+ has_scope: Boolean(process.env.OPENID_SCOPE),+ has_refresh_audience: Boolean(process.env.OPENID_REFRESH_AUDIENCE),+ });+ const tokenset = await openIdClient.refreshTokenGrant(+ getOpenIdConfig(),+ activeRefreshToken,+ refreshParams,+ );+ if (options.assertLeaseOwned) {+ await options.assertLeaseOwned();+ }+ logger.debug('[refreshController] OpenID refresh succeeded', {+ has_access_token: Boolean(tokenset.access_token),+ has_id_token: Boolean(tokenset.id_token),+ has_refresh_token: Boolean(tokenset.refresh_token),+ expires_in: tokenset.expires_in,+ });+ const resolvedTokenset = tokenset.refresh_token+ ? tokenset+ : { ...tokenset, refresh_token: activeRefreshToken };+ if (!options.deferPublication) {+ refreshReq.session.openidTokens = {+ ...refreshReq.session.openidTokens,+ accessToken: tokenset.access_token,+ idToken: tokenset.id_token,+ refreshToken: resolvedTokenset.refresh_token,+ };+ }+ return resolvedTokenset;+ },+ );getUserById.mockResolvedValue({_id: 'user-db-id',email: baseClaims.email,openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,});updateUser.mockResolvedValue({});req = {- headers: { cookie: 'token_provider=openid; refreshToken=stored-refresh' },+ headers: {+ cookie: `token_provider=openid; refreshToken=stored-refresh; openid_user_id=${makeSignedUserId()}`,+ },session: {},};@@ -290,16 +633,170 @@ describe('refreshController – OpenID path', () => {expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {userId: 'user-db-id',existingRefreshToken: 'stored-refresh',- tenantId: undefined,+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,});expect(storeOpenIDSession).toHaveBeenCalledWith('user-db-id','new-refresh',- undefined,+ 'tenant-1','stored-refresh',);};+ it('falls back to the browser token only after the advanced session token is rejected', async () => {+ req.headers.cookie = `token_provider=openid; refreshToken=rt-cookie-current; openid_user_id=${makeSignedUserId()}`;+ req.session = {+ openidTokens: {+ refreshToken: 'rt-session-stale',+ browserRefreshToken: 'rt-browser-stale',+ appUserId: 'user-db-id',+ },+ reload: jest.fn((callback) => {+ req.session.openidTokens = {+ accessToken: 'rejected-access',+ refreshToken: 'rt-session-stale',+ };+ callback();+ }),+ };+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);++ await refreshController(req, res);++ expect(openIdClient.refreshTokenGrant).toHaveBeenNthCalledWith(+ 1,+ { some: 'config' },+ 'rt-session-stale',+ {},+ );+ expect(req.session.reload).toHaveBeenCalled();+ expect(refreshOpenIDSession).toHaveBeenNthCalledWith(+ 1,+ req,+ res,+ expect.objectContaining({ _id: 'user-db-id' }),+ 'id_token',+ expect.objectContaining({ appUserId: 'user-db-id' }),+ { deferPublication: true, forceRefresh: true },+ );+ expect(refreshOpenIDSession).toHaveBeenNthCalledWith(+ 2,+ req,+ res,+ expect.objectContaining({ _id: 'user-db-id' }),+ 'id_token',+ expect.objectContaining({ appUserId: 'user-db-id' }),+ { deferPublication: true, forceRefresh: true },+ );+ expect(openIdClient.refreshTokenGrant).toHaveBeenNthCalledWith(+ 2,+ { some: 'config' },+ 'rt-cookie-current',+ {},+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {+ userId: 'user-db-id',+ existingRefreshToken: 'rt-cookie-current',+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,+ });+ });++ it('keeps the advanced session token when an older browser cookie arrives on drift', async () => {+ const reusableIdToken = makeSessionToken();+ req.headers.cookie = [+ 'token_provider=openid',+ 'refreshToken=rt-cookie-current',+ `openid_user_id=${makeSignedUserId()}`,+ ].join('; ');+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ idToken: reusableIdToken,+ refreshToken: 'rt-session-stale',+ browserRefreshToken: 'rt-browser-stale',+ lastRefreshedAt: Date.now(),+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,+ },+ };++ await refreshController(req, res);++ expect(getUserById).toHaveBeenCalled();+ expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledWith(+ { some: 'config' },+ 'rt-session-stale',+ {},+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {+ userId: 'user-db-id',+ existingRefreshToken: 'rt-session-stale',+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,+ });+ });++ it('prefers the session token when pre-marker session state differs', async () => {+ req.headers.cookie = `token_provider=openid; refreshToken=rt-cookie-current; openid_user_id=${makeSignedUserId()}`;+ req.session = {+ openidTokens: {+ refreshToken: 'rt-session-stale',+ appUserId: 'user-db-id',+ },+ };++ await refreshController(req, res);++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledWith(+ { some: 'config' },+ 'rt-session-stale',+ {},+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {+ userId: 'user-db-id',+ existingRefreshToken: 'rt-session-stale',+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,+ });+ });++ it('keeps the session refresh token when the browser cookie matches the session marker', async () => {+ req.headers.cookie = `token_provider=openid; refreshToken=rt-browser-stale; openid_user_id=${makeSignedUserId()}`;+ req.session = {+ openidTokens: {+ refreshToken: 'rt-session-current',+ browserRefreshToken: 'rt-browser-stale',+ appUserId: 'user-db-id',+ },+ };++ await refreshController(req, res);++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledWith(+ { some: 'config' },+ 'rt-session-current',+ {},+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {+ userId: 'user-db-id',+ existingRefreshToken: 'rt-session-current',+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,+ });+ });+it('should call getOpenIdEmail with token claims and use result for findOpenIDUser', async () => {await refreshController(req, res);@@ -314,6 +811,64 @@ describe('refreshController – OpenID path', () => {expect(res.status).toHaveBeenCalledWith(200);});+ it('stores a recovery bridge when durable rotation fails after the IdP grant', async () => {+ storeOpenIDSession.mockRejectedValueOnce(new Error('durable transition failed'));++ await refreshController(req, res);++ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'stored-refresh',+ newRefreshToken: 'new-refresh',+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,+ ttl: 60 * 1000,+ });+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('uses a reloaded advanced session instead of publishing a stale flight result', async () => {+ req.session.reload = jest.fn((callback) => {+ req.session.openidTokens = {+ accessToken: 'advanced-access',+ idToken: 'advanced-id',+ refreshToken: 'advanced-refresh',+ accessTokenExpiresAt: Math.floor(Date.now() / 1000) + 3600,+ appUserId: 'advanced-user-id',+ openidSubject: 'advanced-subject',+ tenantId: 'advanced-tenant',+ openidIssuer: 'https://advanced-issuer.example.com',+ };+ callback();+ });++ await refreshController(req, res);++ expect(storeOpenIDSession).toHaveBeenCalledWith(+ 'advanced-user-id',+ 'advanced-refresh',+ 'advanced-tenant',+ 'advanced-refresh',+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({+ access_token: 'advanced-access',+ id_token: 'advanced-id',+ refresh_token: 'advanced-refresh',+ }),+ req,+ res,+ {+ userId: 'advanced-user-id',+ existingRefreshToken: 'advanced-refresh',+ tenantId: 'advanced-tenant',+ openidSubject: 'advanced-subject',+ openidIssuer: 'https://advanced-issuer.example.com',+ },+ );+ });+it('reuses valid OpenID session tokens and refreshes CloudFront cookies', async () => {const reusableIdToken = makeSessionToken();const signedUserId = makeSignedUserId();@@ -324,6 +879,10 @@ describe('refreshController – OpenID path', () => {idToken: reusableIdToken,refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,},};const user = {@@ -336,6 +895,7 @@ describe('refreshController – OpenID path', () => {expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();expect(getUserById).toHaveBeenCalledWith('user-db-id','-password -__v -totpSecret -backupCodes -federatedTokens',@@ -369,84 +929,194 @@ describe('refreshController – OpenID path', () => {expect(debugOutput).not.toContain('session-access-token');});- it('falls through to full OpenID refresh when session tokens are expired', async () => {- const expiredToken = makeSessionToken({ exp: Math.floor(Date.now() / 1000) - 60 });+ it('rejects a late-saved session whose publication generation was tombstoned', async () => {setOpenIDReuseCookies();req.session = {openidTokens: {- accessToken: expiredToken,- idToken: expiredToken,+ accessToken: 'session-access-token',+ idToken: makeSessionToken(),refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,+ publicationFlightKey: 'publication-key',+ publicationFlightOwnerId: 'publication-owner',},};+ assertOpenIDRefreshSessionGenerationAvailable.mockRejectedValueOnce(+ ownershipLost('revoked by logout'),+ );await refreshController(req, res);+ expect(assertOpenIDRefreshSessionGenerationAvailable).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ });+ expect(clearOpenIDAuthTokens).toHaveBeenCalledWith(req, res, 'user-db-id', 'tenant-1');expect(getUserById).not.toHaveBeenCalled();expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();- expectOpenIDRefreshGrant();+ expect(res.status).toHaveBeenCalledWith(403);});- it('falls through to full OpenID refresh when session tokens are near expiry', async () => {- const nearExpiryToken = makeSessionToken({ exp: Math.floor(Date.now() / 1000) + 5 });+ it('withholds a reusable response when logout revokes its delivery lease', async () => {setOpenIDReuseCookies();req.session = {openidTokens: {- accessToken: nearExpiryToken,- idToken: nearExpiryToken,+ accessToken: 'session-access-token',+ idToken: makeSessionToken(),refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,+ publicationFlightKey: 'publication-key',+ publicationFlightOwnerId: 'publication-owner',+ publicationFlightCreatedAt: 1000,},};+ assertOpenIDRefreshFlightDeliveryAvailable.mockRejectedValueOnce(+ ownershipLost('logout won during user lookup'),+ );await refreshController(req, res);- expect(getUserById).not.toHaveBeenCalled();- expectOpenIDRefreshGrant();+ expect(claimOpenIDRefreshFlightDelivery).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ createdAt: 1000,+ });+ expect(assertOpenIDRefreshFlightDeliveryAvailable).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ deliveryId: 'delivery-1',+ });+ expect(releaseOpenIDRefreshFlightDelivery).toHaveBeenCalled();+ expect(clearOpenIDAuthTokens).toHaveBeenCalledWith(req, res, 'user-db-id', 'tenant-1');+ expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();+ expect(res.send).not.toHaveBeenCalledWith(+ expect.objectContaining({ token: expect.any(String) }),+ );+ expect(res.status).toHaveBeenCalledWith(403);});- it('falls through to full OpenID refresh when session tokens have no exp claim', async () => {- const tokenWithoutExp = jwt.sign({ sub: baseClaims.sub }, idpSigningSecret);+ it('falls through to full OpenID refresh when reusable session token identity mismatches', async () => {setOpenIDReuseCookies();req.session = {openidTokens: {- accessToken: tokenWithoutExp,- idToken: tokenWithoutExp,+ accessToken: 'session-access-token',+ idToken: makeSessionToken(),refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),+ appUserId: 'other-user-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,},};await refreshController(req, res);- expect(getUserById).not.toHaveBeenCalled();+ expect(getUserById).toHaveBeenCalledWith(+ 'user-db-id',+ '-password -__v -totpSecret -backupCodes -federatedTokens',+ );+ expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();expectOpenIDRefreshGrant();+ expect(logger.warn).toHaveBeenCalledWith(+ '[refreshController] OpenID session token identity mismatch; forcing refresh',+ expect.objectContaining({+ userId: 'user-db-id',+ }),+ );});- it('falls through to full OpenID refresh when the signed reuse user cookie is invalid', async () => {- setOpenIDReuseCookies('tampered-cookie');+ it('falls through to full OpenID refresh when session tokens are expired', async () => {+ const expiredToken = makeSessionToken({ exp: Math.floor(Date.now() / 1000) - 60 });+ setOpenIDReuseCookies();req.session = {openidTokens: {- accessToken: 'session-access-token',- idToken: makeSessionToken(),+ accessToken: expiredToken,+ idToken: expiredToken,refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,},};await refreshController(req, res);- expect(getUserById).not.toHaveBeenCalled();+ expect(getUserById).toHaveBeenCalled();+ expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();expectOpenIDRefreshGrant();});- it('falls through to full OpenID refresh when the reuse user no longer exists', async () => {+ it('falls through to full OpenID refresh when session tokens are near expiry', async () => {+ const nearExpiryToken = makeSessionToken({ exp: Math.floor(Date.now() / 1000) + 5 });setOpenIDReuseCookies();req.session = {openidTokens: {- accessToken: 'session-access-token',- idToken: makeSessionToken(),+ accessToken: nearExpiryToken,+ idToken: nearExpiryToken,+ refreshToken: 'stored-refresh',+ lastRefreshedAt: Date.now(),+ },+ };++ await refreshController(req, res);++ expect(getUserById).toHaveBeenCalled();+ expectOpenIDRefreshGrant();+ });++ it('falls through to full OpenID refresh when session tokens have no exp claim', async () => {+ const tokenWithoutExp = jwt.sign({ sub: baseClaims.sub }, idpSigningSecret);+ setOpenIDReuseCookies();+ req.session = {+ openidTokens: {+ accessToken: tokenWithoutExp,+ idToken: tokenWithoutExp,+ refreshToken: 'stored-refresh',+ lastRefreshedAt: Date.now(),+ },+ };++ await refreshController(req, res);++ expect(getUserById).toHaveBeenCalled();+ expectOpenIDRefreshGrant();+ });++ it('rejects refresh when neither the session nor signed marker identifies the user', async () => {+ setOpenIDReuseCookies('tampered-cookie');+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ idToken: makeSessionToken(),+ refreshToken: 'stored-refresh',+ lastRefreshedAt: Date.now(),+ },+ };++ await refreshController(req, res);++ expect(getUserById).not.toHaveBeenCalled();+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('falls through to full OpenID refresh when the reuse user no longer exists', async () => {+ setOpenIDReuseCookies();+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ idToken: makeSessionToken(),refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),},@@ -476,7 +1146,7 @@ describe('refreshController – OpenID path', () => {await refreshController(req, res);- expect(getUserById).not.toHaveBeenCalled();+ expect(getUserById).toHaveBeenCalled();expectOpenIDRefreshGrant();});@@ -493,7 +1163,7 @@ describe('refreshController – OpenID path', () => {await refreshController(req, res);- expect(getUserById).not.toHaveBeenCalled();+ expect(getUserById).toHaveBeenCalled();expectOpenIDRefreshGrant();});@@ -509,7 +1179,7 @@ describe('refreshController – OpenID path', () => {await refreshController(req, res);- expect(getUserById).not.toHaveBeenCalled();+ expect(getUserById).toHaveBeenCalled();expectOpenIDRefreshGrant();});@@ -522,6 +1192,10 @@ describe('refreshController – OpenID path', () => {idToken: reusableIdToken,refreshToken: 'stored-refresh',lastRefreshedAt: Date.now(),+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,},};const userDocument = {@@ -720,10 +1394,795 @@ describe('refreshController – OpenID path', () => {await refreshController(req, res);+ expect(getRefreshTokenBridge).toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.send).toHaveBeenCalledWith('Invalid OpenID refresh token');+ });++ it('does not use the bridge when signed user-id cookie payload is invalid', async () => {+ setOpenIDReuseCookies(jwt.sign({ id: 123 }, process.env.JWT_REFRESH_SECRET));+ openIdClient.refreshTokenGrant.mockRejectedValue(new Error('invalid_grant'));++ await refreshController(req, res);++ expect(getUserById).not.toHaveBeenCalled();+ expect(getRefreshTokenBridge).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('does not use the bridge when the signed marker belongs to another refresh token', async () => {+ setOpenIDReuseCookies(makeSignedUserId('user-db-id', { expiresIn: '1h' }, 'different-refresh'));+ openIdClient.refreshTokenGrant.mockRejectedValue(new Error('invalid_grant'));++ await refreshController(req, res);++ expect(getUserById).toHaveBeenCalled();+ expect(getRefreshTokenBridge).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('does not use the bridge when the signed marker lacks a refresh-token binding', async () => {+ setOpenIDReuseCookies(+ jwt.sign({ id: 'user-db-id' }, process.env.JWT_REFRESH_SECRET, { expiresIn: '1h' }),+ );+ openIdClient.refreshTokenGrant.mockRejectedValue(new Error('invalid_grant'));++ await refreshController(req, res);++ expect(getUserById).toHaveBeenCalled();+ expect(getRefreshTokenBridge).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ /** The recovery grant need not rotate. When it does not, the browser must still be moved onto+ * the bridged token rather than back onto the stale one the bridge exists to retire. */+ it('installs the bridged token when the recovery grant does not rotate', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ const nonRotatingTokenset = { ...mockTokenset };+ delete nonRotatingTokenset.refresh_token;+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(nonRotatingTokenset);++ await refreshController(req, res);++ expect(storeOpenIDSession).toHaveBeenCalledWith(+ 'user-db-id',+ 'bridged-refresh',+ 'tenant-1',+ 'stored-refresh',+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({ refresh_token: 'bridged-refresh' }),+ req,+ res,+ expect.any(Object),+ );+ expect(res.status).toHaveBeenCalledWith(200);+ });++ /** A recovery grant that omits `id_token` leaves the rebuilt token set with no identity+ * material of its own; the refresh carries the stripped token in a non-enumerable marker so+ * claims still resolve without that expired token re-entering the auth response. */+ it('resolves identity from the marker when the refresh stripped an expired id_token', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ let refreshCall = 0;+ refreshOpenIDSession.mockImplementation(async () => {+ refreshCall += 1;+ if (refreshCall === 1) {+ throw new Error('invalid_grant');+ }+ const stripped = {+ access_token: 'new-access',+ refresh_token: 'bridged-refresh',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ };+ Object.defineProperty(stripped, '__identityIdToken', {+ value: jwt.sign(baseClaims, 'idp-secret'),+ enumerable: false,+ configurable: true,+ });+ return stripped;+ });++ await refreshController(req, res);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({ refresh_token: 'bridged-refresh' }),+ req,+ res,+ expect.any(Object),+ );+ expect(setOpenIDAuthTokens.mock.calls.at(-1)[0].id_token).toBeUndefined();+ });++ it('recovers stale refresh-token cookies and keeps a short grace bridge', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ const bridgeUser = {+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ };+ getUserById.mockResolvedValue(bridgeUser);+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);++ await refreshController(req, res);++ expect(getUserById).toHaveBeenCalledWith(+ 'user-db-id',+ '-password -__v -totpSecret -backupCodes -federatedTokens',+ );+ expect(getRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'stored-refresh',+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ expect(openIdClient.refreshTokenGrant).toHaveBeenNthCalledWith(+ 1,+ { some: 'config' },+ 'stored-refresh',+ {},+ );+ expect(openIdClient.refreshTokenGrant).toHaveBeenNthCalledWith(+ 2,+ { some: 'config' },+ 'bridged-refresh',+ {},+ );+ expect(findOpenIDUser).toHaveBeenCalledWith(+ expect.objectContaining({+ strategyName: 'refreshController (bridge recovery)',+ }),+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledTimes(1);+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {+ userId: 'user-db-id',+ existingRefreshToken: 'stored-refresh',+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,+ });+ expect(completeOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'bridge-flight-key',+ ownerId: 'bridge-owner',+ tokens: expect.objectContaining({+ appAuthToken: 'new-app-token',+ claims: baseClaims,+ tokenset: mockTokenset,+ }),+ });+ expect(completeOpenIDRefreshFlight.mock.invocationCallOrder[0]).toBeLessThan(+ setOpenIDAuthTokens.mock.invocationCallOrder[0],+ );+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'stored-refresh',+ newRefreshToken: 'new-refresh',+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ ttl: 60000,+ });+ /** Recovery issues a fresh credential like any other refresh, so the durable session has to+ * follow it — otherwise the record still names the token the bridge just replaced. */+ expect(storeOpenIDSession).toHaveBeenCalledWith(+ 'user-db-id',+ 'new-refresh',+ 'tenant-1',+ 'stored-refresh',+ );+ const lookupIdentity = getRefreshTokenBridge.mock.calls[0][0];+ const graceIdentity = storeRefreshTokenBridge.mock.calls[0][0];+ expect(graceIdentity).toEqual(+ expect.objectContaining({+ oldRefreshToken: lookupIdentity.oldRefreshToken,+ userId: lookupIdentity.userId,+ tenantId: lookupIdentity.tenantId,+ openidIssuer: lookupIdentity.openidIssuer,+ }),+ );+ expect(res.status).toHaveBeenCalledWith(200);+ });++ it('joins an existing stale-cookie recovery without rotating the bridged token again', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ const bridgeUser = {+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ };+ getUserById.mockResolvedValue(bridgeUser);+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant.mockRejectedValueOnce(new Error('invalid_grant'));+ acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: false, ownerId: 'other-owner' });+ waitForOpenIDRefreshFlight.mockResolvedValue({+ appAuthToken: 'shared-app-token',+ __flightOwnerId: 'shared-owner',+ tokenset: { ...mockTokenset },+ claims: baseClaims,+ openidIssuer: baseClaims.iss,+ });+ getOpenIDAppAuthToken.mockReturnValueOnce('shared-app-token');+ setOpenIDAuthTokens.mockReturnValueOnce('shared-app-token');++ await refreshController(req, res);++ expect(createRefreshTokenBridgeFlightKey).toHaveBeenCalledWith({+ oldRefreshToken: 'stored-refresh',+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ expect(withOpenIDRefreshFlightLease).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({ refresh_token: 'new-refresh' }),+ req,+ res,+ expect.objectContaining({+ userId: 'user-db-id',+ existingRefreshToken: 'stored-refresh',+ }),+ );+ expect(storeOpenIDSession).not.toHaveBeenCalled();+ expect(res.send).toHaveBeenCalledWith(expect.objectContaining({ token: 'shared-app-token' }));+ expect(res.status).toHaveBeenCalledWith(200);+ });++ it('publishes an ordinary completed result to a cross-replica follower', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ ...defaultUser,+ openidIssuer: 'https://predecessor.example.com',+ });+ acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: false, ownerId: 'other-owner' });+ waitForOpenIDRefreshFlight.mockResolvedValue({+ appAuthToken: 'shared-app-token',+ __flightOwnerId: 'shared-owner',+ tokenset: { ...mockTokenset },+ claims: baseClaims,+ openidIssuer: baseClaims.iss,+ });+ getOpenIDAppAuthToken.mockReturnValueOnce('shared-app-token');+ setOpenIDAuthTokens.mockReturnValueOnce('shared-app-token');++ await refreshController(req, res);++ expect(createRefreshTokenBridgeFlightKey).toHaveBeenCalledWith({+ oldRefreshToken: 'stored-refresh',+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://predecessor.example.com',+ });+ expect(storeOpenIDSession).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({ refresh_token: 'new-refresh' }),+ req,+ res,+ expect.objectContaining({+ userId: 'user-db-id',+ existingRefreshToken: 'stored-refresh',+ openidIssuer: baseClaims.iss,+ }),+ );+ expect(res.send).toHaveBeenCalledWith(expect.objectContaining({ token: 'shared-app-token' }));+ expect(res.status).toHaveBeenCalledWith(200);+ });++ it('claims the completed generation before delivering a newly refreshed app token', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ setOpenIDAuthTokens.mockImplementationOnce(() => {+ req.session.openidTokens = {+ accessToken: 'new-access',+ refreshToken: 'new-refresh',+ appUserId: 'user-db-id',+ tenantId: 'tenant-1',+ };+ return 'new-app-token';+ });++ await refreshController(req, res);++ expect(claimOpenIDRefreshFlightDelivery).toHaveBeenCalledWith({+ key: 'bridge-flight-key',+ ownerId: 'bridge-owner',+ createdAt: expect.any(Number),+ });+ expect(assertOpenIDRefreshFlightDeliveryAvailable).toHaveBeenCalledWith({+ key: 'bridge-flight-key',+ ownerId: 'bridge-owner',+ deliveryId: 'delivery-1',+ });+ expect(res.send).toHaveBeenCalledWith(expect.objectContaining({ token: 'new-app-token' }));+ expect(releaseOpenIDRefreshFlightDelivery).toHaveBeenCalled();+ });++ it('does not deliver a newly refreshed app token after logout requests revocation', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ setOpenIDAuthTokens.mockImplementationOnce(() => {+ req.session.openidTokens = {+ accessToken: 'new-access',+ refreshToken: 'new-refresh',+ appUserId: 'user-db-id',+ tenantId: 'tenant-1',+ };+ return 'new-app-token';+ });+ assertOpenIDRefreshFlightDeliveryAvailable.mockRejectedValueOnce(+ ownershipLost('logout requested revocation'),+ );++ await refreshController(req, res);++ expect(releaseOpenIDRefreshFlightDelivery).toHaveBeenCalled();+ expect(clearOpenIDAuthTokens).toHaveBeenCalled();+ expect(res.send).not.toHaveBeenCalledWith(expect.objectContaining({ token: 'new-app-token' }));+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('clears a follower publication when logout revokes its generation after emission', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue(defaultUser);+ acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: false, ownerId: 'other-owner' });+ waitForOpenIDRefreshFlight.mockResolvedValue({+ appAuthToken: 'shared-app-token',+ __flightOwnerId: 'shared-owner',+ tokenset: { ...mockTokenset },+ claims: baseClaims,+ openidIssuer: baseClaims.iss,+ });+ getOpenIDAppAuthToken.mockReturnValueOnce('shared-app-token');+ setOpenIDAuthTokens.mockImplementationOnce(() => {+ req.session.openidTokens = {+ accessToken: 'new-access',+ refreshToken: 'new-refresh',+ };+ return 'shared-app-token';+ });+ assertOpenIDRefreshFlightAvailable+ .mockResolvedValueOnce({ status: 'completed', ownerId: 'shared-owner' })+ .mockResolvedValueOnce({ status: 'completed', ownerId: 'shared-owner' })+ .mockResolvedValueOnce({ status: 'completed', ownerId: 'shared-owner' })+ .mockRejectedValueOnce(ownershipLost('revoked after emission'));++ await refreshController(req, res);++ expect(setOpenIDAuthTokens).toHaveBeenCalled();+ expect(req.session.openidTokens).toEqual(+ expect.objectContaining({+ publicationFlightKey: 'bridge-flight-key',+ publicationFlightOwnerId: 'shared-owner',+ }),+ );+ expect(clearOpenIDAuthTokens).toHaveBeenCalledWith(req, res, 'user-db-id', 'tenant-1');+ expect(deleteSession).toHaveBeenCalledWith({ refreshToken: 'new-refresh' });+ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.send).not.toHaveBeenCalledWith(+ expect.objectContaining({ token: 'shared-app-token' }),+ );+ });++ it('returns a newer stable-refresh session instead of a stale publication result', async () => {+ setOpenIDReuseCookies();+ req.session = {+ reload: jest.fn((callback) => {+ req.session.openidTokens = {+ accessToken: 'advanced-access',+ idToken: 'advanced-id',+ refreshToken: 'stored-refresh',+ accessTokenExpiresAt: Math.floor(Date.now() / 1000) + 7200,+ appUserId: 'user-db-id',+ openidSubject: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: baseClaims.iss,+ publicationFlightKey: 'advanced-publication-key',+ publicationFlightOwnerId: 'advanced-publication-owner',+ };+ callback();+ }),+ };+ getUserById.mockResolvedValue(defaultUser);+ acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: false, ownerId: 'other-owner' });+ waitForOpenIDRefreshFlight.mockResolvedValue({+ appAuthToken: 'stale-app-token',+ __flightOwnerId: 'shared-owner',+ tokenset: {+ access_token: 'stale-access',+ id_token: 'stale-id',+ refresh_token: 'stored-refresh',+ expires_in: 3600,+ },+ claims: baseClaims,+ openidIssuer: baseClaims.iss,+ predecessorAccessToken: 'predecessor-access',+ });+ getOpenIDAppAuthToken.mockReturnValueOnce('advanced-app-token');+ setOpenIDAuthTokens.mockReturnValueOnce('advanced-app-token');++ await refreshController(req, res);++ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({+ access_token: 'advanced-access',+ refresh_token: 'stored-refresh',+ }),+ req,+ res,+ expect.any(Object),+ );+ expect(res.send).toHaveBeenCalledWith(expect.objectContaining({ token: 'advanced-app-token' }));+ expect(req.session.openidTokens).toEqual(+ expect.objectContaining({+ publicationFlightKey: 'advanced-publication-key',+ publicationFlightOwnerId: 'advanced-publication-owner',+ }),+ );+ });++ it('recovers with serialized identity claims when the refreshed ID token is omitted', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ refreshOpenIDSession+ .mockRejectedValueOnce(Object.assign(new Error('invalid_grant'), { error: 'invalid_grant' }))+ .mockResolvedValueOnce({+ access_token: 'new-access',+ refresh_token: 'new-refresh',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ __identityClaims: baseClaims,+ });++ await refreshController(req, res);++ expect(findOpenIDUser).toHaveBeenCalledWith(+ expect.objectContaining({+ email: baseClaims.email,+ openidId: baseClaims.sub,+ strategyName: 'refreshController (bridge recovery)',+ }),+ );+ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(+ expect.objectContaining({+ access_token: 'new-access',+ __identityClaims: baseClaims,+ }),+ req,+ res,+ expect.objectContaining({ openidSubject: baseClaims.sub }),+ );+ expect(setOpenIDAuthTokens.mock.calls[0][0]).not.toHaveProperty('id_token');+ expect(res.status).toHaveBeenCalledWith(200);+ });++ it('rejects bridge recovery when retry resolves a different user than the signed cookie', async () => {+ setOpenIDReuseCookies(makeSignedUserId('cookie-user-id'));+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'cookie-user-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ findOpenIDUser.mockResolvedValueOnce({+ user: { ...defaultUser, _id: 'different-user-id' },+ error: null,+ migration: false,+ });+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);++ await refreshController(req, res);++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(2);+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ expect(logger.warn).toHaveBeenCalledWith(+ '[refreshController] Bridge recovery resolved a different user; refusing token issuance',+ {+ cookieUserId: 'cookie-user-id',+ resolvedUserId: 'different-user-id',+ },+ );expect(res.status).toHaveBeenCalledWith(403);expect(res.send).toHaveBeenCalledWith('Invalid OpenID refresh token');});+ it('does not re-store the bridge when bridged refresh retry fails', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockRejectedValueOnce(new Error('temporarily unavailable'));++ await refreshController(req, res);++ expect(getRefreshTokenBridge).toHaveBeenCalled();+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('returns success when bridge grace-period storage fails after bridged refresh succeeds', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ storeRefreshTokenBridge.mockRejectedValueOnce(new Error('grace failed'));+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);++ await refreshController(req, res);++ expect(setOpenIDAuthTokens).toHaveBeenCalledWith(mockTokenset, req, res, {+ userId: 'user-db-id',+ existingRefreshToken: 'stored-refresh',+ tenantId: 'tenant-1',+ openidSubject: baseClaims.sub,+ openidIssuer: baseClaims.iss,+ });+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'stored-refresh',+ newRefreshToken: 'new-refresh',+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ ttl: 60000,+ });+ expect(logger.warn).toHaveBeenCalledWith(+ '[refreshController] Bridge grace-period storage failed after successful recovery',+ expect.any(Error),+ );+ expect(res.status).toHaveBeenCalledWith(200);+ });++ it('removes a grace bridge published concurrently with logout revocation', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(ownershipLost('revoked by logout'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );++ await refreshController(req, res);++ expect(deleteRefreshTokenBridges).toHaveBeenCalledWith({+ refreshTokens: ['stored-refresh'],+ userId: 'user-db-id',+ tenantId: 'tenant-1',+ version: 'bridge-version-1',+ });+ expect(completeOpenIDRefreshFlight).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('keeps the grace bridge when the ownership check fails for an undetermined reason', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(new Error('connection timed out'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );++ await refreshController(req, res);++ expect(deleteRefreshTokenBridges).not.toHaveBeenCalled();+ expect(completeOpenIDRefreshFlight).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('removes a prepared durable session when logout wins before publication commits', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(ownershipLost('revoked by logout'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );++ await refreshController(req, res);++ expect(storeOpenIDSession).toHaveBeenCalledWith(+ 'user-db-id',+ 'new-refresh',+ 'tenant-1',+ 'stored-refresh',+ );+ expect(deleteSession).toHaveBeenCalledWith({ refreshToken: 'new-refresh' });+ expect(clearOpenIDAuthTokens).toHaveBeenCalledWith(req, res, 'user-db-id', 'tenant-1');+ expect(completeOpenIDRefreshFlight).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('cleans the prepared successor before emission when logout wins the final commit', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);+ completeOpenIDRefreshFlight.mockResolvedValueOnce(null);++ await refreshController(req, res);++ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(deleteSession).toHaveBeenCalledWith({ refreshToken: 'new-refresh' });+ expect(clearOpenIDAuthTokens).toHaveBeenCalledWith(req, res, 'user-db-id', 'tenant-1');+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('preserves the successor and bridge when publication completion is indeterminate', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);+ completeOpenIDRefreshFlight.mockRejectedValueOnce(new Error('mongo timeout'));+ assertOpenIDRefreshFlightAvailable.mockRejectedValueOnce(new Error('mongo read timeout'));++ await refreshController(req, res);++ expect(storeOpenIDSession).toHaveBeenCalledWith(+ 'user-db-id',+ 'new-refresh',+ 'tenant-1',+ 'stored-refresh',+ );+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ oldRefreshToken: 'stored-refresh',+ newRefreshToken: 'new-refresh',+ ttl: 60000,+ }),+ );+ expect(deleteSession).not.toHaveBeenCalledWith({ refreshToken: 'new-refresh' });+ expect(clearOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(failOpenIDRefreshFlight).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('does not publish a nested bridge refresh after the outer logout fence is revoked', async () => {+ setOpenIDReuseCookies();+ req.session = {};+ getUserById.mockResolvedValue({+ _id: 'user-db-id',+ email: baseClaims.email,+ openidId: baseClaims.sub,+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ getRefreshTokenBridge.mockResolvedValue('bridged-refresh');+ openIdClient.refreshTokenGrant+ .mockRejectedValueOnce(new Error('invalid_grant'))+ .mockResolvedValueOnce(mockTokenset);+ const assertLeaseOwned = jest.fn().mockRejectedValueOnce(ownershipLost('revoked by logout'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );++ await refreshController(req, res);++ expect(refreshOpenIDSession).toHaveBeenCalledWith(+ expect.anything(),+ res,+ expect.objectContaining({ _id: 'user-db-id' }),+ 'id_token',+ expect.anything(),+ expect.objectContaining({+ assertLeaseOwned,+ deferPublication: true,+ forceRefresh: true,+ }),+ );+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ expect(completeOpenIDRefreshFlight).not.toHaveBeenCalled();+ expect(setOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(req.session.openidTokens?.accessToken).toBeUndefined();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('does not use the bridge for generic HTTP 400 errors without invalid_grant', async () => {+ setOpenIDReuseCookies();+ openIdClient.refreshTokenGrant.mockRejectedValue(+ Object.assign(new Error('bad request'), { status: 400 }),+ );++ await refreshController(req, res);++ expect(getRefreshTokenBridge).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });+it('should skip OpenID path when token_provider is not openid', async () => {req.headers.cookie = 'token_provider=local; refreshToken=some-token';diff --git a/api/server/controllers/assistants/v1.js b/api/server/controllers/assistants/v1.jsindex 7116edda75..2f53c07632 100644--- a/api/server/controllers/assistants/v1.js+++ b/api/server/controllers/assistants/v1.js@@ -44,6 +44,7 @@ const createAssistant = async (req, res) => {const { toolDefinitions, accessibleServerNames } = await getAssistantToolDefinitions({req,+ res,tools,});const healedTools = await healMcpToolNames({@@ -172,6 +173,7 @@ const patchAssistant = async (req, res) => {const { toolDefinitions, accessibleServerNames } = await getAssistantToolDefinitions({req,+ res,tools: updateData.tools,});const healedTools = await healMcpToolNames({diff --git a/api/server/controllers/assistants/v2.js b/api/server/controllers/assistants/v2.jsindex afaf04f5d0..e6e9a5d0ef 100644--- a/api/server/controllers/assistants/v2.js+++ b/api/server/controllers/assistants/v2.js@@ -34,6 +34,7 @@ const createAssistant = async (req, res) => {const { toolDefinitions, accessibleServerNames } = await getAssistantToolDefinitions({req,+ res,tools,});const healedTools = await healMcpToolNames({@@ -153,6 +154,7 @@ const updateAssistant = async ({ req, openai, assistant_id, updateData }) => {let hasFileSearch = false;const { toolDefinitions, accessibleServerNames } = await getAssistantToolDefinitions({req,+ res: req.res,tools: updateData.tools,});const healedTools = await healMcpToolNames({diff --git a/api/server/controllers/auth/LogoutController.js b/api/server/controllers/auth/LogoutController.jsindex 95e6c8965c..cdf5404569 100644--- a/api/server/controllers/auth/LogoutController.js+++ b/api/server/controllers/auth/LogoutController.js@@ -1,7 +1,9 @@const cookies = require('cookie');-const { isEnabled, clearCloudFrontCookies } = require('@librechat/api');-const { logger } = require('@librechat/data-schemas');+const { isEnabled, math, clearCloudFrontCookies } = require('@librechat/api');+const { logger, DEFAULT_REFRESH_TOKEN_EXPIRY } = require('@librechat/data-schemas');const { logoutUser } = require('~/server/services/AuthService');+const { deleteAllRefreshTokenBridges } = require('~/server/services/RefreshTokenBridge');+const { revokeOpenIDRefreshTokenChain } = require('~/server/services/OpenIDRefreshRecovery');const { getOpenIdConfig } = require('~/strategies');/** Parses and validates OPENID_MAX_LOGOUT_URL_LENGTH, returning defaultValue on invalid input */@@ -27,16 +29,54 @@ const logoutController = async (req, res) => {let refreshToken;let idToken;+ let sessionRefreshToken;if (isOpenIdUser && req.session?.openidTokens) {- refreshToken = req.session.openidTokens.refreshToken;+ sessionRefreshToken = req.session.openidTokens.refreshToken;idToken = req.session.openidTokens.idToken;- delete req.session.openidTokens;}- refreshToken = refreshToken || parsedCookies.refreshToken;+ /** Both can name distinct durable sessions when an older browser request races rotation. */+ refreshToken = parsedCookies.refreshToken || sessionRefreshToken;idToken = idToken || parsedCookies.openid_id_token;+ const logoutTokens = isOpenIdUser+ ? [...new Set([parsedCookies.refreshToken, sessionRefreshToken].filter(Boolean))]+ : [refreshToken];try {- const logout = await logoutUser(req, refreshToken);+ if (isOpenIdUser) {+ const userId = req.user?.id ?? req.user?._id?.toString?.();+ const refreshIdentity = {+ appUserId: userId,+ openidSubject: req.session?.openidTokens?.openidSubject ?? req.user?.openidId,+ tenantId: req.session?.openidTokens?.tenantId ?? req.user?.tenantId,+ openidIssuer: req.session?.openidTokens?.openidIssuer ?? req.user?.openidIssuer,+ };+ const revokedRefreshTokens = await revokeOpenIDRefreshTokenChain({+ req,+ user: req.user,+ identityContext: refreshIdentity,+ refreshTokens: [...logoutTokens],+ publicationKeys: [req.session?.openidTokens?.publicationFlightKey].filter(Boolean),+ ttl: math(process.env.REFRESH_TOKEN_EXPIRY, DEFAULT_REFRESH_TOKEN_EXPIRY),+ });+ logoutTokens.push(...revokedRefreshTokens);+ await deleteAllRefreshTokenBridges({+ userId,+ tenantId: req.user?.tenantId,+ });+ if (req.session?.openidTokens) {+ delete req.session.openidTokens;+ }+ }+ if (logoutTokens.length === 0) {+ logoutTokens.push(undefined);+ }+ let logout = { status: 200, message: 'Logout successful' };+ for (const token of new Set(logoutTokens)) {+ const result = await logoutUser(req, token);+ if (result.status !== 200) {+ logout = result;+ }+ }const { status, message } = logout;res.clearCookie('refreshToken');diff --git a/api/server/controllers/auth/LogoutController.spec.js b/api/server/controllers/auth/LogoutController.spec.jsindex e6c3149217..06a051a66a 100644--- a/api/server/controllers/auth/LogoutController.spec.js+++ b/api/server/controllers/auth/LogoutController.spec.js@@ -5,16 +5,28 @@ const mockLogger = { warn: jest.fn(), error: jest.fn(), debug: jest.fn() };const mockIsEnabled = jest.fn();const mockGetOpenIdConfig = jest.fn();const mockClearCloudFrontCookies = jest.fn();+const mockDeleteAllRefreshTokenBridges = jest.fn();+const mockRevokeOpenIDRefreshTokenChain = jest.fn();jest.mock('cookie');jest.mock('@librechat/api', () => ({isEnabled: (...args) => mockIsEnabled(...args),+ math: (_value, fallback) => fallback,clearCloudFrontCookies: (...args) => mockClearCloudFrontCookies(...args),}));-jest.mock('@librechat/data-schemas', () => ({ logger: mockLogger }));+jest.mock('@librechat/data-schemas', () => ({+ logger: mockLogger,+ DEFAULT_REFRESH_TOKEN_EXPIRY: 7 * 24 * 60 * 60 * 1000,+}));jest.mock('~/server/services/AuthService', () => ({logoutUser: (...args) => mockLogoutUser(...args),}));+jest.mock('~/server/services/RefreshTokenBridge', () => ({+ deleteAllRefreshTokenBridges: (...args) => mockDeleteAllRefreshTokenBridges(...args),+}));+jest.mock('~/server/services/OpenIDRefreshRecovery', () => ({+ revokeOpenIDRefreshTokenChain: (...args) => mockRevokeOpenIDRefreshTokenChain(...args),+}));jest.mock('~/strategies', () => ({ getOpenIdConfig: () => mockGetOpenIdConfig() }));const { logoutController } = require('./LogoutController');@@ -24,7 +36,11 @@ function buildReq(overrides = {}) {user: { _id: 'user1', openidId: 'oid1', provider: 'openid' },headers: { cookie: 'refreshToken=rt1' },session: {- openidTokens: { refreshToken: 'srt', idToken: 'small-id-token' },+ openidTokens: {+ refreshToken: 'srt',+ idToken: 'small-id-token',+ publicationFlightKey: 'recorded-publication-key',+ },destroy: jest.fn(),},...overrides,@@ -54,6 +70,8 @@ beforeEach(() => {};cookies.parse.mockReturnValue({ refreshToken: 'cookie-rt' });mockLogoutUser.mockResolvedValue({ status: 200, message: 'Logout successful' });+ mockDeleteAllRefreshTokenBridges.mockResolvedValue({ acknowledged: true, deletedCount: 1 });+ mockRevokeOpenIDRefreshTokenChain.mockResolvedValue(['cookie-rt', 'srt']);mockIsEnabled.mockReturnValue(true);mockGetOpenIdConfig.mockReturnValue({serverMetadata: () => ({@@ -246,6 +264,91 @@ describe('LogoutController', () => {});});+ describe('bridge revocation', () => {+ it('revokes all predecessor bridges and deletes the browser durable session', async () => {+ const req = buildReq({+ user: {+ _id: 'user1',+ openidId: 'oid1',+ provider: 'openid',+ tenantId: 'tenantA',+ },+ });+ const res = buildRes();++ await logoutController(req, res);++ expect(mockDeleteAllRefreshTokenBridges).toHaveBeenCalledWith({+ userId: 'user1',+ tenantId: 'tenantA',+ });+ expect(mockRevokeOpenIDRefreshTokenChain).toHaveBeenCalledWith({+ req,+ user: req.user,+ identityContext: {+ appUserId: 'user1',+ openidSubject: 'oid1',+ tenantId: 'tenantA',+ openidIssuer: undefined,+ },+ refreshTokens: ['cookie-rt', 'srt'],+ publicationKeys: ['recorded-publication-key'],+ ttl: 7 * 24 * 60 * 60 * 1000,+ });+ expect(mockRevokeOpenIDRefreshTokenChain.mock.invocationCallOrder[0]).toBeLessThan(+ mockDeleteAllRefreshTokenBridges.mock.invocationCallOrder[0],+ );+ expect(mockLogoutUser).toHaveBeenCalledWith(req, 'cookie-rt');+ expect(mockLogoutUser).toHaveBeenCalledWith(req, 'srt');+ expect(mockLogoutUser).toHaveBeenCalledTimes(2);+ expect(req.session.openidTokens).toBeUndefined();+ });++ it('deletes successors retained by completed flights before a late refresh response arrives', async () => {+ mockRevokeOpenIDRefreshTokenChain.mockResolvedValue([+ 'cookie-rt',+ 'srt',+ 'grant-successor',+ 'publication-successor',+ ]);+ const req = buildReq();+ const res = buildRes();++ await logoutController(req, res);++ expect(mockLogoutUser).toHaveBeenCalledWith(req, 'cookie-rt');+ expect(mockLogoutUser).toHaveBeenCalledWith(req, 'srt');+ expect(mockLogoutUser).toHaveBeenCalledWith(req, 'grant-successor');+ expect(mockLogoutUser).toHaveBeenCalledWith(req, 'publication-successor');+ expect(mockLogoutUser).toHaveBeenCalledTimes(4);+ });++ it('fails closed before logout when bridge revocation fails', async () => {+ mockDeleteAllRefreshTokenBridges.mockRejectedValue(new Error('bridge delete failed'));+ const req = buildReq();+ const res = buildRes();++ await logoutController(req, res);++ expect(mockLogoutUser).not.toHaveBeenCalled();+ expect(req.session.openidTokens).toBeDefined();+ expect(res.status).toHaveBeenCalledWith(500);+ });++ it('fails closed before deleting auth state when the refresh-flight fence fails', async () => {+ mockRevokeOpenIDRefreshTokenChain.mockRejectedValue(new Error('flight fence failed'));+ const req = buildReq();+ const res = buildRes();++ await logoutController(req, res);++ expect(mockDeleteAllRefreshTokenBridges).not.toHaveBeenCalled();+ expect(mockLogoutUser).not.toHaveBeenCalled();+ expect(req.session.openidTokens).toBeDefined();+ expect(res.status).toHaveBeenCalledWith(500);+ });+ });+describe('cookie clearing', () => {it('clears all auth cookies on successful logout', async () => {const req = buildReq();diff --git a/api/server/controllers/auth/oauth.js b/api/server/controllers/auth/oauth.jsindex 368f8729f5..bdfcd102bc 100644--- a/api/server/controllers/auth/oauth.js+++ b/api/server/controllers/auth/oauth.js@@ -7,11 +7,8 @@ const {generateAdminExchangeCode,} = require('@librechat/api');const { syncUserEntraGroupMemberships } = require('~/server/services/PermissionService');-const {- setAuthTokens,- setOpenIDAuthTokens,- storeOpenIDSession,-} = require('~/server/services/AuthService');+const { setAuthTokens } = require('~/server/services/AuthService');+const { sendOpenIDAuthResponse } = require('~/server/services/OpenIDRefreshRecovery');const getLogStores = require('~/cache/getLogStores');const { checkBan } = require('~/server/middleware');const { generateToken } = require('~/models');@@ -80,14 +77,14 @@ function createOAuthHandler(redirectUri = domains.client) {isEnabled(process.env.OPENID_REUSE_TOKENS) === true) {await syncUserEntraGroupMemberships(req.user, req.user.tokenset.access_token);- await storeOpenIDSession(- req.user._id.toString(),- req.user.tokenset.refresh_token,- req.user.tenantId,- );- setOpenIDAuthTokens(req.user.tokenset, req, res, {- userId: req.user._id.toString(),- tenantId: req.user.tenantId,+ await sendOpenIDAuthResponse({+ tokenset: req.user.tokenset,+ user: req.user,+ existingRefreshToken: req.user.tokenset.refresh_token,+ openidSubject: req.user.openidId,+ openidIssuer: req.user.openidIssuer,+ req,+ res,});} else {await setAuthTokens(req.user._id, res, null, req);diff --git a/api/server/controllers/auth/oauth.spec.js b/api/server/controllers/auth/oauth.spec.jsindex 62290210e2..c0b6f09e76 100644--- a/api/server/controllers/auth/oauth.spec.js+++ b/api/server/controllers/auth/oauth.spec.js@@ -4,8 +4,7 @@ const mockIsAdminPanelRedirect = jest.fn();const mockGenerateAdminExchangeCode = jest.fn();const mockSyncUserEntraGroupMemberships = jest.fn();const mockSetAuthTokens = jest.fn();-const mockSetOpenIDAuthTokens = jest.fn();-const mockStoreOpenIDSession = jest.fn();+const mockSendOpenIDAuthResponse = jest.fn();const mockGetLogStores = jest.fn();const mockCheckBan = jest.fn();const mockGenerateToken = jest.fn();@@ -33,8 +32,10 @@ jest.mock('~/server/services/PermissionService', () => ({jest.mock('~/server/services/AuthService', () => ({setAuthTokens: (...args) => mockSetAuthTokens(...args),- setOpenIDAuthTokens: (...args) => mockSetOpenIDAuthTokens(...args),- storeOpenIDSession: (...args) => mockStoreOpenIDSession(...args),+}));++jest.mock('~/server/services/OpenIDRefreshRecovery', () => ({+ sendOpenIDAuthResponse: (...args) => mockSendOpenIDAuthResponse(...args),}));jest.mock(@@ -94,7 +95,7 @@ describe('createOAuthHandler', () => {mockCheckBan.mockResolvedValue(undefined);mockGenerateToken.mockResolvedValue('jwt-token');mockGenerateAdminExchangeCode.mockResolvedValue('exchange-code');- mockStoreOpenIDSession.mockResolvedValue(true);+ mockSendOpenIDAuthResponse.mockResolvedValue('app-token');});afterAll(() => {@@ -121,7 +122,7 @@ describe('createOAuthHandler', () => {expect(res.redirect).toHaveBeenCalledWith('http://admin.example.com/auth/openid/callback?code=exchange-code',);- expect(mockSetOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(mockSendOpenIDAuthResponse).not.toHaveBeenCalled();expect(mockSetAuthTokens).not.toHaveBeenCalled();expect(next).not.toHaveBeenCalled();});@@ -147,12 +148,12 @@ describe('createOAuthHandler', () => {expect(res.redirect).toHaveBeenCalledWith('http://admin.example.com/auth/openid/callback?code=exchange-code',);- expect(mockSetOpenIDAuthTokens).not.toHaveBeenCalled();+ expect(mockSendOpenIDAuthResponse).not.toHaveBeenCalled();expect(mockSetAuthTokens).not.toHaveBeenCalled();expect(next).not.toHaveBeenCalled();});- it('stores the OpenID refresh token before setting cookies for the standard app', async () => {+ it('publishes the standard OpenID login through the durable generation service', async () => {process.env.OPENID_REUSE_TOKENS = 'true';mockIsAdminPanelRedirect.mockReturnValue(false);const handler = createOAuthHandler('http://localhost:3080');@@ -162,14 +163,14 @@ describe('createOAuthHandler', () => {await handler(req, res, next);- expect(mockStoreOpenIDSession).toHaveBeenCalledWith(- 'user-123',- 'openid-refresh-token',- undefined,- );- expect(mockSetOpenIDAuthTokens).toHaveBeenCalledWith(req.user.tokenset, req, res, {- userId: 'user-123',- tenantId: undefined,+ expect(mockSendOpenIDAuthResponse).toHaveBeenCalledWith({+ tokenset: req.user.tokenset,+ user: req.user,+ existingRefreshToken: 'openid-refresh-token',+ openidSubject: undefined,+ openidIssuer: undefined,+ req,+ res,});expect(res.redirect).toHaveBeenCalledWith('http://localhost:3080');});diff --git a/api/server/routes/__tests__/mcp.spec.js b/api/server/routes/__tests__/mcp.spec.jsindex 9fcb49a1aa..17b6d4e678 100644--- a/api/server/routes/__tests__/mcp.spec.js+++ b/api/server/routes/__tests__/mcp.spec.js@@ -2449,6 +2449,38 @@ describe('MCP Routes', () => {});});+ /**+ * Codex Finding 2 regression: the reinitialize route must forward a+ * session-aware upstream-token closure to reinitMCPServer so OBO servers+ * can mint a downstream token. The closure is built at the route boundary+ * (from req/res) and passed as `upstreamTokenProvider`; the raw `req` is+ * NOT threaded into the MCP layer.+ */+ it('forwards an upstream-token closure (not req) into reinitMCPServer for OBO session access', async () => {+ const mockMcpManager = {+ disconnectUserConnection: jest.fn().mockResolvedValue(),+ };+ mockRegistryInstance.getServerConfig.mockResolvedValue({});+ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);+ require('~/config').getFlowStateManager.mockReturnValue({});+ require('~/cache').getLogStores.mockReturnValue({});+ const reinitSpy = require('~/server/services/Tools/mcp').reinitMCPServer;+ reinitSpy.mockResolvedValue({ success: true, serverName: 'obo-server' });++ await request(app).post('/api/mcp/obo-server/reinitialize');++ expect(reinitSpy).toHaveBeenCalledWith(+ expect.objectContaining({+ upstreamTokenProvider: expect.any(Function),+ oboIdentityContext: expect.objectContaining({+ appUserId: 'test-user-id',+ }),+ }),+ );+ const [params] = reinitSpy.mock.calls[reinitSpy.mock.calls.length - 1];+ expect(params).not.toHaveProperty('req');+ });+it('should return 500 when unexpected error occurs', async () => {const mockMcpManager = {disconnectUserConnection: jest.fn(),diff --git a/api/server/routes/mcp.js b/api/server/routes/mcp.jsindex 32bca863d8..e430a4a324 100644--- a/api/server/routes/mcp.js+++ b/api/server/routes/mcp.js@@ -10,6 +10,7 @@ const {const {getBasePath,createSafeUser,+ createAuthIdentityContext,MCPOAuthHandler,MCPTokenStorage,setOAuthSession,@@ -51,6 +52,7 @@ const { getUserPluginAuthValue } = require('~/server/services/PluginService');const { invalidateCachedTools } = require('~/server/services/Config');const { updateMCPServerTools } = require('~/server/services/Config/mcp');const { reinitMCPServer } = require('~/server/services/Tools/mcp');+const { createOpenIDSessionTokenProvider } = require('~/server/services/OpenIDSessionRefresh');const { getLogStores } = require('~/cache');const db = require('~/models');@@ -839,6 +841,10 @@ router.post(findPluginAuthsByKeys: db.findPluginAuthsByKeys,});}+ const oboIdentityContext = createAuthIdentityContext({+ user: req.user,+ tenantId: getTenantId(),+ });const result = await reinitMCPServer({user,@@ -846,6 +852,14 @@ router.post(serverConfig,configServers,userMCPAuthMap,+ upstreamTokenProvider: createOpenIDSessionTokenProvider({+ req,+ res,+ user: req.user,+ identityContext: oboIdentityContext,+ tokenPreference: 'access_token',+ }),+ oboIdentityContext,});if (!result) {diff --git a/api/server/services/AuthService.js b/api/server/services/AuthService.jsindex 224e8436bf..fb736ded81 100644--- a/api/server/services/AuthService.js+++ b/api/server/services/AuthService.js@@ -1,6 +1,6 @@const bcrypt = require('bcryptjs');const jwt = require('jsonwebtoken');-const { createHash, webcrypto } = require('node:crypto');+const { webcrypto } = require('node:crypto');const {logger,getTenantId,@@ -19,6 +19,11 @@ const {CLOUDFRONT_SCOPE_COOKIE,isEmailDomainAllowed,shouldUseSecureCookie,+ setRefreshTokenCookie,+ setOpenIDMarkerCookies,+ clearCloudFrontCookies,+ normalizeExpiresIn,+ createOpenIDSessionIdentity,resolveAppConfigForUser,} = require('@librechat/api');const {@@ -154,6 +159,21 @@ const getPasswordResetTokenDeleteQuery = (passwordResetToken) => {};};+const isExpiredOpenIDIdToken = (idToken) => {+ if (!idToken) {+ return false;+ }++ const decoded = jwt.decode(idToken);+ if (!decoded || typeof decoded !== 'object' || typeof decoded.exp !== 'number') {+ return false;+ }++ return (+ decoded.exp <= Math.floor(Date.now() / 1000) + OPENID_SESSION_ID_TOKEN_EXPIRY_BUFFER_SECONDS+ );+};+const getUnexpiredOpenIDSessionIdToken = (idToken) => {if (!idToken) {return;@@ -170,6 +190,27 @@ const getUnexpiredOpenIDSessionIdToken = (idToken) => {}};+const getOpenIDAppAuthToken = (tokenset, sessionIdToken) =>+ (isExpiredOpenIDIdToken(tokenset?.id_token) ? undefined : tokenset?.id_token) ||+ getUnexpiredOpenIDSessionIdToken(sessionIdToken) ||+ tokenset?.access_token;++const clearOpenIDAuthTokens = (req, res, userId, tenantId) => {+ if (req.session?.openidTokens) {+ delete req.session.openidTokens;+ }+ for (const name of [+ 'refreshToken',+ 'openid_access_token',+ 'openid_id_token',+ 'openid_user_id',+ 'token_provider',+ ]) {+ res.clearCookie?.(name);+ }+ clearCloudFrontCookies(res, { userId, tenantId });+};+/*** Logout user*@@ -701,7 +742,9 @@ const resolveOpenIDAuthTokenOptions = (optionsOrUserId, existingRefreshToken, teif ('userId' in optionsOrUserId ||'existingRefreshToken' in optionsOrUserId ||- 'tenantId' in optionsOrUserId+ 'tenantId' in optionsOrUserId ||+ 'openidSubject' in optionsOrUserId ||+ 'openidIssuer' in optionsOrUserId) {return optionsOrUserId;}@@ -711,6 +754,44 @@ const resolveOpenIDAuthTokenOptions = (optionsOrUserId, existingRefreshToken, tereturn { userId: optionsOrUserId, existingRefreshToken, tenantId };};+const getOpenIDTokenClaims = (tokenset) => {+ if (typeof tokenset?.claims === 'function') {+ try {+ const claims = tokenset.claims();+ return claims && typeof claims === 'object' ? claims : {};+ } catch (error) {+ logger.debug('[setOpenIDAuthTokens] Unable to read tokenset claims', error?.message);+ }+ }++ if (typeof tokenset?.id_token !== 'string') {+ return {};+ }++ const decoded = jwt.decode(tokenset.id_token);+ return decoded && typeof decoded === 'object' ? decoded : {};+};++const getStringClaim = (claims, claim) => {+ const value = claims?.[claim];+ return typeof value === 'string' && value ? value : undefined;+};++const applyOpenIDSessionIdentity = (sessionOpenidTokens, identity) => {+ if (identity.appUserId) {+ sessionOpenidTokens.appUserId = identity.appUserId;+ }+ if (identity.openidSubject) {+ sessionOpenidTokens.openidSubject = identity.openidSubject;+ }+ if (identity.tenantId) {+ sessionOpenidTokens.tenantId = identity.tenantId;+ }+ if (identity.openidIssuer) {+ sessionOpenidTokens.openidIssuer = identity.openidIssuer;+ }+};+/*** @function setOpenIDAuthTokens* Set OpenID Authentication Tokens@@ -725,6 +806,8 @@ const resolveOpenIDAuthTokenOptions = (optionsOrUserId, existingRefreshToken, te* @param {string} [options.userId] - Optional MongoDB user ID for image path validation* @param {string} [options.existingRefreshToken] - Optional existing refresh token to preserve* @param {string} [options.tenantId] - Optional tenant identifier for CloudFront cookie scoping+ * @param {string} [options.openidSubject] - Optional OpenID subject bound to the session tokens+ * @param {string} [options.openidIssuer] - Optional OpenID issuer bound to the session tokens* @returns {String} - id_token (preferred) or access_token as the app auth token*/const setOpenIDAuthTokens = (@@ -736,11 +819,8 @@ const setOpenIDAuthTokens = (tenantIdArg,) => {try {- const { userId, existingRefreshToken, tenantId } = resolveOpenIDAuthTokenOptions(- optionsOrUserId,- existingRefreshTokenArg,- tenantIdArg,- );+ const { userId, existingRefreshToken, tenantId, openidSubject, openidIssuer } =+ resolveOpenIDAuthTokenOptions(optionsOrUserId, existingRefreshTokenArg, tenantIdArg);if (!tokenset) {logger.error('[setOpenIDAuthTokens] No tokenset found in request');@@ -771,11 +851,22 @@ const setOpenIDAuthTokens = (* Falls back to access_token for providers where id_token is not available.*/const sessionIdToken = req.session?.openidTokens?.idToken;- const appAuthToken =- tokenset.id_token ||- getUnexpiredOpenIDSessionIdToken(sessionIdToken) ||- tokenset.access_token;+ /**+ * An inline refresh carries the previous id_token forward when the IdP omits one on+ * rotation, so `tokenset.id_token` is not necessarily freshly issued. Skip it only when it+ * is provably expired; an id_token whose expiry cannot be read stays preferred, since+ * access_token may be opaque or scoped to another audience and fail JWKS validation.+ */+ const appAuthToken = getOpenIDAppAuthToken(tokenset, sessionIdToken);const logoutIdToken = tokenset.id_token || sessionIdToken;+ const claims = getOpenIDTokenClaims(tokenset);+ const sessionIdentity = createOpenIDSessionIdentity({+ user: req?.user,+ userId,+ openidSubject: openidSubject ?? getStringClaim(claims, 'sub'),+ tenantId,+ openidIssuer: openidIssuer ?? getStringClaim(claims, 'iss'),+ });/*** Always set refresh token cookie so it survives express session expiry.@@ -786,22 +877,34 @@ const setOpenIDAuthTokens = (* The refresh token is small (opaque string) so it doesn't hit the HTTP/2 header* size limits that motivated session storage for the larger access_token/id_token.*/- res.cookie('refreshToken', refreshToken, {- expires: expirationDate,- httpOnly: true,- secure: shouldUseSecureCookie(),- sameSite: 'strict',- });+ setRefreshTokenCookie(res, refreshToken, expirationDate);/** Store tokens server-side in session to avoid large cookies */if (req.session) {- req.session.openidTokens = {+ const sessionOpenidTokens = {accessToken: tokenset.access_token,idToken: logoutIdToken,refreshToken: refreshToken,+ browserRefreshToken: refreshToken,expiresAt: expirationDate.getTime(),lastRefreshedAt: Date.now(),};+ applyOpenIDSessionIdentity(sessionOpenidTokens, sessionIdentity);+ /**+ * Capture the access-token's own expiry (unix seconds) when the IdP+ * advertises one. Lets downstream consumers — notably the OBO inline-+ * refresh path in `OpenIDSessionRefresh.js` — reuse opaque (non-JWT)+ * access tokens without burning an IdP refresh on the first tool call.+ * Without this, the very first OBO call after login or SPA refresh would+ * always trigger a redundant inline refresh whenever the IdP issues+ * opaque access tokens (e.g. Microsoft Graph audiences).+ */+ const accessTokenExpiresIn = normalizeExpiresIn(tokenset.expires_in);+ if (accessTokenExpiresIn != null) {+ sessionOpenidTokens.accessTokenExpiresAt =+ Math.floor(Date.now() / 1000) + accessTokenExpiresIn;+ }+ req.session.openidTokens = sessionOpenidTokens;} else {logger.warn('[setOpenIDAuthTokens] No session available, falling back to cookies');res.cookie('openid_access_token', tokenset.access_token, {@@ -820,28 +923,12 @@ const setOpenIDAuthTokens = (}}- /** Small cookie to indicate token provider (required for auth middleware) */- res.cookie('token_provider', 'openid', {+ setOpenIDMarkerCookies(res, {+ userId,expires: expirationDate,- httpOnly: true,- secure: shouldUseSecureCookie(),- sameSite: 'strict',+ refreshExpiryMs: expiryInMilliseconds,+ refreshToken,});- if (userId && isEnabled(process.env.OPENID_REUSE_TOKENS)) {- /** Bind image cookie identity to the durable refresh-token session. */- const refreshTokenHash = createHash('sha256').update(refreshToken).digest('base64url');- const signedUserId = jwt.sign(- { id: userId, refreshTokenHash },- process.env.JWT_REFRESH_SECRET,- { expiresIn: expiryInMilliseconds / 1000 },- );- res.cookie('openid_user_id', signedUserId, {- expires: expirationDate,- httpOnly: true,- secure: shouldUseSecureCookie(),- sameSite: 'strict',- });- }setCloudFrontAuthCookies(req, res, req.user, { userId, tenantId });@@ -927,6 +1014,8 @@ module.exports = {registerUser,setAuthTokens,resetPassword,+ clearOpenIDAuthTokens,+ getOpenIDAppAuthToken,setOpenIDAuthTokens,storeOpenIDSession,setCloudFrontAuthCookies,diff --git a/api/server/services/AuthService.spec.js b/api/server/services/AuthService.spec.jsindex fb74692f9a..d6182e1334 100644--- a/api/server/services/AuthService.spec.js+++ b/api/server/services/AuthService.spec.js@@ -20,25 +20,80 @@ jest.mock();jest.mock('@librechat/api',- () => ({- isEnabled: jest.fn((val) => val === 'true' || val === true),- checkEmailConfig: jest.fn(),- isEmailDomainAllowed: jest.fn(),- math: jest.fn((val, fallback) => (val ? Number(val) : fallback)),- storeOpenIdSession: jest.fn(),- shouldUseSecureCookie: jest.fn(() => false),- resolveAppConfigForUser: jest.fn(async (_getAppConfig, _user) => ({})),- setCloudFrontCookies: jest.fn(() => true),- getCloudFrontConfig: jest.fn(() => ({- domain: 'https://cdn.example.com',- imageSigning: 'cookies',- cookieDomain: '.example.com',- privateKey: 'test-private-key',- keyPairId: 'K123ABC',- })),- parseCloudFrontCookieScope: jest.fn(() => null),- CLOUDFRONT_SCOPE_COOKIE: 'LibreChat-CloudFront-Scope',- }),+ () => {+ const shouldUseSecureCookie = jest.fn(() => false);+ return {+ isEnabled: jest.fn((val) => val === 'true' || val === true),+ checkEmailConfig: jest.fn(),+ isEmailDomainAllowed: jest.fn(),+ math: jest.fn((val, fallback) => (val ? Number(val) : fallback)),+ storeOpenIdSession: jest.fn(),+ shouldUseSecureCookie,+ setRefreshTokenCookie: jest.fn((res, refreshToken, expires) => {+ res.cookie('refreshToken', refreshToken, {+ expires,+ httpOnly: true,+ secure: shouldUseSecureCookie(),+ sameSite: 'strict',+ });+ }),+ setOpenIDMarkerCookies: jest.fn((res, { userId, expires }) => {+ res.cookie('token_provider', 'openid', {+ expires,+ httpOnly: true,+ secure: shouldUseSecureCookie(),+ sameSite: 'strict',+ });+ if (userId) {+ res.cookie('openid_user_id', `signed:${userId}`, {+ expires,+ httpOnly: true,+ secure: shouldUseSecureCookie(),+ sameSite: 'strict',+ });+ }+ }),+ normalizeExpiresIn: (value) => {+ const normalized = typeof value === 'string' && value.trim() ? Number(value) : value;+ return typeof normalized === 'number' && Number.isFinite(normalized)+ ? normalized+ : undefined;+ },+ resolveAppConfigForUser: jest.fn(async (_getAppConfig, _user) => ({})),+ createOpenIDSessionIdentity: jest.fn(+ ({ user, userId, openidSubject, tenantId, openidIssuer }) => {+ const normalize = (value) => {+ if (value == null) {+ return undefined;+ }+ const normalized = typeof value === 'string' ? value.trim() : value.toString().trim();+ return normalized || undefined;+ };+ const normalizeIssuer = (value) =>+ normalize(value)+ ?.replace(/\/\.well-known\/openid-configuration$/, '')+ .replace(/\/+$/, '');+ return {+ appUserId: normalize(userId) ?? normalize(user?._id) ?? normalize(user?.id),+ openidSubject: normalize(openidSubject) ?? normalize(user?.openidId),+ tenantId: normalize(tenantId) ?? normalize(user?.tenantId),+ openidIssuer: normalizeIssuer(openidIssuer) ?? normalizeIssuer(user?.openidIssuer),+ };+ },+ ),+ setCloudFrontCookies: jest.fn(() => true),+ clearCloudFrontCookies: jest.fn(),+ getCloudFrontConfig: jest.fn(() => ({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieDomain: '.example.com',+ privateKey: 'test-private-key',+ keyPairId: 'K123ABC',+ })),+ parseCloudFrontCookieScope: jest.fn(() => null),+ CLOUDFRONT_SCOPE_COOKIE: 'LibreChat-CloudFront-Scope',+ };+ },{ virtual: true },);jest.mock('~/models', () => ({@@ -75,48 +130,88 @@ jest.mock('~/strategies/validators', () => ({jest.mock('~/server/services/Config', () => ({ getAppConfig: jest.fn() }));jest.mock('~/server/utils', () => ({ sendEmail: jest.fn() }));-const {- checkEmailConfig,- shouldUseSecureCookie,- isEmailDomainAllowed,- resolveAppConfigForUser,- setCloudFrontCookies,- getCloudFrontConfig,- parseCloudFrontCookieScope,- storeOpenIdSession,-} = require('@librechat/api');-const jwt = require('jsonwebtoken');-const { createHash } = require('node:crypto');-const { logger, getTenantId } = require('@librechat/data-schemas');-const {- findUser,- findToken,- createUser,- updateUser,- countUsers,- getUserById,- generateToken,- generateRefreshToken,- createSession,- upsertSession,- deleteSession,- createToken,- deleteTokens,-} = require('~/models');-const { getAppConfig } = require('~/server/services/Config');-const { sendEmail } = require('~/server/utils');-const bcrypt = require('bcryptjs');-const {- setOpenIDAuthTokens,- storeOpenIDSession,- requestPasswordReset,- registerUser,- resetPassword,- resendVerificationEmail,- setAuthTokens,- setCloudFrontAuthCookies,- verifyEmail,-} = require('./AuthService');+let checkEmailConfig;+let isEmailDomainAllowed;+let resolveAppConfigForUser;+let setRefreshTokenCookie;+let setOpenIDMarkerCookies;+let setCloudFrontCookies;+let getCloudFrontConfig;+let parseCloudFrontCookieScope;+let storeOpenIdSession;+let jwt;+let logger;+let getTenantId;+let findUser;+let findToken;+let createUser;+let updateUser;+let countUsers;+let getUserById;+let generateToken;+let generateRefreshToken;+let createSession;+let upsertSession;+let deleteSession;+let createToken;+let deleteTokens;+let getAppConfig;+let sendEmail;+let bcrypt;+let setOpenIDAuthTokens;+let storeOpenIDSession;+let requestPasswordReset;+let registerUser;+let resetPassword;+let resendVerificationEmail;+let setAuthTokens;+let setCloudFrontAuthCookies;+let verifyEmail;++jest.isolateModules(() => {+ ({+ checkEmailConfig,+ isEmailDomainAllowed,+ resolveAppConfigForUser,+ setRefreshTokenCookie,+ setOpenIDMarkerCookies,+ setCloudFrontCookies,+ getCloudFrontConfig,+ parseCloudFrontCookieScope,+ storeOpenIdSession,+ } = require('@librechat/api'));+ jwt = require('jsonwebtoken');+ ({ logger, getTenantId } = require('@librechat/data-schemas'));+ ({+ findUser,+ findToken,+ createUser,+ updateUser,+ countUsers,+ getUserById,+ generateToken,+ generateRefreshToken,+ createSession,+ upsertSession,+ deleteSession,+ createToken,+ deleteTokens,+ } = require('~/models'));+ ({ getAppConfig } = require('~/server/services/Config'));+ ({ sendEmail } = require('~/server/utils'));+ bcrypt = require('bcryptjs');+ ({+ setOpenIDAuthTokens,+ storeOpenIDSession,+ requestPasswordReset,+ registerUser,+ resetPassword,+ resendVerificationEmail,+ setAuthTokens,+ setCloudFrontAuthCookies,+ verifyEmail,+ } = require('./AuthService'));+});/** Helper to build a mock Express response */function mockResponse() {@@ -236,9 +331,96 @@ describe('setOpenIDAuthTokens', () => {expect(req.session.openidTokens.accessToken).toBe('the-access-token');expect(req.session.openidTokens.idToken).toBe('the-id-token');expect(req.session.openidTokens.refreshToken).toBe('the-refresh-token');+ expect(req.session.openidTokens.browserRefreshToken).toBe('the-refresh-token');expect(req.session.openidTokens.lastRefreshedAt).toEqual(expect.any(Number));});+ it('should bind session tokens to the OpenID user identity', () => {+ const tokenset = {+ id_token: 'the-id-token',+ access_token: 'the-access-token',+ refresh_token: 'the-refresh-token',+ };+ const req = mockRequest();+ const res = mockResponse();++ setOpenIDAuthTokens(tokenset, req, res, {+ userId: 'user-123',+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenantA',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ });++ expect(req.session.openidTokens).toEqual(+ expect.objectContaining({+ appUserId: 'user-123',+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenantA',+ openidIssuer: 'https://issuer.example.com',+ }),+ );+ });++ /**+ * Codex Finding 5: persist the access-token's expiry (unix seconds) so the+ * first OBO call after login or SPA refresh can reuse a still-valid OPAQUE+ * access token without burning a redundant inline refresh. The expiry comes+ * from the IdP's `tokenset.expires_in`; downstream consumers (notably+ * `OpenIDSessionRefresh.getAccessTokenExp`) read it as a fallback when the+ * access token isn't a JWT and can't be decoded.+ */+ it('should persist accessTokenExpiresAt when tokenset.expires_in is provided', () => {+ const tokenset = {+ id_token: 'the-id-token',+ access_token: 'the-access-token',+ refresh_token: 'the-refresh-token',+ expires_in: 3600,+ };+ const req = mockRequest();+ const res = mockResponse();+ const beforeSec = Math.floor(Date.now() / 1000);++ setOpenIDAuthTokens(tokenset, req, res, 'user-123');++ const persisted = req.session.openidTokens.accessTokenExpiresAt;+ expect(typeof persisted).toBe('number');+ expect(persisted).toBeGreaterThanOrEqual(beforeSec + 3590);+ expect(persisted).toBeLessThanOrEqual(beforeSec + 3610);+ });++ it('should persist accessTokenExpiresAt when tokenset.expires_in is a numeric string', () => {+ const tokenset = {+ id_token: 'the-id-token',+ access_token: 'the-access-token',+ refresh_token: 'the-refresh-token',+ expires_in: '3600',+ };+ const req = mockRequest();+ const res = mockResponse();+ const beforeSec = Math.floor(Date.now() / 1000);++ setOpenIDAuthTokens(tokenset, req, res, 'user-123');++ expect(req.session.openidTokens.accessTokenExpiresAt).toBeGreaterThanOrEqual(+ beforeSec + 3590,+ );+ });++ it('should NOT persist accessTokenExpiresAt when tokenset.expires_in is missing', () => {+ const tokenset = {+ id_token: 'the-id-token',+ access_token: 'the-access-token',+ refresh_token: 'the-refresh-token',+ // expires_in deliberately omitted+ };+ const req = mockRequest();+ const res = mockResponse();++ setOpenIDAuthTokens(tokenset, req, res, 'user-123');++ expect(req.session.openidTokens).not.toHaveProperty('accessTokenExpiresAt');+ });+it('should return the existing unexpired session id_token when refresh omits one', () => {const existingIdToken = jwt.sign({ sub: 'user-123', exp: Math.floor(Date.now() / 1000) + 3600 },@@ -291,6 +473,43 @@ describe('setOpenIDAuthTokens', () => {expect(req.session.openidTokens.accessToken).toBe('new-access-token');});+ it('falls back to access_token when the refresh carried an expired id_token forward', () => {+ const expiredIdToken = jwt.sign(+ { sub: 'user-123', exp: Math.floor(Date.now() / 1000) - 60 },+ 'idp-signing-secret',+ );+ const tokenset = {+ id_token: expiredIdToken,+ access_token: 'new-access-token',+ refresh_token: 'new-refresh-token',+ };+ const req = mockRequest({+ openidTokens: {+ accessToken: 'old-access-token',+ idToken: expiredIdToken,+ refreshToken: 'old-refresh-token',+ },+ });+ const res = mockResponse();++ const result = setOpenIDAuthTokens(tokenset, req, res, 'user-123');++ expect(result).toBe('new-access-token');+ expect(req.session.openidTokens.idToken).toBe(expiredIdToken);+ });++ it('still prefers an id_token whose expiry cannot be read', () => {+ const tokenset = {+ id_token: 'opaque-but-not-a-jwt',+ access_token: 'new-access-token',+ refresh_token: 'new-refresh-token',+ };+ const req = mockRequest();+ const res = mockResponse();++ expect(setOpenIDAuthTokens(tokenset, req, res, 'user-123')).toBe('opaque-but-not-a-jwt');+ });+it('should fall back to access_token when the existing session id_token is near expiry', () => {const nearExpiryIdToken = jwt.sign({ sub: 'user-123', exp: Math.floor(Date.now() / 1000) + 10 },@@ -317,25 +536,6 @@ describe('setOpenIDAuthTokens', () => {});});- it('binds the signed OpenID user cookie to its refresh token', () => {- const tokenset = {- id_token: 'the-id-token',- access_token: 'the-access-token',- refresh_token: 'the-refresh-token',- };- const req = mockRequest();- const res = mockResponse();-- setOpenIDAuthTokens(tokenset, req, res, 'user-123');-- expect(jwt.verify(res._cookies.openid_user_id.value, process.env.JWT_REFRESH_SECRET)).toEqual(- expect.objectContaining({- id: 'user-123',- refreshTokenHash: createHash('sha256').update(tokenset.refresh_token).digest('base64url'),- }),- );- });-it('stores an OpenID refresh token for durable revocation checks', async () => {storeOpenIdSession.mockResolvedValue(true);@@ -368,31 +568,8 @@ describe('setOpenIDAuthTokens', () => {);});- describe('cookie secure flag', () => {- it('should call shouldUseSecureCookie for every cookie set', () => {- const tokenset = {- id_token: 'the-id-token',- access_token: 'the-access-token',- refresh_token: 'the-refresh-token',- };- const req = mockRequest();- const res = mockResponse();-- setOpenIDAuthTokens(tokenset, req, res, 'user-123');-- // token_provider + openid_user_id (session path, so no refreshToken/openid_access_token cookies)- const secureCalls = shouldUseSecureCookie.mock.calls.length;- expect(secureCalls).toBeGreaterThanOrEqual(2);-- // Verify all cookies use the result of shouldUseSecureCookie- for (const [, cookie] of Object.entries(res._cookies)) {- expect(cookie.options.secure).toBe(false);- }- });-- it('should set secure: true when shouldUseSecureCookie returns true', () => {- shouldUseSecureCookie.mockReturnValue(true);-+ describe('OpenID cookie delegation', () => {+ it('delegates session-path refresh and marker cookies to shared cookie helpers', () => {const tokenset = {id_token: 'the-id-token',access_token: 'the-access-token',@@ -403,14 +580,30 @@ describe('setOpenIDAuthTokens', () => {setOpenIDAuthTokens(tokenset, req, res, 'user-123');- for (const [, cookie] of Object.entries(res._cookies)) {- expect(cookie.options.secure).toBe(true);- }+ expect(setRefreshTokenCookie).toHaveBeenCalledWith(+ res,+ 'the-refresh-token',+ expect.any(Date),+ );+ expect(setOpenIDMarkerCookies).toHaveBeenCalledWith(res, {+ userId: 'user-123',+ expires: expect.any(Date),+ refreshExpiryMs: 604800000,+ refreshToken: 'the-refresh-token',+ });+ expect(res.cookie).not.toHaveBeenCalledWith(+ 'openid_access_token',+ expect.any(String),+ expect.any(Object),+ );+ expect(res.cookie).not.toHaveBeenCalledWith(+ 'openid_id_token',+ expect.any(String),+ expect.any(Object),+ );});- it('should use shouldUseSecureCookie for cookie fallback path (no session)', () => {- shouldUseSecureCookie.mockReturnValue(false);-+ it('uses cookie fallback for OpenID access tokens when no session is available', () => {const tokenset = {id_token: 'the-id-token',access_token: 'the-access-token',@@ -421,21 +614,34 @@ describe('setOpenIDAuthTokens', () => {setOpenIDAuthTokens(tokenset, req, res, 'user-123');- // In the cookie fallback path, we get: refreshToken, openid_access_token, token_provider, openid_user_id- expect(res.cookie).toHaveBeenCalledWith(- 'refreshToken',- expect.any(String),- expect.objectContaining({ secure: false }),+ expect(setRefreshTokenCookie).toHaveBeenCalledWith(+ res,+ 'the-refresh-token',+ expect.any(Date),);+ expect(setOpenIDMarkerCookies).toHaveBeenCalledWith(res, {+ userId: 'user-123',+ expires: expect.any(Date),+ refreshExpiryMs: 604800000,+ refreshToken: 'the-refresh-token',+ });expect(res.cookie).toHaveBeenCalledWith('openid_access_token',- expect.any(String),- expect.objectContaining({ secure: false }),+ 'the-access-token',+ expect.objectContaining({+ expires: expect.any(Date),+ httpOnly: true,+ sameSite: 'strict',+ }),);expect(res.cookie).toHaveBeenCalledWith(- 'token_provider',- 'openid',- expect.objectContaining({ secure: false }),+ 'openid_id_token',+ 'the-id-token',+ expect.objectContaining({+ expires: expect.any(Date),+ httpOnly: true,+ sameSite: 'strict',+ }),);});});diff --git a/api/server/services/GraphApiService.spec.js b/api/server/services/GraphApiService.spec.jsindex 0a625e77e1..3f085dabb7 100644--- a/api/server/services/GraphApiService.spec.js+++ b/api/server/services/GraphApiService.spec.js@@ -208,10 +208,12 @@ describe('GraphApiService', () => {);}+ /** The entry expires 30s (OPENID_EXPIRY_BUFFER_SECONDS) before the credential it holds, so a+ * token served from cache cannot expire in transit and 401 against Graph. */expect(mockTokensCache.set).toHaveBeenCalledWith('test-user:graph',{ access_token: 'mocked-graph-token' },- 3600000,+ 3570000,);expect(result).toBe('mocked-graph-token');diff --git a/api/server/services/MCP.js b/api/server/services/MCP.jsindex 3e5cb87b0e..3f636d7591 100644--- a/api/server/services/MCP.js+++ b/api/server/services/MCP.js@@ -38,6 +38,7 @@ const {requiresOAuthMachinery,hasRuntimeUrlPlaceholders,containsGraphTokenPlaceholder,+ createAuthIdentityContext,isOAuthServer,OpenIDReauthRequiredError,} = require('@librechat/api');@@ -60,6 +61,7 @@ const { findToken, createToken, updateToken, deleteTokens, findPluginAuthsByKeysconst { getGraphApiToken } = require('./GraphTokenService');const { exchangeOboToken } = require('./OboTokenService');const { createOboTrustChecker } = require('./OboPolicyService');+const { createOpenIDSessionTokenProvider } = require('./OpenIDSessionRefresh');const { reinitMCPServer } = require('./Tools/mcp');const {getAppConfig,@@ -367,12 +369,24 @@ async function healMcpToolNames({ req, tools, toolDefinitions, accessibleServerN* server slices instead of relying on the static aggregate cache.* @param {object} params* @param {ServerRequest} params.req+ * @param {ServerResponse} [params.res]* @param {Array<string | object>} [params.tools]* @returns {Promise<object>}*/-async function getAssistantToolDefinitions({ req, tools }) {+async function getAssistantToolDefinitions({ req, res, tools }) {const registry = getMCPServersRegistry();const appConfig = await getAppConfigForRequest(req);+ const oboIdentityContext = createAuthIdentityContext({+ user: req.user,+ tenantId: getTenantId(),+ });+ const upstreamTokenProvider = createOpenIDSessionTokenProvider({+ req,+ res: res ?? req.res,+ user: req.user,+ identityContext: oboIdentityContext,+ tokenPreference: 'access_token',+ });return await loadAssistantToolDefinitions({user: req.user,@@ -404,6 +418,8 @@ async function getAssistantToolDefinitions({ req, tools }) {serverName,serverConfig,userMCPAuthMap,+ upstreamTokenProvider,+ oboIdentityContext,});return result?.availableTools ?? null;},@@ -669,9 +685,29 @@ function createOAuthCallback({ runStepEmitter, runStepDeltaEmitter }) {};}+function resolveToolCallUserId({ effectiveUser, capturedUser, invocationUserId, serverConfig }) {+ if (serverConfig?.obo == null) {+ return effectiveUser?.id || invocationUserId || capturedUser?.id;+ }++ const effectiveUserId = effectiveUser?.id;+ const capturedUserId = capturedUser?.id;+ if (!effectiveUserId || !capturedUserId) {+ throw new Error('OBO tool calls require matching captured and effective user ids');+ }++ if (effectiveUserId !== capturedUserId) {+ throw new Error('OBO tool call user mismatch');+ }++ return effectiveUserId;+}+/*** @param {Object} params* @param {ServerResponse} params.res - The Express response object for sending events.+ * @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary so this layer never receives the raw Express request.+ * @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.* @param {IUser} params.user - The user from the request object.* @param {string} params.serverName* @param {AbortSignal} params.signal@@ -695,6 +731,8 @@ async function reconnectServer({userMCPAuthMap,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,streamId = null,jobCreatedAt,}) {@@ -760,6 +798,8 @@ async function reconnectServer({userMCPAuthMap,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,forceNew: true,returnOnOAuth: false,connectionTimeout: Time.THIRTY_SECONDS,@@ -787,6 +827,8 @@ async function reconnectServer({* @param {import('@librechat/api').RequestBody} [params.requestBody]* @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]+ * @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary.+ * @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.* @returns { Promise<Array<typeof tool | { _call: (toolInput: Object | string) => unknown}>> } An object with `_call` method to execute the tool input.*/async function createMCPTools({@@ -802,6 +844,8 @@ async function createMCPTools({userMCPAuthMap,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,streamId = null,jobCreatedAt,}) {@@ -842,6 +886,8 @@ async function createMCPTools({userMCPAuthMap,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,streamId,jobCreatedAt,});@@ -877,6 +923,8 @@ async function createMCPTools({toolKey: `${keyToolNames.get(tool.name) ?? tool.name}${Constants.mcp_delimiter}${keyServerName}`,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,config: serverConfig,});if (toolInstance) {@@ -904,6 +952,9 @@ async function createMCPTools({* @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]* @param {import('@librechat/api').ParsedServerConfig} [params.config]+ * @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary.+ * @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.+ * @param {string} [params.serverName] - Resolved raw MCP server name from tool loading.* @param {(availableTools: LCAvailableTools) => void} [params.onAvailableTools]* @param {number} [params.jobCreatedAt] - The generation epoch that owns emitted events.* @returns { Promise<typeof tool | { _call: (toolInput: Object | string) => unknown}> } An object with `_call` method to execute the tool input.@@ -922,6 +973,8 @@ async function createMCPTool({requestScopedConnections,config,configServers,+ upstreamTokenProvider,+ oboIdentityContext,serverName: resolvedServerName,onAvailableTools,streamId = null,@@ -1050,6 +1103,8 @@ async function createMCPTool({userMCPAuthMap,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,streamId,jobCreatedAt,});@@ -1092,6 +1147,8 @@ async function createMCPTool({serverName,serverConfig,toolDefinition: toolEntry['function'],+ upstreamTokenProvider,+ oboIdentityContext,streamId,jobCreatedAt,});@@ -1110,6 +1167,8 @@ function createToolInstance({serverConfig: capturedServerConfig,toolDefinition,provider: capturedProvider,+ upstreamTokenProvider: capturedUpstreamTokenProvider = null,+ oboIdentityContext: capturedOboIdentityContext = null,streamId = null,jobCreatedAt,}) {@@ -1141,8 +1200,16 @@ function createToolInstance({const _call = async (toolArguments, config) => {const effectiveUser = config?.configurable?.user ?? capturedUser;const permissionUser = effectiveUser;- const userId = effectiveUser?.id || config?.configurable?.user_id || capturedUser?.id;+ /** @type {string | undefined} */+ let userId;+try {+ userId = resolveToolCallUserId({+ effectiveUser,+ capturedUser,+ invocationUserId: config?.configurable?.user_id,+ serverConfig: capturedServerConfig,+ });const provider = (config?.metadata?.provider || capturedProvider)?.toLowerCase();const canUseMCP = mcpPermissionContext? await mcpPermissionContext.canUseServers(permissionUser)@@ -1180,6 +1247,17 @@ function createToolInstance({const customUserVars =config?.configurable?.userMCPAuthMap?.[`${Constants.mcp_prefix}${serverName}`];+ /**+ * The upstream-token closure is built at the request boundary (where+ * `req`/`res` are in scope) and captured here, so this layer never holds+ * the raw Express request. The closure reads/refreshes the LIVE+ * `req.session.openidTokens` at call time and persists rotations; it is a+ * no-op when reuse is off or the user is non-OpenID. A browser request whose session loses+ * openidTokens rejects instead of falling back to a stale strategy snapshot.+ * `tokenPreference: 'access_token'` (set at construction)+ * is required for OBO since the grant sends the access token to the IdP+ * as the jwt-bearer assertion.+ */const result = await mcpManager.callTool({serverName,serverConfig: capturedServerConfig,@@ -1208,6 +1286,8 @@ function createToolInstance({graphTokenResolver: getGraphApiToken,oboTokenResolver: exchangeOboToken,oboTrustChecker: createOboTrustChecker(),+ upstreamTokenProvider: capturedUpstreamTokenProvider,+ oboIdentityContext: capturedOboIdentityContext,});if (isAssistantsEndpoint(provider) && Array.isArray(result)) {diff --git a/api/server/services/MCP.spec.js b/api/server/services/MCP.spec.jsindex 36a1ac57ed..86a0681c28 100644--- a/api/server/services/MCP.spec.js+++ b/api/server/services/MCP.spec.js@@ -91,6 +91,14 @@ jest.mock('./GraphTokenService', () => ({getGraphApiToken: jest.fn(),}));+jest.mock('./OboTokenService', () => ({+ exchangeOboToken: jest.fn(),+}));++jest.mock('./OboPolicyService', () => ({+ createOboTrustChecker: jest.fn(() => jest.fn()),+}));+describe('tests for the new helper functions used by the MCP connection status endpoints', () => {let mockGetMCPManager;let mockGetFlowStateManager;@@ -2333,6 +2341,200 @@ describe('User parameter passing tests', () => {}),);});++ it('forwards the pre-built upstream-token closure to callTool without receiving req', async () => {+ const mockUser = {+ id: 'obo-user',+ email: '[email protected]',+ role: 'USER',+ provider: 'openid',+ };+ const mockRes = { write: jest.fn(), flush: jest.fn() };+ const { getRoleByName } = require('~/models');+ getRoleByName.mockResolvedValue({+ permissions: {+ [PermissionTypes.MCP_SERVERS]: {+ [Permissions.USE]: true,+ },+ },+ });++ const sentinelClosure = async () => null;++ const mockCallTool = jest.fn().mockResolvedValue(['ok', null]);+ mockGetMCPManager.mockReturnValue({ callTool: mockCallTool });++ const mcpTool = await createMCPTool({+ res: mockRes,+ user: mockUser,+ toolKey: `test-tool${D}test-server`,+ provider: 'openai',+ userMCPAuthMap: {},+ upstreamTokenProvider: sentinelClosure,+ availableTools: {+ [`test-tool${D}test-server`]: {+ function: {+ description: 'Cached tool',+ parameters: { type: 'object', properties: {} },+ },+ },+ },+ });++ await expect(+ mcpTool.invoke(+ {},+ {+ configurable: { user: mockUser },+ metadata: { provider: 'openai', thread_id: 't1', run_id: 'r1' },+ toolCall: {},+ },+ ),+ ).resolves.toBe('ok');++ expect(mockCallTool).toHaveBeenCalledWith(+ expect.objectContaining({+ upstreamTokenProvider: sentinelClosure,+ }),+ );+ });++ it('should reject OBO tool execution when effective and captured users differ', async () => {+ const capturedUser = { id: 'captured-user', email: '[email protected]', role: 'USER' };+ const effectiveUser = { id: 'effective-user', email: '[email protected]', role: 'USER' };+ const mockRes = { write: jest.fn(), flush: jest.fn() };++ const mcpTool = await createMCPTool({+ res: mockRes,+ user: capturedUser,+ toolKey: `test-tool${D}obo-server`,+ provider: 'openai',+ userMCPAuthMap: {},+ config: {+ url: 'https://obo.example.com',+ obo: { scopes: 'api://obo-server/Mcp.Tools.ReadWrite' },+ },+ availableTools: {+ [`test-tool${D}obo-server`]: {+ function: {+ description: 'Cached OBO tool',+ parameters: { type: 'object', properties: {} },+ },+ },+ },+ });++ await expect(+ mcpTool.invoke(+ {},+ {+ configurable: { user: effectiveUser },+ metadata: { provider: 'openai', thread_id: 't1', run_id: 'r1' },+ toolCall: {},+ },+ ),+ ).rejects.toThrow('OBO tool call user mismatch');++ expect(mockGetMCPManager).not.toHaveBeenCalled();+ });++ it('should reject OBO tool execution when an effective or captured user id is missing', async () => {+ const capturedUser = { email: '[email protected]', role: 'USER' };+ const effectiveUser = { id: 'effective-user', email: '[email protected]', role: 'USER' };+ const mockRes = { write: jest.fn(), flush: jest.fn() };++ const mcpTool = await createMCPTool({+ res: mockRes,+ user: capturedUser,+ toolKey: `test-tool${D}obo-server`,+ provider: 'openai',+ userMCPAuthMap: {},+ config: {+ url: 'https://obo.example.com',+ obo: { scopes: 'api://obo-server/Mcp.Tools.ReadWrite' },+ },+ availableTools: {+ [`test-tool${D}obo-server`]: {+ function: {+ description: 'Cached OBO tool',+ parameters: { type: 'object', properties: {} },+ },+ },+ },+ });++ await expect(+ mcpTool.invoke(+ {},+ {+ configurable: { user: effectiveUser },+ metadata: { provider: 'openai', thread_id: 't1', run_id: 'r1' },+ toolCall: {},+ },+ ),+ ).rejects.toThrow('OBO tool calls require matching captured and effective user ids');++ expect(mockGetMCPManager).not.toHaveBeenCalled();+ });++ it('should execute OBO tools when effective and captured user ids match', async () => {+ const capturedUser = { id: 'obo-user', email: '[email protected]', role: 'USER' };+ const effectiveUser = { id: 'obo-user', email: '[email protected]', role: 'USER' };+ const mockRes = { write: jest.fn(), flush: jest.fn() };+ const { getRoleByName } = require('~/models');+ getRoleByName.mockResolvedValue({+ permissions: {+ [PermissionTypes.MCP_SERVERS]: {+ [Permissions.USE]: true,+ },+ },+ });++ const mockCallTool = jest.fn().mockResolvedValue(['ok', null]);+ mockGetMCPManager.mockReturnValue({ callTool: mockCallTool });++ const mcpTool = await createMCPTool({+ res: mockRes,+ user: capturedUser,+ toolKey: `test-tool${D}obo-server`,+ provider: 'openai',+ userMCPAuthMap: {},+ upstreamTokenProvider: async () => null,+ config: {+ url: 'https://obo.example.com',+ obo: { scopes: 'api://obo-server/Mcp.Tools.ReadWrite' },+ },+ availableTools: {+ [`test-tool${D}obo-server`]: {+ function: {+ description: 'Cached OBO tool',+ parameters: { type: 'object', properties: {} },+ },+ },+ },+ });++ await expect(+ mcpTool.invoke(+ {},+ {+ configurable: {+ user: effectiveUser,+ user_id: 'third-user',+ },+ metadata: { provider: 'openai', thread_id: 't1', run_id: 'r1' },+ toolCall: {},+ },+ ),+ ).resolves.toBe('ok');++ expect(mockGetMCPManager).toHaveBeenCalledWith('obo-user');+ expect(mockCallTool).toHaveBeenCalledWith(+ expect.objectContaining({+ user: effectiveUser,+ }),+ );+ });});describe('reinitMCPServer (via reconnectServer)', () => {diff --git a/api/server/services/OboTokenService.js b/api/server/services/OboTokenService.jsindex 86edf15b5a..fc1a7a45d9 100644--- a/api/server/services/OboTokenService.js+++ b/api/server/services/OboTokenService.js@@ -1,9 +1,14 @@+const crypto = require('node:crypto');const client = require('openid-client');const { logger } = require('@librechat/data-schemas');const { CacheKeys } = require('librechat-data-provider');const {+ createOpenIDOboIdentityTuple,+ getSkewedTokenCacheTtlMs,+ getTokenExpiresAtMs,+ hasUsableTokenExpiry,normalizeExpiresIn,- getTokenCacheTtlMs,+ serializeAuthIdentityTuple,DEFAULT_OAUTH_TOKEN_TTL_SECONDS,} = require('@librechat/api');const { getOpenIdConfig } = require('~/strategies/openidStrategy');@@ -14,7 +19,7 @@ const RETRYABLE_ERROR_CODES = new Set(['ETIMEDOUT', 'ECONNRESET', 'EAI_AGAIN', 'const OBO_RETRY_DELAY_MS = 300;/**- * In-flight OBO exchanges keyed by `${openidId}:${scopes}`.+ * In-flight OBO exchanges keyed by identity tuple, scopes, and upstream assertion hash.** Without coalescing, parallel tool calls that arrive on a cache miss each issue* their own jwt-bearer request to the IdP. Under fan-out, Entra intermittently@@ -64,6 +69,26 @@ function tagOboExchangeError(error, retryable) {return error;}+function createEmptyOboExchangeResponseError() {+ const error = new Error('The identity provider returned no access token for the OBO exchange');+ error.retryable = false;+ error.oboFailureReason = 'empty_exchange_response';+ return error;+}++function sha256(value) {+ return crypto.createHash('sha256').update(value).digest('hex');+}++function buildOboCacheKey({ user, accessToken, scopes, identityContext }) {+ const tuple = createOpenIDOboIdentityTuple({ user, identityContext });+ if (!tuple) {+ return null;+ }++ return [serializeAuthIdentityTuple(tuple), scopes, sha256(accessToken)].join('\x1f');+}+async function delay(ms) {await new Promise((resolve) => setTimeout(resolve, ms));}@@ -98,18 +123,22 @@ async function performOboExchange({ user, accessToken, scopes, config, tokensCac}}+ if (!grantResponse?.access_token) {+ throw createEmptyOboExchangeResponseError();+ }++ const expiresIn = normalizeExpiresIn(grantResponse.expires_in) ?? DEFAULT_OAUTH_TOKEN_TTL_SECONDS;+ const now = Date.now();+ const expiresAt = getTokenExpiresAtMs({ expiresIn, now });const tokenResponse = {access_token: grantResponse.access_token,token_type: 'Bearer',- expires_in: normalizeExpiresIn(grantResponse.expires_in) ?? DEFAULT_OAUTH_TOKEN_TTL_SECONDS,+ expires_in: expiresIn,+ expires_at: expiresAt,scope: scopes,};- await tokensCache.set(- cacheKey,- tokenResponse,- getTokenCacheTtlMs(grantResponse.expires_in, DEFAULT_OAUTH_TOKEN_TTL_SECONDS),- );+ await tokensCache.set(cacheKey, tokenResponse, getSkewedTokenCacheTtlMs(expiresAt, now));logger.debug(`[OboTokenService] Successfully obtained and cached OBO token for user: ${user.openidId}`,@@ -121,7 +150,7 @@ async function performOboExchange({ user, accessToken, scopes, config, tokensCac* Exchange a user's access token for a downstream-scoped token via the* OAuth 2.0 On-Behalf-Of (jwt-bearer) grant.*- * Concurrent callers for the same `${openidId}:${scopes}` key share a single+ * Concurrent callers for the same identity/scopes/assertion key share a single* upstream exchange (see `inFlightExchanges`) so a fan-out of tool calls right* after a cache miss does not produce N parallel requests to the IdP.*@@ -130,13 +159,11 @@ async function performOboExchange({ user, accessToken, scopes, config, tokensCac* @param {string} scopes - Scopes to request for the downstream service* @param {boolean} [fromCache=true] - When true, read from cache and join any* in-flight exchange. When false, bypass both and force a fresh exchange.+ * @param {import('@librechat/api').AuthIdentityContext} [identityContext] - Real request identity+ * context used to scope OBO cache keys without exposing tenant/issuer placeholders.* @returns {Promise<Object>} Token response with access_token and expires_in*/-async function exchangeOboToken(user, accessToken, scopes, fromCache = true) {- if (!user.openidId) {- throw new Error('User must be authenticated via OpenID to perform OBO token exchange');- }-+async function exchangeOboToken(user, accessToken, scopes, fromCache = true, identityContext) {if (!accessToken) {throw new Error('Access token is required for OBO exchange');}@@ -150,14 +177,27 @@ async function exchangeOboToken(user, accessToken, scopes, fromCache = true) {throw new Error('OpenID configuration not available');}- const cacheKey = `${user.openidId}:${scopes}`;+ const cacheKey = buildOboCacheKey({+ user,+ accessToken,+ scopes,+ identityContext,+ });+ if (!cacheKey) {+ throw new Error('User must be authenticated via OpenID to perform OBO token exchange');+ }const tokensCache = getLogStores(CacheKeys.OPENID_EXCHANGED_TOKENS);if (fromCache) {const cachedToken = await tokensCache.get(cacheKey);if (cachedToken) {- logger.debug(`[OboTokenService] Using cached token for user: ${user.openidId}`);- return cachedToken;+ if (hasUsableTokenExpiry(cachedToken.expires_at)) {+ logger.debug(`[OboTokenService] Using cached token for user: ${user.openidId}`);+ return cachedToken;+ }+ logger.debug(+ `[OboTokenService] Ignoring cached OBO token without usable expiry for user: ${user.openidId}`,+ );}const inFlight = inFlightExchanges.get(cacheKey);@@ -200,4 +240,7 @@ async function exchangeOboToken(user, accessToken, scopes, fromCache = true) {module.exports = {exchangeOboToken,+ __internals: {+ buildOboCacheKey,+ },};diff --git a/api/server/services/OboTokenService.spec.js b/api/server/services/OboTokenService.spec.jsindex 122ddee4b2..f08eef4405 100644--- a/api/server/services/OboTokenService.spec.js+++ b/api/server/services/OboTokenService.spec.js@@ -12,7 +12,7 @@ jest.mock('@librechat/data-schemas', () => ({const client = require('openid-client');const { getOpenIdConfig } = require('~/strategies/openidStrategy');const getLogStores = require('~/cache/getLogStores');-const { exchangeOboToken } = require('./OboTokenService');+const { exchangeOboToken, __internals } = require('./OboTokenService');describe('OboTokenService', () => {let mockTokensCache;@@ -20,10 +20,15 @@ describe('OboTokenService', () => {const mockUser = {openidId: 'oidc-sub-123',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-a.example.com',email: '[email protected]',name: 'Test User',};+ const expectedCacheKey = (user, accessToken, scopes, identityContext) =>+ __internals.buildOboCacheKey({ user, accessToken, scopes, identityContext });+beforeEach(() => {jest.clearAllMocks();@@ -79,6 +84,7 @@ describe('OboTokenService', () => {access_token: 'cached-obo-token',token_type: 'Bearer',expires_in: 1800,+ expires_at: Date.now() + 1800 * 1000,scope: 'api://mcp-server/Scope.Read',};mockTokensCache.get.mockResolvedValue(cachedToken);@@ -91,10 +97,33 @@ describe('OboTokenService', () => {);expect(result).toBe(cachedToken);- expect(mockTokensCache.get).toHaveBeenCalledWith('oidc-sub-123:api://mcp-server/Scope.Read');+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token', 'api://mcp-server/Scope.Read'),+ );expect(client.genericGrantRequest).not.toHaveBeenCalled();});+ it('should ignore legacy cached tokens without absolute expiry', async () => {+ const cachedToken = {+ access_token: 'cached-obo-token',+ token_type: 'Bearer',+ expires_in: 1800,+ scope: 'api://mcp-server/Scope.Read',+ };+ mockTokensCache.get.mockResolvedValue(cachedToken);++ const result = await exchangeOboToken(+ mockUser,+ 'access-token',+ 'api://mcp-server/Scope.Read',+ true,+ );++ expect(result.access_token).toBe('exchanged-obo-token');+ expect(client.genericGrantRequest).toHaveBeenCalledTimes(1);+ expect(mockTokensCache.set).toHaveBeenCalledTimes(1);+ });+it('should skip cache when fromCache is false', async () => {const cachedToken = { access_token: 'cached-obo-token' };mockTokensCache.get.mockResolvedValue(cachedToken);@@ -116,7 +145,9 @@ describe('OboTokenService', () => {await exchangeOboToken(mockUser, 'access-token', 'api://scope');- expect(mockTokensCache.get).toHaveBeenCalledWith('oidc-sub-123:api://scope');+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token', 'api://scope'),+ );});});@@ -146,11 +177,12 @@ describe('OboTokenService', () => {access_token: 'exchanged-obo-token',token_type: 'Bearer',expires_in: 3600,+ expires_at: expect.any(Number),scope: 'api://mcp-server/Tools.ReadWrite',});});- it('should cache the exchanged token with correct TTL', async () => {+ it('should cache the exchanged token with a skewed TTL', async () => {client.genericGrantRequest.mockResolvedValue({access_token: 'new-obo-token',expires_in: 1800,@@ -159,14 +191,15 @@ describe('OboTokenService', () => {await exchangeOboToken(mockUser, 'access-token', 'api://scope');expect(mockTokensCache.set).toHaveBeenCalledWith(- 'oidc-sub-123:api://scope',+ expectedCacheKey(mockUser, 'access-token', 'api://scope'),{access_token: 'new-obo-token',token_type: 'Bearer',expires_in: 1800,+ expires_at: expect.any(Number),scope: 'api://scope',},- 1800 * 1000,+ 1770 * 1000,);});@@ -179,9 +212,37 @@ describe('OboTokenService', () => {expect(result.expires_in).toBe(3600);expect(mockTokensCache.set).toHaveBeenCalledWith(- 'oidc-sub-123:api://scope',+ expectedCacheKey(mockUser, 'access-token', 'api://scope'),expect.objectContaining({ expires_in: 3600 }),- 3600 * 1000,+ 3570 * 1000,+ );+ });++ it('should not cache an exchange response without access_token', async () => {+ client.genericGrantRequest.mockResolvedValue({+ expires_in: 3600,+ });++ await expect(exchangeOboToken(mockUser, 'access-token', 'api://scope')).rejects.toThrow(+ 'The identity provider returned no access token for the OBO exchange',+ );++ expect(mockTokensCache.set).not.toHaveBeenCalled();+ });++ it('should keep a positive TTL for very short-lived tokens', async () => {+ client.genericGrantRequest.mockResolvedValue({+ access_token: 'short-lived-token',+ expires_in: 10,+ });++ const result = await exchangeOboToken(mockUser, 'access-token', 'api://scope');++ expect(result.expires_in).toBe(10);+ expect(mockTokensCache.set).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token', 'api://scope'),+ expect.objectContaining({ access_token: 'short-lived-token', expires_in: 10 }),+ 1000,);});@@ -215,6 +276,7 @@ describe('OboTokenService', () => {access_token: 'retried-obo-token',token_type: 'Bearer',expires_in: 1800,+ expires_at: expect.any(Number),scope: 'api://scope',});} finally {@@ -237,12 +299,23 @@ describe('OboTokenService', () => {});describe('cache key isolation', () => {+ it('does not include the raw upstream assertion in cache keys', async () => {+ await exchangeOboToken(mockUser, 'sensitive-access-token', 'api://scope');++ expect(mockTokensCache.get.mock.calls[0][0]).not.toContain('sensitive-access-token');+ expect(mockTokensCache.set.mock.calls[0][0]).not.toContain('sensitive-access-token');+ });+it('should use different cache keys for different scopes', async () => {await exchangeOboToken(mockUser, 'access-token', 'api://server-a/Scope.A');await exchangeOboToken(mockUser, 'access-token', 'api://server-b/Scope.B');- expect(mockTokensCache.get).toHaveBeenCalledWith('oidc-sub-123:api://server-a/Scope.A');- expect(mockTokensCache.get).toHaveBeenCalledWith('oidc-sub-123:api://server-b/Scope.B');+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token', 'api://server-a/Scope.A'),+ );+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token', 'api://server-b/Scope.B'),+ );});it('should use different cache keys for different users', async () => {@@ -251,8 +324,88 @@ describe('OboTokenService', () => {await exchangeOboToken(mockUser, 'access-token', 'api://scope');await exchangeOboToken(otherUser, 'access-token', 'api://scope');- expect(mockTokensCache.get).toHaveBeenCalledWith('oidc-sub-123:api://scope');- expect(mockTokensCache.get).toHaveBeenCalledWith('oidc-sub-456:api://scope');+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token', 'api://scope'),+ );+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(otherUser, 'access-token', 'api://scope'),+ );+ });++ it('should use different cache keys for different tenants with the same OpenID subject', async () => {+ const identityA = {+ openidSubject: 'shared-sub',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer.example.com',+ };+ const identityB = {+ openidSubject: 'shared-sub',+ tenantId: 'tenant-b',+ openidIssuer: 'https://issuer.example.com',+ };+ const safeUser = { openidId: 'shared-sub', email: '[email protected]' };++ await exchangeOboToken(safeUser, 'access-token', 'api://scope', true, identityA);+ await exchangeOboToken(safeUser, 'access-token', 'api://scope', true, identityB);++ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(safeUser, 'access-token', 'api://scope', identityA),+ );+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(safeUser, 'access-token', 'api://scope', identityB),+ );+ });++ it('should use identity context when the forwarded user lacks OpenID fields', async () => {+ const identityContext = {+ openidSubject: 'context-sub',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer.example.com',+ };+ const safeUser = { id: 'safe-user-id', email: '[email protected]' };++ await exchangeOboToken(safeUser, 'access-token', 'api://scope', true, identityContext);++ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(safeUser, 'access-token', 'api://scope', identityContext),+ );+ expect(client.genericGrantRequest).toHaveBeenCalledTimes(1);+ });++ it('should use different cache keys for different issuers with the same OpenID subject', async () => {+ const identityA = {+ openidSubject: 'shared-sub',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-a.example.com',+ };+ const identityB = {+ openidSubject: 'shared-sub',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-b.example.com',+ };+ const safeUser = { openidId: 'shared-sub', email: '[email protected]' };++ await exchangeOboToken(safeUser, 'access-token', 'api://scope', true, identityA);+ await exchangeOboToken(safeUser, 'access-token', 'api://scope', true, identityB);++ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(safeUser, 'access-token', 'api://scope', identityA),+ );+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(safeUser, 'access-token', 'api://scope', identityB),+ );+ });++ it('should use different cache keys when the upstream assertion rotates', async () => {+ await exchangeOboToken(mockUser, 'access-token-old', 'api://scope');+ await exchangeOboToken(mockUser, 'access-token-new', 'api://scope');++ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token-old', 'api://scope'),+ );+ expect(mockTokensCache.get).toHaveBeenCalledWith(+ expectedCacheKey(mockUser, 'access-token-new', 'api://scope'),+ );});});@@ -292,6 +445,15 @@ describe('OboTokenService', () => {expect(client.genericGrantRequest).toHaveBeenCalledTimes(2);});+ it('does not coalesce exchanges for rotated upstream assertions', async () => {+ await Promise.all([+ exchangeOboToken(mockUser, 'access-token-old', 'api://scope'),+ exchangeOboToken(mockUser, 'access-token-new', 'api://scope'),+ ]);++ expect(client.genericGrantRequest).toHaveBeenCalledTimes(2);+ });+it('clears the in-flight slot after a successful exchange', async () => {await exchangeOboToken(mockUser, 'access-token', 'api://scope');expect(client.genericGrantRequest).toHaveBeenCalledTimes(1);diff --git a/api/server/services/OpenIDRefreshFlight.js b/api/server/services/OpenIDRefreshFlight.jsnew file mode 100644index 0000000000..691833d85c--- /dev/null+++ b/api/server/services/OpenIDRefreshFlight.js@@ -0,0 +1,10 @@+const { createOpenIDRefreshFlightService } = require('@librechat/api');+const { logger, encryptV2, decryptV2 } = require('@librechat/data-schemas');+const db = require('~/models');++module.exports = createOpenIDRefreshFlightService({+ db,+ logger,+ encrypt: encryptV2,+ decrypt: decryptV2,+});diff --git a/api/server/services/OpenIDRefreshFlight.spec.js b/api/server/services/OpenIDRefreshFlight.spec.jsnew file mode 100644index 0000000000..b19ac1753f--- /dev/null+++ b/api/server/services/OpenIDRefreshFlight.spec.js@@ -0,0 +1,640 @@+jest.mock('@librechat/data-schemas', () => ({+ logger: {+ warn: jest.fn(),+ },+ encryptV2: jest.fn(async (value) => `encrypted:${value}`),+ decryptV2: jest.fn(async (value) => value.replace(/^encrypted:/, '')),+}));++jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),+ createOpenIDRefreshIdentityTuple: ({ user, requestUser }) => {+ const subject = user?.openidId || user?.id || requestUser?.openidId || requestUser?.id;+ if (!subject) {+ return null;+ }+ return {+ tenantId: user?.tenantId || requestUser?.tenantId || 'no-tenant',+ openidIssuer: user?.openidIssuer || requestUser?.openidIssuer || 'no-issuer',+ subject,+ };+ },+ serializeAuthIdentityTuple: ({ tenantId, openidIssuer, subject }) =>+ [tenantId, openidIssuer, subject].join('\x1f'),+}));++jest.mock('~/models', () => ({+ acquireOpenIDRefreshFlight: jest.fn(),+ claimOpenIDRefreshFlightDelivery: jest.fn(),+ completeOpenIDRefreshFlight: jest.fn(),+ failOpenIDRefreshFlight: jest.fn(),+ findOpenIDRefreshFlight: jest.fn(),+ revokeOpenIDRefreshFlight: jest.fn(),+ renewOpenIDRefreshFlight: jest.fn(),+ releaseOpenIDRefreshFlightDelivery: jest.fn(),+}));++const { encryptV2, decryptV2 } = require('@librechat/data-schemas');+const db = require('~/models');+const {+ acquireOpenIDRefreshFlight,+ assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshFlightDeliveryAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ claimOpenIDRefreshFlightDelivery,+ completeOpenIDRefreshFlight,+ createOpenIDRefreshFlightKey,+ failOpenIDRefreshFlight,+ renewOpenIDRefreshFlight,+ releaseOpenIDRefreshFlightDelivery,+ revokeOpenIDRefreshFlights,+ waitForOpenIDRefreshFlight,+ withOpenIDRefreshFlightLease,+ __internals,+} = require('./OpenIDRefreshFlight');++describe('OpenIDRefreshFlight', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ db.acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: true, flight: null });+ db.claimOpenIDRefreshFlightDelivery.mockResolvedValue({+ status: 'completed',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ });+ db.completeOpenIDRefreshFlight.mockResolvedValue({});+ db.failOpenIDRefreshFlight.mockResolvedValue({});+ db.findOpenIDRefreshFlight.mockResolvedValue(null);+ db.renewOpenIDRefreshFlight.mockResolvedValue({ ownerId: 'owner-1', status: 'pending' });+ db.releaseOpenIDRefreshFlightDelivery.mockResolvedValue({ status: 'completed' });+ db.revokeOpenIDRefreshFlight.mockResolvedValue({ status: 'revoked' });+ });++ it('creates a stable hash key from session, user, issuer, tenant, and refresh token', () => {+ const req = {+ sessionID: 'session-1',+ user: { tenantId: 'tenant-1', openidIssuer: 'issuer-1' },+ };+ const user = { openidId: 'oidc-sub-1' };++ const keyA = createOpenIDRefreshFlightKey({ req, user, refreshToken: 'rt-old' });+ const keyB = createOpenIDRefreshFlightKey({ req, user, refreshToken: 'rt-old' });+ const keyC = createOpenIDRefreshFlightKey({ req, user, refreshToken: 'rt-other' });+ const keyFromNewSession = createOpenIDRefreshFlightKey({+ req: { ...req, sessionID: 'session-2' },+ user,+ refreshToken: 'rt-old',+ });++ expect(keyA).toBe(keyB);+ expect(keyA).toBe(keyFromNewSession);+ expect(keyA).not.toBe(keyC);+ expect(keyA).not.toContain('rt-old');+ });++ it('allows follower publication only while the completed flight remains available', async () => {+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({ status: 'completed', ownerId: 'owner-1' });++ await expect(+ assertOpenIDRefreshFlightAvailable({ key: 'flight-key', ownerId: 'owner-1' }),+ ).resolves.toMatchObject({ status: 'completed' });++ db.findOpenIDRefreshFlight.mockResolvedValueOnce({ status: 'completed', ownerId: 'owner-2' });+ await expect(+ assertOpenIDRefreshFlightAvailable({ key: 'flight-key', ownerId: 'owner-1' }),+ ).rejects.toMatchObject({ code: 'OPENID_REFRESH_OWNERSHIP_LOST' });+ });++ it('rejects tombstoned or replaced session generations but permits expired records', async () => {+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({ status: 'revoked', ownerId: 'owner-1' });+ await expect(+ assertOpenIDRefreshSessionGenerationAvailable({ key: 'flight-key', ownerId: 'owner-1' }),+ ).rejects.toMatchObject({ code: 'OPENID_REFRESH_OWNERSHIP_LOST' });++ db.findOpenIDRefreshFlight.mockResolvedValueOnce({ status: 'completed', ownerId: 'owner-2' });+ await expect(+ assertOpenIDRefreshSessionGenerationAvailable({ key: 'flight-key', ownerId: 'owner-1' }),+ ).rejects.toMatchObject({ code: 'OPENID_REFRESH_OWNERSHIP_LOST' });++ db.findOpenIDRefreshFlight.mockResolvedValueOnce(null);+ await expect(+ assertOpenIDRefreshSessionGenerationAvailable({ key: 'flight-key', ownerId: 'owner-1' }),+ ).resolves.toBe(true);+ });++ it('claims and releases a durable response-delivery lease for the exact generation', async () => {+ const createdAt = Date.now() - 1000;+ const claimed = await claimOpenIDRefreshFlightDelivery({+ key: 'flight-key',+ ownerId: 'owner-1',+ createdAt,+ deliveryId: 'delivery-1',+ ttl: 5000,+ });++ expect(claimed.deliveryId).toBe('delivery-1');+ expect(db.claimOpenIDRefreshFlightDelivery).toHaveBeenCalledWith({+ key: 'flight-key',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ deliveryExpiresAt: expect.any(Date),+ createdAt: new Date(createdAt),+ });++ await releaseOpenIDRefreshFlightDelivery({+ key: 'flight-key',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ });+ expect(db.releaseOpenIDRefreshFlightDelivery).toHaveBeenCalledWith({+ key: 'flight-key',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ });+ });++ it('retries an expired synthetic generation when its previous delivery releases between reads', async () => {+ db.claimOpenIDRefreshFlightDelivery.mockResolvedValueOnce(null).mockResolvedValueOnce({+ status: 'completed',+ ownerId: 'owner-1',+ deliveryId: 'delivery-2',+ });+ db.findOpenIDRefreshFlight.mockResolvedValueOnce(null);++ await expect(+ claimOpenIDRefreshFlightDelivery({+ key: 'flight-key',+ ownerId: 'owner-1',+ createdAt: Date.now() - 1000,+ deliveryId: 'delivery-2',+ ttl: 1000,+ }),+ ).resolves.toMatchObject({ deliveryId: 'delivery-2' });+ expect(db.claimOpenIDRefreshFlightDelivery).toHaveBeenCalledTimes(2);+ });++ it('authorizes only the active, unrevoked response-delivery lease', async () => {+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({+ status: 'completed',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ deliveryExpiresAt: new Date(Date.now() + 5000),+ });+ await expect(+ assertOpenIDRefreshFlightDeliveryAvailable({+ key: 'flight-key',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ }),+ ).resolves.toBeUndefined();++ db.findOpenIDRefreshFlight.mockResolvedValueOnce({+ status: 'completed',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ deliveryExpiresAt: new Date(Date.now() + 5000),+ revocationRequestedAt: new Date(),+ });+ await expect(+ assertOpenIDRefreshFlightDeliveryAvailable({+ key: 'flight-key',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ }),+ ).rejects.toMatchObject({ code: 'OPENID_REFRESH_OWNERSHIP_LOST' });+ });++ it('uses explicit identity context when safe user lacks tenant and issuer', () => {+ const req = {+ sessionID: 'session-1',+ user: { id: 'safe-user' },+ };+ const user = { id: 'safe-user' };++ const keyA = createOpenIDRefreshFlightKey({+ req,+ user,+ refreshToken: 'rt-old',+ identityContext: {+ openidSubject: 'oidc-sub-1',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-a.example.com',+ },+ });+ const keyB = createOpenIDRefreshFlightKey({+ req,+ user,+ refreshToken: 'rt-old',+ identityContext: {+ openidSubject: 'oidc-sub-1',+ tenantId: 'tenant-b',+ openidIssuer: 'https://issuer-a.example.com',+ },+ });++ expect(keyA).not.toBe(keyB);+ });++ it('returns null key when identity or refresh token is unavailable', () => {+ expect(createOpenIDRefreshFlightKey({ req: {}, user: {}, refreshToken: 'rt' })).toBeNull();+ expect(+ createOpenIDRefreshFlightKey({+ req: { user: { id: 'user-1' } },+ user: undefined,+ refreshToken: undefined,+ }),+ ).toBeNull();+ });++ it('acquires a Mongo flight with owner and expiry metadata', async () => {+ const result = await acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ ttl: 60000,+ lockTtl: 30000,+ });++ expect(result.acquired).toBe(true);+ expect(result.key).toBe('flight-key');+ expect(result.ownerId).toBe('owner-1');+ expect(db.acquireOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: expect.any(Date),+ expiresAt: expect.any(Date),+ });+ });++ it('renews only the owning pending flight lease', async () => {+ await renewOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockTtl: 30000,+ ttl: 60000,+ });++ expect(db.renewOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: expect.any(Date),+ expiresAt: expect.any(Date),+ });+ });++ it('keeps renewing a leader lease until its refresh operation settles', async () => {+ jest.useFakeTimers();+ let resolveOperation;+ const operation = jest.fn(+ () =>+ new Promise((resolve) => {+ resolveOperation = resolve;+ }),+ );++ try {+ const resultPromise = withOpenIDRefreshFlightLease({+ key: 'flight-key',+ ownerId: 'owner-1',+ heartbeatInterval: 1000,+ lockTtl: 30000,+ ttl: 60000,+ operation,+ });++ await jest.advanceTimersByTimeAsync(1000);+ expect(db.renewOpenIDRefreshFlight).toHaveBeenCalledTimes(1);++ resolveOperation('tokens');+ await expect(resultPromise).resolves.toBe('tokens');++ await jest.advanceTimersByTimeAsync(2000);+ expect(db.renewOpenIDRefreshFlight).toHaveBeenCalledTimes(1);+ } finally {+ jest.useRealTimers();+ }+ });++ it('rejects a stale owner after the heartbeat observes lease loss', async () => {+ jest.useFakeTimers();+ db.renewOpenIDRefreshFlight.mockResolvedValueOnce(null);+ let finishOperation;+ const operation = jest.fn(+ () =>+ new Promise((resolve) => {+ finishOperation = resolve;+ }),+ );++ try {+ const resultPromise = withOpenIDRefreshFlightLease({+ key: 'flight-key',+ ownerId: 'owner-1',+ heartbeatInterval: 1000,+ operation,+ });++ await jest.advanceTimersByTimeAsync(1000);+ finishOperation('tokens');+ await expect(resultPromise).rejects.toThrow('ownership was lost');+ } finally {+ jest.useRealTimers();+ }+ });++ it("does not treat the owner's completed flight as heartbeat lease loss", async () => {+ jest.useFakeTimers();+ db.renewOpenIDRefreshFlight.mockResolvedValueOnce(null);+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({+ ownerId: 'owner-1',+ status: 'completed',+ });+ let finishOperation;+ const operation = jest.fn(+ () =>+ new Promise((resolve) => {+ finishOperation = resolve;+ }),+ );++ try {+ const resultPromise = withOpenIDRefreshFlightLease({+ key: 'flight-key',+ ownerId: 'owner-1',+ heartbeatInterval: 1000,+ operation,+ });++ await jest.advanceTimersByTimeAsync(1000);+ finishOperation('tokens');+ await expect(resultPromise).resolves.toBe('tokens');+ expect(db.findOpenIDRefreshFlight).toHaveBeenCalledWith({ key: 'flight-key' });+ } finally {+ jest.useRealTimers();+ }+ });++ it('does not let a trailing renewal failure replace a completed result', async () => {+ jest.useFakeTimers();+ let rejectRenewal;+ db.renewOpenIDRefreshFlight.mockReturnValueOnce(+ new Promise((_resolve, reject) => {+ rejectRenewal = reject;+ }),+ );+ let finishOperation;+ const operation = jest.fn(+ ({ markLeaseSettled }) =>+ new Promise((resolve) => {+ finishOperation = (value) => {+ markLeaseSettled();+ resolve(value);+ };+ }),+ );++ try {+ const resultPromise = withOpenIDRefreshFlightLease({+ key: 'flight-key',+ ownerId: 'owner-1',+ heartbeatInterval: 1000,+ operation,+ });++ /** Heartbeat issues a renewal that is still in flight when the operation finishes. */+ await jest.advanceTimersByTimeAsync(1000);+ finishOperation('tokens');+ rejectRenewal(new Error('connection timed out'));++ await expect(resultPromise).resolves.toBe('tokens');+ } finally {+ jest.useRealTimers();+ }+ });++ it('encrypts completed token results before storing them', async () => {+ const tokens = {+ access_token: 'access',+ id_token: 'id',+ refresh_token: 'refresh',+ expires_at: 123,+ appAuthToken: 'app-auth-token',+ __identityClaims: { sub: 'user-123', iss: 'https://issuer.example.com' },+ };++ await completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ tokens,+ ttl: 60000,+ });++ expect(encryptV2).toHaveBeenCalledWith(JSON.stringify(tokens));+ expect(db.completeOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight-key',+ ownerId: 'owner-1',+ encryptedResult: `encrypted:${JSON.stringify(tokens)}`,+ expiresAt: expect.any(Date),+ });+ });++ it('expires a completed flight at the access token usable-lifetime boundary', async () => {+ const now = Date.now();+ jest.spyOn(Date, 'now').mockReturnValue(now);+ const tokens = {+ access_token: 'short-access',+ expires_at: Math.floor(now / 1000) + 45,+ };++ await completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ tokens,+ ttl: 60000,+ });++ const storedExpiry = db.completeOpenIDRefreshFlight.mock.calls[0][0].expiresAt;+ expect(storedExpiry.getTime()).toBeLessThanOrEqual(now + 15_000);+ expect(storedExpiry.getTime()).toBeGreaterThan(now);+ Date.now.mockRestore();+ });++ it('preserves non-enumerable publication metadata for shared flight joiners', async () => {+ const tokens = {+ access_token: 'access',+ refresh_token: 'refresh',+ expires_at: 123,+ };+ Object.defineProperty(tokens, '__browserRefreshToken', {+ value: 'browser-refresh',+ enumerable: false,+ });+ Object.defineProperty(tokens, '__predecessorRefreshToken', {+ value: 'predecessor-refresh',+ enumerable: false,+ });+ Object.defineProperty(tokens, '__predecessorAccessToken', {+ value: 'predecessor-access',+ enumerable: false,+ });+ Object.defineProperty(tokens, '__deferredPublication', {+ value: true,+ enumerable: false,+ });++ await completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ tokens,+ ttl: 60000,+ });++ const serializedTokens = JSON.parse(encryptV2.mock.calls[0][0]);+ expect(serializedTokens.__browserRefreshToken).toBe('browser-refresh');+ expect(serializedTokens.__predecessorRefreshToken).toBe('predecessor-refresh');+ expect(serializedTokens.__predecessorAccessToken).toBe('predecessor-access');+ expect(serializedTokens.__deferredPublication).toBe(true);+ expect(Object.keys(tokens)).not.toContain('__browserRefreshToken');+ });++ it('marks a flight failed with a non-sensitive message', async () => {+ await failOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ error: new Error('invalid_grant'),+ ttl: 60000,+ });++ expect(db.failOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight-key',+ ownerId: 'owner-1',+ errorMessage: 'invalid_grant',+ expiresAt: expect.any(Date),+ });+ });++ it('persists logout revocation fences for every distinct flight key', async () => {+ await revokeOpenIDRefreshFlights({+ keys: ['flight-a', 'flight-b', 'flight-a', null],+ ttl: 60000,+ });++ expect(db.revokeOpenIDRefreshFlight).toHaveBeenCalledTimes(2);+ expect(db.revokeOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight-a',+ expiresAt: expect.any(Date),+ });+ expect(db.revokeOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight-b',+ expiresAt: expect.any(Date),+ });+ });++ it('returns the retained successor from a completed flight during revocation', async () => {+ const result = {+ tokenset: { access_token: 'access', refresh_token: 'successor' },+ claims: { sub: 'subject' },+ appAuthToken: 'app-token',+ };+ db.revokeOpenIDRefreshFlight.mockResolvedValueOnce({+ status: 'revoked',+ encryptedResult: `encrypted:${JSON.stringify(result)}`,+ });++ await expect(revokeOpenIDRefreshFlights({ keys: ['flight-a'] })).resolves.toEqual([result]);+ });++ it('waits for and decrypts a completed flight result', async () => {+ const tokens = {+ access_token: 'access',+ refresh_token: 'refresh',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ };+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({+ status: 'completed',+ encryptedResult: `encrypted:${JSON.stringify(tokens)}`,+ });++ const result = await waitForOpenIDRefreshFlight({+ key: 'flight-key',+ timeoutMs: 1,+ intervalMs: 1,+ });++ expect(decryptV2).toHaveBeenCalledWith(`encrypted:${JSON.stringify(tokens)}`);+ expect(result).toEqual(tokens);+ });++ it('throws when another worker records a failed flight', async () => {+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({+ status: 'failed',+ errorMessage: 'invalid_grant',+ });++ await expect(+ waitForOpenIDRefreshFlight({ key: 'flight-key', timeoutMs: 1, intervalMs: 1 }),+ ).rejects.toThrow('invalid_grant');+ });++ it('throws when logout revokes the flight', async () => {+ db.findOpenIDRefreshFlight.mockResolvedValueOnce({+ status: 'revoked',+ errorMessage: 'OpenID refresh was revoked by logout',+ });++ await expect(+ waitForOpenIDRefreshFlight({ key: 'flight-key', timeoutMs: 1, intervalMs: 1 }),+ ).rejects.toThrow('revoked by logout');+ });++ it('waits for the full renewable-flight lifetime by default', () => {+ expect(__internals.DEFAULT_WAIT_TIMEOUT_MS).toBe(__internals.DEFAULT_FLIGHT_TTL_MS);+ expect(__internals.DEFAULT_WAIT_TIMEOUT_MS).toBeGreaterThan(__internals.DEFAULT_LOCK_TTL_MS);+ const initialDeadline = Date.now() + __internals.DEFAULT_WAIT_TIMEOUT_MS;+ const renewedExpiry = new Date(initialDeadline + 60_000);+ expect(__internals.getRenewedWaitDeadline(initialDeadline, { expiresAt: renewedExpiry })).toBe(+ renewedExpiry.getTime(),+ );+ });++ it('does not reuse a completed result inside the access-token expiry buffer', async () => {+ const tokens = {+ access_token: 'near-expiry',+ expires_at: Math.floor(Date.now() / 1000) + 10,+ };+ await expect(+ __internals.readCompletedFlight({+ status: 'completed',+ encryptedResult: `encrypted:${JSON.stringify(tokens)}`,+ }),+ ).resolves.toBeNull();+ });++ it('exposes completed-flight parsing for focused tests', async () => {+ const tokens = { access_token: 'access' };+ await expect(+ __internals.readCompletedFlight({+ status: 'completed',+ encryptedResult: `encrypted:${JSON.stringify(tokens)}`,+ }),+ ).resolves.toEqual(tokens);+ });++ it('restores publication metadata as non-enumerable', async () => {+ const createdAt = new Date('2026-08-29T12:00:00.000Z');+ const result = await __internals.readCompletedFlight({+ status: 'completed',+ ownerId: 'generation-owner',+ createdAt,+ encryptedResult:+ 'encrypted:{"access_token":"access","__browserRefreshToken":"browser-refresh","__predecessorRefreshToken":"predecessor-refresh","__predecessorAccessToken":"predecessor-access","__deferredPublication":true}',+ });++ expect(result.__browserRefreshToken).toBe('browser-refresh');+ expect(result.__predecessorRefreshToken).toBe('predecessor-refresh');+ expect(result.__predecessorAccessToken).toBe('predecessor-access');+ expect(result.__deferredPublication).toBe(true);+ expect(result.__flightOwnerId).toBe('generation-owner');+ expect(result.__flightCreatedAt).toBe(createdAt.getTime());+ expect(Object.keys(result)).toEqual(['access_token']);+ });+});diff --git a/api/server/services/OpenIDRefreshRecovery.js b/api/server/services/OpenIDRefreshRecovery.jsnew file mode 100644index 0000000000..a041e27336--- /dev/null+++ b/api/server/services/OpenIDRefreshRecovery.js@@ -0,0 +1,45 @@+const jwt = require('jsonwebtoken');+const api = require('@librechat/api');+const { logger } = require('@librechat/data-schemas');+const { deleteSession, findUser } = require('~/models');+const { getOpenIdConfig, getOpenIdEmail } = require('~/strategies');+const {+ clearOpenIDAuthTokens,+ getOpenIDAppAuthToken,+ setOpenIDAuthTokens,+ storeOpenIDSession,+} = require('./AuthService');+const bridge = require('./RefreshTokenBridge');+const flight = require('./OpenIDRefreshFlight');+const { refreshOpenIDSession } = require('./OpenIDSessionRefresh');++module.exports = api.createOpenIDRefreshRecoveryService({+ jwt,+ logger,+ findOpenIDUser: api.findOpenIDUser,+ findUser,+ getOpenIdConfig,+ getOpenIdEmail,+ getOpenIdIssuer: api.getOpenIdIssuer,+ createAuthIdentityContext: api.createAuthIdentityContext,+ refreshOpenIDSession,+ storeOpenIDSession,+ setOpenIDAuthTokens,+ clearOpenIDAuthTokens,+ getOpenIDAppAuthToken,+ deleteOpenIDSession: (refreshToken) => deleteSession({ refreshToken }),+ createRefreshTokenBridgeFlightKey: bridge.createRefreshTokenBridgeFlightKey,+ createOpenIDRefreshFlightKey: flight.createOpenIDRefreshFlightKey,+ storeRefreshTokenBridge: bridge.storeRefreshTokenBridge,+ deleteRefreshTokenBridges: bridge.deleteRefreshTokenBridges,+ acquireOpenIDRefreshFlight: flight.acquireOpenIDRefreshFlight,+ completeOpenIDRefreshFlight: flight.completeOpenIDRefreshFlight,+ failOpenIDRefreshFlight: flight.failOpenIDRefreshFlight,+ waitForOpenIDRefreshFlight: flight.waitForOpenIDRefreshFlight,+ assertOpenIDRefreshFlightAvailable: flight.assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable:+ flight.assertOpenIDRefreshSessionGenerationAvailable,+ revokeOpenIDRefreshFlights: flight.revokeOpenIDRefreshFlights,+ withOpenIDRefreshFlightLease: flight.withOpenIDRefreshFlightLease,+ bridgeGraceMs: bridge.OPENID_REFRESH_BRIDGE_GRACE_MS,+});diff --git a/api/server/services/OpenIDSessionRefresh.js b/api/server/services/OpenIDSessionRefresh.jsnew file mode 100644index 0000000000..297a174a9b--- /dev/null+++ b/api/server/services/OpenIDSessionRefresh.js@@ -0,0 +1,46 @@+const jwt = require('jsonwebtoken');+const cookies = require('cookie');+const crypto = require('node:crypto');+const openIdClient = require('openid-client');+const api = require('@librechat/api');+const { logger, DEFAULT_REFRESH_TOKEN_EXPIRY } = require('@librechat/data-schemas');+const { upsertSession, deleteSession } = require('~/models');+const { getOpenIdConfig } = require('~/strategies/openidStrategy');+const bridge = require('./RefreshTokenBridge');+const flight = require('./OpenIDRefreshFlight');++module.exports = api.createOpenIDSessionRefreshService({+ jwt,+ cookies,+ crypto,+ openIdClient,+ logger,+ defaultRefreshTokenExpiry: DEFAULT_REFRESH_TOKEN_EXPIRY,+ isEnabled: api.isEnabled,+ math: api.math,+ createAuthIdentityContext: api.createAuthIdentityContext,+ isOpenIDSessionIdentityMatch: api.isOpenIDSessionIdentityMatch,+ createOpenIDRefreshIdentityTuple: api.createOpenIDRefreshIdentityTuple,+ createRefreshTokenBridgeIdentity: api.createRefreshTokenBridgeIdentity,+ serializeAuthIdentityTuple: api.serializeAuthIdentityTuple,+ buildOpenIDRefreshParams: api.buildOpenIDRefreshParams,+ setRefreshTokenCookie: api.setRefreshTokenCookie,+ setOpenIDMarkerCookies: api.setOpenIDMarkerCookies,+ storeOpenIdSession: api.storeOpenIdSession,+ normalizeExpiresIn: api.normalizeExpiresIn,+ upsertSession,+ deleteSession,+ getOpenIdConfig,+ OPENID_REFRESH_BRIDGE_GRACE_MS: bridge.OPENID_REFRESH_BRIDGE_GRACE_MS,+ storeRefreshTokenBridge: bridge.storeRefreshTokenBridge,+ deleteRefreshTokenBridges: bridge.deleteRefreshTokenBridges,+ acquireOpenIDRefreshFlight: flight.acquireOpenIDRefreshFlight,+ assertOpenIDRefreshFlightAvailable: flight.assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable:+ flight.assertOpenIDRefreshSessionGenerationAvailable,+ completeOpenIDRefreshFlight: flight.completeOpenIDRefreshFlight,+ createOpenIDRefreshFlightKey: flight.createOpenIDRefreshFlightKey,+ failOpenIDRefreshFlight: flight.failOpenIDRefreshFlight,+ waitForOpenIDRefreshFlight: flight.waitForOpenIDRefreshFlight,+ withOpenIDRefreshFlightLease: flight.withOpenIDRefreshFlightLease,+});diff --git a/api/server/services/OpenIDSessionRefresh.spec.js b/api/server/services/OpenIDSessionRefresh.spec.jsnew file mode 100644index 0000000000..b48061a89d--- /dev/null+++ b/api/server/services/OpenIDSessionRefresh.spec.js@@ -0,0 +1,2495 @@+jest.mock('openid-client', () => ({+ refreshTokenGrant: jest.fn(),+}));+jest.mock('~/strategies/openidStrategy', () => ({+ getOpenIdConfig: jest.fn(),+}));+jest.mock('@librechat/data-schemas', () => ({+ logger: {+ error: jest.fn(),+ debug: jest.fn(),+ warn: jest.fn(),+ info: jest.fn(),+ },+ DEFAULT_REFRESH_TOKEN_EXPIRY: 1000 * 60 * 60 * 24 * 7,+}));+jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),+ isEnabled: jest.fn(),+ math: jest.fn((_value, fallback) => fallback),+ createAuthIdentityContext: jest.fn(({ user, requestUser }) => ({+ appUserId:+ user?._id?.toString?.() ?? user?.id ?? requestUser?._id?.toString?.() ?? requestUser?.id,+ openidSubject: user?.openidId ?? requestUser?.openidId,+ tenantId: user?.tenantId ?? requestUser?.tenantId,+ openidIssuer: user?.openidIssuer ?? requestUser?.openidIssuer,+ })),+ isOpenIDSessionIdentityMatch: jest.fn((sessionIdentity, expectedIdentity) => {+ const normalize = (value) => {+ if (value == null) {+ return undefined;+ }+ const normalized = typeof value === 'string' ? value.trim() : value.toString().trim();+ return normalized || undefined;+ };+ const normalizeIssuer = (value) => normalize(value)?.replace(/\/+$/, '');+ const session = {+ appUserId: normalize(sessionIdentity?.appUserId),+ openidSubject: normalize(sessionIdentity?.openidSubject),+ tenantId: normalize(sessionIdentity?.tenantId),+ openidIssuer: normalizeIssuer(sessionIdentity?.openidIssuer),+ };+ const expected = {+ appUserId: normalize(expectedIdentity?.appUserId),+ openidSubject: normalize(expectedIdentity?.openidSubject),+ tenantId: normalize(expectedIdentity?.tenantId),+ openidIssuer: normalizeIssuer(expectedIdentity?.openidIssuer),+ };+ return (+ Boolean(session.appUserId) &&+ Boolean(session.openidSubject) &&+ session.appUserId === expected.appUserId &&+ session.openidSubject === expected.openidSubject &&+ session.tenantId === expected.tenantId &&+ session.openidIssuer === expected.openidIssuer+ );+ }),+ createOpenIDRefreshIdentityTuple: jest.fn(({ user, requestUser }) => {+ const subject =+ user?.openidId ??+ user?.id ??+ user?._id?.toString?.() ??+ requestUser?.openidId ??+ requestUser?.id ??+ requestUser?._id?.toString?.();+ if (!subject) {+ return null;+ }+ return {+ subject,+ tenantId: user?.tenantId ?? requestUser?.tenantId ?? 'no-tenant',+ openidIssuer: user?.openidIssuer ?? requestUser?.openidIssuer ?? 'no-issuer',+ };+ }),+ serializeAuthIdentityTuple: jest.fn(+ (tuple) => `${tuple.tenantId}\x1f${tuple.openidIssuer}\x1f${tuple.subject}`,+ ),+ createRefreshTokenBridgeIdentity: jest.fn(+ ({ user, requestUser, userId, tenantId, openidIssuer }) => {+ const normalize = (value) => {+ if (value == null) {+ return undefined;+ }+ const normalized = typeof value === 'string' ? value.trim() : value.toString().trim();+ return normalized || undefined;+ };+ const resolvedUserId =+ normalize(userId) ??+ normalize(user?._id) ??+ normalize(user?.id) ??+ normalize(requestUser?._id) ??+ normalize(requestUser?.id);+ if (!resolvedUserId) {+ return null;+ }+ return {+ userId: resolvedUserId,+ tenantId: tenantId ?? user?.tenantId ?? requestUser?.tenantId,+ openidIssuer: openidIssuer ?? user?.openidIssuer ?? requestUser?.openidIssuer,+ };+ },+ ),+ buildOpenIDRefreshParams: jest.fn(() => ({ scope: 'openid profile' })),+ setRefreshTokenCookie: jest.fn((res, refreshToken, expires) => {+ res.cookie('refreshToken', refreshToken, { expires });+ }),+ setOpenIDMarkerCookies: jest.fn((res, { userId, expires }) => {+ res.cookie('token_provider', 'openid', { expires });+ if (userId) {+ res.cookie('openid_user_id', `signed:${userId}`, { expires });+ }+ }),+ normalizeExpiresIn: (value) => {+ const normalized = typeof value === 'string' && value.trim() ? Number(value) : value;+ return typeof normalized === 'number' && Number.isFinite(normalized) ? normalized : undefined;+ },+ storeOpenIdSession: jest.fn(),+}));+jest.mock('~/models', () => ({+ upsertSession: jest.fn(),+ deleteSession: jest.fn(),+}));+jest.mock('./RefreshTokenBridge', () => ({+ OPENID_REFRESH_BRIDGE_GRACE_MS: 60 * 1000,+ storeRefreshTokenBridge: jest.fn(),+ deleteRefreshTokenBridges: jest.fn(),+}));+jest.mock('./OpenIDRefreshFlight', () => ({+ acquireOpenIDRefreshFlight: jest.fn(),+ assertOpenIDRefreshFlightAvailable: jest.fn(),+ assertOpenIDRefreshSessionGenerationAvailable: jest.fn(),+ completeOpenIDRefreshFlight: jest.fn(),+ createOpenIDRefreshFlightKey: jest.fn(),+ failOpenIDRefreshFlight: jest.fn(),+ waitForOpenIDRefreshFlight: jest.fn(),+ withOpenIDRefreshFlightLease: jest.fn(({ operation }) =>+ operation({+ assertLeaseOwned: jest.fn().mockResolvedValue(true),+ markLeaseSettled: jest.fn(),+ }),+ ),+}));++const jwt = require('jsonwebtoken');+const crypto = require('node:crypto');+const openIdClient = require('openid-client');+const {+ isEnabled,+ buildOpenIDRefreshParams,+ setRefreshTokenCookie,+ setOpenIDMarkerCookies,+ storeOpenIdSession,+} = require('@librechat/api');+const { upsertSession, deleteSession } = require('~/models');+const { getOpenIdConfig } = require('~/strategies/openidStrategy');+const { deleteRefreshTokenBridges, storeRefreshTokenBridge } = require('./RefreshTokenBridge');+const {+ acquireOpenIDRefreshFlight,+ assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ completeOpenIDRefreshFlight,+ createOpenIDRefreshFlightKey,+ failOpenIDRefreshFlight,+ waitForOpenIDRefreshFlight,+ withOpenIDRefreshFlightLease,+} = require('./OpenIDRefreshFlight');+const {+ createOpenIDSessionTokenProvider,+ refreshOpenIDSession,+ __internals,+} = require('./OpenIDSessionRefresh');++const SECRET = 'test-secret';++const makeJwt = (exp) => jwt.sign({ sub: 'user-123', exp }, SECRET);++const DEFAULT_SESSION_IDENTITY = {+ appUserId: 'local-id-1',+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+};++const withSessionIdentity = (sessionTokens) =>+ sessionTokens == null ? sessionTokens : { ...DEFAULT_SESSION_IDENTITY, ...sessionTokens };++const buildReq = (sessionTokens, sessionId = 'session-A', { bindIdentity = true } = {}) => ({+ sessionID: sessionId,+ session: Object.assign(+ {+ save: jest.fn((cb) => cb(null)),+ },+ sessionTokens === undefined+ ? {}+ : { openidTokens: bindIdentity ? withSessionIdentity(sessionTokens) : sessionTokens },+ ),+});++/** Minimal writable Express response stub for cookie-sync assertions. */+const buildRes = ({ headersSent = false } = {}) => ({+ headersSent,+ cookie: jest.fn(),+ clearCookie: jest.fn(),+});++const makeOpenIdUser = (overrides = {}) => ({+ id: 'local-id-1',+ openidId: 'oidc-sub-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ provider: 'openid',+ ...overrides,+});++const { createOpenIDRefreshOwnershipError } = jest.requireActual('@librechat/api');+const ownershipLost = (message) => createOpenIDRefreshOwnershipError(message);++describe('OpenIDSessionRefresh', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ __internals.inFlightRefreshes.clear();+ isEnabled.mockReturnValue(true);+ getOpenIdConfig.mockReturnValue({ issuer: 'https://issuer.example.com' });+ openIdClient.refreshTokenGrant.mockReset();+ createOpenIDRefreshFlightKey.mockImplementation(+ ({ req, refreshToken }) => refreshToken && `flight:${req?.sessionID}:${refreshToken}`,+ );+ acquireOpenIDRefreshFlight.mockResolvedValue({ acquired: true, ownerId: 'owner-1' });+ assertOpenIDRefreshFlightAvailable.mockResolvedValue({ status: 'completed' });+ assertOpenIDRefreshSessionGenerationAvailable.mockResolvedValue(true);+ completeOpenIDRefreshFlight.mockResolvedValue({});+ failOpenIDRefreshFlight.mockResolvedValue({});+ waitForOpenIDRefreshFlight.mockResolvedValue(null);+ storeRefreshTokenBridge.mockResolvedValue('bridge-version-1');+ withOpenIDRefreshFlightLease.mockImplementation(({ operation }) =>+ operation({+ assertLeaseOwned: jest.fn().mockResolvedValue(true),+ markLeaseSettled: jest.fn(),+ }),+ );+ });++ describe('createOpenIDSessionTokenProvider closure no-op cases', () => {+ it('throws when tokenPreference is missing', () => {+ expect(() =>+ createOpenIDSessionTokenProvider({+ req: buildReq({ accessToken: makeJwt(Date.now() / 1000 + 600) }),+ user: makeOpenIdUser(),+ }),+ ).toThrow(/tokenPreference/);+ });++ it('throws when tokenPreference is invalid', () => {+ expect(() =>+ createOpenIDSessionTokenProvider({+ req: buildReq({ accessToken: makeJwt(Date.now() / 1000 + 600) }),+ user: makeOpenIdUser(),+ tokenPreference: 'bogus',+ }),+ ).toThrow(/tokenPreference/);+ });++ it('returns null when OPENID_REUSE_TOKENS is disabled', async () => {+ isEnabled.mockReturnValue(false);+ const provider = createOpenIDSessionTokenProvider({+ req: buildReq({ accessToken: makeJwt(Date.now() / 1000 + 600) }),+ user: makeOpenIdUser(),+ tokenPreference: 'access_token',+ });+ await expect(provider()).resolves.toBeNull();+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('returns null when user is non-OpenID', async () => {+ const provider = createOpenIDSessionTokenProvider({+ req: buildReq({ accessToken: makeJwt(Date.now() / 1000 + 600) }),+ user: { id: 'local-1', provider: 'local' },+ tokenPreference: 'access_token',+ });+ await expect(provider()).resolves.toBeNull();+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('returns null when user is missing entirely', async () => {+ const provider = createOpenIDSessionTokenProvider({+ req: buildReq({ accessToken: makeJwt(Date.now() / 1000 + 600) }),+ user: undefined,+ tokenPreference: 'access_token',+ });+ await expect(provider()).resolves.toBeNull();+ });++ it('rejects a stale user token snapshot when an Express session lost its OpenID tokens', async () => {+ const provider = createOpenIDSessionTokenProvider({+ req: buildReq(undefined),+ user: makeOpenIdUser(),+ tokenPreference: 'access_token',+ });+ await expect(provider()).rejects.toMatchObject({+ code: 'OPENID_REFRESH_OWNERSHIP_LOST',+ });+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('allows remote OIDC bearer fallback when the request itself carries the upstream token', async () => {+ const req = buildReq(undefined);+ req.headers = { authorization: 'Bearer remote-access-token' };+ const provider = createOpenIDSessionTokenProvider({+ req,+ user: makeOpenIdUser({+ federatedTokens: { access_token: 'remote-access-token' },+ }),+ tokenPreference: 'access_token',+ });++ await expect(provider()).resolves.toBeNull();+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('returns null when req is missing entirely', async () => {+ const provider = createOpenIDSessionTokenProvider({+ req: undefined,+ user: makeOpenIdUser(),+ tokenPreference: 'access_token',+ });+ await expect(provider()).resolves.toBeNull();+ });+ });++ describe('refreshOpenIDSession live-token reuse', () => {+ it('returns live tokens without calling IdP when access_token still valid past skew', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const sessionTokens = {+ accessToken: makeJwt(farFutureExp),+ idToken: makeJwt(farFutureExp),+ refreshToken: 'rt-1',+ };+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ expect(result).toEqual({+ access_token: sessionTokens.accessToken,+ id_token: sessionTokens.idToken,+ refresh_token: 'rt-1',+ expires_at: farFutureExp,+ });+ });++ it('rejects a live OBO token whose recorded publication generation was revoked', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const sessionTokens = {+ accessToken: makeJwt(farFutureExp),+ idToken: makeJwt(farFutureExp),+ refreshToken: 'rt-revoked',+ publicationFlightKey: 'publication-key',+ publicationFlightOwnerId: 'publication-owner',+ };+ const req = buildReq(sessionTokens);+ assertOpenIDRefreshSessionGenerationAvailable.mockRejectedValueOnce(+ ownershipLost('revoked by logout'),+ );++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('revoked by logout');++ expect(assertOpenIDRefreshSessionGenerationAvailable).toHaveBeenCalledWith({+ key: 'publication-key',+ ownerId: 'publication-owner',+ });+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('rejects legacy session tokens without a verifiable signed marker', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const sessionTokens = {+ accessToken: makeJwt(farFutureExp),+ idToken: makeJwt(farFutureExp),+ refreshToken: 'rt-unbound',+ };+ const req = buildReq(sessionTokens, 'session-unbound', { bindIdentity: false });++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('OpenID session token identity mismatch');+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('binds a verified legacy session during rolling upgrades before token reuse', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const refreshToken = 'rt-legacy';+ const sessionTokens = {+ accessToken: makeJwt(farFutureExp),+ idToken: makeJwt(farFutureExp),+ refreshToken,+ };+ const req = buildReq(sessionTokens, 'session-legacy', { bindIdentity: false });+ const previousSecret = process.env.JWT_REFRESH_SECRET;+ process.env.JWT_REFRESH_SECRET = SECRET;+ const refreshTokenHash = crypto.createHash('sha256').update(refreshToken).digest('base64url');+ const marker = jwt.sign({ id: 'local-id-1', refreshTokenHash }, SECRET);+ req.headers = {+ cookie: `refreshToken=${refreshToken}; openid_user_id=${marker}`,+ };++ try {+ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).resolves.toEqual(+ expect.objectContaining({+ access_token: sessionTokens.accessToken,+ refresh_token: refreshToken,+ }),+ );+ } finally {+ if (previousSecret == null) {+ delete process.env.JWT_REFRESH_SECRET;+ } else {+ process.env.JWT_REFRESH_SECRET = previousSecret;+ }+ }++ expect(req.session.openidTokens).toEqual(expect.objectContaining(DEFAULT_SESSION_IDENTITY));+ expect(req.session.save).toHaveBeenCalledTimes(1);+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ it('rejects session tokens bound to a different OpenID identity', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const sessionTokens = {+ accessToken: makeJwt(farFutureExp),+ idToken: makeJwt(farFutureExp),+ refreshToken: 'rt-other-user',+ appUserId: 'other-user',+ };+ const req = buildReq(sessionTokens);++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('OpenID session token identity mismatch');+ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });++ /**+ * The bug fixed by Codex Finding 1a: id_token can outlive access_token.+ * Old behavior would declare "live" because id_token is fresh, sending an+ * expired access_token to the OBO IdP. New behavior must trigger a refresh.+ */+ it('refreshes when access_token is expired even if id_token is still fresh', async () => {+ const accessExp = Math.floor(Date.now() / 1000) - 30;+ const idExp = Math.floor(Date.now() / 1000) + 3600;+ const sessionTokens = {+ accessToken: makeJwt(accessExp),+ idToken: makeJwt(idExp),+ refreshToken: 'rt-asym',+ };+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-asym-2',+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ expect(result.access_token).not.toBe(sessionTokens.accessToken);+ });++ it('falls through to refresh when access_token expires within the skew buffer', async () => {+ const veryNearExp = Math.floor(Date.now() / 1000) + 10; // < 30s buffer+ const sessionTokens = {+ accessToken: makeJwt(veryNearExp),+ idToken: makeJwt(veryNearExp),+ refreshToken: 'rt-2',+ };+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-3',+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ expect(buildOpenIDRefreshParams).toHaveBeenCalled();+ expect(result.refresh_token).toBe('rt-3');+ expect(req.session.openidTokens.refreshToken).toBe('rt-3');+ expect(req.session.save).toHaveBeenCalled();+ });+ });++ describe('refreshOpenIDSession refresh path', () => {+ it('refreshes when access_token is expired and persists session', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-old',+ };+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-new',+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ expect(req.session.save).toHaveBeenCalledTimes(1);+ expect(typeof result.access_token).toBe('string');+ expect(req.session.openidTokens).toEqual(+ expect.objectContaining({+ refreshToken: 'rt-new',+ lastRefreshedAt: expect.any(Number),+ }),+ );+ });++ it('preserves an expired prior id_token only as session metadata when rotation omits it', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const priorIdToken = makeJwt(expiredExp);+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: priorIdToken,+ refreshToken: 'rt-keep',+ };+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ // id_token and refresh_token both omitted+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(result.id_token).toBeUndefined();+ expect(result.__identityClaims).toEqual(expect.objectContaining({ sub: 'user-123' }));+ expect(result.refresh_token).toBe('rt-keep');+ expect(req.session.openidTokens.idToken).toBe(priorIdToken);+ expect(req.session.openidTokens.refreshToken).toBe('rt-keep');+ });++ it.each([0, -30])('rejects an elapsed IdP access-token lifetime (%s)', async (expiresIn) => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-elapsed',+ });+ const res = buildRes({ headersSent: false });+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'elapsed-access-token',+ refresh_token: 'rt-rotated',+ expires_in: expiresIn,+ });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('expired access_token');++ expect(req.session.openidTokens.refreshToken).toBe('rt-elapsed');+ expect(req.session.save).not.toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ });++ /**+ * The bug fixed by Codex Finding 1b: when IdP rotates only access_token,+ * derive expires_at from the IdP's tokenset.expires_in (authoritative for+ * the new access_token) rather than the prior id_token's exp claim. The+ * latter would cause `isOpenIDTokenValid` to reject a fresh credential.+ */+ it('uses tokenset.expires_in (not prior id_token exp) for expires_at after rotation-omits-id-token refresh', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-rot',+ };+ // IdP omits id_token; expires_in is the only authoritative expiry source+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ // id_token omitted+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);+ const beforeSec = Math.floor(Date.now() / 1000);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ // expires_at should be ~now + 3600, NOT the stale prior id_token exp+ expect(result.expires_at).toBeGreaterThanOrEqual(beforeSec + 3590);+ expect(result.expires_at).toBeLessThanOrEqual(beforeSec + 3610);+ });++ it('returns null when session lacks a refresh_token (cannot refresh)', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ // no refreshToken+ };+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ expect(result).toBeNull();+ });++ it('rethrows when refreshTokenGrant rejects', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-bad',+ };+ openIdClient.refreshTokenGrant.mockRejectedValueOnce(new Error('invalid_grant'));+ const req = buildReq(sessionTokens);++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('invalid_grant');+ expect(req.session.save).not.toHaveBeenCalled();+ });++ it('rethrows when refreshTokenGrant returns no access_token', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-incomplete',+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ // access_token absent+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow(/no access_token/i);+ });+ });++ describe('rotated refresh-token cookie sync', () => {+ const buildExpiredSession = (refreshToken, browserRefreshToken) => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken,+ };+ if (browserRefreshToken) {+ sessionTokens.browserRefreshToken = browserRefreshToken;+ }+ return sessionTokens;+ };++ it('writes the rotated refresh token to the cookie when res is writable', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(setRefreshTokenCookie).toHaveBeenCalledTimes(1);+ expect(setRefreshTokenCookie).toHaveBeenCalledWith(res, 'rt-rotated', expect.any(Date));+ expect(setOpenIDMarkerCookies).toHaveBeenCalledTimes(1);+ expect(setOpenIDMarkerCookies).toHaveBeenCalledWith(res, {+ userId: 'local-id-1',+ expires: expect.any(Date),+ refreshExpiryMs: 1000 * 60 * 60 * 24 * 7,+ refreshToken: 'rt-rotated',+ });+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ ttl: 60 * 1000,+ }),+ );+ expect(req.session.openidTokens.browserRefreshToken).toBe('rt-rotated');+ });++ /** The durable Session record is what authorizes local image access for OpenID users, and it is+ * looked up by the refresh token in the browser's cookie — so it has to move with the cookie. */+ it('moves the durable session record onto the rotated token alongside the cookie', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(storeOpenIdSession).toHaveBeenCalledWith(+ {+ userId: 'local-id-1',+ refreshToken: 'rt-rotated',+ tenantId: 'tenant-1',+ previousRefreshToken: 'rt-old',+ },+ { upsertSession, deleteSession },+ );+ expect(storeOpenIdSession.mock.invocationCallOrder[0]).toBeLessThan(+ setRefreshTokenCookie.mock.invocationCallOrder[0],+ );+ });++ /** Headers are already sent, so the browser keeps the old cookie: revoking the record it still+ * presents would lock the user out of images until the next `/refresh` recovers the bridge. */+ it('leaves the durable session alone when the rotation can only be bridged', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: true });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(storeRefreshTokenBridge).toHaveBeenCalled();+ expect(storeOpenIdSession).not.toHaveBeenCalled();+ });++ it('removes a bridge published concurrently with logout revocation', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(ownershipLost('revoked by logout'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: true });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('revoked by logout');++ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ ttl: 60 * 1000,+ });+ expect(deleteRefreshTokenBridges).toHaveBeenCalledWith({+ refreshTokens: ['rt-old'],+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ version: 'bridge-version-1',+ });+ expect(deleteSession).not.toHaveBeenCalled();+ expect(res.clearCookie).not.toHaveBeenCalled();+ expect(req.session.openidTokens.refreshToken).toBe('rt-old');+ expect(req.session.save).not.toHaveBeenCalled();+ });++ it('keeps the bridge when the ownership check fails for an undetermined reason', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(new Error('connection timed out'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: true });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('connection timed out');++ expect(storeRefreshTokenBridge).toHaveBeenCalled();+ expect(deleteRefreshTokenBridges).not.toHaveBeenCalled();+ });++ it('surfaces the lease error when removing the orphaned bridge also fails', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ deleteRefreshTokenBridges.mockRejectedValueOnce(new Error('mongo unavailable'));+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(ownershipLost('revoked by logout'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: true });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('revoked by logout');++ expect(deleteRefreshTokenBridges).toHaveBeenCalled();+ });++ it('fails closed before publishing cookies when the durable session transition fails', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ storeOpenIdSession.mockRejectedValueOnce(new Error('mongo down'));+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('mongo down');+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ ttl: 60 * 1000,+ });+ expect(req.session.openidTokens.refreshToken).toBe('rt-old');+ });++ it('does not begin durable publication when ownership is lost at candidate settlement', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const assertLeaseOwned = jest+ .fn()+ .mockResolvedValueOnce(true)+ .mockResolvedValueOnce(true)+ .mockRejectedValueOnce(new Error('lease lost during durable transition'));+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({ assertLeaseOwned, markLeaseSettled: jest.fn() }),+ );+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('lease lost');++ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ expect(req.session.openidTokens.refreshToken).toBe('rt-old');+ });++ it('does not write the cookie when the IdP does not rotate the refresh token', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ // refresh_token omitted → preserved as 'rt-stable'+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-stable'));+ const res = buildRes({ headersSent: false });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ });++ it('rejects a grant whose declared access-token lifetime has already elapsed', async () => {+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-and-already-spent',+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-rotated',+ expires_in: 0,+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('already-expired access_token');++ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(req.session.openidTokens.refreshToken).toBe('rt-old');+ });++ it('publishes a grant whose access-token lifetime is unknown', async () => {+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-unknown-lifetime',+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-rotated',+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(req.session.openidTokens.refreshToken).toBe('rt-rotated');+ expect(req.session.openidTokens.accessTokenExpiresAt).toBeUndefined();+ });++ it('repairs a stale browser cookie when a stable refresh omits refresh_token', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-session-current', 'rt-browser-stale'));+ const res = buildRes({ headersSent: false });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(setRefreshTokenCookie).toHaveBeenCalledWith(+ res,+ 'rt-session-current',+ expect.any(Date),+ );+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ oldRefreshToken: 'rt-browser-stale',+ newRefreshToken: 'rt-session-current',+ ttl: 60 * 1000,+ }),+ );+ expect(req.session.openidTokens.refreshToken).toBe('rt-session-current');+ expect(req.session.openidTokens.browserRefreshToken).toBe('rt-session-current');+ });++ it('revokes the advanced session token rather than the stale browser token on rotation', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-next',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-session-current', 'rt-browser-stale'));+ const res = buildRes({ headersSent: false });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(storeOpenIdSession).toHaveBeenCalledWith(+ expect.objectContaining({+ refreshToken: 'rt-next',+ previousRefreshToken: 'rt-session-current',+ }),+ { upsertSession, deleteSession },+ );+ });++ it('stores a bridge for stale browser cookies when a stable refresh cannot write cookies', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-session-current', 'rt-browser-stale'));+ const res = buildRes({ headersSent: true });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-browser-stale',+ newRefreshToken: 'rt-session-current',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ expect(req.session.openidTokens.browserRefreshToken).toBe('rt-browser-stale');+ });++ it('resolves bridge identity through the shared helper when identity context is absent', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq({+ ...buildExpiredSession('rt-old'),+ appUserId: 'mongo-id',+ });+ const res = buildRes({ headersSent: true });++ await refreshOpenIDSession(+ req,+ res,+ makeOpenIdUser({+ id: 'public-id',+ _id: { toString: () => 'mongo-id' },+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ }),+ 'access_token',+ );++ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'mongo-id',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ });++ it('syncs the rotated cookie and stores a short bridge before surfacing a session save failure', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: false });+ req.session.save.mockImplementationOnce((cb) => cb(new Error('session store down')));++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('session store down');++ expect(setRefreshTokenCookie).toHaveBeenCalledWith(res, 'rt-rotated', expect.any(Date));+ expect(setOpenIDMarkerCookies).toHaveBeenCalledTimes(1);+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ ttl: 60 * 1000,+ });+ expect(req.session.openidTokens.refreshToken).toBe('rt-rotated');+ expect(req.session.openidTokens.browserRefreshToken).toBe('rt-rotated');+ });++ it('stores a recovery bridge when response headers are already sent (streaming path)', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: true });+ const user = makeOpenIdUser({+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });++ await refreshOpenIDSession(req, res, user, 'access_token');++ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ /** Session copy remains authoritative even when the cookie can't be set. */+ expect(req.session.openidTokens.refreshToken).toBe('rt-rotated');+ expect(req.session.openidTokens.browserRefreshToken).toBe('rt-old');+ });++ it('keeps bridging from the stale browser cookie across repeated rotations', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-second-rotation',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-first-rotation', 'rt-browser-cookie'));+ const res = buildRes({ headersSent: true });++ await refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token');++ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-browser-cookie',+ newRefreshToken: 'rt-second-rotation',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ expect(req.session.openidTokens.refreshToken).toBe('rt-second-rotation');+ expect(req.session.openidTokens.browserRefreshToken).toBe('rt-browser-cookie');+ });++ it('stores a recovery bridge when no res is provided', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).resolves.toBeDefined();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ });++ it('stores a recovery bridge when res cannot write cookies', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ const req = buildReq(buildExpiredSession('rt-old'));++ await refreshOpenIDSession(req, { headersSent: false }, makeOpenIdUser(), 'access_token');++ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(setOpenIDMarkerCookies).not.toHaveBeenCalled();+ expect(storeRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-rotated',+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ });+ });++ it('fails closed without mutating the session when bridge storage fails', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });+ storeRefreshTokenBridge.mockRejectedValueOnce(new Error('encrypt failed'));+ const req = buildReq(buildExpiredSession('rt-old'));+ const res = buildRes({ headersSent: true });++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('encrypt failed');++ expect(req.session.openidTokens.refreshToken).toBe('rt-old');+ });+ });++ describe('single-flight coalescing', () => {+ it('scopes the local refresh key by explicit identity context', () => {+ const req = buildReq({ refreshToken: 'rt-shared' }, 'session-shared');+ const user = makeOpenIdUser({ tenantId: undefined, openidIssuer: undefined });++ const keyA = __internals.getSingleFlightKey(req, user, {+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-a.example.com',+ });+ const keyB = __internals.getSingleFlightKey(req, user, {+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenant-b',+ openidIssuer: 'https://issuer-a.example.com',+ });+ const keyC = __internals.getSingleFlightKey(req, user, {+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-b.example.com',+ });++ expect(keyA).not.toBe(keyB);+ expect(keyA).not.toBe(keyC);+ expect(keyA).not.toContain('rt-shared');+ });++ it('shares one refreshTokenGrant across new Express sessions with the same token', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-shared',+ };+ let resolveGrant;+ const grantPromise = new Promise((resolve) => {+ resolveGrant = resolve;+ });+ openIdClient.refreshTokenGrant.mockReturnValueOnce(grantPromise);++ const reqA = buildReq(sessionTokens, 'session-A');+ const reqB = buildReq(sessionTokens, 'session-B');+ const user = makeOpenIdUser();++ const p1 = refreshOpenIDSession(reqA, undefined, user, 'access_token');+ const p2 = refreshOpenIDSession(reqB, undefined, user, 'access_token');+ await Promise.resolve();++ // Both calls land before the IdP responds+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ resolveGrant({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });++ const [r1, r2] = await Promise.all([p1, p2]);+ expect(r1).toStrictEqual(r2);+ expect(__internals.inFlightRefreshes.size).toBe(0);+ });++ it('does not share an in-flight refresh across distinct refresh tokens', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const reqA = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-A',+ },+ 'session-A',+ );+ const reqB = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-B',+ },+ 'session-B',+ );+ let resolveA;+ let resolveB;+ const promiseA = new Promise((resolve) => {+ resolveA = resolve;+ });+ const promiseB = new Promise((resolve) => {+ resolveB = resolve;+ });+ openIdClient.refreshTokenGrant.mockReturnValueOnce(promiseA).mockReturnValueOnce(promiseB);++ const user = makeOpenIdUser();+ const pA = refreshOpenIDSession(reqA, undefined, user, 'access_token');+ const pB = refreshOpenIDSession(reqB, undefined, user, 'access_token');+ await Promise.resolve();++ // Two refreshes started, one per session+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(2);++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ resolveA({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-A-rotated',+ expires_in: 3600,+ });+ resolveB({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-B-rotated',+ expires_in: 3600,+ });++ const [rA, rB] = await Promise.all([pA, pB]);+ expect(rA).not.toBe(rB);+ expect(reqA.session.openidTokens.refreshToken).toBe('rt-A-rotated');+ expect(reqB.session.openidTokens.refreshToken).toBe('rt-B-rotated');+ });++ it('does NOT share an in-flight refresh in the same session when refresh tokens differ', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const reqOld = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-old',+ },+ 'session-rotated',+ );+ const reqCurrent = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-current',+ },+ 'session-rotated',+ );+ let resolveOld;+ let resolveCurrent;+ const oldPromise = new Promise((resolve) => {+ resolveOld = resolve;+ });+ const currentPromise = new Promise((resolve) => {+ resolveCurrent = resolve;+ });+ openIdClient.refreshTokenGrant+ .mockReturnValueOnce(oldPromise)+ .mockReturnValueOnce(currentPromise);++ const user = makeOpenIdUser();+ const oldRefresh = refreshOpenIDSession(reqOld, undefined, user, 'access_token');+ const currentRefresh = refreshOpenIDSession(reqCurrent, undefined, user, 'access_token');+ await Promise.resolve();++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(2);++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ resolveOld({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-old-rotated',+ expires_in: 3600,+ });+ resolveCurrent({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-current-rotated',+ expires_in: 3600,+ });++ const [oldResult, currentResult] = await Promise.all([oldRefresh, currentRefresh]);+ expect(oldResult).not.toBe(currentResult);+ expect(reqOld.session.openidTokens.refreshToken).toBe('rt-old-rotated');+ expect(reqCurrent.session.openidTokens.refreshToken).toBe('rt-current-rotated');+ });++ it('clears in-flight slot on rejection so subsequent attempts can retry', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-flaky',+ };+ openIdClient.refreshTokenGrant.mockRejectedValueOnce(new Error('transient'));+ const req = buildReq(sessionTokens);+ const user = makeOpenIdUser();++ await expect(refreshOpenIDSession(req, undefined, user, 'access_token')).rejects.toThrow(+ 'transient',+ );+ expect(__internals.inFlightRefreshes.size).toBe(0);++ // Second attempt: succeed+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-recovered',+ expires_in: 3600,+ });+ const result = await refreshOpenIDSession(req, undefined, user, 'access_token');+ expect(result.refresh_token).toBe('rt-recovered');+ });++ it('hydrates a joining request that shares the session id but carries a distinct req', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const makeExpiredSession = (refreshToken) => ({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken,+ });+ /** Two concurrent HTTP requests from the same browser session. */+ const leaderReq = buildReq(makeExpiredSession('rt-stale'), 'session-joined');+ const joinerReq = buildReq(makeExpiredSession('rt-stale'), 'session-joined');+ const user = makeOpenIdUser();++ let resolveGrant;+ const grantPromise = new Promise((resolve) => {+ resolveGrant = resolve;+ });+ openIdClient.refreshTokenGrant.mockReturnValueOnce(grantPromise);++ const leaderPromise = refreshOpenIDSession(leaderReq, undefined, user, 'access_token');+ const joinerPromise = refreshOpenIDSession(joinerReq, undefined, user, 'access_token');+ await Promise.resolve();++ // Only the leader hit the IdP; the joiner coalesced onto it.+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ resolveGrant({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });++ const [leaderTokens, joinerTokens] = await Promise.all([leaderPromise, joinerPromise]);++ expect(leaderTokens.refresh_token).toBe('rt-rotated');+ expect(joinerTokens.refresh_token).toBe('rt-rotated');+ // The joiner's OWN session is hydrated so a later OBO call won't replay rt-stale.+ expect(joinerReq.session.openidTokens.refreshToken).toBe('rt-rotated');+ expect(joinerReq.session.openidTokens.browserRefreshToken).toBe('rt-stale');+ expect(joinerReq.session.save).toHaveBeenCalled();+ });++ it('checks revocation before an already-current local joiner returns', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-shared-request',+ });+ let resolveGrant;+ openIdClient.refreshTokenGrant.mockReturnValueOnce(+ new Promise((resolve) => {+ resolveGrant = resolve;+ }),+ );+ const leaderPromise = refreshOpenIDSession(req, buildRes(), makeOpenIdUser(), 'access_token');+ const joinerPromise = refreshOpenIDSession(req, buildRes(), makeOpenIdUser(), 'access_token');+ await Promise.resolve();+ resolveGrant({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-shared-successor',+ expires_in: 3600,+ });+ assertOpenIDRefreshFlightAvailable.mockRejectedValueOnce(ownershipLost('revoked by logout'));++ await expect(leaderPromise).resolves.toBeDefined();+ await expect(joinerPromise).rejects.toThrow('revoked by logout');+ expect(assertOpenIDRefreshFlightAvailable).toHaveBeenCalledWith({+ key: 'flight:session-A:rt-shared-request',+ ownerId: 'owner-1',+ });+ });++ it('keeps both local coalescing participants unpublished when publication is deferred', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const makeExpiredSession = () => ({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-deferred',+ browserRefreshToken: 'rt-deferred',+ });+ const leaderReq = buildReq(makeExpiredSession(), 'session-deferred-leader');+ const joinerReq = buildReq(makeExpiredSession(), 'session-deferred-joiner');+ const user = makeOpenIdUser();+ let resolveGrant;+ openIdClient.refreshTokenGrant.mockReturnValueOnce(+ new Promise((resolve) => {+ resolveGrant = resolve;+ }),+ );++ const options = { forceRefresh: true, deferPublication: true };+ const leaderPromise = refreshOpenIDSession(+ leaderReq,+ undefined,+ user,+ 'access_token',+ undefined,+ options,+ );+ const joinerPromise = refreshOpenIDSession(+ joinerReq,+ undefined,+ user,+ 'access_token',+ undefined,+ options,+ );+ await Promise.resolve();+ resolveGrant({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-deferred-rotated',+ expires_in: 3600,+ });++ const [leaderTokens, joinerTokens] = await Promise.all([leaderPromise, joinerPromise]);++ expect(leaderTokens.refresh_token).toBe('rt-deferred-rotated');+ expect(joinerTokens.refresh_token).toBe('rt-deferred-rotated');+ expect(leaderReq.session.openidTokens.refreshToken).toBe('rt-deferred');+ expect(joinerReq.session.openidTokens.refreshToken).toBe('rt-deferred');+ expect(leaderReq.session.save).not.toHaveBeenCalled();+ expect(joinerReq.session.save).not.toHaveBeenCalled();+ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ });++ it('hydrates a joining request with the rotated browser marker when the leader wrote cookies', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const makeExpiredSession = () => ({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-stale',+ browserRefreshToken: 'rt-stale',+ });+ const leaderReq = buildReq(makeExpiredSession(), 'session-cookie-joined');+ const joinerReq = buildReq(makeExpiredSession(), 'session-cookie-joined');+ const leaderRes = buildRes({ headersSent: false });+ const joinerRes = buildRes({ headersSent: false });+ const user = makeOpenIdUser();++ let resolveGrant;+ const grantPromise = new Promise((resolve) => {+ resolveGrant = resolve;+ });+ openIdClient.refreshTokenGrant.mockReturnValueOnce(grantPromise);++ const leaderPromise = refreshOpenIDSession(leaderReq, leaderRes, user, 'access_token');+ const joinerPromise = refreshOpenIDSession(joinerReq, joinerRes, user, 'access_token');+ await Promise.resolve();++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ resolveGrant({+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-rotated',+ expires_in: 3600,+ });++ const [leaderTokens, joinerTokens] = await Promise.all([leaderPromise, joinerPromise]);++ expect(leaderTokens.refresh_token).toBe('rt-rotated');+ expect(joinerTokens.refresh_token).toBe('rt-rotated');+ expect(setRefreshTokenCookie).toHaveBeenCalledWith(leaderRes, 'rt-rotated', expect.any(Date));+ expect(setRefreshTokenCookie).toHaveBeenCalledWith(joinerRes, 'rt-rotated', expect.any(Date));+ expect(leaderReq.session.openidTokens.browserRefreshToken).toBe('rt-rotated');+ expect(leaderReq.session.openidTokens).toEqual(+ expect.objectContaining({+ publicationFlightKey: 'flight:session-cookie-joined:rt-stale',+ publicationFlightOwnerId: 'owner-1',+ }),+ );+ expect(joinerReq.session.openidTokens.refreshToken).toBe('rt-rotated');+ expect(joinerReq.session.openidTokens.browserRefreshToken).toBe('rt-rotated');+ expect(Object.keys(joinerTokens)).not.toContain('__browserRefreshToken');+ expect(joinerReq.session.save).toHaveBeenCalled();+ });++ it('hydrates a joining request when the refresh token stays stable', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const makeExpiredSession = () => ({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-stable',+ accessTokenExpiresAt: expiredExp,+ });+ const leaderReq = buildReq(makeExpiredSession(), 'session-stable-joined');+ const joinerReq = buildReq(makeExpiredSession(), 'session-stable-joined');+ const user = makeOpenIdUser();++ let resolveGrant;+ const grantPromise = new Promise((resolve) => {+ resolveGrant = resolve;+ });+ openIdClient.refreshTokenGrant.mockReturnValueOnce(grantPromise);++ const leaderPromise = refreshOpenIDSession(leaderReq, undefined, user, 'access_token');+ const joinerPromise = refreshOpenIDSession(joinerReq, undefined, user, 'access_token');+ await Promise.resolve();++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ const refreshedAccessToken = makeJwt(refreshedExp);+ const refreshedIdToken = makeJwt(refreshedExp);+ resolveGrant({+ access_token: refreshedAccessToken,+ id_token: refreshedIdToken,+ refresh_token: 'rt-stable',+ expires_in: 3600,+ });++ const [leaderTokens, joinerTokens] = await Promise.all([leaderPromise, joinerPromise]);++ expect(leaderTokens.refresh_token).toBe('rt-stable');+ expect(joinerTokens.refresh_token).toBe('rt-stable');+ expect(joinerReq.session.openidTokens.accessToken).toBe(refreshedAccessToken);+ expect(joinerReq.session.openidTokens.idToken).toBe(refreshedIdToken);+ expect(joinerReq.session.openidTokens.refreshToken).toBe('rt-stable');+ expect(joinerReq.session.openidTokens.accessTokenExpiresAt).toBe(joinerTokens.expires_at);+ expect(joinerReq.session.openidTokens.accessTokenExpiresAt).toBeGreaterThan(expiredExp);+ expect(joinerReq.session.save).toHaveBeenCalled();+ });++ it('joins a shared Mongo refresh flight when the local process has no in-flight entry', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const makeExpiredSession = () => ({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-cross-worker',+ });+ const leaderReq = buildReq(makeExpiredSession(), 'session-cross-worker');+ const joinerReq = buildReq(makeExpiredSession(), 'session-cross-worker');+ const user = makeOpenIdUser();++ let resolveGrant;+ const grantPromise = new Promise((resolve) => {+ resolveGrant = resolve;+ });+ openIdClient.refreshTokenGrant.mockReturnValueOnce(grantPromise);+ acquireOpenIDRefreshFlight+ .mockResolvedValueOnce({ acquired: true, ownerId: 'owner-leader' })+ .mockResolvedValueOnce({ acquired: false, ownerId: 'owner-joiner' });++ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ const sharedTokens = {+ access_token: makeJwt(refreshedExp),+ id_token: makeJwt(refreshedExp),+ refresh_token: 'rt-cross-worker-rotated',+ expires_at: refreshedExp,+ };+ Object.defineProperty(sharedTokens, '__flightOwnerId', {+ value: 'owner-leader',+ enumerable: false,+ });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce(sharedTokens);++ const leaderPromise = refreshOpenIDSession(leaderReq, undefined, user, 'access_token');+ await Promise.resolve();+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);++ /**+ * Simulate a second worker: it does not see this process-local Map, but+ * it does see the Mongo flight for the same browser session/token.+ */+ __internals.inFlightRefreshes.clear();+ const joinerTokens = await refreshOpenIDSession(joinerReq, undefined, user, 'access_token');++ expect(waitForOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight:session-cross-worker:rt-cross-worker',+ });+ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ expect(joinerTokens).toStrictEqual(sharedTokens);+ expect(joinerReq.session.openidTokens.refreshToken).toBe('rt-cross-worker-rotated');+ expect(joinerReq.session.openidTokens).toEqual(+ expect.objectContaining({+ publicationFlightKey: 'flight:session-cross-worker:rt-cross-worker',+ publicationFlightOwnerId: 'owner-leader',+ }),+ );+ expect(joinerReq.session.save).toHaveBeenCalled();++ resolveGrant({+ access_token: sharedTokens.access_token,+ id_token: sharedTokens.id_token,+ refresh_token: sharedTokens.refresh_token,+ expires_in: 3600,+ });++ await expect(leaderPromise).resolves.toEqual(+ expect.objectContaining({+ access_token: sharedTokens.access_token,+ id_token: sharedTokens.id_token,+ refresh_token: sharedTokens.refresh_token,+ expires_at: expect.any(Number),+ }),+ );+ expect(completeOpenIDRefreshFlight).toHaveBeenCalledWith({+ key: 'flight:session-cross-worker:rt-cross-worker',+ ownerId: 'owner-leader',+ tokens: expect.objectContaining({+ access_token: sharedTokens.access_token,+ id_token: sharedTokens.id_token,+ refresh_token: sharedTokens.refresh_token,+ expires_at: expect.any(Number),+ }),+ });+ expect(withOpenIDRefreshFlightLease).toHaveBeenCalledWith({+ key: 'flight:session-cross-worker:rt-cross-worker',+ ownerId: 'owner-leader',+ operation: expect.any(Function),+ });+ });++ it('rolls back a follower replay when logout revokes the completed flight', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const predecessorAccessToken = makeJwt(expiredExp);+ const req = buildReq({+ accessToken: predecessorAccessToken,+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ browserRefreshToken: 'rt-predecessor',+ });+ const res = buildRes({ headersSent: false });+ req.session.destroy = jest.fn((callback) => {+ delete req.session.openidTokens;+ callback();+ });+ acquireOpenIDRefreshFlight.mockResolvedValueOnce({ acquired: false, ownerId: 'follower' });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-successor',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ __predecessorRefreshToken: 'rt-predecessor',+ __predecessorAccessToken: predecessorAccessToken,+ __flightOwnerId: 'generation-owner',+ });+ assertOpenIDRefreshFlightAvailable+ .mockResolvedValueOnce({ status: 'completed' })+ .mockResolvedValueOnce({ status: 'completed' })+ .mockResolvedValueOnce({ status: 'completed' })+ .mockResolvedValueOnce({ status: 'completed' })+ .mockResolvedValueOnce({ status: 'completed' })+ .mockRejectedValueOnce(ownershipLost('revoked by logout'));++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('revoked by logout');++ expect(storeOpenIdSession).toHaveBeenCalled();+ expect(setRefreshTokenCookie).toHaveBeenCalled();+ expect(req.session.save).toHaveBeenCalled();+ expect(deleteSession).toHaveBeenCalledWith({ refreshToken: 'rt-successor' });+ expect(req.session.destroy).toHaveBeenCalled();+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(assertOpenIDRefreshFlightAvailable).toHaveBeenCalledWith({+ key: 'flight:session-A:rt-predecessor',+ ownerId: 'generation-owner',+ });+ });++ it('does not replay a stable-token flight over a newer access token', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const predecessorAccessToken = makeJwt(expiredExp);+ const advancedAccessToken = makeJwt(Math.floor(Date.now() / 1000) + 7200);+ const req = buildReq({+ accessToken: predecessorAccessToken,+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-stable',+ });+ req.session.reload = jest.fn((callback) => {+ req.session.openidTokens = {+ ...req.session.openidTokens,+ accessToken: advancedAccessToken,+ refreshToken: 'rt-stable',+ };+ callback();+ });+ acquireOpenIDRefreshFlight.mockResolvedValueOnce({ acquired: false, ownerId: 'follower' });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-stable',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ __predecessorRefreshToken: 'rt-stable',+ __predecessorAccessToken: predecessorAccessToken,+ __flightOwnerId: 'stable-generation-owner',+ });++ const result = await refreshOpenIDSession(req, buildRes(), makeOpenIdUser(), 'access_token');++ expect(req.session.openidTokens.accessToken).toBe(advancedAccessToken);+ expect(result.access_token).toBe(advancedAccessToken);+ expect(result.__predecessorAccessToken).toBe(predecessorAccessToken);+ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(req.session.save).not.toHaveBeenCalled();+ });++ it('does not publish a deferred local leader result through an immediate joiner', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const makeExpiredSession = () => ({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-mixed-mode',+ });+ const leaderReq = buildReq(makeExpiredSession(), 'session-mixed-mode');+ const joinerReq = buildReq(makeExpiredSession(), 'session-mixed-mode');+ let resolveGrant;+ openIdClient.refreshTokenGrant.mockReturnValueOnce(+ new Promise((resolve) => {+ resolveGrant = resolve;+ }),+ );++ const leaderPromise = refreshOpenIDSession(+ leaderReq,+ undefined,+ makeOpenIdUser(),+ 'access_token',+ undefined,+ { forceRefresh: true, deferPublication: true },+ );+ const joinerPromise = refreshOpenIDSession(+ joinerReq,+ buildRes(),+ makeOpenIdUser(),+ 'access_token',+ );+ await Promise.resolve();+ resolveGrant({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-mixed-successor',+ expires_in: 3600,+ });++ await expect(leaderPromise).resolves.toBeDefined();+ await expect(joinerPromise).rejects.toThrow('awaiting identity validation');+ expect(joinerReq.session.save).not.toHaveBeenCalled();+ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ });++ it('does not publish a deferred cross-replica result through an immediate follower', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-deferred-worker',+ });+ acquireOpenIDRefreshFlight.mockResolvedValueOnce({ acquired: false, ownerId: 'follower' });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-deferred-successor',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ __deferredPublication: true,+ });++ await expect(+ refreshOpenIDSession(req, buildRes(), makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('awaiting identity validation');++ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(req.session.save).not.toHaveBeenCalled();+ });++ it('fails closed when a shared flight times out instead of issuing a duplicate grant', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-cross-worker',+ },+ 'session-cross-worker',+ );+ acquireOpenIDRefreshFlight.mockResolvedValueOnce({+ acquired: false,+ ownerId: 'owner-joiner',+ });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce(null);++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('OpenID refresh coordination is temporarily unavailable');++ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ expect(withOpenIDRefreshFlightLease).not.toHaveBeenCalled();+ });++ it('does not mutate session state after refresh-flight ownership is lost', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-lost-owner',+ };+ const req = buildReq(sessionTokens, 'session-lost-owner');+ withOpenIDRefreshFlightLease.mockImplementationOnce(({ operation }) =>+ operation({+ assertLeaseOwned: jest+ .fn()+ .mockRejectedValue(new Error('OpenID refresh coordination ownership was lost')),+ markLeaseSettled: jest.fn(),+ }),+ );+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-rotated-by-stale-owner',+ expires_in: 3600,+ });++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('ownership was lost');++ expect(req.session.openidTokens).toEqual(+ expect.objectContaining({+ accessToken: sessionTokens.accessToken,+ idToken: sessionTokens.idToken,+ refreshToken: sessionTokens.refreshToken,+ }),+ );+ expect(req.session.save).not.toHaveBeenCalled();+ expect(completeOpenIDRefreshFlight).not.toHaveBeenCalled();+ expect(failOpenIDRefreshFlight).toHaveBeenCalled();+ });++ it('keeps an indeterminate completed generation recoverable instead of marking it failed', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ });+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-successor',+ expires_in: 3600,+ });+ completeOpenIDRefreshFlight.mockRejectedValueOnce(new Error('completion timed out'));+ assertOpenIDRefreshFlightAvailable.mockRejectedValueOnce(new Error('read timed out'));++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('completion timed out');++ expect(req.session.openidTokens.refreshToken).toBe('rt-successor');+ expect(failOpenIDRefreshFlight).not.toHaveBeenCalled();+ });++ it('accepts an observed completed generation after the completion acknowledgement is lost', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ });+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-successor',+ expires_in: 3600,+ });+ completeOpenIDRefreshFlight.mockRejectedValueOnce(new Error('completion timed out'));+ assertOpenIDRefreshFlightAvailable.mockResolvedValueOnce({+ status: 'completed',+ ownerId: 'owner-1',+ });++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).resolves.toMatchObject({ refresh_token: 'rt-successor' });+ expect(failOpenIDRefreshFlight).not.toHaveBeenCalled();+ });++ it('rolls back session and cookie publication when logout revokes the pending flight', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ browserRefreshToken: 'rt-predecessor',+ });+ const res = buildRes({ headersSent: false });+ req.session.destroy = jest.fn((callback) => {+ delete req.session.openidTokens;+ callback();+ });+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-successor',+ expires_in: 3600,+ });+ completeOpenIDRefreshFlight.mockResolvedValueOnce(null);++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('ownership was lost');++ expect(storeOpenIdSession).toHaveBeenCalled();+ expect(setRefreshTokenCookie).toHaveBeenCalledWith(res, 'rt-successor', expect.any(Date));+ expect(deleteSession).toHaveBeenCalledWith({ refreshToken: 'rt-successor' });+ expect(req.session.destroy).toHaveBeenCalled();+ expect(deleteRefreshTokenBridges).toHaveBeenCalledWith({+ refreshTokens: ['rt-predecessor'],+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ version: 'bridge-version-1',+ });+ expect(req.session.openidTokens).toBeUndefined();+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.clearCookie).toHaveBeenCalledWith('openid_user_id');+ expect(res.clearCookie).toHaveBeenCalledWith('token_provider');+ });++ it('compare-deletes the final long-lived bridge when publication is revoked', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ browserRefreshToken: 'rt-predecessor',+ });+ req.session.destroy = jest.fn((callback) => {+ delete req.session.openidTokens;+ callback();+ });+ storeRefreshTokenBridge+ .mockResolvedValueOnce('grace-bridge-version')+ .mockResolvedValueOnce('final-bridge-version');+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-successor',+ expires_in: 3600,+ });+ completeOpenIDRefreshFlight.mockResolvedValueOnce(null);++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('ownership was lost');++ expect(storeRefreshTokenBridge).toHaveBeenCalledTimes(2);+ expect(deleteRefreshTokenBridges).toHaveBeenCalledWith({+ refreshTokens: ['rt-predecessor'],+ userId: 'local-id-1',+ tenantId: 'tenant-1',+ version: 'final-bridge-version',+ });+ });++ it('does not destroy a newer Express session when another owner advanced it', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const advancedAccessToken = makeJwt(Math.floor(Date.now() / 1000) + 7200);+ const req = buildReq({+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ browserRefreshToken: 'rt-predecessor',+ });+ const res = buildRes({ headersSent: false });+ req.session.destroy = jest.fn((callback) => callback());+ req.session.reload = jest.fn();+ req.session.reload+ .mockImplementationOnce((callback) => callback())+ .mockImplementationOnce((callback) => {+ req.session.openidTokens = {+ ...req.session.openidTokens,+ accessToken: advancedAccessToken,+ refreshToken: 'rt-new-owner',+ };+ callback();+ });+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 3600),+ refresh_token: 'rt-stale-owner',+ expires_in: 3600,+ });+ completeOpenIDRefreshFlight.mockResolvedValueOnce(null);++ await expect(+ refreshOpenIDSession(req, res, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('ownership was lost');++ expect(req.session.destroy).not.toHaveBeenCalled();+ expect(req.session.openidTokens.accessToken).toBe(advancedAccessToken);+ expect(req.session.openidTokens.refreshToken).toBe('rt-new-owner');+ expect(deleteSession).toHaveBeenCalledWith({ refreshToken: 'rt-stale-owner' });+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ });++ it('fails closed when Mongo flight acquisition is unavailable', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const req = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-coordination-down',+ },+ 'session-coordination-down',+ );+ acquireOpenIDRefreshFlight.mockRejectedValueOnce(new Error('mongo unavailable'));++ await expect(+ refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token'),+ ).rejects.toThrow('OpenID refresh coordination is temporarily unavailable');++ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ });+ });++ describe('createOpenIDSessionTokenProvider closure delegation', () => {+ it('returns the live OIDCTokens shape from a valid session', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const sessionTokens = {+ accessToken: makeJwt(farFutureExp),+ idToken: makeJwt(farFutureExp),+ refreshToken: 'rt-1',+ };+ const provider = createOpenIDSessionTokenProvider({+ req: buildReq(sessionTokens),+ user: makeOpenIdUser(),+ tokenPreference: 'access_token',+ });++ const result = await provider();+ expect(result).toEqual({+ access_token: sessionTokens.accessToken,+ id_token: sessionTokens.idToken,+ refresh_token: 'rt-1',+ expires_at: farFutureExp,+ });+ });++ it('rejects with the IdP error when refresh fails through the closure', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-fail',+ };+ openIdClient.refreshTokenGrant.mockRejectedValueOnce(new Error('invalid_grant'));+ const provider = createOpenIDSessionTokenProvider({+ req: buildReq(sessionTokens),+ user: makeOpenIdUser(),+ tokenPreference: 'access_token',+ });++ await expect(provider()).rejects.toThrow('invalid_grant');+ });+ });++ /**+ * Codex Finding 4: opaque (non-JWT) access tokens make `decodeJwtExp` return+ * null, which would force every OBO call to refresh even when the previous+ * refresh response advertised a still-valid `expires_in`. The fix persists+ * `accessTokenExpiresAt` (unix seconds) on each refresh and uses it as a+ * fallback for the freshness check + `expires_at` derivation.+ */+ describe('opaque access token support (accessTokenExpiresAt fallback)', () => {+ it('reuses live opaque access_token when accessTokenExpiresAt is in the future', async () => {+ const farFutureExp = Math.floor(Date.now() / 1000) + 600;+ const sessionTokens = {+ accessToken: 'opaque-blob-not-a-jwt',+ idToken: makeJwt(farFutureExp),+ refreshToken: 'rt-opaque',+ accessTokenExpiresAt: farFutureExp,+ };+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ expect(result).toEqual({+ access_token: 'opaque-blob-not-a-jwt',+ id_token: sessionTokens.idToken,+ refresh_token: 'rt-opaque',+ expires_at: farFutureExp,+ });+ });++ it('refreshes opaque access_token when accessTokenExpiresAt has passed', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ const sessionTokens = {+ accessToken: 'opaque-stale',+ idToken: makeJwt(refreshedExp), // id_token still valid+ refreshToken: 'rt-opaque-stale',+ accessTokenExpiresAt: expiredExp,+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-fresh',+ // IdP omits id_token (Auth0 rotation off / MS personal); we use expires_in+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ const result = await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ expect(result.access_token).toBe('opaque-fresh');+ });++ it('refreshes opaque access_token when no JWT exp and no accessTokenExpiresAt are present', async () => {+ const refreshedExp = Math.floor(Date.now() / 1000) + 3600;+ const sessionTokens = {+ accessToken: 'opaque-no-expiry',+ idToken: makeJwt(refreshedExp),+ refreshToken: 'rt-no-exp',+ // accessTokenExpiresAt deliberately omitted+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-fresh',+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(openIdClient.refreshTokenGrant).toHaveBeenCalledTimes(1);+ });++ it('persists accessTokenExpiresAt to req.session.openidTokens after a refresh with expires_in', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: 'opaque-stale',+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-persist',+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-fresh',+ expires_in: 3600,+ });+ const req = buildReq(sessionTokens);+ const beforeSec = Math.floor(Date.now() / 1000);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ const persistedExp = req.session.openidTokens.accessTokenExpiresAt;+ expect(typeof persistedExp).toBe('number');+ expect(persistedExp).toBeGreaterThanOrEqual(beforeSec + 3590);+ expect(persistedExp).toBeLessThanOrEqual(beforeSec + 3610);+ });++ it('persists accessTokenExpiresAt when the refreshed expires_in is a numeric string', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: 'opaque-stale',+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-string-expiry',+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-fresh',+ expires_in: '3600',+ });+ const req = buildReq(sessionTokens);+ const beforeSec = Math.floor(Date.now() / 1000);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(req.session.openidTokens.accessTokenExpiresAt).toBeGreaterThanOrEqual(+ beforeSec + 3590,+ );+ });++ it('does not roll an advanced session backward with a stale completed flight', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const advancedExp = Math.floor(Date.now() / 1000) + 3600;+ const req = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-predecessor',+ },+ 'session-stale-follower',+ );+ req.session.reload = jest.fn((callback) => {+ req.session.openidTokens = withSessionIdentity({+ accessToken: makeJwt(advancedExp),+ idToken: makeJwt(advancedExp),+ refreshToken: 'rt-advanced',+ accessTokenExpiresAt: advancedExp,+ publicationFlightKey: 'advanced-publication-key',+ publicationFlightOwnerId: 'advanced-publication-owner',+ });+ callback();+ });+ acquireOpenIDRefreshFlight.mockResolvedValueOnce({ acquired: false, ownerId: 'other' });+ const staleResult = {+ access_token: makeJwt(advancedExp - 60),+ id_token: makeJwt(advancedExp - 60),+ refresh_token: 'rt-stale-result',+ expires_at: advancedExp - 60,+ };+ Object.defineProperty(staleResult, '__predecessorRefreshToken', {+ value: 'rt-predecessor',+ enumerable: false,+ });+ Object.defineProperty(staleResult, '__flightOwnerId', {+ value: 'stale-publication-owner',+ enumerable: false,+ });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce(staleResult);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(req.session.reload).toHaveBeenCalled();+ expect(req.session.openidTokens.refreshToken).toBe('rt-advanced');+ expect(assertOpenIDRefreshSessionGenerationAvailable).toHaveBeenCalledWith({+ key: 'advanced-publication-key',+ ownerId: 'advanced-publication-owner',+ });+ expect(storeRefreshTokenBridge).not.toHaveBeenCalled();+ expect(storeOpenIdSession).not.toHaveBeenCalled();+ expect(setRefreshTokenCookie).not.toHaveBeenCalled();+ expect(req.session.save).not.toHaveBeenCalled();+ });++ it('keeps the newer generation when stale and current flights contain identical token strings', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const liveExp = Math.floor(Date.now() / 1000) + 3600;+ const req = buildReq(+ {+ accessToken: makeJwt(expiredExp),+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-stable',+ },+ 'session-identical-generations',+ );+ req.session.reload = jest.fn((callback) => {+ req.session.openidTokens = withSessionIdentity({+ accessToken: 'identical-access',+ idToken: 'identical-id',+ refreshToken: 'rt-stable',+ accessTokenExpiresAt: liveExp,+ publicationFlightKey: 'newer-publication-key',+ publicationFlightOwnerId: 'newer-publication-owner',+ publicationFlightCreatedAt: 2000,+ });+ callback();+ });+ acquireOpenIDRefreshFlight.mockResolvedValueOnce({ acquired: false, ownerId: 'other' });+ const staleResult = {+ access_token: 'identical-access',+ id_token: 'identical-id',+ refresh_token: 'rt-stable',+ expires_at: liveExp,+ };+ Object.defineProperty(staleResult, '__predecessorRefreshToken', {+ value: 'rt-stable',+ enumerable: false,+ });+ Object.defineProperty(staleResult, '__flightOwnerId', {+ value: 'stale-publication-owner',+ enumerable: false,+ });+ Object.defineProperty(staleResult, '__flightCreatedAt', {+ value: 1000,+ enumerable: false,+ });+ waitForOpenIDRefreshFlight.mockResolvedValueOnce(staleResult);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(req.session.openidTokens).toEqual(+ expect.objectContaining({+ accessToken: 'identical-access',+ refreshToken: 'rt-stable',+ publicationFlightKey: 'newer-publication-key',+ publicationFlightOwnerId: 'newer-publication-owner',+ publicationFlightCreatedAt: 2000,+ }),+ );+ expect(req.session.save).not.toHaveBeenCalled();+ });++ it('drops a stale accessTokenExpiresAt when the new tokenset has neither expires_in nor a JWT access_token', async () => {+ const expiredExp = Math.floor(Date.now() / 1000) - 60;+ const sessionTokens = {+ accessToken: 'opaque-old',+ idToken: makeJwt(expiredExp),+ refreshToken: 'rt-drop',+ accessTokenExpiresAt: expiredExp, // stale carry-over+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-fresh-no-meta',+ // no expires_in, no JWT access_token, no id_token+ });+ const req = buildReq(sessionTokens);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ expect(req.session.openidTokens).not.toHaveProperty('accessTokenExpiresAt');+ });++ it('getAccessTokenExp prefers JWT exp over the persisted accessTokenExpiresAt', () => {+ const jwtExp = Math.floor(Date.now() / 1000) + 600;+ const persistedExp = Math.floor(Date.now() / 1000) - 60; // stale+ const result = __internals.getAccessTokenExp({+ accessToken: makeJwt(jwtExp),+ accessTokenExpiresAt: persistedExp,+ });+ expect(result).toBe(jwtExp);+ });++ it('getAccessTokenExp returns null when neither a decodable JWT nor a persisted expiry is present', () => {+ const result = __internals.getAccessTokenExp({+ accessToken: 'opaque',+ });+ expect(result).toBeNull();+ });++ /**+ * Codex Finding 6: id_token TTL is governed by IdP session policy and is+ * often longer than access-token TTL. Trusting it as access-token expiry+ * would mark an opaque access token reusable past its real lifetime,+ * sending an expired credential to the OBO IdP. The fallback chain must+ * be expires_in → JWT access_token exp → unset (NOT id_token exp).+ */+ it('does NOT fall back to id_token exp for accessTokenExpiresAt when expires_in is missing', async () => {+ const longLivedIdTokenExp = Math.floor(Date.now() / 1000) + 86400; // 24h+ const sessionTokens = {+ accessToken: 'opaque-old',+ idToken: makeJwt(Math.floor(Date.now() / 1000) - 60),+ refreshToken: 'rt-no-fallback',+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: 'opaque-fresh', // opaque, NOT a JWT+ id_token: makeJwt(longLivedIdTokenExp), // long-lived id_token+ // no expires_in+ });+ const req = buildReq(sessionTokens);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ // The long-lived id_token exp must NOT have been borrowed for the access token.+ expect(req.session.openidTokens).not.toHaveProperty('accessTokenExpiresAt');+ });++ it('falls back to JWT access_token exp for accessTokenExpiresAt when expires_in is missing', async () => {+ const accessExp = Math.floor(Date.now() / 1000) + 1800; // 30min+ const sessionTokens = {+ accessToken: 'opaque-old',+ idToken: makeJwt(Math.floor(Date.now() / 1000) - 60),+ refreshToken: 'rt-jwt-access',+ };+ openIdClient.refreshTokenGrant.mockResolvedValueOnce({+ access_token: makeJwt(accessExp), // JWT access token+ id_token: makeJwt(Math.floor(Date.now() / 1000) + 86400), // long-lived; should NOT win+ // no expires_in+ });+ const req = buildReq(sessionTokens);++ await refreshOpenIDSession(req, undefined, makeOpenIdUser(), 'access_token');++ // accessTokenExpiresAt comes from the access token's own JWT exp, not the id_token.+ expect(req.session.openidTokens.accessTokenExpiresAt).toBe(accessExp);+ });+ });+});diff --git a/api/server/services/RefreshTokenBridge.js b/api/server/services/RefreshTokenBridge.jsnew file mode 100644index 0000000000..f0faf367ae--- /dev/null+++ b/api/server/services/RefreshTokenBridge.js@@ -0,0 +1,22 @@+const {+ createRefreshTokenBridgeIdentity,+ createRefreshTokenBridgeService,+ math,+} = require('@librechat/api');+const {+ logger,+ encryptV2,+ decryptV2,+ DEFAULT_REFRESH_TOKEN_EXPIRY,+} = require('@librechat/data-schemas');+const db = require('~/models');++module.exports = createRefreshTokenBridgeService({+ db,+ logger,+ encrypt: encryptV2,+ decrypt: decryptV2,+ math,+ defaultRefreshTokenExpiry: DEFAULT_REFRESH_TOKEN_EXPIRY,+ createIdentity: createRefreshTokenBridgeIdentity,+});diff --git a/api/server/services/RefreshTokenBridge.spec.js b/api/server/services/RefreshTokenBridge.spec.jsnew file mode 100644index 0000000000..d3e8cc21bb--- /dev/null+++ b/api/server/services/RefreshTokenBridge.spec.js@@ -0,0 +1,282 @@+jest.mock('@librechat/data-schemas', () => ({+ logger: {+ error: jest.fn(),+ debug: jest.fn(),+ warn: jest.fn(),+ info: jest.fn(),+ },+ DEFAULT_REFRESH_TOKEN_EXPIRY: 604800000,+ encryptV2: jest.fn(async (value) => `encrypted:${value}`),+ decryptV2: jest.fn(async (value) => value.replace(/^encrypted:/, '')),+}));++jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),+ math: jest.fn((_value, fallback) => fallback),+ createRefreshTokenBridgeIdentity: ({ userId, tenantId, openidIssuer }) => ({+ userId: userId?.trim(),+ tenantId: tenantId?.trim() || undefined,+ openidIssuer:+ openidIssuer?.trim().replace('/.well-known/openid-configuration', '').replace(/\/+$/, '') ||+ undefined,+ }),+}));++jest.mock('~/models', () => ({+ deleteRefreshTokenBridges: jest.fn(),+ upsertRefreshTokenBridge: jest.fn(),+ findRefreshTokenBridge: jest.fn(),+}));++const { encryptV2, decryptV2 } = require('@librechat/data-schemas');+const { math } = require('@librechat/api');+const db = require('~/models');+const {+ createRefreshTokenBridgeFlightKey,+ deleteAllRefreshTokenBridges,+ deleteRefreshTokenBridges,+ storeRefreshTokenBridge,+ getRefreshTokenBridge,+ __internals,+} = require('./RefreshTokenBridge');++describe('RefreshTokenBridge', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ db.upsertRefreshTokenBridge.mockResolvedValue({});+ db.findRefreshTokenBridge.mockResolvedValue(null);+ db.deleteRefreshTokenBridges.mockResolvedValue({ acknowledged: true, deletedCount: 1 });+ });++ describe('storeRefreshTokenBridge', () => {+ it('stores an encrypted Mongo bridge with required fields', async () => {+ const before = Date.now();++ await storeRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-new',+ userId: 'user-123',+ });++ expect(encryptV2).toHaveBeenCalledWith('rt-new');+ expect(db.upsertRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshTokenHash: __internals.hashRefreshToken('rt-old'),+ encryptedNewRefreshToken: 'encrypted:rt-new',+ userId: 'user-123',+ tenantId: undefined,+ openidIssuer: undefined,+ version: expect.any(String),+ expiresAt: expect.any(Date),+ });+ const stored = db.upsertRefreshTokenBridge.mock.calls[0][0];+ expect(JSON.stringify(stored)).not.toContain('"rt-new"');+ expect(stored.expiresAt.getTime()).toBeGreaterThanOrEqual(before + 604800000 - 1000);+ });++ it('stores optional tenant and issuer context', async () => {+ await storeRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-new',+ userId: ' user-123 ',+ tenantId: ' tenant-1 ',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ });++ expect(db.upsertRefreshTokenBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ userId: 'user-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ }),+ );+ });++ it('does not store a bridge without required fields', async () => {+ await storeRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ userId: 'user-123',+ });++ expect(db.upsertRefreshTokenBridge).not.toHaveBeenCalled();+ });++ it('honors an explicit ttl override', async () => {+ const before = Date.now();++ await storeRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-new',+ userId: 'user-123',+ ttl: 1000,+ });++ const stored = db.upsertRefreshTokenBridge.mock.calls[0][0];+ expect(stored.expiresAt.getTime()).toBeGreaterThanOrEqual(before + 1000);+ expect(stored.expiresAt.getTime()).toBeLessThanOrEqual(Date.now() + 1000);+ });++ it('derives the default ttl from REFRESH_TOKEN_EXPIRY', async () => {+ await storeRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ newRefreshToken: 'rt-new',+ userId: 'user-123',+ });++ expect(math).toHaveBeenCalledWith(process.env.REFRESH_TOKEN_EXPIRY, 604800000);+ });+ });++ describe('coordination and revocation', () => {+ it('creates a stable opaque flight key scoped to token and identity', () => {+ const key = createRefreshTokenBridgeFlightKey({+ oldRefreshToken: 'rt-old',+ userId: ' user-123 ',+ tenantId: ' tenant-1 ',+ openidIssuer: 'https://issuer.example.com/',+ });++ expect(key).toHaveLength(64);+ expect(key).not.toContain('rt-old');+ expect(key).toBe(+ createRefreshTokenBridgeFlightKey({+ oldRefreshToken: 'rt-old',+ userId: 'user-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ }),+ );+ });++ it('deletes bridge hashes for all distinct logout tokens', async () => {+ await deleteRefreshTokenBridges({+ refreshTokens: ['cookie-token', 'session-token', 'cookie-token'],+ userId: ' user-123 ',+ tenantId: ' tenant-1 ',+ });++ expect(db.deleteRefreshTokenBridges).toHaveBeenCalledWith({+ oldRefreshTokenHashes: [+ __internals.hashRefreshToken('cookie-token'),+ __internals.hashRefreshToken('session-token'),+ ],+ userId: 'user-123',+ tenantId: 'tenant-1',+ });+ });++ it('deletes every predecessor bridge for a logout identity', async () => {+ await deleteAllRefreshTokenBridges({ userId: ' user-123 ', tenantId: ' tenant-1 ' });++ expect(db.deleteRefreshTokenBridges).toHaveBeenCalledWith({+ userId: 'user-123',+ tenantId: 'tenant-1',+ });+ });+ });++ describe('getRefreshTokenBridge', () => {+ it('retrieves and decrypts a matching bridge', async () => {+ db.findRefreshTokenBridge.mockResolvedValue({+ encryptedNewRefreshToken: 'encrypted:rt-new',+ userId: 'user-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ createdAt: new Date(Date.now() - 100),+ });++ const result = await getRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ userId: ' user-123 ',+ tenantId: ' tenant-1 ',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ });++ expect(db.findRefreshTokenBridge).toHaveBeenCalledWith({+ oldRefreshTokenHash: __internals.hashRefreshToken('rt-old'),+ userId: 'user-123',+ tenantId: 'tenant-1',+ });+ expect(decryptV2).toHaveBeenCalledWith('encrypted:rt-new');+ expect(result).toBe('rt-new');+ });++ it('returns null when bridge does not exist', async () => {+ await expect(+ getRefreshTokenBridge({+ oldRefreshToken: 'rt-nonexistent',+ userId: 'user-123',+ }),+ ).resolves.toBeNull();+ });++ it('returns null when stored issuer does not match', async () => {+ db.findRefreshTokenBridge.mockResolvedValue({+ encryptedNewRefreshToken: 'encrypted:rt-new',+ userId: 'user-123',+ openidIssuer: 'https://issuer1.example.com',+ createdAt: new Date(),+ });++ const result = await getRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ userId: 'user-123',+ openidIssuer: 'https://issuer2.example.com',+ });++ expect(result).toBeNull();+ expect(decryptV2).not.toHaveBeenCalled();+ });++ it('returns null when only the expected issuer is present', async () => {+ db.findRefreshTokenBridge.mockResolvedValue({+ encryptedNewRefreshToken: 'encrypted:rt-new',+ userId: 'user-123',+ createdAt: new Date(),+ });++ const result = await getRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ userId: 'user-123',+ openidIssuer: 'https://issuer.example.com',+ });++ expect(result).toBeNull();+ expect(decryptV2).not.toHaveBeenCalled();+ });++ it('returns null when only the stored issuer is present', async () => {+ db.findRefreshTokenBridge.mockResolvedValue({+ encryptedNewRefreshToken: 'encrypted:rt-new',+ userId: 'user-123',+ openidIssuer: 'https://issuer.example.com',+ createdAt: new Date(),+ });++ const result = await getRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ userId: 'user-123',+ });++ expect(result).toBeNull();+ expect(decryptV2).not.toHaveBeenCalled();+ });++ it('normalizes the stored issuer before validation', async () => {+ db.findRefreshTokenBridge.mockResolvedValue({+ encryptedNewRefreshToken: 'encrypted:rt-new',+ userId: 'user-123',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ createdAt: new Date(),+ });++ const result = await getRefreshTokenBridge({+ oldRefreshToken: 'rt-old',+ userId: 'user-123',+ openidIssuer: 'https://issuer.example.com/',+ });++ expect(decryptV2).toHaveBeenCalledWith('encrypted:rt-new');+ expect(result).toBe('rt-new');+ });+ });+});diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.jsindex 7d5a161896..200f81fbd0 100644--- a/api/server/services/ToolService.js+++ b/api/server/services/ToolService.js@@ -1,4 +1,4 @@-const { logger, redactMessage } = require('@librechat/data-schemas');+const { logger, redactMessage, getTenantId } = require('@librechat/data-schemas');const { tool: toolFn, DynamicStructuredTool } = require('@librechat/agents/langchain/tools');const {sleep,@@ -11,6 +11,7 @@ const {sendEvent,getToolkitKey,getUserMCPAuthMap,+ createAuthIdentityContext,loadToolDefinitions,GenerationJobManager,isActionDomainAllowed,@@ -95,6 +96,7 @@ const {getAccessibleMcpServerNames,resolveCollisionAuditNames,} = require('~/server/services/MCP');+const { createOpenIDSessionTokenProvider } = require('~/server/services/OpenIDSessionRefresh');const { getMCPRequestContext } = require('~/server/services/MCPRequestContext');const { recordUsage } = require('~/server/services/Threads');const { loadTools } = require('~/app/clients/tools/util');@@ -921,6 +923,23 @@ async function loadToolDefinitionsWrapper({/** @type {Record<string, import('@librechat/api').LCAvailableTools>} */const mcpAvailableTools = {};const requestScopedConnections = getMCPRequestContext(req, res);+ /**+ * Build the OBO upstream-token closure once at this request boundary and pass+ * the function into MCP handling, so `reinitMCPServer` never receives the raw+ * Express request. `res` is forwarded so a rotated refresh token can be+ * mirrored to the `refreshToken` cookie when the response is still writable.+ */+ const oboIdentityContext = createAuthIdentityContext({+ user: req.user,+ tenantId: getTenantId(),+ });+ const upstreamTokenProvider = createOpenIDSessionTokenProvider({+ req,+ res,+ user: req.user,+ identityContext: oboIdentityContext,+ tokenPreference: 'access_token',+ });const rememberMCPAvailableTools = (serverName, availableTools) => {if (!availableTools || Object.keys(availableTools).length === 0) {return;@@ -1106,6 +1125,8 @@ async function loadToolDefinitionsWrapper({userMCPAuthMap,requestBody: runtimeRequestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,});rememberMCPAvailableTools(serverName, result?.availableTools);@@ -1133,6 +1154,8 @@ async function loadToolDefinitionsWrapper({userMCPAuthMap,requestBody: runtimeRequestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,});rememberMCPAvailableTools(serverName, result?.availableTools);@@ -1278,6 +1301,8 @@ async function loadToolDefinitionsWrapper({oauthStart,oauthEnd: createOAuthEndEmitter(serverName),connectionTimeout: Time.TWO_MINUTES,+ upstreamTokenProvider,+ oboIdentityContext,});if (result?.availableTools && Object.keys(result.availableTools).length > 0) {diff --git a/api/server/services/Tools/mcp.js b/api/server/services/Tools/mcp.jsindex 9532d526b7..c74b80ce10 100644--- a/api/server/services/Tools/mcp.js+++ b/api/server/services/Tools/mcp.js@@ -26,6 +26,8 @@ const MCP_REINITIALIZE_FAILURE_REASONS = {* (per MCP spec, tool listing should be possible without auth).* @param {Object} params* @param {IUser} params.user - The user from the request object.+ * @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO connection establishment, built at the request boundary so this layer never receives the raw Express request.+ * @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.* @param {string} params.serverName - The name of the MCP server* @param {boolean} params.returnOnOAuth - Whether to initiate OAuth and return, or wait for OAuth flow to finish* @param {AbortSignal} [params.signal] - The abort signal to handle cancellation.@@ -52,6 +54,8 @@ async function reinitMCPServer({serverConfig: providedConfig,requestBody,requestScopedConnections,+ upstreamTokenProvider,+ oboIdentityContext,oauthEnd,}) {/** @type {MCPConnection | null} */@@ -201,6 +205,8 @@ async function reinitMCPServer({graphTokenResolver: getGraphApiToken,oboTokenResolver: exchangeOboToken,oboTrustChecker: createOboTrustChecker(),+ upstreamTokenProvider,+ oboIdentityContext,});logger.info('[MCP Reinitialize] Successfully established connection');@@ -236,6 +242,8 @@ async function reinitMCPServer({graphTokenResolver: getGraphApiToken,oboTokenResolver: exchangeOboToken,oboTrustChecker: createOboTrustChecker(),+ upstreamTokenProvider,+ oboIdentityContext,});if (discoveryResult.tools && discoveryResult.tools.length > 0) {diff --git a/api/server/services/Tools/mcp.spec.js b/api/server/services/Tools/mcp.spec.jsindex 1b0736baba..d5bdeff5f9 100644--- a/api/server/services/Tools/mcp.spec.js+++ b/api/server/services/Tools/mcp.spec.js@@ -251,6 +251,22 @@ describe('reinitMCPServer — customUserVars gating (issue #10969)', () => {);});+ it('forwards the pre-built upstreamTokenProvider closure into connection creation', async () => {+ mockGetConnection.mockResolvedValue({ fetchTools: jest.fn().mockResolvedValue([]) });+ const upstreamTokenProvider = jest.fn().mockResolvedValue(null);++ await reinitMCPServer({+ user,+ serverName,+ serverConfig: { type: 'streamable-http', url: 'https://thingy.example.com/mcp' },+ upstreamTokenProvider,+ });++ expect(mockGetConnection).toHaveBeenCalledWith(+ expect.objectContaining({ upstreamTokenProvider }),+ );+ });+it('passes request body and Graph resolver into OAuth discovery fallback', async () => {mockGetConnection.mockRejectedValue(new Error('OAuth authentication required'));mockDiscoverServerTools.mockResolvedValue({ tools: [], oauthRequired: true, oauthUrl: null });diff --git a/api/server/services/__tests__/MCP.spec.js b/api/server/services/__tests__/MCP.spec.jsindex 0fae7a3058..e2b8ebca36 100644--- a/api/server/services/__tests__/MCP.spec.js+++ b/api/server/services/__tests__/MCP.spec.js@@ -2,6 +2,8 @@ const mockRegistry = {ensureConfigServers: jest.fn(),getAllServerConfigs: jest.fn(),};+const mockUpstreamTokenProvider = jest.fn().mockResolvedValue(null);+const mockCreateOpenIDSessionTokenProvider = jest.fn(() => mockUpstreamTokenProvider);jest.mock('~/config', () => ({getMCPServersRegistry: jest.fn(() => mockRegistry),@@ -34,6 +36,12 @@ jest.mock('@librechat/api', () => ({GenerationJobManager: jest.fn(),buildOAuthToolCallName: jest.fn((name) => name),getUserMCPAuthMap: jest.fn(),+ createAuthIdentityContext: ({ user, tenantId }) => ({+ appUserId: user?._id?.toString?.() ?? user?.id,+ openidSubject: user?.openidId,+ tenantId: tenantId ?? user?.tenantId,+ openidIssuer: user?.openidIssuer,+ }),/** Mirrors the real resolver so these tests still exercise the wrapper's own* plumbing - loading the request config and degrading on failure - rather than* the resolution logic, which is unit-tested in packages/api. Like the real@@ -66,6 +74,9 @@ jest.mock('~/server/services/OboTokenService', () => ({jest.mock('~/server/services/OboPolicyService', () => ({createOboTrustChecker: jest.fn(() => async () => true),}));+jest.mock('~/server/services/OpenIDSessionRefresh', () => ({+ createOpenIDSessionTokenProvider: (...args) => mockCreateOpenIDSessionTokenProvider(...args),+}));jest.mock('~/server/services/Tools/mcp', () => ({reinitMCPServer: jest.fn(),}));@@ -159,10 +170,11 @@ describe('getAssistantToolDefinitions', () => {const getServerToolFunctionsSnapshot = jest.fn().mockResolvedValue({ tools: null });require('~/config').getMCPManager.mockReturnValue({ getServerToolFunctionsSnapshot });const userMCPAuthMap = { 'mcp_app-server': { API_KEY: 'saved' } };+ const res = { cookie: jest.fn() };getUserMCPAuthMap.mockResolvedValue(userMCPAuthMap);reinitMCPServer.mockResolvedValue({ availableTools: { [toolKey]: mcpDefinition } });- await expect(getAssistantToolDefinitions({ req, tools: [toolKey] })).resolves.toEqual({+ await expect(getAssistantToolDefinitions({ req, res, tools: [toolKey] })).resolves.toEqual({toolDefinitions: { [toolKey]: mcpDefinition },accessibleServerNames: ['app-server'],});@@ -171,6 +183,25 @@ describe('getAssistantToolDefinitions', () => {serverName: 'app-server',serverConfig,userMCPAuthMap,+ upstreamTokenProvider: mockUpstreamTokenProvider,+ oboIdentityContext: {+ appUserId: 'u1',+ openidSubject: undefined,+ tenantId: 'tenant-1',+ openidIssuer: undefined,+ },+ });+ expect(mockCreateOpenIDSessionTokenProvider).toHaveBeenCalledWith({+ req,+ res,+ user: req.user,+ identityContext: {+ appUserId: 'u1',+ openidSubject: undefined,+ tenantId: 'tenant-1',+ openidIssuer: undefined,+ },+ tokenPreference: 'access_token',});expect(getUserMCPAuthMap).toHaveBeenCalledWith({userId: 'u1',diff --git a/api/server/services/__tests__/ToolService.spec.js b/api/server/services/__tests__/ToolService.spec.jsindex 4281e485ea..c92edd971b 100644--- a/api/server/services/__tests__/ToolService.spec.js+++ b/api/server/services/__tests__/ToolService.spec.js@@ -69,6 +69,12 @@ jest.mock('@librechat/api', () => ({['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),loadToolDefinitions: (...args) => mockLoadToolDefinitions(...args),getUserMCPAuthMap: (...args) => mockGetUserMCPAuthMap(...args),+ createAuthIdentityContext: ({ user, tenantId }) => ({+ appUserId: user?._id?.toString?.() ?? user?.id,+ openidSubject: user?.openidId,+ tenantId: tenantId ?? user?.tenantId,+ openidIssuer: user?.openidIssuer,+ }),sendEvent: (...args) => mockSendEvent(...args),GenerationJobManager: {emitChunk: (...args) => mockEmitChunk(...args),@@ -2069,6 +2075,56 @@ describe('ToolService - Action Capability Gating', () => {);});+ it('forwards OBO context through forced MCP catalog refreshes', async () => {+ const serverName = 'OBO-Refresh';+ const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;+ const capabilities = [AgentCapabilities.tools];+ const req = createMockReq(capabilities);+ req.user = {+ id: 'user_123',+ provider: 'openid',+ openidId: 'oidc-sub-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ };++ mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));+ mockGetServerConfig.mockResolvedValue({+ type: 'streamable-http',+ url: 'https://mcp.example.com/obo',+ obo: { scopes: 'api://obo/Mcp.Tools.ReadWrite' },+ });+ mockLoadToolDefinitions.mockImplementation(async (params, dependencies) => {+ await dependencies.refreshMCPServerTools(params.userId, serverName);+ return {+ toolDefinitions: [],+ toolRegistry: new Map(),+ hasDeferredTools: false,+ };+ });+ reinitMCPServer.mockResolvedValue({ availableTools: {} });++ await loadAgentTools({+ req,+ agent: { id: 'agent_123', tools: [mcpTool] },+ definitionsOnly: true,+ });++ expect(reinitMCPServer).toHaveBeenCalledWith(+ expect.objectContaining({+ serverName,+ forceNew: true,+ upstreamTokenProvider: expect.any(Function),+ oboIdentityContext: expect.objectContaining({+ appUserId: 'user_123',+ openidSubject: 'oidc-sub-123',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ }),+ }),+ );+ });+it('returns run-scoped MCP tool definitions for request-scoped servers', async () => {const serverName = 'ClickHouse';const mcpTool = `list_tables${Constants.mcp_delimiter}${serverName}`;diff --git a/api/strategies/openidStrategy.spec.js b/api/strategies/openidStrategy.spec.jsindex 36a491a068..641619d100 100644--- a/api/strategies/openidStrategy.spec.js+++ b/api/strategies/openidStrategy.spec.js@@ -1138,10 +1138,12 @@ describe('setupOpenId', () => {// First call: cache miss → OBO exchange → cache setawait validate(tokenset);+ /** The entry expires 30s (OPENID_EXPIRY_BUFFER_SECONDS) before the credential it holds, so a+ * token served from cache cannot expire in transit and 401 downstream. */expect(mockSet).toHaveBeenCalledWith('1234:overage',{ access_token: 'exchanged_graph_token' },- 3600000,+ 3570000,);expect(openidClient.genericGrantRequest).toHaveBeenCalledTimes(1);diff --git a/packages/api/src/auth/index.ts b/packages/api/src/auth/index.tsindex 5e1da8e1c5..f6e8956439 100644--- a/packages/api/src/auth/index.ts+++ b/packages/api/src/auth/index.ts@@ -12,3 +12,4 @@ export * from './codeapi';export * from './openidRoleSync';export * from './userDocCache';export * from './reuse';+export * from './openid/index';diff --git a/packages/api/src/auth/openid/bridge.ts b/packages/api/src/auth/openid/bridge.tsnew file mode 100644index 0000000000..e86c7c9766--- /dev/null+++ b/packages/api/src/auth/openid/bridge.ts@@ -0,0 +1,220 @@+import crypto from 'node:crypto';+import type {+ RefreshTokenBridgeDeleteInput,+ RefreshTokenBridgeIdentity,+ RefreshTokenBridgeInput,+ OpenIDLogger,+} from './types';++interface StoredRefreshTokenBridge {+ encryptedNewRefreshToken: string;+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+ version?: string;+ createdAt: Date | string;+}++interface BridgeQuery {+ oldRefreshTokenHash?: string;+ oldRefreshTokenHashes?: string[];+ encryptedNewRefreshToken?: string;+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+ version?: string;+ expiresAt?: Date;+}++type IdentityInput = Partial<RefreshTokenBridgeIdentity>;++export interface RefreshTokenBridgeService {+ OPENID_REFRESH_BRIDGE_GRACE_MS: number;+ createRefreshTokenBridgeFlightKey: (args: {+ oldRefreshToken?: string;+ userId?: string;+ tenantId?: string;+ openidIssuer?: string;+ }) => string | null;+ deleteAllRefreshTokenBridges: (args: {+ userId?: string;+ tenantId?: string;+ }) => Promise<object | null>;+ deleteRefreshTokenBridges: (args: RefreshTokenBridgeDeleteInput) => Promise<object | null>;+ storeRefreshTokenBridge: (args: RefreshTokenBridgeInput) => Promise<string | null>;+ getRefreshTokenBridge: (args: {+ oldRefreshToken?: string;+ userId?: string;+ tenantId?: string;+ openidIssuer?: string;+ }) => Promise<string | null>;+ __internals: {+ hashRefreshToken: (refreshToken: string) => string;+ getBridgeTtlMs: () => number;+ resolveBridgeIdentity: (input: IdentityInput) => RefreshTokenBridgeIdentity | null;+ };+}++export interface RefreshTokenBridgeDeps {+ db: {+ upsertRefreshTokenBridge: (data: BridgeQuery) => Promise<StoredRefreshTokenBridge | null>;+ findRefreshTokenBridge: (data: BridgeQuery) => Promise<StoredRefreshTokenBridge | null>;+ deleteRefreshTokenBridges: (data: BridgeQuery) => Promise<object>;+ };+ logger: Pick<OpenIDLogger, 'warn' | 'debug' | 'info'>;+ encrypt: (value: string) => Promise<string>;+ decrypt: (value: string) => Promise<string>;+ math: (value: string | undefined, fallback: number) => number;+ defaultRefreshTokenExpiry: number;+ createIdentity: (data: IdentityInput) => RefreshTokenBridgeIdentity | null;+}++export function createRefreshTokenBridgeService(+ deps: RefreshTokenBridgeDeps,+): RefreshTokenBridgeService {+ const { db, logger, encrypt, decrypt, math, defaultRefreshTokenExpiry, createIdentity } = deps;+ const OPENID_REFRESH_BRIDGE_GRACE_MS = math(+ process.env.OPENID_REFRESH_BRIDGE_GRACE_MS,+ 60 * 1000,+ );+ const getBridgeTtlMs = () => math(process.env.REFRESH_TOKEN_EXPIRY, defaultRefreshTokenExpiry);+ const resolveBridgeIdentity = ({ userId, tenantId, openidIssuer }: IdentityInput) =>+ createIdentity({ userId, tenantId, openidIssuer });+ const hashRefreshToken = (refreshToken: string) =>+ crypto.createHash('sha256').update(refreshToken).digest('hex');++ function createRefreshTokenBridgeFlightKey({+ oldRefreshToken,+ userId,+ tenantId,+ openidIssuer,+ }: {+ oldRefreshToken?: string;+ userId?: string;+ tenantId?: string;+ openidIssuer?: string;+ }) {+ const identity = resolveBridgeIdentity({ userId, tenantId, openidIssuer });+ if (!oldRefreshToken || !identity) return null;+ return hashRefreshToken(+ [+ 'bridge-recovery',+ identity.userId,+ identity.tenantId ?? '',+ identity.openidIssuer ?? '',+ hashRefreshToken(oldRefreshToken),+ ].join('\x1f'),+ );+ }++ async function storeRefreshTokenBridge({+ oldRefreshToken,+ newRefreshToken,+ userId,+ tenantId,+ openidIssuer,+ ttl,+ }: RefreshTokenBridgeInput): Promise<string | null> {+ const identity = resolveBridgeIdentity({ userId, tenantId, openidIssuer });+ if (!oldRefreshToken || !newRefreshToken || !identity) {+ logger.warn('[RefreshTokenBridge] Attempted to store bridge with missing required fields');+ return null;+ }+ const oldRefreshTokenHash = hashRefreshToken(oldRefreshToken);+ const bridgeTtl = ttl ?? getBridgeTtlMs();+ const version = crypto.randomUUID();+ await db.upsertRefreshTokenBridge({+ oldRefreshTokenHash,+ encryptedNewRefreshToken: await encrypt(newRefreshToken),+ userId: identity.userId,+ tenantId: identity.tenantId,+ openidIssuer: identity.openidIssuer,+ version,+ expiresAt: new Date(Date.now() + bridgeTtl),+ });+ logger.debug('[RefreshTokenBridge] Stored recovery bridge', {+ tokenHash: oldRefreshTokenHash,+ userId: identity.userId,+ ttl: bridgeTtl,+ });+ return version;+ }++ async function getRefreshTokenBridge({+ oldRefreshToken,+ userId,+ tenantId,+ openidIssuer,+ }: {+ oldRefreshToken?: string;+ userId?: string;+ tenantId?: string;+ openidIssuer?: string;+ }): Promise<string | null> {+ const identity = resolveBridgeIdentity({ userId, tenantId, openidIssuer });+ if (!oldRefreshToken || !identity) return null;+ const oldRefreshTokenHash = hashRefreshToken(oldRefreshToken);+ const bridge = await db.findRefreshTokenBridge({+ oldRefreshTokenHash,+ userId: identity.userId,+ tenantId: identity.tenantId,+ });+ if (!bridge) return null;+ const bridgeIdentity = resolveBridgeIdentity({+ userId: bridge.userId,+ tenantId: bridge.tenantId,+ openidIssuer: bridge.openidIssuer,+ });+ if (!bridgeIdentity || bridgeIdentity.openidIssuer !== identity.openidIssuer) {+ logger.warn('[RefreshTokenBridge] Bridge lookup failed: issuer mismatch', {+ tokenHash: oldRefreshTokenHash,+ });+ return null;+ }+ logger.info('[RefreshTokenBridge] Successfully resolved recovery bridge', {+ tokenHash: oldRefreshTokenHash,+ userId: identity.userId,+ age: Date.now() - new Date(bridge.createdAt).getTime(),+ });+ return decrypt(bridge.encryptedNewRefreshToken);+ }++ async function deleteRefreshTokenBridges({+ refreshTokens,+ userId,+ tenantId,+ version,+ }: RefreshTokenBridgeDeleteInput): Promise<object | null> {+ const identity = resolveBridgeIdentity({ userId, tenantId });+ const tokens = [...new Set<string>((refreshTokens ?? []).filter(Boolean))];+ if (!identity || tokens.length === 0) return null;+ return db.deleteRefreshTokenBridges({+ oldRefreshTokenHashes: tokens.map(hashRefreshToken),+ userId: identity.userId,+ tenantId: identity.tenantId,+ version,+ });+ }++ async function deleteAllRefreshTokenBridges({+ userId,+ tenantId,+ }: {+ userId?: string;+ tenantId?: string;+ }): Promise<object | null> {+ const identity = resolveBridgeIdentity({ userId, tenantId });+ if (!identity) return null;+ return db.deleteRefreshTokenBridges({ userId: identity.userId, tenantId: identity.tenantId });+ }++ return {+ OPENID_REFRESH_BRIDGE_GRACE_MS,+ createRefreshTokenBridgeFlightKey,+ deleteAllRefreshTokenBridges,+ deleteRefreshTokenBridges,+ storeRefreshTokenBridge,+ getRefreshTokenBridge,+ __internals: { hashRefreshToken, getBridgeTtlMs, resolveBridgeIdentity },+ };+}diff --git a/packages/api/src/auth/openid/errors.ts b/packages/api/src/auth/openid/errors.tsnew file mode 100644index 0000000000..9c762cf972--- /dev/null+++ b/packages/api/src/auth/openid/errors.ts@@ -0,0 +1,26 @@+import type { LogArgument } from './types';++export const OPENID_REFRESH_OWNERSHIP_LOST = 'OPENID_REFRESH_OWNERSHIP_LOST';++export function toOpenIDLogArgument(error: unknown): LogArgument {+ return error instanceof Error ? error : String(error);+}++/**+ * Marks the one failure mode that proves another worker owns this refresh: the coordination+ * record is no longer pending under our owner id. Callers that compensate a published side+ * effect must distinguish it from a transient coordination read failure, where ownership is+ * merely unknown and the side effect is still the caller's only usable credential.+ */+export function createOpenIDRefreshOwnershipError(message: string): Error {+ return Object.assign(new Error(message), { code: OPENID_REFRESH_OWNERSHIP_LOST });+}++export function isOpenIDRefreshOwnershipError(error: unknown): boolean {+ return (+ typeof error === 'object' &&+ error !== null &&+ 'code' in error &&+ error.code === OPENID_REFRESH_OWNERSHIP_LOST+ );+}diff --git a/packages/api/src/auth/openid/flight.ts b/packages/api/src/auth/openid/flight.tsnew file mode 100644index 0000000000..7500e3cbed--- /dev/null+++ b/packages/api/src/auth/openid/flight.ts@@ -0,0 +1,666 @@+import crypto from 'node:crypto';+import { setTimeout as delay } from 'node:timers/promises';+import type {+ AuthIdentityContext,+ LeaseContext,+ OpenIDLogger,+ OpenIDClaims,+ OpenIDTokenSet,+ RefreshFlightAcquireResult,+ RefreshFlightRecord,+ RefreshKeyInput,+} from './types';+import {+ createOpenIDRefreshOwnershipError,+ isOpenIDRefreshOwnershipError,+ toOpenIDLogArgument,+} from './errors';+import { createOpenIDRefreshIdentityTuple, serializeAuthIdentityTuple } from '~/utils/identity';+import { OPENID_EXPIRY_BUFFER_SECONDS } from '~/oauth/expiry';++const DEFAULT_FLIGHT_TTL_MS = 2 * 60 * 1000;+const DEFAULT_LOCK_TTL_MS = 30 * 1000;+const DEFAULT_WAIT_TIMEOUT_MS = DEFAULT_FLIGHT_TTL_MS;+const DEFAULT_WAIT_INTERVAL_MS = 100;+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10 * 1000;+const DEFAULT_DELIVERY_TTL_MS = 30 * 1000;+const INTERNAL_BROWSER_REFRESH_TOKEN_FIELD = '__browserRefreshToken';+const INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD = '__predecessorRefreshToken';+const INTERNAL_PREDECESSOR_ACCESS_TOKEN_FIELD = '__predecessorAccessToken';+const INTERNAL_DEFERRED_PUBLICATION_FIELD = '__deferredPublication';+const INTERNAL_FLIGHT_OWNER_FIELD = '__flightOwnerId';+const INTERNAL_FLIGHT_CREATED_AT_FIELD = '__flightCreatedAt';++export interface TokenResult extends Omit<OpenIDTokenSet, 'claims'> {+ tokenset?: OpenIDTokenSet;+ claims?: OpenIDClaims | (() => OpenIDClaims);+ openidIssuer?: string;+ __browserRefreshToken?: string;+ __predecessorRefreshToken?: string;+ __predecessorAccessToken?: string;+ __deferredPublication?: boolean;+ __flightOwnerId?: string;+ __flightCreatedAt?: number;+ predecessorAccessToken?: string;+ acceptedIdentity?: AuthIdentityContext;+}++interface FlightAcquireData {+ key: string;+ ownerId: string;+ lockExpiresAt: Date;+ expiresAt: Date;+}++interface FlightOwnerData {+ key: string;+ ownerId: string;+ expiresAt: Date;+}++interface FlightCompleteData extends FlightOwnerData {+ encryptedResult: string;+}++interface FlightRenewData extends FlightOwnerData {+ lockExpiresAt: Date;+}++interface FlightFailData extends FlightOwnerData {+ errorMessage: string;+}++interface FlightDeliveryData {+ key: string;+ ownerId: string;+ deliveryId: string;+}++export interface OpenIDRefreshFlightService {+ acquireOpenIDRefreshFlight: (args: {+ key?: string | null;+ ownerId?: string;+ ttl?: number;+ lockTtl?: number;+ }) => Promise<RefreshFlightAcquireResult>;+ completeOpenIDRefreshFlight: (args: {+ key?: string | null;+ ownerId?: string;+ tokens?: TokenResult | null;+ ttl?: number;+ }) => Promise<RefreshFlightRecord | null>;+ createOpenIDRefreshFlightKey: (input: RefreshKeyInput) => string | null;+ failOpenIDRefreshFlight: (args: {+ key?: string | null;+ ownerId?: string;+ error?: Error | { message?: string } | null;+ ttl?: number;+ }) => Promise<RefreshFlightRecord | null>;+ renewOpenIDRefreshFlight: (args: {+ key?: string | null;+ ownerId?: string;+ lockTtl?: number;+ ttl?: number;+ }) => Promise<RefreshFlightRecord | null>;+ assertOpenIDRefreshFlightAvailable: (args: {+ key?: string | null;+ ownerId?: string;+ }) => Promise<RefreshFlightRecord | boolean>;+ assertOpenIDRefreshSessionGenerationAvailable: (args: {+ key?: string | null;+ ownerId?: string;+ }) => Promise<RefreshFlightRecord | boolean>;+ claimOpenIDRefreshFlightDelivery: (args: {+ key: string;+ ownerId: string;+ createdAt?: number;+ deliveryId?: string;+ ttl?: number;+ }) => Promise<RefreshFlightRecord>;+ assertOpenIDRefreshFlightDeliveryAvailable: (args: FlightDeliveryData) => Promise<void>;+ releaseOpenIDRefreshFlightDelivery: (args: FlightDeliveryData) => Promise<void>;+ revokeOpenIDRefreshFlights: (args: {+ keys?: Array<string | null | undefined>;+ ttl?: number;+ }) => Promise<Array<TokenResult | null>>;+ waitForOpenIDRefreshFlight: (args: {+ key?: string | null;+ timeoutMs?: number;+ intervalMs?: number;+ }) => Promise<TokenResult | null>;+ withOpenIDRefreshFlightLease: <T>(args: {+ key?: string | null;+ ownerId?: string;+ operation: (context: LeaseContext) => Promise<T>;+ heartbeatInterval?: number;+ lockTtl?: number;+ ttl?: number;+ }) => Promise<T>;+ __internals: {+ sha256: (value: string) => string;+ readCompletedFlight: (flight: RefreshFlightRecord | null) => Promise<TokenResult | null>;+ DEFAULT_FLIGHT_TTL_MS: number;+ DEFAULT_LOCK_TTL_MS: number;+ DEFAULT_WAIT_TIMEOUT_MS: number;+ DEFAULT_WAIT_INTERVAL_MS: number;+ DEFAULT_HEARTBEAT_INTERVAL_MS: number;+ DEFAULT_DELIVERY_TTL_MS: number;+ INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD: string;+ getRenewedWaitDeadline: (deadline: number, flight: RefreshFlightRecord | null) => number;+ };+}++export interface OpenIDRefreshFlightDeps {+ db: {+ acquireOpenIDRefreshFlight: (+ data: FlightAcquireData,+ ) => Promise<{ acquired: boolean; flight?: RefreshFlightRecord | null }>;+ completeOpenIDRefreshFlight: (data: FlightCompleteData) => Promise<RefreshFlightRecord | null>;+ renewOpenIDRefreshFlight: (data: FlightRenewData) => Promise<RefreshFlightRecord | null>;+ failOpenIDRefreshFlight: (data: FlightFailData) => Promise<RefreshFlightRecord | null>;+ revokeOpenIDRefreshFlight: (data: {+ key: string;+ expiresAt: Date;+ }) => Promise<RefreshFlightRecord | null>;+ findOpenIDRefreshFlight: (data: { key: string }) => Promise<RefreshFlightRecord | null>;+ claimOpenIDRefreshFlightDelivery: (+ data: FlightDeliveryData & { deliveryExpiresAt: Date; createdAt?: Date },+ ) => Promise<RefreshFlightRecord | null>;+ releaseOpenIDRefreshFlightDelivery: (+ data: FlightDeliveryData,+ ) => Promise<RefreshFlightRecord | null>;+ };+ logger: Pick<OpenIDLogger, 'warn'>;+ encrypt: (value: string) => Promise<string>;+ decrypt: (value: string) => Promise<string>;+}++export function createOpenIDRefreshFlightService({+ db,+ logger,+ encrypt,+ decrypt,+}: OpenIDRefreshFlightDeps): OpenIDRefreshFlightService {+ const sha256 = (value: string): string => crypto.createHash('sha256').update(value).digest('hex');++ function createOpenIDRefreshFlightKey({+ req,+ user,+ refreshToken,+ identityContext,+ }: RefreshKeyInput): string | null {+ const identitySource = identityContext+ ? {+ id: identityContext.appUserId,+ openidId: identityContext.openidSubject,+ tenantId: identityContext.tenantId,+ openidIssuer: identityContext.openidIssuer,+ }+ : user;+ const tuple = createOpenIDRefreshIdentityTuple({+ user: identitySource,+ requestUser: req?.user,+ });+ if (!tuple || !refreshToken) return null;+ return sha256([serializeAuthIdentityTuple(tuple), sha256(refreshToken)].join('\x1f'));+ }++ async function acquireOpenIDRefreshFlight({+ key,+ ownerId = crypto.randomUUID(),+ ttl = DEFAULT_FLIGHT_TTL_MS,+ lockTtl = DEFAULT_LOCK_TTL_MS,+ }: {+ key?: string | null;+ ownerId?: string;+ ttl?: number;+ lockTtl?: number;+ }): Promise<RefreshFlightAcquireResult> {+ if (!key) return { acquired: true, key: null, ownerId, flight: null };+ const acquired = await db.acquireOpenIDRefreshFlight({+ key,+ ownerId,+ lockExpiresAt: new Date(Date.now() + lockTtl),+ expiresAt: new Date(Date.now() + ttl),+ });+ return { ...acquired, key, ownerId };+ }++ async function completeOpenIDRefreshFlight({+ key,+ ownerId,+ tokens,+ ttl = DEFAULT_FLIGHT_TTL_MS,+ }: {+ key?: string | null;+ ownerId?: string;+ tokens?: TokenResult | null;+ ttl?: number;+ }): Promise<RefreshFlightRecord | null> {+ if (!key || !ownerId || !tokens) return null;+ const serializedTokens: TokenResult = { ...tokens };+ if (tokens.__browserRefreshToken) {+ serializedTokens.__browserRefreshToken = tokens.__browserRefreshToken;+ }+ if (tokens.__predecessorRefreshToken) {+ serializedTokens.__predecessorRefreshToken = tokens.__predecessorRefreshToken;+ }+ if (tokens.__predecessorAccessToken) {+ serializedTokens.__predecessorAccessToken = tokens.__predecessorAccessToken;+ }+ if (tokens.__deferredPublication) {+ serializedTokens.__deferredPublication = true;+ }+ const accessTokenExpiresAt = Number(tokens.expires_at) * 1000;+ const usableTokenTtl = Number.isFinite(accessTokenExpiresAt)+ ? Math.max(1, accessTokenExpiresAt - Date.now() - OPENID_EXPIRY_BUFFER_SECONDS * 1000)+ : ttl;+ return db.completeOpenIDRefreshFlight({+ key,+ ownerId,+ encryptedResult: await encrypt(JSON.stringify(serializedTokens)),+ expiresAt: new Date(Date.now() + Math.min(ttl, usableTokenTtl)),+ });+ }++ async function renewOpenIDRefreshFlight({+ key,+ ownerId,+ lockTtl = DEFAULT_LOCK_TTL_MS,+ ttl = DEFAULT_FLIGHT_TTL_MS,+ }: {+ key?: string | null;+ ownerId?: string;+ lockTtl?: number;+ ttl?: number;+ }): Promise<RefreshFlightRecord | null> {+ if (!key || !ownerId) return null;+ return db.renewOpenIDRefreshFlight({+ key,+ ownerId,+ lockExpiresAt: new Date(Date.now() + lockTtl),+ expiresAt: new Date(Date.now() + ttl),+ });+ }++ async function assertOpenIDRefreshFlightAvailable({+ key,+ ownerId,+ }: {+ key?: string | null;+ ownerId?: string;+ }): Promise<RefreshFlightRecord | boolean> {+ if (!key) return true;+ const flight = await db.findOpenIDRefreshFlight({ key });+ if (+ flight?.status === 'completed' &&+ ownerId &&+ flight.ownerId === ownerId &&+ !flight.revocationRequestedAt+ ) {+ return flight;+ }+ throw createOpenIDRefreshOwnershipError(+ 'OpenID refresh result is no longer available for publication',+ );+ }++ /**+ * Validates a generation already installed in an Express session. Completed-flight rows may+ * expire before the session reuse window, so absence is acceptable; an extant row must still+ * name the same completed generation. Logout tombstones and replacement generations fail closed.+ */+ async function assertOpenIDRefreshSessionGenerationAvailable({+ key,+ ownerId,+ }: {+ key?: string | null;+ ownerId?: string;+ }): Promise<RefreshFlightRecord | boolean> {+ if (!key && !ownerId) return true;+ if (!key || !ownerId) {+ throw createOpenIDRefreshOwnershipError(+ 'OpenID session publication generation is incomplete',+ );+ }+ const flight = await db.findOpenIDRefreshFlight({ key });+ if (+ !flight ||+ (flight.status === 'completed' && flight.ownerId === ownerId && !flight.revocationRequestedAt)+ ) {+ return flight ?? true;+ }+ throw createOpenIDRefreshOwnershipError(+ 'OpenID session publication generation is no longer available',+ );+ }++ async function claimOpenIDRefreshFlightDelivery({+ key,+ ownerId,+ createdAt,+ deliveryId = crypto.randomUUID(),+ ttl = DEFAULT_DELIVERY_TTL_MS,+ }: {+ key: string;+ ownerId: string;+ createdAt?: number;+ deliveryId?: string;+ ttl?: number;+ }): Promise<RefreshFlightRecord> {+ const deadline = Date.now() + ttl;+ while (Date.now() <= deadline) {+ const deliveryExpiresAt = new Date(Date.now() + ttl);+ const delivery = await db.claimOpenIDRefreshFlightDelivery({+ key,+ ownerId,+ deliveryId,+ deliveryExpiresAt,+ ...(Number.isFinite(createdAt) ? { createdAt: new Date(createdAt as number) } : {}),+ });+ if (delivery) return delivery;++ const current = await db.findOpenIDRefreshFlight({ key });+ if (!current && Number.isFinite(createdAt)) {+ await delay(DEFAULT_WAIT_INTERVAL_MS);+ continue;+ }+ if (+ current?.status !== 'completed' ||+ current.ownerId !== ownerId ||+ current.revocationRequestedAt+ ) {+ throw createOpenIDRefreshOwnershipError(+ 'OpenID refresh generation is unavailable for response delivery',+ );+ }+ await delay(DEFAULT_WAIT_INTERVAL_MS);+ }+ throw new Error('Timed out waiting to deliver the OpenID refresh generation');+ }++ async function assertOpenIDRefreshFlightDeliveryAvailable({+ key,+ ownerId,+ deliveryId,+ }: FlightDeliveryData): Promise<void> {+ const delivery = await db.findOpenIDRefreshFlight({ key });+ const deliveryExpiresAt = delivery?.deliveryExpiresAt+ ? new Date(delivery.deliveryExpiresAt).getTime()+ : NaN;+ if (+ delivery?.status === 'completed' &&+ delivery.ownerId === ownerId &&+ delivery.deliveryId === deliveryId &&+ !delivery.revocationRequestedAt &&+ Number.isFinite(deliveryExpiresAt) &&+ deliveryExpiresAt > Date.now()+ ) {+ return;+ }+ throw createOpenIDRefreshOwnershipError(+ 'OpenID refresh response delivery authorization was revoked',+ );+ }++ async function releaseOpenIDRefreshFlightDelivery({+ key,+ ownerId,+ deliveryId,+ }: FlightDeliveryData): Promise<void> {+ await db.releaseOpenIDRefreshFlightDelivery({ key, ownerId, deliveryId });+ }++ async function withOpenIDRefreshFlightLease<T>({+ key,+ ownerId,+ operation,+ heartbeatInterval = DEFAULT_HEARTBEAT_INTERVAL_MS,+ lockTtl = DEFAULT_LOCK_TTL_MS,+ ttl = DEFAULT_FLIGHT_TTL_MS,+ }: {+ key?: string | null;+ ownerId?: string;+ operation: (context: LeaseContext) => Promise<T>;+ heartbeatInterval?: number;+ lockTtl?: number;+ ttl?: number;+ }): Promise<T> {+ if (!key || !ownerId)+ return operation({ assertLeaseOwned: async () => true, markLeaseSettled: () => {} });+ let renewalPromise: Promise<RefreshFlightRecord | null> | null = null;+ let ownershipLost = false;+ let settled = false;+ const ownershipError = () =>+ createOpenIDRefreshOwnershipError(+ 'OpenID refresh coordination ownership was lost before completion',+ );+ const renewLease = async () => {+ if (ownershipLost) throw ownershipError();+ if (!renewalPromise)+ renewalPromise = renewOpenIDRefreshFlight({ key, ownerId, lockTtl, ttl }).finally(() => {+ renewalPromise = null;+ });+ const flight = await renewalPromise;+ if (!flight) {+ if (settled) return null;+ const terminalFlight = await db.findOpenIDRefreshFlight({ key });+ if (terminalFlight?.ownerId === ownerId && terminalFlight?.status === 'completed') {+ return terminalFlight;+ }+ ownershipLost = true;+ throw ownershipError();+ }+ return flight;+ };+ const heartbeat = setInterval(() => {+ renewLease().catch((error) =>+ logger.warn('[OpenIDRefreshFlight] Refresh flight lease renewal failed', {+ key,+ error: error?.message,+ }),+ );+ }, heartbeatInterval);+ heartbeat.unref?.();+ let result: T;+ try {+ result = await operation({+ assertLeaseOwned: renewLease,+ markLeaseSettled: () => {+ settled = true;+ },+ });+ if (ownershipLost) throw ownershipError();+ } catch (error) {+ clearInterval(heartbeat);+ if (renewalPromise) {+ try {+ await renewalPromise;+ } catch (cleanupError) {+ logger.warn('[OpenIDRefreshFlight] Lease cleanup also failed after the operation', {+ key,+ error: toOpenIDLogArgument(cleanupError),+ });+ }+ }+ throw error;+ }+ clearInterval(heartbeat);+ if (renewalPromise) {+ try {+ await renewalPromise;+ } catch (error) {+ if (!settled || isOpenIDRefreshOwnershipError(error)) {+ throw error;+ }+ }+ }+ if (ownershipLost) {+ throw ownershipError();+ }+ return result;+ }++ async function failOpenIDRefreshFlight({+ key,+ ownerId,+ error,+ ttl = DEFAULT_FLIGHT_TTL_MS,+ }: {+ key?: string | null;+ ownerId?: string;+ error?: Error | { message?: string } | null;+ ttl?: number;+ }): Promise<RefreshFlightRecord | null> {+ if (!key || !ownerId) return null;+ const errorMessage =+ typeof error?.message === 'string' && error.message ? error.message : 'OpenID refresh failed';+ return db.failOpenIDRefreshFlight({+ key,+ ownerId,+ errorMessage,+ expiresAt: new Date(Date.now() + ttl),+ });+ }++ async function revokeOpenIDRefreshFlights({+ keys,+ ttl = DEFAULT_FLIGHT_TTL_MS,+ }: {+ keys?: Array<string | null | undefined>;+ ttl?: number;+ }): Promise<Array<TokenResult | null>> {+ const uniqueKeys = [...new Set<string>((keys ?? []).filter((key): key is string => !!key))];+ if (uniqueKeys.length === 0) return [];+ const expiresAt = new Date(Date.now() + ttl);+ const revoked = await Promise.all(+ uniqueKeys.map((key) => db.revokeOpenIDRefreshFlight({ key, expiresAt })),+ );+ return Promise.all(+ revoked.map(async (flight) => {+ if (!flight?.encryptedResult) return null;+ return restoreInternalTokenFields(+ JSON.parse(await decrypt(flight.encryptedResult)) as TokenResult,+ );+ }),+ );+ }++ function restoreInternalTokenFields(tokens: TokenResult): TokenResult {+ for (const [field, value] of [+ [INTERNAL_BROWSER_REFRESH_TOKEN_FIELD, tokens.__browserRefreshToken],+ [INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD, tokens.__predecessorRefreshToken],+ [INTERNAL_PREDECESSOR_ACCESS_TOKEN_FIELD, tokens.__predecessorAccessToken],+ [INTERNAL_DEFERRED_PUBLICATION_FIELD, tokens.__deferredPublication],+ ] as const) {+ if (value) {+ delete tokens[field];+ Object.defineProperty(tokens, field, { value, enumerable: false, configurable: true });+ }+ }+ return tokens;+ }++ function attachFlightOwner(+ tokens: TokenResult,+ ownerId?: string,+ createdAt?: Date | string,+ ): TokenResult {+ if (!ownerId) return tokens;+ Object.defineProperty(tokens, INTERNAL_FLIGHT_OWNER_FIELD, {+ value: ownerId,+ enumerable: false,+ configurable: true,+ });+ const createdAtMs = createdAt ? new Date(createdAt).getTime() : NaN;+ if (Number.isFinite(createdAtMs)) {+ Object.defineProperty(tokens, INTERNAL_FLIGHT_CREATED_AT_FIELD, {+ value: createdAtMs,+ enumerable: false,+ configurable: true,+ });+ }+ return tokens;+ }++ async function readCompletedFlight(+ flight: RefreshFlightRecord | null,+ ): Promise<TokenResult | null> {+ if (!flight) return null;+ if (flight.status === 'revoked')+ throw new Error(flight.errorMessage || 'OpenID refresh was revoked by logout');+ if (flight.status === 'failed')+ throw new Error(flight.errorMessage || 'OpenID refresh failed in another worker');+ if (flight.status !== 'completed' || flight.revocationRequestedAt || !flight.encryptedResult)+ return null;+ const tokens = JSON.parse(await decrypt(flight.encryptedResult)) as TokenResult;+ const accessTokenExpiresAt = Number(tokens.expires_at) * 1000;+ if (+ Number.isFinite(accessTokenExpiresAt) &&+ accessTokenExpiresAt <= Date.now() + OPENID_EXPIRY_BUFFER_SECONDS * 1000+ ) {+ return null;+ }+ return attachFlightOwner(restoreInternalTokenFields(tokens), flight.ownerId, flight.createdAt);+ }++ function getRenewedWaitDeadline(deadline: number, flight: RefreshFlightRecord | null): number {+ const renewedExpiry = flight?.expiresAt ? new Date(flight.expiresAt).getTime() : NaN;+ return Number.isFinite(renewedExpiry) ? Math.max(deadline, renewedExpiry) : deadline;+ }++ async function waitForOpenIDRefreshFlight({+ key,+ timeoutMs,+ intervalMs = DEFAULT_WAIT_INTERVAL_MS,+ }: {+ key?: string | null;+ timeoutMs?: number;+ intervalMs?: number;+ }): Promise<TokenResult | null> {+ if (!key) return null;+ const followRenewals = timeoutMs == null;+ let deadline = Date.now() + (timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS);+ while (Date.now() <= deadline) {+ const flight = await db.findOpenIDRefreshFlight({ key });+ const completed = await readCompletedFlight(flight);+ if (completed) return completed;+ if (flight?.status === 'completed') return null;+ if (!flight) return null;+ if (followRenewals) {+ deadline = getRenewedWaitDeadline(deadline, flight);+ }+ await delay(intervalMs);+ }+ logger.warn('[OpenIDRefreshFlight] Timed out waiting for refresh flight', { key });+ return null;+ }++ return {+ acquireOpenIDRefreshFlight,+ assertOpenIDRefreshFlightDeliveryAvailable,+ assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ claimOpenIDRefreshFlightDelivery,+ completeOpenIDRefreshFlight,+ createOpenIDRefreshFlightKey,+ failOpenIDRefreshFlight,+ renewOpenIDRefreshFlight,+ releaseOpenIDRefreshFlightDelivery,+ revokeOpenIDRefreshFlights,+ waitForOpenIDRefreshFlight,+ withOpenIDRefreshFlightLease,+ __internals: {+ sha256,+ readCompletedFlight,+ DEFAULT_FLIGHT_TTL_MS,+ DEFAULT_LOCK_TTL_MS,+ DEFAULT_WAIT_TIMEOUT_MS,+ DEFAULT_WAIT_INTERVAL_MS,+ DEFAULT_HEARTBEAT_INTERVAL_MS,+ DEFAULT_DELIVERY_TTL_MS,+ INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD,+ getRenewedWaitDeadline,+ },+ };+}diff --git a/packages/api/src/auth/openid/index.ts b/packages/api/src/auth/openid/index.tsnew file mode 100644index 0000000000..4d5d56550b--- /dev/null+++ b/packages/api/src/auth/openid/index.ts@@ -0,0 +1,5 @@+export * from './errors';+export * from './flight';+export * from './bridge';+export * from './recovery';+export * from './session';diff --git a/packages/api/src/auth/openid/recovery.ts b/packages/api/src/auth/openid/recovery.tsnew file mode 100644index 0000000000..f08e3edee9--- /dev/null+++ b/packages/api/src/auth/openid/recovery.ts@@ -0,0 +1,1010 @@+import type {+ AuthIdentityContext,+ LeaseAssertion,+ LeaseContext,+ OpenIDClaims,+ OpenIDLogger,+ OpenIDPublicationGeneration,+ OpenIDRefreshResolution,+ OpenIDRequest,+ OpenIDResponse,+ OpenIDTokenSet,+ OpenIDUser,+ RefreshFlightAcquireResult,+ RefreshFlightRecord,+ RefreshTokenBridgeDeleteInput,+ RefreshTokenBridgeIdentity,+ RefreshTokenBridgeInput,+ SharedOpenIDRefreshResult,+ TokenPreference,+} from './types';+import type { TokenResult } from './flight';+import {+ createOpenIDRefreshOwnershipError,+ isOpenIDRefreshOwnershipError,+ toOpenIDLogArgument,+} from './errors';++type FindUser = (...args: Array<string | object | undefined>) => Promise<OpenIDUser | null>;++interface FindOpenIDUserArgs {+ findUser: FindUser;+ email: string;+ openidId: string;+ openidIssuer?: string;+ idOnTheSource?: string;+ strategyName: string;+}++interface RefreshOpenIDUserArgs {+ req: OpenIDRequest;+ res?: OpenIDResponse;+ user: OpenIDUser;+ refreshToken: string;+ browserRefreshToken?: string;+ strategyName: string;+ assertLeaseOwned?: LeaseAssertion;+ deferPublication?: boolean;+}++interface BridgeUser extends OpenIDUser {+ _id: string | number | { toString(): string };+}++interface ResolveOpenIDRefreshInput {+ tokenset: OpenIDTokenSet | null;+ strategyName: string;+}++type SeedRefreshSessionInput = Omit<+ RefreshOpenIDUserArgs,+ 'strategyName' | 'assertLeaseOwned' | 'deferPublication'+>;++interface RecoverOpenIDRefreshBridgeInput {+ req: OpenIDRequest;+ res: OpenIDResponse;+ refreshToken: string;+ bridgedRefreshToken: string;+ bridgeUser: BridgeUser;+}++interface RevokeOpenIDRefreshTokenChainInput {+ req: OpenIDRequest;+ user: OpenIDUser;+ identityContext: AuthIdentityContext;+ refreshTokens: string[];+ publicationKeys?: string[];+ ttl: number;+}++interface SendOpenIDAuthResponseInput {+ tokenset: OpenIDTokenSet;+ user: BridgeUser;+ existingRefreshToken?: string;+ openidSubject?: string;+ openidIssuer?: string;+ predecessorIdentity?: RefreshTokenBridgeIdentity;+ predecessorAccessToken?: string;+ rejectedRefreshTokens?: string[];+ req: OpenIDRequest;+ res: OpenIDResponse;+ assertLeaseOwned?: LeaseAssertion;+ publicationGeneration?: OpenIDPublicationGeneration;+ commitPublication?: (+ appAuthToken: string,+ publishedTokenset: OpenIDTokenSet,+ metadata: {+ predecessorAccessToken?: string;+ acceptedIdentity: AuthIdentityContext;+ },+ ) => Promise<void>;+ preparePublication?: boolean;+}++export interface OpenIDRefreshRecoveryService {+ recoverOpenIDRefreshBridge: (+ input: RecoverOpenIDRefreshBridgeInput,+ ) => Promise<SharedOpenIDRefreshResult>;+ refreshOpenIDUser: (input: RefreshOpenIDUserArgs) => Promise<OpenIDRefreshResolution>;+ resolveOpenIDRefreshResult: (+ input: ResolveOpenIDRefreshInput,+ ) => Promise<OpenIDRefreshResolution>;+ sendOpenIDAuthResponse: (input: SendOpenIDAuthResponseInput) => Promise<string | undefined>;+ revokeOpenIDRefreshTokenChain: (input: RevokeOpenIDRefreshTokenChainInput) => Promise<string[]>;+ __internals: {+ getTokenClaims: (tokenset: OpenIDTokenSet) => OpenIDClaims;+ seedRefreshSession: (input: SeedRefreshSessionInput) => AuthIdentityContext;+ };+}++export interface OpenIDRefreshRecoveryDeps {+ jwt: { decode: (token: string) => OpenIDClaims | string | null };+ logger: Pick<OpenIDLogger, 'debug' | 'warn'>;+ findOpenIDUser: (args: FindOpenIDUserArgs) => Promise<{+ user?: OpenIDUser | null;+ error?: string | null;+ migration?: boolean;+ }>;+ findUser: FindUser;+ getOpenIdConfig: () => object;+ getOpenIdEmail: (claims: OpenIDClaims) => string;+ getOpenIdIssuer: (claims: OpenIDClaims, config: object) => string | undefined;+ createAuthIdentityContext: (args: {+ user?: OpenIDUser;+ requestUser?: OpenIDUser;+ }) => AuthIdentityContext;+ refreshOpenIDSession: (+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ user: OpenIDUser,+ preference: TokenPreference,+ identity: AuthIdentityContext,+ options: {+ forceRefresh: boolean;+ assertLeaseOwned?: LeaseAssertion;+ deferPublication?: boolean;+ },+ ) => Promise<OpenIDTokenSet | null>;+ storeOpenIDSession: (+ userId: string,+ refreshToken: string,+ tenantId?: string,+ previousRefreshToken?: string,+ ) => Promise<void>;+ setOpenIDAuthTokens: (+ tokens: OpenIDTokenSet,+ req: OpenIDRequest,+ res: OpenIDResponse,+ identity: {+ userId: string;+ existingRefreshToken?: string;+ tenantId?: string;+ openidSubject?: string;+ openidIssuer?: string;+ },+ ) => string | undefined;+ getOpenIDAppAuthToken: (tokens: OpenIDTokenSet, sessionIdToken?: string) => string | undefined;+ clearOpenIDAuthTokens: (+ req: OpenIDRequest,+ res: OpenIDResponse,+ userId: string,+ tenantId?: string,+ ) => void;+ deleteOpenIDSession: (refreshToken: string) => Promise<object | null>;+ createRefreshTokenBridgeFlightKey: (args: {+ oldRefreshToken: string;+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+ }) => string | null;+ createOpenIDRefreshFlightKey: (args: {+ req: OpenIDRequest;+ user: OpenIDUser;+ refreshToken: string;+ identityContext: AuthIdentityContext;+ }) => string | null;+ storeRefreshTokenBridge: (args: RefreshTokenBridgeInput) => Promise<string | null>;+ deleteRefreshTokenBridges: (args: RefreshTokenBridgeDeleteInput) => Promise<object | null>;+ acquireOpenIDRefreshFlight: (args: { key: string }) => Promise<RefreshFlightAcquireResult>;+ completeOpenIDRefreshFlight: (args: {+ key: string;+ ownerId: string;+ tokens: SharedOpenIDRefreshResult;+ }) => Promise<RefreshFlightRecord | null>;+ failOpenIDRefreshFlight: (args: {+ key: string;+ ownerId: string;+ error: Error;+ }) => Promise<RefreshFlightRecord | null>;+ waitForOpenIDRefreshFlight: (args: { key: string }) => Promise<SharedOpenIDRefreshResult | null>;+ assertOpenIDRefreshFlightAvailable: (args: {+ key: string;+ ownerId: string;+ }) => Promise<RefreshFlightRecord | boolean>;+ assertOpenIDRefreshSessionGenerationAvailable: (args: {+ key?: string | null;+ ownerId?: string;+ }) => Promise<RefreshFlightRecord | boolean>;+ revokeOpenIDRefreshFlights: (args: {+ keys: Array<string | null>;+ ttl: number;+ }) => Promise<Array<TokenResult | null>>;+ withOpenIDRefreshFlightLease: <T>(args: {+ key: string;+ ownerId: string;+ operation: (context: LeaseContext) => Promise<T>;+ }) => Promise<T>;+ bridgeGraceMs: number;+}++export function createOpenIDRefreshRecoveryService(+ deps: OpenIDRefreshRecoveryDeps,+): OpenIDRefreshRecoveryService {+ const {+ jwt,+ logger,+ findOpenIDUser,+ findUser,+ getOpenIdConfig,+ getOpenIdEmail,+ getOpenIdIssuer,+ createAuthIdentityContext,+ refreshOpenIDSession,+ storeOpenIDSession,+ setOpenIDAuthTokens,+ getOpenIDAppAuthToken,+ clearOpenIDAuthTokens,+ deleteOpenIDSession,+ createRefreshTokenBridgeFlightKey,+ createOpenIDRefreshFlightKey,+ storeRefreshTokenBridge,+ deleteRefreshTokenBridges,+ acquireOpenIDRefreshFlight,+ completeOpenIDRefreshFlight,+ failOpenIDRefreshFlight,+ waitForOpenIDRefreshFlight,+ assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ revokeOpenIDRefreshFlights,+ withOpenIDRefreshFlightLease,+ bridgeGraceMs,+ } = deps;++ const MAX_LOGOUT_REFRESH_CHAIN_DEPTH = 16;+ const MAX_LOGOUT_REFRESH_TARGETS = 128;++ async function revokeOpenIDRefreshTokenChain({+ req,+ user,+ identityContext,+ refreshTokens,+ publicationKeys = [],+ ttl,+ }: RevokeOpenIDRefreshTokenChainInput): Promise<string[]> {+ const userId = identityContext.appUserId;+ if (!userId) {+ throw new Error('OpenID logout identity is unavailable');+ }+ const identityKey = (identity: AuthIdentityContext): string =>+ [+ identity.appUserId ?? '',+ identity.tenantId ?? '',+ identity.openidIssuer ?? '',+ identity.openidSubject ?? '',+ ].join('\x1f');+ const discovered = new Set(refreshTokens.filter(Boolean));+ const scheduled = new Set<string>();+ let frontier = [...discovered].map((refreshToken) => ({+ refreshToken,+ identity: identityContext,+ }));+ for (const target of frontier) {+ scheduled.add(`${target.refreshToken}\x1e${identityKey(target.identity)}`);+ }+ let directPublicationKeys = [...new Set(publicationKeys.filter(Boolean))];++ for (let depth = 0; frontier.length > 0 || directPublicationKeys.length > 0; depth++) {+ if (depth >= MAX_LOGOUT_REFRESH_CHAIN_DEPTH) {+ throw new Error('OpenID logout refresh chain exceeded the safety limit');+ }+ const keys = [+ ...directPublicationKeys,+ ...frontier.flatMap(({ refreshToken, identity }) => [+ createOpenIDRefreshFlightKey({ req, user, refreshToken, identityContext: identity }),+ createRefreshTokenBridgeFlightKey({+ oldRefreshToken: refreshToken,+ userId: identity.appUserId ?? userId,+ tenantId: identity.tenantId,+ openidIssuer: identity.openidIssuer,+ }),+ ]),+ ];+ directPublicationKeys = [];+ const revoked = await revokeOpenIDRefreshFlights({ keys, ttl });+ const inheritedIdentities = frontier.map(({ identity }) => identity);+ const acceptedIdentities = revoked.flatMap((result) => {+ if (result?.acceptedIdentity) return [result.acceptedIdentity];+ const claims = result?.__identityClaims;+ if (!claims?.sub) return [];+ return [+ {+ ...identityContext,+ openidSubject: claims.sub,+ openidIssuer: result?.openidIssuer ?? claims.iss ?? identityContext.openidIssuer,+ },+ ];+ });+ const identities = [...inheritedIdentities, ...acceptedIdentities].filter(+ (identity, index, all) =>+ all.findIndex((candidate) => identityKey(candidate) === identityKey(identity)) === index,+ );+ const successors = revoked.flatMap((result) =>+ [result?.refresh_token, result?.tokenset?.refresh_token].filter((token): token is string =>+ Boolean(token),+ ),+ );+ frontier = successors.flatMap((refreshToken) => {+ discovered.add(refreshToken);+ return identities.flatMap((identity) => {+ const targetKey = `${refreshToken}\x1e${identityKey(identity)}`;+ if (scheduled.has(targetKey)) return [];+ if (scheduled.size >= MAX_LOGOUT_REFRESH_TARGETS) {+ throw new Error('OpenID logout refresh chain exceeded the target safety limit');+ }+ scheduled.add(targetKey);+ return [{ refreshToken, identity }];+ });+ });+ }++ return [...discovered];+ }++ function getTokenClaims(tokenset: OpenIDTokenSet): OpenIDClaims {+ if (typeof tokenset?.claims === 'function') {+ return tokenset.claims();+ }+ if (tokenset.__identityClaims?.sub) {+ return tokenset.__identityClaims;+ }+ const identityToken = tokenset.id_token ?? tokenset.__identityIdToken;+ const decoded = identityToken ? jwt.decode(identityToken) : null;+ if (!decoded || typeof decoded !== 'object') {+ throw new Error('OpenID refresh returned no usable identity claims');+ }+ return decoded as OpenIDClaims;+ }++ async function resolveOpenIDRefreshResult({+ tokenset,+ strategyName,+ }: ResolveOpenIDRefreshInput): Promise<OpenIDRefreshResolution> {+ if (!tokenset?.access_token) {+ throw new Error('OpenID refresh returned no access token');+ }+ const claims = getTokenClaims(tokenset);+ const openIdConfig = getOpenIdConfig();+ const openidIssuer = getOpenIdIssuer(claims, openIdConfig);+ const { user, error, migration } = await findOpenIDUser({+ findUser,+ email: getOpenIdEmail(claims),+ openidId: claims.sub,+ openidIssuer,+ idOnTheSource: claims.oid,+ strategyName,+ });++ logger.debug(+ `[refreshController] findOpenIDUser result: user=${user?.email ?? 'null'}, error=${error ?? 'null'}, migration=${migration}, userOpenidId=${user?.openidId ?? 'null'}, claimsSub=${claims.sub}`,+ );+ return { tokenset, claims, openidIssuer, user, error, migration };+ }++ function seedRefreshSession({+ req,+ user,+ refreshToken,+ browserRefreshToken,+ }: SeedRefreshSessionInput): AuthIdentityContext {+ if (!req.session) {+ throw new Error('OpenID refresh requires an Express session');+ }+ const identity = createAuthIdentityContext({ user, requestUser: req.user });+ req.session.openidTokens = {+ ...(req.session.openidTokens ?? {}),+ refreshToken,+ browserRefreshToken: browserRefreshToken || refreshToken,+ appUserId: identity.appUserId,+ openidSubject: identity.openidSubject,+ ...(identity.tenantId ? { tenantId: identity.tenantId } : {}),+ ...(identity.openidIssuer ? { openidIssuer: identity.openidIssuer } : {}),+ };+ return identity;+ }++ async function refreshOpenIDUser({+ req,+ res,+ user,+ refreshToken,+ browserRefreshToken,+ strategyName,+ assertLeaseOwned,+ deferPublication = false,+ }: RefreshOpenIDUserArgs): Promise<OpenIDRefreshResolution> {+ const previousSessionTokens = deferPublication ? req.session?.openidTokens : undefined;+ const hadSessionTokens = Boolean(req.session && 'openidTokens' in req.session);+ const identityContext = seedRefreshSession({+ req,+ user,+ refreshToken,+ browserRefreshToken,+ });+ let tokenset: OpenIDTokenSet | null;+ try {+ tokenset = await refreshOpenIDSession(req, res, user, 'id_token', identityContext, {+ forceRefresh: true,+ ...(assertLeaseOwned ? { assertLeaseOwned } : {}),+ ...(deferPublication ? { deferPublication: true } : {}),+ });+ } finally {+ if (deferPublication && req.session) {+ if (hadSessionTokens) {+ req.session.openidTokens = previousSessionTokens;+ } else {+ delete req.session.openidTokens;+ }+ }+ }+ return resolveOpenIDRefreshResult({ tokenset, strategyName });+ }++ async function recoverOpenIDRefreshBridge({+ req,+ res,+ refreshToken,+ bridgedRefreshToken,+ bridgeUser,+ }: RecoverOpenIDRefreshBridgeInput): Promise<SharedOpenIDRefreshResult> {+ const userId = bridgeUser._id.toString();+ const key = createRefreshTokenBridgeFlightKey({+ oldRefreshToken: refreshToken,+ userId,+ tenantId: bridgeUser.tenantId,+ openidIssuer: bridgeUser.openidIssuer,+ });+ if (!key) {+ throw new Error('OpenID refresh bridge coordination key is unavailable');+ }++ const flight = await acquireOpenIDRefreshFlight({ key });+ if (!flight.acquired) {+ const resolved = await waitForOpenIDRefreshFlight({ key });+ if (!resolved?.appAuthToken || !resolved.__flightOwnerId) {+ throw new Error('OpenID refresh bridge coordination is temporarily unavailable');+ }+ const publicationGeneration = {+ key,+ ownerId: resolved.__flightOwnerId,+ createdAt: resolved.__flightCreatedAt,+ };+ const publishedAppAuthToken = await sendOpenIDAuthResponse({+ tokenset: resolved.tokenset,+ user: bridgeUser,+ existingRefreshToken: refreshToken,+ openidSubject: resolved.claims.sub,+ openidIssuer: resolved.openidIssuer,+ predecessorIdentity: {+ userId,+ tenantId: bridgeUser.tenantId,+ openidIssuer: bridgeUser.openidIssuer,+ },+ predecessorAccessToken: resolved.predecessorAccessToken,+ req,+ res,+ assertLeaseOwned: () => assertOpenIDRefreshFlightAvailable(publicationGeneration),+ publicationGeneration,+ commitPublication: async () => {},+ preparePublication: false,+ });+ return { ...resolved, appAuthToken: publishedAppAuthToken ?? resolved.appAuthToken };+ }++ return withOpenIDRefreshFlightLease({+ key,+ ownerId: flight.ownerId,+ operation: async ({ assertLeaseOwned, markLeaseSettled }: LeaseContext) => {+ let completionIndeterminate = false;+ try {+ const resolved = await refreshOpenIDUser({+ req,+ res,+ user: bridgeUser,+ refreshToken: bridgedRefreshToken,+ browserRefreshToken: refreshToken,+ strategyName: 'refreshController (bridge recovery)',+ assertLeaseOwned,+ deferPublication: true,+ });+ const { tokenset, user, error } = resolved;+ const resolvedUserId = user?._id?.toString();+ if (!user || error || !resolvedUserId || resolvedUserId !== userId) {+ if (resolvedUserId && resolvedUserId !== userId) {+ logger.warn(+ '[refreshController] Bridge recovery resolved a different user; refusing token issuance',+ { cookieUserId: userId, resolvedUserId },+ );+ }+ throw new Error('Invalid OpenID refresh token');+ }++ await assertLeaseOwned();+ let graceBridgeVersion: string | null = null;+ try {+ graceBridgeVersion = await storeRefreshTokenBridge({+ oldRefreshToken: refreshToken,+ newRefreshToken: tokenset.refresh_token || bridgedRefreshToken,+ userId,+ tenantId: bridgeUser.tenantId,+ openidIssuer: bridgeUser.openidIssuer,+ ttl: bridgeGraceMs,+ });+ } catch (graceError) {+ logger.warn(+ '[refreshController] Bridge grace-period storage failed after successful recovery',+ toOpenIDLogArgument(graceError),+ );+ }+ if (graceBridgeVersion) {+ try {+ await assertLeaseOwned();+ } catch (ownershipError) {+ /** Ownership must be proven, not merely unreadable; see the note in `session.ts`. */+ if (!isOpenIDRefreshOwnershipError(ownershipError)) {+ logger.warn(+ '[refreshController] Keeping the grace bridge; lease ownership is undetermined',+ { userId, error: (ownershipError as Error)?.message },+ );+ throw ownershipError;+ }+ try {+ await deleteRefreshTokenBridges({+ refreshTokens: [refreshToken],+ userId,+ tenantId: bridgeUser.tenantId,+ version: graceBridgeVersion,+ });+ } catch (cleanupError) {+ logger.warn(+ '[refreshController] Failed to remove grace bridge after ownership loss',+ toOpenIDLogArgument(cleanupError),+ );+ }+ throw ownershipError;+ }+ }++ const publication: { result?: SharedOpenIDRefreshResult } = {};+ const sharedResult = {+ tokenset,+ claims: resolved.claims,+ openidIssuer: resolved.openidIssuer,+ expires_at: tokenset.expires_at,+ };+ const appAuthToken = await sendOpenIDAuthResponse({+ tokenset,+ user: bridgeUser,+ existingRefreshToken: refreshToken,+ openidSubject: resolved.claims.sub,+ openidIssuer: resolved.openidIssuer,+ predecessorIdentity: {+ userId,+ tenantId: bridgeUser.tenantId,+ openidIssuer: bridgeUser.openidIssuer,+ },+ req,+ res,+ assertLeaseOwned,+ publicationGeneration: {+ key,+ ownerId: flight.ownerId,+ createdAt: flight.flight?.createdAt+ ? new Date(flight.flight.createdAt).getTime()+ : Date.now(),+ },+ commitPublication: async (preparedAppAuthToken, publishedTokenset, metadata) => {+ const result = {+ ...sharedResult,+ tokenset: publishedTokenset,+ expires_at: publishedTokenset.expires_at,+ appAuthToken: preparedAppAuthToken,+ ...metadata,+ };+ let completed: RefreshFlightRecord | null = null;+ try {+ completed = await completeOpenIDRefreshFlight({+ key,+ ownerId: flight.ownerId,+ tokens: result,+ });+ } catch (completionError) {+ completionIndeterminate = true;+ try {+ const observed = await assertOpenIDRefreshFlightAvailable({+ key,+ ownerId: flight.ownerId,+ });+ if (typeof observed === 'object') {+ completed = observed;+ completionIndeterminate = false;+ }+ } catch {+ /** Preserve the pending generation when completion cannot be observed. */+ }+ if (!completed) {+ throw completionError;+ }+ }+ if (!completed) {+ throw createOpenIDRefreshOwnershipError(+ 'OpenID refresh bridge coordination ownership was lost',+ );+ }+ publication.result = result;+ markLeaseSettled();+ },+ });+ if (!publication.result || publication.result.appAuthToken !== appAuthToken) {+ throw new Error('OpenID refresh bridge publication did not settle');+ }+ return publication.result;+ } catch (error) {+ if (!completionIndeterminate) {+ try {+ await failOpenIDRefreshFlight({+ key,+ ownerId: flight.ownerId,+ error: error instanceof Error ? error : new Error('OpenID bridge recovery failed'),+ });+ } catch (flightError) {+ logger.warn('[refreshController] Failed to mark refresh bridge flight failed', {+ error: (flightError as Error)?.message,+ });+ }+ } else {+ logger.warn(+ '[refreshController] Keeping an indeterminate bridge generation recoverable',+ );+ }+ throw error;+ }+ },+ });+ }++ async function sendOpenIDAuthResponse({+ tokenset,+ user,+ existingRefreshToken,+ openidSubject,+ openidIssuer,+ predecessorIdentity,+ predecessorAccessToken,+ rejectedRefreshTokens = [],+ req,+ res,+ assertLeaseOwned,+ publicationGeneration,+ commitPublication,+ preparePublication = true,+ }: SendOpenIDAuthResponseInput): Promise<string | undefined> {+ const userId = user._id.toString();+ const publicationIdentity = predecessorIdentity ?? {+ userId,+ tenantId: user.tenantId,+ openidIssuer: user.openidIssuer,+ };+ if (!commitPublication && existingRefreshToken) {+ const key = createRefreshTokenBridgeFlightKey({+ oldRefreshToken: existingRefreshToken,+ userId: publicationIdentity.userId,+ tenantId: publicationIdentity.tenantId,+ openidIssuer: publicationIdentity.openidIssuer,+ });+ if (key) {+ const flight = await acquireOpenIDRefreshFlight({ key });+ if (!flight.acquired) {+ const shared = await waitForOpenIDRefreshFlight({ key });+ if (!shared?.appAuthToken || !shared.__flightOwnerId) {+ throw new Error('OpenID authentication publication is temporarily unavailable');+ }+ const sharedGeneration = {+ key,+ ownerId: shared.__flightOwnerId,+ createdAt: shared.__flightCreatedAt,+ };+ return sendOpenIDAuthResponse({+ tokenset: shared.tokenset,+ user,+ existingRefreshToken,+ openidSubject: shared.claims.sub,+ openidIssuer: shared.openidIssuer,+ predecessorIdentity: publicationIdentity,+ predecessorAccessToken: shared.predecessorAccessToken,+ rejectedRefreshTokens,+ req,+ res,+ assertLeaseOwned: () => assertOpenIDRefreshFlightAvailable(sharedGeneration),+ publicationGeneration: sharedGeneration,+ commitPublication: async () => {},+ preparePublication: false,+ });+ }+ return withOpenIDRefreshFlightLease({+ key,+ ownerId: flight.ownerId,+ operation: async ({ assertLeaseOwned, markLeaseSettled }) =>+ sendOpenIDAuthResponse({+ tokenset,+ user,+ existingRefreshToken,+ openidSubject,+ openidIssuer,+ predecessorIdentity: publicationIdentity,+ rejectedRefreshTokens,+ req,+ res,+ assertLeaseOwned,+ publicationGeneration: {+ key,+ ownerId: flight.ownerId,+ createdAt: flight.flight?.createdAt+ ? new Date(flight.flight.createdAt).getTime()+ : Date.now(),+ },+ commitPublication: async (appAuthToken, publishedTokenset, metadata) => {+ const completed = await completeOpenIDRefreshFlight({+ key,+ ownerId: flight.ownerId,+ tokens: {+ tokenset: publishedTokenset,+ claims: { sub: openidSubject ?? user.openidId ?? userId },+ openidIssuer: openidIssuer ?? user.openidIssuer,+ expires_at: publishedTokenset.expires_at,+ appAuthToken,+ ...metadata,+ },+ });+ if (!completed) {+ throw createOpenIDRefreshOwnershipError(+ 'OpenID authentication publication was revoked before completion',+ );+ }+ markLeaseSettled();+ },+ }),+ });+ }+ }+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }+ if (typeof req?.session?.reload === 'function') {+ const reload = req.session.reload.bind(req.session);+ await new Promise<void>((resolve, reject) => {+ reload((error?: Error | null) => (error ? reject(error) : resolve()));+ });+ }+ let effectiveTokenset = tokenset;+ let effectiveExistingRefreshToken = existingRefreshToken;+ let usesAdvancedSession = false;+ const currentSessionTokens = req?.session?.openidTokens;+ const proposedRefreshToken = tokenset.refresh_token || existingRefreshToken;+ const refreshTokenAdvanced = Boolean(+ currentSessionTokens?.refreshToken &&+ !rejectedRefreshTokens.includes(currentSessionTokens.refreshToken) &&+ currentSessionTokens.refreshToken !== existingRefreshToken &&+ currentSessionTokens.refreshToken !== proposedRefreshToken,+ );+ const candidatePredecessorAccessToken =+ predecessorAccessToken ?? tokenset.__predecessorAccessToken;+ const accessTokenAdvanced = Boolean(+ candidatePredecessorAccessToken &&+ currentSessionTokens?.accessToken &&+ currentSessionTokens.accessToken !== candidatePredecessorAccessToken &&+ currentSessionTokens.accessToken !== tokenset.access_token,+ );+ if ((refreshTokenAdvanced || accessTokenAdvanced) && currentSessionTokens) {+ if (!currentSessionTokens.accessToken) {+ throw new Error('OpenID refresh result was superseded by an incomplete session state');+ }+ logger.debug(+ '[refreshController] Using the advanced session instead of a stale flight result',+ );+ effectiveExistingRefreshToken = currentSessionTokens.refreshToken;+ effectiveTokenset = {+ access_token: currentSessionTokens.accessToken,+ id_token: currentSessionTokens.idToken,+ refresh_token: currentSessionTokens.refreshToken,+ expires_at: currentSessionTokens.accessTokenExpiresAt,+ };+ usesAdvancedSession = true;+ }+ const advancedSessionGeneration = usesAdvancedSession+ ? (() => {+ const key = currentSessionTokens?.publicationFlightKey;+ const ownerId = currentSessionTokens?.publicationFlightOwnerId;+ const createdAt = currentSessionTokens?.publicationFlightCreatedAt;+ if (!key && !ownerId) return undefined;+ if (!key || !ownerId) {+ throw createOpenIDRefreshOwnershipError(+ 'OpenID advanced session publication generation is incomplete',+ );+ }+ return { key, ownerId, createdAt };+ })()+ : undefined;+ if (advancedSessionGeneration) {+ await assertOpenIDRefreshSessionGenerationAvailable(advancedSessionGeneration);+ }+ const effectiveSessionGeneration = advancedSessionGeneration ?? publicationGeneration;+ const acceptedSessionIdentity: AuthIdentityContext = usesAdvancedSession+ ? {+ appUserId: currentSessionTokens?.appUserId ?? userId,+ openidSubject:+ currentSessionTokens?.openidSubject ?? openidSubject ?? user.openidId ?? userId,+ tenantId: currentSessionTokens?.tenantId ?? user.tenantId,+ openidIssuer: currentSessionTokens?.openidIssuer ?? openidIssuer ?? user.openidIssuer,+ }+ : {+ appUserId: userId,+ openidSubject: openidSubject ?? user.openidId ?? userId,+ tenantId: user.tenantId,+ openidIssuer: openidIssuer ?? user.openidIssuer,+ };+ const acceptedBridgeIdentity = {+ userId: acceptedSessionIdentity.appUserId ?? userId,+ tenantId: acceptedSessionIdentity.tenantId,+ openidIssuer: acceptedSessionIdentity.openidIssuer,+ };+ const assertSettledPublicationAvailable = async (): Promise<void> => {+ if (publicationGeneration) {+ await assertOpenIDRefreshFlightAvailable(publicationGeneration);+ }+ if (+ advancedSessionGeneration &&+ (advancedSessionGeneration.key !== publicationGeneration?.key ||+ advancedSessionGeneration.ownerId !== publicationGeneration?.ownerId)+ ) {+ await assertOpenIDRefreshSessionGenerationAvailable(advancedSessionGeneration);+ }+ };+ const nextRefreshToken = effectiveTokenset.refresh_token || effectiveExistingRefreshToken;+ if (!nextRefreshToken) {+ throw new Error('OpenID refresh returned no refresh token');+ }++ let authTokenset = effectiveTokenset;+ const effectiveExpiresAt = effectiveTokenset.expires_at;+ if (effectiveTokenset.expires_in == null && Number.isFinite(effectiveExpiresAt)) {+ authTokenset = {+ ...effectiveTokenset,+ expires_in: Math.max(0, Math.floor((effectiveExpiresAt as number) - Date.now() / 1000)),+ };+ }+ const preparedAppAuthToken = getOpenIDAppAuthToken(+ authTokenset,+ req.session?.openidTokens?.idToken,+ );+ if (!preparedAppAuthToken) {+ throw new Error('OpenID refresh returned no application authentication token');+ }+ let bridgeVersion: string | null = null;+ const rotated =+ !!effectiveExistingRefreshToken && nextRefreshToken !== effectiveExistingRefreshToken;++ if (preparePublication) {+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }+ try {+ await storeOpenIDSession(+ acceptedSessionIdentity.appUserId ?? userId,+ nextRefreshToken,+ acceptedSessionIdentity.tenantId,+ effectiveExistingRefreshToken,+ );+ } catch (error) {+ if (rotated && effectiveExistingRefreshToken) {+ try {+ await storeRefreshTokenBridge({+ oldRefreshToken: effectiveExistingRefreshToken,+ newRefreshToken: nextRefreshToken,+ ...acceptedBridgeIdentity,+ ttl: bridgeGraceMs,+ });+ } catch (bridgeError) {+ logger.warn(+ '[refreshController] Failed to preserve a rotated token after durable-session failure',+ toOpenIDLogArgument(bridgeError),+ );+ }+ }+ throw error;+ }++ if (rotated && effectiveExistingRefreshToken) {+ try {+ bridgeVersion = await storeRefreshTokenBridge({+ oldRefreshToken: effectiveExistingRefreshToken,+ newRefreshToken: nextRefreshToken,+ ...acceptedBridgeIdentity,+ ttl: bridgeGraceMs,+ });+ } catch (bridgeError) {+ logger.warn(+ '[refreshController] Failed to store the publication recovery bridge',+ toOpenIDLogArgument(bridgeError),+ );+ }+ }+ }++ try {+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }+ await commitPublication?.(preparedAppAuthToken, authTokenset, {+ predecessorAccessToken: candidatePredecessorAccessToken,+ acceptedIdentity: acceptedSessionIdentity,+ });+ await assertSettledPublicationAvailable();++ const publishedAppAuthToken = setOpenIDAuthTokens(authTokenset, req, res, {+ userId: acceptedSessionIdentity.appUserId ?? userId,+ existingRefreshToken: effectiveExistingRefreshToken,+ tenantId: acceptedSessionIdentity.tenantId,+ openidSubject: acceptedSessionIdentity.openidSubject,+ openidIssuer: acceptedSessionIdentity.openidIssuer,+ });+ if (req.session?.openidTokens && effectiveSessionGeneration) {+ req.session.openidTokens.publicationFlightKey = effectiveSessionGeneration.key;+ req.session.openidTokens.publicationFlightOwnerId = effectiveSessionGeneration.ownerId;+ req.session.openidTokens.publicationFlightCreatedAt = effectiveSessionGeneration.createdAt;+ }+ await assertSettledPublicationAvailable();+ if (publishedAppAuthToken !== preparedAppAuthToken) {+ throw new Error('OpenID authentication publication returned an inconsistent token');+ }+ return publishedAppAuthToken;+ } catch (error) {+ if (!isOpenIDRefreshOwnershipError(error)) {+ logger.warn(+ '[refreshController] Keeping the prepared successor after an indeterminate publication failure',+ toOpenIDLogArgument(error),+ );+ throw error;+ }+ try {+ await deleteOpenIDSession(nextRefreshToken);+ } catch (cleanupError) {+ logger.warn(+ '[refreshController] Failed to remove prepared session after publication failure',+ toOpenIDLogArgument(cleanupError),+ );+ }+ if (bridgeVersion && effectiveExistingRefreshToken) {+ try {+ await deleteRefreshTokenBridges({+ refreshTokens: [effectiveExistingRefreshToken],+ userId: acceptedBridgeIdentity.userId,+ tenantId: acceptedBridgeIdentity.tenantId,+ version: bridgeVersion,+ });+ } catch (cleanupError) {+ logger.warn(+ '[refreshController] Failed to remove the owned bridge after publication revocation',+ toOpenIDLogArgument(cleanupError),+ );+ }+ }+ clearOpenIDAuthTokens(+ req,+ res,+ acceptedSessionIdentity.appUserId ?? userId,+ acceptedSessionIdentity.tenantId,+ );+ throw error;+ }+ }++ return {+ recoverOpenIDRefreshBridge,+ revokeOpenIDRefreshTokenChain,+ refreshOpenIDUser,+ resolveOpenIDRefreshResult,+ sendOpenIDAuthResponse,+ __internals: { getTokenClaims, seedRefreshSession },+ };+}diff --git a/packages/api/src/auth/openid/session.ts b/packages/api/src/auth/openid/session.tsnew file mode 100644index 0000000000..a402874e00--- /dev/null+++ b/packages/api/src/auth/openid/session.ts@@ -0,0 +1,2043 @@+import type {+ AuthIdentityContext,+ AuthIdentitySource,+ AuthIdentityTuple,+ LeaseAssertion,+ LeaseContext,+ OIDCTokens,+ OpenIDClaims,+ OpenIDLogger,+ OpenIDRequest,+ OpenIDResponse,+ OpenIDPublicationGeneration,+ OpenIDSessionIdentitySource,+ OpenIDTokenSet,+ OpenIDUser,+ RefreshFlightAcquireResult,+ RefreshFlightRecord,+ RefreshKeyInput,+ RefreshTokenBridgeDeleteInput,+ RefreshTokenBridgeIdentity,+ RefreshTokenBridgeInput,+ SessionOpenIDTokens,+ TokenPreference,+} from './types';+import type { OpenIdSessionDeps, OpenIdSessionParams } from '~/images/session';+import type { TokenResult } from './flight';+import {+ createOpenIDRefreshOwnershipError,+ isOpenIDRefreshOwnershipError,+ toOpenIDLogArgument,+} from './errors';++interface OpenIDSessionRefreshDeps {+ jwt: {+ decode: (token: string) => (Partial<OpenIDClaims> & { exp?: number }) | string | null;+ verify: (token: string, secret: string) => { id?: string; refreshTokenHash?: string } | string;+ };+ cookies: { parse: (header: string) => Record<string, string> };+ crypto: {+ createHash: (algorithm: string) => {+ update: (value: string) => { digest: (encoding: 'hex' | 'base64url') => string };+ };+ };+ openIdClient: {+ refreshTokenGrant: (+ config: object,+ refreshToken: string,+ params: Record<string, string>,+ ) => Promise<OpenIDTokenSet>;+ };+ logger: OpenIDLogger;+ defaultRefreshTokenExpiry: number;+ isEnabled: (value?: string) => boolean;+ math: (value: string | undefined, fallback: number) => number;+ createAuthIdentityContext: (args: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ tenantId?: string;+ openidIssuer?: string;+ }) => AuthIdentityContext;+ isOpenIDSessionIdentityMatch: (+ session: OpenIDSessionIdentitySource,+ expected: OpenIDSessionIdentitySource,+ ) => boolean;+ createOpenIDRefreshIdentityTuple: (args: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ }) => AuthIdentityTuple | null;+ createRefreshTokenBridgeIdentity: (args: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ userId?: string;+ tenantId?: string;+ openidIssuer?: string;+ }) => RefreshTokenBridgeIdentity | null;+ serializeAuthIdentityTuple: (tuple: AuthIdentityTuple) => string;+ buildOpenIDRefreshParams: () => Record<string, string>;+ setRefreshTokenCookie: (res: OpenIDResponse, token: string, expires: Date) => void;+ setOpenIDMarkerCookies: (+ res: OpenIDResponse,+ args: {+ userId?: string;+ expires: Date;+ refreshExpiryMs: number;+ refreshToken: string;+ },+ ) => void;+ storeOpenIdSession: (data: OpenIdSessionParams, methods: OpenIdSessionDeps) => Promise<boolean>;+ normalizeExpiresIn: (value?: number | string) => number | undefined;+ upsertSession: OpenIdSessionDeps['upsertSession'];+ deleteSession: OpenIdSessionDeps['deleteSession'];+ getOpenIdConfig: () => object;+ OPENID_REFRESH_BRIDGE_GRACE_MS: number;+ storeRefreshTokenBridge: (input: RefreshTokenBridgeInput) => Promise<string | null>;+ deleteRefreshTokenBridges: (input: RefreshTokenBridgeDeleteInput) => Promise<object | null>;+ acquireOpenIDRefreshFlight: (args: {+ key?: string | null;+ }) => Promise<RefreshFlightAcquireResult>;+ completeOpenIDRefreshFlight: (args: {+ key?: string | null;+ ownerId?: string;+ tokens?: TokenResult | null;+ }) => Promise<RefreshFlightRecord | null>;+ createOpenIDRefreshFlightKey: (input: RefreshKeyInput) => string | null;+ failOpenIDRefreshFlight: (args: {+ key?: string | null;+ ownerId?: string;+ error?: Error | null;+ }) => Promise<RefreshFlightRecord | null>;+ waitForOpenIDRefreshFlight: (args: { key?: string | null }) => Promise<TokenResult | null>;+ assertOpenIDRefreshFlightAvailable: (args: {+ key?: string | null;+ ownerId?: string;+ }) => Promise<RefreshFlightRecord | boolean>;+ assertOpenIDRefreshSessionGenerationAvailable: (args: {+ key?: string | null;+ ownerId?: string;+ }) => Promise<RefreshFlightRecord | boolean>;+ withOpenIDRefreshFlightLease: <T>(args: {+ key?: string | null;+ ownerId?: string;+ operation: (context: LeaseContext) => Promise<T>;+ }) => Promise<T>;+}++interface MarkedOIDCTokens extends OIDCTokens {+ __browserRefreshToken?: string;+ __identityClaims?: OpenIDClaims;+ __predecessorRefreshToken?: string;+ __predecessorAccessToken?: string;+ __deferredPublication?: boolean;+ __flightOwnerId?: string;+ __flightCreatedAt?: number;+ __identityIdToken?: string;+}++interface RefreshSessionOptions {+ forceRefresh?: boolean;+ assertLeaseOwned?: LeaseAssertion;+ deferPublication?: boolean;+}++interface SessionPublicationEffects {+ durableSession: boolean;+ browserCookies: boolean;+ expressSession: boolean;+ bridge?: {+ version: string;+ predecessorRefreshToken: string;+ identity: RefreshTokenBridgeIdentity;+ };+}++interface CreateOpenIDSessionTokenProviderInput {+ req?: OpenIDRequest;+ res?: OpenIDResponse;+ user?: OpenIDUser;+ tokenPreference: TokenPreference;+ identityContext?: AuthIdentityContext;+}++export interface OpenIDSessionRefreshService {+ createOpenIDSessionTokenProvider: (+ input: CreateOpenIDSessionTokenProviderInput,+ ) => () => Promise<OIDCTokens | null>;+ refreshOpenIDSession: (+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ user: OpenIDUser,+ tokenPreference: TokenPreference,+ identityContext?: AuthIdentityContext,+ options?: RefreshSessionOptions,+ ) => Promise<MarkedOIDCTokens | null>;+ __internals: {+ UPSTREAM_TOKEN_EXPIRY_BUFFER_SECONDS: number;+ inFlightRefreshes: Map<string, Promise<MarkedOIDCTokens | null>>;+ getSingleFlightKey: (+ req: OpenIDRequest,+ user: OpenIDUser,+ identityContext?: AuthIdentityContext,+ ) => string | null;+ isLiveSessionTokenStillValid: (+ sessionTokens: SessionOpenIDTokens,+ tokenPreference: TokenPreference,+ ) => boolean;+ getAccessTokenExp: (sessionTokens: SessionOpenIDTokens) => number | null;+ };+}++/**+ * OpenID session refresh implementation. Runtime-only Express, model, and strategy dependencies+ * are supplied by the thin /api wrapper; the authentication and coordination logic lives here.+ */+export function createOpenIDSessionRefreshService(+ deps: OpenIDSessionRefreshDeps,+): OpenIDSessionRefreshService {+ const {+ jwt,+ cookies,+ crypto,+ openIdClient,+ logger,+ defaultRefreshTokenExpiry: DEFAULT_REFRESH_TOKEN_EXPIRY,+ isEnabled,+ math,+ createAuthIdentityContext,+ isOpenIDSessionIdentityMatch,+ createOpenIDRefreshIdentityTuple,+ createRefreshTokenBridgeIdentity,+ serializeAuthIdentityTuple,+ buildOpenIDRefreshParams,+ setRefreshTokenCookie,+ setOpenIDMarkerCookies,+ storeOpenIdSession,+ normalizeExpiresIn,+ upsertSession,+ deleteSession,+ getOpenIdConfig,+ OPENID_REFRESH_BRIDGE_GRACE_MS,+ storeRefreshTokenBridge,+ deleteRefreshTokenBridges,+ acquireOpenIDRefreshFlight,+ completeOpenIDRefreshFlight,+ createOpenIDRefreshFlightKey,+ failOpenIDRefreshFlight,+ waitForOpenIDRefreshFlight,+ assertOpenIDRefreshFlightAvailable,+ assertOpenIDRefreshSessionGenerationAvailable,+ withOpenIDRefreshFlightLease,+ } = deps;++ /**+ * Shape of `req.session.openidTokens`. Established by `setOpenIDAuthTokens`+ * (`api/server/services/AuthService.js`) on login/refresh, mutated in place by+ * this module on inline refresh, and consumed by `refreshController` and+ * `LogoutController`. Distinct from the snake_case `OIDCTokens` type in+ * `@librechat/data-schemas` (which describes `IUser.federatedTokens` /+ * `IUser.openidTokens` — model fields, not the express-session field).+ *+ * Express-session's SessionData is open by design, so this contract lives in+ * comments rather than a TS interface; keep this and AuthService.js in sync+ * when the shape changes.+ *+ * @typedef {Object} SessionOpenIDTokens+ * @property {string} [accessToken] — IdP access token (may be opaque).+ * @property {string} [idToken] — IdP ID token (always JWT).+ * @property {string} [refreshToken] — IdP refresh token.+ * @property {string} [browserRefreshToken] — refresh token last known to be written to+ * the browser cookie.+ * @property {number} [expiresAt] — SESSION cookie expiry (ms).+ * @property {number} [lastRefreshedAt] — wall-clock ms of the last server-side rotation.+ * @property {string} [appUserId] — LibreChat user id bound to these session tokens.+ * @property {string} [openidSubject] — OpenID `sub` bound to these session tokens.+ * @property {string} [tenantId] — tenant bound to these session tokens.+ * @property {string} [openidIssuer] — normalized issuer bound to these session tokens.+ * @property {number} [accessTokenExpiresAt] — access token expiry (unix seconds), captured+ * from the IdP `tokenset.expires_in` so opaque+ * access tokens can still be reused without+ * redundant refreshes.+ * @property {string} [publicationFlightKey] — durable publication key authorizing this state.+ * @property {string} [publicationFlightOwnerId] — exact completed generation for that key.+ */++ /**+ * Skew buffer for the upstream access-token expiry check. Mirrors+ * `OPENID_REUSE_EXPIRY_BUFFER_SECONDS` in `AuthController.js` so that a token+ * which the controller is about to rotate also triggers an inline refresh here.+ */+ const UPSTREAM_TOKEN_EXPIRY_BUFFER_SECONDS = 30;+ const INTERNAL_BROWSER_REFRESH_TOKEN_FIELD = '__browserRefreshToken';+ const INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD = '__predecessorRefreshToken';+ const INTERNAL_PREDECESSOR_ACCESS_TOKEN_FIELD = '__predecessorAccessToken';+ const INTERNAL_DEFERRED_PUBLICATION_FIELD = '__deferredPublication';+ const INTERNAL_IDENTITY_ID_TOKEN_FIELD = '__identityIdToken';+ const IDENTITY_PART_SEPARATOR = '\x1f';++ /**+ * In-flight upstream refreshes keyed by `getSingleFlightKey(req, user, identityContext)` —+ * a composite of `tenantId:openidIssuer:subject:refreshTokenHash`.+ * See that helper for the rationale on why each component is needed; in short,+ * tenant+issuer keying prevents cross-tenant token crossover when distinct users+ * share an IdP `sub`, and refresh-token keying makes every request holding the same+ * rotating credential join the same logical grant across sessions and replicas.+ *+ * A fan-out of tool calls carrying the same expired credential coalesces into+ * one IdP refresh-token grant. Mirrors the+ * single-flight pattern in `OboTokenService.js`.+ *+ * Process-local coalescing is backed by a renewable Mongo lease in+ * `performIdpRefresh`, so distinct workers do not admit parallel rotating-token+ * grants for the same key.+ */+ const inFlightRefreshes = new Map<string, Promise<MarkedOIDCTokens | null>>();++ /**+ * Returns the single-flight key for a refresh attempt, composed from the user's+ * tenant (if any), the IdP issuer + sub, and the current refresh token.+ * Tightening past `openidId` alone serves two purposes:+ *+ * 1. Same credential, multiple Express sessions: every holder joins one grant,+ * so token rotation cannot admit duplicate IdP refreshes merely because an+ * Express session expired or a request landed on another replica.+ * 2. Multi-tenant deployments where two distinct users share an IdP `sub`+ * (different issuers, same sub): tenant + issuer disambiguates them so+ * tokens never cross tenant boundaries via shared in-flight Promises.+ *+ * Concurrent tool calls inside the SAME session with the SAME refresh token+ * still coalesce — the common case the single-flight is designed for (a fan-out+ * of MCP tool calls in one agent run) is unaffected.+ *+ * Returns null when there's no usable identity at all; callers fall through+ * to a non-coalesced refresh, which is safe but missing the optimization.+ */+ function getSingleFlightKey(+ req: OpenIDRequest,+ user: OpenIDUser,+ identityContext?: AuthIdentityContext,+ ): string | null {+ const identitySource = identityContext+ ? {+ id: identityContext.appUserId,+ openidId: identityContext.openidSubject,+ tenantId: identityContext.tenantId,+ openidIssuer: identityContext.openidIssuer,+ }+ : user;+ const tuple = createOpenIDRefreshIdentityTuple({+ user: identitySource,+ requestUser: req?.user,+ });+ const refreshToken = req?.session?.openidTokens?.refreshToken;+ if (!tuple || !refreshToken) {+ return null;+ }+ const refreshTokenHash = crypto.createHash('sha256').update(refreshToken).digest('hex');+ return [serializeAuthIdentityTuple(tuple), refreshTokenHash].join(IDENTITY_PART_SEPARATOR);+ }++ /**+ * Returns a short SHA-256 prefix of the single-flight key for use in logs.+ * Preserves correlation across "started" / "joined" / "completed" log events+ * for the same refresh attempt without leaking the underlying values:+ *+ * - refresh-token hashes are still credential-derived and remain private.+ * - openidId (the IdP `sub`) and openidIssuer are tenant/user fingerprints.+ *+ * 12 hex chars = 48 bits of entropy: ~7×10^14 distinct keys before a 50%+ * collision chance — more than enough for correlating concurrent refreshes.+ */+ function hashKeyForLogs(key: string): string {+ return crypto.createHash('sha256').update(key).digest('hex').slice(0, 12);+ }++ function resolveExpectedOpenIDSessionIdentity(+ req: OpenIDRequest,+ user: OpenIDUser,+ identityContext?: AuthIdentityContext,+ ): AuthIdentityContext {+ if (!identityContext) {+ return createAuthIdentityContext({+ user,+ requestUser: req?.user,+ });+ }++ return createAuthIdentityContext({+ user: {+ id: identityContext.appUserId,+ openidId: identityContext.openidSubject,+ tenantId: identityContext.tenantId,+ openidIssuer: identityContext.openidIssuer,+ },+ requestUser: user ?? req?.user,+ tenantId: identityContext.tenantId,+ openidIssuer: identityContext.openidIssuer,+ });+ }++ function hasAnyOpenIDSessionIdentity(sessionTokens: SessionOpenIDTokens): boolean {+ const identityFields: Array<keyof OpenIDSessionIdentitySource> = [+ 'appUserId',+ 'openidSubject',+ 'tenantId',+ 'openidIssuer',+ ];+ return identityFields.some((field) => sessionTokens?.[field] != null);+ }++ function canBindLegacyOpenIDSession(+ req: OpenIDRequest,+ sessionTokens: SessionOpenIDTokens,+ expectedIdentity: AuthIdentityContext,+ ): boolean {+ if (+ hasAnyOpenIDSessionIdentity(sessionTokens) ||+ !expectedIdentity.appUserId ||+ !expectedIdentity.openidSubject ||+ !process.env.JWT_REFRESH_SECRET+ ) {+ return false;+ }++ const parsedCookies = req?.headers?.cookie ? cookies.parse(req.headers.cookie) : {};+ const browserRefreshToken = parsedCookies.refreshToken;+ const expectedBrowserRefreshToken =+ sessionTokens.browserRefreshToken || sessionTokens.refreshToken;+ if (+ !browserRefreshToken ||+ !expectedBrowserRefreshToken ||+ browserRefreshToken !== expectedBrowserRefreshToken ||+ !parsedCookies.openid_user_id+ ) {+ return false;+ }++ try {+ const marker = jwt.verify(parsedCookies.openid_user_id, process.env.JWT_REFRESH_SECRET);+ if (+ typeof marker !== 'object' ||+ marker == null ||+ marker.id !== expectedIdentity.appUserId ||+ typeof marker.refreshTokenHash !== 'string'+ ) {+ return false;+ }+ const refreshTokenHash = crypto+ .createHash('sha256')+ .update(browserRefreshToken)+ .digest('base64url');+ return marker.refreshTokenHash === refreshTokenHash;+ } catch {+ return false;+ }+ }++ function assertOpenIDSessionIdentityMatch(+ req: OpenIDRequest,+ user: OpenIDUser,+ identityContext?: AuthIdentityContext,+ ): Promise<void> | undefined {+ const sessionTokens = req?.session?.openidTokens;+ if (!sessionTokens) {+ return;+ }++ const expectedIdentity = resolveExpectedOpenIDSessionIdentity(req, user, identityContext);+ if (isOpenIDSessionIdentityMatch(sessionTokens, expectedIdentity)) {+ return;+ }++ /**+ * Sessions minted before identity stamping was deployed have none of these+ * fields. During a rolling upgrade, bind that legacy record only when the+ * signed browser marker proves the current app user and refresh-token cookie+ * are the ones that created it. Partial or unverifiable metadata still fails+ * closed, preventing cross-user token adoption.+ */+ if (canBindLegacyOpenIDSession(req, sessionTokens, expectedIdentity)) {+ Object.assign(sessionTokens, expectedIdentity);+ return persistSession(req).then(() => {+ logger.info('[OpenIDSessionRefresh] Bound verified legacy OpenID session identity', {+ userId: expectedIdentity.appUserId,+ });+ });+ }++ logger.warn('[OpenIDSessionRefresh] OpenID session token identity mismatch; refusing reuse', {+ userId: expectedIdentity.appUserId,+ has_session_user_id: Boolean(sessionTokens.appUserId),+ has_session_subject: Boolean(sessionTokens.openidSubject),+ has_session_issuer: Boolean(sessionTokens.openidIssuer),+ });+ throw new Error('OpenID session token identity mismatch');+ }++ function decodeJwtExp(token?: string): number | null {+ if (typeof token !== 'string' || token.length === 0) {+ return null;+ }+ try {+ const decoded = jwt.decode(token);+ if (!decoded || typeof decoded !== 'object') {+ return null;+ }+ return typeof decoded.exp === 'number' ? decoded.exp : null;+ } catch (error) {+ logger.debug(+ '[OpenIDSessionRefresh] JWT decode failed (non-fatal)',+ (error as Error)?.message,+ );+ return null;+ }+ }++ /**+ * Returns the access token's expiry in unix seconds, preferring the JWT `exp`+ * claim and falling back to the persisted `accessTokenExpiresAt` written from+ * the IdP's `tokenset.expires_in` on the previous refresh.+ *+ * The fallback exists because some IdPs (Microsoft Entra for Graph audiences,+ * Auth0 without a custom audience) issue OPAQUE access tokens whose expiry+ * cannot be decoded locally. Without this lookup, every OBO call would treat+ * the session as expired and burn an IdP refresh, risking refresh-token+ * rotation thrash under concurrent tool calls.+ *+ * @param {{ accessToken?: string, accessTokenExpiresAt?: number }} sessionTokens+ * @returns {number | null} unix seconds, or null when no source proves an expiry+ */+ function getAccessTokenExp(sessionTokens: SessionOpenIDTokens): number | null {+ const fromJwt = decodeJwtExp(sessionTokens?.accessToken);+ if (fromJwt != null) {+ return fromJwt;+ }+ const persisted = sessionTokens?.accessTokenExpiresAt;+ return typeof persisted === 'number' ? persisted : null;+ }++ function canWriteRefreshTokenCookie(res?: OpenIDResponse): res is OpenIDResponse & {+ cookie: NonNullable<OpenIDResponse['cookie']>;+ } {+ return !!res && typeof res.cookie === 'function' && !res.headersSent;+ }++ /**+ * Returns true when the session token nominated by `tokenPreference` is still+ * valid for at least the skew buffer. Required argument (no default) so every+ * caller is explicit about which token's freshness gates this check.+ *+ * Use 'access_token' for OBO and any flow whose downstream sends the access+ * token to the IdP as an assertion (jwt-bearer / on-behalf-of) — those flows+ * fail when the access token is expired even if the id_token is still fresh.+ * Access-token expiry is read via `getAccessTokenExp`, which handles opaque+ * (non-JWT) tokens by falling back to the persisted `accessTokenExpiresAt`.+ *+ * Use 'id_token' for flows whose downstream is the LibreChat backend itself+ * (e.g. session-token reuse in `refreshController`); the id_token is the+ * standard JWT signed for the client_id audience and is the bearer the SPA+ * sends back to LibreChat.+ *+ * @param {{ accessToken?: string, idToken?: string, accessTokenExpiresAt?: number }} sessionTokens+ * @param {'access_token' | 'id_token'} tokenPreference+ */+ function isLiveSessionTokenStillValid(+ sessionTokens: SessionOpenIDTokens,+ tokenPreference: TokenPreference,+ ): boolean {+ if (tokenPreference !== 'access_token' && tokenPreference !== 'id_token') {+ throw new Error(+ `[OpenIDSessionRefresh] tokenPreference must be 'access_token' or 'id_token', got: ${tokenPreference}`,+ );+ }+ const now = Math.floor(Date.now() / 1000);+ const exp =+ tokenPreference === 'access_token'+ ? getAccessTokenExp(sessionTokens)+ : decodeJwtExp(sessionTokens?.idToken);+ return exp != null && exp > now + UPSTREAM_TOKEN_EXPIRY_BUFFER_SECONDS;+ }++ /**+ * Builds the OIDCTokens shape consumed by `resolveOboToken`. Required+ * `tokenPreference` selects which token's expiry becomes `expires_at` —+ * caller intent must match what the downstream consumer actually validates.+ * `expiresAtOverride` (unix seconds) wins when the caller has an authoritative+ * value such as the IdP's `tokenset.expires_in` from a fresh refresh response;+ * use it after refresh so we never attribute a prior token's `exp` to a freshly+ * rotated counterpart. For 'access_token', the fallback uses `getAccessTokenExp`+ * so opaque tokens are handled correctly via the persisted `accessTokenExpiresAt`.+ *+ * @param {{ accessToken?: string, idToken?: string, refreshToken?: string, accessTokenExpiresAt?: number }} sessionTokens+ * @param {'access_token' | 'id_token'} tokenPreference+ * @param {number} [expiresAtOverride] — unix seconds (preferred when present)+ */+ function buildOIDCTokensFromSession(+ sessionTokens: SessionOpenIDTokens,+ tokenPreference: TokenPreference,+ expiresAtOverride?: number,+ ): MarkedOIDCTokens {+ if (tokenPreference !== 'access_token' && tokenPreference !== 'id_token') {+ throw new Error(+ `[OpenIDSessionRefresh] tokenPreference must be 'access_token' or 'id_token', got: ${tokenPreference}`,+ );+ }+ let expiresAt = expiresAtOverride;+ if (expiresAt == null) {+ expiresAt =+ tokenPreference === 'access_token'+ ? (getAccessTokenExp(sessionTokens) ?? undefined)+ : (decodeJwtExp(sessionTokens?.idToken) ?? undefined);+ }+ return {+ access_token: sessionTokens?.accessToken,+ id_token: sessionTokens?.idToken,+ refresh_token: sessionTokens?.refreshToken,+ expires_at: expiresAt ?? undefined,+ };+ }++ function resolveRefreshIdentityClaims(+ tokenset: OpenIDTokenSet,+ fallbackIdToken?: string,+ ): OpenIDClaims | null {+ if (typeof tokenset.claims === 'function') {+ const claims = tokenset.claims();+ if (claims?.sub) {+ return claims;+ }+ }+ const idToken = tokenset.id_token || fallbackIdToken;+ const decoded = idToken ? jwt.decode(idToken) : null;+ if (!decoded || typeof decoded !== 'object' || typeof decoded.sub !== 'string') {+ return null;+ }+ return decoded as OpenIDClaims;+ }++ function attachBrowserRefreshTokenMarker<T extends MarkedOIDCTokens | null>(+ tokens: T,+ browserRefreshToken?: string,+ ): T {+ if (!tokens || !browserRefreshToken) {+ return tokens;+ }+ Object.defineProperty(tokens, INTERNAL_BROWSER_REFRESH_TOKEN_FIELD, {+ value: browserRefreshToken,+ enumerable: false,+ configurable: true,+ });+ return tokens;+ }++ function getBrowserRefreshTokenMarker(tokens: MarkedOIDCTokens): string | null {+ const browserRefreshToken = tokens?.[INTERNAL_BROWSER_REFRESH_TOKEN_FIELD];+ return typeof browserRefreshToken === 'string' && browserRefreshToken+ ? browserRefreshToken+ : null;+ }++ function attachIdentityIdTokenMarker<T extends MarkedOIDCTokens | null>(+ tokens: T,+ idToken?: string,+ ): T {+ if (!tokens || !idToken) return tokens;+ Object.defineProperty(tokens, INTERNAL_IDENTITY_ID_TOKEN_FIELD, {+ value: idToken,+ enumerable: false,+ configurable: true,+ });+ return tokens;+ }++ function attachPredecessorRefreshTokenMarker<T extends MarkedOIDCTokens | null>(+ tokens: T,+ predecessorRefreshToken?: string,+ ): T {+ if (!tokens || !predecessorRefreshToken) return tokens;+ Object.defineProperty(tokens, INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD, {+ value: predecessorRefreshToken,+ enumerable: false,+ configurable: true,+ });+ return tokens;+ }++ function attachPredecessorAccessTokenMarker<T extends MarkedOIDCTokens | null>(+ tokens: T,+ predecessorAccessToken?: string,+ ): T {+ if (!tokens || !predecessorAccessToken) return tokens;+ Object.defineProperty(tokens, INTERNAL_PREDECESSOR_ACCESS_TOKEN_FIELD, {+ value: predecessorAccessToken,+ enumerable: false,+ configurable: true,+ });+ return tokens;+ }++ function attachDeferredPublicationMarker<T extends MarkedOIDCTokens | null>(+ tokens: T,+ deferred: boolean,+ ): T {+ if (!tokens || !deferred) return tokens;+ Object.defineProperty(tokens, INTERNAL_DEFERRED_PUBLICATION_FIELD, {+ value: true,+ enumerable: false,+ configurable: true,+ });+ return tokens;+ }++ function attachFlightOwnerMarker<T extends MarkedOIDCTokens | null>(+ tokens: T,+ ownerId?: string,+ createdAt?: number,+ ): T {+ if (!tokens || !ownerId) return tokens;+ Object.defineProperty(tokens, '__flightOwnerId', {+ value: ownerId,+ enumerable: false,+ configurable: true,+ });+ if (Number.isFinite(createdAt)) {+ Object.defineProperty(tokens, '__flightCreatedAt', {+ value: createdAt,+ enumerable: false,+ configurable: true,+ });+ }+ return tokens;+ }++ function getPredecessorRefreshTokenMarker(tokens: MarkedOIDCTokens): string | null {+ const predecessor = tokens?.[INTERNAL_PREDECESSOR_REFRESH_TOKEN_FIELD];+ return typeof predecessor === 'string' && predecessor ? predecessor : null;+ }++ function cloneResolvedTokens(tokens: MarkedOIDCTokens): MarkedOIDCTokens {+ const clone = { ...tokens };+ attachBrowserRefreshTokenMarker(clone, getBrowserRefreshTokenMarker(tokens) ?? undefined);+ attachPredecessorRefreshTokenMarker(+ clone,+ getPredecessorRefreshTokenMarker(tokens) ?? undefined,+ );+ attachPredecessorAccessTokenMarker(clone, tokens.__predecessorAccessToken);+ attachDeferredPublicationMarker(clone, tokens.__deferredPublication === true);+ attachFlightOwnerMarker(clone, tokens.__flightOwnerId, tokens.__flightCreatedAt);+ attachIdentityIdTokenMarker(clone, tokens.__identityIdToken);+ return clone;+ }++ function hasSessionAdvancedPastResult(+ existing: SessionOpenIDTokens,+ resolvedTokens: MarkedOIDCTokens,+ predecessorOverride?: string,+ ): boolean {+ const predecessorRefreshToken =+ getPredecessorRefreshTokenMarker(resolvedTokens) ?? predecessorOverride;+ const refreshTokenAdvanced = Boolean(+ predecessorRefreshToken &&+ existing.refreshToken &&+ existing.refreshToken !== predecessorRefreshToken &&+ existing.refreshToken !== resolvedTokens.refresh_token,+ );+ const predecessorAccessToken = resolvedTokens.__predecessorAccessToken;+ const accessTokenAdvanced = Boolean(+ predecessorAccessToken &&+ existing.accessToken &&+ existing.accessToken !== predecessorAccessToken &&+ existing.accessToken !== resolvedTokens.access_token,+ );+ return refreshTokenAdvanced || accessTokenAdvanced;+ }++ async function persistSession(req: OpenIDRequest): Promise<void> {+ if (typeof req?.session?.save !== 'function') {+ return;+ }+ const save = req.session.save.bind(req.session);+ await new Promise<void>((resolve, reject) => {+ save((err?: Error | null) => {+ if (err) {+ reject(err);+ } else {+ resolve();+ }+ });+ });+ }++ /**+ * Writes the rotated refresh token and OpenID marker cookies to the browser so+ * they stay in sync with the session copy. These cookies outlive the shorter+ * express-session cookie and are the fallback `refreshController` reads when+ * the session is gone; without this sync an OBO-triggered rotation would leave+ * stale or mismatched cookies and sign the user out on the next refresh.+ *+ * When no cookie-capable response is available, or `res.headersSent` is true+ * (streaming SSE path), the cookie cannot be set. In this case, store a+ * server-side recovery bridge so that if the session is later lost,+ * `refreshController` can look up the rotated token by hash of the stale cookie+ * token.+ *+ * @param {object} args+ * @param {import('express').Response} [args.res]+ * @param {string} args.newRefreshToken — the rotated token to sync+ * @param {string} [args.oldRefreshToken] — the browser-cookie token to bridge from+ * @param {string} [args.previousSessionRefreshToken] — durable session token to revoke+ * @param {string} [args.userId] — user._id (required for bridge verification)+ * @param {string} [args.tenantId] — user.tenantId (optional, verified on bridge lookup)+ * @param {string} [args.openidIssuer] — user.openidIssuer (optional, verified on bridge lookup)+ */+ async function syncRefreshTokenCookie({+ res,+ newRefreshToken,+ oldRefreshToken,+ previousSessionRefreshToken,+ userId,+ tenantId,+ openidIssuer,+ assertLeaseOwned,+ }: {+ res?: OpenIDResponse;+ newRefreshToken: string;+ oldRefreshToken?: string;+ previousSessionRefreshToken?: string;+ userId?: string;+ tenantId?: string;+ openidIssuer?: string;+ assertLeaseOwned?: LeaseAssertion;+ }): Promise<string | null> {+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }++ if (canWriteRefreshTokenCookie(res)) {+ const expiryInMilliseconds = math(+ process.env.REFRESH_TOKEN_EXPIRY,+ DEFAULT_REFRESH_TOKEN_EXPIRY,+ );+ const expirationDate = new Date(Date.now() + expiryInMilliseconds);+ /**+ * The durable Session record is what authorizes local image access for OpenID users+ * (`authenticateRequest` in `packages/api/src/images/authorization.ts` looks it up by the+ * browser's refresh-token cookie). The cookie just moved to the rotated token, so the record+ * has to move with it — otherwise every image request 401s until the next `/refresh`.+ * The bridge branch below deliberately leaves the record alone: there the browser keeps the+ * old cookie, and `refreshController` rewrites both once it recovers through the bridge.+ */+ if (userId) {+ try {+ await storeOpenIdSession(+ {+ userId,+ refreshToken: newRefreshToken,+ tenantId,+ previousRefreshToken: previousSessionRefreshToken ?? oldRefreshToken,+ },+ { upsertSession, deleteSession },+ );+ } catch (error) {+ /**+ * The durable transition is an upsert followed by deletion. If deletion fails after+ * the upsert succeeds, the IdP has already spent the old token while the browser still+ * carries it. Persist a short predecessor bridge before surfacing the failure so the+ * next request can recover the only viable credential.+ */+ await storeSessionSaveFailureBridge({+ oldRefreshToken,+ newRefreshToken,+ bridgeIdentity: { userId, tenantId, openidIssuer },+ assertLeaseOwned,+ });+ throw error;+ }+ }+ if (assertLeaseOwned) {+ try {+ await assertLeaseOwned();+ } catch (error) {+ if (!isOpenIDRefreshOwnershipError(error)) {+ await storeSessionSaveFailureBridge({+ oldRefreshToken,+ newRefreshToken,+ bridgeIdentity: userId ? { userId, tenantId, openidIssuer } : null,+ });+ throw error;+ }+ if (userId) {+ try {+ await deleteSession({ refreshToken: newRefreshToken });+ } catch (cleanupError) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to remove the successor after ownership loss',+ toOpenIDLogArgument(cleanupError),+ );+ }+ }+ throw error;+ }+ }+ setRefreshTokenCookie(res, newRefreshToken, expirationDate);+ setOpenIDMarkerCookies(res, {+ userId,+ expires: expirationDate,+ refreshExpiryMs: expiryInMilliseconds,+ refreshToken: newRefreshToken,+ });+ return null;+ }++ if (oldRefreshToken && userId) {+ const bridgeVersion = await storeRefreshTokenBridgeWithLease({+ oldRefreshToken,+ newRefreshToken,+ userId,+ tenantId,+ openidIssuer,+ assertLeaseOwned,+ });+ logger.debug('[OpenIDSessionRefresh] Stored refresh-token recovery bridge', {+ userId,+ responseAvailable: !!res,+ headersSent: !!res?.headersSent,+ hasCookieWriter: typeof res?.cookie === 'function',+ });+ return bridgeVersion;+ } else {+ logger.warn(+ '[OpenIDSessionRefresh] Cannot set refresh-token cookie and insufficient context to store bridge',+ {+ responseAvailable: !!res,+ headersSent: !!res?.headersSent,+ hasCookieWriter: typeof res?.cookie === 'function',+ hasOldToken: !!oldRefreshToken,+ hasUserId: !!userId,+ },+ );+ }+ return null;+ }++ async function storeRefreshTokenBridgeWithLease({+ assertLeaseOwned,+ ...bridge+ }: RefreshTokenBridgeInput & { assertLeaseOwned?: LeaseAssertion }): Promise<string | null> {+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }+ const bridgeVersion = await storeRefreshTokenBridge(bridge);+ if (!assertLeaseOwned) {+ return bridgeVersion;+ }+ try {+ await assertLeaseOwned();+ } catch (error) {+ /**+ * Only a proven ownership loss justifies removing what we just published. A coordination+ * read that merely failed leaves ownership unknown, and on the headers-already-sent path+ * this bridge is the only mapping from the token the browser still holds to the one the+ * IdP has already rotated to — deleting it on a transient error signs the user out.+ */+ if (!isOpenIDRefreshOwnershipError(error)) {+ logger.warn(+ '[OpenIDSessionRefresh] Keeping the recovery bridge; lease ownership is undetermined',+ { userId: bridge.userId, error: (error as Error)?.message },+ );+ throw error;+ }+ try {+ await deleteRefreshTokenBridges({+ refreshTokens: [bridge.oldRefreshToken],+ userId: bridge.userId,+ tenantId: bridge.tenantId,+ ...(bridgeVersion ? { version: bridgeVersion } : {}),+ });+ } catch (cleanupError) {+ logger.error(+ '[OpenIDSessionRefresh] Failed to remove bridge after refresh ownership loss',+ toOpenIDLogArgument(cleanupError),+ );+ }+ throw error;+ }+ return bridgeVersion;+ }++ async function storeSessionSaveFailureBridge({+ oldRefreshToken,+ newRefreshToken,+ bridgeIdentity,+ assertLeaseOwned,+ }: {+ oldRefreshToken?: string;+ newRefreshToken?: string;+ bridgeIdentity?: RefreshTokenBridgeIdentity | null;+ assertLeaseOwned?: LeaseAssertion;+ }): Promise<void> {+ if (!oldRefreshToken || !newRefreshToken || !bridgeIdentity?.userId) {+ return;+ }++ try {+ await storeRefreshTokenBridgeWithLease({+ oldRefreshToken,+ newRefreshToken,+ userId: bridgeIdentity.userId,+ tenantId: bridgeIdentity.tenantId,+ openidIssuer: bridgeIdentity.openidIssuer,+ ttl: OPENID_REFRESH_BRIDGE_GRACE_MS,+ assertLeaseOwned,+ });+ logger.warn(+ '[OpenIDSessionRefresh] Stored short refresh-token bridge after session save failure',+ {+ userId: bridgeIdentity.userId,+ ttl: OPENID_REFRESH_BRIDGE_GRACE_MS,+ },+ );+ } catch (bridgeError) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to store refresh-token bridge after session save failure',+ toOpenIDLogArgument(bridgeError),+ );+ }+ }++ async function performIdpRefreshGrant(+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ user: OpenIDUser,+ tokenPreference: TokenPreference,+ identityContext: AuthIdentityContext | undefined,+ assertLeaseOwned?: LeaseAssertion,+ deferPublication = false,+ ): Promise<MarkedOIDCTokens | null> {+ const sessionTokens = req?.session?.openidTokens;+ const refreshToken = sessionTokens?.refreshToken;+ if (!refreshToken) {+ logger.debug(+ '[OpenIDSessionRefresh] Session lacks refresh_token; cannot refresh upstream token',+ );+ return null;+ }++ const config = getOpenIdConfig();+ const refreshParams = buildOpenIDRefreshParams();+ logger.debug('[OpenIDSessionRefresh] Performing inline IdP refresh-token grant');+ const tokenset = await openIdClient.refreshTokenGrant(config, refreshToken, refreshParams);++ /**+ * A rotating grant can finish after this worker's Mongo lease was reclaimed. Re-prove+ * ownership before mutating the Express session, cookies, bridge, or durable session so a+ * stale owner cannot publish credentials after another worker has taken over.+ */+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }++ if (!tokenset?.access_token) {+ throw new Error('IdP refresh returned no access_token');+ }++ /**+ * Preserve previous values when the IdP omits `id_token` / `refresh_token`+ * on rotation (Auth0 with rotation off, MS personal accounts in some flows).+ * Same fallback behavior as setOpenIDAuthTokens.+ */+ const nextIdToken = tokenset.id_token || sessionTokens.idToken;+ const nextRefreshToken = tokenset.refresh_token || refreshToken;+ const browserRefreshToken = sessionTokens.browserRefreshToken || refreshToken;+ const needsRefreshTokenSync = nextRefreshToken !== browserRefreshToken;+ const willWriteRefreshTokenCookie =+ !deferPublication && needsRefreshTokenSync && canWriteRefreshTokenCookie(res);++ /**+ * Capture the freshly-issued access-token's expiry (unix seconds) so the+ * next OBO call can reuse it without a redundant refresh — critical for+ * opaque (non-JWT) access tokens whose expiry isn't readable from the+ * token itself. Source order:+ * 1. tokenset.expires_in — IdP's authoritative value for the new access+ * token. Always preferred when present.+ * 2. decodeJwtExp(tokenset.access_token) — only when access_token is+ * itself a JWT. Decoding is a fact about THIS token, not a guess.+ *+ * Deliberately do NOT fall back to id_token's exp: id_token TTL is governed+ * by IdP session policy and is often longer than access-token TTL. Trusting+ * it would mark an opaque access token reusable past its real lifetime, so+ * a stale token would be sent to the OBO IdP and rejected. When neither+ * source proves an expiry, leave `accessTokenExpiresAt` unset; the next+ * freshness check will correctly fall through to refresh.+ */+ let nextAccessTokenExp = null;+ const accessTokenExpiresIn = normalizeExpiresIn(tokenset.expires_in);+ if (accessTokenExpiresIn != null) {+ nextAccessTokenExp = Math.floor(Date.now() / 1000) + accessTokenExpiresIn;+ } else {+ nextAccessTokenExp = decodeJwtExp(tokenset.access_token);+ }+ /**+ * `normalizeExpiresIn` preserves a zero or negative lifetime rather than discarding it, so a+ * grant can succeed while declaring a credential that is already spent. Publishing it rotates+ * the refresh token and hands the caller a token every freshness check rejects, which turns+ * each OBO call into another rotation. An unknown expiry is not an elapsed one and still+ * publishes.+ */+ if (nextAccessTokenExp != null && nextAccessTokenExp <= Math.floor(Date.now() / 1000)) {+ throw new Error('IdP refresh returned an already-expired access_token');+ }++ const updatedSessionTokens = {+ ...sessionTokens,+ accessToken: tokenset.access_token,+ idToken: nextIdToken,+ refreshToken: nextRefreshToken,+ browserRefreshToken: willWriteRefreshTokenCookie ? nextRefreshToken : browserRefreshToken,+ lastRefreshedAt: Date.now(),+ };+ if (nextAccessTokenExp != null) {+ updatedSessionTokens.accessTokenExpiresAt = nextAccessTokenExp;+ } else {+ /** Drop a stale value rather than carry it across an unknown-expiry rotation. */+ delete updatedSessionTokens.accessTokenExpiresAt;+ }++ const resolvedTokens = buildOIDCTokensFromSession(+ updatedSessionTokens,+ tokenPreference,+ nextAccessTokenExp ?? undefined,+ );+ attachPredecessorAccessTokenMarker(resolvedTokens, sessionTokens.accessToken);+ const identityClaims = resolveRefreshIdentityClaims(tokenset, sessionTokens.idToken);+ if (identityClaims) {+ resolvedTokens.__identityClaims = identityClaims;+ }+ const fallbackIdTokenExp = decodeJwtExp(sessionTokens.idToken);+ if (+ !tokenset.id_token &&+ (fallbackIdTokenExp == null ||+ fallbackIdTokenExp <= Math.floor(Date.now() / 1000) + UPSTREAM_TOKEN_EXPIRY_BUFFER_SECONDS)+ ) {+ delete resolvedTokens.id_token;+ /**+ * The stripped token is still the only identity material this rotation left behind, and a+ * rebuilt token set carries no provider `claims()`, so `getTokenClaims` would have nothing+ * left to read. Keep it reachable for identity resolution without letting it back into the+ * authentication response.+ */+ attachIdentityIdTokenMarker(resolvedTokens, sessionTokens.idToken);+ }++ if (deferPublication) {+ return attachBrowserRefreshTokenMarker(+ resolvedTokens,+ updatedSessionTokens.browserRefreshToken,+ );+ }++ /**+ * Keep the browser refresh-token cookie in sync with the session token. If headers are+ * already sent (SSE streaming), store a recovery bridge instead. Do this before the+ * session save so a transient session-store failure cannot lose an IdP-rotated token.+ */+ let bridgeIdentity = null;+ if (needsRefreshTokenSync) {+ bridgeIdentity = createRefreshTokenBridgeIdentity({+ user,+ requestUser: req?.user,+ userId: identityContext?.appUserId,+ tenantId: identityContext?.tenantId,+ openidIssuer: identityContext?.openidIssuer,+ });++ await syncRefreshTokenCookie({+ res,+ newRefreshToken: nextRefreshToken,+ oldRefreshToken: browserRefreshToken,+ previousSessionRefreshToken: refreshToken,+ userId: bridgeIdentity?.userId,+ tenantId: bridgeIdentity?.tenantId,+ openidIssuer: bridgeIdentity?.openidIssuer,+ assertLeaseOwned,+ });+ }++ /** Cookie/bridge synchronization may involve I/O; do not persist after losing the lease. */+ if (assertLeaseOwned) {+ await assertLeaseOwned();+ }++ if (!req.session) {+ throw new Error('OpenID refresh requires an Express session');+ }+ req.session.openidTokens = updatedSessionTokens;++ try {+ await persistSession(req);+ } catch (error) {+ if (needsRefreshTokenSync && willWriteRefreshTokenCookie) {+ await storeSessionSaveFailureBridge({+ oldRefreshToken: browserRefreshToken,+ newRefreshToken: nextRefreshToken,+ bridgeIdentity,+ assertLeaseOwned,+ });+ }+ throw error;+ }++ logger.info('[OpenIDSessionRefresh] Inline refresh succeeded');+ /**+ * Pass the same expiry as the explicit `expiresAtOverride` so the returned+ * OIDCTokens carries it directly, regardless of token preference. After+ * refresh the IdP's value is authoritative and supersedes any decode.+ */+ return attachBrowserRefreshTokenMarker(+ resolvedTokens,+ updatedSessionTokens.browserRefreshToken,+ );+ }++ async function publishResolvedSessionTokens({+ req,+ res,+ user,+ identityContext,+ resolvedTokens,+ predecessorRefreshToken,+ tokenPreference,+ assertLeaseOwned,+ publicationGeneration,+ effects,+ }: {+ req: OpenIDRequest;+ res?: OpenIDResponse;+ user: OpenIDUser;+ identityContext?: AuthIdentityContext;+ resolvedTokens: MarkedOIDCTokens | null;+ predecessorRefreshToken?: string;+ tokenPreference: TokenPreference;+ assertLeaseOwned?: LeaseAssertion;+ publicationGeneration?: OpenIDPublicationGeneration;+ effects?: SessionPublicationEffects;+ }): Promise<MarkedOIDCTokens | null> {+ if (!resolvedTokens?.access_token) return null;+ if (assertLeaseOwned) await assertLeaseOwned();+ if (typeof req.session?.reload === 'function') {+ const reload = req.session.reload.bind(req.session);+ await new Promise<void>((resolve, reject) => {+ reload((error?: Error | null) => (error ? reject(error) : resolve()));+ });+ }+ if (assertLeaseOwned) await assertLeaseOwned();+ const requestTokens = cloneResolvedTokens(resolvedTokens);+ if (+ req.session?.openidTokens &&+ hasSessionAdvancedPastResult(req.session.openidTokens, requestTokens, predecessorRefreshToken)+ ) {+ logger.info(+ '[OpenIDSessionRefresh] Skipping stale flight publication because the session advanced',+ );+ await assertOpenIDRefreshSessionGenerationAvailable({+ key: req.session.openidTokens.publicationFlightKey,+ ownerId: req.session.openidTokens.publicationFlightOwnerId,+ });+ const effectiveTokens = buildOIDCTokensFromSession(req.session.openidTokens, tokenPreference);+ attachPredecessorRefreshTokenMarker(+ effectiveTokens,+ getPredecessorRefreshTokenMarker(requestTokens) ?? predecessorRefreshToken,+ );+ attachPredecessorAccessTokenMarker(effectiveTokens, requestTokens.__predecessorAccessToken);+ return effectiveTokens;+ }+ const nextRefreshToken = requestTokens.refresh_token ?? predecessorRefreshToken;+ const browserRefreshToken =+ getBrowserRefreshTokenMarker(requestTokens) ?? predecessorRefreshToken;+ if (nextRefreshToken && nextRefreshToken !== browserRefreshToken) {+ const writesBrowserCookie = canWriteRefreshTokenCookie(res);+ const bridgeIdentity = createRefreshTokenBridgeIdentity({+ user,+ requestUser: req.user,+ userId: identityContext?.appUserId,+ tenantId: identityContext?.tenantId,+ openidIssuer: identityContext?.openidIssuer,+ });+ const bridgeVersion = await syncRefreshTokenCookie({+ res,+ newRefreshToken: nextRefreshToken,+ oldRefreshToken: browserRefreshToken,+ previousSessionRefreshToken: predecessorRefreshToken,+ userId: bridgeIdentity?.userId,+ tenantId: bridgeIdentity?.tenantId,+ openidIssuer: bridgeIdentity?.openidIssuer,+ assertLeaseOwned,+ });+ if (effects && bridgeVersion && browserRefreshToken && bridgeIdentity) {+ effects.bridge = {+ version: bridgeVersion,+ predecessorRefreshToken: browserRefreshToken,+ identity: bridgeIdentity,+ };+ }+ if (writesBrowserCookie) {+ if (effects) {+ effects.durableSession = Boolean(bridgeIdentity?.userId);+ effects.browserCookies = true;+ }+ attachBrowserRefreshTokenMarker(requestTokens, nextRefreshToken);+ }+ }+ if (assertLeaseOwned) await assertLeaseOwned();+ const hydrated = await hydrateSessionFromResolvedTokens(+ req,+ requestTokens,+ predecessorRefreshToken,+ false,+ publicationGeneration,+ );+ if (effects && hydrated) {+ effects.expressSession = true;+ }+ if (assertLeaseOwned) await assertLeaseOwned();+ return requestTokens;+ }++ async function rollbackSessionPublication(+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ resolvedTokens: MarkedOIDCTokens | null,+ effects: SessionPublicationEffects,+ successorRefreshToken?: string,+ ): Promise<void> {+ if (effects.durableSession && successorRefreshToken) {+ try {+ await deleteSession({ refreshToken: successorRefreshToken });+ } catch (error) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to remove successor during publication rollback',+ toOpenIDLogArgument(error),+ );+ }+ }+ let shouldClearExpressSession = effects.expressSession;+ if (shouldClearExpressSession && typeof req.session?.reload === 'function') {+ try {+ const reload = req.session.reload.bind(req.session);+ await new Promise<void>((resolve, reject) => {+ reload((error?: Error | null) => (error ? reject(error) : resolve()));+ });+ const current = req.session.openidTokens;+ shouldClearExpressSession = Boolean(+ current &&+ current.accessToken === resolvedTokens?.access_token &&+ current.refreshToken === successorRefreshToken,+ );+ } catch {+ shouldClearExpressSession = true;+ }+ }+ if (shouldClearExpressSession && typeof req.session?.destroy === 'function') {+ try {+ const destroy = req.session.destroy.bind(req.session);+ await new Promise<void>((resolve, reject) => {+ destroy((error?: Error | null) => (error ? reject(error) : resolve()));+ });+ } catch (error) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to destroy Express session during publication rollback',+ toOpenIDLogArgument(error),+ );+ }+ } else if (shouldClearExpressSession && req.session?.openidTokens) {+ delete req.session.openidTokens;+ try {+ await persistSession(req);+ } catch (error) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to clear Express session during publication rollback',+ toOpenIDLogArgument(error),+ );+ }+ }+ if (effects.browserCookies) {+ for (const name of [+ 'refreshToken',+ 'openid_access_token',+ 'openid_id_token',+ 'openid_user_id',+ 'token_provider',+ ]) {+ res?.clearCookie?.(name);+ }+ }+ if (effects.bridge) {+ try {+ await deleteRefreshTokenBridges({+ refreshTokens: [effects.bridge.predecessorRefreshToken],+ userId: effects.bridge.identity.userId,+ tenantId: effects.bridge.identity.tenantId,+ version: effects.bridge.version,+ });+ } catch (error) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to remove publication bridge during rollback',+ toOpenIDLogArgument(error),+ );+ }+ }+ }++ function hasPublicationEffects(effects: SessionPublicationEffects): boolean {+ return Boolean(+ effects.durableSession || effects.browserCookies || effects.expressSession || effects.bridge,+ );+ }++ function createSessionPublicationEffects(): SessionPublicationEffects {+ return {+ durableSession: false,+ browserCookies: false,+ expressSession: false,+ };+ }++ async function publishCompletedFlightTokens({+ key,+ req,+ res,+ user,+ identityContext,+ resolvedTokens,+ predecessorRefreshToken,+ tokenPreference,+ }: {+ key: string;+ req: OpenIDRequest;+ res?: OpenIDResponse;+ user: OpenIDUser;+ identityContext?: AuthIdentityContext;+ resolvedTokens: MarkedOIDCTokens;+ predecessorRefreshToken?: string;+ tokenPreference: TokenPreference;+ }): Promise<MarkedOIDCTokens> {+ if (resolvedTokens.__deferredPublication) {+ throw new Error('OpenID refresh result is awaiting identity validation');+ }+ if (!resolvedTokens.__flightOwnerId) {+ throw new Error('OpenID refresh result is missing its publication generation');+ }+ const publicationGeneration = {+ key,+ ownerId: resolvedTokens.__flightOwnerId,+ createdAt: resolvedTokens.__flightCreatedAt,+ };+ const effects = createSessionPublicationEffects();+ try {+ const effectiveTokens = await publishResolvedSessionTokens({+ req,+ res,+ user,+ identityContext,+ resolvedTokens,+ predecessorRefreshToken,+ tokenPreference,+ assertLeaseOwned: () => assertOpenIDRefreshFlightAvailable(publicationGeneration),+ publicationGeneration,+ effects,+ });+ if (!effectiveTokens) {+ throw new Error('OpenID refresh result is unavailable for publication');+ }+ return effectiveTokens;+ } catch (error) {+ if (isOpenIDRefreshOwnershipError(error) && hasPublicationEffects(effects)) {+ await rollbackSessionPublication(+ req,+ res,+ resolvedTokens,+ effects,+ resolvedTokens.refresh_token ?? predecessorRefreshToken,+ );+ }+ throw error;+ }+ }++ async function performIdpRefresh(+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ user: OpenIDUser,+ tokenPreference: TokenPreference,+ identityContext?: AuthIdentityContext,+ deferPublication = false,+ ): Promise<MarkedOIDCTokens | null> {+ const refreshToken = req?.session?.openidTokens?.refreshToken;+ const predecessorAccessToken = req?.session?.openidTokens?.accessToken;+ const key = createOpenIDRefreshFlightKey({ req, user, refreshToken, identityContext });+ if (!key) {+ return performIdpRefreshGrant(+ req,+ res,+ user,+ tokenPreference,+ identityContext,+ undefined,+ deferPublication,+ );+ }++ let flight;+ try {+ flight = await acquireOpenIDRefreshFlight({ key });+ } catch (error) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to acquire shared refresh flight',+ toOpenIDLogArgument(error),+ );+ throw new Error('OpenID refresh coordination is temporarily unavailable', { cause: error });+ }++ if (!flight.acquired) {+ logger.debug('[OpenIDSessionRefresh] Joining shared refresh flight', {+ key: hashKeyForLogs(key),+ });+ const resolvedTokens = await waitForOpenIDRefreshFlight({ key });+ if (resolvedTokens) {+ if (!deferPublication) {+ return publishCompletedFlightTokens({+ key,+ req,+ res,+ user,+ identityContext,+ resolvedTokens,+ predecessorRefreshToken: refreshToken,+ tokenPreference,+ });+ }+ return resolvedTokens;+ }++ logger.warn('[OpenIDSessionRefresh] Shared refresh flight remained unresolved', {+ key: hashKeyForLogs(key),+ });+ throw new Error('OpenID refresh coordination is temporarily unavailable');+ }++ return withOpenIDRefreshFlightLease({+ key,+ ownerId: flight.ownerId,+ operation: async ({ assertLeaseOwned, markLeaseSettled }: LeaseContext) => {+ let recoveryBridgeVersion: string | null = null;+ let recoveryBridgeIdentity: RefreshTokenBridgeIdentity | null = null;+ let recoveryBridgePredecessor: string | undefined;+ let resolvedTokens: MarkedOIDCTokens | null = null;+ let successorRefreshToken: string | undefined;+ let completionIndeterminate = false;+ const publicationEffects = createSessionPublicationEffects();+ try {+ resolvedTokens = await performIdpRefreshGrant(+ req,+ res,+ user,+ tokenPreference,+ identityContext,+ assertLeaseOwned,+ true,+ );+ attachPredecessorRefreshTokenMarker(resolvedTokens, refreshToken);+ attachPredecessorAccessTokenMarker(resolvedTokens, predecessorAccessToken);+ attachDeferredPublicationMarker(resolvedTokens, deferPublication);+ const flightCreatedAt = flight.flight?.createdAt+ ? new Date(flight.flight.createdAt).getTime()+ : Date.now();+ attachFlightOwnerMarker(resolvedTokens, flight.ownerId, flightCreatedAt);+ successorRefreshToken = resolvedTokens?.refresh_token ?? refreshToken;+ const browserRefreshToken = resolvedTokens+ ? (getBrowserRefreshTokenMarker(resolvedTokens) ?? refreshToken)+ : refreshToken;+ if (+ !deferPublication &&+ successorRefreshToken &&+ browserRefreshToken &&+ successorRefreshToken !== browserRefreshToken+ ) {+ recoveryBridgeIdentity = createRefreshTokenBridgeIdentity({+ user,+ requestUser: req.user,+ userId: identityContext?.appUserId,+ tenantId: identityContext?.tenantId,+ openidIssuer: identityContext?.openidIssuer,+ });+ recoveryBridgePredecessor = browserRefreshToken;+ if (recoveryBridgeIdentity) {+ recoveryBridgeVersion = await storeRefreshTokenBridgeWithLease({+ oldRefreshToken: browserRefreshToken,+ newRefreshToken: successorRefreshToken,+ userId: recoveryBridgeIdentity.userId,+ tenantId: recoveryBridgeIdentity.tenantId,+ openidIssuer: recoveryBridgeIdentity.openidIssuer,+ ttl: OPENID_REFRESH_BRIDGE_GRACE_MS,+ assertLeaseOwned,+ });+ }+ }+ if (!deferPublication) {+ await publishResolvedSessionTokens({+ req,+ res,+ user,+ identityContext,+ resolvedTokens,+ predecessorRefreshToken: refreshToken,+ tokenPreference,+ assertLeaseOwned,+ publicationGeneration: { key, ownerId: flight.ownerId, createdAt: flightCreatedAt },+ effects: publicationEffects,+ });+ }+ let completedFlight: RefreshFlightRecord | null = null;+ try {+ completedFlight = await completeOpenIDRefreshFlight({+ key,+ ownerId: flight.ownerId,+ tokens: resolvedTokens,+ });+ } catch (completionError) {+ completionIndeterminate = true;+ try {+ const observed = await assertOpenIDRefreshFlightAvailable({+ key,+ ownerId: flight.ownerId,+ });+ if (typeof observed === 'object') {+ completedFlight = observed;+ completionIndeterminate = false;+ }+ } catch {+ /** Keep the pending generation recoverable when completion cannot be observed. */+ }+ if (!completedFlight) {+ throw completionError;+ }+ }+ if (!completedFlight) {+ throw createOpenIDRefreshOwnershipError(+ 'OpenID refresh coordination ownership was lost before completion',+ );+ }+ attachFlightOwnerMarker(resolvedTokens, completedFlight.ownerId ?? flight.ownerId);+ markLeaseSettled();+ return resolvedTokens;+ } catch (error) {+ if (isOpenIDRefreshOwnershipError(error) && hasPublicationEffects(publicationEffects)) {+ await rollbackSessionPublication(+ req,+ res,+ resolvedTokens,+ publicationEffects,+ successorRefreshToken,+ );+ }+ if (+ isOpenIDRefreshOwnershipError(error) &&+ recoveryBridgeVersion &&+ recoveryBridgeIdentity &&+ recoveryBridgePredecessor &&+ !publicationEffects.bridge+ ) {+ try {+ await deleteRefreshTokenBridges({+ refreshTokens: [recoveryBridgePredecessor],+ userId: recoveryBridgeIdentity.userId,+ tenantId: recoveryBridgeIdentity.tenantId,+ version: recoveryBridgeVersion,+ });+ } catch (cleanupError) {+ logger.warn(+ '[OpenIDSessionRefresh] Failed to remove the owned bridge after refresh revocation',+ toOpenIDLogArgument(cleanupError),+ );+ }+ }+ if (!completionIndeterminate) {+ try {+ await failOpenIDRefreshFlight({+ key,+ ownerId: flight.ownerId,+ error: error instanceof Error ? error : new Error('OpenID session refresh failed'),+ });+ } catch (flightError) {+ logger.warn('[OpenIDSessionRefresh] Failed to mark shared refresh flight failed', {+ key: hashKeyForLogs(key),+ error: (flightError as Error)?.message,+ });+ }+ } else {+ logger.warn(+ '[OpenIDSessionRefresh] Keeping an indeterminate publication generation recoverable',+ { key: hashKeyForLogs(key) },+ );+ }+ throw error;+ }+ },+ });+ }++ /**+ * Hydrates `req.session.openidTokens` from a resolved OIDCTokens result and+ * persists it. Used by joining requests in the single-flight path: the leader+ * mutates only its own `req.session`, so a joiner carrying a distinct `req`+ * (including a renewed Express session) would otherwise re-read+ * stale tokens on its next OBO call. This includes stable-refresh-token IdPs,+ * where the refresh token remains unchanged but the access token and expiry+ * were refreshed by the leader.+ * Idempotent when the joiner shares the leader's `req` object.+ */+ async function hydrateSessionFromResolvedTokens(+ req: OpenIDRequest,+ resolvedTokens: MarkedOIDCTokens | null,+ predecessorOverride?: string,+ reloadSession = true,+ publicationGeneration?: OpenIDPublicationGeneration,+ ): Promise<boolean> {+ if (!req?.session || !resolvedTokens?.access_token) {+ return false;+ }+ if (reloadSession && typeof req.session.reload === 'function') {+ const reload = req.session.reload.bind(req.session);+ await new Promise<void>((resolve, reject) => {+ reload((error?: Error | null) => (error ? reject(error) : resolve()));+ });+ }+ const existing = req.session.openidTokens ?? {};+ const generationDiffers = Boolean(+ publicationGeneration &&+ existing.publicationFlightKey &&+ (existing.publicationFlightKey !== publicationGeneration.key ||+ existing.publicationFlightOwnerId !== publicationGeneration.ownerId),+ );+ const existingGenerationIsNewer = Boolean(+ generationDiffers &&+ existing.publicationFlightCreatedAt != null &&+ (publicationGeneration?.createdAt == null ||+ existing.publicationFlightCreatedAt >= publicationGeneration.createdAt),+ );+ if (existingGenerationIsNewer) {+ logger.info(+ '[OpenIDSessionRefresh] Skipping stale flight hydration because its generation is older',+ );+ return false;+ }+ if (hasSessionAdvancedPastResult(existing, resolvedTokens, predecessorOverride)) {+ logger.info(+ '[OpenIDSessionRefresh] Skipping stale flight hydration because the session advanced',+ );+ return false;+ }+ const accessTokenChanged = existing.accessToken !== resolvedTokens.access_token;+ const idTokenChanged =+ resolvedTokens.id_token != null && existing.idToken !== resolvedTokens.id_token;+ const refreshTokenChanged =+ resolvedTokens.refresh_token != null &&+ existing.refreshToken !== resolvedTokens.refresh_token;+ const resolvedBrowserRefreshToken = getBrowserRefreshTokenMarker(resolvedTokens);+ const browserRefreshTokenChanged =+ resolvedBrowserRefreshToken != null &&+ existing.browserRefreshToken !== resolvedBrowserRefreshToken;+ const hasResolvedExpiry = typeof resolvedTokens.expires_at === 'number';+ const expiresAtChanged = hasResolvedExpiry+ ? existing.accessTokenExpiresAt !== resolvedTokens.expires_at+ : accessTokenChanged && existing.accessTokenExpiresAt !== undefined;+ const publicationGenerationChanged = publicationGeneration+ ? existing.publicationFlightKey !== publicationGeneration.key ||+ existing.publicationFlightOwnerId !== publicationGeneration.ownerId+ : false;++ if (+ !accessTokenChanged &&+ !idTokenChanged &&+ !refreshTokenChanged &&+ !browserRefreshTokenChanged &&+ !expiresAtChanged &&+ !publicationGenerationChanged+ ) {+ return false;+ }++ const nextSessionTokens = {+ ...existing,+ accessToken: resolvedTokens.access_token,+ idToken: resolvedTokens.id_token ?? existing.idToken,+ refreshToken: resolvedTokens.refresh_token ?? existing.refreshToken,+ browserRefreshToken: resolvedBrowserRefreshToken ?? existing.browserRefreshToken,+ lastRefreshedAt: Date.now(),+ ...(publicationGeneration+ ? {+ publicationFlightKey: publicationGeneration.key,+ publicationFlightOwnerId: publicationGeneration.ownerId,+ publicationFlightCreatedAt: publicationGeneration.createdAt,+ }+ : {}),+ };+ if (hasResolvedExpiry) {+ nextSessionTokens.accessTokenExpiresAt = resolvedTokens.expires_at;+ } else if (accessTokenChanged) {+ delete nextSessionTokens.accessTokenExpiresAt;+ }+ req.session.openidTokens = nextSessionTokens;+ await persistSession(req);+ return true;+ }++ async function refreshOrReuseSession(+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ user: OpenIDUser,+ tokenPreference: TokenPreference,+ identityContext?: AuthIdentityContext,+ forceRefresh = false,+ deferPublication = false,+ ): Promise<MarkedOIDCTokens | null> {+ const sessionTokens = req?.session?.openidTokens;+ if (!sessionTokens) {+ logger.debug('[OpenIDSessionRefresh] No session tokens to refresh from');+ return null;+ }++ if (!forceRefresh && isLiveSessionTokenStillValid(sessionTokens, tokenPreference)) {+ await assertOpenIDRefreshSessionGenerationAvailable({+ key: sessionTokens.publicationFlightKey,+ ownerId: sessionTokens.publicationFlightOwnerId,+ });+ logger.debug('[OpenIDSessionRefresh] Live session token reused');+ return buildOIDCTokensFromSession(sessionTokens, tokenPreference);+ }++ return performIdpRefresh(req, res, user, tokenPreference, identityContext, deferPublication);+ }++ /**+ * Single-flighted entry point. Concurrent callers for the same user share one+ * in-flight refresh. The map is cleared in finally so a failed refresh does+ * not pin subsequent retries.+ *+ * @param {import('express').Request} req+ * @param {import('express').Response} [res] — when present and writable, the+ * rotated refresh token is mirrored to the `refreshToken` cookie.+ * @param {import('@librechat/data-schemas').IUser} user+ * @param {'access_token' | 'id_token'} tokenPreference — required; selects+ * which token's `exp` gates the live-vs-refresh decision and populates the+ * returned `expires_at`. OBO callers pass 'access_token'.+ */+ async function refreshOpenIDSession(+ req: OpenIDRequest,+ res: OpenIDResponse | undefined,+ user: OpenIDUser,+ tokenPreference: TokenPreference,+ identityContext?: AuthIdentityContext,+ options: RefreshSessionOptions = {},+ ): Promise<MarkedOIDCTokens | null> {+ const identityBinding = assertOpenIDSessionIdentityMatch(req, user, identityContext);+ if (identityBinding) {+ await identityBinding;+ }+ if (options.assertLeaseOwned) {+ return performIdpRefreshGrant(+ req,+ res,+ user,+ tokenPreference,+ identityContext,+ options.assertLeaseOwned,+ options.deferPublication,+ );+ }+ const key = getSingleFlightKey(req, user, identityContext);+ if (!key) {+ return refreshOrReuseSession(+ req,+ res,+ user,+ tokenPreference,+ identityContext,+ options.forceRefresh,+ options.deferPublication,+ );+ }++ const inFlight = inFlightRefreshes.get(key);+ if (inFlight) {+ const predecessorRefreshToken = req?.session?.openidTokens?.refreshToken;+ const sharedFlightKey = createOpenIDRefreshFlightKey({+ req,+ user,+ refreshToken: predecessorRefreshToken,+ identityContext,+ });+ logger.debug(`[OpenIDSessionRefresh] Joining in-flight refresh (key=${hashKeyForLogs(key)})`);+ const resolvedTokens = await inFlight;+ /**+ * The leader mutated only its own request's session. Copy the resolved+ * tokens into THIS request's session so a later OBO call on the joiner+ * reads the rotated refresh token instead of replaying the stale one.+ */+ if (!options.deferPublication) {+ if (resolvedTokens?.__deferredPublication) {+ throw new Error('OpenID refresh result is awaiting identity validation');+ }+ const currentSessionTokens = req.session?.openidTokens;+ const alreadyCurrent = Boolean(+ currentSessionTokens?.accessToken === resolvedTokens?.access_token &&+ currentSessionTokens?.refreshToken ===+ (resolvedTokens?.refresh_token ?? predecessorRefreshToken),+ );+ if (alreadyCurrent) {+ if (resolvedTokens?.__flightOwnerId) {+ if (!sharedFlightKey) {+ throw new Error('OpenID refresh coordination key is unavailable for publication');+ }+ await assertOpenIDRefreshFlightAvailable({+ key: sharedFlightKey,+ ownerId: resolvedTokens.__flightOwnerId,+ });+ }+ return resolvedTokens;+ }+ if (!sharedFlightKey || !resolvedTokens) {+ throw new Error('OpenID refresh coordination key is unavailable for publication');+ }+ return publishCompletedFlightTokens({+ key: sharedFlightKey,+ req,+ res,+ user,+ identityContext,+ resolvedTokens,+ predecessorRefreshToken,+ tokenPreference,+ });+ }+ return resolvedTokens;+ }++ const promise = refreshOrReuseSession(+ req,+ res,+ user,+ tokenPreference,+ identityContext,+ options.forceRefresh,+ options.deferPublication,+ ).finally(() => {+ if (inFlightRefreshes.get(key) === promise) {+ inFlightRefreshes.delete(key);+ }+ });+ inFlightRefreshes.set(key, promise);+ /** Swallow rejection on the cleanup chain; the original is delivered to the awaiter. */+ promise.catch(() => {});+ return promise;+ }++ /**+ * Returns true when this user is in scope for OIDC session refresh. Non-OIDC+ * users and deployments without `OPENID_REUSE_TOKENS` never had a populated+ * `req.session.openidTokens` to begin with. Bearer-authenticated remote-agent requests may use+ * their current verified bearer; browser requests whose session capability disappeared reject.+ */+ function isOIDCRefreshApplicable(user?: OpenIDUser): user is OpenIDUser {+ if (!isEnabled(process.env.OPENID_REUSE_TOKENS)) {+ return false;+ }+ if (!user) {+ return false;+ }+ return user.provider === 'openid' || Boolean(user.openidId);+ }++ /**+ * Builds the UpstreamTokenProvider closure forwarded into the MCP layer.+ * The closure closes over `req` so it reads `req.session.openidTokens` at OBO+ * call time (not at request validation), which is what makes the walk-away+ * failure mode recover without a user-visible re-authentication.+ *+ * `tokenPreference` is required and identifies which upstream token's freshness+ * gates the closure. OBO needs 'access_token' because the OBO exchange uses+ * the access token as the jwt-bearer assertion; using id_token preference here+ * would let an expired access token reach the IdP under a still-fresh id_token.+ *+ * Closure contract (matches `UpstreamTokenProvider` in obo.ts):+ * - resolves to non-null OIDCTokens when fresh tokens are available.+ * - resolves to null when refresh is not applicable or the request itself carries the+ * verified upstream bearer (the remote-agent flow).+ * - rejects when an Express session existed but its OpenID capability was cleared, so a+ * strategy-time `user.federatedTokens` snapshot cannot bypass logout.+ * - rejects when session identity metadata does not match the current user.+ * - rejects when refresh was attempted and rejected by the IdP. The MCP+ * layer wraps the rejection as `session_refresh_failed`.+ *+ * @param {object} args+ * @param {import('express').Request} [args.req]+ * @param {import('express').Response} [args.res] — forwarded so a rotated+ * refresh token can be mirrored to the `refreshToken` cookie when the+ * response is still writable (no-op on the streaming tool-call path).+ * @param {import('@librechat/data-schemas').IUser} [args.user]+ * @param {import('@librechat/api').AuthIdentityContext} [args.identityContext]+ * @param {'access_token' | 'id_token'} args.tokenPreference+ * @returns {() => Promise<import('@librechat/data-schemas').OIDCTokens | null>}+ */+ function createOpenIDSessionTokenProvider({+ req,+ res,+ user,+ tokenPreference,+ identityContext,+ }: CreateOpenIDSessionTokenProviderInput): () => Promise<OIDCTokens | null> {+ if (tokenPreference !== 'access_token' && tokenPreference !== 'id_token') {+ throw new Error(+ `[OpenIDSessionRefresh] createOpenIDSessionTokenProvider requires tokenPreference 'access_token' or 'id_token', got: ${tokenPreference}`,+ );+ }+ return async function upstreamTokenProvider() {+ if (!isOIDCRefreshApplicable(user)) {+ return null;+ }+ if (!req?.session?.openidTokens) {+ const authorization = req?.headers?.authorization;+ const bearerToken = authorization?.match(/^Bearer\s+(.+)$/i)?.[1];+ const carriesCurrentUpstreamBearer = Boolean(+ bearerToken && bearerToken === user?.federatedTokens?.access_token,+ );+ if (req?.session && !carriesCurrentUpstreamBearer) {+ throw createOpenIDRefreshOwnershipError('OpenID session tokens are no longer available');+ }+ logger.debug(+ '[OpenIDSessionRefresh] No session.openidTokens available on req; closure returning null',+ );+ return null;+ }+ const resolvedIdentityContext =+ identityContext ??+ createAuthIdentityContext({+ user,+ requestUser: req?.user,+ });+ return refreshOpenIDSession(req, res, user, tokenPreference, resolvedIdentityContext);+ };+ }++ return {+ createOpenIDSessionTokenProvider,+ refreshOpenIDSession,+ /** Exposed for tests; not a public API. */+ __internals: {+ UPSTREAM_TOKEN_EXPIRY_BUFFER_SECONDS,+ inFlightRefreshes,+ getSingleFlightKey,+ isLiveSessionTokenStillValid,+ getAccessTokenExp,+ },+ };+}diff --git a/packages/api/src/auth/openid/types.ts b/packages/api/src/auth/openid/types.tsnew file mode 100644index 0000000000..ff1c42e947--- /dev/null+++ b/packages/api/src/auth/openid/types.ts@@ -0,0 +1,175 @@+import type { OIDCTokens } from '@librechat/data-schemas';+import type {+ AuthIdentityContext,+ AuthIdentitySource,+ AuthIdentityTuple,+ OpenIDSessionIdentitySource,+ RefreshTokenBridgeIdentity,+} from '~/utils/identity';++export type TokenPreference = 'access_token' | 'id_token';+export type AsyncVoidCallback = (error?: Error | null) => void;+export type LeaseAssertion = () => Promise<object | null | boolean>;+export type LogArgument = string | number | boolean | Error | object | null | undefined;++export interface OpenIDPublicationGeneration {+ key: string;+ ownerId: string;+ createdAt?: number;+}++export interface OpenIDClaims {+ sub: string;+ oid?: string;+ email?: string;+ iss?: string;+}++export interface OpenIDTokenSet extends OIDCTokens {+ access_token?: string;+ expires_in?: number | string;+ claims?: () => OpenIDClaims;+ /**+ * Set non-enumerably when an inline refresh strips an expired carried-forward `id_token` from+ * the result. It is identity material only — never an authentication response token.+ */+ __identityIdToken?: string;+ /** Serializable identity evidence for shared-flight followers. */+ __identityClaims?: OpenIDClaims;+ /** Access token that the shared candidate advanced from. */+ __predecessorAccessToken?: string;+}++export interface SharedOpenIDRefreshResult {+ tokenset: OpenIDTokenSet;+ claims: OpenIDClaims;+ openidIssuer?: string;+ expires_at?: number;+ appAuthToken: string;+ predecessorAccessToken?: string;+ acceptedIdentity?: AuthIdentityContext;+ /** Non-enumerable durable generation marker restored by the flight service. */+ __flightOwnerId?: string;+ __flightCreatedAt?: number;+}++export interface SessionOpenIDTokens {+ accessToken?: string;+ idToken?: string;+ refreshToken?: string;+ browserRefreshToken?: string;+ expiresAt?: number;+ lastRefreshedAt?: number;+ appUserId?: string;+ openidSubject?: string;+ tenantId?: string;+ openidIssuer?: string;+ accessTokenExpiresAt?: number;+ /** Durable coordination generation that authorized this session publication. */+ publicationFlightKey?: string;+ publicationFlightOwnerId?: string;+ publicationFlightCreatedAt?: number;+}++export interface OpenIDSession {+ openidTokens?: SessionOpenIDTokens;+ save?: (callback: AsyncVoidCallback) => void;+ reload?: (callback: AsyncVoidCallback) => void;+ destroy?: (callback: AsyncVoidCallback) => void;+}++export interface OpenIDRequest {+ headers?: { authorization?: string; cookie?: string };+ session?: OpenIDSession;+ sessionID?: string;+ user?: OpenIDUser;+}++export interface OpenIDResponse {+ headersSent?: boolean;+ cookie?: (name: string, value: string, options?: { expires?: Date }) => void;+ clearCookie?: (name: string) => void;+}++export interface OpenIDUser extends AuthIdentitySource {+ _id?: string | number | { toString(): string };+ id?: string;+ email?: string;+ provider?: string;+ openidId?: string;+ tenantId?: string;+ openidIssuer?: string;+ federatedTokens?: OIDCTokens;+}++export interface OpenIDRefreshResolution {+ tokenset: OpenIDTokenSet;+ claims: OpenIDClaims;+ openidIssuer?: string;+ user?: OpenIDUser | null;+ error?: string | null;+ migration?: boolean;+}++export interface OpenIDLogger {+ debug: (...args: LogArgument[]) => void;+ info: (...args: LogArgument[]) => void;+ warn: (...args: LogArgument[]) => void;+ error: (...args: LogArgument[]) => void;+}++export interface LeaseContext {+ assertLeaseOwned: LeaseAssertion;+ markLeaseSettled: () => void;+}++export interface RefreshFlightAcquireResult {+ acquired: boolean;+ key: string | null;+ ownerId: string;+ flight?: RefreshFlightRecord | null;+}++export interface RefreshFlightRecord {+ status?: 'pending' | 'completed' | 'failed' | 'revoked';+ ownerId?: string;+ createdAt?: Date | string;+ deliveryId?: string;+ deliveryExpiresAt?: Date | string;+ revocationRequestedAt?: Date | string;+ encryptedResult?: string;+ errorMessage?: string;+ expiresAt?: Date | string;+}++export interface RefreshTokenBridgeInput {+ oldRefreshToken: string;+ newRefreshToken: string;+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+ ttl?: number;+}++export interface RefreshTokenBridgeDeleteInput {+ refreshTokens: string[];+ userId: string;+ tenantId?: string;+ version?: string;+}++export interface RefreshKeyInput {+ req?: OpenIDRequest;+ user?: OpenIDUser;+ refreshToken?: string;+ identityContext?: AuthIdentityContext;+}++export type {+ AuthIdentityContext,+ AuthIdentitySource,+ AuthIdentityTuple,+ OpenIDSessionIdentitySource,+ OIDCTokens,+ RefreshTokenBridgeIdentity,+};diff --git a/packages/api/src/mcp/MCPConnectionFactory.ts b/packages/api/src/mcp/MCPConnectionFactory.tsindex 3aedb7b7a6..e545c1b102 100644--- a/packages/api/src/mcp/MCPConnectionFactory.ts+++ b/packages/api/src/mcp/MCPConnectionFactory.ts@@ -11,7 +11,8 @@ import type {OAuthStoredClientMetadata,OAuthClientSource,} from '~/mcp/oauth';-import type { OboTokenResolver, OboTrustChecker } from '~/mcp/oauth/obo';+import type { OboTokenResolver, OboTrustChecker, UpstreamTokenProvider } from '~/mcp/oauth/obo';+import type { AuthIdentityContext } from '~/utils/identity';import type { FlowStateManager } from '~/flow/manager';import type * as t from './types';import {@@ -74,6 +75,8 @@ export class MCPConnectionFactory {protected readonly connectionTimeout?: number;protected readonly oboTokenResolver?: OboTokenResolver;protected readonly oboTrustChecker?: OboTrustChecker;+ protected readonly upstreamTokenProvider?: UpstreamTokenProvider;+ protected readonly oboIdentityContext?: AuthIdentityContext;private connectionReady = false;/*** Snapshot of the tenant context at factory construction time. Captured eagerly@@ -169,71 +172,93 @@ export class MCPConnectionFactory {protected async discoverToolsInternal(): Promise<ToolDiscoveryResult> {const oauthUrl: string | null = null;let oauthRequired = false;+ let shouldAttemptAuthenticatedDiscovery = true;let oauthTokens: MCPOAuthTokens | null = null;if (this.usesObo) {- oauthTokens = await this.getOboTokens();+ try {+ oauthTokens = await this.getOboTokens();+ } catch (error) {+ if (!(error instanceof OboTokenResolutionError)) {+ throw error;+ }+ oauthRequired = true;+ shouldAttemptAuthenticatedDiscovery = false;+ logger.debug(+ `${this.logPrefix} [Discovery] OBO token resolution failed, attempting unauthenticated tool listing`,+ error,+ );+ }} else if (this.useOAuth) {oauthTokens = await this.getOAuthTokens();}- const connection = new MCPConnection({- serverName: this.serverName,- serverConfig: this.serverConfig,- userId: this.userId,- oauthTokens,- useSSRFProtection: this.useSSRFProtection,- allowedAddresses: this.allowedAddresses,- ephemeralConnection: this.ephemeralConnection,- });- const oauthHandler = () => {- logger.info(- `${this.logPrefix} [Discovery] OAuth required; skipping URL generation in discovery mode`,- );- oauthRequired = true;- connection.emit('oauthFailed', new Error('OAuth required during tool discovery'));- };+ let connection: MCPConnection | null = null;+ let oauthHandler: (() => void) | null = null;+ if (shouldAttemptAuthenticatedDiscovery) {+ connection = new MCPConnection({+ serverName: this.serverName,+ serverConfig: this.serverConfig,+ userId: this.userId,+ oauthTokens,+ useSSRFProtection: this.useSSRFProtection,+ allowedAddresses: this.allowedAddresses,+ ephemeralConnection: this.ephemeralConnection,+ });- // Register unconditionally: non-OAuth servers that return 401 also emit 'oauthRequired',- // and without this listener, connectClient()'s oauthHandledPromise hangs for 30s+.- connection.once('oauthRequired', oauthHandler);+ oauthHandler = () => {+ logger.info(+ `${this.logPrefix} [Discovery] OAuth required; skipping URL generation in discovery mode`,+ );+ oauthRequired = true;+ connection?.emit('oauthFailed', new Error('OAuth required during tool discovery'));+ };- try {- const connectTimeout = this.connectionTimeout ?? this.serverConfig.initTimeout ?? 30000;- await withTimeout(- connection.connect(),- connectTimeout,- `Connection timeout after ${connectTimeout}ms`,- );+ // Register unconditionally: non-OAuth servers that return 401 also emit 'oauthRequired',+ // and without this listener, connectClient()'s oauthHandledPromise hangs for 30s+.+ connection.once('oauthRequired', oauthHandler);- if (await connection.isConnected()) {- const snapshot = await connection.fetchOrderedToolsSnapshot();- connection.removeListener('oauthRequired', oauthHandler);- return {- tools: snapshot.complete ? snapshot.tools : null,- connection,- oauthRequired: false,- oauthUrl: null,- };+ try {+ const connectTimeout = this.connectionTimeout ?? this.serverConfig.initTimeout ?? 30000;+ await withTimeout(+ connection.connect(),+ connectTimeout,+ `Connection timeout after ${connectTimeout}ms`,+ );++ if (await connection.isConnected()) {+ const snapshot = await connection.fetchOrderedToolsSnapshot();+ connection.removeListener('oauthRequired', oauthHandler);+ return {+ tools: snapshot.complete ? snapshot.tools : null,+ connection,+ oauthRequired: false,+ oauthUrl: null,+ };+ }+ } catch {+ MCPConnection.decrementCycleCount(this.serverName);+ logger.debug(+ `${this.logPrefix} [Discovery] Connection failed, attempting unauthenticated tool listing`,+ );}- } catch {- MCPConnection.decrementCycleCount(this.serverName);- logger.debug(- `${this.logPrefix} [Discovery] Connection failed, attempting unauthenticated tool listing`,- );}try {const tools = await this.attemptUnauthenticatedToolListing();- connection.removeListener('oauthRequired', oauthHandler);+ if (connection && oauthHandler) {+ connection.removeListener('oauthRequired', oauthHandler);+ }if (tools && tools.length > 0) {logger.info(`${this.logPrefix} [Discovery] Successfully discovered ${tools.length} tools without auth`,);- try {- await connection.dispose();- } catch {- // Ignore cleanup errors+ if (connection) {+ try {+ await connection.dispose();+ } catch {+ // Ignore cleanup errors+ }}return { tools, connection: null, oauthRequired, oauthUrl };}@@ -243,12 +268,16 @@ export class MCPConnectionFactory {logger.debug(`${this.logPrefix} [Discovery] Unauthenticated tool listing failed`);}- connection.removeListener('oauthRequired', oauthHandler);+ if (connection && oauthHandler) {+ connection.removeListener('oauthRequired', oauthHandler);+ }- try {- await connection.dispose();- } catch {- // Ignore cleanup errors+ if (connection) {+ try {+ await connection.dispose();+ } catch {+ // Ignore cleanup errors+ }}return { tools: null, connection: null, oauthRequired, oauthUrl };@@ -333,6 +362,8 @@ export class MCPConnectionFactory {this.returnOnOAuth = options.returnOnOAuth;this.oboTokenResolver = options.oboTokenResolver;this.oboTrustChecker = options.oboTrustChecker;+ this.upstreamTokenProvider = options.upstreamTokenProvider;+ this.oboIdentityContext = options.oboIdentityContext;} else {this.useOAuth = false;}@@ -345,6 +376,14 @@ export class MCPConnectionFactory {return null;}+ if (!this.upstreamTokenProvider) {+ throw new Error(+ `${this.logPrefix} Internal: upstreamTokenProvider not plumbed for OBO connection. ` ++ 'OBO requires a live upstream-token closure; the caller must construct one via ' ++ 'createOpenIDSessionTokenProvider() and forward it through the MCP connection options.',+ );+ }+if (this.oboTrustChecker) {const config = this.serverConfig as t.ParsedServerConfig;const trusted = await this.oboTrustChecker({@@ -360,8 +399,14 @@ export class MCPConnectionFactory {}}- logger.info(`${this.logPrefix} Resolving OBO token`);- return resolveOboToken(this.user, oboConfig, this.oboTokenResolver);+ logger.info(`${this.logPrefix} Resolving OBO token for scopes: ${oboConfig.scopes}`);+ return resolveOboToken(+ this.user,+ oboConfig,+ this.oboTokenResolver,+ this.upstreamTokenProvider,+ this.oboIdentityContext,+ );}/** Returns true if this server uses OBO instead of standard OAuth */diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.tsindex aa10fdfb77..5a465d44be 100644--- a/packages/api/src/mcp/MCPManager.ts+++ b/packages/api/src/mcp/MCPManager.ts@@ -4,7 +4,8 @@ import { Permissions, PermissionTypes } from 'librechat-data-provider';import { CallToolResultSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';import type { TokenMethods, IUser } from '@librechat/data-schemas';-import type { OboTokenResolver, OboTrustChecker } from '~/mcp/oauth/obo';+import type { OboTokenResolver, OboTrustChecker, UpstreamTokenProvider } from '~/mcp/oauth/obo';+import type { AuthIdentityContext } from '~/utils/identity';import type { GraphTokenResolver } from '~/utils/graph';import type { FlowStateManager } from '~/flow/manager';import type { MCPOAuthTokens } from './oauth';@@ -46,6 +47,8 @@ function createOboToolCallErrorMessage(failureSuffix = 'Please retry.';} else if (error.reason === 'exchange_failed') {failureSuffix = 'Re-authenticate the user or verify the configured OBO scopes and retry.';+ } else if (error.reason === 'session_refresh_failed') {+ failureSuffix = 'Please sign in again.';}return `${logPrefix} ${error.userMessage} Cannot execute tool ${toolName}. ${failureSuffix}`;@@ -369,6 +372,8 @@ export class MCPManager extends UserConnectionManager {connectionTimeout: args.connectionTimeout,oboTokenResolver: args.oboTokenResolver,oboTrustChecker: args.oboTrustChecker,+ upstreamTokenProvider: args.upstreamTokenProvider,+ oboIdentityContext: args.oboIdentityContext,});return finalizeDiscoveryResult(result);@@ -788,6 +793,8 @@ Please follow these instructions when using tools from the respective MCP servergraphTokenResolver,oboTokenResolver,oboTrustChecker,+ upstreamTokenProvider,+ oboIdentityContext,}: {user?: IUser;serverName: string;@@ -807,6 +814,8 @@ Please follow these instructions when using tools from the respective MCP servergraphTokenResolver?: GraphTokenResolver;oboTokenResolver?: OboTokenResolver;oboTrustChecker?: OboTrustChecker;+ upstreamTokenProvider?: UpstreamTokenProvider;+ oboIdentityContext?: AuthIdentityContext;}): Promise<t.FormattedToolResponse> {const userId = user?.id;const logPrefix = userId ? `[MCP][User: ${userId}][${serverName}]` : `[MCP][${serverName}]`;@@ -866,6 +875,8 @@ Please follow these instructions when using tools from the respective MCP serveroauthEnd,oboTokenResolver,oboTrustChecker,+ upstreamTokenProvider,+ oboIdentityContext,graphTokenResolver,signal: options?.signal,customUserVars,@@ -955,9 +966,17 @@ Please follow these instructions when using tools from the respective MCP serverconst resolvedHeaders: Record<string, string> ='headers' in currentOptions ? { ...(currentOptions.headers || {}) } : {};- /** Refresh OBO token on each tool call to ensure it's current */+ /** Resolve the current OBO token for this tool call; the resolver may serve cached tokens. */const oboConfig = rawConfig.obo;if (oboConfig && oboTokenResolver && user) {+ if (!upstreamTokenProvider) {+ throw new McpError(+ ErrorCode.InternalError,+ `${logPrefix} Internal: upstreamTokenProvider not plumbed for OBO tool call. ` ++ 'OBO requires a live upstream-token closure; the caller must construct one via ' ++ 'createOpenIDSessionTokenProvider() and forward it through callTool().',+ );+ }const oboTrusted = oboTrustChecker? await oboTrustChecker({source: rawConfig.source,@@ -976,7 +995,13 @@ Please follow these instructions when using tools from the respective MCP server}let oboTokens: MCPOAuthTokens;try {- oboTokens = await resolveOboToken(user, oboConfig, oboTokenResolver);+ oboTokens = await resolveOboToken(+ user,+ oboConfig,+ oboTokenResolver,+ upstreamTokenProvider,+ oboIdentityContext,+ );} catch (error) {if (error instanceof OboTokenResolutionError) {throw new McpError(diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.tsindex 888f79d910..9d3ab98071 100644--- a/packages/api/src/mcp/UserConnectionManager.ts+++ b/packages/api/src/mcp/UserConnectionManager.ts@@ -472,6 +472,8 @@ export abstract class UserConnectionManager {oauthEnd,oboTokenResolver,oboTrustChecker,+ upstreamTokenProvider,+ oboIdentityContext,signal,returnOnOAuth = false,connectionTimeout,@@ -679,6 +681,8 @@ export abstract class UserConnectionManager {oauthEnd: oauthEnd,oboTokenResolver: oboTokenResolver,oboTrustChecker: oboTrustChecker,+ upstreamTokenProvider: upstreamTokenProvider,+ oboIdentityContext,graphTokenResolver,returnOnOAuth: returnOnOAuth,requestBody: requestBody,diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.tsindex 991690725b..6e2b5e3477 100644--- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts@@ -3,8 +3,8 @@ import type { TokenMethods, IUser } from '@librechat/data-schemas';import type { FlowStateManager } from '~/flow/manager';import type { MCPOAuthTokens } from '~/mcp/oauth';import type * as t from '~/mcp/types';+import { MCPOAuthHandler, MCPTokenStorage, OboTokenResolutionError } from '~/mcp/oauth';import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';-import { MCPOAuthHandler, MCPTokenStorage } from '~/mcp/oauth';import { preProcessGraphTokens } from '~/utils/graph';import { PENDING_STALE_MS } from '~/flow/manager';import { MCPConnection } from '~/mcp/connection';@@ -16,7 +16,15 @@ jest.mock('~/utils/graph', () => ({...jest.requireActual('~/utils/graph'),preProcessGraphTokens: jest.fn(async (options) => options),}));-jest.mock('~/utils');+jest.mock('~/utils', () => {+ const { isEnabled } = jest.requireActual('~/utils/common');+ const { math } = jest.requireActual('~/utils/math');+ return {+ isEnabled,+ math,+ processMCPEnv: jest.fn(),+ };+});jest.mock('@librechat/data-schemas', () => ({logger: {info: jest.fn(),@@ -836,6 +844,10 @@ describe('MCPConnectionFactory', () => {});describe('OAuth event handling', () => {+ beforeEach(() => {+ mockConnectionInstance.connect.mockRejectedValue(new Error('OAuth authentication required'));+ });+it('should handle oauthRequired event for returnOnOAuth scenario', async () => {const basicOptions = {serverName: 'test-server',@@ -4084,6 +4096,66 @@ describe('MCPConnectionFactory', () => {expect(result.connection).toBeNull();});+ it('should degrade OBO resolution failures to unauthenticated discovery', async () => {+ const { resolveOboToken } = jest.requireMock('~/mcp/oauth') as {+ resolveOboToken: jest.Mock;+ };+ const serverConfig = {+ type: 'sse' as const,+ url: 'https://obo.example.com',+ requiresOAuth: false,+ obo: { scopes: 'api://obo-server/Mcp.Tools.ReadWrite' },+ } as unknown as t.MCPOptions;+ const oboError = new OboTokenResolutionError(+ 'session_refresh_failed',+ 'Your sign-in session expired and could not be refreshed. Please sign in again.',+ );++ mockProcessMCPEnv.mockReturnValue(serverConfig);+ resolveOboToken.mockRejectedValueOnce(oboError);+ mockConnectionInstance.connect.mockResolvedValue(undefined);+ mockConnectionInstance.isConnected.mockResolvedValue(true);+ mockConnectionInstance.fetchOrderedToolsSnapshot = jest.fn().mockResolvedValue({+ tools: mockTools,+ complete: true,+ });+ mockConnectionInstance.dispose = jest.fn().mockResolvedValue(undefined);++ const result = await MCPConnectionFactory.discoverTools(+ { serverName: 'obo-srv', serverConfig },+ {+ useOAuth: true,+ user: mockUser as IUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ oboTokenResolver: jest.fn(),+ upstreamTokenProvider: jest.fn(),+ },+ );++ expect(result.tools).toEqual(mockTools);+ expect(result.connection).toBeNull();+ expect(result.oauthRequired).toBe(true);+ expect(result.oauthUrl).toBeNull();+ expect(mockMCPConnection).toHaveBeenCalledTimes(1);+ expect(mockMCPConnection).toHaveBeenCalledWith(+ expect.objectContaining({+ oauthTokens: null,+ }),+ );+ expect(mockLogger.debug).toHaveBeenCalledWith(+ expect.stringContaining(+ '[Discovery] OBO token resolution failed, attempting unauthenticated tool listing',+ ),+ oboError,+ );+ });+it('should return null tools when discovery fails completely', async () => {const basicOptions = {serverName: 'test-server',@@ -4546,4 +4618,87 @@ describe('MCPConnectionFactory', () => {expect(mockMCPOAuthHandler.initiateOAuthFlow).not.toHaveBeenCalled();});});++ describe('OBO upstreamTokenProvider plumbing', () => {+ const oboServerConfig = {+ type: 'sse' as const,+ url: 'https://obo.example.com',+ requiresOAuth: false,+ obo: { scopes: 'api://obo-server/Mcp.Tools.ReadWrite' },+ } as unknown as t.MCPOptions;++ beforeEach(() => {+ mockProcessMCPEnv.mockReturnValue(oboServerConfig);+ mockConnectionInstance.connect.mockResolvedValue(undefined);+ mockConnectionInstance.isConnected.mockResolvedValue(true);+ });++ it('forwards upstreamTokenProvider into resolveOboToken at connection establishment', async () => {+ const { resolveOboToken } = jest.requireMock('~/mcp/oauth') as {+ resolveOboToken: jest.Mock;+ };+ resolveOboToken.mockResolvedValue({+ access_token: 'connection-time-obo-token',+ token_type: 'Bearer',+ obtained_at: Date.now(),+ expires_at: Date.now() + 3600_000,+ });++ const upstreamTokenProvider = jest.fn();+ const oboTokenResolver = jest.fn();++ await MCPConnectionFactory.create(+ { serverName: 'obo-srv', serverConfig: oboServerConfig },+ {+ useOAuth: true,+ user: mockUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ oboTokenResolver,+ upstreamTokenProvider,+ },+ );++ expect(resolveOboToken).toHaveBeenCalledWith(+ mockUser,+ oboServerConfig.obo,+ oboTokenResolver,+ upstreamTokenProvider,+ undefined,+ );+ });++ it('throws an internal error when upstreamTokenProvider is omitted on an OBO connection', async () => {+ const { resolveOboToken } = jest.requireMock('~/mcp/oauth') as {+ resolveOboToken: jest.Mock;+ };+ resolveOboToken.mockClear();+ const oboTokenResolver = jest.fn();++ await expect(+ MCPConnectionFactory.create(+ { serverName: 'obo-srv', serverConfig: oboServerConfig },+ {+ useOAuth: true,+ user: mockUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ oboTokenResolver,+ /** upstreamTokenProvider intentionally omitted */+ },+ ),+ ).rejects.toThrow(/upstreamTokenProvider not plumbed/);+ expect(resolveOboToken).not.toHaveBeenCalled();+ });+ });});diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.tsindex 530bd71c2f..64e1dc7131 100644--- a/packages/api/src/mcp/__tests__/MCPManager.test.ts+++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts@@ -2576,6 +2576,11 @@ describe('MCPManager', () => {} as unknown as MCPConnection;const mockOboTokenResolver = jest.fn();+ const mockUpstreamTokenProvider = jest.fn().mockResolvedValue({+ access_token: 'live-access-token',+ id_token: 'live-id-token',+ expires_at: Math.floor(Date.now() / 1000) + 3600,+ });const serverConfig: t.SSEOptions & { obo: { scopes: string } } = {type: 'sse',@@ -2590,6 +2595,7 @@ describe('MCPManager', () => {beforeEach(() => {mockResolveOboToken.mockReset();+ mockUpstreamTokenProvider.mockClear();});it('should bypass shared app connections for OBO servers and use a user-scoped connection', async () => {@@ -2645,6 +2651,7 @@ describe('MCPManager', () => {typeof manager.callTool>[0]['flowManager'],oboTokenResolver: mockOboTokenResolver,+ upstreamTokenProvider: mockUpstreamTokenProvider,});expect(appConnections.get).not.toHaveBeenCalled();@@ -2695,12 +2702,15 @@ describe('MCPManager', () => {typeof manager.callTool>[0]['flowManager'],oboTokenResolver: mockOboTokenResolver,+ upstreamTokenProvider: mockUpstreamTokenProvider,});expect(mockResolveOboToken).toHaveBeenCalledWith(mockUser,serverConfig.obo,mockOboTokenResolver,+ mockUpstreamTokenProvider,+ undefined,);expect(appConnections.get).not.toHaveBeenCalled();expect(getUserConnectionSpy).toHaveBeenCalled();@@ -2744,6 +2754,7 @@ describe('MCPManager', () => {typeof manager.callTool>[0]['flowManager'],oboTokenResolver: mockOboTokenResolver,+ upstreamTokenProvider: mockUpstreamTokenProvider,}),).rejects.toMatchObject({message: expect.stringContaining('Temporary OBO token exchange failure.'),@@ -2790,6 +2801,7 @@ describe('MCPManager', () => {typeof manager.callTool>[0]['flowManager'],oboTokenResolver: mockOboTokenResolver,+ upstreamTokenProvider: mockUpstreamTokenProvider,}),).rejects.toMatchObject({message: expect.stringContaining('verify the configured OBO scopes'),@@ -2800,6 +2812,35 @@ describe('MCPManager', () => {expect(mockConnection.setRequestHeaders).not.toHaveBeenCalled();expect(mockConnection.client.request).not.toHaveBeenCalled();});++ it('should fail with an internal error when upstreamTokenProvider is omitted on an OBO call', async () => {+ const appConnections = {+ get: jest.fn().mockResolvedValue(mockConnection),+ };++ mockAppConnections(appConnections);+ (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);++ const manager = await MCPManager.createInstance(newMCPServersConfig());+ jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);++ await expect(+ manager.callTool({+ user: mockUser as IUser,+ serverName,+ toolName: 'test_tool',+ provider: 'openai',+ flowManager: mockFlowManager as unknown as Parameters<+ typeof manager.callTool+ >[0]['flowManager'],+ oboTokenResolver: mockOboTokenResolver,+ /** upstreamTokenProvider intentionally omitted */+ }),+ ).rejects.toMatchObject({+ message: expect.stringContaining('upstreamTokenProvider not plumbed'),+ });+ expect(mockResolveOboToken).not.toHaveBeenCalled();+ });});describe('getConnection', () => {diff --git a/packages/api/src/mcp/oauth/obo.spec.ts b/packages/api/src/mcp/oauth/obo.spec.tsindex 039f13da7d..9a837694b7 100644--- a/packages/api/src/mcp/oauth/obo.spec.ts+++ b/packages/api/src/mcp/oauth/obo.spec.ts@@ -1,6 +1,6 @@-import type { IUser } from '@librechat/data-schemas';import { Permissions, PermissionTypes } from 'librechat-data-provider';-import type { OboTokenResolver } from './obo';+import type { IUser } from '@librechat/data-schemas';+import type { OboTokenResolver, UpstreamTokenProvider } from './obo';import { isOboConfigStillTrusted, resolveOboToken } from './obo';jest.mock('@librechat/data-schemas', () => ({@@ -12,14 +12,26 @@ jest.mock('@librechat/data-schemas', () => ({}));jest.mock('~/utils/oidc', () => ({- extractOpenIDTokenInfo: jest.fn(),isOpenIDTokenValid: jest.fn(),+ extractOpenIDTokenInfo: jest.fn(),}));-import { extractOpenIDTokenInfo, isOpenIDTokenValid } from '~/utils/oidc';+import { isOpenIDTokenValid, extractOpenIDTokenInfo } from '~/utils/oidc';-const mockExtractOpenIDTokenInfo = extractOpenIDTokenInfo as jest.Mock;const mockIsOpenIDTokenValid = isOpenIDTokenValid as jest.Mock;+const mockExtractOpenIDTokenInfo = extractOpenIDTokenInfo as jest.Mock;++const farFutureExp = Math.floor(Date.now() / 1000) + 3600;++const liveTokens = {+ access_token: 'live-access-token',+ id_token: 'live-id-token',+ refresh_token: 'live-refresh-token',+ expires_at: farFutureExp,+};++const liveProvider: UpstreamTokenProvider = jest.fn().mockResolvedValue(liveTokens);+const nullProvider: UpstreamTokenProvider = jest.fn().mockResolvedValue(null);describe('resolveOboToken', () => {const mockUser: Partial<IUser> = {@@ -28,11 +40,6 @@ describe('resolveOboToken', () => {openidId: 'oidc-sub-456',email: '[email protected]',name: 'Test User',- federatedTokens: {- access_token: 'federated-access-token',- id_token: 'federated-id-token',- expires_at: Math.floor(Date.now() / 1000) + 3600,- },};const oboConfig = { scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite' };@@ -44,106 +51,198 @@ describe('resolveOboToken', () => {beforeEach(() => {jest.clearAllMocks();+ mockIsOpenIDTokenValid.mockReturnValue(true);+ /** Default: no federated-token fallback unless a test opts in. */+ mockExtractOpenIDTokenInfo.mockReturnValue(null);+ (liveProvider as jest.Mock).mockResolvedValue(liveTokens);+ (mockResolver as jest.Mock).mockResolvedValue({+ access_token: 'exchanged-mcp-token',+ expires_in: 3600,+ });});- it('should throw when user has no valid OpenID token info', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue(null);+ it('throws missing_upstream_token when provider returns null and no federated fallback', async () => {+ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, mockResolver, nullProvider),+ ).rejects.toMatchObject({+ reason: 'missing_upstream_token',+ retryable: false,+ });+ expect(mockResolver).not.toHaveBeenCalled();+ });- await expect(resolveOboToken(mockUser as IUser, oboConfig, mockResolver)).rejects.toMatchObject(- {- reason: 'missing_upstream_token',- retryable: false,- },+ it('falls back to user.federatedTokens for the OBO exchange when provider returns null', async () => {+ /** OIDC remote-agent flow: bearer token on the user, no Express session. */+ mockExtractOpenIDTokenInfo.mockReturnValue({+ accessToken: 'federated-access-token',+ idToken: 'federated-id-token',+ expiresAt: farFutureExp,+ userId: 'oidc-sub-456',+ });+ mockIsOpenIDTokenValid.mockReturnValue(true);++ const result = await resolveOboToken(mockUser as IUser, oboConfig, mockResolver, nullProvider);++ expect(mockExtractOpenIDTokenInfo).toHaveBeenCalledWith(mockUser);+ expect(mockResolver).toHaveBeenCalledWith(+ mockUser,+ 'federated-access-token',+ 'api://mcp-server-id/Mcp.Tools.ReadWrite',+ true,+ undefined,);+ expect(result.access_token).toBe('exchanged-mcp-token');+ });++ it('throws missing_upstream_token when federated fallback token is invalid', async () => {+ mockExtractOpenIDTokenInfo.mockReturnValue({+ accessToken: 'federated-access-token',+ expiresAt: farFutureExp,+ });+ mockIsOpenIDTokenValid.mockReturnValue(false);++ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, mockResolver, nullProvider),+ ).rejects.toMatchObject({+ reason: 'missing_upstream_token',+ retryable: false,+ });+ expect(mockResolver).not.toHaveBeenCalled();+ });++ it('throws session_refresh_failed when provider rejects', async () => {+ const failingProvider: UpstreamTokenProvider = jest+ .fn()+ .mockRejectedValue(new Error('invalid_grant'));++ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, mockResolver, failingProvider),+ ).rejects.toMatchObject({+ reason: 'session_refresh_failed',+ retryable: false,+ userMessage: expect.stringContaining('Please sign in again'),+ });+ expect(mockResolver).not.toHaveBeenCalled();+ });++ it('marks transient session refresh failures as retryable', async () => {+ const failingProvider: UpstreamTokenProvider = jest+ .fn()+ .mockRejectedValue(Object.assign(new Error('service unavailable'), { status: 503 }));++ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, mockResolver, failingProvider),+ ).rejects.toMatchObject({+ reason: 'session_refresh_failed',+ retryable: true,+ userMessage: 'Temporary sign-in session refresh failure.',+ });expect(mockResolver).not.toHaveBeenCalled();});- it('should throw when OpenID token is not valid (expired)', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'some-token' });+ it('throws missing_upstream_token when isOpenIDTokenValid returns false (live token expired)', async () => {mockIsOpenIDTokenValid.mockReturnValue(false);- await expect(resolveOboToken(mockUser as IUser, oboConfig, mockResolver)).rejects.toMatchObject(- {- reason: 'missing_upstream_token',- retryable: false,- },- );+ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, mockResolver, liveProvider),+ ).rejects.toMatchObject({+ reason: 'missing_upstream_token',+ retryable: false,+ });expect(mockResolver).not.toHaveBeenCalled();});- it('should throw when access token is missing from token info', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ userId: 'user-123' });+ it('throws missing_upstream_access_token when live tokens lack an access_token', async () => {+ (liveProvider as jest.Mock).mockResolvedValueOnce({+ access_token: undefined,+ id_token: 'live-id-token',+ expires_at: farFutureExp,+ });+ /** isOpenIDTokenValid is mocked to true here to isolate the access_token guard */mockIsOpenIDTokenValid.mockReturnValue(true);- await expect(resolveOboToken(mockUser as IUser, oboConfig, mockResolver)).rejects.toMatchObject(- {- reason: 'missing_upstream_access_token',- retryable: false,- },- );- expect(mockResolver).not.toHaveBeenCalled();+ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, mockResolver, liveProvider),+ ).rejects.toMatchObject({+ reason: 'missing_upstream_access_token',+ retryable: false,+ });});- it('should call the resolver with correct arguments and return MCPOAuthTokens', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });+ it('uses live token from provider for the OBO exchange and returns MCPOAuthTokens', async () => {mockIsOpenIDTokenValid.mockReturnValue(true);const beforeCall = Date.now();- const result = await resolveOboToken(mockUser as IUser, oboConfig, mockResolver);+ const result = await resolveOboToken(mockUser as IUser, oboConfig, mockResolver, liveProvider);const afterCall = Date.now();+ expect(liveProvider).toHaveBeenCalledTimes(1);expect(mockResolver).toHaveBeenCalledWith(mockUser,- 'federated-access-token',+ 'live-access-token','api://mcp-server-id/Mcp.Tools.ReadWrite',true,+ undefined,);- expect(result).not.toBeNull();- expect(result!.access_token).toBe('exchanged-mcp-token');- expect(result!.token_type).toBe('Bearer');- expect(result!.obtained_at).toBeGreaterThanOrEqual(beforeCall);- expect(result!.obtained_at).toBeLessThanOrEqual(afterCall);- expect(result!.expires_at).toBe(result!.obtained_at + 3600 * 1000);+ expect(result.access_token).toBe('exchanged-mcp-token');+ expect(result.token_type).toBe('Bearer');+ expect(result.obtained_at).toBeGreaterThanOrEqual(beforeCall);+ expect(result.obtained_at).toBeLessThanOrEqual(afterCall);+ expect(result.expires_at).toBe(result.obtained_at + 3570 * 1000);});- it('should default expires_in to 3600 when not provided by resolver', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });- mockIsOpenIDTokenValid.mockReturnValue(true);-+ it('defaults expires_in to 3600 when not provided by resolver', async () => {const resolverNoExpiry: OboTokenResolver = jest.fn().mockResolvedValue({access_token: 'exchanged-token',});- const result = await resolveOboToken(mockUser as IUser, oboConfig, resolverNoExpiry);+ const result = await resolveOboToken(+ mockUser as IUser,+ oboConfig,+ resolverNoExpiry,+ liveProvider,+ );- expect(result).not.toBeNull();- expect(result!.expires_at).toBe(result!.obtained_at + 3600 * 1000);+ expect(result.expires_at).toBe(result.obtained_at + 3570 * 1000);});- it('should throw when resolver returns no access_token', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });- mockIsOpenIDTokenValid.mockReturnValue(true);-+ it('throws when resolver returns no access_token', async () => {const emptyResolver: OboTokenResolver = jest.fn().mockResolvedValue({});await expect(- resolveOboToken(mockUser as IUser, oboConfig, emptyResolver),+ resolveOboToken(mockUser as IUser, oboConfig, emptyResolver, liveProvider),).rejects.toMatchObject({reason: 'empty_exchange_response',retryable: false,});});- it('should throw a retryable error when resolver reports a transient failure', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });- mockIsOpenIDTokenValid.mockReturnValue(true);+ it('preserves empty_exchange_response when the resolver rejects a malformed exchange', async () => {+ const malformedError = Object.assign(+ new Error('The identity provider returned no access token for the OBO exchange'),+ {+ oboFailureReason: 'empty_exchange_response',+ retryable: false,+ },+ );+ const emptyResolver: OboTokenResolver = jest.fn().mockRejectedValue(malformedError);++ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, emptyResolver, liveProvider),+ ).rejects.toMatchObject({+ reason: 'empty_exchange_response',+ retryable: false,+ userMessage: 'The identity provider returned no access token for the OBO exchange.',+ });+ });+ it('throws a retryable error when resolver reports a transient failure', async () => {const failingResolver: OboTokenResolver = jest.fn().mockRejectedValue(Object.assign(new Error('temporary timeout'), { retryable: true }));await expect(- resolveOboToken(mockUser as IUser, oboConfig, failingResolver),+ resolveOboToken(mockUser as IUser, oboConfig, failingResolver, liveProvider),).rejects.toMatchObject({reason: 'exchange_failed',retryable: true,@@ -151,16 +250,13 @@ describe('resolveOboToken', () => {});});- it('should throw a non-retryable error when resolver reports a permanent failure', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });- mockIsOpenIDTokenValid.mockReturnValue(true);-+ it('throws a non-retryable error when resolver reports a permanent failure', async () => {const failingResolver: OboTokenResolver = jest.fn().mockRejectedValue(new Error('invalid_grant: assertion invalid'));await expect(- resolveOboToken(mockUser as IUser, oboConfig, failingResolver),+ resolveOboToken(mockUser as IUser, oboConfig, failingResolver, liveProvider),).rejects.toMatchObject({reason: 'exchange_failed',retryable: false,@@ -168,34 +264,119 @@ describe('resolveOboToken', () => {});});- it('should use the correct scopes from oboConfig', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });- mockIsOpenIDTokenValid.mockReturnValue(true);-+ it('uses the correct scopes from oboConfig', async () => {const customConfig = { scopes: 'api://other-app/Custom.Scope' };- await resolveOboToken(mockUser as IUser, customConfig, mockResolver);+ await resolveOboToken(mockUser as IUser, customConfig, mockResolver, liveProvider);expect(mockResolver).toHaveBeenCalledWith(mockUser,- 'federated-access-token',+ 'live-access-token','api://other-app/Custom.Scope',true,+ undefined,);});- it('should respect custom expires_in from resolver', async () => {- mockExtractOpenIDTokenInfo.mockReturnValue({ accessToken: 'federated-access-token' });- mockIsOpenIDTokenValid.mockReturnValue(true);+ it('forwards identity context to the OBO resolver', async () => {+ const identityContext = {+ openidSubject: 'oidc-sub-456',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer.example.com',+ };++ await resolveOboToken(+ mockUser as IUser,+ oboConfig,+ mockResolver,+ liveProvider,+ identityContext,+ );++ expect(mockResolver).toHaveBeenCalledWith(+ mockUser,+ 'live-access-token',+ 'api://mcp-server-id/Mcp.Tools.ReadWrite',+ true,+ identityContext,+ );+ });+ it('respects custom expires_in from resolver', async () => {const shortLivedResolver: OboTokenResolver = jest.fn().mockResolvedValue({access_token: 'short-lived-token',expires_in: 300,});- const result = await resolveOboToken(mockUser as IUser, oboConfig, shortLivedResolver);+ const result = await resolveOboToken(+ mockUser as IUser,+ oboConfig,+ shortLivedResolver,+ liveProvider,+ );++ expect(result.expires_at).toBe(result.obtained_at + 270 * 1000);+ });++ it('respects absolute expires_at from cached resolver responses', async () => {+ const absoluteExpiresAt = Date.now() + 120 * 1000;+ const cachedResolver: OboTokenResolver = jest.fn().mockResolvedValue({+ access_token: 'cached-token',+ expires_in: 3600,+ expires_at: absoluteExpiresAt,+ });++ const result = await resolveOboToken(+ mockUser as IUser,+ oboConfig,+ cachedResolver,+ liveProvider,+ );++ expect(result.expires_at).toBe(absoluteExpiresAt - 30 * 1000);+ });++ /** A credential the IdP declares already spent must not reach the MCP connection: `callTool`+ * checks only for an access token before setting the Authorization header. */+ it.each([0, -60])(+ 'rejects an exchange response whose declared expiry has already elapsed: %s',+ async (expiresIn) => {+ const expiredResolver: OboTokenResolver = jest.fn().mockResolvedValue({+ access_token: 'already-expired-token',+ expires_in: expiresIn,+ });++ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, expiredResolver, liveProvider),+ ).rejects.toMatchObject({ reason: 'exchange_failed', retryable: true });+ },+ );++ it('rejects an exchange response carrying an absolute expiry in the past', async () => {+ const expiredResolver: OboTokenResolver = jest.fn().mockResolvedValue({+ access_token: 'already-expired-token',+ expires_in: 3600,+ expires_at: Date.now() - 60_000,+ });++ await expect(+ resolveOboToken(mockUser as IUser, oboConfig, expiredResolver, liveProvider),+ ).rejects.toMatchObject({ reason: 'exchange_failed' });+ });++ it('keeps a positive expires_at lifetime for very short-lived OBO tokens', async () => {+ const shortLivedResolver: OboTokenResolver = jest.fn().mockResolvedValue({+ access_token: 'very-short-lived-token',+ expires_in: 10,+ });++ const result = await resolveOboToken(+ mockUser as IUser,+ oboConfig,+ shortLivedResolver,+ liveProvider,+ );- expect(result).not.toBeNull();- expect(result!.expires_at).toBe(result!.obtained_at + 300 * 1000);+ expect(result.expires_at).toBe(result.obtained_at + 1000);});});diff --git a/packages/api/src/mcp/oauth/obo.ts b/packages/api/src/mcp/oauth/obo.tsindex 91b994a682..a87e444e86 100644--- a/packages/api/src/mcp/oauth/obo.ts+++ b/packages/api/src/mcp/oauth/obo.ts@@ -1,8 +1,12 @@import { logger } from '@librechat/data-schemas';import { Permissions, PermissionTypes } from 'librechat-data-provider';-import type { IUser } from '@librechat/data-schemas';-import { extractOpenIDTokenInfo, isOpenIDTokenValid } from '~/utils/oidc';+import type { IUser, OIDCTokens } from '@librechat/data-schemas';+import type { TRole } from 'librechat-data-provider';+import type { AuthIdentityContext } from '~/utils/identity';+import type { OpenIDTokenInfo } from '~/utils/oidc';import type { MCPOAuthTokens } from './types';+import { getSkewedTokenExpiresAtMs, getTokenExpiresAtMs } from '~/oauth/expiry';+import { extractOpenIDTokenInfo, isOpenIDTokenValid } from '~/utils/oidc';export interface OboConfig {scopes: string;@@ -17,13 +21,31 @@ export type OboTokenResolver = (accessToken: string,scopes: string,fromCache?: boolean,-) => Promise<{ access_token: string; expires_in?: number }>;+ identityContext?: AuthIdentityContext,+) => Promise<{ access_token: string; expires_in?: number; expires_at?: number }>;++/**+ * Provides the LIVE upstream OpenID tokens at OBO call time, refreshing the+ * server-side session via the IdP refresh-token grant when the access token+ * has expired. Closes over the active Express request so it can read/write+ * `req.session.openidTokens` in place.+ *+ * Contract:+ * - non-null result: `access_token` MUST be populated; the closure enforces+ * this internally so callers do not defend against missing access_token.+ * - null: not applicable, or a bearer-authenticated remote-agent request whose+ * current upstream token can be read from `user.federatedTokens`.+ * - throws: refresh was attempted and the IdP rejected it. Caller wraps as+ * `session_refresh_failed`.+ */+export type UpstreamTokenProvider = () => Promise<OIDCTokens | null>;export type OboTokenResolutionReason =| 'missing_upstream_token'| 'missing_upstream_access_token'| 'empty_exchange_response'- | 'exchange_failed';+ | 'exchange_failed'+ | 'session_refresh_failed';const RETRYABLE_OBO_STATUS_CODES = new Set([429, 500, 502, 503, 504]);const RETRYABLE_OBO_ERROR_CODES = new Set(['ETIMEDOUT', 'ECONNRESET', 'EAI_AGAIN', 'ENOTFOUND']);@@ -60,6 +82,19 @@ function getErrorRetryableFlag(error: unknown): boolean | undefined {return typeof retryable === 'boolean' ? retryable : undefined;}+function getOboFailureReason(error: unknown): OboTokenResolutionReason | undefined {+ if (!error || typeof error !== 'object' || !('oboFailureReason' in error)) {+ return undefined;+ }++ const reason = (error as { oboFailureReason?: unknown }).oboFailureReason;+ if (reason === 'empty_exchange_response') {+ return reason;+ }++ return undefined;+}+export class OboTokenResolutionError extends Error {public readonly reason: OboTokenResolutionReason;public readonly retryable: boolean;@@ -113,19 +148,78 @@ function isRetryableOboExchangeError(error: unknown): boolean {);}+/**+ * Resolves the upstream OpenID token info used for the OBO exchange. The live+ * session (via `upstreamTokenProvider`) is the preferred source because it can+ * inline-refresh an expired access token. When no live session exists — the+ * OIDC remote-agent flow verifies a bearer token and attaches it to+ * `user.federatedTokens` without an Express session — fall back to the token+ * snapshot on the user via `extractOpenIDTokenInfo`. Returns null when neither+ * source yields a token; the caller maps that to `missing_upstream_token`.+ */+function buildUpstreamTokenInfo(+ user: IUser,+ liveTokens: OIDCTokens | null,+): OpenIDTokenInfo | null {+ if (liveTokens) {+ return {+ accessToken: liveTokens.access_token,+ idToken: liveTokens.id_token,+ expiresAt: liveTokens.expires_at,+ userId: user.openidId || user.id,+ userEmail: user.email,+ userName: user.name || user.username,+ };+ }+ return extractOpenIDTokenInfo(user);+}+/*** Performs an OBO token exchange for the given user and MCP server OBO config.* Returns MCPOAuthTokens suitable for injection into the MCP connection.+ *+ * The `upstreamTokenProvider` closure is the authoritative source of the user's+ * upstream OpenID access token at call time — it reads from the live session and+ * may inline-refresh via the IdP refresh-token grant when the token has expired.+ * This avoids relying on a stale snapshot frozen onto `user.federatedTokens` at+ * request validation, which is what previously caused the walk-away failure mode+ * ("No valid OpenID access token is available for OBO exchange") on long-running+ * tool calls. Required (not optional) so wiring bugs surface at compile time.+ *+ * When the provider yields no live session (it resolves to null), this falls+ * back to `user.federatedTokens` so the OIDC remote-agent flow — whose request+ * itself carries that verified upstream bearer — still works. Browser requests+ * whose Express session was cleared reject in the provider instead of reaching+ * this fallback with a stale strategy-time snapshot.*/export async function resolveOboToken(user: IUser,oboConfig: OboConfig,oboTokenResolver: OboTokenResolver,+ upstreamTokenProvider: UpstreamTokenProvider,+ identityContext?: AuthIdentityContext,): Promise<MCPOAuthTokens> {- const tokenInfo = extractOpenIDTokenInfo(user);+ let liveTokens: OIDCTokens | null;+ try {+ liveTokens = await upstreamTokenProvider();+ } catch (error) {+ logger.error('[OBO] Upstream session refresh failed:', error);+ const retryable = isRetryableOboExchangeError(error);+ throw new OboTokenResolutionError(+ 'session_refresh_failed',+ retryable+ ? 'Temporary sign-in session refresh failure.'+ : 'Your sign-in session expired and could not be refreshed. Please sign in again.',+ retryable,+ error,+ );+ }++ const tokenInfo = buildUpstreamTokenInfo(user, liveTokens);+if (!tokenInfo || !isOpenIDTokenValid(tokenInfo)) {logger.warn(- `[OBO] No valid OpenID token available for OBO exchange (provider: ${user.provider}, hasOpenidId: ${!!user.openidId}, hasFederatedTokens: ${!!user.federatedTokens})`,+ `[OBO] No valid OpenID token available for OBO exchange (provider: ${user.provider}, hasOpenidId: ${!!user.openidId}, hasFederatedTokens: ${!!user.federatedTokens}, hadLiveSession: ${!!liveTokens})`,);throw new OboTokenResolutionError('missing_upstream_token',@@ -142,7 +236,13 @@ export async function resolveOboToken(}try {- const response = await oboTokenResolver(user, tokenInfo.accessToken, oboConfig.scopes, true);+ const response = await oboTokenResolver(+ user,+ tokenInfo.accessToken,+ oboConfig.scopes,+ true,+ identityContext,+ );if (!response?.access_token) {logger.warn('[OBO] Token exchange did not return an access token');@@ -153,19 +253,51 @@ export async function resolveOboToken(}const now = Date.now();- const expiresIn = response.expires_in ?? 3600;+ const expiresAt = getTokenExpiresAtMs({+ expiresAt: response.expires_at,+ expiresIn: response.expires_in,+ now,+ });++ /**+ * Preserving an elapsed expiry only helps if someone acts on it. `MCPManager.callTool` checks+ * the access token and nothing else before setting the Authorization header, so a credential+ * the IdP already declared spent would be sent downstream to fail there. Rejected here, where+ * the reason is still known, and retryably: the exchange itself worked, so another attempt+ * with a fresh grant can succeed.+ */+ const skewedExpiresAt = getSkewedTokenExpiresAtMs(expiresAt, now);+ if (skewedExpiresAt <= now) {+ logger.warn('[OBO] Token exchange returned a credential that is already expired');+ throw new OboTokenResolutionError(+ 'exchange_failed',+ 'The identity provider returned an already-expired token for the OBO exchange.',+ true,+ );+ }return {access_token: response.access_token,token_type: 'Bearer',obtained_at: now,- expires_at: now + expiresIn * 1000,+ expires_at: skewedExpiresAt,};} catch (error) {if (error instanceof OboTokenResolutionError) {throw error;}+ const failureReason = getOboFailureReason(error);+ if (failureReason === 'empty_exchange_response') {+ logger.warn('[OBO] Token exchange did not return an access token');+ throw new OboTokenResolutionError(+ failureReason,+ 'The identity provider returned no access token for the OBO exchange.',+ false,+ error,+ );+ }+logger.error('[OBO] Failed to exchange token:', error);const retryable = isRetryableOboExchangeError(error);throw new OboTokenResolutionError(@@ -193,9 +325,11 @@ export async function resolveOboToken(* - role missing the CONFIGURE_OBO bit*/export type GetUserRoleByAuthorId = (authorId: string) => Promise<string | null | undefined>;-export type GetRolePermissions = (- roleName: string,-) => Promise<Record<string, Record<string, boolean | undefined>> | null | undefined>;+type RolePermissions = Partial<{+ [K in keyof TRole['permissions']]: Partial<TRole['permissions'][K]>;+}>;++export type GetRolePermissions = (roleName: string) => Promise<RolePermissions | null | undefined>;export async function isOboConfigStillTrusted({authorId,@@ -219,7 +353,7 @@ export async function isOboConfigStillTrusted({if (!roleName) {return false;}- let permissions: Record<string, Record<string, boolean | undefined>> | null | undefined;+ let permissions: RolePermissions | null | undefined;try {permissions = await getRolePermissions(roleName);} catch (err) {diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.tsindex e3382f3bbb..ad2eedf0ef 100644--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts@@ -106,6 +106,7 @@ const ADMIN_CONFIGURABLE_FIELDS = ['apiKey','oauth','oauth_headers',+ 'obo','title','description','iconPath',diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.tsindex d5a97b239b..19379e39b4 100644--- a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts+++ b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts@@ -533,4 +533,41 @@ describe('MCPServersInitializer', () => {expect(mockInspect).not.toHaveBeenCalled();});});++ describe('OBO initialization without browser token reuse', () => {+ const oboConfigs: t.MCPServers = {+ obo_server: {+ type: 'streamable-http',+ url: 'https://obo.example.com/mcp',+ obo: { scopes: 'api://obo-server/Mcp.Tools.ReadWrite' },+ } as unknown as t.MCPOptions,+ };++ const originalReuse = process.env.OPENID_REUSE_TOKENS;++ afterEach(() => {+ if (originalReuse == null) {+ delete process.env.OPENID_REUSE_TOKENS;+ } else {+ process.env.OPENID_REUSE_TOKENS = originalReuse;+ }+ });++ it('does not declare OBO unusable because bearer-auth flows remain valid', async () => {+ delete process.env.OPENID_REUSE_TOKENS;+ mockInspect.mockImplementationOnce(+ async (_n, raw) =>+ ({+ ...raw,+ requiresOAuth: false,+ }) as unknown as t.ParsedServerConfig,+ );++ await MCPServersInitializer.initialize(oboConfigs);++ const warnCalls = mockLogger.warn.mock.calls.flat().join(' | ');+ expect(warnCalls).not.toMatch(/OBO is configured/);+ expect(await registry.getServerConfig('obo_server')).toBeDefined();+ });+ });});diff --git a/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts b/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.tsindex 933ff7cec2..bbee631e60 100644--- a/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts+++ b/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts@@ -153,6 +153,23 @@ describe('MCPServersRegistry — ensureConfigServers', () => {expect(inspectSpy).toHaveBeenCalledTimes(1);});+ it('should lazy-init YAML server when admin overrides only the OBO field', async () => {+ await registry.addServer('yaml_remote', sseConfig, 'CACHE');+ inspectSpy.mockClear();++ const overrideConfig: t.MCPOptions = {+ ...sseConfig,+ obo: { scopes: 'api://mcp-server/Mcp.Tools.ReadWrite' },+ };+ const result = await registry.ensureConfigServers({+ yaml_remote: overrideConfig,+ });++ expect(result).toHaveProperty('yaml_remote');+ expect(result.yaml_remote.obo).toEqual({ scopes: 'api://mcp-server/Mcp.Tools.ReadWrite' });+ expect(inspectSpy).toHaveBeenCalledTimes(1);+ });+it('should not re-init YAML server when only the difference is an inspector-derived field absent from rawConfig', async () => {const yamlWithInferred: t.MCPOptions = {...sseConfig,diff --git a/packages/api/src/mcp/types/index.ts b/packages/api/src/mcp/types/index.tsindex e823f421b1..1dba82518c 100644--- a/packages/api/src/mcp/types/index.ts+++ b/packages/api/src/mcp/types/index.ts@@ -19,7 +19,8 @@ import type {import type { SearchResultData, UIResource, TPlugin } from 'librechat-data-provider';import type { TokenMethods, IUser } from '@librechat/data-schemas';import type { LCTool } from '@librechat/agents';-import type { OboTokenResolver, OboTrustChecker } from '~/mcp/oauth/obo';+import type { OboTokenResolver, OboTrustChecker, UpstreamTokenProvider } from '~/mcp/oauth/obo';+import type { AuthIdentityContext } from '~/utils/identity';import type { GraphTokenResolver } from '~/utils/graph';import type { FlowStateManager } from '~/flow/manager';import type { RequestBody } from '~/types/http';@@ -250,6 +251,8 @@ export interface OAuthConnectionOptions extends UserConnectionContext {returnOnOAuth?: boolean;oboTokenResolver?: OboTokenResolver;oboTrustChecker?: OboTrustChecker;+ upstreamTokenProvider?: UpstreamTokenProvider;+ oboIdentityContext?: AuthIdentityContext;}/** Options accepted by UserConnectionManager.getUserConnection. OAuth fields are optional. */@@ -266,6 +269,8 @@ export interface UserMCPConnectionOptions extends UserConnectionContext {returnOnOAuth?: boolean;oboTokenResolver?: OboTokenResolver;oboTrustChecker?: OboTrustChecker;+ upstreamTokenProvider?: UpstreamTokenProvider;+ oboIdentityContext?: AuthIdentityContext;}export interface ToolDiscoveryOptions {@@ -283,6 +288,8 @@ export interface ToolDiscoveryOptions {configServers?: Record<string, ParsedServerConfig>;oboTokenResolver?: OboTokenResolver;oboTrustChecker?: OboTrustChecker;+ upstreamTokenProvider?: UpstreamTokenProvider;+ oboIdentityContext?: AuthIdentityContext;}export interface ToolDiscoveryResult {diff --git a/packages/api/src/oauth/csrf.spec.ts b/packages/api/src/oauth/csrf.spec.tsindex 1199dea297..5fb21a886a 100644--- a/packages/api/src/oauth/csrf.spec.ts+++ b/packages/api/src/oauth/csrf.spec.ts@@ -1,4 +1,13 @@-import { shouldUseSecureCookie } from './csrf';+import crypto from 'crypto';+import jwt from 'jsonwebtoken';+import {+ shouldUseSecureCookie,+ setRefreshTokenCookie,+ setOpenIDMarkerCookies,+ REFRESH_TOKEN_COOKIE,+ TOKEN_PROVIDER_COOKIE,+ OPENID_USER_ID_COOKIE,+} from './csrf';describe('shouldUseSecureCookie', () => {const originalEnv = process.env;@@ -126,3 +135,181 @@ describe('shouldUseSecureCookie', () => {});});});++describe('setRefreshTokenCookie', () => {+ const originalEnv = process.env;++ beforeEach(() => {+ process.env = { ...originalEnv };+ delete process.env.SESSION_COOKIE_SECURE;+ });++ afterAll(() => {+ process.env = originalEnv;+ });++ it('writes the refresh token cookie with httpOnly + strict sameSite and the given expiry', () => {+ process.env.NODE_ENV = 'production';+ process.env.DOMAIN_SERVER = 'https://myapp.example.com';+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 1000);++ setRefreshTokenCookie(res, 'rt-value', expires);++ expect(res.cookie).toHaveBeenCalledWith(REFRESH_TOKEN_COOKIE, 'rt-value', {+ expires,+ httpOnly: true,+ secure: true,+ sameSite: 'strict',+ });+ });++ it('uses an insecure cookie on localhost', () => {+ process.env.NODE_ENV = 'production';+ process.env.DOMAIN_SERVER = 'http://localhost:3080';+ const res = { cookie: jest.fn() } as unknown as import('express').Response;++ setRefreshTokenCookie(res, 'rt-value', new Date());++ expect(res.cookie).toHaveBeenCalledWith(+ REFRESH_TOKEN_COOKIE,+ 'rt-value',+ expect.objectContaining({ secure: false }),+ );+ });+});++describe('setOpenIDMarkerCookies', () => {+ const originalEnv = process.env;++ beforeEach(() => {+ process.env = {+ ...originalEnv,+ JWT_REFRESH_SECRET: 'marker-secret',+ OPENID_REUSE_TOKENS: 'true',+ };+ delete process.env.SESSION_COOKIE_SECURE;+ });++ afterAll(() => {+ process.env = originalEnv;+ });++ it('writes OpenID provider and signed user-id marker cookies with the same expiry', () => {+ process.env.NODE_ENV = 'production';+ process.env.DOMAIN_SERVER = 'https://myapp.example.com';+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 604800000);++ setOpenIDMarkerCookies(res, {+ userId: 'user-123',+ expires,+ refreshExpiryMs: 604800000,+ });++ expect(res.cookie).toHaveBeenCalledWith(TOKEN_PROVIDER_COOKIE, 'openid', {+ expires,+ httpOnly: true,+ secure: true,+ sameSite: 'strict',+ });+ expect(res.cookie).toHaveBeenCalledWith(+ OPENID_USER_ID_COOKIE,+ expect.any(String),+ expect.objectContaining({ expires, secure: true }),+ );++ const signedUserId = (res.cookie as jest.Mock).mock.calls.find(+ ([name]) => name === OPENID_USER_ID_COOKIE,+ )?.[1];+ expect(jwt.verify(signedUserId, 'marker-secret')).toMatchObject({ id: 'user-123' });+ });++ /** Preserves the marker's binding to the durable refresh-token session: a marker signed for one+ * session must not stand in for another once the refresh token has rotated. */+ it('binds the signed user marker to the refresh token it was issued with', () => {+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 604800000);++ setOpenIDMarkerCookies(res, {+ userId: 'user-123',+ expires,+ refreshExpiryMs: 604800000,+ refreshToken: 'the-refresh-token',+ });++ const signedUserId = (res.cookie as jest.Mock).mock.calls.find(+ ([name]) => name === OPENID_USER_ID_COOKIE,+ )?.[1];+ expect(jwt.verify(signedUserId, 'marker-secret')).toMatchObject({+ id: 'user-123',+ refreshTokenHash: crypto.createHash('sha256').update('the-refresh-token').digest('base64url'),+ });+ });++ it('omits the binding when no refresh token is supplied', () => {+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 604800000);++ setOpenIDMarkerCookies(res, { userId: 'user-123', expires, refreshExpiryMs: 604800000 });++ const signedUserId = (res.cookie as jest.Mock).mock.calls.find(+ ([name]) => name === OPENID_USER_ID_COOKIE,+ )?.[1];+ expect(jwt.verify(signedUserId, 'marker-secret')).not.toHaveProperty('refreshTokenHash');+ });++ it('updates token_provider even when the signed user marker is not applicable', () => {+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 604800000);++ setOpenIDMarkerCookies(res, {+ expires,+ refreshExpiryMs: 604800000,+ reuseTokens: false,+ });++ expect(res.cookie).toHaveBeenCalledTimes(1);+ expect(res.cookie).toHaveBeenCalledWith(+ TOKEN_PROVIDER_COOKIE,+ 'openid',+ expect.objectContaining({ expires }),+ );+ });++ it('uses integer seconds for fractional refresh expiry durations', () => {+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 604800999);++ setOpenIDMarkerCookies(res, {+ userId: 'user-123',+ expires,+ refreshExpiryMs: 604800999,+ });++ const signedUserId = (res.cookie as jest.Mock).mock.calls.find(+ ([name]) => name === OPENID_USER_ID_COOKIE,+ )?.[1];+ const payload = jwt.verify(signedUserId, 'marker-secret') as jwt.JwtPayload;+ if (typeof payload.exp !== 'number' || typeof payload.iat !== 'number') {+ throw new Error('Expected signed marker JWT to include numeric exp and iat');+ }+ expect(payload.exp - payload.iat).toBe(604800);+ });++ it.each([0, -1000, 999, Number.NaN, Number.POSITIVE_INFINITY])(+ 'throws when the refresh expiry duration is invalid: %p',+ (refreshExpiryMs) => {+ const res = { cookie: jest.fn() } as unknown as import('express').Response;+ const expires = new Date(Date.now() + 999);++ expect(() =>+ setOpenIDMarkerCookies(res, {+ userId: 'user-123',+ expires,+ refreshExpiryMs,+ }),+ ).toThrow('refreshExpiryMs must be a positive duration for OpenID marker cookies');+ },+ );+});diff --git a/packages/api/src/oauth/csrf.ts b/packages/api/src/oauth/csrf.tsindex 802655f2ee..0912815dc4 100644--- a/packages/api/src/oauth/csrf.ts+++ b/packages/api/src/oauth/csrf.ts@@ -1,4 +1,5 @@import crypto from 'crypto';+import jwt from 'jsonwebtoken';import type { Request, Response, NextFunction } from 'express';import { isEnabled } from '~/utils/common';@@ -47,6 +48,83 @@ export function shouldUseSecureCookie(): boolean {return isProduction && !isLocalhost;}+export const REFRESH_TOKEN_COOKIE = 'refreshToken';+export const TOKEN_PROVIDER_COOKIE = 'token_provider';+export const OPENID_USER_ID_COOKIE = 'openid_user_id';++/**+ * Writes the IdP refresh token to the `refreshToken` cookie. Single source of+ * truth for the cookie's options so the login/refresh path+ * (`setOpenIDAuthTokens`) and the inline OBO refresh path (`performIdpRefresh`)+ * stay byte-for-byte in sync. The cookie outlives the (shorter) express-session+ * cookie and is the fallback `refreshController` reads when the session copy is+ * gone, so a rotated refresh token must land here too — otherwise a later+ * session loss replays an invalidated token and signs the user out.+ */+export function setRefreshTokenCookie(res: Response, refreshToken: string, expires: Date): void {+ res.cookie(REFRESH_TOKEN_COOKIE, refreshToken, {+ expires,+ httpOnly: true,+ secure: shouldUseSecureCookie(),+ sameSite: 'strict',+ });+}++export interface OpenIDMarkerCookieOptions {+ userId?: string | null;+ expires: Date;+ refreshExpiryMs: number;+ reuseTokens?: boolean;+ /** Binds the marker to the refresh token it was issued alongside. */+ refreshToken?: string | null;+}++export function setOpenIDMarkerCookies(+ res: Response,+ {+ userId,+ expires,+ refreshExpiryMs,+ reuseTokens = isEnabled(process.env.OPENID_REUSE_TOKENS),+ refreshToken,+ }: OpenIDMarkerCookieOptions,+): void {+ const cookieOptions = {+ expires,+ httpOnly: true,+ secure: shouldUseSecureCookie(),+ sameSite: 'strict' as const,+ };++ res.cookie(TOKEN_PROVIDER_COOKIE, 'openid', cookieOptions);++ if (!userId || !reuseTokens) {+ return;+ }++ const secret = process.env.JWT_REFRESH_SECRET;+ if (!secret) {+ throw new Error('JWT_REFRESH_SECRET is required for OpenID marker cookies');+ }++ const refreshExpirySeconds = Math.floor(refreshExpiryMs / 1000);+ if (!Number.isFinite(refreshExpirySeconds) || refreshExpirySeconds <= 0) {+ throw new Error('refreshExpiryMs must be a positive duration for OpenID marker cookies');+ }++ /** Bind the marker to the durable refresh-token session it was issued with, so a+ * marker lifted from one session cannot stand in for another's. */+ const refreshTokenHash = refreshToken+ ? crypto.createHash('sha256').update(refreshToken).digest('base64url')+ : undefined;+ const signedUserId = jwt.sign(+ refreshTokenHash ? { id: userId, refreshTokenHash } : { id: userId },+ secret,+ { expiresIn: refreshExpirySeconds },+ );+ res.cookie(OPENID_USER_ID_COOKIE, signedUserId, cookieOptions);+}+/** Generates an HMAC-based token for OAuth CSRF protection */export function generateOAuthCsrfToken(flowId: string, secret?: string): string {const key = secret || process.env.JWT_SECRET;diff --git a/packages/api/src/oauth/expiry.spec.ts b/packages/api/src/oauth/expiry.spec.tsindex 3a489bfe8f..0e982da296 100644--- a/packages/api/src/oauth/expiry.spec.ts+++ b/packages/api/src/oauth/expiry.spec.ts@@ -1,8 +1,13 @@import {DEFAULT_OAUTH_TOKEN_TTL_SECONDS,+ getSkewedTokenCacheTtlMs,+ getSkewedTokenExpiresAtMs,getTokenCacheTtlMs,getTokenExpiresAt,+ getTokenExpiresAtMs,+ hasUsableTokenExpiry,normalizeExpiresIn,+ OPENID_EXPIRY_BUFFER_SECONDS,} from './expiry';describe('normalizeExpiresIn', () => {@@ -74,10 +79,29 @@ describe('normalizeExpiresIn', () => {});describe('getTokenCacheTtlMs', () => {- it('converts a declared lifetime to milliseconds', () => {- expect(getTokenCacheTtlMs(1800, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBe(1_800_000);+ it('converts a declared lifetime to milliseconds, less the in-transit buffer', () => {+ expect(getTokenCacheTtlMs(1800, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBe(+ (1800 - OPENID_EXPIRY_BUFFER_SECONDS) * 1000,+ );});+ /** The read side re-serves whatever is cached, so the entry must expire before the credential:+ * a token handed out in its final seconds expires in transit and 401s downstream. */+ it('drops a credential from the cache before its last usable moment', () => {+ expect(getTokenCacheTtlMs(3600, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBeLessThan(3_600_000);+ expect(getTokenCacheTtlMs(3600, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBe(3_570_000);+ });++ /** A lifetime shorter than the buffer has no safe window left, but the credential is still real:+ * it gets the minimum usable TTL rather than a negative one or the elapsed-credential floor. */+ it('floors a live lifetime shorter than the buffer instead of going negative', () => {+ expect(getTokenCacheTtlMs(10, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBe(1000);+ expect(getTokenCacheTtlMs(OPENID_EXPIRY_BUFFER_SECONDS, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBe(+ 1000,+ );+ });++ /** An unknown lifetime has no declared expiry to protect, so the fallback is used unshortened */it('falls back rather than returning NaN when the provider omits `expires_in`', () => {expect(getTokenCacheTtlMs(undefined, DEFAULT_OAUTH_TOKEN_TTL_SECONDS)).toBe(3_600_000);expect(getTokenCacheTtlMs(NaN, 60)).toBe(60_000);@@ -147,3 +171,76 @@ describe('getTokenExpiresAt', () => {}});});++describe('getTokenExpiresAtMs', () => {+ const now = 1_700_000_000_000;++ it('prefers an absolute expiry the caller already holds', () => {+ expect(getTokenExpiresAtMs({ expiresAt: now + 120_000, expiresIn: 3600, now })).toBe(+ now + 120_000,+ );+ });++ it('derives an expiry from the declared lifetime when no absolute one is given', () => {+ expect(getTokenExpiresAtMs({ expiresIn: 300, now })).toBe(now + 300_000);+ expect(getTokenExpiresAtMs({ expiresAt: NaN, expiresIn: '120', now })).toBe(now + 120_000);+ });++ it('falls back when the provider declares no usable lifetime', () => {+ expect(getTokenExpiresAtMs({ expiresIn: undefined, now })).toBe(+ now + DEFAULT_OAUTH_TOKEN_TTL_SECONDS * 1000,+ );+ expect(getTokenExpiresAtMs({ expiresIn: 'abc', fallbackSeconds: 60, now })).toBe(now + 60_000);+ });++ /** An explicitly elapsed lifetime stays elapsed rather than taking the fallback */+ it('keeps an elapsed lifetime in the past', () => {+ expect(getTokenExpiresAtMs({ expiresIn: 0, now })).toBe(now);+ expect(getTokenExpiresAtMs({ expiresIn: -60, now })).toBe(now - 60_000);+ });+});++describe('skew helpers', () => {+ const now = 1_700_000_000_000;+ const bufferMs = OPENID_EXPIRY_BUFFER_SECONDS * 1000;++ it('pulls an expiry back by the in-transit buffer', () => {+ const expiresAt = now + 120_000;++ expect(getSkewedTokenExpiresAtMs(expiresAt, now)).toBe(now + 120_000 - bufferMs);+ expect(getSkewedTokenCacheTtlMs(expiresAt, now)).toBe(120_000 - bufferMs);+ });++ it('floors a live lifetime shorter than the buffer to a usable minimum, never 0', () => {+ const expiresAt = now + 10_000;++ expect(getSkewedTokenExpiresAtMs(expiresAt, now)).toBe(now + 1000);+ expect(getSkewedTokenCacheTtlMs(expiresAt, now)).toBe(1000);+ });++ /** The floor exists to keep a short-but-real credential usable, not to revive a dead one: a+ * provider that declares an elapsed expiry must not have it stamped into the future. */+ it('leaves an already-elapsed expiry elapsed', () => {+ expect(getSkewedTokenExpiresAtMs(now - 60_000, now)).toBe(now - 60_000);+ expect(getSkewedTokenExpiresAtMs(now, now)).toBe(now);+ expect(getSkewedTokenCacheTtlMs(now - 60_000, now)).toBe(1);+ expect(getSkewedTokenCacheTtlMs(now, now)).toBe(1);+ });+});++describe('hasUsableTokenExpiry', () => {+ const now = 1_700_000_000_000;+ const bufferMs = OPENID_EXPIRY_BUFFER_SECONDS * 1000;++ it('requires the credential to outlive the trip downstream', () => {+ expect(hasUsableTokenExpiry(now + bufferMs + 1, now)).toBe(true);+ expect(hasUsableTokenExpiry(now + bufferMs, now)).toBe(false);+ expect(hasUsableTokenExpiry(now + bufferMs - 1, now)).toBe(false);+ });++ it('rejects a missing or unusable expiry rather than assuming it is fresh', () => {+ expect(hasUsableTokenExpiry(null, now)).toBe(false);+ expect(hasUsableTokenExpiry(undefined, now)).toBe(false);+ expect(hasUsableTokenExpiry(NaN, now)).toBe(false);+ });+});diff --git a/packages/api/src/oauth/expiry.ts b/packages/api/src/oauth/expiry.tsindex 9aaec7aa86..84981d01f7 100644--- a/packages/api/src/oauth/expiry.ts+++ b/packages/api/src/oauth/expiry.ts@@ -18,6 +18,15 @@*/export const DEFAULT_OAUTH_TOKEN_TTL_SECONDS = 3600;+/**+ * Margin a credential needs to survive the trip to whoever will use it. A token served inside this+ * window expires in transit and is rejected downstream, so it is treated as already gone — both+ * when validating the user's own federated token (`isOpenIDTokenValid`, `isIdTokenCurrent`) and+ * when caching a token obtained by exchange. Lives here, with the rest of the lifetime math, so a+ * consumer that stubs OpenID token validation cannot leave the arithmetic reading `undefined`.+ */+export const OPENID_EXPIRY_BUFFER_SECONDS = 30;+/*** Floor for a cache TTL derived from an already-elapsed lifetime. Keyv reads a TTL of exactly `0`* as "no expiry" (`data.ttl === 0` becomes `undefined`), so a credential the provider declared@@ -25,6 +34,14 @@ export const DEFAULT_OAUTH_TOKEN_TTL_SECONDS = 3600;*/const EXPIRED_CACHE_TTL_MS = 1;+/**+ * Floor for a credential that is still alive but whose remaining lifetime is shorter than the+ * in-transit buffer. Distinct from {@link EXPIRED_CACHE_TTL_MS}: a lifetime the provider declared+ * elapsed is dead and must not be reused, while a short one is real and gets a usable moment+ * rather than a value that expires before the caller can act on it.+ */+const MIN_LIVE_TOKEN_TTL_MS = 1000;+/*** Longest lifetime that can still produce a valid `Date`. The ECMAScript time value range ends at* ±8.64e15 ms, and every derived timestamp adds `Date.now()`, so the bound is halved to leave room@@ -68,13 +85,78 @@ export function normalizeExpiresIn(expiresIn: unknown): number | undefined {* Cache TTL in milliseconds for a token response. A provider that omits `expires_in` gets* `fallbackSeconds` rather than an entry that outlives the credential it holds; one that declares* an elapsed lifetime gets the shortest positive TTL rather than `0`, which Keyv reads as no expiry.+ *+ * The declared lifetime is shortened by {@link OPENID_EXPIRY_BUFFER_SECONDS} — the same margin+ * `isOpenIDTokenValid` applies to the user's own federated token. A credential served in the final+ * seconds of its life expires in transit and is rejected downstream, and because the read side+ * re-serves whatever the cache still holds, that entry must be gone before the credential is.+ * An unknown lifetime takes the fallback unshortened: there is no declared expiry to protect.*/export function getTokenCacheTtlMs(expiresIn: unknown, fallbackSeconds: number): number {const seconds = normalizeExpiresIn(expiresIn);if (seconds == null) {return fallbackSeconds * 1000;}- return Math.max(seconds * 1000, EXPIRED_CACHE_TTL_MS);+ if (seconds <= 0) {+ return EXPIRED_CACHE_TTL_MS;+ }+ return Math.max((seconds - OPENID_EXPIRY_BUFFER_SECONDS) * 1000, MIN_LIVE_TOKEN_TTL_MS);+}++/**+ * Absolute expiry in epoch milliseconds for a token response, preferring an expiry the caller+ * already holds. `fallbackSeconds` covers a response that declares no usable lifetime.+ */+export function getTokenExpiresAtMs({+ expiresAt,+ expiresIn,+ fallbackSeconds = DEFAULT_OAUTH_TOKEN_TTL_SECONDS,+ now,+}: {+ expiresAt?: number | null;+ expiresIn?: unknown;+ fallbackSeconds?: number;+ now: number;+}): number {+ if (expiresAt != null && Number.isFinite(expiresAt)) {+ return expiresAt;+ }+ return now + (normalizeExpiresIn(expiresIn) ?? fallbackSeconds) * 1000;+}++/**+ * The expiry a downstream consumer should honour: the real one pulled back by the in-transit+ * buffer, so a credential handed on with this stamp cannot be accepted into its final seconds.+ */+export function getSkewedTokenExpiresAtMs(expiresAt: number, now: number): number {+ /** An expiry already in the past is the provider saying the credential is dead. Flooring it to a+ * moment in the future would hand a consumer a token that cannot work, so it stays elapsed and+ * the caller rejects the exchange instead of failing downstream. */+ if (expiresAt <= now) {+ return expiresAt;+ }+ return Math.max(now + MIN_LIVE_TOKEN_TTL_MS, expiresAt - OPENID_EXPIRY_BUFFER_SECONDS * 1000);+}++/** Cache TTL for a token whose absolute expiry is already known, buffered as above. */+export function getSkewedTokenCacheTtlMs(expiresAt: number, now: number): number {+ if (expiresAt <= now) {+ return EXPIRED_CACHE_TTL_MS;+ }+ return Math.max(MIN_LIVE_TOKEN_TTL_MS, expiresAt - now - OPENID_EXPIRY_BUFFER_SECONDS * 1000);+}++/**+ * Whether a cached credential still has enough life to survive the trip downstream. A cache entry+ * that outlived its TTL check — a shared store with a coarser clock, an entry written before the+ * buffer existed — is rejected here rather than handed out to fail at the far end.+ */+export function hasUsableTokenExpiry(expiresAt?: number | null, now: number = Date.now()): boolean {+ return (+ expiresAt != null &&+ Number.isFinite(expiresAt) &&+ expiresAt > now + OPENID_EXPIRY_BUFFER_SECONDS * 1000+ );}/**diff --git a/packages/api/src/utils/env.spec.ts b/packages/api/src/utils/env.spec.tsindex f33f1645e4..25db696d31 100644--- a/packages/api/src/utils/env.spec.ts+++ b/packages/api/src/utils/env.spec.ts@@ -3,11 +3,11 @@ import { TokenExchangeMethodEnum } from 'librechat-data-provider';import type { MCPOptions } from 'librechat-data-provider';import type { IUser } from '@librechat/data-schemas';import {- resolveNestedObject,- encodeHeaderValue,- resolveHeaders,createSafeUser,+ resolveHeaders,+ resolveNestedObject,processMCPEnv,+ encodeHeaderValue,} from './env';function isStdioOptions(options: MCPOptions): options is Extract<MCPOptions, { type?: 'stdio' }> {@@ -472,6 +472,27 @@ describe('resolveHeaders', () => {expect(result['X-User-TermsAccepted']).toBe('true');});+ it('should not expose tenant or issuer fields through safe user placeholders', () => {+ const user = createTestUser({+ tenantId: 'tenant-secret',+ openidIssuer: 'https://issuer.example.com',+ });+ const safeUser = createSafeUser(user);+ const headers = {+ 'X-Tenant': '{{LIBRECHAT_USER_TENANTID}}',+ 'X-Issuer': '{{LIBRECHAT_USER_OPENIDISSUER}}',+ };++ expect(safeUser).not.toHaveProperty('tenantId');+ expect(safeUser).not.toHaveProperty('openidIssuer');+ expect(resolveHeaders({ headers, user: safeUser })['X-Tenant']).toBe(+ '{{LIBRECHAT_USER_TENANTID}}',+ );+ expect(resolveHeaders({ headers, user: safeUser })['X-Issuer']).toBe(+ '{{LIBRECHAT_USER_OPENIDISSUER}}',+ );+ });+it('should handle multiple placeholders in one value', () => {const user = { id: 'abc', email: '[email protected]' };const headers = {diff --git a/packages/api/src/utils/identity.spec.ts b/packages/api/src/utils/identity.spec.tsnew file mode 100644index 0000000000..761489351b--- /dev/null+++ b/packages/api/src/utils/identity.spec.ts@@ -0,0 +1,148 @@+import {+ createAuthIdentityContext,+ createOpenIDOboIdentityTuple,+ createOpenIDSessionIdentity,+ createOpenIDRefreshIdentityTuple,+ createRefreshTokenBridgeIdentity,+ isOpenIDSessionIdentityMatch,+ resolveAppUserId,+ serializeAuthIdentityTuple,+} from './identity';++describe('auth identity helpers', () => {+ it('resolves app user id from _id before id', () => {+ expect(resolveAppUserId({ _id: { toString: () => 'mongo-id' }, id: 'virtual-id' })).toBe(+ 'mongo-id',+ );+ });++ it('uses explicit tenant and normalized issuer in context', () => {+ expect(+ createAuthIdentityContext({+ user: {+ id: 'user-id',+ openidId: 'oidc-sub',+ tenantId: 'user-tenant',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ },+ tenantId: 'ambient-tenant',+ }),+ ).toEqual({+ appUserId: 'user-id',+ openidSubject: 'oidc-sub',+ tenantId: 'ambient-tenant',+ openidIssuer: 'https://issuer.example.com',+ });+ });++ it('creates session identity from explicit token metadata before request user fallback', () => {+ expect(+ createOpenIDSessionIdentity({+ user: {+ id: 'request-user',+ openidId: 'request-sub',+ tenantId: 'request-tenant',+ openidIssuer: 'https://request.example.com',+ },+ userId: 'session-user',+ openidSubject: 'session-sub',+ tenantId: 'session-tenant',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ }),+ ).toEqual({+ appUserId: 'session-user',+ openidSubject: 'session-sub',+ tenantId: 'session-tenant',+ openidIssuer: 'https://issuer.example.com',+ });+ });++ it('requires stamped OpenID session identity metadata to match exactly', () => {+ const expected = {+ appUserId: 'user-123',+ openidSubject: 'oidc-sub',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer.example.com',+ };++ expect(+ isOpenIDSessionIdentityMatch(+ {+ ...expected,+ openidIssuer: 'https://issuer.example.com/',+ },+ expected,+ ),+ ).toBe(true);+ expect(+ isOpenIDSessionIdentityMatch(+ {+ ...expected,+ openidSubject: 'different-sub',+ },+ expected,+ ),+ ).toBe(false);+ expect(+ isOpenIDSessionIdentityMatch(+ {+ ...expected,+ openidIssuer: undefined,+ },+ expected,+ ),+ ).toBe(false);+ });++ it('allows refresh tuple to fall back to app id when openidId is absent', () => {+ expect(+ createOpenIDRefreshIdentityTuple({+ user: { id: 'app-user' },+ requestUser: { openidId: 'request-sub' },+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-a.example.com/',+ }),+ ).toEqual({+ subject: 'app-user',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer-a.example.com',+ });+ });++ it('creates refresh-token bridge identity from app user id and normalized issuer', () => {+ expect(+ createRefreshTokenBridgeIdentity({+ userId: ' user-123 ',+ tenantId: ' tenant-a ',+ openidIssuer: 'https://issuer.example.com/.well-known/openid-configuration',+ }),+ ).toEqual({+ userId: 'user-123',+ tenantId: 'tenant-a',+ openidIssuer: 'https://issuer.example.com',+ });+ });++ it('requires an app user id for refresh-token bridge identity', () => {+ expect(+ createRefreshTokenBridgeIdentity({+ user: { openidId: 'oidc-sub' },+ tenantId: 'tenant-a',+ }),+ ).toBeNull();+ });++ it('requires an OpenID subject for OBO identity tuples', () => {+ expect(createOpenIDOboIdentityTuple({ user: { id: 'app-user' } })).toBeNull();+ });++ it('serializes tuple parts with a stable separator', () => {+ expect(+ serializeAuthIdentityTuple({+ tenantId: 'tenant-a',+ openidIssuer: 'issuer-a',+ subject: 'sub-a',+ }),+ ).toBe('tenant-a\x1fissuer-a\x1fsub-a');+ });+});diff --git a/packages/api/src/utils/identity.ts b/packages/api/src/utils/identity.tsnew file mode 100644index 0000000000..f40928b332--- /dev/null+++ b/packages/api/src/utils/identity.ts@@ -0,0 +1,290 @@+import { normalizeOpenIdIssuer } from '~/auth/openid';++/**+ * Auth-boundary identity helpers for token/cache scoping.+ * Do not use these as a blanket replacement for app ownership checks, and keep+ * tenant/issuer data out of placeholder-visible safe user fields.+ */+type StringableId = string | number | { toString(): string };++export type AuthIdentitySource = {+ id?: string | null;+ _id?: StringableId | null;+ openidId?: string | null;+ openidIssuer?: string | null;+ tenantId?: string | null;+};++export type AuthIdentityContext = {+ appUserId?: string;+ openidSubject?: string;+ tenantId?: string;+ openidIssuer?: string;+};++export type AuthIdentityTuple = {+ tenantId: string;+ openidIssuer: string;+ subject: string;+};++export type RefreshTokenBridgeIdentity = {+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+};++export type OpenIDSessionIdentitySource = {+ appUserId?: string | null;+ openidSubject?: string | null;+ tenantId?: string | null;+ openidIssuer?: string | null;+};++const NO_TENANT = 'no-tenant';+const NO_ISSUER = 'no-issuer';+const IDENTITY_PART_SEPARATOR = '\x1f';++function normalizeIdentityValue(value: string | null | undefined): string | undefined {+ const normalized = value?.trim();+ return normalized ? normalized : undefined;+}++function stringifyId(value: StringableId | null | undefined): string | undefined {+ if (value == null) {+ return undefined;+ }++ const id =+ typeof value === 'string' || typeof value === 'number' ? String(value) : value.toString();+ return normalizeIdentityValue(id);+}++export function resolveAppUserId(+ ...sources: Array<AuthIdentitySource | null | undefined>+): string | undefined {+ for (const source of sources) {+ const id = stringifyId(source?._id) ?? normalizeIdentityValue(source?.id);+ if (id) {+ return id;+ }+ }++ return undefined;+}++export function resolveOpenIDSubject(+ source: AuthIdentitySource | null | undefined,+): string | undefined {+ return normalizeIdentityValue(source?.openidId);+}++export function resolveRefreshSubject(+ ...sources: Array<AuthIdentitySource | null | undefined>+): string | undefined {+ for (const source of sources) {+ const subject = resolveOpenIDSubject(source) ?? resolveAppUserId(source);+ if (subject) {+ return subject;+ }+ }++ return undefined;+}++export function resolveTenantId({+ tenantId,+ user,+ requestUser,+}: {+ tenantId?: string | null;+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+}): string | undefined {+ return (+ normalizeIdentityValue(tenantId) ??+ normalizeIdentityValue(user?.tenantId) ??+ normalizeIdentityValue(requestUser?.tenantId)+ );+}++export function resolveAuthOpenIDIssuer({+ openidIssuer,+ user,+ requestUser,+}: {+ openidIssuer?: string | null;+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+}): string | undefined {+ return (+ normalizeOpenIdIssuer(openidIssuer ?? undefined) ??+ normalizeOpenIdIssuer(user?.openidIssuer ?? undefined) ??+ normalizeOpenIdIssuer(requestUser?.openidIssuer ?? undefined)+ );+}++export function createAuthIdentityContext({+ user,+ requestUser,+ tenantId,+ openidIssuer,+}: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ tenantId?: string | null;+ openidIssuer?: string | null;+}): AuthIdentityContext {+ return {+ appUserId: resolveAppUserId(user, requestUser),+ openidSubject: resolveOpenIDSubject(user) ?? resolveOpenIDSubject(requestUser),+ tenantId: resolveTenantId({ tenantId, user, requestUser }),+ openidIssuer: resolveAuthOpenIDIssuer({ openidIssuer, user, requestUser }),+ };+}++export function createOpenIDSessionIdentity({+ user,+ requestUser,+ userId,+ openidSubject,+ tenantId,+ openidIssuer,+}: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ userId?: string | null;+ openidSubject?: string | null;+ tenantId?: string | null;+ openidIssuer?: string | null;+}): AuthIdentityContext {+ return createAuthIdentityContext({+ user: {+ id: userId,+ openidId: openidSubject,+ tenantId,+ openidIssuer,+ },+ requestUser: user ?? requestUser,+ tenantId,+ openidIssuer,+ });+}++function normalizeOpenIDSessionIdentity(+ identity: OpenIDSessionIdentitySource | null | undefined,+): AuthIdentityContext | null {+ const appUserId = normalizeIdentityValue(identity?.appUserId);+ const openidSubject = normalizeIdentityValue(identity?.openidSubject);+ if (!appUserId || !openidSubject) {+ return null;+ }++ return {+ appUserId,+ openidSubject,+ tenantId: normalizeIdentityValue(identity?.tenantId),+ openidIssuer: normalizeOpenIdIssuer(identity?.openidIssuer ?? undefined),+ };+}++export function isOpenIDSessionIdentityMatch(+ sessionIdentity: OpenIDSessionIdentitySource | null | undefined,+ expectedIdentity: OpenIDSessionIdentitySource | null | undefined,+): boolean {+ const session = normalizeOpenIDSessionIdentity(sessionIdentity);+ const expected = normalizeOpenIDSessionIdentity(expectedIdentity);++ return (+ session != null &&+ expected != null &&+ session.appUserId === expected.appUserId &&+ session.openidSubject === expected.openidSubject &&+ session.tenantId === expected.tenantId &&+ session.openidIssuer === expected.openidIssuer+ );+}++export function createRefreshTokenBridgeIdentity({+ user,+ requestUser,+ userId,+ tenantId,+ openidIssuer,+}: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ userId?: string | null;+ tenantId?: string | null;+ openidIssuer?: string | null;+}): RefreshTokenBridgeIdentity | null {+ const appUserId = normalizeIdentityValue(userId) ?? resolveAppUserId(user, requestUser);+ if (!appUserId) {+ return null;+ }++ return {+ userId: appUserId,+ tenantId: resolveTenantId({ tenantId, user, requestUser }),+ openidIssuer: resolveAuthOpenIDIssuer({ openidIssuer, user, requestUser }),+ };+}++export function createOpenIDRefreshIdentityTuple({+ user,+ requestUser,+ tenantId,+ openidIssuer,+}: {+ user?: AuthIdentitySource | null;+ requestUser?: AuthIdentitySource | null;+ tenantId?: string | null;+ openidIssuer?: string | null;+}): AuthIdentityTuple | null {+ const subject = resolveRefreshSubject(user, requestUser);+ if (!subject) {+ return null;+ }++ return {+ subject,+ tenantId: resolveTenantId({ tenantId, user, requestUser }) ?? NO_TENANT,+ openidIssuer: resolveAuthOpenIDIssuer({ openidIssuer, user, requestUser }) ?? NO_ISSUER,+ };+}++export function createOpenIDOboIdentityTuple({+ user,+ identityContext,+ tenantId,+ openidIssuer,+}: {+ user?: AuthIdentitySource | null;+ identityContext?: AuthIdentityContext | null;+ tenantId?: string | null;+ openidIssuer?: string | null;+}): AuthIdentityTuple | null {+ const subject =+ normalizeIdentityValue(identityContext?.openidSubject) ?? resolveOpenIDSubject(user);+ if (!subject) {+ return null;+ }++ return {+ subject,+ tenantId:+ normalizeIdentityValue(tenantId) ??+ normalizeIdentityValue(identityContext?.tenantId) ??+ normalizeIdentityValue(user?.tenantId) ??+ NO_TENANT,+ openidIssuer:+ normalizeOpenIdIssuer(openidIssuer ?? undefined) ??+ normalizeOpenIdIssuer(identityContext?.openidIssuer) ??+ normalizeOpenIdIssuer(user?.openidIssuer ?? undefined) ??+ NO_ISSUER,+ };+}++export function serializeAuthIdentityTuple(tuple: AuthIdentityTuple): string {+ return [tuple.tenantId, tuple.openidIssuer, tuple.subject].join(IDENTITY_PART_SEPARATOR);+}diff --git a/packages/api/src/utils/index.ts b/packages/api/src/utils/index.tsindex 32cd8cc391..06e63a62eb 100644--- a/packages/api/src/utils/index.ts+++ b/packages/api/src/utils/index.ts@@ -12,6 +12,7 @@ export * from './import';export * from './generators';export * from './graph';export * from './headers';+export * from './identity';export * from './path';export * from './key';export * from './latex';diff --git a/packages/api/src/utils/oidc.ts b/packages/api/src/utils/oidc.tsindex f03b0a54f8..b2516cd754 100644--- a/packages/api/src/utils/oidc.ts+++ b/packages/api/src/utils/oidc.ts@@ -1,5 +1,6 @@import { logger } from '@librechat/data-schemas';import type { IUser, OIDCTokens } from '@librechat/data-schemas';+import { OPENID_EXPIRY_BUFFER_SECONDS } from '~/oauth/expiry';export interface OpenIDTokenInfo {accessToken?: string;@@ -43,9 +44,6 @@ export const GRAPH_TOKEN_PLACEHOLDER = '{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}';*/export const DEFAULT_GRAPH_SCOPES = 'https://graph.microsoft.com/.default';-/** Shared with AuthController's OpenID session reuse check: a token within the buffer would expire in transit and 401 downstream */-export const OPENID_EXPIRY_BUFFER_SECONDS = 30;-/** Claims consulted when deciding whether a verified JWT is an access token rather than an ID token. */export interface JwtTypeClaims {aud?: string | string[];diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.tsindex eaa6a58cd5..dbcd724fa8 100644--- a/packages/data-schemas/src/methods/index.ts+++ b/packages/data-schemas/src/methods/index.ts@@ -1,4 +1,12 @@import type { RoleMethods, RoleDeps } from './role';+import {+ createOpenIDRefreshFlightMethods,+ type OpenIDRefreshFlightMethods,+} from './openidRefreshFlight';+import {+ createRefreshTokenBridgeMethods,+ type RefreshTokenBridgeMethods,+} from './refreshTokenBridge';import { createSessionMethods, DEFAULT_REFRESH_TOKEN_EXPIRY, type SessionMethods } from './session';import { createUserMethods, DEFAULT_SESSION_EXPIRY, type UserMethods } from './user';import { createFileMethods, type FileMethods, type FileOwnerScope } from './file';@@ -183,6 +191,8 @@ export { AgentTriggerDeliveryConflictError };export type AllMethods = UserMethods &SessionMethods &TokenMethods &+ RefreshTokenBridgeMethods &+ OpenIDRefreshFlightMethods &RoleMethods &KeyMethods &FileMethods &@@ -331,6 +341,8 @@ export function createMethods(...createUserMethods(mongoose, { getCache: deps.getCache }),...createSessionMethods(mongoose),...createTokenMethods(mongoose),+ ...createRefreshTokenBridgeMethods(mongoose),+ ...createOpenIDRefreshFlightMethods(mongoose),...roleMethods,...createKeyMethods(mongoose),...createFileMethods(mongoose),@@ -382,6 +394,8 @@ export type {UserMethods,SessionMethods,TokenMethods,+ RefreshTokenBridgeMethods,+ OpenIDRefreshFlightMethods,RoleMethods,KeyMethods,FileMethods,diff --git a/packages/data-schemas/src/methods/openidRefreshFlight.spec.ts b/packages/data-schemas/src/methods/openidRefreshFlight.spec.tsnew file mode 100644index 0000000000..a4c71c0d17--- /dev/null+++ b/packages/data-schemas/src/methods/openidRefreshFlight.spec.ts@@ -0,0 +1,424 @@+import mongoose from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import type * as t from '~/types';+import { createOpenIDRefreshFlightMethods } from './openidRefreshFlight';+import openidRefreshFlightSchema from '~/schema/openidRefreshFlight';++jest.mock('~/config/winston', () => ({+ error: jest.fn(),+ info: jest.fn(),+ debug: jest.fn(),+}));++let mongoServer: MongoMemoryServer;+let methods: ReturnType<typeof createOpenIDRefreshFlightMethods>;++beforeAll(async () => {+ mongoServer = await MongoMemoryServer.create();+ await mongoose.connect(mongoServer.getUri());+ if (!mongoose.models.OpenIDRefreshFlight) {+ mongoose.model<t.IOpenIDRefreshFlight>('OpenIDRefreshFlight', openidRefreshFlightSchema);+ }+});++afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer?.stop();+});++beforeEach(async () => {+ await mongoose.connection.dropDatabase();+ methods = createOpenIDRefreshFlightMethods(mongoose);+});++describe('OpenIDRefreshFlight Methods', () => {+ it('creates coordination indexes before the first acquisition', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ const indexes = await mongoose.models.OpenIDRefreshFlight.listIndexes();+ expect(indexes).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ key: { key: 1 }, unique: true }),+ expect.objectContaining({ key: { expiresAt: 1 }, expireAfterSeconds: 0 }),+ ]),+ );+ });++ it('acquires a new pending flight and returns existing flight to joiners', async () => {+ const first = await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ const second = await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-2',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ expect(first.acquired).toBe(true);+ expect(first.flight?.ownerId).toBe('owner-1');+ expect(second.acquired).toBe(false);+ expect(second.flight?.ownerId).toBe('owner-1');+ expect(second.flight?.status).toBe('pending');+ });++ it('reclaims an expired pending lock', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() - 1000),+ expiresAt: new Date(Date.now() + 60000),+ });+ await mongoose.models.OpenIDRefreshFlight.updateOne(+ { key: 'flight-key' },+ { $set: { createdAt: new Date('2020-01-01T00:00:00.000Z') } },+ );++ const reclaimed = await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-2',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ expect(reclaimed.acquired).toBe(true);+ expect(reclaimed.flight?.ownerId).toBe('owner-2');+ expect(reclaimed.flight?.createdAt.getTime()).toBeGreaterThan(+ new Date('2020-01-01T00:00:00.000Z').getTime(),+ );+ });++ it('reclaims a failed flight immediately so transient failures can retry', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ await methods.failOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ errorMessage: 'upstream timeout',+ expiresAt: new Date(Date.now() + 60000),+ });++ const reclaimed = await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-2',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ expect(reclaimed.acquired).toBe(true);+ expect(reclaimed.flight?.ownerId).toBe('owner-2');+ expect(reclaimed.flight?.status).toBe('pending');+ expect(reclaimed.flight?.errorMessage).toBeUndefined();+ });++ it('renews a lease only for the owning pending worker', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ const nextLockExpiry = new Date(Date.now() + 45000);+ const nextFlightExpiry = new Date(Date.now() + 90000);+ await expect(+ methods.renewOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-2',+ lockExpiresAt: nextLockExpiry,+ expiresAt: nextFlightExpiry,+ }),+ ).resolves.toBeNull();++ const renewed = await methods.renewOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: nextLockExpiry,+ expiresAt: nextFlightExpiry,+ });++ expect(renewed?.ownerId).toBe('owner-1');+ expect(renewed?.status).toBe('pending');+ expect(renewed?.lockExpiresAt.getTime()).toBe(nextLockExpiry.getTime());+ expect(renewed?.expiresAt.getTime()).toBe(nextFlightExpiry.getTime());+ });++ it('completes a flight only for the owning pending worker', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });++ await expect(+ methods.completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-2',+ encryptedResult: 'encrypted-wrong',+ expiresAt: new Date(Date.now() + 60000),+ }),+ ).resolves.toBeNull();++ const completed = await methods.completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ encryptedResult: 'encrypted-result',+ expiresAt: new Date(Date.now() + 60000),+ });++ expect(completed?.status).toBe('completed');+ expect(completed?.encryptedResult).toBe('encrypted-result');+ });++ it('finds completed unexpired flights and ignores expired ones', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });+ await methods.completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ encryptedResult: 'encrypted-result',+ expiresAt: new Date(Date.now() + 60000),+ });++ await expect(methods.findOpenIDRefreshFlight({ key: 'flight-key' })).resolves.toMatchObject({+ status: 'completed',+ encryptedResult: 'encrypted-result',+ });++ const OpenIDRefreshFlight = mongoose.models.OpenIDRefreshFlight;+ await OpenIDRefreshFlight.updateOne(+ { key: 'flight-key' },+ { $set: { expiresAt: new Date(Date.now() - 1000) } },+ );++ await expect(methods.findOpenIDRefreshFlight({ key: 'flight-key' })).resolves.toBeNull();+ });++ it('persists a logout revocation fence that an active owner cannot publish through', async () => {+ await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });+ const revocationExpiry = new Date(Date.now() + 3600000);++ const revoked = await methods.revokeOpenIDRefreshFlight({+ key: 'flight-key',+ expiresAt: revocationExpiry,+ });++ expect(revoked?.status).toBe('revoked');+ await expect(+ methods.completeOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-1',+ encryptedResult: 'late-result',+ expiresAt: revocationExpiry,+ }),+ ).resolves.toBeNull();+ const reacquire = await methods.acquireOpenIDRefreshFlight({+ key: 'flight-key',+ ownerId: 'owner-2',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt: new Date(Date.now() + 60000),+ });+ expect(reacquire.acquired).toBe(false);+ expect(reacquire.flight?.status).toBe('revoked');+ });++ it('retains a completed result when logout atomically revokes its delivery', async () => {+ const expiresAt = new Date(Date.now() + 60000);+ await methods.acquireOpenIDRefreshFlight({+ key: 'completed-flight',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt,+ });+ await methods.completeOpenIDRefreshFlight({+ key: 'completed-flight',+ ownerId: 'owner-1',+ encryptedResult: 'encrypted-successor',+ expiresAt,+ });++ const revoked = await methods.revokeOpenIDRefreshFlight({+ key: 'completed-flight',+ expiresAt: new Date(Date.now() + 3600000),+ });++ expect(revoked?.status).toBe('revoked');+ expect(revoked?.encryptedResult).toBe('encrypted-successor');+ });++ it('serializes response delivery without changing the completed publication state', async () => {+ const expiresAt = new Date(Date.now() + 60000);+ await methods.acquireOpenIDRefreshFlight({+ key: 'delivery-flight',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt,+ });+ await methods.completeOpenIDRefreshFlight({+ key: 'delivery-flight',+ ownerId: 'owner-1',+ encryptedResult: 'encrypted-result',+ expiresAt,+ });++ const first = await methods.claimOpenIDRefreshFlightDelivery({+ key: 'delivery-flight',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ deliveryExpiresAt: new Date(Date.now() + 30000),+ });+ expect(first).toMatchObject({ status: 'completed', deliveryId: 'delivery-1' });++ await expect(+ methods.claimOpenIDRefreshFlightDelivery({+ key: 'delivery-flight',+ ownerId: 'owner-1',+ deliveryId: 'delivery-2',+ deliveryExpiresAt: new Date(Date.now() + 30000),+ }),+ ).resolves.toBeNull();++ const released = await methods.releaseOpenIDRefreshFlightDelivery({+ key: 'delivery-flight',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ });+ expect(released).toMatchObject({ status: 'completed', encryptedResult: 'encrypted-result' });+ expect(released?.deliveryId).toBeUndefined();+ });++ it('recreates an expired generation only for delivery and removes the synthetic row on release', async () => {+ const createdAt = new Date('2026-08-29T12:00:00.000Z');+ const claimed = await methods.claimOpenIDRefreshFlightDelivery({+ key: 'expired-generation',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ deliveryExpiresAt: new Date(Date.now() + 30000),+ createdAt,+ });++ expect(claimed).toMatchObject({+ key: 'expired-generation',+ ownerId: 'owner-1',+ status: 'completed',+ deliveryId: 'delivery-1',+ });+ expect(claimed?.createdAt.getTime()).toBe(createdAt.getTime());++ await methods.releaseOpenIDRefreshFlightDelivery({+ key: 'expired-generation',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ });+ await expect(+ mongoose.models.OpenIDRefreshFlight.findOne({ key: 'expired-generation' }).lean(),+ ).resolves.toBeNull();+ });++ it('makes logout wait for an active delivery and revokes it when the response releases', async () => {+ const expiresAt = new Date(Date.now() + 60000);+ await methods.acquireOpenIDRefreshFlight({+ key: 'logout-delivery-flight',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt,+ });+ await methods.completeOpenIDRefreshFlight({+ key: 'logout-delivery-flight',+ ownerId: 'owner-1',+ encryptedResult: 'encrypted-result',+ expiresAt,+ });+ await methods.claimOpenIDRefreshFlightDelivery({+ key: 'logout-delivery-flight',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ deliveryExpiresAt: new Date(Date.now() + 30000),+ });++ let logoutSettled = false;+ const logout = methods+ .revokeOpenIDRefreshFlight({+ key: 'logout-delivery-flight',+ expiresAt: new Date(Date.now() + 3600000),+ })+ .finally(() => {+ logoutSettled = true;+ });++ let revocationRequested = false;+ for (let attempt = 0; attempt < 20 && !revocationRequested; attempt++) {+ const flight = await mongoose.models.OpenIDRefreshFlight.findOne({+ key: 'logout-delivery-flight',+ }).lean<t.IOpenIDRefreshFlight>();+ revocationRequested = Boolean(flight?.revocationRequestedAt);+ if (!revocationRequested) {+ await new Promise((resolve) => setTimeout(resolve, 10));+ }+ }+ expect(revocationRequested).toBe(true);+ expect(logoutSettled).toBe(false);++ const released = await methods.releaseOpenIDRefreshFlightDelivery({+ key: 'logout-delivery-flight',+ ownerId: 'owner-1',+ deliveryId: 'delivery-1',+ });+ expect(released?.status).toBe('revoked');+ await expect(logout).resolves.toMatchObject({+ status: 'revoked',+ encryptedResult: 'encrypted-result',+ });+ });++ it('treats a malformed delivery without an expiry as abandoned during logout', async () => {+ const expiresAt = new Date(Date.now() + 60000);+ await methods.acquireOpenIDRefreshFlight({+ key: 'abandoned-delivery-flight',+ ownerId: 'owner-1',+ lockExpiresAt: new Date(Date.now() + 30000),+ expiresAt,+ });+ await methods.completeOpenIDRefreshFlight({+ key: 'abandoned-delivery-flight',+ ownerId: 'owner-1',+ encryptedResult: 'encrypted-result',+ expiresAt,+ });+ await mongoose.models.OpenIDRefreshFlight.updateOne(+ { key: 'abandoned-delivery-flight' },+ { $set: { deliveryId: 'orphaned-delivery' }, $unset: { deliveryExpiresAt: '' } },+ );++ await expect(+ methods.revokeOpenIDRefreshFlight({+ key: 'abandoned-delivery-flight',+ expiresAt: new Date(Date.now() + 3600000),+ }),+ ).resolves.toMatchObject({ status: 'revoked' });+ });+});diff --git a/packages/data-schemas/src/methods/openidRefreshFlight.ts b/packages/data-schemas/src/methods/openidRefreshFlight.tsnew file mode 100644index 0000000000..140c658ad8--- /dev/null+++ b/packages/data-schemas/src/methods/openidRefreshFlight.ts@@ -0,0 +1,464 @@+import { setTimeout as delay } from 'node:timers/promises';+import type { Model } from 'mongoose';+import type {+ IOpenIDRefreshFlight,+ OpenIDRefreshFlightCreateData,+ OpenIDRefreshFlightCompleteData,+ OpenIDRefreshFlightRenewData,+ OpenIDRefreshFlightFailData,+ OpenIDRefreshFlightRevokeData,+ OpenIDRefreshFlightQuery,+ OpenIDRefreshFlightAcquireResult,+ OpenIDRefreshFlightClaimDeliveryData,+ OpenIDRefreshFlightReleaseDeliveryData,+} from '~/types';+import { createIndexesWithRetry } from '~/utils/retry';+import logger from '~/config/winston';++const DELIVERY_RELEASE_POLL_MS = 100;++function hasErrorCode(error: unknown): error is { code: number } {+ return (+ typeof error === 'object' &&+ error != null &&+ 'code' in error &&+ typeof (error as { code: unknown }).code === 'number'+ );+}++function isDuplicateKeyError(error: unknown): boolean {+ return hasErrorCode(error) && error.code === 11000;+}++export function createOpenIDRefreshFlightMethods(mongoose: typeof import('mongoose')): {+ acquireOpenIDRefreshFlight: (+ data: OpenIDRefreshFlightCreateData,+ ) => Promise<OpenIDRefreshFlightAcquireResult>;+ completeOpenIDRefreshFlight: (+ data: OpenIDRefreshFlightCompleteData,+ ) => Promise<IOpenIDRefreshFlight | null>;+ renewOpenIDRefreshFlight: (+ data: OpenIDRefreshFlightRenewData,+ ) => Promise<IOpenIDRefreshFlight | null>;+ failOpenIDRefreshFlight: (+ data: OpenIDRefreshFlightFailData,+ ) => Promise<IOpenIDRefreshFlight | null>;+ revokeOpenIDRefreshFlight: (+ data: OpenIDRefreshFlightRevokeData,+ ) => Promise<IOpenIDRefreshFlight | null>;+ claimOpenIDRefreshFlightDelivery: (+ data: OpenIDRefreshFlightClaimDeliveryData,+ ) => Promise<IOpenIDRefreshFlight | null>;+ releaseOpenIDRefreshFlightDelivery: (+ data: OpenIDRefreshFlightReleaseDeliveryData,+ ) => Promise<IOpenIDRefreshFlight | null>;+ findOpenIDRefreshFlight: (+ query: OpenIDRefreshFlightQuery,+ ) => Promise<IOpenIDRefreshFlight | null>;+} {+ let indexesPromise: Promise<void> | null = null;++ function ensureIndexes(): Promise<void> {+ if (!indexesPromise) {+ const OpenIDRefreshFlight = mongoose.models+ .OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ indexesPromise = createIndexesWithRetry(OpenIDRefreshFlight).catch((error) => {+ indexesPromise = null;+ throw error;+ });+ }+ return indexesPromise;+ }++ async function acquireOpenIDRefreshFlight(+ data: OpenIDRefreshFlightCreateData,+ ): Promise<OpenIDRefreshFlightAcquireResult> {+ const OpenIDRefreshFlight = mongoose.models.OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ const now = new Date();++ await ensureIndexes();++ try {+ const flight = await OpenIDRefreshFlight.create({+ ...data,+ status: 'pending',+ createdAt: now,+ updatedAt: now,+ });+ return { acquired: true, flight };+ } catch (error) {+ if (!isDuplicateKeyError(error)) {+ logger.debug('[acquireOpenIDRefreshFlight] Error creating flight:', error);+ throw error;+ }+ }++ try {+ const reclaimed = await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ $or: [+ { status: 'failed' },+ { expiresAt: { $lte: now } },+ { status: 'pending', lockExpiresAt: { $lte: now } },+ ],+ },+ {+ $set: {+ ownerId: data.ownerId,+ status: 'pending',+ createdAt: now,+ lockExpiresAt: data.lockExpiresAt,+ expiresAt: data.expiresAt,+ updatedAt: now,+ },+ $unset: {+ encryptedResult: '',+ errorMessage: '',+ deliveryId: '',+ deliveryExpiresAt: '',+ revocationRequestedAt: '',+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();++ if (reclaimed) {+ return { acquired: true, flight: reclaimed };+ }++ const existing = await OpenIDRefreshFlight.findOne({+ key: data.key,+ expiresAt: { $gt: now },+ }).lean<IOpenIDRefreshFlight>();++ return { acquired: false, flight: existing };+ } catch (error) {+ logger.debug('[acquireOpenIDRefreshFlight] Error acquiring flight:', error);+ throw error;+ }+ }++ async function completeOpenIDRefreshFlight(+ data: OpenIDRefreshFlightCompleteData,+ ): Promise<IOpenIDRefreshFlight | null> {+ try {+ const OpenIDRefreshFlight = mongoose.models+ .OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ return await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ ownerId: data.ownerId,+ status: 'pending',+ },+ {+ $set: {+ status: 'completed',+ encryptedResult: data.encryptedResult,+ expiresAt: data.expiresAt,+ updatedAt: new Date(),+ },+ $unset: {+ errorMessage: '',+ deliveryId: '',+ deliveryExpiresAt: '',+ revocationRequestedAt: '',+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ } catch (error) {+ logger.debug('[completeOpenIDRefreshFlight] Error completing flight:', error);+ throw error;+ }+ }++ async function renewOpenIDRefreshFlight(+ data: OpenIDRefreshFlightRenewData,+ ): Promise<IOpenIDRefreshFlight | null> {+ try {+ const OpenIDRefreshFlight = mongoose.models+ .OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ return await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ ownerId: data.ownerId,+ status: 'pending',+ },+ {+ $set: {+ lockExpiresAt: data.lockExpiresAt,+ expiresAt: data.expiresAt,+ updatedAt: new Date(),+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ } catch (error) {+ logger.debug('[renewOpenIDRefreshFlight] Error renewing flight:', error);+ throw error;+ }+ }++ async function failOpenIDRefreshFlight(+ data: OpenIDRefreshFlightFailData,+ ): Promise<IOpenIDRefreshFlight | null> {+ try {+ const OpenIDRefreshFlight = mongoose.models+ .OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ return await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ ownerId: data.ownerId,+ status: 'pending',+ },+ {+ $set: {+ status: 'failed',+ errorMessage: data.errorMessage,+ expiresAt: data.expiresAt,+ updatedAt: new Date(),+ },+ $unset: {+ encryptedResult: '',+ deliveryId: '',+ deliveryExpiresAt: '',+ revocationRequestedAt: '',+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ } catch (error) {+ logger.debug('[failOpenIDRefreshFlight] Error failing flight:', error);+ throw error;+ }+ }++ async function findOpenIDRefreshFlight(+ query: OpenIDRefreshFlightQuery,+ ): Promise<IOpenIDRefreshFlight | null> {+ try {+ const OpenIDRefreshFlight = mongoose.models+ .OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ return await OpenIDRefreshFlight.findOne({+ key: query.key,+ expiresAt: { $gt: new Date() },+ }).lean<IOpenIDRefreshFlight>();+ } catch (error) {+ logger.debug('[findOpenIDRefreshFlight] Error finding flight:', error);+ throw error;+ }+ }++ async function claimOpenIDRefreshFlightDelivery(+ data: OpenIDRefreshFlightClaimDeliveryData,+ ): Promise<IOpenIDRefreshFlight | null> {+ try {+ const OpenIDRefreshFlight = mongoose.models+ .OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ try {+ return await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ ownerId: data.ownerId,+ status: 'completed',+ revocationRequestedAt: { $exists: false },+ $or: [+ { deliveryId: { $exists: false } },+ { deliveryExpiresAt: { $exists: false } },+ { deliveryExpiresAt: { $lte: new Date() } },+ ],+ },+ {+ $set: {+ deliveryId: data.deliveryId,+ deliveryExpiresAt: data.deliveryExpiresAt,+ updatedAt: new Date(),+ },+ $max: { expiresAt: data.deliveryExpiresAt },+ ...(data.createdAt+ ? {+ $setOnInsert: {+ createdAt: data.createdAt,+ lockExpiresAt: data.deliveryExpiresAt,+ },+ }+ : {}),+ },+ { new: true, upsert: Boolean(data.createdAt) },+ ).lean<IOpenIDRefreshFlight>();+ } catch (error) {+ if (isDuplicateKeyError(error)) return null;+ throw error;+ }+ } catch (error) {+ logger.debug('[claimOpenIDRefreshFlightDelivery] Error claiming delivery:', error);+ throw error;+ }+ }++ async function releaseOpenIDRefreshFlightDelivery(+ data: OpenIDRefreshFlightReleaseDeliveryData,+ ): Promise<IOpenIDRefreshFlight | null> {+ const OpenIDRefreshFlight = mongoose.models.OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ const delivery = {+ key: data.key,+ ownerId: data.ownerId,+ deliveryId: data.deliveryId,+ status: 'completed',+ } as const;+ try {+ const revoked = await OpenIDRefreshFlight.findOneAndUpdate(+ { ...delivery, revocationRequestedAt: { $exists: true } },+ {+ $set: {+ ownerId: 'revoked',+ status: 'revoked',+ errorMessage: 'OpenID refresh was revoked by logout',+ updatedAt: new Date(),+ },+ $unset: {+ deliveryId: '',+ deliveryExpiresAt: '',+ revocationRequestedAt: '',+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ if (revoked) return revoked;++ const synthetic = await OpenIDRefreshFlight.findOneAndDelete({+ ...delivery,+ encryptedResult: { $exists: false },+ revocationRequestedAt: { $exists: false },+ }).lean<IOpenIDRefreshFlight>();+ if (synthetic) return null;++ const completed = await OpenIDRefreshFlight.findOneAndUpdate(+ {+ ...delivery,+ encryptedResult: { $exists: true },+ revocationRequestedAt: { $exists: false },+ },+ {+ $set: { updatedAt: new Date() },+ $unset: { deliveryId: '', deliveryExpiresAt: '' },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ if (completed) return completed;++ return await OpenIDRefreshFlight.findOneAndUpdate(+ { ...delivery, revocationRequestedAt: { $exists: true } },+ {+ $set: {+ ownerId: 'revoked',+ status: 'revoked',+ errorMessage: 'OpenID refresh was revoked by logout',+ updatedAt: new Date(),+ },+ $unset: {+ deliveryId: '',+ deliveryExpiresAt: '',+ revocationRequestedAt: '',+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ } catch (error) {+ logger.debug('[releaseOpenIDRefreshFlightDelivery] Error releasing delivery:', error);+ throw error;+ }+ }++ async function revokeOpenIDRefreshFlight(+ data: OpenIDRefreshFlightRevokeData,+ ): Promise<IOpenIDRefreshFlight | null> {+ const OpenIDRefreshFlight = mongoose.models.OpenIDRefreshFlight as Model<IOpenIDRefreshFlight>;+ const now = new Date();+ await ensureIndexes();+ try {+ for (;;) {+ const revoked = await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ $or: [+ { deliveryId: { $exists: false } },+ { deliveryExpiresAt: { $exists: false } },+ { deliveryExpiresAt: { $lte: new Date() } },+ ],+ },+ {+ $set: {+ ownerId: 'revoked',+ status: 'revoked',+ errorMessage: 'OpenID refresh was revoked by logout',+ lockExpiresAt: data.expiresAt,+ expiresAt: data.expiresAt,+ updatedAt: new Date(),+ },+ $unset: {+ deliveryId: '',+ deliveryExpiresAt: '',+ revocationRequestedAt: '',+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ if (revoked) return revoked;++ const delivering = await OpenIDRefreshFlight.findOneAndUpdate(+ {+ key: data.key,+ status: 'completed',+ deliveryId: { $exists: true },+ deliveryExpiresAt: { $gt: new Date() },+ },+ {+ $set: {+ revocationRequestedAt: new Date(),+ expiresAt: data.expiresAt,+ updatedAt: new Date(),+ },+ },+ { new: true },+ ).lean<IOpenIDRefreshFlight>();+ if (delivering) {+ await delay(DELIVERY_RELEASE_POLL_MS);+ continue;+ }++ try {+ return await OpenIDRefreshFlight.create({+ key: data.key,+ ownerId: 'revoked',+ status: 'revoked',+ errorMessage: 'OpenID refresh was revoked by logout',+ lockExpiresAt: data.expiresAt,+ expiresAt: data.expiresAt,+ createdAt: now,+ updatedAt: now,+ });+ } catch (error) {+ if (!isDuplicateKeyError(error)) throw error;+ }+ }+ } catch (error) {+ logger.debug('[revokeOpenIDRefreshFlight] Error revoking flight:', error);+ throw error;+ }+ }++ return {+ acquireOpenIDRefreshFlight,+ claimOpenIDRefreshFlightDelivery,+ renewOpenIDRefreshFlight,+ completeOpenIDRefreshFlight,+ failOpenIDRefreshFlight,+ revokeOpenIDRefreshFlight,+ releaseOpenIDRefreshFlightDelivery,+ findOpenIDRefreshFlight,+ };+}++export type OpenIDRefreshFlightMethods = ReturnType<typeof createOpenIDRefreshFlightMethods>;diff --git a/packages/data-schemas/src/methods/refreshTokenBridge.spec.ts b/packages/data-schemas/src/methods/refreshTokenBridge.spec.tsnew file mode 100644index 0000000000..e3a0da7c36--- /dev/null+++ b/packages/data-schemas/src/methods/refreshTokenBridge.spec.ts@@ -0,0 +1,215 @@+import mongoose from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import type * as t from '~/types';+import { createRefreshTokenBridgeMethods } from './refreshTokenBridge';+import refreshTokenBridgeSchema from '~/schema/refreshTokenBridge';++jest.mock('~/config/winston', () => ({+ error: jest.fn(),+ info: jest.fn(),+ debug: jest.fn(),+}));++let mongoServer: MongoMemoryServer;+let methods: ReturnType<typeof createRefreshTokenBridgeMethods>;++beforeAll(async () => {+ mongoServer = await MongoMemoryServer.create();+ await mongoose.connect(mongoServer.getUri());+ if (!mongoose.models.RefreshTokenBridge) {+ mongoose.model<t.IRefreshTokenBridge>('RefreshTokenBridge', refreshTokenBridgeSchema);+ }+});++afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer?.stop();+});++beforeEach(async () => {+ await mongoose.connection.dropDatabase();+ methods = createRefreshTokenBridgeMethods(mongoose);+});++describe('RefreshTokenBridge Methods', () => {+ it('creates uniqueness and TTL indexes before the first write', async () => {+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-new',+ userId: 'user-1',+ tenantId: 'tenant-1',+ expiresAt: new Date(Date.now() + 60000),+ });++ const indexes = await mongoose.models.RefreshTokenBridge.listIndexes();+ expect(indexes).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ key: { oldRefreshTokenHash: 1, userId: 1, tenantId: 1 },+ unique: true,+ }),+ expect.objectContaining({ key: { expiresAt: 1 }, expireAfterSeconds: 0 }),+ ]),+ );+ });++ it('keeps the lookup indexes aligned with the data-layer query shape', () => {+ const indexKeys = mongoose.models.RefreshTokenBridge.schema.indexes().map(([key]) => key);++ expect(indexKeys).toContainEqual({ oldRefreshTokenHash: 1, userId: 1, tenantId: 1 });+ expect(indexKeys).not.toContainEqual({+ oldRefreshTokenHash: 1,+ userId: 1,+ tenantId: 1,+ openidIssuer: 1,+ });+ });++ it('upserts and finds a bridge by old token hash, user, and tenant', async () => {+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-new',+ userId: 'user-1',+ tenantId: 'tenant-1',+ openidIssuer: 'https://issuer.example.com',+ expiresAt: new Date(Date.now() + 60000),+ });++ const found = await methods.findRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ userId: 'user-1',+ tenantId: 'tenant-1',+ });++ expect(found?.encryptedNewRefreshToken).toBe('encrypted-new');+ expect(found?.openidIssuer).toBe('https://issuer.example.com');+ });++ it('replaces the encrypted token and expiry on repeated stores', async () => {+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-old',+ userId: 'user-1',+ expiresAt: new Date(Date.now() + 60000),+ });++ const nextExpiresAt = new Date(Date.now() + 120000);+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-new',+ userId: 'user-1',+ expiresAt: nextExpiresAt,+ });++ const found = await methods.findRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ userId: 'user-1',+ });++ expect(found?.encryptedNewRefreshToken).toBe('encrypted-new');+ expect(found?.expiresAt.getTime()).toBe(nextExpiresAt.getTime());+ expect(await mongoose.models.RefreshTokenBridge.countDocuments()).toBe(1);+ });++ it('does not return expired bridges before Mongo TTL cleanup runs', async () => {+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-new',+ userId: 'user-1',+ expiresAt: new Date(Date.now() - 1000),+ });++ await expect(+ methods.findRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ userId: 'user-1',+ }),+ ).resolves.toBeNull();+ });++ it('deletes only the requested user and tenant bridge hashes', async () => {+ for (const [oldRefreshTokenHash, userId, tenantId] of [+ ['hash-a', 'user-1', 'tenant-1'],+ ['hash-b', 'user-1', 'tenant-1'],+ ['hash-a', 'user-2', 'tenant-1'],+ ['hash-a', 'user-1', 'tenant-2'],+ ]) {+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash,+ encryptedNewRefreshToken: `encrypted-${oldRefreshTokenHash}`,+ userId,+ tenantId,+ expiresAt: new Date(Date.now() + 60000),+ });+ }++ const result = await methods.deleteRefreshTokenBridges({+ oldRefreshTokenHashes: ['hash-a', 'hash-b'],+ userId: 'user-1',+ tenantId: 'tenant-1',+ });++ expect(result.deletedCount).toBe(2);+ expect(await mongoose.models.RefreshTokenBridge.countDocuments()).toBe(2);+ });++ it('does not let a stale owner delete a replacement bridge version', async () => {+ const expiresAt = new Date(Date.now() + 60000);+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-old',+ userId: 'user-1',+ tenantId: 'tenant-1',+ version: 'owner-version',+ expiresAt,+ });+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ encryptedNewRefreshToken: 'encrypted-winner',+ userId: 'user-1',+ tenantId: 'tenant-1',+ version: 'winner-version',+ expiresAt,+ });++ const staleDelete = await methods.deleteRefreshTokenBridges({+ oldRefreshTokenHashes: ['old-hash'],+ userId: 'user-1',+ tenantId: 'tenant-1',+ version: 'owner-version',+ });+ const winner = await methods.findRefreshTokenBridge({+ oldRefreshTokenHash: 'old-hash',+ userId: 'user-1',+ tenantId: 'tenant-1',+ });++ expect(staleDelete.deletedCount).toBe(0);+ expect(winner?.encryptedNewRefreshToken).toBe('encrypted-winner');+ expect(winner?.version).toBe('winner-version');+ });++ it('deletes all predecessor bridges for one user and tenant', async () => {+ for (const [oldRefreshTokenHash, userId, tenantId] of [+ ['hash-a', 'user-1', 'tenant-1'],+ ['hash-b', 'user-1', 'tenant-1'],+ ['hash-c', 'user-2', 'tenant-1'],+ ]) {+ await methods.upsertRefreshTokenBridge({+ oldRefreshTokenHash,+ encryptedNewRefreshToken: `encrypted-${oldRefreshTokenHash}`,+ userId,+ tenantId,+ expiresAt: new Date(Date.now() + 60000),+ });+ }++ const result = await methods.deleteRefreshTokenBridges({+ userId: 'user-1',+ tenantId: 'tenant-1',+ });++ expect(result.deletedCount).toBe(2);+ expect(await mongoose.models.RefreshTokenBridge.countDocuments()).toBe(1);+ });+});diff --git a/packages/data-schemas/src/methods/refreshTokenBridge.ts b/packages/data-schemas/src/methods/refreshTokenBridge.tsnew file mode 100644index 0000000000..b42761a833--- /dev/null+++ b/packages/data-schemas/src/methods/refreshTokenBridge.ts@@ -0,0 +1,126 @@+import type { DeleteResult, FilterQuery, Model, UpdateQuery } from 'mongoose';+import type {+ IRefreshTokenBridge,+ RefreshTokenBridgeCreateData,+ RefreshTokenBridgeDeleteData,+ RefreshTokenBridgeQuery,+} from '~/types';+import { createIndexesWithRetry } from '~/utils/retry';+import logger from '~/config/winston';++function bridgeFilter({+ oldRefreshTokenHash,+ userId,+ tenantId,+}: RefreshTokenBridgeQuery): FilterQuery<IRefreshTokenBridge> {+ return {+ oldRefreshTokenHash,+ userId,+ tenantId: tenantId ?? { $exists: false },+ };+}++export function createRefreshTokenBridgeMethods(mongoose: typeof import('mongoose')): {+ upsertRefreshTokenBridge: (+ bridgeData: RefreshTokenBridgeCreateData,+ ) => Promise<IRefreshTokenBridge | null>;+ findRefreshTokenBridge: (query: RefreshTokenBridgeQuery) => Promise<IRefreshTokenBridge | null>;+ deleteRefreshTokenBridges: (data: RefreshTokenBridgeDeleteData) => Promise<DeleteResult>;+} {+ let indexesPromise: Promise<void> | null = null;++ const getRefreshTokenBridgeModel = () =>+ mongoose.models.RefreshTokenBridge as Model<IRefreshTokenBridge>;++ /**+ * A bridge holds an encrypted refresh token, and the TTL index is the only thing that ever+ * deletes one. `MONGO_AUTO_INDEX=false` is a supported deployment setting, and under it Mongoose+ * builds neither that index nor the compound uniqueness the upsert relies on — so bridges would+ * accumulate for the life of the collection and concurrent writes could leave duplicates. The+ * indexes are therefore installed before the first write, and a failed build is retried on the+ * next attempt rather than cached.+ */+ function ensureIndexes(): Promise<void> {+ if (!indexesPromise) {+ indexesPromise = createIndexesWithRetry(getRefreshTokenBridgeModel()).catch((error) => {+ indexesPromise = null;+ throw error;+ });+ }+ return indexesPromise;+ }++ async function upsertRefreshTokenBridge(+ bridgeData: RefreshTokenBridgeCreateData,+ ): Promise<IRefreshTokenBridge | null> {+ try {+ await ensureIndexes();+ const RefreshTokenBridge = getRefreshTokenBridgeModel();+ const filter = bridgeFilter(bridgeData);+ const update: UpdateQuery<IRefreshTokenBridge> = {+ $set: {+ encryptedNewRefreshToken: bridgeData.encryptedNewRefreshToken,+ version: bridgeData.version,+ expiresAt: bridgeData.expiresAt,+ ...(bridgeData.openidIssuer != null && { openidIssuer: bridgeData.openidIssuer }),+ },+ $setOnInsert: {+ oldRefreshTokenHash: bridgeData.oldRefreshTokenHash,+ userId: bridgeData.userId,+ ...(bridgeData.tenantId != null && { tenantId: bridgeData.tenantId }),+ createdAt: new Date(),+ },+ ...(bridgeData.openidIssuer == null && { $unset: { openidIssuer: '' } }),+ };+ return await RefreshTokenBridge.findOneAndUpdate(filter, update, {+ upsert: true,+ new: true,+ }).lean<IRefreshTokenBridge>();+ } catch (error) {+ logger.debug('[upsertRefreshTokenBridge] Error storing bridge:', error);+ throw error;+ }+ }++ async function findRefreshTokenBridge(+ query: RefreshTokenBridgeQuery,+ ): Promise<IRefreshTokenBridge | null> {+ try {+ const RefreshTokenBridge = getRefreshTokenBridgeModel();+ return await RefreshTokenBridge.findOne({+ ...bridgeFilter(query),+ expiresAt: { $gt: new Date() },+ }).lean<IRefreshTokenBridge>();+ } catch (error) {+ logger.debug('[findRefreshTokenBridge] Error finding bridge:', error);+ throw error;+ }+ }++ async function deleteRefreshTokenBridges(+ data: RefreshTokenBridgeDeleteData,+ ): Promise<DeleteResult> {+ try {+ const RefreshTokenBridge = getRefreshTokenBridgeModel();+ return await RefreshTokenBridge.deleteMany({+ ...(data.oldRefreshTokenHashes && {+ oldRefreshTokenHash: { $in: data.oldRefreshTokenHashes },+ }),+ ...(data.version && { version: data.version }),+ userId: data.userId,+ tenantId: data.tenantId ?? { $exists: false },+ });+ } catch (error) {+ logger.debug('[deleteRefreshTokenBridges] Error deleting bridges:', error);+ throw error;+ }+ }++ return {+ upsertRefreshTokenBridge,+ findRefreshTokenBridge,+ deleteRefreshTokenBridges,+ };+}++export type RefreshTokenBridgeMethods = ReturnType<typeof createRefreshTokenBridgeMethods>;diff --git a/packages/data-schemas/src/models/index.ts b/packages/data-schemas/src/models/index.tsindex 1da5a3eb3a..ed68a2fd43 100644--- a/packages/data-schemas/src/models/index.ts+++ b/packages/data-schemas/src/models/index.ts@@ -1,7 +1,9 @@import { createAgentTriggerLaneSequenceModel } from './triggerLaneSequence';import { createScheduleModel, createScheduleRunModel } from './schedule';import { createSkillSyncCredentialModel } from './skillSyncCredential';+import { createOpenIDRefreshFlightModel } from './openidRefreshFlight';import { createAgentTriggerUserPurgeModel } from './triggerUserPurge';+import { createRefreshTokenBridgeModel } from './refreshTokenBridge';import { createAgentTriggerDeliveryModel } from './triggerDelivery';import { createSkillSyncStatusModel } from './skillSyncStatus';import { createConversationTagModel } from './conversationTag';@@ -87,6 +89,8 @@ export function createModels(mongoose: typeof import('mongoose')): {AgentTriggerUserPurge: ReturnType<typeof createAgentTriggerUserPurgeModel>;Schedule: ReturnType<typeof createScheduleModel>;ScheduleRun: ReturnType<typeof createScheduleRunModel>;+ RefreshTokenBridge: ReturnType<typeof createRefreshTokenBridgeModel>;+ OpenIDRefreshFlight: ReturnType<typeof createOpenIDRefreshFlightModel>;} {const models = {User: createUserModel(mongoose),@@ -131,6 +135,8 @@ export function createModels(mongoose: typeof import('mongoose')): {AgentTriggerUserPurge: createAgentTriggerUserPurgeModel(mongoose),Schedule: createScheduleModel(mongoose),ScheduleRun: createScheduleRunModel(mongoose),+ RefreshTokenBridge: createRefreshTokenBridgeModel(mongoose),+ OpenIDRefreshFlight: createOpenIDRefreshFlightModel(mongoose),};/*** Background index builds fail silently unless an 'index' listener isdiff --git a/packages/data-schemas/src/models/openidRefreshFlight.ts b/packages/data-schemas/src/models/openidRefreshFlight.tsnew file mode 100644index 0000000000..55c07c2e94--- /dev/null+++ b/packages/data-schemas/src/models/openidRefreshFlight.ts@@ -0,0 +1,16 @@+import { Model } from 'mongoose';+import type * as t from '~/types';+import openidRefreshFlightSchema from '~/schema/openidRefreshFlight';++/**+ * Short-lived cross-worker coordination for inline OIDC refreshes. These+ * documents are keyed by hashed token/session context and expire via TTL.+ */+export function createOpenIDRefreshFlightModel(+ mongoose: typeof import('mongoose'),+): Model<t.IOpenIDRefreshFlight> {+ return (+ mongoose.models.OpenIDRefreshFlight ||+ mongoose.model<t.IOpenIDRefreshFlight>('OpenIDRefreshFlight', openidRefreshFlightSchema)+ );+}diff --git a/packages/data-schemas/src/models/plugins/tenantIsolation.coverage.spec.ts b/packages/data-schemas/src/models/plugins/tenantIsolation.coverage.spec.tsindex 6f318abe10..3af1e34b79 100644--- a/packages/data-schemas/src/models/plugins/tenantIsolation.coverage.spec.ts+++ b/packages/data-schemas/src/models/plugins/tenantIsolation.coverage.spec.ts@@ -15,10 +15,17 @@ const TENANT_ISOLATION_APPLIED = Symbol.for('librechat:tenantIsolation');* status rows and tenant-scoped override rows, so its methods apply explicit* tenant filters instead of ambient ALS scoping. AuditLog composes its tenant* filter from the JWT-resolved caller and uses `{ tenantId: { $exists: false } }`- * for platform-level entries. Adding an entry here must be a deliberate,- * reviewed decision — that is the whole point of this guard.+ * for platform-level entries. RefreshTokenBridge resolves tenant context from+ * the signed OpenID marker cookie during unauthenticated refresh recovery, and+ * its methods apply explicit tenant filters. Adding an entry here must be a+ * deliberate, reviewed decision — that is the whole point of this guard.*/-const MANUAL_TENANT_SCOPING = new Set<string>(['SystemGrant', 'SkillSyncStatus', 'AuditLog']);+const MANUAL_TENANT_SCOPING = new Set<string>([+ 'SystemGrant',+ 'SkillSyncStatus',+ 'AuditLog',+ 'RefreshTokenBridge',+]);function isPluginApplied(schema: mongoose.Schema): boolean {return (schema as unknown as { [key: symbol]: boolean })[TENANT_ISOLATION_APPLIED] === true;diff --git a/packages/data-schemas/src/models/refreshTokenBridge.ts b/packages/data-schemas/src/models/refreshTokenBridge.tsnew file mode 100644index 0000000000..f55063c4b2--- /dev/null+++ b/packages/data-schemas/src/models/refreshTokenBridge.ts@@ -0,0 +1,17 @@+import { Model } from 'mongoose';+import type * as t from '~/types';+import refreshTokenBridgeSchema from '~/schema/refreshTokenBridge';++/**+ * Refresh-token bridges are looked up from unauthenticated refresh requests+ * after user context is recovered from a signed cookie. Methods apply explicit+ * tenant checks, so automatic tenant isolation would be the wrong boundary here.+ */+export function createRefreshTokenBridgeModel(+ mongoose: typeof import('mongoose'),+): Model<t.IRefreshTokenBridge> {+ return (+ mongoose.models.RefreshTokenBridge ||+ mongoose.model<t.IRefreshTokenBridge>('RefreshTokenBridge', refreshTokenBridgeSchema)+ );+}diff --git a/packages/data-schemas/src/schema/index.ts b/packages/data-schemas/src/schema/index.tsindex 84aa7d4ec0..210a765b90 100644--- a/packages/data-schemas/src/schema/index.ts+++ b/packages/data-schemas/src/schema/index.ts@@ -17,6 +17,8 @@ export { default as pluginAuthSchema } from './pluginAuth';export { default as presetSchema } from './preset';export { default as promptSchema } from './prompt';export { default as promptGroupSchema } from './promptGroup';+export { default as openidRefreshFlightSchema } from './openidRefreshFlight';+export { default as refreshTokenBridgeSchema } from './refreshTokenBridge';export { default as roleSchema } from './role';export { default as sessionSchema } from './session';export { default as shareSchema } from './share';diff --git a/packages/data-schemas/src/schema/openidRefreshFlight.ts b/packages/data-schemas/src/schema/openidRefreshFlight.tsnew file mode 100644index 0000000000..ed852a9b9a--- /dev/null+++ b/packages/data-schemas/src/schema/openidRefreshFlight.ts@@ -0,0 +1,59 @@+import { Schema } from 'mongoose';+import type { IOpenIDRefreshFlight } from '~/types';++const openidRefreshFlightSchema: Schema<IOpenIDRefreshFlight> = new Schema<IOpenIDRefreshFlight>({+ key: {+ type: String,+ required: true,+ unique: true,+ },+ ownerId: {+ type: String,+ required: true,+ },+ status: {+ type: String,+ enum: ['pending', 'completed', 'failed', 'revoked'],+ required: true,+ default: 'pending',+ index: true,+ },+ encryptedResult: {+ type: String,+ },+ errorMessage: {+ type: String,+ },+ deliveryId: {+ type: String,+ },+ deliveryExpiresAt: {+ type: Date,+ },+ revocationRequestedAt: {+ type: Date,+ },+ createdAt: {+ type: Date,+ required: true,+ default: Date.now,+ },+ updatedAt: {+ type: Date,+ required: true,+ default: Date.now,+ },+ lockExpiresAt: {+ type: Date,+ required: true,+ index: true,+ },+ expiresAt: {+ type: Date,+ required: true,+ },+});++openidRefreshFlightSchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });++export default openidRefreshFlightSchema;diff --git a/packages/data-schemas/src/schema/refreshTokenBridge.ts b/packages/data-schemas/src/schema/refreshTokenBridge.tsnew file mode 100644index 0000000000..0f8658f4cb--- /dev/null+++ b/packages/data-schemas/src/schema/refreshTokenBridge.ts@@ -0,0 +1,45 @@+import { Schema } from 'mongoose';+import type { IRefreshTokenBridge } from '~/types';++const refreshTokenBridgeSchema: Schema<IRefreshTokenBridge> = new Schema<IRefreshTokenBridge>({+ oldRefreshTokenHash: {+ type: String,+ required: true,+ },+ encryptedNewRefreshToken: {+ type: String,+ required: true,+ },+ userId: {+ type: String,+ required: true,+ index: true,+ },+ tenantId: {+ type: String,+ index: true,+ },+ openidIssuer: {+ type: String,+ },+ version: {+ type: String,+ },+ createdAt: {+ type: Date,+ required: true,+ default: Date.now,+ },+ expiresAt: {+ type: Date,+ required: true,+ },+});++refreshTokenBridgeSchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });+refreshTokenBridgeSchema.index(+ { oldRefreshTokenHash: 1, userId: 1, tenantId: 1 },+ { unique: true },+);++export default refreshTokenBridgeSchema;diff --git a/packages/data-schemas/src/types/index.ts b/packages/data-schemas/src/types/index.tsindex c3c9aecd61..6f29fe93e6 100644--- a/packages/data-schemas/src/types/index.ts+++ b/packages/data-schemas/src/types/index.ts@@ -5,6 +5,8 @@ export * from './app';export * from './cache';export * from './user';export * from './token';+export * from './refreshTokenBridge';+export * from './openidRefreshFlight';export * from './convo';export * from './chatProject';export * from './session';diff --git a/packages/data-schemas/src/types/openidRefreshFlight.ts b/packages/data-schemas/src/types/openidRefreshFlight.tsnew file mode 100644index 0000000000..2da103909f--- /dev/null+++ b/packages/data-schemas/src/types/openidRefreshFlight.ts@@ -0,0 +1,74 @@+import type { Document } from 'mongoose';++export type OpenIDRefreshFlightStatus = 'pending' | 'completed' | 'failed' | 'revoked';++export interface IOpenIDRefreshFlight extends Document {+ key: string;+ ownerId: string;+ status: OpenIDRefreshFlightStatus;+ encryptedResult?: string;+ errorMessage?: string;+ deliveryId?: string;+ deliveryExpiresAt?: Date;+ revocationRequestedAt?: Date;+ createdAt: Date;+ updatedAt: Date;+ lockExpiresAt: Date;+ expiresAt: Date;+}++export interface OpenIDRefreshFlightCreateData {+ key: string;+ ownerId: string;+ lockExpiresAt: Date;+ expiresAt: Date;+}++export interface OpenIDRefreshFlightCompleteData {+ key: string;+ ownerId: string;+ encryptedResult: string;+ expiresAt: Date;+}++export interface OpenIDRefreshFlightRenewData {+ key: string;+ ownerId: string;+ lockExpiresAt: Date;+ expiresAt: Date;+}++export interface OpenIDRefreshFlightFailData {+ key: string;+ ownerId: string;+ errorMessage: string;+ expiresAt: Date;+}++export interface OpenIDRefreshFlightRevokeData {+ key: string;+ expiresAt: Date;+}++export interface OpenIDRefreshFlightClaimDeliveryData {+ key: string;+ ownerId: string;+ deliveryId: string;+ deliveryExpiresAt: Date;+ createdAt?: Date;+}++export interface OpenIDRefreshFlightReleaseDeliveryData {+ key: string;+ ownerId: string;+ deliveryId: string;+}++export interface OpenIDRefreshFlightQuery {+ key: string;+}++export interface OpenIDRefreshFlightAcquireResult {+ acquired: boolean;+ flight: IOpenIDRefreshFlight | null;+}diff --git a/packages/data-schemas/src/types/refreshTokenBridge.ts b/packages/data-schemas/src/types/refreshTokenBridge.tsnew file mode 100644index 0000000000..6db7cd8f14--- /dev/null+++ b/packages/data-schemas/src/types/refreshTokenBridge.ts@@ -0,0 +1,35 @@+import type { Document } from 'mongoose';++export interface IRefreshTokenBridge extends Document {+ oldRefreshTokenHash: string;+ encryptedNewRefreshToken: string;+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+ version?: string;+ createdAt: Date;+ expiresAt: Date;+}++export interface RefreshTokenBridgeCreateData {+ oldRefreshTokenHash: string;+ encryptedNewRefreshToken: string;+ userId: string;+ tenantId?: string;+ openidIssuer?: string;+ version?: string;+ expiresAt: Date;+}++export interface RefreshTokenBridgeQuery {+ oldRefreshTokenHash: string;+ userId: string;+ tenantId?: string;+}++export interface RefreshTokenBridgeDeleteData {+ oldRefreshTokenHashes?: string[];+ userId: string;+ tenantId?: string;+ version?: string;+}