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
🔐 feat: Enforce Required Two-Factor Authentication (#14731)
Marco Beretta92432e95d5bd
diff --git a/.env.example b/.env.exampleindex 19e0e6155a..c3c02f2d18 100644--- a/.env.example+++ b/.env.example@@ -849,6 +849,12 @@ LOGIN_MAX=7LOGIN_WINDOW=5REGISTER_MAX=5REGISTER_WINDOW=60+# Two-factor code attempts (login challenge and enrollment confirmation); defaults to LOGIN_MAX/LOGIN_WINDOW.+# TWO_FACTOR_TEMP_MAX=7+# TWO_FACTOR_TEMP_WINDOW=5+# Two-factor enrollment steps that check no guessable code; kept separate so wrong codes cannot strand an enrollment.+# TWO_FACTOR_SETUP_MAX=20+# TWO_FACTOR_SETUP_WINDOW=5# Password-reset email requests and token submissions are limited separately.# Submission values inherit the matching request value when omitted; all default to 2.@@ -894,6 +900,7 @@ ALLOW_EMAIL_LOGIN=trueALLOW_REGISTRATION=trueALLOW_SOCIAL_LOGIN=falseALLOW_SOCIAL_REGISTRATION=false+# A successful password reset invalidates existing sessions and bearer tokens, independently of 2FA enforcement.ALLOW_PASSWORD_RESET=false# ALLOW_ACCOUNT_DELETION=true # note: enabled by default if omitted/commented out# ALLOW_EMAIL_CHANGE=true # note: enabled by default if omitted/commented out@@ -902,6 +909,11 @@ ALLOW_PASSWORD_RESET=false# nodes issue and accept password reset links that carry no address binding, so one held by# a previous address owner can outlive the change and reset the renamed account.ALLOW_UNVERIFIED_EMAIL_LOGIN=true+# Requires email/password and LDAP users to enroll in 2FA before a full session is issued.+# Federated identity providers remain responsible for enforcing their own MFA policies.+# This policy and the TWO_FACTOR_SETUP_* quotas are process-wide environment settings, like the+# existing pre-authentication login limits, because they apply before request/tenant config is available.+ENFORCE_TWO_FACTOR_AUTHENTICATION=falseSESSION_EXPIRY=1000 * 60 * 15REFRESH_TOKEN_EXPIRY=(1000 * 60 * 60 * 24) * 7diff --git a/api/server/controllers/AuthController.js b/api/server/controllers/AuthController.jsindex f5e3a230f0..a261ace60c 100644--- a/api/server/controllers/AuthController.js+++ b/api/server/controllers/AuthController.js@@ -1,6 +1,5 @@const cookies = require('cookie');const jwt = require('jsonwebtoken');-const crypto = require('node:crypto');const { logger, runAsSystem, tenantStorage } = require('@librechat/data-schemas');const {math,@@ -12,6 +11,13 @@ const {isOpenIDSessionMissingError,isOpenIDSessionIdentityMatch,OPENID_EXPIRY_BUFFER_SECONDS,+ clearCloudFrontCookies,+ createLocalRefreshHandler,+ generateTwoFactorSetupToken,+ getValidOpenIDReuseCredential,+ isTokenRetired,+ isTwoFactorEnrollmentRequired,+ sanitizeUserForAuthResponse,} = require('@librechat/api');const {requestPasswordReset,@@ -25,6 +31,7 @@ const {deleteAllUserSessions,deletePasskeysByUser,awaitAuthUserDocEviction,+ deleteSession,getUserById,findSession,updateUser,@@ -81,19 +88,6 @@ const registrationController = async (req, res) => {}};-const sanitizeUserForAuthResponse = (user) => {- const source = (typeof user?.toObject === 'function' ? user.toObject() : user) || {};- const {- password: _pw,- __v: _v,- totpSecret: _ts,- backupCodes: _bc,- federatedTokens: _ft,- ...safeUser- } = source;- return safeUser;-};-const runInUserTenant = (user, fn) =>user.tenantId? tenantStorage.run(@@ -102,30 +96,6 @@ const runInUserTenant = (user, fn) =>): runAsSystem(fn);-const getValidOpenIDReuseUserId = (parsedCookies, refreshToken) => {- const openidUserId = parsedCookies.openid_user_id;- if (!openidUserId || !process.env.JWT_REFRESH_SECRET) {- return null;- }-- try {- const payload = jwt.verify(openidUserId, process.env.JWT_REFRESH_SECRET);- 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;@@ -330,6 +300,20 @@ const resetPasswordController = createResetPasswordController({awaitAuthUserDocEviction,});+const refreshLocalSession = createLocalRefreshHandler({+ userProjection: AUTH_REFRESH_USER_PROJECTION,+ getUserById,+ findSession,+ setAuthTokens,+ deleteAllUserSessions,+ deleteSession,+ generateTwoFactorSetupToken,+ isTwoFactorEnrollmentRequired,+ clearCloudFrontCookies,+ warn: (message) => logger.warn(message),+ error: (message, cause) => logger.error(message, cause),+});+const refreshController = async (req, res) => {const parsedCookies = req.headers.cookie ? cookies.parse(req.headers.cookie) : {};const token_provider = parsedCookies.token_provider;@@ -352,7 +336,10 @@ const refreshController = async (req, res) => {const reusableSessionToken = cookieDiffersFromSession? null: getReusableOpenIDSessionToken(req.session?.openidTokens);- const reuseUserId = reusableSessionToken ? getValidOpenIDReuseUserId(parsedCookies) : null;+ const reuseCredential = reusableSessionToken+ ? getValidOpenIDReuseCredential(parsedCookies, process.env.JWT_REFRESH_SECRET)+ : null;+ const reuseUserId = reuseCredential?.userId;if (reuseUserId) {const reuseSessionTokens = req.session?.openidTokens;try {@@ -366,7 +353,11 @@ const refreshController = async (req, res) => {const user = await runAsSystem(async () =>getUserById(reuseUserId, AUTH_REFRESH_USER_PROJECTION),);- if (!user || !isReusableOpenIDSessionIdentity(reuseSessionTokens, user)) {+ if (+ !user ||+ isTokenRetired(reuseCredential, user) ||+ !isReusableOpenIDSessionIdentity(reuseSessionTokens, user)+ ) {return undefined;}return sendAuthorized(() => {@@ -397,7 +388,8 @@ const refreshController = async (req, res) => {}const refreshUserId =- req.session?.openidTokens?.appUserId ?? getValidOpenIDReuseUserId(parsedCookies);+ req.session?.openidTokens?.appUserId ??+ getValidOpenIDReuseCredential(parsedCookies, process.env.JWT_REFRESH_SECRET)?.userId;if (!refreshUserId) {return res.status(403).send('Invalid OpenID refresh token');}@@ -532,7 +524,11 @@ const refreshController = async (req, res) => {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);+ const userId = getValidOpenIDReuseCredential(+ parsedCookies,+ process.env.JWT_REFRESH_SECRET,+ bridgeSourceToken,+ )?.userId;if (userId) {try {const bridgeUser = await runAsSystem(async () =>@@ -602,51 +598,8 @@ const refreshController = async (req, res) => {}}- /** For non-OpenID users, read refresh token from cookies */- const refreshToken = parsedCookies.refreshToken;- if (!refreshToken) {- return res.status(200).send('Refresh token not provided');- }-- try {- const payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);- const user = await getUserById(payload.id, AUTH_REFRESH_USER_PROJECTION);- if (!user) {- return res.status(401).redirect('/login');- }-- const userId = payload.id;-- if (process.env.NODE_ENV === 'CI') {- const token = await setAuthTokens(userId, res, null, req);- return res.status(200).send({ token, user: sanitizeUserForAuthResponse(user) });- }-- /** Session with the hashed refresh token */- const session = await findSession(- {- userId: userId,- refreshToken: refreshToken,- },- { lean: false },- );-- if (session && session.expiration > new Date()) {- const token = await setAuthTokens(userId, res, session, req);-- res.status(200).send({ token, user: sanitizeUserForAuthResponse(user) });- } else if (req?.query?.retry) {- // Retrying from a refresh token request that failed (401)- res.status(403).send('No session found');- } else if (payload.exp < Date.now() / 1000) {- res.status(403).redirect('/login');- } else {- res.status(401).send('Refresh token expired or not found for this user');- }- } catch (err) {- logger.error(`[refreshController] Invalid refresh token:`, err);- res.status(403).send('Invalid refresh token');- }+ /** For non-OpenID users, delegate refresh to the typed local handler. */+ return refreshLocalSession(req, res, parsedCookies.refreshToken);};const graphTokenController = async (req, res) => {diff --git a/api/server/controllers/AuthController.spec.js b/api/server/controllers/AuthController.spec.jsindex 6a1866c1f9..40fb8d2a0b 100644--- a/api/server/controllers/AuthController.spec.js+++ b/api/server/controllers/AuthController.spec.js@@ -115,13 +115,29 @@ jest.mock('@librechat/api', () => ({}return params;}),+ clearCloudFrontCookies: jest.fn(),+ createLocalRefreshHandler: jest.requireActual('@librechat/api').createLocalRefreshHandler,+ getValidOpenIDReuseCredential: jest.requireActual('@librechat/api').getValidOpenIDReuseCredential,+ sanitizeUserForAuthResponse: jest.requireActual('@librechat/api').sanitizeUserForAuthResponse,+ generateTwoFactorSetupToken: jest.fn(() => 'setup-token'),+ isTwoFactorEnrollmentRequired: jest.fn(() => false),+ /** The retirement cutoff is the assertion under test, so it runs for real rather than stubbed. */+ isTokenRetired: jest.requireActual('@librechat/api').isTokenRetired,+ TOKEN_RETIREMENT_FIELDS: jest.requireActual('@librechat/api').TOKEN_RETIREMENT_FIELDS,}));const { createHash } = require('node:crypto');const openIdClient = require('openid-client');const jwt = require('jsonwebtoken');const { logger } = require('@librechat/data-schemas');-const { isEnabled, findOpenIDUser, buildOpenIDRefreshParams } = require('@librechat/api');+const {+ isEnabled,+ clearCloudFrontCookies,+ findOpenIDUser,+ buildOpenIDRefreshParams,+ generateTwoFactorSetupToken,+ isTwoFactorEnrollmentRequired,+} = require('@librechat/api');const {graphTokenController,refreshController,@@ -536,6 +552,18 @@ describe('refreshController – OpenID path', () => {options,);+ /** `setOpenIDAuthTokens` stamps this cookie to the millisecond, so the cutoffs can date it */+ const makeSignedReuseCookie = (issuedAtMs, id = 'user-db-id') =>+ jwt.sign(+ {+ id,+ issuedAtMs,+ refreshTokenHash: createHash('sha256').update('stored-refresh').digest('base64url'),+ },+ process.env.JWT_REFRESH_SECRET,+ { expiresIn: '1h' },+ );+const setOpenIDReuseCookies = (signedUserId = makeSignedUserId()) => {req.headers.cookie = ['token_provider=openid',@@ -1201,6 +1229,61 @@ describe('refreshController – OpenID path', () => {expectOpenIDRefreshGrant();});+ /** Arms the reuse shortcut so only the cookie's mint time decides whether it is taken. */+ const armOpenIDReuse = (issuedAtMs) => {+ setOpenIDReuseCookies(makeSignedReuseCookie(issuedAtMs));+ req.session = {+ openidTokens: {+ accessToken: 'session-access-token',+ idToken: makeSessionToken(),+ refreshToken: 'stored-refresh',+ lastRefreshedAt: Date.now(),+ appUserId: defaultUser._id,+ openidSubject: baseClaims.sub,+ tenantId: defaultUser.tenantId,+ openidIssuer: baseClaims.iss,+ },+ };+ };++ it('declines the reuse shortcut for a cookie minted before enrollment', async () => {+ const twoFactorEnrolledAt = new Date();+ armOpenIDReuse(twoFactorEnrolledAt.getTime() - 1);+ getUserById.mockResolvedValue({ ...defaultUser, twoFactorEnrolledAt });++ await refreshController(req, res);++ expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();+ expectOpenIDRefreshGrant();+ });++ it('declines the reuse shortcut for a cookie minted in the resetting millisecond', async () => {+ const credentialsChangedAt = new Date();+ armOpenIDReuse(credentialsChangedAt.getTime());+ getUserById.mockResolvedValue({ ...defaultUser, credentialsChangedAt });++ await refreshController(req, res);++ expect(setCloudFrontAuthCookies).not.toHaveBeenCalled();+ expectOpenIDRefreshGrant();+ });++ it('keeps the reuse shortcut for a cookie minted after both cutoffs', async () => {+ const twoFactorEnrolledAt = new Date();+ armOpenIDReuse(twoFactorEnrolledAt.getTime() + 1);+ getUserById.mockResolvedValue({+ ...defaultUser,+ twoFactorEnrolledAt,+ credentialsChangedAt: new Date(twoFactorEnrolledAt.getTime() - 60_000),+ });++ await refreshController(req, res);++ expect(openIdClient.refreshTokenGrant).not.toHaveBeenCalled();+ expect(setCloudFrontAuthCookies).toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(200);+ });+it('falls through to full OpenID refresh when session tokens are stale', async () => {setOpenIDReuseCookies();req.session = {@@ -2311,7 +2394,8 @@ describe('refreshController – LibreChat path', () => {process.env.JWT_REFRESH_SECRET = refreshSecret;process.env.NODE_ENV = 'test';setAuthTokens.mockResolvedValue('local-app-token');- findSession.mockResolvedValue({ expiration: new Date(Date.now() + 60_000) });+ findSession.mockResolvedValue({ _id: 'session-id', expiration: new Date(Date.now() + 60_000) });+ isTwoFactorEnrollmentRequired.mockReturnValue(false);const refreshToken = jwt.sign({ id: 'local-user-id' }, refreshSecret, {expiresIn: '1h',@@ -2325,6 +2409,7 @@ describe('refreshController – LibreChat path', () => {status: jest.fn().mockReturnThis(),send: jest.fn().mockReturnThis(),redirect: jest.fn(),+ clearCookie: jest.fn(),};});@@ -2361,7 +2446,7 @@ describe('refreshController – LibreChat path', () => {expect(setAuthTokens).toHaveBeenCalledWith('local-user-id',res,- { expiration: expect.any(Date) },+ expect.objectContaining({ expiration: expect.any(Date) }),req,);expect(sentPayload).toEqual({@@ -2373,6 +2458,244 @@ describe('refreshController – LibreChat path', () => {});});+ it('requires enrollment before issuing tokens from an existing local refresh session', async () => {+ const user = {+ _id: 'local-user-id',+ provider: 'local',+ twoFactorEnabled: false,+ email: '[email protected]',+ };+ getUserById.mockResolvedValue(user);+ isTwoFactorEnrollmentRequired.mockReturnValue(true);++ await refreshController(req, res);++ expect(generateTwoFactorSetupToken).toHaveBeenCalledWith(+ 'local-user-id',+ process.env.JWT_SECRET,+ );+ expect(res.send).toHaveBeenCalledWith({+ code: 'TWO_FACTOR_ENROLLMENT_REQUIRED',+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });+ expect(findSession).toHaveBeenCalledWith(+ {+ userId: 'local-user-id',+ refreshToken: expect.any(String),+ },+ { lean: false },+ );+ expect(setAuthTokens).not.toHaveBeenCalled();+ expect(deleteSession).toHaveBeenCalledWith({ sessionId: 'session-id' });+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(clearCloudFrontCookies).toHaveBeenCalledWith(res, {+ userId: 'local-user-id',+ tenantId: undefined,+ storageRegion: undefined,+ });++ findSession.mockResolvedValue(null);+ jest.clearAllMocks();+ isTwoFactorEnrollmentRequired.mockReturnValue(true);++ await refreshController(req, res);++ expect(generateTwoFactorSetupToken).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ /**+ * `findSession` resolves before anything is minted, so recovery landing in that gap is caught by+ * neither gate: the token handed back postdates `credentialsChangedAt`, and `setAuthTokens` re-saves+ * the very session document recovery had already deleted.+ */+ describe('a password reset landing after the session lookup', () => {+ const racingRead = (user) => {+ getUserById+ .mockResolvedValueOnce(user)+ .mockResolvedValueOnce({ credentialsChangedAt: new Date(Date.now() + 60_000) });+ };++ it('withdraws the session it had already minted', async () => {+ racingRead({ _id: 'local-user-id', provider: 'local', twoFactorEnabled: true });++ await refreshController(req, res);++ expect(setAuthTokens).toHaveBeenCalled();+ expect(deleteAllUserSessions).toHaveBeenCalledWith({ userId: 'local-user-id' });+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.send).toHaveBeenCalledWith('Refresh token expired or not found for this user');+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.clearCookie).toHaveBeenCalledWith('token_provider');+ });++ it('withdraws the session it had already minted when the recheck cannot complete', async () => {+ getUserById+ .mockResolvedValueOnce({ _id: 'local-user-id', provider: 'local', twoFactorEnabled: true })+ .mockRejectedValueOnce(new Error('database unavailable'));++ await refreshController(req, res);++ expect(setAuthTokens).toHaveBeenCalled();+ expect(deleteAllUserSessions).toHaveBeenCalledWith({ userId: 'local-user-id' });+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.send).not.toHaveBeenCalledWith(+ expect.objectContaining({ token: 'local-app-token' }),+ );+ });++ it('withholds the enrollment token it had already minted', async () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ racingRead({ _id: 'local-user-id', provider: 'local', twoFactorEnabled: false });++ await refreshController(req, res);++ expect(generateTwoFactorSetupToken).toHaveBeenCalled();+ expect(deleteAllUserSessions).toHaveBeenCalledWith({ userId: 'local-user-id' });+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.send).not.toHaveBeenCalledWith(+ expect.objectContaining({ tempToken: 'setup-token' }),+ );+ });++ it('reads the cutoff again only once the credential exists', async () => {+ const order = [];+ getUserById+ .mockResolvedValueOnce({ _id: 'local-user-id', provider: 'local', twoFactorEnabled: true })+ .mockImplementationOnce(async () => {+ order.push('recheck');+ return {};+ });+ setAuthTokens.mockImplementationOnce(async () => {+ order.push('mint');+ return 'local-app-token';+ });++ await refreshController(req, res);++ expect(order).toEqual(['mint', 'recheck']);+ expect(getUserById).toHaveBeenLastCalledWith(+ 'local-user-id',+ 'twoFactorEnrolledAt credentialsChangedAt',+ );+ expect(res.status).toHaveBeenCalledWith(200);+ });+ });++ it('refuses a refresh credential that predates required enrollment', async () => {+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ provider: 'local',+ twoFactorEnabled: true,+ twoFactorEnrolledAt: new Date(Date.now() + 60_000),+ });++ await refreshController(req, res);++ /** Promotion lands before revocation, so the cutoff is what denies the older cookie. */+ expect(setAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ });++ it('refuses a stale refresh credential even on the CI shortcut', async () => {+ process.env.NODE_ENV = 'CI';+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ provider: 'local',+ twoFactorEnabled: true,+ twoFactorEnrolledAt: new Date(Date.now() + 60_000),+ });++ await refreshController(req, res);++ process.env.NODE_ENV = 'test';+ expect(setAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('accepts a refresh credential minted after enrollment', async () => {+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ email: '[email protected]',+ provider: 'local',+ twoFactorEnabled: true,+ twoFactorEnrolledAt: new Date(Date.now() - 60_000),+ });++ await refreshController(req, res);++ expect(setAuthTokens).toHaveBeenCalled();+ expect(res.send).toHaveBeenCalledWith(expect.objectContaining({ token: 'local-app-token' }));+ });++ it('leaves refresh alone for accounts that never enrolled through the policy', async () => {+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ email: '[email protected]',+ provider: 'local',+ twoFactorEnabled: true,+ twoFactorEnrolledAt: null,+ });++ await refreshController(req, res);++ expect(setAuthTokens).toHaveBeenCalled();+ });++ it('does not issue an enrollment token for a revoked local refresh session', async () => {+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ provider: 'local',+ twoFactorEnabled: false,+ });+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ findSession.mockResolvedValue(null);++ await refreshController(req, res);++ expect(generateTwoFactorSetupToken).not.toHaveBeenCalled();+ expect(setAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.send).toHaveBeenCalledWith('Refresh token expired or not found for this user');+ });++ it('does not issue an enrollment token for an expired local refresh session', async () => {+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ provider: 'local',+ twoFactorEnabled: false,+ });+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ findSession.mockResolvedValue({ expiration: new Date(Date.now() - 60_000) });++ await refreshController(req, res);++ expect(generateTwoFactorSetupToken).not.toHaveBeenCalled();+ expect(setAuthTokens).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.send).toHaveBeenCalledWith('Refresh token expired or not found for this user');+ });++ it('preserves CI refresh compatibility without session lookup', async () => {+ process.env.NODE_ENV = 'CI';+ getUserById.mockResolvedValue({+ _id: 'local-user-id',+ provider: 'local',+ twoFactorEnabled: false,+ });+ isTwoFactorEnrollmentRequired.mockReturnValue(true);++ await refreshController(req, res);++ expect(findSession).not.toHaveBeenCalled();+ expect(generateTwoFactorSetupToken).not.toHaveBeenCalled();+ expect(setAuthTokens).toHaveBeenCalledWith('local-user-id', res, null, req);+ });+it('sanitizes user documents before returning CI refresh responses', async () => {process.env.NODE_ENV = 'CI';getUserById.mockResolvedValue({diff --git a/api/server/controllers/TwoFactorController.js b/api/server/controllers/TwoFactorController.jsindex 18a0ee3f5a..1844332acb 100644--- a/api/server/controllers/TwoFactorController.js+++ b/api/server/controllers/TwoFactorController.js@@ -1,4 +1,5 @@const { encryptV3, logger } = require('@librechat/data-schemas');+const { clearEnrollmentNonces } = require('@librechat/api');const {verifyOTPOrBackupCode,generateBackupCodes,@@ -43,10 +44,13 @@ const enable2FA = async (req, res) => {const { plainCodes, codeObjects } = await generateBackupCodes();const encryptedSecret = encryptV3(secret);- const user = await updateUser(userId, {- pendingTotpSecret: encryptedSecret,- pendingBackupCodes: codeObjects,- });+ const user = await updateUser(+ userId,+ clearEnrollmentNonces({+ pendingTotpSecret: encryptedSecret,+ pendingBackupCodes: codeObjects,+ }),+ );const email = user.email || (existingUser && existingUser.email) || '';const otpauthUrl = `otpauth://totp/${safeAppTitle}:${email}?secret=${secret}&issuer=${safeAppTitle}`;@@ -119,7 +123,7 @@ const confirm2FA = async (req, res) => {if (user.pendingBackupCodes?.length) {update.backupCodes = user.pendingBackupCodes;}- await updateUser(userId, update);+ await updateUser(userId, clearEnrollmentNonces(update));return res.status(200).json();}return res.status(400).json({ message: 'Invalid token.' });@@ -151,13 +155,16 @@ const disable2FA = async (req, res) => {return res.status(result.status ?? 400).json({ message: msg });}}- await updateUser(userId, {- totpSecret: null,- backupCodes: [],- twoFactorEnabled: false,- pendingTotpSecret: null,- pendingBackupCodes: [],- });+ await updateUser(+ userId,+ clearEnrollmentNonces({+ totpSecret: null,+ backupCodes: [],+ twoFactorEnabled: false,+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ }),+ );return res.status(200).json();} catch (err) {logger.error('[disable2FA]', err);diff --git a/api/server/controllers/__tests__/TwoFactorController.spec.js b/api/server/controllers/__tests__/TwoFactorController.spec.jsindex 62531d94a1..edea2c0f82 100644--- a/api/server/controllers/__tests__/TwoFactorController.spec.js+++ b/api/server/controllers/__tests__/TwoFactorController.spec.js@@ -4,8 +4,11 @@ const mockVerifyOTPOrBackupCode = jest.fn();const mockGenerateTOTPSecret = jest.fn();const mockGenerateBackupCodes = jest.fn();const mockEncryptV3 = jest.fn();+const mockGetTOTPSecret = jest.fn();+const mockVerifyTOTP = jest.fn();jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),encryptV3: (...args) => mockEncryptV3(...args),logger: { error: jest.fn() },}));@@ -15,8 +18,8 @@ jest.mock('~/server/services/twoFactorService', () => ({generateBackupCodes: (...args) => mockGenerateBackupCodes(...args),generateTOTPSecret: (...args) => mockGenerateTOTPSecret(...args),verifyBackupCode: jest.fn(),- getTOTPSecret: jest.fn(),- verifyTOTP: jest.fn(),+ getTOTPSecret: (...args) => mockGetTOTPSecret(...args),+ verifyTOTP: (...args) => mockVerifyTOTP(...args),}));jest.mock('~/models', () => ({@@ -24,7 +27,12 @@ jest.mock('~/models', () => ({updateUser: (...args) => mockUpdateUser(...args),}));-const { enable2FA, regenerateBackupCodes } = require('~/server/controllers/TwoFactorController');+const {+ enable2FA,+ confirm2FA,+ disable2FA,+ regenerateBackupCodes,+} = require('~/server/controllers/TwoFactorController');function createRes() {const res = {};@@ -45,6 +53,66 @@ beforeEach(() => {mockGenerateTOTPSecret.mockReturnValue('NEWSECRET');mockGenerateBackupCodes.mockResolvedValue({ plainCodes: PLAIN_CODES, codeObjects: CODE_OBJECTS });mockEncryptV3.mockReturnValue('encrypted-secret');+ mockGetTOTPSecret.mockResolvedValue('plain-secret');+ mockVerifyTOTP.mockResolvedValue(true);+});++/** Any write that moves the pending or live credentials strands an in-flight required enrollment. */+const CLEARED_NONCES = {+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+};++describe('required-enrollment nonce cleanup', () => {+ it('clears stale nonce state when setup is regenerated', async () => {+ mockGetUserById.mockResolvedValue({ _id: 'user1', twoFactorEnabled: false, email: '[email protected]' });+ mockUpdateUser.mockResolvedValue({ email: '[email protected]' });++ await enable2FA({ user: { id: 'user1' }, body: {} }, createRes());++ expect(mockUpdateUser.mock.calls[0][1]).toMatchObject(CLEARED_NONCES);+ });++ it('clears stale nonce state when 2FA is confirmed from account settings', async () => {+ mockGetUserById.mockResolvedValue({+ _id: 'user1',+ twoFactorEnabled: false,+ pendingTotpSecret: 'encrypted-secret',+ pendingBackupCodes: CODE_OBJECTS,+ });+ mockUpdateUser.mockResolvedValue({});+ const res = createRes();++ await confirm2FA({ user: { id: 'user1' }, body: { token: '123456' } }, res);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(mockUpdateUser.mock.calls[0][1]).toMatchObject({+ twoFactorEnabled: true,+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ ...CLEARED_NONCES,+ });+ });++ it('clears stale nonce state when 2FA is disabled', async () => {+ mockGetUserById.mockResolvedValue({+ _id: 'user1',+ twoFactorEnabled: true,+ totpSecret: 'enc-secret',+ });+ mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: true });+ mockUpdateUser.mockResolvedValue({});+ const res = createRes();++ await disable2FA({ user: { id: 'user1' }, body: { token: '123456' } }, res);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(mockUpdateUser.mock.calls[0][1]).toMatchObject({+ twoFactorEnabled: false,+ totpSecret: null,+ ...CLEARED_NONCES,+ });+ });});describe('enable2FA', () => {diff --git a/api/server/controllers/auth/LoginController.js b/api/server/controllers/auth/LoginController.jsindex bf606b1dea..593c081a80 100644--- a/api/server/controllers/auth/LoginController.js+++ b/api/server/controllers/auth/LoginController.js@@ -1,30 +1,14 @@-const { logger } = require('@librechat/data-schemas');+const { createLoginController, clearCloudFrontCookies } = require('@librechat/api');const { generate2FATempToken } = require('~/server/services/twoFactorService');+const { getUserById, deleteAllUserSessions } = require('~/models');const { setAuthTokens } = require('~/server/services/AuthService');-const loginController = async (req, res) => {- try {- if (!req.user) {- return res.status(400).json({ message: 'Invalid credentials' });- }+const loginController = createLoginController({+ generate2FATempToken,+ getUserById,+ deleteAllUserSessions,+ setAuthTokens,+ clearCloudFrontCookies,+});- if (req.user.twoFactorEnabled) {- const tempToken = generate2FATempToken(req.user._id);- return res.status(200).json({ twoFAPending: true, tempToken });- }-- const { password: _p, totpSecret: _t, __v, ...user } = req.user;- user.id = user._id.toString();-- const token = await setAuthTokens(req.user._id, res, null, req);-- return res.status(200).send({ token, user });- } catch (err) {- logger.error('[loginController]', err);- return res.status(500).json({ message: 'Something went wrong' });- }-};--module.exports = {- loginController,-};+module.exports = { loginController };diff --git a/api/server/controllers/auth/LoginController.spec.js b/api/server/controllers/auth/LoginController.spec.jsnew file mode 100644index 0000000000..d012f8536c--- /dev/null+++ b/api/server/controllers/auth/LoginController.spec.js@@ -0,0 +1,319 @@+const mockGenerate2FATempToken = jest.fn(() => 'challenge-token');+const mockSetAuthTokens = jest.fn(() => Promise.resolve('auth-token'));+const mockClearCloudFrontCookies = jest.fn();+const mockDeleteAllUserSessions = jest.fn(() => Promise.resolve({ deletedCount: 1 }));++/** What the record carries right now, so a reset can land mid-request the way recovery does. */+const record = { credentialsChangedAt: null };+const mockGetUserById = jest.fn(async () => ({+ credentialsChangedAt: record.credentialsChangedAt,+}));++jest.mock('@librechat/data-schemas', () => ({+ logger: { error: jest.fn(), warn: jest.fn() },+}));++jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),+ clearCloudFrontCookies: (...args) => mockClearCloudFrontCookies(...args),+}));++jest.mock('~/server/services/twoFactorService', () => ({+ generate2FATempToken: (...args) => mockGenerate2FATempToken(...args),+}));++jest.mock('~/server/services/AuthService', () => ({+ setAuthTokens: (...args) => mockSetAuthTokens(...args),+}));++jest.mock('~/models', () => ({+ getUserById: (...args) => mockGetUserById(...args),+ deleteAllUserSessions: (...args) => mockDeleteAllUserSessions(...args),+}));++const { loginController } = require('./LoginController');+const { verifyTwoFactorSetupToken } = require('@librechat/api');++function createResponse() {+ return {+ status: jest.fn().mockReturnThis(),+ json: jest.fn().mockReturnThis(),+ send: jest.fn().mockReturnThis(),+ clearCookie: jest.fn().mockReturnThis(),+ };+}++describe('loginController', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ const originalSecret = process.env.JWT_SECRET;++ beforeEach(() => {+ jest.clearAllMocks();+ record.credentialsChangedAt = null;+ process.env.JWT_SECRET = 'jwt-secret';+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ });++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ if (originalSecret === undefined) {+ delete process.env.JWT_SECRET;+ } else {+ process.env.JWT_SECRET = originalSecret;+ }+ });++ it('uses the existing 2FA challenge for enrolled users', async () => {+ const req = { user: { _id: 'user-1', twoFactorEnabled: true } };+ const res = createResponse();++ await loginController(req, res);++ expect(mockGenerate2FATempToken).toHaveBeenCalledWith('user-1');+ expect(res.json).toHaveBeenCalledWith({+ twoFAPending: true,+ tempToken: 'challenge-token',+ });+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('requires purpose-scoped enrollment before issuing auth tokens', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const req = { user: { _id: 'user-2', twoFactorEnabled: false } };+ const res = createResponse();++ await loginController(req, res);++ expect(mockClearCloudFrontCookies).toHaveBeenCalledWith(res, {+ userId: 'user-2',+ tenantId: undefined,+ storageRegion: undefined,+ });+ expect(res.json).toHaveBeenCalledWith({+ code: 'TWO_FACTOR_ENROLLMENT_REQUIRED',+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: expect.any(String),+ });+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ expect(verifyTwoFactorSetupToken(res.json.mock.calls[0][0].tempToken, 'jwt-secret')).toEqual(+ expect.objectContaining({ userId: 'user-2' }),+ );+ });++ it('keeps optional 2FA login behavior unchanged when enforcement is disabled', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ const req = {+ user: {+ _id: 'user-3',+ password: 'secret',+ totpSecret: 'totp',+ email: '[email protected]',+ },+ };+ const res = createResponse();++ await loginController(req, res);++ expect(mockSetAuthTokens).toHaveBeenCalledWith('user-3', res, null, req);+ expect(res.send).toHaveBeenCalledWith({+ token: 'auth-token',+ user: {+ _id: 'user-3',+ email: '[email protected]',+ id: 'user-3',+ },+ });+ });++ it('does not offer local enrollment to federated users', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const req = {+ user: { _id: 'user-4', provider: 'openid', email: '[email protected]' },+ };+ const res = createResponse();++ await loginController(req, res);++ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ /**+ * A password reset assigns a password without consulting `provider`, so a federated record can+ * be signed in through the local strategy. Under enforcement that login checks neither the+ * identity provider's MFA nor this policy, and enrollment cannot remedy it.+ */+ it('refuses a password login for a federated record under enforcement', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const req = {+ user: { _id: 'user-4', provider: 'openid', email: '[email protected]' },+ };+ const res = createResponse();++ await loginController(req, res);++ expect(res.status).toHaveBeenCalledWith(403);+ /** The code carries the reason: a bare 403 is rendered as a ban by getLoginError. */+ expect(res.json).toHaveBeenCalledWith({+ code: 'TWO_FACTOR_FEDERATED_LOGIN_BLOCKED',+ message: 'Sign in with your identity provider to continue.',+ });+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ expect(res.send).not.toHaveBeenCalled();+ });++ it('refuses a federated password login even when LibreChat 2FA is already enabled', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const req = { user: { _id: 'user-5', provider: 'openid', twoFactorEnabled: true } };+ const res = createResponse();++ await loginController(req, res);++ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.json).toHaveBeenCalledWith({+ code: 'TWO_FACTOR_FEDERATED_LOGIN_BLOCKED',+ message: 'Sign in with your identity provider to continue.',+ });+ expect(mockGenerate2FATempToken).not.toHaveBeenCalled();+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('leaves federated password logins alone when enforcement is disabled', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ const req = {+ user: { _id: 'user-6', provider: 'openid', email: '[email protected]' },+ };+ const res = createResponse();++ await loginController(req, res);++ expect(mockSetAuthTokens).toHaveBeenCalledWith('user-6', res, null, req);+ });++ /**+ * The strategy compared the password against a document read before hashing it, so recovery+ * landing before the response revokes the credential this request is still holding. Everything+ * minted here is stamped after that reset, which is precisely what `isTokenRetired` cannot catch,+ * so the reset lands during the mint in each of these and the login has to lose the race.+ */+ describe('a password reset landing mid-login', () => {+ const resetDuring = (mock, value) =>+ mock.mockImplementationOnce(() => {+ record.credentialsChangedAt = new Date('2026-01-01T00:00:00.000Z');+ return value;+ });++ it('refuses the session it had already minted', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ resetDuring(mockSetAuthTokens, Promise.resolve('auth-token'));+ const req = { user: { _id: 'user-7', email: '[email protected]' } };+ const res = createResponse();++ await loginController(req, res);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.json).toHaveBeenCalledWith({ message: 'Invalid credentials' });+ expect(res.send).not.toHaveBeenCalled();+ expect(mockDeleteAllUserSessions).toHaveBeenCalledWith({ userId: 'user-7' });+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.clearCookie).toHaveBeenCalledWith('token_provider');+ });++ it('withdraws the session it had already minted when the recheck cannot complete', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ mockGetUserById.mockRejectedValueOnce(new Error('database unavailable'));+ const req = { user: { _id: 'user-9', email: '[email protected]' } };+ const res = createResponse();++ await loginController(req, res);++ expect(mockSetAuthTokens).toHaveBeenCalledTimes(1);+ expect(mockDeleteAllUserSessions).toHaveBeenCalledWith({ userId: 'user-9' });+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.status).toHaveBeenCalledWith(500);+ expect(res.send).not.toHaveBeenCalled();+ });++ /** Otherwise the holder of the revoked password picks the second factor the account keeps. */+ it('withholds the enrollment token it had already minted', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ mockGetUserById.mockImplementationOnce(async () => {+ record.credentialsChangedAt = new Date('2026-01-01T00:00:00.000Z');+ return { credentialsChangedAt: record.credentialsChangedAt };+ });+ const req = { user: { _id: 'user-8', twoFactorEnabled: false } };+ const res = createResponse();++ await loginController(req, res);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.json).toHaveBeenCalledWith({ message: 'Invalid credentials' });+ expect(res.json).not.toHaveBeenCalledWith(+ expect.objectContaining({ tempToken: expect.any(String) }),+ );+ });++ it('withholds the second-factor challenge it had already minted', async () => {+ resetDuring(mockGenerate2FATempToken, 'challenge-token');+ const req = { user: { _id: 'user-9', twoFactorEnabled: true } };+ const res = createResponse();++ await loginController(req, res);++ expect(mockGenerate2FATempToken).toHaveBeenCalledWith('user-9');+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.json).toHaveBeenCalledWith({ message: 'Invalid credentials' });+ expect(res.json).not.toHaveBeenCalledWith(+ expect.objectContaining({ tempToken: 'challenge-token' }),+ );+ });++ it('reads the stamp again only after the credential exists', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ const order = [];+ mockSetAuthTokens.mockImplementationOnce(async () => {+ order.push('mint');+ return 'auth-token';+ });+ mockGetUserById.mockImplementationOnce(async () => {+ order.push('recheck');+ return { credentialsChangedAt: record.credentialsChangedAt };+ });+ const res = createResponse();++ await loginController({ user: { _id: 'user-10', email: '[email protected]' } }, res);++ expect(order).toEqual(['mint', 'recheck']);+ expect(mockGetUserById).toHaveBeenCalledWith(+ 'user-10',+ 'twoFactorEnrolledAt credentialsChangedAt',+ );+ });+ });++ /** A stamp the authenticating read already saw is not a reset, and must not refuse the login. */+ it('signs in an account whose password reset predates the login', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ record.credentialsChangedAt = new Date('2026-01-01T00:00:00.000Z');+ const req = {+ user: {+ _id: 'user-11',+ email: '[email protected]',+ credentialsChangedAt: new Date('2026-01-01T00:00:00.000Z'),+ },+ };+ const res = createResponse();++ await loginController(req, res);++ expect(res.send).toHaveBeenCalledWith({+ token: 'auth-token',+ user: expect.objectContaining({ id: 'user-11' }),+ });+ expect(mockDeleteAllUserSessions).not.toHaveBeenCalled();+ });+});diff --git a/api/server/controllers/auth/TwoFactorAuthController.js b/api/server/controllers/auth/TwoFactorAuthController.jsindex a75f7c2653..2eac6c4860 100644--- a/api/server/controllers/auth/TwoFactorAuthController.js+++ b/api/server/controllers/auth/TwoFactorAuthController.js@@ -1,71 +1,21 @@-const jwt = require('jsonwebtoken');-const { logger } = require('@librechat/data-schemas');-const { isTokenIssuedBeforeCredentialChange } = require('@librechat/api');+const { createEnrollmentControllers, clearCloudFrontCookies } = require('@librechat/api');const {verifyTOTP,getTOTPSecret,verifyBackupCode,+ generateBackupCodes,} = require('~/server/services/twoFactorService');const { setAuthTokens } = require('~/server/services/AuthService');-const { getUserById } = require('~/models');+const { getUserById, updateTwoFactorEnrollment, deleteAllUserSessions } = require('~/models');-/**- * Verifies the 2FA code during login using a temporary token.- */-const verify2FAWithTempToken = async (req, res) => {- try {- const { tempToken, token, backupCode } = req.body;- if (!tempToken) {- return res.status(400).json({ message: 'Missing temporary token' });- }-- let payload;- try {- payload = jwt.verify(tempToken, process.env.JWT_SECRET);- } catch (err) {- logger.error('Failed to verify temporary token:', err);- return res.status(401).json({ message: 'Invalid or expired temporary token' });- }-- const user = await getUserById(payload.userId, '+totpSecret +backupCodes');- if (!user || !user.twoFactorEnabled) {- return res.status(400).json({ message: '2FA is not enabled for this user' });- }-- /**- * The first factor was proven before the reset, so honouring this token would let a- * password reset be survived by anyone who also holds the second factor.- */- if (isTokenIssuedBeforeCredentialChange(payload, user)) {- logger.warn('[verify2FAWithTempToken] Rejected a token issued before a credential change');- return res.status(401).json({ message: 'Invalid or expired temporary token' });- }-- const secret = await getTOTPSecret(user.totpSecret);- let isVerified = false;- if (token) {- isVerified = await verifyTOTP(secret, token);- } else if (backupCode) {- isVerified = await verifyBackupCode({ user, backupCode });- }-- if (!isVerified) {- return res.status(401).json({ message: 'Invalid 2FA code or backup code' });- }-- const userData = user.toObject ? user.toObject() : { ...user };- delete userData.__v;- delete userData.password;- delete userData.totpSecret;- delete userData.backupCodes;- userData.id = user._id.toString();-- const authToken = await setAuthTokens(user._id, res, null, req);- return res.status(200).json({ token: authToken, user: userData });- } catch (err) {- logger.error('[verify2FAWithTempToken]', err);- return res.status(500).json({ message: 'Something went wrong' });- }-};--module.exports = { verify2FAWithTempToken };+module.exports = createEnrollmentControllers({+ getUserById,+ getTOTPSecret,+ verifyTOTP,+ verifyBackupCode,+ generateBackupCodes,+ updateTwoFactorEnrollment,+ deleteAllUserSessions,+ setAuthTokens,+ clearCloudFrontCookies,+});diff --git a/api/server/controllers/auth/TwoFactorAuthController.spec.js b/api/server/controllers/auth/TwoFactorAuthController.spec.jsindex 82f72e13fa..53da727c91 100644--- a/api/server/controllers/auth/TwoFactorAuthController.spec.js+++ b/api/server/controllers/auth/TwoFactorAuthController.spec.js@@ -1,18 +1,20 @@const jwt = require('jsonwebtoken');-const mockLogger = { warn: jest.fn(), error: jest.fn(), debug: jest.fn() };-const mockGetUserById = jest.fn();+const mockSetAuthTokens = jest.fn(() => Promise.resolve('auth-token'));+const mockDeleteAllUserSessions = jest.fn(() => Promise.resolve({ deletedCount: 0 }));const mockGetTOTPSecret = jest.fn();const mockVerifyTOTP = jest.fn();const mockVerifyBackupCode = jest.fn();-const mockSetAuthTokens = jest.fn();-jest.mock('@librechat/data-schemas', () => ({ logger: mockLogger }));+jest.mock('@librechat/data-schemas', () => ({+ logger: { error: jest.fn(), warn: jest.fn() },+}));jest.mock('~/server/services/twoFactorService', () => ({getTOTPSecret: (...args) => mockGetTOTPSecret(...args),verifyTOTP: (...args) => mockVerifyTOTP(...args),verifyBackupCode: (...args) => mockVerifyBackupCode(...args),+ generateBackupCodes: (...args) => store.generateBackupCodes(...args),}));jest.mock('~/server/services/AuthService', () => ({@@ -20,47 +22,210 @@ jest.mock('~/server/services/AuthService', () => ({}));jest.mock('~/models', () => ({- getUserById: (...args) => mockGetUserById(...args),+ getUserById: (...args) => store.getUserById(...args),+ updateTwoFactorEnrollment: (...args) => store.updateTwoFactorEnrollment(...args),+ deleteAllUserSessions: (...args) => mockDeleteAllUserSessions(...args),}));-const { verify2FAWithTempToken } = require('./TwoFactorAuthController');+const ELIGIBLE_PROVIDERS = new Set(['local', 'ldap']);++/**+ * Minimal in-memory user store with the same compare-and-swap semantics as the Mongo-backed+ * `updateTwoFactorEnrollment`, so the controller chain is exercised against real lifecycle state.+ */+const store = {+ doc: null,+ codeCounter: 0,+ reset(overrides = {}) {+ this.codeCounter = 0;+ this.doc = {+ _id: 'user-1',+ email: '[email protected]',+ password: 'password-hash',+ provider: 'local',+ /**+ * These queries select with `+field` tokens only, which leaves Mongoose no projection to+ * send, so the stored document arrives whole. The session records ride along with it.+ */+ refreshToken: [{ refreshToken: 'live-session-token' }],+ twoFactorEnabled: false,+ totpSecret: null,+ backupCodes: [],+ pendingTotpSecret: 'encrypted-secret',+ pendingBackupCodes: [{ codeHash: 'staged-hash', used: false }],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ ...overrides,+ };+ },+ async getUserById() {+ return this.doc ? { ...this.doc } : null;+ },+ async generateBackupCodes() {+ this.codeCounter += 1;+ return {+ plainCodes: [`plain-${this.codeCounter}`],+ codeObjects: [{ codeHash: `hash-${this.codeCounter}`, used: false, usedAt: null }],+ };+ },+ async updateTwoFactorEnrollment(_userId, guard, update) {+ if (this.doc.twoFactorEnabled) {+ return null;+ }+ if (this.doc.provider != null && !ELIGIBLE_PROVIDERS.has(this.doc.provider)) {+ return null;+ }+ const matches = Object.entries(guard).every(+ ([key, value]) => JSON.stringify(this.doc[key] ?? null) === JSON.stringify(value ?? null),+ );+ if (!matches) {+ return null;+ }+ this.doc = { ...this.doc, ...update };+ return { ...this.doc };+ },+};++const {+ verify2FAWithTempToken,+ confirm2FASetupWithTempToken,+ acknowledge2FASetup,+ finalize2FASetup,+} = require('./TwoFactorAuthController');+const {+ generateTwoFactorLoginChallengeToken,+ verifyTwoFactorSetupAcknowledgementToken,+ verifyTwoFactorSetupFinalizationToken,+} = require('@librechat/api');-const USER_ID = '65f0c1b2c3d4e5f6a7b8c9d0';-const SECRET = 'test-jwt-secret';+function createResponse() {+ return {+ status: jest.fn().mockReturnThis(),+ json: jest.fn().mockReturnThis(),+ clearCookie: jest.fn().mockReturnThis(),+ };+}-const buildRes = () => {- const res = {};- res.status = jest.fn(() => res);- res.json = jest.fn(() => res);+/** Drives the request pipeline the routes wire up: credential validation, then the controller. */+async function runAcknowledge(acknowledgementToken) {+ const credential = verifyTwoFactorSetupAcknowledgementToken(+ acknowledgementToken,+ process.env.JWT_SECRET,+ );+ const req = {+ user: credential ? { id: credential.userId } : undefined,+ twoFactorEnrollmentNonce: credential?.nonce,+ body: { acknowledgementToken },+ };+ const res = createResponse();+ await acknowledge2FASetup(req, res);return res;-};+}++async function runFinalize(finalizationToken) {+ const credential = verifyTwoFactorSetupFinalizationToken(+ finalizationToken,+ process.env.JWT_SECRET,+ );+ const req = {+ user: credential ? { id: credential.userId } : undefined,+ twoFactorEnrollmentNonce: credential?.nonce,+ body: { finalizationToken },+ };+ const res = createResponse();+ await finalize2FASetup(req, res);+ return res;+}++async function runConfirm(token = '123456') {+ const req = { user: { id: 'user-1' }, body: { token } };+ const res = createResponse();+ await confirm2FASetupWithTempToken(req, res);+ return res;+}++const jsonPayload = (res) => res.json.mock.calls[0][0];-/** Signs a real temp token so `iat` is genuine rather than hand-stamped. */-const tempTokenFor = (userId) => jwt.sign({ userId }, SECRET, { expiresIn: '5m' });+const originalSecret = process.env.JWT_SECRET;+const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;beforeEach(() => {jest.clearAllMocks();- process.env.JWT_SECRET = SECRET;- mockGetTOTPSecret.mockResolvedValue('totp-secret');+ process.env.JWT_SECRET = 'jwt-secret';+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ mockGetTOTPSecret.mockResolvedValue('plain-secret');mockVerifyTOTP.mockResolvedValue(true);- mockSetAuthTokens.mockResolvedValue('auth-token');+ store.reset();});-describe('verify2FAWithTempToken credential-change cutoff', () => {- const userDoc = (overrides = {}) => ({- _id: { toString: () => USER_ID },- twoFactorEnabled: true,- totpSecret: 'totp-secret',- ...overrides,+afterAll(() => {+ if (originalSecret === undefined) {+ delete process.env.JWT_SECRET;+ } else {+ process.env.JWT_SECRET = originalSecret;+ }+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+});++/** The recheck after minting is a read like any other, and it can fail after the cookies are set. */+const failRecheckAfterMint = () =>+ mockSetAuthTokens.mockImplementationOnce(async () => {+ jest.spyOn(store, 'getUserById').mockRejectedValueOnce(new Error('database unavailable'));+ return 'auth-token';+ });++describe('verify2FAWithTempToken', () => {+ beforeEach(() => {+ store.reset({ twoFactorEnabled: true, totpSecret: 'encrypted-secret' });});- it('rejects a temp token minted before the credentials changed', async () => {- const tempToken = tempTokenFor(USER_ID);- /** Stamp the reset a minute into the future so the token unambiguously predates it. */- mockGetUserById.mockResolvedValue(- userDoc({ credentialsChangedAt: new Date(Date.now() + 60_000) }),+ it('accepts a normal login challenge token and creates the app session', async () => {+ const tempToken = jwt.sign(+ { userId: 'user-1', purpose: 'login_2fa_challenge' },+ process.env.JWT_SECRET,);- const res = buildRes();+ const req = { body: { tempToken, token: '123456' } };+ const res = createResponse();++ await verify2FAWithTempToken(req, res);++ expect(mockSetAuthTokens).toHaveBeenCalledWith('user-1', res, null, req);+ expect(res.status).toHaveBeenCalledWith(200);+ });++ it('refuses a federated password challenge under enforcement', async () => {+ store.reset({ provider: 'openid', twoFactorEnabled: true, totpSecret: 'encrypted-secret' });+ const tempToken = jwt.sign(+ { userId: 'user-1', purpose: 'login_2fa_challenge' },+ process.env.JWT_SECRET,+ );+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);++ expect(res.status).toHaveBeenCalledWith(403);+ expect(jsonPayload(res)).toEqual({+ code: 'TWO_FACTOR_FEDERATED_LOGIN_BLOCKED',+ message: 'Sign in with your identity provider to continue.',+ });+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it.each([+ 'required_2fa_setup',+ 'required_2fa_acknowledgement',+ 'required_2fa_finalization',+ undefined,+ ])('rejects a %s token before creating a session', async (purpose) => {+ const claims = purpose+ ? { userId: 'user-1', purpose, nonce: 'nonce' }+ : { userId: 'user-1', nonce: 'nonce' };+ const tempToken = jwt.sign(claims, process.env.JWT_SECRET);+ const res = createResponse();await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);@@ -68,27 +233,459 @@ describe('verify2FAWithTempToken credential-change cutoff', () => {expect(mockSetAuthTokens).not.toHaveBeenCalled();});- it('accepts a temp token minted after the credentials changed', async () => {- const tempToken = tempTokenFor(USER_ID);- mockGetUserById.mockResolvedValue(- userDoc({ credentialsChangedAt: new Date(Date.now() - 60_000) }),+ it('strips every secret and enrollment nonce from the session response', async () => {+ const tempToken = jwt.sign(+ { userId: 'user-1', purpose: 'login_2fa_challenge' },+ process.env.JWT_SECRET,);- const res = buildRes();+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);++ expect(jsonPayload(res).user).toEqual({+ _id: 'user-1',+ id: 'user-1',+ email: '[email protected]',+ provider: 'local',+ twoFactorEnabled: true,+ });+ });++ /**+ * The challenge buys a session without presenting the password again, so recovery has to reach+ * it: redeeming one minted beforehand would hand back exactly the access `deleteAllUserSessions`+ * had just revoked.+ */+ it('refuses a challenge minted before a password reset', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ store.doc.credentialsChangedAt = new Date(Date.now() + 1000);+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('keeps a challenge minted after a password reset', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ store.doc.credentialsChangedAt = new Date(Date.now() - 60_000);+ const res = createResponse();await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);expect(res.status).toHaveBeenCalledWith(200);- expect(mockSetAuthTokens).toHaveBeenCalled();+ expect(mockSetAuthTokens).toHaveBeenCalledTimes(1);+ });++ /** `iat` cannot separate these two, so the millisecond claim is what decides both cases. */+ it('orders the challenge against a reset landing in the same second', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ const { issuedAtMs } = jwt.decode(tempToken);++ store.doc.credentialsChangedAt = new Date(issuedAtMs - 1);+ const accepted = createResponse();+ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, accepted);+ expect(accepted.status).toHaveBeenCalledWith(200);++ store.doc.credentialsChangedAt = new Date(issuedAtMs);+ const refused = createResponse();+ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, refused);+ expect(refused.status).toHaveBeenCalledWith(401);});- it('accepts a temp token when the account never changed credentials', async () => {- const tempToken = tempTokenFor(USER_ID);- mockGetUserById.mockResolvedValue(userDoc());- const res = buildRes();+ it('surrenders the resetting second for a challenge minted before the claim existed', async () => {+ const issuedAt = Math.floor(Date.now() / 1000);+ const tempToken = jwt.sign(+ { userId: 'user-1', purpose: 'login_2fa_challenge', iat: issuedAt },+ process.env.JWT_SECRET,+ );+ store.doc.credentialsChangedAt = new Date(issuedAt * 1000 + 500);+ const res = createResponse();await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);+ expect(res.status).toHaveBeenCalledWith(401);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ /**+ * Verifying the factor is a decrypt and a comparison, so recovery can land inside it. The session+ * minted afterwards postdates `credentialsChangedAt`, which is the one thing the cutoff cannot retire,+ * and it is created after recovery has already swept the sessions away.+ */+ describe('a password reset landing mid-verification', () => {+ const resetDuring = (mock) =>+ mock.mockImplementationOnce(async () => {+ store.doc.credentialsChangedAt = new Date(Date.now() + 1000);+ return true;+ });++ it('withdraws the session it had already minted for a TOTP code', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ resetDuring(mockVerifyTOTP);+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);++ expect(mockSetAuthTokens).toHaveBeenCalledTimes(1);+ expect(mockDeleteAllUserSessions).toHaveBeenCalledWith({ userId: 'user-1' });+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.clearCookie).toHaveBeenCalledWith('token_provider');+ expect(res.status).toHaveBeenCalledWith(401);+ expect(jsonPayload(res)).toEqual({ message: 'Invalid or expired temporary token' });+ });++ /** Backup codes are the slower comparison of the two, so the window is wider here. */+ it('withdraws the session it had already minted for a backup code', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ resetDuring(mockVerifyBackupCode);+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, backupCode: 'backup-1' } }, res);++ expect(mockSetAuthTokens).toHaveBeenCalledTimes(1);+ expect(mockDeleteAllUserSessions).toHaveBeenCalledWith({ userId: 'user-1' });+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('withdraws the minted session when the recheck cannot complete', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ mockVerifyTOTP.mockResolvedValueOnce(true);+ failRecheckAfterMint();+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);++ expect(mockDeleteAllUserSessions).toHaveBeenCalledWith({ userId: 'user-1' });+ expect(mockDeleteAllUserSessions.mock.invocationCallOrder[0]).toBeGreaterThan(+ mockSetAuthTokens.mock.invocationCallOrder[0],+ );+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.status).toHaveBeenCalledWith(500);+ });++ it('leaves a verification no reset raced through alone', async () => {+ const tempToken = generateTwoFactorLoginChallengeToken('user-1', process.env.JWT_SECRET);+ const res = createResponse();++ await verify2FAWithTempToken({ body: { tempToken, token: '123456' } }, res);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(mockDeleteAllUserSessions).not.toHaveBeenCalled();+ });+ });+});++describe('confirm2FASetupWithTempToken', () => {+ it('returns deliverable codes and an acknowledgement credential without a session', async () => {+ const res = await runConfirm();+expect(res.status).toHaveBeenCalledWith(200);- expect(mockSetAuthTokens).toHaveBeenCalled();+ expect(jsonPayload(res).backupCodes).toEqual(['plain-1']);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ expect(store.doc.twoFactorEnabled).toBe(false);+ expect(store.doc.totpSecret).toBeNull();+ expect(store.doc.pendingBackupCodes).toEqual([+ { codeHash: 'hash-1', used: false, usedAt: null },+ ]);+ expect(+ verifyTwoFactorSetupAcknowledgementToken(+ jsonPayload(res).acknowledgementToken,+ process.env.JWT_SECRET,+ ),+ ).toEqual({ userId: 'user-1', nonce: expect.any(String) });+ });++ it('is retryable after a lost response, rotating codes and retiring the old credential', async () => {+ const first = await runConfirm();+ const second = await runConfirm();++ expect(jsonPayload(second).backupCodes).toEqual(['plain-2']);+ expect(jsonPayload(second).acknowledgementToken).not.toBe(+ jsonPayload(first).acknowledgementToken,+ );++ const staleAcknowledgement = await runAcknowledge(jsonPayload(first).acknowledgementToken);++ expect(staleAcknowledgement.status).toHaveBeenCalledWith(400);+ expect(store.doc.twoFactorEnabled).toBe(false);+ });++ it('does not issue auth tokens when the TOTP is wrong', async () => {+ mockVerifyTOTP.mockResolvedValue(false);++ const res = await runConfirm('000000');++ expect(res.status).toHaveBeenCalledWith(400);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ expect(store.doc.twoFactorAcknowledgementNonceHash).toBeNull();+ });++ it('rejects requests without a validated setup user', async () => {+ const res = createResponse();++ await confirm2FASetupWithTempToken({ body: { token: '123456' } }, res);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });+});++describe('acknowledge2FASetup', () => {+ it('exchanges a one-time acknowledgement nonce for a finalization credential', async () => {+ const confirmed = await runConfirm();++ const res = await runAcknowledge(jsonPayload(confirmed).acknowledgementToken);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ expect(store.doc.twoFactorEnabled).toBe(false);+ expect(store.doc.twoFactorAcknowledgementNonceHash).toBeNull();+ expect(+ verifyTwoFactorSetupFinalizationToken(+ jsonPayload(res).finalizationToken,+ process.env.JWT_SECRET,+ ),+ ).toEqual({ userId: 'user-1', nonce: expect.any(String) });+ });++ it('rejects a replayed acknowledgement credential without minting anything', async () => {+ const confirmed = await runConfirm();+ await runAcknowledge(jsonPayload(confirmed).acknowledgementToken);++ const replay = await runAcknowledge(jsonPayload(confirmed).acknowledgementToken);++ expect(replay.status).toHaveBeenCalledWith(400);+ expect(jsonPayload(replay)).not.toHaveProperty('finalizationToken');+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('rejects acknowledgement without a validated identity', async () => {+ const res = createResponse();++ await acknowledge2FASetup({ body: {} }, res);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });+});++describe('finalize2FASetup', () => {+ async function reachFinalization() {+ const confirmed = await runConfirm();+ const acknowledged = await runAcknowledge(jsonPayload(confirmed).acknowledgementToken);+ return jsonPayload(acknowledged).finalizationToken;+ }++ it.each(['local', 'ldap', undefined])(+ 'promotes an eligible %s enrollment and only then creates the session',+ async (provider) => {+ store.reset({ provider });+ const finalizationToken = await reachFinalization();++ expect(mockSetAuthTokens).not.toHaveBeenCalled();++ const res = await runFinalize(finalizationToken);++ expect(mockSetAuthTokens).toHaveBeenCalledWith('user-1', res, null, expect.any(Object));+ expect(store.doc).toMatchObject({+ twoFactorEnabled: true,+ totpSecret: 'encrypted-secret',+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ /** Dates the tokens issued before enrollment, so it is stamped but never published. */+ twoFactorEnrolledAt: expect.any(Date),+ });+ expect(jsonPayload(res)).toEqual({+ token: 'auth-token',+ user: {+ _id: 'user-1',+ id: 'user-1',+ email: '[email protected]',+ provider,+ twoFactorEnabled: true,+ },+ });+ },+ );++ it('revokes pre-enrollment sessions before minting the enrolled one', async () => {+ const finalizationToken = await reachFinalization();++ await runFinalize(finalizationToken);++ expect(mockDeleteAllUserSessions).toHaveBeenCalledWith({ userId: 'user-1' });+ /** Revoking after minting would drop the session this response hands back. */+ expect(mockDeleteAllUserSessions.mock.invocationCallOrder[0]).toBeLessThan(+ mockSetAuthTokens.mock.invocationCallOrder[0],+ );+ });++ it('withdraws the enrolled session when the recheck cannot complete', async () => {+ const finalizationToken = await reachFinalization();+ failRecheckAfterMint();++ const res = await runFinalize(finalizationToken);++ expect(mockDeleteAllUserSessions).toHaveBeenCalledTimes(2);+ expect(mockDeleteAllUserSessions.mock.invocationCallOrder[1]).toBeGreaterThan(+ mockSetAuthTokens.mock.invocationCallOrder[0],+ );+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.status).toHaveBeenCalledWith(500);+ });++ it('leaves existing sessions alone when finalization is rejected', async () => {+ const finalizationToken = await reachFinalization();+ store.doc.pendingTotpSecret = null;++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(400);+ expect(mockDeleteAllUserSessions).not.toHaveBeenCalled();+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('rejects a replayed finalization credential without a second session', async () => {+ const finalizationToken = await reachFinalization();+ await runFinalize(finalizationToken);+ mockSetAuthTokens.mockClear();++ const replay = await runFinalize(finalizationToken);++ expect(replay.status).toHaveBeenCalledWith(400);+ expect(jsonPayload(replay)).not.toHaveProperty('token');+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('rejects a finalization credential retired by a later confirmation', async () => {+ const finalizationToken = await reachFinalization();+ await runConfirm();++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(400);+ expect(store.doc.twoFactorEnabled).toBe(false);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('rejects a user whose provider becomes federated before finalization', async () => {+ const finalizationToken = await reachFinalization();+ store.doc.provider = 'openid';++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(400);+ expect(store.doc.twoFactorEnabled).toBe(false);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('rejects finalization when global enforcement is disabled', async () => {+ const finalizationToken = await reachFinalization();+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(400);+ expect(store.doc.twoFactorEnabled).toBe(false);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('withdraws the session when password recovery lands after the promotion', async () => {+ const finalizationToken = await reachFinalization();+ /**+ * Recovery cannot be staged up front: clearing the pending enrollment first would fail the+ * compare-and-swap, which is the half already covered. Landing it while the hand-off runs is+ * the ordering that leaves a token postdating the cutoff.+ */+ mockSetAuthTokens.mockImplementationOnce(async () => {+ store.doc.credentialsChangedAt = new Date(Date.now() + 1000);+ return 'auth-token';+ });++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(jsonPayload(res)).not.toHaveProperty('token');+ expect(res.clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(res.clearCookie).toHaveBeenCalledWith('token_provider');+ /** The session minted in that gap has to go, not just the token this response withholds. */+ expect(mockDeleteAllUserSessions).toHaveBeenCalledTimes(2);+ expect(mockDeleteAllUserSessions.mock.invocationCallOrder[1]).toBeGreaterThan(+ mockSetAuthTokens.mock.invocationCallOrder[0],+ );+ });++ it('hands off normally when the account was recovered before the enrollment', async () => {+ store.reset({ credentialsChangedAt: new Date(Date.now() - 60_000) });+ const finalizationToken = await reachFinalization();++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(jsonPayload(res)).toHaveProperty('token', 'auth-token');+ expect(mockDeleteAllUserSessions).toHaveBeenCalledTimes(1);+ });++ it('rejects finalization once the pending setup has been cleared', async () => {+ const finalizationToken = await reachFinalization();+ store.doc.pendingTotpSecret = null;+ store.doc.pendingBackupCodes = [];++ const res = await runFinalize(finalizationToken);++ expect(res.status).toHaveBeenCalledWith(400);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('rejects finalization without a validated identity', async () => {+ const res = createResponse();++ await finalize2FASetup({ body: {} }, res);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(mockSetAuthTokens).not.toHaveBeenCalled();+ });++ it('never leaks secrets or enrollment nonces in the session response', async () => {+ const finalizationToken = await reachFinalization();++ const res = await runFinalize(finalizationToken);+ const { user } = jsonPayload(res);++ for (const field of [+ 'password',+ 'totpSecret',+ 'backupCodes',+ 'refreshToken',+ 'pendingTotpSecret',+ 'pendingBackupCodes',+ 'twoFactorAcknowledgementNonceHash',+ 'twoFactorFinalizationNonceHash',+ ]) {+ expect(user).not.toHaveProperty(field);+ }+ });++ /**+ * Naming the secrets one by one only ever catches the secrets already thought of, and this+ * response is built from an unprojected document. Pinning the whole shape is what keeps a field+ * added to the schema later from arriving here unannounced.+ */+ it('sends only allowlisted fields in the session response', async () => {+ const finalizationToken = await reachFinalization();++ const res = await runFinalize(finalizationToken);++ expect(jsonPayload(res).user).toEqual({+ _id: 'user-1',+ id: 'user-1',+ email: '[email protected]',+ provider: 'local',+ twoFactorEnabled: true,+ });});});diff --git a/api/server/middleware/__tests__/requireJwtAuth.spec.js b/api/server/middleware/__tests__/requireJwtAuth.spec.jsindex bbadd5fb04..7f81760181 100644--- a/api/server/middleware/__tests__/requireJwtAuth.spec.js+++ b/api/server/middleware/__tests__/requireJwtAuth.spec.js@@ -14,6 +14,12 @@ const jwt = require('jsonwebtoken');let mockPassportError = null;let mockRegisteredStrategies = new Set(['jwt']);+/** The post-mint retirement read; defaults to an account no recovery has touched. */+let mockGetUserById = jest.fn(async () => ({}));++jest.mock('~/models', () => ({+ getUserById: (...args) => mockGetUserById(...args),+}));jest.mock('passport', () => ({_strategy: jest.fn((strategy) => (mockRegisteredStrategies.has(strategy) ? {} : undefined)),@@ -44,6 +50,7 @@ jest.mock('@librechat/data-schemas', () => {getUserId: () => tenantStorage.getStore()?.userId,getRequestId: () => tenantStorage.getStore()?.requestId,logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },+ runAsSystem: (fn) => tenantStorage.run({ tenantId: '__SYSTEM__' }, fn),tenantStorage,};});@@ -68,6 +75,13 @@ jest.mock('@librechat/api', () => {normalizeContextValue(req.headers?.['x-correlation-id']);return {isEnabled: jest.fn(() => false),+ createRequiredTwoFactorGate: actualApi.createRequiredTwoFactorGate,+ clearCloudFrontCookies: jest.fn(),+ generateTwoFactorSetupToken: jest.fn(() => 'setup-token'),+ isTwoFactorEnrollmentRequired: jest.fn(() => false),+ /** Real dating logic: the ordering these tests exercise is the whole point. */+ isTokenRetired: actualApi.isTokenRetired,+ TOKEN_RETIREMENT_FIELDS: actualApi.TOKEN_RETIREMENT_FIELDS,recordRumProxyRequest: jest.fn(),getAuthFailureReasonCategory: actualApi.getAuthFailureReasonCategory,buildSafeAuthLogContext: actualApi.buildSafeAuthLogContext,@@ -106,8 +120,11 @@ const { requireRumProxyAuth } = requireJwtAuth;const { getTenantId, getUserId, logger } = require('@librechat/data-schemas');const {isEnabled,+ clearCloudFrontCookies,maybeRefreshCloudFrontAuthCookiesMiddleware,recordRumProxyRequest,+ generateTwoFactorSetupToken,+ isTwoFactorEnrollmentRequired,} = require('@librechat/api');const passport = require('passport');@@ -129,6 +146,9 @@ function mockRes() {};}+/** The enrollment policy re-reads the retirement cutoff, so its response lands a tick later. */+const flushPolicy = () => new Promise((resolve) => setImmediate(resolve));+/** Runs requireJwtAuth and returns the tenantId observed inside next(). */function runAuth(user) {return new Promise((resolve) => {@@ -152,7 +172,11 @@ describe('requireJwtAuth tenant context chaining', () => {afterEach(() => {mockPassportError = null;mockRegisteredStrategies = new Set(['jwt']);+ mockGetUserById = jest.fn(async () => ({}));isEnabled.mockReturnValue(false);+ isTwoFactorEnrollmentRequired.mockReturnValue(false);+ generateTwoFactorSetupToken.mockClear();+ clearCloudFrontCookies.mockClear();maybeRefreshCloudFrontAuthCookiesMiddleware.mockClear();logger.debug.mockClear();logger.info.mockClear();@@ -200,6 +224,162 @@ describe('requireJwtAuth tenant context chaining', () => {expect(next).toHaveBeenCalled();});+ it('blocks protected API access for unenrolled local users', async () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ { method: 'GET', baseUrl: '/api/convos', path: '/' },+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);+ await flushPolicy();++ expect(generateTwoFactorSetupToken).toHaveBeenCalledWith('user-123', process.env.JWT_SECRET);+ expect(clearCloudFrontCookies).toHaveBeenCalledWith(res, {+ userId: 'user-123',+ tenantId: undefined,+ storageRegion: undefined,+ });+ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.json).toHaveBeenCalledWith({+ code: 'TWO_FACTOR_ENROLLMENT_REQUIRED',+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });+ expect(next).not.toHaveBeenCalled();+ });++ it('allows only the exact logout route through the enrollment policy', () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ { method: 'POST', baseUrl: '/api/auth', path: '/logout' },+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);++ expect(generateTwoFactorSetupToken).not.toHaveBeenCalled();+ expect(next).toHaveBeenCalledTimes(1);+ });++ it.each([+ ['a trailing slash', { method: 'POST', baseUrl: '/api/auth', path: '/logout/' }],+ ['an uppercase path', { method: 'POST', baseUrl: '/API/AUTH', path: '/LOGOUT' }],+ ['mixed case and a trailing slash', { method: 'POST', baseUrl: '/Api/Auth', path: '/Logout/' }],+ ])('allows the logout route through the enrollment policy with %s', (_label, requestShape) => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ requestShape,+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);++ expect(generateTwoFactorSetupToken).not.toHaveBeenCalled();+ expect(res.status).not.toHaveBeenCalledWith(403);+ expect(next).toHaveBeenCalledTimes(1);+ });++ it('still blocks a non-logout route that merely ends in a slash', async () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ { method: 'POST', baseUrl: '/api/auth', path: '/logout/extra' },+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);+ await flushPolicy();++ expect(res.status).toHaveBeenCalledWith(403);+ expect(next).not.toHaveBeenCalled();+ });++ it('withdraws the setup token when recovery lands between the strategy read and the mint', async () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ const issuedAtMs = Date.now();+ /** The reset commits after the bearer was minted, so it revokes the credential in flight. */+ mockGetUserById = jest.fn(async () => ({ credentialsChangedAt: new Date(issuedAtMs + 1000) }));+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ {+ method: 'GET',+ baseUrl: '/api/convos',+ path: '/',+ headers: {+ authorization: `Bearer ${jwt.sign({ id: 'user-123', issuedAtMs }, jwtSecret)}`,+ },+ },+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);+ await flushPolicy();++ expect(mockGetUserById).toHaveBeenCalledWith(+ 'user-123',+ 'twoFactorEnrolledAt credentialsChangedAt',+ );+ expect(res.status).toHaveBeenCalledWith(401);+ expect(res.json).toHaveBeenCalledWith({ message: 'Unauthorized' });+ expect(res.json).not.toHaveBeenCalledWith(+ expect.objectContaining({ tempToken: 'setup-token' }),+ );+ expect(next).not.toHaveBeenCalled();+ });++ it('still hands back a setup token when no recovery raced the request', async () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ const issuedAtMs = Date.now();+ mockGetUserById = jest.fn(async () => ({ credentialsChangedAt: new Date(issuedAtMs - 1000) }));+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ {+ method: 'GET',+ baseUrl: '/api/convos',+ path: '/',+ headers: {+ authorization: `Bearer ${jwt.sign({ id: 'user-123', issuedAtMs }, jwtSecret)}`,+ },+ },+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);+ await flushPolicy();++ expect(res.status).toHaveBeenCalledWith(403);+ expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ tempToken: 'setup-token' }));+ expect(next).not.toHaveBeenCalled();+ });++ it('withdraws the setup token for a bearer that carries no datable claim', async () => {+ isTwoFactorEnrollmentRequired.mockReturnValue(true);+ mockGetUserById = jest.fn(async () => ({ credentialsChangedAt: new Date() }));+ const req = mockReq(+ { id: 'user-123', provider: 'local', twoFactorEnabled: false },+ { method: 'GET', baseUrl: '/api/convos', path: '/', headers: {} },+ );+ const res = mockRes();+ const next = jest.fn();++ requireJwtAuth(req, res, next);+ await flushPolicy();++ expect(res.status).toHaveBeenCalledWith(401);+ expect(next).not.toHaveBeenCalled();+ });+it('refreshes CloudFront auth cookies inside the request context', () => {let observedContext;maybeRefreshCloudFrontAuthCookiesMiddleware.mockImplementationOnce(diff --git a/api/server/middleware/blockRetiredSetupToken.js b/api/server/middleware/blockRetiredSetupToken.jsnew file mode 100644index 0000000000..51005f4ba5--- /dev/null+++ b/api/server/middleware/blockRetiredSetupToken.js@@ -0,0 +1,4 @@+const { createBlockRetiredSetupToken } = require('@librechat/api');+const { getUserById } = require('~/models');++module.exports = createBlockRetiredSetupToken({ getUserById });diff --git a/api/server/middleware/index.js b/api/server/middleware/index.jsindex 852b23b7f6..774ee44a2b 100644--- a/api/server/middleware/index.js+++ b/api/server/middleware/index.js@@ -1,5 +1,8 @@+const blockRetiredSetupToken = require('./blockRetiredSetupToken');const validatePasswordReset = require('./validatePasswordReset');const setTwoFactorTempUser = require('./setTwoFactorTempUser');+const { setTwoFactorAcknowledgementTempUser, setTwoFactorFinalizationTempUser } =+ setTwoFactorTempUser;const validateRegistration = require('./validateRegistration');const buildEndpointOption = require('./buildEndpointOption');const validateEmailLogin = require('./validateEmailLogin');@@ -50,6 +53,9 @@ module.exports = {requireJwtAuth,requireRumProxyAuth,setTwoFactorTempUser,+ setTwoFactorAcknowledgementTempUser,+ setTwoFactorFinalizationTempUser,+ blockRetiredSetupToken,checkInviteUser,requireLdapAuth,requireLocalAuth,diff --git a/api/server/middleware/limiters/index.js b/api/server/middleware/limiters/index.jsindex 45397e9f1d..757afc6018 100644--- a/api/server/middleware/limiters/index.js+++ b/api/server/middleware/limiters/index.js@@ -21,6 +21,8 @@ const passkeyStepUpLimiter = require('./passkeyStepUpLimiter');const verifyEmailSubmissionLimiter = require('./verifyEmailSubmissionLimiter');const resetPasswordSubmissionLimiter = require('./resetPasswordSubmissionLimiter');+const { twoFactorSetupLimiter } = twoFactorTempLimiter;+module.exports = {...uploadLimiters,...importLimiters,@@ -43,4 +45,5 @@ module.exports = {verifyEmailSubmissionLimiter,resetPasswordSubmissionLimiter,twoFactorTempLimiter,+ twoFactorSetupLimiter,};diff --git a/api/server/middleware/limiters/twoFactorTempLimiter.js b/api/server/middleware/limiters/twoFactorTempLimiter.jsindex 97d0861af6..ffbe1328be 100644--- a/api/server/middleware/limiters/twoFactorTempLimiter.js+++ b/api/server/middleware/limiters/twoFactorTempLimiter.js@@ -1,101 +1,12 @@-const jwt = require('jsonwebtoken');-const { createHash } = require('crypto');-const rateLimit = require('express-rate-limit');-const { ViolationTypes } = require('librechat-data-provider');-const { limiterCache, removePorts } = require('@librechat/api');+const { createTwoFactorLimiters, limiterCache, removePorts } = require('@librechat/api');const { logViolation } = require('~/cache');-const {- LOGIN_WINDOW = 5,- LOGIN_MAX = 7,- LOGIN_VIOLATION_SCORE,- TWO_FACTOR_TEMP_WINDOW = LOGIN_WINDOW,- TWO_FACTOR_TEMP_MAX = LOGIN_MAX,- TWO_FACTOR_TEMP_VIOLATION_SCORE,-} = process.env;-const windowMs = TWO_FACTOR_TEMP_WINDOW * 60 * 1000;-const max = TWO_FACTOR_TEMP_MAX;-const score = TWO_FACTOR_TEMP_VIOLATION_SCORE ?? LOGIN_VIOLATION_SCORE;-const windowInMinutes = windowMs / 60000;-const message = `Too many verification attempts, please try again after ${windowInMinutes} minutes.`;--const hashLimiterKey = (value) => createHash('sha256').update(value).digest('hex');--const getUserLimiterKey = (req) => {- const userId = req.user?.id ?? req.user?._id;- if (userId) {- return `user:${userId.toString()}`;- }-- const tempToken = req.body?.tempToken;- if (typeof tempToken === 'string' && tempToken) {- return `temp:${hashLimiterKey(tempToken)}`;- }-- const ip = removePorts(req);- return ip ? `ip:${ip}` : 'ip:unknown';-};--const getTempTokenUserId = (tempToken) => {- if (!tempToken) {- return null;- }-- try {- const payload = jwt.verify(tempToken, process.env.JWT_SECRET);- return payload?.userId ?? null;- } catch {- return null;- }-};--const createHandler = (limiter) => async (req, res) => {- const type = ViolationTypes.LOGINS;- const errorMessage = {- type,- max,- limiter,- windowInMinutes,- };-- const userId = getTempTokenUserId(req.body?.tempToken);- if (userId && !req.user) {- req.user = { id: userId };- } else if (userId && !req.user.id && !req.user._id) {- req.user.id = userId;- }-- await logViolation(req, res, type, errorMessage, score);- return res.status(429).json({ message });-};--const ipLimiterOptions = {- windowMs,- max,- handler: createHandler('ip'),- keyGenerator: removePorts,- store: limiterCache('two_factor_temp_limiter'),-};--const userLimiterOptions = {- windowMs,- max,- handler: createHandler('user'),- keyGenerator: getUserLimiterKey,- store: limiterCache('two_factor_temp_user_limiter'),-};--const twoFactorTempIpLimiter = rateLimit(ipLimiterOptions);-const twoFactorTempUserLimiter = rateLimit(userLimiterOptions);--const twoFactorTempLimiter = (req, res, next) => {- twoFactorTempIpLimiter(req, res, (err) => {- if (err) {- return next(err);- }-- return twoFactorTempUserLimiter(req, res, next);- });-};+const { twoFactorTempLimiter, twoFactorSetupLimiter } = createTwoFactorLimiters({+ env: process.env,+ limiterCache,+ removePorts,+ logViolation,+});module.exports = twoFactorTempLimiter;+module.exports.twoFactorSetupLimiter = twoFactorSetupLimiter;diff --git a/api/server/middleware/limiters/twoFactorTempLimiter.test.js b/api/server/middleware/limiters/twoFactorTempLimiter.test.jsindex 37b06c7fdb..da2965c2c5 100644--- a/api/server/middleware/limiters/twoFactorTempLimiter.test.js+++ b/api/server/middleware/limiters/twoFactorTempLimiter.test.js@@ -1,25 +1,30 @@const jwt = require('jsonwebtoken');const express = require('express');const request = require('supertest');+const { createTwoFactorLimiters, createTwoFactorTempUser } = jest.requireActual('@librechat/api');const originalEnv = process.env;const jwtSecret = 'test-two-factor-secret';-const createToken = (userId) =>- jwt.sign({ userId, twoFAPending: true }, jwtSecret, { expiresIn: '5m' });+const createToken = (userId, purpose = 'login_2fa_challenge') =>+ jwt.sign({ userId, purpose }, jwtSecret, { expiresIn: '5m' });-const createApp = () => {+const createApp = (max = '2', setupMax = '2') => {jest.resetModules();process.env = {...originalEnv,JWT_SECRET: jwtSecret,LOGIN_MAX: '2',LOGIN_WINDOW: '5',- TWO_FACTOR_TEMP_MAX: '2',+ TWO_FACTOR_TEMP_MAX: max,TWO_FACTOR_TEMP_WINDOW: '5',+ TWO_FACTOR_SETUP_MAX: setupMax,+ TWO_FACTOR_SETUP_WINDOW: '5',};jest.doMock('@librechat/api', () => ({+ createTwoFactorLimiters,+ createTwoFactorTempUser,limiterCache: jest.fn(() => undefined),removePorts: (req) => req?.['ip'],}));@@ -28,7 +33,10 @@ const createApp = () => {}));const setTwoFactorTempUser = require('../setTwoFactorTempUser');+ const { setTwoFactorAcknowledgementTempUser, setTwoFactorFinalizationTempUser } =+ setTwoFactorTempUser;const twoFactorTempLimiter = require('./twoFactorTempLimiter');+ const { twoFactorSetupLimiter } = twoFactorTempLimiter;const { logViolation } = require('~/cache');const app = express();@@ -37,6 +45,28 @@ const createApp = () => {app.post('/verify', setTwoFactorTempUser, twoFactorTempLimiter, (req, res) =>res.status(204).end(),);+ app.post('/finalize', setTwoFactorFinalizationTempUser, twoFactorTempLimiter, (req, res) =>+ res.status(204).end(),+ );+ app.post('/acknowledge', setTwoFactorAcknowledgementTempUser, twoFactorTempLimiter, (req, res) =>+ res.status(204).end(),+ );+ /** Mirrors the production split: code checks on one quota, enrollment transitions on the other. */+ app.post('/setup', setTwoFactorTempUser, twoFactorSetupLimiter, (req, res) =>+ res.status(204).end(),+ );+ app.post(+ '/setup/acknowledge',+ setTwoFactorAcknowledgementTempUser,+ twoFactorSetupLimiter,+ (req, res) => res.status(204).end(),+ );+ app.post('/setup/confirm', setTwoFactorTempUser, twoFactorTempLimiter, (req, res) =>+ res.status(204).end(),+ );+ app.post('/setup/finalize', setTwoFactorFinalizationTempUser, twoFactorSetupLimiter, (req, res) =>+ res.status(204).end(),+ );return { app, logViolation };};@@ -81,7 +111,7 @@ describe('twoFactorTempLimiter', () => {});});- it('keeps the existing source IP limit before the user limit', async () => {+ it('keeps the source IP limit across valid challenge tokens for different users', async () => {const { app, logViolation } = createApp();await request(app)@@ -108,4 +138,198 @@ describe('twoFactorTempLimiter', () => {windowInMinutes: 5,});});++ it('does not charge enrollment transitions against the shared code-attempt IP quota', async () => {+ const { app, logViolation } = createApp('7', '20');+ const sourceIp = '198.51.100.10';++ for (const userId of ['user-a', 'user-b']) {+ const setupToken = createToken(userId, 'required_2fa_setup');+ const acknowledgementToken = createToken(userId, 'required_2fa_acknowledgement');+ const finalizationToken = createToken(userId, 'required_2fa_finalization');++ await request(app)+ .post('/setup')+ .set('X-Forwarded-For', sourceIp)+ .send({ tempToken: setupToken })+ .expect(204);+ await request(app)+ .post('/setup/confirm')+ .set('X-Forwarded-For', sourceIp)+ .send({ tempToken: setupToken, token: '000000' })+ .expect(204);+ await request(app)+ .post('/setup/acknowledge')+ .set('X-Forwarded-For', sourceIp)+ .send({ acknowledgementToken })+ .expect(204);+ await request(app)+ .post('/setup/finalize')+ .set('X-Forwarded-For', sourceIp)+ .send({ finalizationToken })+ .expect(204);+ }++ expect(logViolation).not.toHaveBeenCalled();+ });++ it.each([+ ['login challenge', 'tempToken', 'login_2fa_challenge', '/verify'],+ ['required setup', 'tempToken', 'required_2fa_setup', '/verify'],+ [+ 'required acknowledgement',+ 'acknowledgementToken',+ 'required_2fa_acknowledgement',+ '/acknowledge',+ ],+ ['required finalization', 'finalizationToken', 'required_2fa_finalization', '/finalize'],+ ])('applies the same per-user limit to a %s token', async (_name, field, purpose, route) => {+ const { app, logViolation } = createApp();+ const token = createToken('user-shared', purpose);++ await request(app)+ .post(route)+ .set('X-Forwarded-For', '203.0.113.10')+ .send({ [field]: token })+ .expect(204);+ await request(app)+ .post(route)+ .set('X-Forwarded-For', '203.0.113.11')+ .send({ [field]: token })+ .expect(204);+ await request(app)+ .post(route)+ .set('X-Forwarded-For', '203.0.113.12')+ .send({ [field]: token })+ .expect(429);++ expect(logViolation.mock.calls[0][0].user).toEqual({ id: 'user-shared' });+ });++ it('binds finalization limiting to the finalization token when both fields are present', async () => {+ const { app, logViolation } = createApp();+ const finalizationToken = createToken('finalization-user', 'required_2fa_finalization');++ for (let attempt = 0; attempt < 2; attempt++) {+ await request(app)+ .post('/finalize')+ .set('X-Forwarded-For', `203.0.113.${20 + attempt}`)+ .send({+ tempToken: createToken(`decoy-${attempt}`),+ finalizationToken,+ })+ .expect(204);+ }++ await request(app)+ .post('/finalize')+ .set('X-Forwarded-For', '203.0.113.22')+ .send({ tempToken: createToken('decoy-2'), finalizationToken })+ .expect(429);++ expect(logViolation.mock.calls[0][0].user).toEqual({ id: 'finalization-user' });+ });++ /**+ * Sharing one quota let a handful of wrong codes strand a user who already held their backup+ * codes: confirmation succeeded, then finalization was refused and nothing was ever promoted.+ */+ it('keeps exhausted code attempts from blocking enrollment transitions', async () => {+ const { app, logViolation } = createApp();+ const tempToken = createToken('split-user', 'required_2fa_setup');+ const finalizationToken = createToken('split-user', 'required_2fa_finalization');++ await request(app)+ .post('/setup/confirm')+ .set('X-Forwarded-For', '203.0.113.40')+ .send({ tempToken, token: '000000' })+ .expect(204);+ await request(app)+ .post('/setup/confirm')+ .set('X-Forwarded-For', '203.0.113.41')+ .send({ tempToken, token: '000001' })+ .expect(204);+ await request(app)+ .post('/setup/confirm')+ .set('X-Forwarded-For', '203.0.113.42')+ .send({ tempToken, token: '000002' })+ .expect(429);++ const finalized = await request(app)+ .post('/setup/finalize')+ .set('X-Forwarded-For', '203.0.113.43')+ .send({ finalizationToken })+ .expect(204);++ expect(finalized.status).toBe(204);+ /** Only the exhausted code attempt was a violation; finalization drew on its own budget. */+ expect(logViolation).toHaveBeenCalledTimes(1);+ expect(logViolation.mock.calls[0][3]).toMatchObject({ limiter: 'user', max: '2' });+ });++ it.each([+ ['acknowledge', 'acknowledgementToken'],+ ['finalize', 'finalizationToken'],+ ])(+ 'keeps invalid %s credentials in one bucket despite rotating decoys and IPs',+ async (route, field) => {+ const { app, logViolation } = createApp();+ for (let attempt = 0; attempt < 3; attempt++) {+ await request(app)+ .post(`/${route}`)+ .set('X-Forwarded-For', `203.0.113.${70 + attempt}`)+ .send({ tempToken: `decoy-${attempt}`, [field]: 'invalid-enrollment-token' })+ .expect(attempt < 2 ? 204 : 429);+ }+ expect(logViolation.mock.calls[0][3]).toMatchObject({ limiter: 'user' });+ },+ );++ it('still bounds the enrollment transition quota on its own budget', async () => {+ const { app, logViolation } = createApp('7', '2');+ const finalizationToken = createToken('transition-user', 'required_2fa_finalization');++ for (let attempt = 0; attempt < 2; attempt++) {+ await request(app)+ .post('/setup/finalize')+ .set('X-Forwarded-For', `203.0.113.${50 + attempt}`)+ .send({ finalizationToken })+ .expect(204);+ }++ const response = await request(app)+ .post('/setup/finalize')+ .set('X-Forwarded-For', '203.0.113.52')+ .send({ finalizationToken })+ .expect(429);++ expect(response.body).toEqual({+ message: 'Too many two-factor setup requests, please try again after 5 minutes.',+ });+ expect(logViolation.mock.calls[0][0].user).toEqual({ id: 'transition-user' });+ });++ it('binds acknowledgement limiting to the acknowledgement token when a decoy setup token is present', async () => {+ const { app, logViolation } = createApp();+ const acknowledgementToken = createToken(+ 'acknowledgement-user',+ 'required_2fa_acknowledgement',+ );++ for (let attempt = 0; attempt < 2; attempt++) {+ await request(app)+ .post('/acknowledge')+ .set('X-Forwarded-For', `203.0.113.${30 + attempt}`)+ .send({ tempToken: createToken(`decoy-${attempt}`), acknowledgementToken })+ .expect(204);+ }++ await request(app)+ .post('/acknowledge')+ .set('X-Forwarded-For', '203.0.113.32')+ .send({ tempToken: createToken('decoy-2'), acknowledgementToken })+ .expect(429);++ expect(logViolation.mock.calls[0][0].user).toEqual({ id: 'acknowledgement-user' });+ });});diff --git a/api/server/middleware/optionalJwtAuth.js b/api/server/middleware/optionalJwtAuth.jsindex 853579415e..6dcf82e948 100644--- a/api/server/middleware/optionalJwtAuth.js+++ b/api/server/middleware/optionalJwtAuth.js@@ -1,6 +1,12 @@const cookies = require('cookie');const passport = require('passport');-const { isEnabled, tenantContextMiddleware } = require('@librechat/api');+const {+ isEnabled,+ clearCloudFrontCookies,+ continueAfterOptionalAuth,+ tenantContextMiddleware,+ isTwoFactorEnrollmentRequired,+} = require('@librechat/api');const hasPassportStrategy = (strategy) =>typeof passport._strategy === 'function' && passport._strategy(strategy) != null;@@ -20,9 +26,15 @@ const optionalJwtAuth = (req, res, next) => {return next(err);}if (user) {- req.user = user;- req.authStrategy = useOpenIdJwt ? 'openidJwt' : 'jwt';- return tenantContextMiddleware(req, res, next);+ return continueAfterOptionalAuth(+ req,+ res,+ next,+ user,+ useOpenIdJwt ? 'openidJwt' : 'jwt',+ tenantContextMiddleware,+ { clearCloudFrontCookies, enrollmentRequired: isTwoFactorEnrollmentRequired },+ );}next();};diff --git a/api/server/middleware/optionalJwtAuth.spec.js b/api/server/middleware/optionalJwtAuth.spec.jsnew file mode 100644index 0000000000..2e8e755459--- /dev/null+++ b/api/server/middleware/optionalJwtAuth.spec.js@@ -0,0 +1,73 @@+const mockAuthenticate = jest.fn();+const mockTenantContextMiddleware = jest.fn((_req, _res, next) => next());+const mockIsTwoFactorEnrollmentRequired = jest.fn(() => false);+const mockClearCloudFrontCookies = jest.fn();++jest.mock('passport', () => ({+ _strategy: jest.fn(() => undefined),+ authenticate: (...args) => mockAuthenticate(...args),+}));++jest.mock('@librechat/api', () => ({+ continueAfterOptionalAuth: jest.requireActual('@librechat/api').continueAfterOptionalAuth,+ isEnabled: jest.fn(() => false),+ clearCloudFrontCookies: (...args) => mockClearCloudFrontCookies(...args),+ isTwoFactorEnrollmentRequired: (...args) => mockIsTwoFactorEnrollmentRequired(...args),+ tenantContextMiddleware: (...args) => mockTenantContextMiddleware(...args),+}));++const optionalJwtAuth = require('./optionalJwtAuth');++const run = (user) => {+ const req = { headers: {}, _mockUser: user };+ const res = {};+ const next = jest.fn();+ optionalJwtAuth(req, res, next);+ return { req, res, next };+};++describe('optionalJwtAuth', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ mockIsTwoFactorEnrollmentRequired.mockReturnValue(false);+ mockAuthenticate.mockImplementation((_strategy, _options, callback) => {+ return (req) => callback(null, req._mockUser ?? false);+ });+ });++ it('establishes authenticated context when enrollment is not required', () => {+ const user = { id: 'viewer-1', provider: 'local', twoFactorEnabled: true };++ const { req, next } = run(user);++ expect(req.user).toBe(user);+ expect(req.authStrategy).toBe('jwt');+ expect(mockTenantContextMiddleware).toHaveBeenCalledTimes(1);+ expect(next).toHaveBeenCalledTimes(1);+ });++ it('treats a viewer with incomplete required enrollment as unauthenticated', () => {+ const user = { id: 'viewer-required', provider: 'local', twoFactorEnabled: false };+ mockIsTwoFactorEnrollmentRequired.mockReturnValue(true);++ const { req, res, next } = run(user);++ expect(req.user).toBeUndefined();+ expect(req.authStrategy).toBeUndefined();+ expect(mockClearCloudFrontCookies).toHaveBeenCalledWith(res, {+ userId: 'viewer-required',+ tenantId: undefined,+ storageRegion: undefined,+ });+ expect(mockTenantContextMiddleware).not.toHaveBeenCalled();+ expect(next).toHaveBeenCalledTimes(1);+ });++ it('continues anonymously when authentication does not resolve a user', () => {+ const { req, next } = run(undefined);++ expect(req.user).toBeUndefined();+ expect(mockTenantContextMiddleware).not.toHaveBeenCalled();+ expect(next).toHaveBeenCalledTimes(1);+ });+});diff --git a/api/server/middleware/optionalShareFileAuth.js b/api/server/middleware/optionalShareFileAuth.jsindex bebf087d20..6d17573af8 100644--- a/api/server/middleware/optionalShareFileAuth.js+++ b/api/server/middleware/optionalShareFileAuth.js@@ -1,88 +1,22 @@const cookie = require('cookie');-const jwt = require('jsonwebtoken');-const { isEnabled } = require('@librechat/api');const { logger, runAsSystem } = require('@librechat/data-schemas');-const { SystemRoles } = require('librechat-data-provider');+const {+ createOptionalShareFileAuth,+ clearCloudFrontCookies,+ isTwoFactorEnrollmentRequired,+ isTokenRetired,+ isEnabled,+} = require('@librechat/api');const { getUserById, findSession } = require('~/models');-const verifySignedUserId = (token) => {- try {- const payload = jwt.verify(token, process.env.JWT_REFRESH_SECRET);- return typeof payload?.id === 'string' ? payload.id : null;- } catch {- return null;- }-};--const getRefreshTokenUserId = async (token) => {- const userId = verifySignedUserId(token);- if (!userId) {- return null;- }-- const session = await runAsSystem(() => findSession({ userId, refreshToken: token }));- return session ? userId : null;-};--const getOpenIdUserId = (parsed, req) => {- if (parsed.token_provider !== 'openid' || !isEnabled(process.env.OPENID_REUSE_TOKENS)) {- return null;- }-- const sessionRefreshToken = req.session?.openidTokens?.refreshToken;- if (!parsed.refreshToken || parsed.refreshToken !== sessionRefreshToken) {- return null;- }-- return verifySignedUserId(parsed.openid_user_id);-};--/**- * Fallback auth for share file routes that are hit by `<img>`/anchor requests,- * which can't carry the bearer access token. Resolves the viewer from the- * `refreshToken` cookie (or an active OpenID session plus signed `openid_user_id`- * cookie) so non-public shared links can authorize the viewer's ACL. Never- * blocks: on any failure it leaves `req.user` unset and lets- * `canAccessSharedLink` decide (public access, 401, or 403).- */-const optionalShareFileAuth = async (req, res, next) => {- if (req.user) {- return next();- }-- try {- const cookieHeader = req.headers.cookie;- if (!cookieHeader) {- return next();- }-- const parsed = cookie.parse(cookieHeader);- const userId =- getOpenIdUserId(parsed, req) ||- (parsed.refreshToken ? await getRefreshTokenUserId(parsed.refreshToken) : null);- if (!userId) {- return next();- }-- // Resolve in system context: this runs before canAccessSharedLink establishes- // the share tenant, so under strict tenant isolation a tenant-scoped User- // query would otherwise throw. The viewer's id comes from verified, active- // cookie auth; the share's tenant-scoped ACL check still gates access.- const user = await runAsSystem(() =>- getUserById(userId, '-password -__v -totpSecret -backupCodes'),- );- if (user) {- user.id = user._id.toString();- if (!user.role) {- user.role = SystemRoles.USER;- }- req.user = user;- }- } catch (error) {- logger.warn('[optionalShareFileAuth] cookie auth failed:', error?.message);- }-- return next();-};--module.exports = optionalShareFileAuth;+module.exports = createOptionalShareFileAuth({+ parseCookie: cookie.parse,+ getUserById,+ findSession,+ runAsSystem,+ clearCloudFrontCookies,+ enrollmentRequired: isTwoFactorEnrollmentRequired,+ tokenRetired: isTokenRetired,+ enabled: isEnabled,+ warn: (...args) => logger.warn(...args),+});diff --git a/api/server/middleware/optionalShareFileAuth.spec.js b/api/server/middleware/optionalShareFileAuth.spec.jsindex f68a356abf..f5580ee28f 100644--- a/api/server/middleware/optionalShareFileAuth.spec.js+++ b/api/server/middleware/optionalShareFileAuth.spec.js@@ -2,23 +2,23 @@ const mockVerify = jest.fn();const mockGetUserById = jest.fn();const mockFindSession = jest.fn();const mockRunAsSystem = jest.fn((fn) => fn());+const mockIsTwoFactorEnrollmentRequired = jest.fn(() => false);+const mockIsTokenRetired = jest.fn(() => false);+const mockClearCloudFrontCookies = jest.fn();jest.mock('jsonwebtoken', () => ({ verify: (...args) => mockVerify(...args) }));-/** Installed packages need real module IDs when Jest reuses a resolver across suites. */-jest.mock('@librechat/api', () => ({ isEnabled: (v) => v === 'true' || v === true }), {- virtual: false,-});-jest.mock(- '@librechat/data-schemas',- () => ({- logger: { warn: jest.fn(), error: jest.fn() },- runAsSystem: (...args) => mockRunAsSystem(...args),- }),- { virtual: false },-);-jest.mock('librechat-data-provider', () => ({ SystemRoles: { USER: 'USER' } }), {- virtual: false,-});+jest.mock('@librechat/api', () => ({+ createOptionalShareFileAuth: jest.requireActual('@librechat/api').createOptionalShareFileAuth,+ isEnabled: (v) => v === 'true' || v === true,+ clearCloudFrontCookies: (...args) => mockClearCloudFrontCookies(...args),+ isTwoFactorEnrollmentRequired: (...args) => mockIsTwoFactorEnrollmentRequired(...args),+ isTokenRetired: (...args) => mockIsTokenRetired(...args),+}));+jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),+ logger: { warn: jest.fn(), error: jest.fn() },+ runAsSystem: (...args) => mockRunAsSystem(...args),+}));jest.mock('~/models', () => ({getUserById: (...args) => mockGetUserById(...args),findSession: (...args) => mockFindSession(...args),@@ -35,6 +35,8 @@ const run = async (req) => {describe('optionalShareFileAuth', () => {beforeEach(() => {jest.clearAllMocks();+ mockIsTwoFactorEnrollmentRequired.mockReturnValue(false);+ mockIsTokenRetired.mockReturnValue(false);process.env.JWT_REFRESH_SECRET = 'test-secret';});@@ -47,6 +49,28 @@ describe('optionalShareFileAuth', () => {expect(mockFindSession).not.toHaveBeenCalled();});+ it('removes an existing viewer when required enrollment is incomplete', async () => {+ mockIsTwoFactorEnrollmentRequired.mockReturnValue(true);+ const req = {+ user: { id: 'u1', provider: 'local', twoFactorEnabled: false },+ authStrategy: 'jwt',+ headers: { cookie: 'refreshToken=x' },+ };++ const next = await run(req);++ expect(next).toHaveBeenCalledTimes(1);+ expect(req.user).toBeUndefined();+ expect(req.authStrategy).toBeUndefined();+ expect(mockClearCloudFrontCookies).toHaveBeenCalledWith(expect.any(Object), {+ userId: 'u1',+ tenantId: undefined,+ storageRegion: undefined,+ });+ expect(mockGetUserById).not.toHaveBeenCalled();+ expect(mockFindSession).not.toHaveBeenCalled();+ });+it('resolves the viewer from a valid refreshToken cookie with a live session', async () => {mockVerify.mockReturnValue({ id: 'viewer-1' });mockFindSession.mockResolvedValue({ _id: 'session-1' });@@ -60,6 +84,98 @@ describe('optionalShareFileAuth', () => {expect(req.user).toMatchObject({ id: 'viewer-1', role: 'USER' });});+ it('does not restore a cookie viewer when required enrollment is incomplete', async () => {+ mockVerify.mockReturnValue({ id: 'viewer-required' });+ mockFindSession.mockResolvedValue({ _id: 'session-required' });+ mockGetUserById.mockResolvedValue({+ _id: 'viewer-required',+ role: 'USER',+ provider: 'local',+ twoFactorEnabled: false,+ });+ mockIsTwoFactorEnrollmentRequired.mockReturnValue(true);+ const req = { headers: { cookie: 'refreshToken=good.jwt' } };++ const next = await run(req);++ expect(next).toHaveBeenCalledTimes(1);+ expect(req.user).toBeUndefined();+ expect(mockClearCloudFrontCookies).toHaveBeenCalledWith(expect.any(Object), {+ userId: 'viewer-required',+ tenantId: undefined,+ storageRegion: undefined,+ });+ expect(mockGetUserById).toHaveBeenCalledTimes(1);+ });++ it('does not restore a cookie viewer minted before two-factor enrollment', async () => {+ mockVerify.mockReturnValue({ id: 'viewer-stale', iat: 1000 });+ mockFindSession.mockResolvedValue({ _id: 'session-stale' });+ mockGetUserById.mockResolvedValue({+ _id: 'viewer-stale',+ role: 'USER',+ provider: 'local',+ twoFactorEnabled: true,+ twoFactorEnrolledAt: new Date(2000 * 1000),+ });+ mockIsTokenRetired.mockReturnValue(true);+ const req = { headers: { cookie: 'refreshToken=stale.jwt' } };++ const next = await run(req);++ expect(next).toHaveBeenCalledTimes(1);+ expect(req.user).toBeUndefined();+ expect(mockClearCloudFrontCookies).toHaveBeenCalledWith(expect.any(Object), {+ userId: 'viewer-stale',+ tenantId: undefined,+ storageRegion: undefined,+ });+ });++ it('dates the cookie by its own mint stamps rather than discarding them', async () => {+ const enrolledAt = new Date(2000 * 1000);+ mockVerify.mockReturnValue({ id: 'viewer-dated', iat: 1234, issuedAtMs: 1234_500 });+ mockFindSession.mockResolvedValue({ _id: 'session-dated' });+ mockGetUserById.mockResolvedValue({+ _id: 'viewer-dated',+ role: 'USER',+ twoFactorEnrolledAt: enrolledAt,+ });+ const req = { headers: { cookie: 'refreshToken=dated.jwt' } };++ await run(req);++ expect(mockIsTokenRetired).toHaveBeenCalledWith(+ expect.objectContaining({ issuedAt: 1234, issuedAtMs: 1234_500 }),+ expect.objectContaining({ twoFactorEnrolledAt: enrolledAt }),+ );+ });++ it('dates an OpenID cookie viewer by its own mint stamps too', async () => {+ process.env.OPENID_REUSE_TOKENS = 'true';+ const enrolledAt = new Date(2000 * 1000);+ mockVerify.mockReturnValue({ id: 'viewer-openid', iat: 4321, issuedAtMs: 4321_500 });+ mockGetUserById.mockResolvedValue({+ _id: 'viewer-openid',+ role: 'USER',+ twoFactorEnrolledAt: enrolledAt,+ });+ const req = {+ headers: {+ cookie: 'refreshToken=live.jwt; token_provider=openid; openid_user_id=signed.jwt',+ },+ session: { openidTokens: { refreshToken: 'live.jwt' } },+ };++ await run(req);++ expect(mockIsTokenRetired).toHaveBeenCalledWith(+ expect.objectContaining({ issuedAt: 4321, issuedAtMs: 4321_500 }),+ expect.objectContaining({ twoFactorEnrolledAt: enrolledAt }),+ );+ delete process.env.OPENID_REUSE_TOKENS;+ });+it('defaults the role to USER when the record has none', async () => {mockVerify.mockReturnValue({ id: 'viewer-2' });mockFindSession.mockResolvedValue({ _id: 'session-2' });diff --git a/api/server/middleware/requireJwtAuth.js b/api/server/middleware/requireJwtAuth.jsindex 74232012f2..ca01269675 100644--- a/api/server/middleware/requireJwtAuth.js+++ b/api/server/middleware/requireJwtAuth.js@@ -3,13 +3,19 @@ const passport = require('passport');const { logger } = require('@librechat/data-schemas');const {isEnabled,+ isTokenRetired,+ createRequiredTwoFactorGate,+ clearCloudFrontCookies,tenantContextMiddleware,getAuthFailureReasonCategory,buildSafeAuthLogContext,maybeRefreshCloudFrontAuthCookiesMiddleware,recordRumProxyRequest,getValidOpenIdReuseUserId,+ generateTwoFactorSetupToken,+ isTwoFactorEnrollmentRequired,} = require('@librechat/api');+const { getUserById } = require('~/models');const hasPassportStrategy = (strategy) =>typeof passport._strategy === 'function' && passport._strategy(strategy) != null;@@ -65,6 +71,15 @@ const getRumProxyEndpoint = (req) => {const isOpenIdReuseUser = (strategy, user, openIdReuseUserId) =>strategy !== 'openidJwt' || getAuthenticatedUserId(user) === openIdReuseUserId;+const requiredTwoFactorGate = createRequiredTwoFactorGate({+ clearCloudFrontCookies,+ getUserById,+ warn: (message) => logger.warn(message),+ generateSetupToken: generateTwoFactorSetupToken,+ enrollmentRequired: isTwoFactorEnrollmentRequired,+ tokenRetired: isTokenRetired,+});+/*** Custom Middleware to handle JWT authentication, with support for OpenID token reuse.* Switches between JWT and OpenID authentication based on cookies and environment settings.@@ -185,11 +200,13 @@ const requireJwtAuth = (req, res, next) => {req.user = user;req.authStrategy = strategy;logFallbackSuccess(strategy);- tenantContextMiddleware(req, res, (tenantErr) => {- if (tenantErr) {- return next(tenantErr);- }- refreshCloudFrontCookies(req, res, next);+ return requiredTwoFactorGate(req, res, next, () => {+ tenantContextMiddleware(req, res, (tenantErr) => {+ if (tenantErr) {+ return next(tenantErr);+ }+ refreshCloudFrontCookies(req, res, next);+ });});})(req, res, next);};diff --git a/api/server/middleware/setTwoFactorTempUser.js b/api/server/middleware/setTwoFactorTempUser.jsindex facbbcba9a..06b1156fc3 100644--- a/api/server/middleware/setTwoFactorTempUser.js+++ b/api/server/middleware/setTwoFactorTempUser.js@@ -1,25 +1,12 @@-const jwt = require('jsonwebtoken');--const setTwoFactorTempUser = (req, _res, next) => {- if (req.user?.id || req.user?._id) {- return next();- }-- const { tempToken } = req.body ?? {};- if (!tempToken) {- return next();- }-- try {- const payload = jwt.verify(tempToken, process.env.JWT_SECRET);- if (payload?.userId) {- req.user = { id: payload.userId };- }- } catch {- return next();- }-- return next();-};+const { createTwoFactorTempUser } = require('@librechat/api');+const setTwoFactorTempUser = createTwoFactorTempUser('tempToken', process.env);module.exports = setTwoFactorTempUser;+module.exports.setTwoFactorAcknowledgementTempUser = createTwoFactorTempUser(+ 'acknowledgementToken',+ process.env,+);+module.exports.setTwoFactorFinalizationTempUser = createTwoFactorTempUser(+ 'finalizationToken',+ process.env,+);diff --git a/api/server/routes/__tests__/config.spec.js b/api/server/routes/__tests__/config.spec.jsindex 557cdecce9..c6eb406b35 100644--- a/api/server/routes/__tests__/config.spec.js+++ b/api/server/routes/__tests__/config.spec.js@@ -87,6 +87,7 @@ afterEach(() => {delete process.env.ALLOW_REGISTRATION;delete process.env.ALLOW_SOCIAL_LOGIN;delete process.env.ALLOW_PASSWORD_RESET;+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;delete process.env.DOMAIN_SERVER;delete process.env.GOOGLE_CLIENT_ID;delete process.env.GOOGLE_CLIENT_SECRET;@@ -316,6 +317,16 @@ describe('GET /api/config', () => {expect(response.body).toHaveProperty('serverDomain');});+ it('should expose the effective two-factor enforcement policy', async () => {+ mockGetAppConfig.mockResolvedValue(baseAppConfig);+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const app = createApp(null);++ const response = await request(app).get('/api/config');++ expect(response.body.twoFactorAuthenticationRequired).toBe(true);+ });+it('should omit CloudFront cookie refresh from unauthenticated response (#12688)', async () => {mockGetAppConfig.mockResolvedValue(baseAppConfig);mockGetCloudFrontConfig.mockReturnValue({diff --git a/api/server/routes/admin/auth.refresh.test.js b/api/server/routes/admin/auth.refresh.test.jsindex c6e0287054..b14bf1312d 100644--- a/api/server/routes/admin/auth.refresh.test.js+++ b/api/server/routes/admin/auth.refresh.test.js@@ -60,8 +60,9 @@ jest.mock('@librechat/api', () => {};});+const mockAdminLoginController = jest.fn((req, res) => res.status(200).end());jest.mock('~/server/controllers/auth/LoginController', () => ({- loginController: jest.fn((req, res) => res.status(200).end()),+ loginController: (...args) => mockAdminLoginController(...args),}));jest.mock('~/server/middleware/roles/capabilities', () => ({@@ -634,6 +635,27 @@ describe('admin local login route', () => {expect(middleware.requireLocalAuth).not.toHaveBeenCalled();});+ it('preserves the additive required-setup response contract for admin clients', async () => {+ mockAdminLoginController.mockImplementationOnce((req, res) =>+ res.status(200).json({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ }),+ );++ const response = await request(app).post('/api/admin/login/local').send({+ email: '[email protected]',+ password: 'password',+ });++ expect(response.body).toEqual({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });+ });+it('stops before local auth when the email login gate rejects the request', async () => {middleware.validateEmailLogin.mockImplementationOnce((req, res) =>res.status(403).json({ message: 'Email login is not allowed.' }),diff --git a/api/server/routes/auth.2fa-ratelimit.test.js b/api/server/routes/auth.2fa-ratelimit.test.jsindex cd496cce33..a6b145a292 100644--- a/api/server/routes/auth.2fa-ratelimit.test.js+++ b/api/server/routes/auth.2fa-ratelimit.test.js@@ -2,9 +2,20 @@ const express = require('express');const request = require('supertest');const mockSetTwoFactorTempUser = jest.fn((req, res, next) => next());+const mockSetTwoFactorAcknowledgementTempUser = jest.fn((req, res, next) => next());+const mockSetTwoFactorFinalizationTempUser = jest.fn((req, res, next) => next());const mockTwoFactorTempLimiter = jest.fn((req, res, next) => next());+const mockTwoFactorSetupLimiter = jest.fn((req, res, next) => next());const mockCheckBan = jest.fn((req, res, next) => next());+const mockRequireTwoFactorSetupToken = jest.fn((req, res, next) => next());+const mockBlockRetiredSetupToken = jest.fn((req, res, next) => next());+const mockRequireTwoFactorSetupAcknowledgementToken = jest.fn((req, res, next) => next());+const mockRequireTwoFactorSetupFinalizationToken = jest.fn((req, res, next) => next());const mockVerify2FAWithTempToken = jest.fn((req, res) => res.status(204).end());+const mockEnable2FA = jest.fn((req, res) => res.status(204).end());+const mockConfirm2FASetupWithTempToken = jest.fn((req, res) => res.status(204).end());+const mockAcknowledge2FASetup = jest.fn((req, res) => res.status(204).end());+const mockFinalize2FASetup = jest.fn((req, res) => res.status(204).end());jest.mock('@librechat/api', () => ({limiterCache: jest.fn(() => undefined),@@ -13,7 +24,13 @@ jest.mock('@librechat/api', () => ({...args,),createSetBalanceConfig: jest.fn(() => (req, res, next) => next()),+ requireTwoFactorSetupToken: (...args) => mockRequireTwoFactorSetupToken(...args),+ requireTwoFactorSetupAcknowledgementToken: (...args) =>+ mockRequireTwoFactorSetupAcknowledgementToken(...args),+ requireTwoFactorSetupFinalizationToken: (...args) =>+ mockRequireTwoFactorSetupFinalizationToken(...args),forceRefreshCloudFrontAuthCookies: jest.fn(),+ blockTwoFactorDisableWhenRequired: jest.fn((req, res, next) => next()),}));jest.mock('~/server/controllers/AuthController', () => ({@@ -25,7 +42,7 @@ jest.mock('~/server/controllers/AuthController', () => ({}));jest.mock('~/server/controllers/TwoFactorController', () => ({- enable2FA: jest.fn((req, res) => res.status(204).end()),+ enable2FA: (...args) => mockEnable2FA(...args),verify2FA: jest.fn((req, res) => res.status(204).end()),confirm2FA: jest.fn((req, res) => res.status(204).end()),disable2FA: jest.fn((req, res) => res.status(204).end()),@@ -34,6 +51,9 @@ jest.mock('~/server/controllers/TwoFactorController', () => ({jest.mock('~/server/controllers/auth/TwoFactorAuthController', () => ({verify2FAWithTempToken: (...args) => mockVerify2FAWithTempToken(...args),+ confirm2FASetupWithTempToken: (...args) => mockConfirm2FASetupWithTempToken(...args),+ acknowledge2FASetup: (...args) => mockAcknowledge2FASetup(...args),+ finalize2FASetup: (...args) => mockFinalize2FASetup(...args),}));jest.mock('~/server/controllers/auth/PasskeyController', () => ({@@ -72,8 +92,13 @@ jest.mock('~/server/middleware', () => {passkeyLimiter: pass,passkeyStepUpLimiter: pass,setTwoFactorTempUser: (...args) => mockSetTwoFactorTempUser(...args),+ setTwoFactorAcknowledgementTempUser: (...args) =>+ mockSetTwoFactorAcknowledgementTempUser(...args),+ setTwoFactorFinalizationTempUser: (...args) => mockSetTwoFactorFinalizationTempUser(...args),twoFactorTempLimiter: (...args) => mockTwoFactorTempLimiter(...args),+ twoFactorSetupLimiter: (...args) => mockTwoFactorSetupLimiter(...args),checkBan: (...args) => mockCheckBan(...args),+ blockRetiredSetupToken: (...args) => mockBlockRetiredSetupToken(...args),validateEmailLogin: pass,requireLocalAuth: pass,requireLdapAuth: pass,@@ -193,15 +218,151 @@ describe('POST /api/auth/2fa/verify-temp rate limiting', () => {beforeEach(() => {jest.clearAllMocks();mockSetTwoFactorTempUser.mockImplementation((req, res, next) => next());+ mockSetTwoFactorAcknowledgementTempUser.mockImplementation((req, res, next) => next());+ mockSetTwoFactorFinalizationTempUser.mockImplementation((req, res, next) => next());mockTwoFactorTempLimiter.mockImplementation((req, res, next) => next());+ mockTwoFactorSetupLimiter.mockImplementation((req, res, next) => next());mockCheckBan.mockImplementation((req, res, next) => next());+ mockRequireTwoFactorSetupToken.mockImplementation((req, res, next) => next());+ mockBlockRetiredSetupToken.mockImplementation((req, res, next) => next());+ mockRequireTwoFactorSetupAcknowledgementToken.mockImplementation((req, res, next) => next());+ mockRequireTwoFactorSetupFinalizationToken.mockImplementation((req, res, next) => next());mockVerify2FAWithTempToken.mockImplementation((req, res) => res.status(204).end());+ mockEnable2FA.mockImplementation((req, res) => res.status(204).end());+ mockConfirm2FASetupWithTempToken.mockImplementation((req, res) => res.status(204).end());+ mockAcknowledge2FASetup.mockImplementation((req, res) => res.status(204).end());+ mockFinalize2FASetup.mockImplementation((req, res) => res.status(204).end());app = express();app.use(express.json());app.use('/api/auth', authRouter);});+ it('protects finalization with limiting, ban checks, and purpose validation', async () => {+ await request(app)+ .post('/api/auth/2fa/setup/finalize')+ .send({ finalizationToken: 'finalization-token' })+ .expect(204);++ expect(mockSetTwoFactorFinalizationTempUser).toHaveBeenCalledTimes(1);+ expect(mockTwoFactorSetupLimiter).toHaveBeenCalledTimes(1);+ /** Redeeming a nonce checks no guessable code, so it must not draw on the code-attempt quota. */+ expect(mockTwoFactorTempLimiter).not.toHaveBeenCalled();+ expect(mockCheckBan).toHaveBeenCalledTimes(1);+ expect(mockRequireTwoFactorSetupFinalizationToken).toHaveBeenCalledTimes(1);+ expect(mockFinalize2FASetup).toHaveBeenCalledTimes(1);+ expect(mockSetTwoFactorFinalizationTempUser.mock.invocationCallOrder[0]).toBeLessThan(+ mockTwoFactorSetupLimiter.mock.invocationCallOrder[0],+ );+ expect(mockTwoFactorSetupLimiter.mock.invocationCallOrder[0]).toBeLessThan(+ mockCheckBan.mock.invocationCallOrder[0],+ );+ expect(mockCheckBan.mock.invocationCallOrder[0]).toBeLessThan(+ mockRequireTwoFactorSetupFinalizationToken.mock.invocationCallOrder[0],+ );+ expect(mockRequireTwoFactorSetupFinalizationToken.mock.invocationCallOrder[0]).toBeLessThan(+ mockFinalize2FASetup.mock.invocationCallOrder[0],+ );+ });++ it('protects acknowledgement with field-specific identity, limiting, ban checks, and purpose validation', async () => {+ await request(app)+ .post('/api/auth/2fa/setup/acknowledge')+ .send({ acknowledgementToken: 'acknowledgement-token' })+ .expect(204);++ expect(mockSetTwoFactorAcknowledgementTempUser).toHaveBeenCalledTimes(1);+ expect(mockTwoFactorSetupLimiter).toHaveBeenCalledTimes(1);+ expect(mockTwoFactorTempLimiter).not.toHaveBeenCalled();+ expect(mockCheckBan).toHaveBeenCalledTimes(1);+ expect(mockRequireTwoFactorSetupAcknowledgementToken).toHaveBeenCalledTimes(1);+ expect(mockAcknowledge2FASetup).toHaveBeenCalledTimes(1);+ expect(mockSetTwoFactorAcknowledgementTempUser.mock.invocationCallOrder[0]).toBeLessThan(+ mockTwoFactorSetupLimiter.mock.invocationCallOrder[0],+ );+ expect(mockTwoFactorSetupLimiter.mock.invocationCallOrder[0]).toBeLessThan(+ mockCheckBan.mock.invocationCallOrder[0],+ );+ expect(mockCheckBan.mock.invocationCallOrder[0]).toBeLessThan(+ mockRequireTwoFactorSetupAcknowledgementToken.mock.invocationCallOrder[0],+ );+ expect(mockRequireTwoFactorSetupAcknowledgementToken.mock.invocationCallOrder[0]).toBeLessThan(+ mockAcknowledge2FASetup.mock.invocationCallOrder[0],+ );+ });++ it('does not finalize after the limiter or ban check rejects the request', async () => {+ mockCheckBan.mockImplementation((req, res) => res.status(403).json({ message: 'Banned' }));++ await request(app)+ .post('/api/auth/2fa/setup/finalize')+ .send({ finalizationToken: 'finalization-token' })+ .expect(403);++ expect(mockRequireTwoFactorSetupFinalizationToken).not.toHaveBeenCalled();+ expect(mockFinalize2FASetup).not.toHaveBeenCalled();+ });++ it.each([+ ['/api/auth/2fa/setup', mockEnable2FA, mockTwoFactorSetupLimiter],+ ['/api/auth/2fa/setup/confirm', mockConfirm2FASetupWithTempToken, mockTwoFactorTempLimiter],+ ])(+ 'protects %s with temp-token limiting and setup validation',+ async (path, controller, limiter) => {+ await request(app).post(path).send({ tempToken: 'temp-token' }).expect(204);++ expect(mockSetTwoFactorTempUser).toHaveBeenCalledTimes(1);+ expect(limiter).toHaveBeenCalledTimes(1);+ expect(mockCheckBan).toHaveBeenCalledTimes(1);+ expect(mockRequireTwoFactorSetupToken).toHaveBeenCalledTimes(1);+ expect(controller).toHaveBeenCalledTimes(1);+ expect(mockSetTwoFactorTempUser.mock.invocationCallOrder[0]).toBeLessThan(+ limiter.mock.invocationCallOrder[0],+ );+ expect(limiter.mock.invocationCallOrder[0]).toBeLessThan(+ mockCheckBan.mock.invocationCallOrder[0],+ );+ expect(mockCheckBan.mock.invocationCallOrder[0]).toBeLessThan(+ mockRequireTwoFactorSetupToken.mock.invocationCallOrder[0],+ );+ expect(mockRequireTwoFactorSetupToken.mock.invocationCallOrder[0]).toBeLessThan(+ controller.mock.invocationCallOrder[0],+ );+ },+ );++ it.each([+ ['/api/auth/2fa/setup', mockEnable2FA],+ ['/api/auth/2fa/setup/confirm', mockConfirm2FASetupWithTempToken],+ ])(+ 'dates the setup token on %s once its signature has been verified',+ async (path, controller) => {+ await request(app).post(path).send({ tempToken: 'temp-token' }).expect(204);++ expect(mockBlockRetiredSetupToken).toHaveBeenCalledTimes(1);+ expect(mockRequireTwoFactorSetupToken.mock.invocationCallOrder[0]).toBeLessThan(+ mockBlockRetiredSetupToken.mock.invocationCallOrder[0],+ );+ expect(mockBlockRetiredSetupToken.mock.invocationCallOrder[0]).toBeLessThan(+ controller.mock.invocationCallOrder[0],+ );+ },+ );++ it.each([['/api/auth/2fa/setup'], ['/api/auth/2fa/setup/confirm']])(+ 'does not stage enrollment on %s when the setup token has been retired',+ async (path) => {+ mockBlockRetiredSetupToken.mockImplementation((req, res) =>+ res.status(401).json({ message: 'Invalid or expired two-factor setup token' }),+ );++ await request(app).post(path).send({ tempToken: 'temp-token' }).expect(401);++ expect(mockEnable2FA).not.toHaveBeenCalled();+ expect(mockConfirm2FASetupWithTempToken).not.toHaveBeenCalled();+ },+ );+it('sets the temp user before limiting, checking bans, and verifying temp 2FA tokens', async () => {await request(app).post('/api/auth/2fa/verify-temp').send({ token: '123456' }).expect(204);diff --git a/api/server/routes/auth.cloudfront.test.js b/api/server/routes/auth.cloudfront.test.jsindex 764cb169aa..84b7e6ddd3 100644--- a/api/server/routes/auth.cloudfront.test.js+++ b/api/server/routes/auth.cloudfront.test.js@@ -7,7 +7,11 @@ jest.mock('@librechat/api', () => ({limiterCache: jest.fn(),createTwoFactorManagementLimiter: jest.fn(() => (req, res, next) => next()),createSetBalanceConfig: jest.fn(() => (req, res, next) => next()),+ requireTwoFactorSetupToken: jest.fn((req, res, next) => next()),+ requireTwoFactorSetupAcknowledgementToken: jest.fn((req, res, next) => next()),+ requireTwoFactorSetupFinalizationToken: jest.fn((req, res, next) => next()),forceRefreshCloudFrontAuthCookies: (...args) => mockForceRefreshCloudFrontAuthCookies(...args),+ blockTwoFactorDisableWhenRequired: jest.fn((req, res, next) => next()),}));jest.mock('~/server/controllers/AuthController', () => ({@@ -28,6 +32,9 @@ jest.mock('~/server/controllers/TwoFactorController', () => ({jest.mock('~/server/controllers/auth/TwoFactorAuthController', () => ({verify2FAWithTempToken: jest.fn((req, res) => res.status(200).end()),+ confirm2FASetupWithTempToken: jest.fn((req, res) => res.status(200).end()),+ acknowledge2FASetup: jest.fn((req, res) => res.status(200).end()),+ finalize2FASetup: jest.fn((req, res) => res.status(200).end()),}));jest.mock('~/server/controllers/auth/PasskeyController', () => ({@@ -66,8 +73,12 @@ jest.mock('~/server/middleware', () => {passkeyLimiter: pass,passkeyStepUpLimiter: pass,setTwoFactorTempUser: pass,+ setTwoFactorAcknowledgementTempUser: pass,+ setTwoFactorFinalizationTempUser: pass,twoFactorTempLimiter: pass,+ twoFactorSetupLimiter: pass,checkBan: pass,+ blockRetiredSetupToken: pass,validateEmailLogin: pass,requireLocalAuth: pass,requireLdapAuth: pass,diff --git a/api/server/routes/auth.cross-site.test.js b/api/server/routes/auth.cross-site.test.jsindex 8cf0ee6c16..eb32a3b368 100644--- a/api/server/routes/auth.cross-site.test.js+++ b/api/server/routes/auth.cross-site.test.js@@ -36,6 +36,9 @@ jest.mock('~/server/controllers/TwoFactorController', () => ({jest.mock('~/server/controllers/auth/TwoFactorAuthController', () => ({verify2FAWithTempToken: (...args) => mockVerify2FAWithTempToken(...args),+ confirm2FASetupWithTempToken: jest.fn((req, res) => res.status(204).end()),+ acknowledge2FASetup: jest.fn((req, res) => res.status(204).end()),+ finalize2FASetup: jest.fn((req, res) => res.status(204).end()),}));jest.mock('~/server/controllers/auth/PasskeyController', () => ({@@ -74,7 +77,11 @@ jest.mock('~/server/middleware', () => {passkeyLimiter: pass,passkeyStepUpLimiter: pass,setTwoFactorTempUser: (...args) => mockSetTwoFactorTempUser(...args),+ setTwoFactorAcknowledgementTempUser: pass,+ setTwoFactorFinalizationTempUser: pass,twoFactorTempLimiter: pass,+ twoFactorSetupLimiter: pass,+ blockRetiredSetupToken: pass,checkBan: pass,validateEmailLogin: jest.requireActual('~/server/middleware/validateEmailLogin'),requireLocalAuth: (...args) => mockRequireLocalAuth(...args),diff --git a/api/server/routes/auth.js b/api/server/routes/auth.jsindex c8539b33eb..6557dd7cd2 100644--- a/api/server/routes/auth.js+++ b/api/server/routes/auth.js@@ -2,8 +2,12 @@ const express = require('express');const {limiterCache,createSetBalanceConfig,+ requireTwoFactorSetupToken,createTwoFactorManagementLimiter,forceRefreshCloudFrontAuthCookies,+ blockTwoFactorDisableWhenRequired,+ requireTwoFactorSetupAcknowledgementToken,+ requireTwoFactorSetupFinalizationToken,} = require('@librechat/api');const {resetPasswordRequestController,@@ -28,7 +32,12 @@ const {registerPasskeyOptions,registerPasskeyVerify,} = require('~/server/controllers/auth/PasskeyController');-const { verify2FAWithTempToken } = require('~/server/controllers/auth/TwoFactorAuthController');+const {+ verify2FAWithTempToken,+ confirm2FASetupWithTempToken,+ acknowledge2FASetup,+ finalize2FASetup,+} = require('~/server/controllers/auth/TwoFactorAuthController');const { logoutController } = require('~/server/controllers/auth/LogoutController');const { loginController } = require('~/server/controllers/auth/LoginController');const { findBalanceByUser, upsertBalanceFields } = require('~/models');@@ -108,6 +117,40 @@ router.post(router.post('/2fa/enable', middleware.requireJwtAuth, twoFactorManagementLimiter, enable2FA);router.post('/2fa/verify', middleware.requireJwtAuth, twoFactorManagementLimiter, verify2FA);+router.post(+ '/2fa/setup',+ middleware.setTwoFactorTempUser,+ middleware.twoFactorSetupLimiter,+ middleware.checkBan,+ requireTwoFactorSetupToken,+ middleware.blockRetiredSetupToken,+ enable2FA,+);+router.post(+ '/2fa/setup/confirm',+ middleware.setTwoFactorTempUser,+ middleware.twoFactorTempLimiter,+ middleware.checkBan,+ requireTwoFactorSetupToken,+ middleware.blockRetiredSetupToken,+ confirm2FASetupWithTempToken,+);+router.post(+ '/2fa/setup/acknowledge',+ middleware.setTwoFactorAcknowledgementTempUser,+ middleware.twoFactorSetupLimiter,+ middleware.checkBan,+ requireTwoFactorSetupAcknowledgementToken,+ acknowledge2FASetup,+);+router.post(+ '/2fa/setup/finalize',+ middleware.setTwoFactorFinalizationTempUser,+ middleware.twoFactorSetupLimiter,+ middleware.checkBan,+ requireTwoFactorSetupFinalizationToken,+ finalize2FASetup,+);router.post('/2fa/verify-temp',middleware.requireSameOrigin,@@ -117,7 +160,13 @@ router.post(verify2FAWithTempToken,);router.post('/2fa/confirm', middleware.requireJwtAuth, twoFactorManagementLimiter, confirm2FA);-router.post('/2fa/disable', middleware.requireJwtAuth, twoFactorManagementLimiter, disable2FA);+router.post(+ '/2fa/disable',+ middleware.requireJwtAuth,+ twoFactorManagementLimiter,+ blockTwoFactorDisableWhenRequired,+ disable2FA,+);router.post('/2fa/backup/regenerate',middleware.requireJwtAuth,diff --git a/api/server/routes/auth.reset-password-ratelimit.test.js b/api/server/routes/auth.reset-password-ratelimit.test.jsindex f8f8ead7d8..4fe6bc23b2 100644--- a/api/server/routes/auth.reset-password-ratelimit.test.js+++ b/api/server/routes/auth.reset-password-ratelimit.test.js@@ -10,7 +10,11 @@ jest.mock('@librechat/api', () => ({limiterCache: jest.fn(),createTwoFactorManagementLimiter: jest.fn(() => (req, res, next) => next()),createSetBalanceConfig: jest.fn(() => (req, res, next) => next()),+ requireTwoFactorSetupToken: jest.fn((req, res, next) => next()),+ requireTwoFactorSetupAcknowledgementToken: jest.fn((req, res, next) => next()),+ requireTwoFactorSetupFinalizationToken: jest.fn((req, res, next) => next()),forceRefreshCloudFrontAuthCookies: jest.fn(),+ blockTwoFactorDisableWhenRequired: jest.fn((req, res, next) => next()),}));jest.mock('~/server/controllers/AuthController', () => ({@@ -31,6 +35,9 @@ jest.mock('~/server/controllers/TwoFactorController', () => ({jest.mock('~/server/controllers/auth/TwoFactorAuthController', () => ({verify2FAWithTempToken: jest.fn((req, res) => res.status(204).end()),+ confirm2FASetupWithTempToken: jest.fn((req, res) => res.status(204).end()),+ acknowledge2FASetup: jest.fn((req, res) => res.status(204).end()),+ finalize2FASetup: jest.fn((req, res) => res.status(204).end()),}));jest.mock('~/server/controllers/auth/PasskeyController', () => ({@@ -69,8 +76,12 @@ jest.mock('~/server/middleware', () => {passkeyLimiter: pass,passkeyStepUpLimiter: pass,setTwoFactorTempUser: pass,+ setTwoFactorAcknowledgementTempUser: pass,+ setTwoFactorFinalizationTempUser: pass,twoFactorTempLimiter: pass,+ twoFactorSetupLimiter: pass,checkBan: (...args) => mockCheckBan(...args),+ blockRetiredSetupToken: pass,validateEmailLogin: pass,requireLocalAuth: pass,requireLdapAuth: pass,diff --git a/api/server/routes/config.js b/api/server/routes/config.jsindex 6a585bfb2d..1fec348ad4 100644--- a/api/server/routes/config.js+++ b/api/server/routes/config.js@@ -108,6 +108,7 @@ function buildPreLoginPayload() {socialLoginEnabled: isEnabled(process.env.ALLOW_SOCIAL_LOGIN),emailEnabled: checkEmailConfig(),passwordResetEnabled,+ twoFactorAuthenticationRequired: isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION),};const minPasswordLength = parseInt(process.env.MIN_PASSWORD_LENGTH, 10);diff --git a/api/server/services/twoFactorService.js b/api/server/services/twoFactorService.jsindex 081fa611bd..f70e00dc83 100644--- a/api/server/services/twoFactorService.js+++ b/api/server/services/twoFactorService.js@@ -1,5 +1,6 @@const { webcrypto, timingSafeEqual } = require('node:crypto');const { hashBackupCode, decryptV3, decryptV2 } = require('@librechat/data-schemas');+const { generateTwoFactorLoginChallengeToken } = require('@librechat/api');const { updateUser } = require('~/models');// Base32 alphabet for TOTP secret encoding.@@ -268,8 +269,7 @@ const getTOTPSecret = async (storedSecret) => {* @returns {string}*/const generate2FATempToken = (userId) => {- const { sign } = require('jsonwebtoken');- return sign({ userId, twoFAPending: true }, process.env.JWT_SECRET, { expiresIn: '5m' });+ return generateTwoFactorLoginChallengeToken(userId, process.env.JWT_SECRET);};module.exports = {diff --git a/api/strategies/jwtStrategy.js b/api/strategies/jwtStrategy.jsindex 1d5423aa8c..989b6d1b07 100644--- a/api/strategies/jwtStrategy.js+++ b/api/strategies/jwtStrategy.js@@ -1,7 +1,11 @@-const { AGENT_TRIGGER_SCOPE, isTokenIssuedBeforeCredentialChange } = require('@librechat/api');const { logger, runAsSystem } = require('@librechat/data-schemas');const { SystemRoles } = require('librechat-data-provider');const { Strategy: JwtStrategy, ExtractJwt } = require('passport-jwt');+const {+ AGENT_TRIGGER_SCOPE,+ isTokenRetired,+ continueAfterBearerRetirement,+} = require('@librechat/api');const { getUserById, updateUser } = require('~/models');const AGENT_TRIGGER_ADMISSION_PATHS = ['/api/agents/chat/agents', '/api/agents/chat/steer/deliver'];@@ -48,21 +52,25 @@ const jwtLogin = () =>return;}if (user) {- if (isTokenIssuedBeforeCredentialChange(payload, user)) {- logger.warn(- '[jwtLogin] JwtStrategy => token predates the last credential change: ' + payload?.id,- );- done(null, false);- return;- }- user.id = user._id.toString();- /** Absent on the full doc means local user; null skips getUserPrincipals' fallback lookup */- user.idOnTheSource ??= null;- if (!user.role) {- user.role = SystemRoles.USER;- await runAsSystem(() => updateUser(user.id, { role: user.role }));- }- done(null, user);+ return await continueAfterBearerRetirement(+ user,+ { issuedAt: payload?.iat, issuedAtMs: payload?.issuedAtMs },+ 'jwt',+ payload?.id,+ done,+ (message) => logger.warn(message),+ async () => {+ user.id = user._id.toString();+ /** Absent on the full doc means local user; null skips getUserPrincipals' fallback lookup */+ user.idOnTheSource ??= null;+ if (!user.role) {+ user.role = SystemRoles.USER;+ await runAsSystem(() => updateUser(user.id, { role: user.role }));+ }+ done(null, user);+ },+ isTokenRetired,+ );} else {logger.warn('[jwtLogin] JwtStrategy => no user found: ' + payload?.id);done(null, false);diff --git a/api/strategies/jwtStrategy.spec.js b/api/strategies/jwtStrategy.spec.jsindex 5764b91eaa..0ca5cb6864 100644--- a/api/strategies/jwtStrategy.spec.js+++ b/api/strategies/jwtStrategy.spec.js@@ -21,8 +21,8 @@ jest.mock('@librechat/data-schemas', () => ({jest.mock('@librechat/api', () => ({AGENT_TRIGGER_SCOPE: 'agent_trigger',- isTokenIssuedBeforeCredentialChange:- jest.requireActual('@librechat/api').isTokenIssuedBeforeCredentialChange,+ isTokenRetired: jest.requireActual('@librechat/api').isTokenRetired,+ continueAfterBearerRetirement: jest.requireActual('@librechat/api').continueAfterBearerRetirement,}));jest.mock('~/models', () => ({@@ -222,11 +222,23 @@ describe('jwtStrategy', () => {expect(user).toBe(false);});- it('accepts a token issued in the same second as a reset stamped on the second boundary', async () => {+ it('rejects a token issued in the same second as a reset stamped on the second boundary', async () => {mockUserWithStamp(new Date(1700000010000));const { user } = await invokeVerify({ id: 'user-reset', iat: 1700000010 });+ expect(user).toBe(false);+ });++ it('accepts a token dated after a boundary reset to the millisecond', async () => {+ mockUserWithStamp(new Date(1700000010000));++ const { user } = await invokeVerify({+ id: 'user-reset',+ iat: 1700000010,+ issuedAtMs: 1700000010001,+ });+expect(user.id).toBe('user-reset');});@@ -257,4 +269,87 @@ describe('jwtStrategy', () => {expect(user).toBe(false);});});++ describe('two-factor enrollment cutoff', () => {+ const enrolledAt = new Date('2026-01-01T00:00:10.500Z');+ const enrolledSecond = Math.floor(enrolledAt.getTime() / 1000);++ const mockEnrolledUser = () =>+ getUserById.mockResolvedValue({+ _id: { toString: () => 'user-3' },+ role: SystemRoles.USER,+ twoFactorEnabled: true,+ twoFactorEnrolledAt: enrolledAt,+ });++ it('refuses an access token minted before enrollment', async () => {+ mockEnrolledUser();++ const { user } = await invokeVerify({ id: 'user-3', iat: enrolledSecond - 1 });++ expect(user).toBe(false);+ });++ it('refuses an access token minted before a password reset', async () => {+ getUserById.mockResolvedValue({+ _id: { toString: () => 'user-3' },+ role: SystemRoles.USER,+ twoFactorEnrolledAt: null,+ credentialsChangedAt: enrolledAt,+ });++ const { user } = await invokeVerify({ id: 'user-3', iat: enrolledSecond - 1 });++ expect(user).toBe(false);+ });++ it('accepts an access token minted after a password reset', async () => {+ getUserById.mockResolvedValue({+ _id: { toString: () => 'user-3' },+ role: SystemRoles.USER,+ twoFactorEnrolledAt: null,+ credentialsChangedAt: enrolledAt,+ });++ const { user } = await invokeVerify({ id: 'user-3', iat: enrolledSecond + 60 });++ expect(user.id).toBe('user-3');+ });++ it('accepts the session minted within the enrolling second', async () => {+ mockEnrolledUser();++ const { user } = await invokeVerify({ id: 'user-3', iat: enrolledSecond });++ expect(user.id).toBe('user-3');+ });++ it('accepts an access token minted after enrollment', async () => {+ mockEnrolledUser();++ const { user } = await invokeVerify({ id: 'user-3', iat: enrolledSecond + 60 });++ expect(user.id).toBe('user-3');+ });++ it('refuses an undatable token once the account is enrolled', async () => {+ mockEnrolledUser();++ const { user } = await invokeVerify({ id: 'user-3' });++ expect(user).toBe(false);+ });++ it('leaves accounts that never enrolled untouched', async () => {+ getUserById.mockResolvedValue({+ _id: { toString: () => 'user-4' },+ role: SystemRoles.USER,+ twoFactorEnrolledAt: null,+ });++ const { user } = await invokeVerify({ id: 'user-4', iat: 0 });++ expect(user.id).toBe('user-4');+ });+ });});diff --git a/api/strategies/openIdJwtStrategy.js b/api/strategies/openIdJwtStrategy.jsindex 435edb837c..ca4edd7829 100644--- a/api/strategies/openIdJwtStrategy.js+++ b/api/strategies/openIdJwtStrategy.js@@ -5,6 +5,8 @@ const { CacheKeys, SystemRoles } = require('librechat-data-provider');const { Strategy: JwtStrategy, ExtractJwt } = require('passport-jwt');const {isEnabled,+ isTokenRetired,+ continueAfterBearerRetirement,findOpenIDUser,getOpenIdEmail,getOpenIdIssuer,@@ -18,7 +20,6 @@ const {getHttpsProxyAgent,isAccessTokenJwt,math,- isTokenIssuedBeforeCredentialChange,} = require('@librechat/api');const { updateUser, findUser, isAgentTriggerPrincipalActive } = require('~/models');const getLogStores = require('~/cache/getLogStores');@@ -196,96 +197,101 @@ const openIdJwtLogin = (openIdConfig) => {}if (user) {- if (isTokenIssuedBeforeCredentialChange(payload, user)) {- logger.warn(- '[openIdJwtLogin] openId JwtStrategy => token predates the last credential change: ' +- payload?.sub,- );- done(null, false);- return;- }- user.id = user._id.toString();- if (!(await runAsSystem(() => isAgentTriggerPrincipalActive(user.id)))) {- done(null, false, {- message: 'Account deletion is in progress',- code: 'ACCOUNT_DELETION_IN_PROGRESS',- });- return;- }- /** Absent on the full doc means local user; null skips getUserPrincipals' fallback lookup */- user.idOnTheSource ??= null;-- const updateData = {};- if (migration) {- updateData.provider = 'openid';- updateData.openidId = payload?.sub;- if (openidIssuer) {- updateData.openidIssuer = openidIssuer;- }- }- if (!user.role) {- user.role = SystemRoles.USER;- updateData.role = user.role;- }-- if (Object.keys(updateData).length > 0) {- await updateUser(user.id, updateData);- }-- if (authUserCacheStore && authUserCacheKey) {- if (Object.keys(updateData).length > 0) {- await invalidateCachedAuthUserDoc(authUserCacheStore, {- userId: user.id,- cacheKey: authUserCacheKey,- });- } else if (!servedCachedUser && isUserInAuthCacheScope(user, authUserCacheScope)) {- await setCachedAuthUserDoc(authUserCacheStore, authUserCacheKey, user);- }- }-- /** Read tokens from session (server-side) to avoid large cookie issues */- const sessionTokens = req.session?.openidTokens;- let accessToken = sessionTokens?.accessToken;- let idToken = sessionTokens?.idToken;- let refreshToken = sessionTokens?.refreshToken;-- /** Fallback to cookies for backward compatibility */- if (!accessToken || !refreshToken || !idToken) {- accessToken = accessToken || parsedCookies.openid_access_token;- idToken = idToken || parsedCookies.openid_id_token;- refreshToken = refreshToken || parsedCookies.refreshToken;- }-- /**- * The raw bearer only stands in for a missing stored access token when it is- * identifiable as one. It cleared this strategy's audience check, but an ID token- * clears the same check, and an ID token used as the OBO assertion is rejected by the- * IdP (Entra answers `AADSTS240002`). An unrecognised token is left unset so- * `isOpenIDTokenValid` fails closed with an actionable error instead.- */- let reusableRawToken;- if (!accessToken) {- reusableRawToken = isAccessTokenJwt(rawToken, payload, audienceConfig)- ? rawToken- : undefined;- if (!reusableRawToken) {- /** Per-request on the reuse path, so the actionable warning is left to the consumer that actually needs the credential */- logger.debug(- '[openIdJwtLogin] No stored OpenID access token, and the request bearer is not identifiable as one; leaving it unset',- );- }- }-- const resolvedAccessToken = accessToken || reusableRawToken;- user.federatedTokens = {- access_token: resolvedAccessToken,- id_token: idToken,- refresh_token: refreshToken,- expires_at:- resolvedAccessToken === rawToken ? payload.exp : decodeJwtExpiry(resolvedAccessToken),- };-- done(null, user);+ return await continueAfterBearerRetirement(+ user,+ { issuedAt: payload?.iat },+ 'openidJwt',+ payload?.sub,+ done,+ (message) => logger.warn(message),+ async () => {+ user.id = user._id.toString();+ if (!(await runAsSystem(() => isAgentTriggerPrincipalActive(user.id)))) {+ done(null, false, {+ message: 'Account deletion is in progress',+ code: 'ACCOUNT_DELETION_IN_PROGRESS',+ });+ return;+ }+ /** Absent on the full doc means local user; null skips getUserPrincipals' fallback lookup */+ user.idOnTheSource ??= null;++ const updateData = {};+ if (migration) {+ updateData.provider = 'openid';+ updateData.openidId = payload?.sub;+ if (openidIssuer) {+ updateData.openidIssuer = openidIssuer;+ }+ }+ if (!user.role) {+ user.role = SystemRoles.USER;+ updateData.role = user.role;+ }++ if (Object.keys(updateData).length > 0) {+ await updateUser(user.id, updateData);+ }++ if (authUserCacheStore && authUserCacheKey) {+ if (Object.keys(updateData).length > 0) {+ await invalidateCachedAuthUserDoc(authUserCacheStore, {+ userId: user.id,+ cacheKey: authUserCacheKey,+ });+ } else if (!servedCachedUser && isUserInAuthCacheScope(user, authUserCacheScope)) {+ await setCachedAuthUserDoc(authUserCacheStore, authUserCacheKey, user);+ }+ }++ /** Read tokens from session (server-side) to avoid large cookie issues */+ const sessionTokens = req.session?.openidTokens;+ let accessToken = sessionTokens?.accessToken;+ let idToken = sessionTokens?.idToken;+ let refreshToken = sessionTokens?.refreshToken;++ /** Fallback to cookies for backward compatibility */+ if (!accessToken || !refreshToken || !idToken) {+ accessToken = accessToken || parsedCookies.openid_access_token;+ idToken = idToken || parsedCookies.openid_id_token;+ refreshToken = refreshToken || parsedCookies.refreshToken;+ }++ /**+ * The raw bearer only stands in for a missing stored access token when it is+ * identifiable as one. It cleared this strategy's audience check, but an ID token+ * clears the same check, and an ID token used as the OBO assertion is rejected by the+ * IdP (Entra answers `AADSTS240002`). An unrecognised token is left unset so+ * `isOpenIDTokenValid` fails closed with an actionable error instead.+ */+ let reusableRawToken;+ if (!accessToken) {+ reusableRawToken = isAccessTokenJwt(rawToken, payload, audienceConfig)+ ? rawToken+ : undefined;+ if (!reusableRawToken) {+ /** Per-request on the reuse path, so the actionable warning is left to the consumer that actually needs the credential */+ logger.debug(+ '[openIdJwtLogin] No stored OpenID access token, and the request bearer is not identifiable as one; leaving it unset',+ );+ }+ }++ const resolvedAccessToken = accessToken || reusableRawToken;+ user.federatedTokens = {+ access_token: resolvedAccessToken,+ id_token: idToken,+ refresh_token: refreshToken,+ expires_at:+ resolvedAccessToken === rawToken+ ? payload.exp+ : decodeJwtExpiry(resolvedAccessToken),+ };++ done(null, user);+ },+ isTokenRetired,+ );} else {logger.warn('[openIdJwtLogin] openId JwtStrategy => no user found with the sub claims: ' +diff --git a/api/strategies/openIdJwtStrategy.spec.js b/api/strategies/openIdJwtStrategy.spec.jsindex a2563533bc..6615e39eee 100644--- a/api/strategies/openIdJwtStrategy.spec.js+++ b/api/strategies/openIdJwtStrategy.spec.js@@ -34,12 +34,12 @@ jest.mock('@librechat/data-schemas', () => ({}));jest.mock('@librechat/api', () => ({isEnabled: jest.fn(() => false),+ isTokenRetired: jest.requireActual('@librechat/api').isTokenRetired,+ continueAfterBearerRetirement: jest.requireActual('@librechat/api').continueAfterBearerRetirement,findOpenIDUser: jest.fn(),getOpenIdEmail: jest.requireActual('@librechat/api').getOpenIdEmail,getOpenIdIssuer: jest.fn(() => 'https://issuer.example.com'),normalizeOpenIdIssuer: jest.requireActual('@librechat/api').normalizeOpenIdIssuer,- isTokenIssuedBeforeCredentialChange:- jest.requireActual('@librechat/api').isTokenIssuedBeforeCredentialChange,buildAuthUserDocCacheKey: jest.fn(() => 'auth-user-doc-key'),getAuthUserDocCacheMode: jest.fn(() => 'off'),getCachedAuthUserDoc: jest.fn(),@@ -777,6 +777,119 @@ describe('openIdJwtStrategy – auth user document cache', () => {});});+describe('openIdJwtStrategy: retired token cutoffs', () => {+ const req = { headers: { authorization: 'Bearer tok' }, session: {} };++ const baseUser = {+ _id: { toString: () => 'user-abc' },+ role: SystemRoles.USER,+ provider: 'openid',+ email: '[email protected]',+ };++ const enrolledAt = new Date('2026-01-01T00:00:30.500Z');+ const enrolledSecond = Math.floor(enrolledAt.getTime() / 1000);++ /** The provider mints this token, so `iat` is the only stamp it can ever carry. */+ const makePayload = (iat) => ({+ sub: 'oidc-123',+ email: '[email protected]',+ iss: 'https://issuer.example.com',+ exp: 9999999999,+ ...(iat === undefined ? {} : { iat }),+ });++ beforeEach(() => {+ jest.clearAllMocks();+ resetAuthUserDocCacheMocks();+ updateUser.mockResolvedValue({});+ openIdJwtLogin(mockOpenIdConfig);+ });++ it('refuses a federated bearer minted before enrollment', async () => {+ findOpenIDUser.mockResolvedValue({+ user: { ...baseUser, twoFactorEnrolledAt: enrolledAt },+ error: null,+ migration: false,+ });++ const { user, info } = await invokeVerify(req, makePayload(enrolledSecond - 1));++ expect(user).toBe(false);+ expect(info).toEqual({ message: 'Token predates enrollment or password reset' });+ expect(updateUser).not.toHaveBeenCalled();+ });++ it('surrenders the resetting second, which whole-second `iat` cannot tell apart', async () => {+ const credentialsChangedAt = new Date('2026-01-01T00:00:30.500Z');+ findOpenIDUser.mockResolvedValue({+ user: { ...baseUser, credentialsChangedAt },+ error: null,+ migration: false,+ });++ const { user } = await invokeVerify(+ req,+ makePayload(Math.floor(credentialsChangedAt.getTime() / 1000)),+ );++ expect(user).toBe(false);+ });++ it('accepts a federated bearer minted after both cutoffs', async () => {+ findOpenIDUser.mockResolvedValue({+ user: {+ ...baseUser,+ twoFactorEnrolledAt: enrolledAt,+ credentialsChangedAt: new Date('2025-06-01T00:00:00.000Z'),+ },+ error: null,+ migration: false,+ });++ const { user } = await invokeVerify(req, makePayload(enrolledSecond + 1));++ expect(user).toMatchObject({ id: 'user-abc', email: '[email protected]' });+ });++ it('leaves an account that carries neither cutoff alone, undatable token included', async () => {+ findOpenIDUser.mockResolvedValue({ user: { ...baseUser }, error: null, migration: false });++ const { user } = await invokeVerify(req, makePayload(undefined));++ expect(user).toMatchObject({ id: 'user-abc' });+ });++ it('refuses a bearer it cannot date at all once a cutoff is set', async () => {+ findOpenIDUser.mockResolvedValue({+ user: { ...baseUser, twoFactorEnrolledAt: enrolledAt },+ error: null,+ migration: false,+ });++ const { user } = await invokeVerify(req, makePayload(undefined));++ expect(user).toBe(false);+ });++ it('dates the bearer against a cached stamp that came back serialized', async () => {+ getAuthUserDocCacheMode.mockReturnValue('on');+ getCachedAuthUserDoc.mockResolvedValue({+ _id: 'cached-user',+ role: SystemRoles.USER,+ provider: 'openid',+ email: '[email protected]',+ /** Redis round-trips `Date` through JSON, so the cutoff arrives as an ISO string */+ twoFactorEnrolledAt: enrolledAt.toISOString(),+ });++ const { user } = await invokeVerify(req, makePayload(enrolledSecond - 1));++ expect(user).toBe(false);+ expect(findOpenIDUser).not.toHaveBeenCalled();+ });+});+describe('openIdJwtStrategy – idOnTheSource boundary coercion', () => {const payload = {sub: 'oidc-123',diff --git a/client/src/common/types.ts b/client/src/common/types.tsindex 4ba4299949..a3e0a9b319 100644--- a/client/src/common/types.ts+++ b/client/src/common/types.ts@@ -508,6 +508,7 @@ export type TAuthContext = {error: string | undefined;login: (data: t.TLoginUser) => void;logout: (redirect?: string) => void;+ completeAuthentication: (token: string, user: t.TUser) => void;setError: React.Dispatch<React.SetStateAction<string | undefined>>;roles?: Record<string, t.TRole | null | undefined>;};diff --git a/client/src/components/Auth/AuthLayout.tsx b/client/src/components/Auth/AuthLayout.tsxindex 25a1360b35..fdd43eaea2 100644--- a/client/src/components/Auth/AuthLayout.tsx+++ b/client/src/components/Auth/AuthLayout.tsx@@ -8,6 +8,7 @@ import { BlinkAnimation } from './BlinkAnimation';import LegalConsent from './LegalConsent';import { Banner } from '../Banners';import Footer from './Footer';+import { cn } from '~/utils';function AuthLayout({children,@@ -53,6 +54,7 @@ function AuthLayout({/** The bar is dropped exactly when the sentence is on the screen, so a* reader never meets both and never meets neither. */const statesConsent = registrationStatesConsent || statesConsentBelowProviders;+ const isTwoFactorSetup = pathname === '/login/2fa/setup';const DisplayError = () => {if (hasStartupConfigError) {return (@@ -103,7 +105,12 @@ function AuthLayout({</div><main className="flex grow items-center justify-center">- <div className="w-authPageWidth bg-surface-primary overflow-hidden px-6 py-4 sm:max-w-md sm:rounded-lg">+ <div+ className={cn(+ 'bg-surface-primary overflow-hidden px-6 py-4 sm:rounded-lg',+ isTwoFactorSetup ? 'w-11/12 max-w-lg' : 'w-authPageWidth sm:max-w-md',+ )}+ >{!hasStartupConfigError && !isFetching && header && (<h1className="text-text-primary mb-4 text-center text-3xl font-semibold"diff --git a/client/src/components/Auth/TwoFactorSetupScreen.tsx b/client/src/components/Auth/TwoFactorSetupScreen.tsxnew file mode 100644index 0000000000..e2834c5959--- /dev/null+++ b/client/src/components/Auth/TwoFactorSetupScreen.tsx@@ -0,0 +1,311 @@+import React, { useCallback, useEffect, useRef, useState } from 'react';+import { Button } from '@librechat/client';+import { useNavigate, useSearchParams } from 'react-router-dom';+import {+ readTwoFactorSetupToken,+ clearTwoFactorSetupToken,+ subscribeTwoFactorSetupToken,+} from 'librechat-data-provider';+import {+ useAcknowledgeTwoFactorSetupMutation,+ useConfirmTwoFactorSetupMutation,+ useEnableTwoFactorSetupMutation,+ useFinalizeTwoFactorSetupMutation,+} from '~/data-provider';+import {+ BackupPhase,+ QRPhase,+ SetupPhase,+ VerifyPhase,+} from '~/components/Nav/SettingsTabs/Account/TwoFactorPhases';+import { useAuthContext, useLocalize } from '~/hooks';+import { ErrorMessage } from './ErrorMessage';+import { isSafeRedirect } from '~/utils';++type SetupPhaseName = 'setup' | 'qr' | 'verify' | 'backup';++const getSecret = (otpauthUrl: string): string => {+ const value = otpauthUrl.match(/[?&]secret=([^&]+)/)?.[1];+ return value ? decodeURIComponent(value) : '';+};++const getResponseStatus = (error: unknown): number | undefined =>+ (error as { response?: { status?: number } } | undefined)?.response?.status;++/**+ * Every setup route gates on the enforcement policy and on the ban list before it reaches a+ * controller, and both answer 403. Either way the flow is retired rather than merely rejected, so+ * no phase can make progress and a reload would only replay it. Rate limiting answers 429 and a+ * wrong or spent code answers 400, so neither retryable state is caught here.+ */+const isRetiredSetupFlow = (error: unknown): boolean => getResponseStatus(error) === 403;++const isExpiredSetupCredential = (error: unknown): boolean =>+ getResponseStatus(error) === 401 || isRetiredSetupFlow(error);++/**+ * Acknowledgement and finalization nonces are single-use and answer 400 once consumed, so a lost+ * response leaves the screen replaying a credential the server can never accept again. Spent and+ * expired both have to land somewhere the user can act from rather than on an endless retry.+ */+const isSpentTransitionCredential = (error: unknown): boolean => {+ const status = getResponseStatus(error);+ return status === 400 || status === 401 || isRetiredSetupFlow(error);+};++const TwoFactorSetupScreen: React.FC = React.memo(() => {+ const [searchParams] = useSearchParams();+ const navigate = useNavigate();+ const localize = useLocalize();+ const { completeAuthentication } = useAuthContext();+ const phaseRef = useRef<HTMLDivElement>(null);+ /**+ * Read at mount and adopted later only while empty: the credential arrives out of band rather+ * than in the query string, a refresh on this route can hand one off after the screen rendered,+ * and consuming it on completion must not flip the screen to the expired state mid-navigation.+ */+ const [tempToken, setTempToken] = useState(readTwoFactorSetupToken);+ const [phase, setPhase] = useState<SetupPhaseName>('setup');+ const [secret, setSecret] = useState('');+ const [otpauthUrl, setOtpauthUrl] = useState('');+ const [backupCodes, setBackupCodes] = useState<string[]>([]);+ const [verificationToken, setVerificationToken] = useState('');+ const [acknowledgementToken, setAcknowledgementToken] = useState('');+ const [finalizationToken, setFinalizationToken] = useState('');+ const [downloaded, setDownloaded] = useState(false);+ const [error, setError] = useState<string | null>(null);+ const { mutate: enableSetup, isLoading: isGenerating } = useEnableTwoFactorSetupMutation();+ const { mutate: confirmSetup, isLoading: isVerifying } = useConfirmTwoFactorSetupMutation();+ const { mutate: acknowledgeSetup, isLoading: isAcknowledging } =+ useAcknowledgeTwoFactorSetupMutation();+ const { mutate: finalizeSetup, isLoading: isFinalizing } = useFinalizeTwoFactorSetupMutation();+ const redirectTo = searchParams.get('redirect_to');+ const restartLoginPath =+ redirectTo && isSafeRedirect(redirectTo)+ ? `/login?redirect_to=${encodeURIComponent(redirectTo)}`+ : '/login';++ useEffect(() => {+ phaseRef.current?.focus();+ }, [phase]);++ useEffect(() => {+ const adoptToken = () => setTempToken((current) => current || readTwoFactorSetupToken());+ const unsubscribe = subscribeTwoFactorSetupToken(adoptToken);+ adoptToken();+ return unsubscribe;+ }, []);++ const restartLogin = useCallback(() => {+ clearTwoFactorSetupToken();+ navigate(restartLoginPath, { replace: true });+ }, [navigate, restartLoginPath]);++ const restartLoginWhenExpired = useCallback(+ (mutationError: unknown): boolean => {+ if (!isExpiredSetupCredential(mutationError)) {+ return false;+ }+ restartLogin();+ return true;+ },+ [restartLogin],+ );++ const restartLoginWhenSpent = useCallback(+ (mutationError: unknown): boolean => {+ if (!isSpentTransitionCredential(mutationError)) {+ return false;+ }+ restartLogin();+ return true;+ },+ [restartLogin],+ );++ const handleGenerate = useCallback(() => {+ setError(null);+ enableSetup(+ { tempToken },+ {+ onSuccess: (data) => {+ setOtpauthUrl(data.otpauthUrl);+ setSecret(getSecret(data.otpauthUrl));+ setBackupCodes(data.backupCodes);+ setPhase('qr');+ },+ onError: (mutationError) => {+ if (!restartLoginWhenExpired(mutationError)) {+ setError(localize('com_auth_two_factor_setup_expired'));+ }+ },+ },+ );+ }, [enableSetup, localize, restartLoginWhenExpired, tempToken]);++ const handleVerify = useCallback(() => {+ if (verificationToken.length !== 6) {+ return;+ }++ setError(null);+ confirmSetup(+ { tempToken, token: verificationToken },+ {+ onSuccess: (data) => {+ if (!data.acknowledgementToken || !data.backupCodes.length) {+ setError(localize('com_ui_2fa_invalid'));+ return;+ }+ setBackupCodes(data.backupCodes);+ setAcknowledgementToken(data.acknowledgementToken);+ /** Confirming again rotates the codes server-side, retiring any earlier credential. */+ setFinalizationToken('');+ setDownloaded(false);+ setPhase('backup');+ },+ onError: (mutationError) => {+ if (!restartLoginWhenExpired(mutationError)) {+ setError(localize('com_ui_2fa_invalid'));+ }+ },+ },+ );+ }, [confirmSetup, localize, restartLoginWhenExpired, tempToken, verificationToken]);++ const handleDownload = useCallback(() => {+ if (!backupCodes.length) {+ return;+ }++ const blob = new Blob([backupCodes.join('\n')], { type: 'text/plain;charset=utf-8' });+ const url = URL.createObjectURL(blob);+ const anchor = document.createElement('a');+ anchor.href = url;+ anchor.download = 'backup-codes.txt';+ anchor.click();+ URL.revokeObjectURL(url);+ setDownloaded(true);+ }, [backupCodes]);++ const runFinalize = useCallback(+ (token: string) => {+ finalizeSetup(+ { finalizationToken: token },+ {+ onSuccess: ({ token: authToken, user }) => completeAuthentication(authToken, user),+ onError: (mutationError) => {+ if (!restartLoginWhenSpent(mutationError)) {+ setError(localize('com_auth_two_factor_setup_finalize_error'));+ }+ },+ },+ );+ },+ [completeAuthentication, finalizeSetup, localize, restartLoginWhenSpent],+ );++ const handleComplete = useCallback(() => {+ setError(null);+ /** Acknowledgement nonces are single-use, so a retry reuses the finalization credential. */+ if (finalizationToken) {+ runFinalize(finalizationToken);+ return;+ }+ if (!acknowledgementToken) {+ return;+ }++ acknowledgeSetup(+ { acknowledgementToken },+ {+ onSuccess: ({ finalizationToken: issuedToken }) => {+ setFinalizationToken(issuedToken);+ runFinalize(issuedToken);+ },+ onError: (mutationError) => {+ if (!restartLoginWhenSpent(mutationError)) {+ setError(localize('com_auth_two_factor_setup_finalize_error'));+ }+ },+ },+ );+ }, [+ acknowledgementToken,+ acknowledgeSetup,+ finalizationToken,+ localize,+ restartLoginWhenSpent,+ runFinalize,+ ]);++ /**+ * The layout hides the sign-in controls on every setup path, so without this action a screen that+ * lost its credential has nowhere to go: the message tells the user to return to sign in and the+ * page offers no way to do it. Reloading only replays the same empty state.+ */+ if (!tempToken) {+ return (+ <div>+ <ErrorMessage>{localize('com_auth_two_factor_setup_expired')}</ErrorMessage>+ <Button variant="link" onClick={restartLogin} className="mt-4 w-full">+ {localize('com_auth_back_to_login')}+ </Button>+ </div>+ );+ }++ return (+ <div className="text-text-primary mt-4 space-y-6">+ <p className="text-text-primary text-center text-sm">+ {localize('com_auth_two_factor_setup_required_description')}+ </p>+ {error && <ErrorMessage>{error}</ErrorMessage>}+ <div+ ref={phaseRef}+ tabIndex={-1}+ aria-live="polite"+ data-testid="two-factor-setup-phase"+ className="focus:outline-none"+ >+ {phase === 'setup' && (+ <SetupPhase+ isGenerating={isGenerating}+ onGenerate={handleGenerate}+ onNext={() => setPhase('qr')}+ onError={() => setError(localize('com_auth_two_factor_setup_expired'))}+ />+ )}+ {phase === 'qr' && (+ <QRPhase+ secret={secret}+ otpauthUrl={otpauthUrl}+ onNext={() => setPhase('verify')}+ onError={() => setError(localize('com_auth_two_factor_setup_expired'))}+ />+ )}+ {phase === 'verify' && (+ <VerifyPhase+ token={verificationToken}+ onTokenChange={setVerificationToken}+ isVerifying={isVerifying}+ onNext={handleVerify}+ onError={() => setError(localize('com_ui_2fa_invalid'))}+ />+ )}+ {phase === 'backup' && (+ <BackupPhase+ backupCodes={backupCodes}+ onDownload={handleDownload}+ downloaded={downloaded}+ isCompleting={isAcknowledging || isFinalizing}+ onNext={handleComplete}+ onError={() => setError(localize('com_ui_2fa_invalid'))}+ />+ )}+ </div>+ </div>+ );+});++export default TwoFactorSetupScreen;diff --git a/client/src/components/Auth/__tests__/TwoFactorSetupScreen.spec.tsx b/client/src/components/Auth/__tests__/TwoFactorSetupScreen.spec.tsxnew file mode 100644index 0000000000..6b0a698a8c--- /dev/null+++ b/client/src/components/Auth/__tests__/TwoFactorSetupScreen.spec.tsx@@ -0,0 +1,573 @@+/**+ * @jest-environment @happy-dom/jest-environment+ */+import React, { useCallback, useLayoutEffect, useState } from 'react';+import { act, fireEvent, render, screen } from '@testing-library/react';+import { createMemoryRouter, MemoryRouter, RouterProvider, useNavigate } from 'react-router-dom';+import {+ readTwoFactorSetupToken,+ clearTwoFactorSetupToken,+ persistTwoFactorSetupToken,+} from 'librechat-data-provider';+import type { TUser } from 'librechat-data-provider';+import TwoFactorSetupScreen from '../TwoFactorSetupScreen';+import StartupLayout from '~/routes/Layouts/Startup';+import { getPostLoginRedirect } from '~/utils';++const mockEnableMutate = jest.fn();+const mockConfirmMutate = jest.fn();+const mockAcknowledgeMutate = jest.fn();+const mockFinalizeMutate = jest.fn();+const mockCompleteAuthentication = jest.fn();+let mockCompleteAuthenticationImpl: (token: string, user: TUser) => void =+ mockCompleteAuthentication;++jest.mock('~/data-provider', () => ({+ useEnableTwoFactorSetupMutation: () => ({ mutate: mockEnableMutate, isLoading: false }),+ useConfirmTwoFactorSetupMutation: () => ({ mutate: mockConfirmMutate, isLoading: false }),+ useAcknowledgeTwoFactorSetupMutation: () => ({+ mutate: mockAcknowledgeMutate,+ isLoading: false,+ }),+ useFinalizeTwoFactorSetupMutation: () => ({ mutate: mockFinalizeMutate, isLoading: false }),+ useGetStartupConfig: () => ({ data: null, isFetching: false, error: null }),+}));++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => key,+ useAuthContext: () => ({ completeAuthentication: mockCompleteAuthenticationImpl }),+}));++jest.mock('~/components/Auth/AuthLayout', () => ({ children }: { children: React.ReactNode }) => (+ <div data-testid="auth-layout">{children}</div>+));++jest.mock('~/components/Nav/SettingsTabs/Account/TwoFactorPhases', () => ({+ SetupPhase: ({ onGenerate }: { onGenerate: () => void }) => (+ <button data-testid="generate" onClick={onGenerate} />+ ),+ QRPhase: ({ onNext }: { onNext: () => void }) => (+ <button data-testid="qr-next" onClick={onNext} />+ ),+ VerifyPhase: ({+ onTokenChange,+ onNext,+ }: {+ onTokenChange: (value: string) => void;+ onNext: () => void;+ }) => (+ <>+ <button data-testid="enter-code" onClick={() => onTokenChange('123456')} />+ <button data-testid="verify" onClick={onNext} />+ </>+ ),+ BackupPhase: ({+ onDownload,+ onNext,+ downloaded,+ }: {+ onDownload: () => void;+ onNext: () => void;+ downloaded: boolean;+ }) => (+ <>+ <button data-testid="download" onClick={onDownload} />+ <button data-testid="complete" onClick={onNext} disabled={!downloaded} />+ </>+ ),+}));++function renderScreen(tempToken: string | null = 'setup-token', initialEntry = '/login/2fa/setup') {+ if (tempToken != null) {+ persistTwoFactorSetupToken(tempToken);+ }+ return render(+ <MemoryRouter initialEntries={[initialEntry]}>+ <TwoFactorSetupScreen />+ </MemoryRouter>,+ );+}++/** Mirrors the auth context: resolve the destination once, flip state, and navigate there. */+function StartupAuthRoute() {+ const [isAuthenticated, setIsAuthenticated] = useState(false);+ const navigate = useNavigate();+ mockCompleteAuthenticationImpl = useCallback(+ (token: string, user: TUser) => {+ mockCompleteAuthentication(token, user);+ const destination =+ getPostLoginRedirect(new URLSearchParams(window.location.search)) ?? '/c/new';+ setIsAuthenticated(true);+ navigate(destination, { replace: true });+ },+ [navigate],+ );++ return <StartupLayout isAuthenticated={isAuthenticated} />;+}++describe('TwoFactorSetupScreen', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ sessionStorage.clear();+ clearTwoFactorSetupToken();+ mockCompleteAuthenticationImpl = mockCompleteAuthentication;+ URL.createObjectURL = jest.fn(() => 'blob:backup-codes');+ URL.revokeObjectURL = jest.fn();+ jest.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => undefined);+ });++ afterEach(() => {+ jest.restoreAllMocks();+ });++ it('rejects direct visits without a temporary setup token', () => {+ renderScreen(null);++ expect(screen.getByRole('alert')).toHaveTextContent('com_auth_two_factor_setup_expired');+ expect(screen.queryByTestId('generate')).not.toBeInTheDocument();+ });++ it('adopts a setup token handed off after it mounted without one', () => {+ renderScreen(null);+ expect(screen.queryByTestId('generate')).not.toBeInTheDocument();++ act(() => {+ persistTwoFactorSetupToken('refreshed-token');+ });++ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ fireEvent.click(screen.getByTestId('generate'));+ expect(mockEnableMutate).toHaveBeenCalledWith(+ { tempToken: 'refreshed-token' },+ expect.any(Object),+ );+ });++ it('adopts a setup token handed off before its listener was installed', () => {+ function LateHandOff() {+ useLayoutEffect(() => {+ persistTwoFactorSetupToken('late-token');+ }, []);+ return null;+ }+ render(+ <MemoryRouter initialEntries={['/login/2fa/setup']}>+ <TwoFactorSetupScreen />+ <LateHandOff />+ </MemoryRouter>,+ );++ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ fireEvent.click(screen.getByTestId('generate'));+ expect(mockEnableMutate).toHaveBeenCalledWith({ tempToken: 'late-token' }, expect.any(Object));+ });++ it('keeps the token it started with when another is handed off mid-flow', () => {+ renderScreen('setup-token');++ act(() => {+ persistTwoFactorSetupToken('other-token');+ });++ fireEvent.click(screen.getByTestId('generate'));+ expect(mockEnableMutate).toHaveBeenCalledWith({ tempToken: 'setup-token' }, expect.any(Object));+ });++ it('offers a way back to sign-in when the setup credential is missing', () => {+ const router = createMemoryRouter(+ [+ { path: '/login/2fa/setup', element: <TwoFactorSetupScreen /> },+ { path: '/login', element: <div data-testid="login-page" /> },+ ],+ { initialEntries: ['/login/2fa/setup'] },+ );+ render(<RouterProvider router={router} />);++ expect(screen.getByRole('alert')).toHaveTextContent('com_auth_two_factor_setup_expired');++ /** The layout withholds the sign-in controls on this path, so the screen has to carry its own+ * way out or a reload only replays the same empty state. */+ fireEvent.click(screen.getByRole('button', { name: 'com_auth_back_to_login' }));++ expect(router.state.location.pathname).toBe('/login');+ expect(screen.getByTestId('login-page')).toBeInTheDocument();+ });++ it('enrolls, confirms, and requires backup-code download before completion', () => {+ renderScreen();++ expect(screen.getByText('com_auth_two_factor_setup_required_description')).toHaveClass(+ 'text-text-primary',+ );++ fireEvent.click(screen.getByTestId('generate'));+ expect(mockEnableMutate).toHaveBeenCalledWith(+ { tempToken: 'setup-token' },+ expect.objectContaining({ onSuccess: expect.any(Function) }),+ );++ act(() => {+ mockEnableMutate.mock.calls[0][1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:[email protected]?secret=ABC123&issuer=LibreChat',+ backupCodes: ['backup01'],+ });+ });+ expect(screen.getByTestId('two-factor-setup-phase')).toHaveFocus();+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));++ expect(mockConfirmMutate).toHaveBeenCalledWith(+ { tempToken: 'setup-token', token: '123456' },+ expect.objectContaining({ onSuccess: expect.any(Function) }),+ );++ act(() => {+ mockConfirmMutate.mock.calls[0][1].onSuccess({+ backupCodes: ['confirmed-backup01'],+ acknowledgementToken: 'acknowledgement-token',+ });+ });+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();+ expect(screen.getByTestId('complete')).toBeDisabled();++ fireEvent.click(screen.getByTestId('download'));+ expect(screen.getByTestId('complete')).toBeEnabled();+ fireEvent.click(screen.getByTestId('complete'));+ expect(mockAcknowledgeMutate).toHaveBeenCalledWith(+ { acknowledgementToken: 'acknowledgement-token' },+ expect.objectContaining({ onSuccess: expect.any(Function), onError: expect.any(Function) }),+ );+ expect(mockFinalizeMutate).not.toHaveBeenCalled();++ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });+ expect(mockFinalizeMutate).toHaveBeenCalledWith(+ { finalizationToken: 'finalization-token' },+ expect.objectContaining({ onSuccess: expect.any(Function), onError: expect.any(Function) }),+ );+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();++ act(() => {+ mockFinalizeMutate.mock.calls[0][1].onSuccess({+ token: 'auth-token',+ user: { id: 'user-1' },+ });+ });+ expect(mockCompleteAuthentication).toHaveBeenCalledWith('auth-token', { id: 'user-1' });+ });++ it('keeps startup unauthenticated until backup acknowledgement, then reaches the safe destination', () => {+ sessionStorage.setItem('post_login_redirect_to', '/c/requested?model=test');+ persistTwoFactorSetupToken('setup-token');+ const createRouter = () =>+ createMemoryRouter(+ [+ {+ path: '/',+ element: <StartupAuthRoute />,+ children: [{ path: 'login/2fa/setup', element: <TwoFactorSetupScreen /> }],+ },+ { path: '/c/requested', element: <div data-testid="requested-destination" /> },+ ],+ {+ basename: '/chat',+ initialEntries: ['/chat/login/2fa/setup'],+ },+ );+ const initialRouter = createRouter();+ const initialRender = render(<RouterProvider router={initialRouter} />);+ expect(sessionStorage.getItem('post_login_redirect_to')).toBe('/c/requested?model=test');+ initialRender.unmount();++ const router = createRouter();+ render(<RouterProvider router={router} />);+ expect(sessionStorage.getItem('post_login_redirect_to')).toBe('/c/requested?model=test');++ fireEvent.click(screen.getByTestId('generate'));+ act(() => {+ mockEnableMutate.mock.calls[0][1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:user?secret=ABC123',+ backupCodes: ['backup01'],+ });+ });+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));+ act(() => {+ mockConfirmMutate.mock.calls[0][1].onSuccess({+ backupCodes: ['confirmed-backup01'],+ acknowledgementToken: 'acknowledgement-token',+ });+ });++ expect(screen.getByTestId('complete')).toBeDisabled();+ expect(screen.getByTestId('auth-layout')).toBeInTheDocument();+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();+ expect(router.state.location.pathname).toBe('/chat/login/2fa/setup');++ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));++ expect(router.state.location.pathname).toBe('/chat/login/2fa/setup');+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();+ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });+ act(() => {+ mockFinalizeMutate.mock.calls[0][1].onSuccess({+ token: 'auth-token',+ user: { id: 'user-1' },+ });+ });++ expect(mockCompleteAuthentication).toHaveBeenCalledWith('auth-token', { id: 'user-1' });+ expect(router.state.location.pathname).toBe('/chat/c/requested');+ expect(router.state.location.search).toBe('?model=test');+ expect(screen.getByTestId('requested-destination')).toBeInTheDocument();+ expect(sessionStorage.getItem('post_login_redirect_to')).toBeNull();+ });++ it('keeps the backup phase mounted and shows an actionable error when finalization fails', () => {+ renderScreen();+ fireEvent.click(screen.getByTestId('generate'));+ act(() => {+ mockEnableMutate.mock.calls[0][1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:user?secret=ABC123',+ backupCodes: ['backup01'],+ });+ });+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));+ act(() => {+ mockConfirmMutate.mock.calls[0][1].onSuccess({+ backupCodes: ['confirmed-backup01'],+ acknowledgementToken: 'acknowledgement-token',+ });+ });+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));+ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });+ act(() => mockFinalizeMutate.mock.calls[0][1].onError(new Error('network error')));++ expect(screen.getByTestId('complete')).toBeInTheDocument();+ expect(screen.getByRole('alert')).toHaveTextContent('com_auth_two_factor_setup_finalize_error');+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();+ });++ function reachBackupPhase(acknowledgementToken = 'acknowledgement-token') {+ fireEvent.click(screen.getByTestId('generate'));+ act(() => {+ mockEnableMutate.mock.calls.at(-1)?.[1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:user?secret=ABC123',+ backupCodes: ['backup01'],+ });+ });+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));+ act(() => {+ mockConfirmMutate.mock.calls.at(-1)?.[1].onSuccess({+ backupCodes: ['confirmed-backup01'],+ acknowledgementToken,+ });+ });+ }++ it('retries a failed finalization with the issued credential instead of replaying acknowledgement', () => {+ renderScreen();+ reachBackupPhase();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));+ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });+ act(() => mockFinalizeMutate.mock.calls[0][1].onError(new Error('network error')));++ fireEvent.click(screen.getByTestId('complete'));++ expect(mockAcknowledgeMutate).toHaveBeenCalledTimes(1);+ expect(mockFinalizeMutate).toHaveBeenCalledTimes(2);+ expect(mockFinalizeMutate.mock.calls[1][0]).toEqual({+ finalizationToken: 'finalization-token',+ });++ act(() => {+ mockFinalizeMutate.mock.calls[1][1].onSuccess({+ token: 'auth-token',+ user: { id: 'user-1' },+ });+ });+ expect(mockCompleteAuthentication).toHaveBeenCalledWith('auth-token', { id: 'user-1' });+ });++ /** A consumed one-time nonce answers 400, unlike the 401 an unusable setup token returns. */+ const spentCredentialError = { response: { status: 400 } };++ it('restarts sign-in when a spent acknowledgement credential is replayed', () => {+ renderScreen();+ reachBackupPhase();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));++ act(() => mockAcknowledgeMutate.mock.calls[0][1].onError(spentCredentialError));++ /** Retrying a nonce the server already burned can never succeed, so the flow has to reset. */+ expect(readTwoFactorSetupToken()).toBe('');+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ });++ it('restarts sign-in when a spent finalization credential is replayed', () => {+ renderScreen();+ reachBackupPhase();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));+ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });++ act(() => mockFinalizeMutate.mock.calls[0][1].onError(spentCredentialError));++ expect(readTwoFactorSetupToken()).toBe('');+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();+ });++ it('keeps a rejected verification code on the verify phase', () => {+ renderScreen();+ fireEvent.click(screen.getByTestId('generate'));+ act(() => {+ mockEnableMutate.mock.calls[0][1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:user?secret=ABC123',+ backupCodes: ['backup01'],+ });+ });+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));++ act(() => mockConfirmMutate.mock.calls[0][1].onError(spentCredentialError));++ /** A wrong code shares the 400, so only the one-time transitions may treat it as spent. */+ expect(screen.getByRole('alert')).toHaveTextContent('com_ui_2fa_invalid');+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ expect(screen.getByTestId('verify')).toBeInTheDocument();+ });++ /**+ * Every setup route gates on the enforcement policy and on the ban list before it reaches a+ * controller, and both answer 403. Neither can be satisfied from this screen, so all four+ * mutations have to leave rather than keep a credential the server will never accept again.+ */+ const retiredFlowError = { response: { status: 403 } };++ it('restarts sign-in when enforcement is withdrawn during enrollment', () => {+ renderScreen();+ fireEvent.click(screen.getByTestId('generate'));++ act(() => mockEnableMutate.mock.calls[0][1].onError(retiredFlowError));++ expect(readTwoFactorSetupToken()).toBe('');+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ });++ it('restarts sign-in when enforcement is withdrawn at verification', () => {+ renderScreen();+ fireEvent.click(screen.getByTestId('generate'));+ act(() => {+ mockEnableMutate.mock.calls[0][1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:user?secret=ABC123',+ backupCodes: ['backup01'],+ });+ });+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));++ act(() => mockConfirmMutate.mock.calls[0][1].onError(retiredFlowError));++ /** A wrong code and a retired flow both reach this handler, so only the 403 may reset it. */+ expect(readTwoFactorSetupToken()).toBe('');+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ });++ it('restarts sign-in when enforcement is withdrawn at acknowledgement', () => {+ renderScreen();+ reachBackupPhase();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));++ act(() => mockAcknowledgeMutate.mock.calls[0][1].onError(retiredFlowError));++ expect(readTwoFactorSetupToken()).toBe('');+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ });++ it('restarts sign-in when enforcement is withdrawn at finalization', () => {+ renderScreen();+ reachBackupPhase();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));+ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });++ act(() => mockFinalizeMutate.mock.calls[0][1].onError(retiredFlowError));++ expect(readTwoFactorSetupToken()).toBe('');+ expect(mockCompleteAuthentication).not.toHaveBeenCalled();+ });++ it('keeps a rate-limited verification on the verify phase', () => {+ renderScreen();+ fireEvent.click(screen.getByTestId('generate'));+ act(() => {+ mockEnableMutate.mock.calls[0][1].onSuccess({+ otpauthUrl: 'otpauth://totp/LibreChat:user?secret=ABC123',+ backupCodes: ['backup01'],+ });+ });+ fireEvent.click(screen.getByTestId('qr-next'));+ fireEvent.click(screen.getByTestId('enter-code'));+ fireEvent.click(screen.getByTestId('verify'));++ act(() => mockConfirmMutate.mock.calls[0][1].onError({ response: { status: 429 } }));++ /** Throttling clears on its own, so it must not be swept up with the retired-flow 403. */+ expect(screen.getByRole('alert')).toHaveTextContent('com_ui_2fa_invalid');+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ expect(screen.getByTestId('verify')).toBeInTheDocument();+ });++ it('discards the stale finalization credential when confirmation is repeated', () => {+ renderScreen();+ reachBackupPhase();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));+ act(() => {+ mockAcknowledgeMutate.mock.calls[0][1].onSuccess({ finalizationToken: 'finalization-token' });+ });+ act(() => mockFinalizeMutate.mock.calls[0][1].onError(new Error('network error')));++ act(() => {+ mockConfirmMutate.mock.calls.at(-1)?.[1].onSuccess({+ backupCodes: ['rotated-backup01'],+ acknowledgementToken: 'rotated-acknowledgement-token',+ });+ });++ expect(screen.getByTestId('complete')).toBeDisabled();+ fireEvent.click(screen.getByTestId('download'));+ fireEvent.click(screen.getByTestId('complete'));++ expect(mockAcknowledgeMutate).toHaveBeenCalledTimes(2);+ expect(mockAcknowledgeMutate.mock.calls[1][0]).toEqual({+ acknowledgementToken: 'rotated-acknowledgement-token',+ });+ expect(mockFinalizeMutate).toHaveBeenCalledTimes(1);+ });+});diff --git a/client/src/components/Auth/index.ts b/client/src/components/Auth/index.tsindex afde148015..a7cd4fa2dc 100644--- a/client/src/components/Auth/index.ts+++ b/client/src/components/Auth/index.ts@@ -5,3 +5,4 @@ export { default as VerifyEmail } from './VerifyEmail';export { default as ApiErrorWatcher } from './ApiErrorWatcher';export { default as RequestPasswordReset } from './RequestPasswordReset';export { default as TwoFactorScreen } from './TwoFactorScreen';+export { default as TwoFactorSetupScreen } from './TwoFactorSetupScreen';diff --git a/client/src/components/Nav/Settings/__tests__/Sidebar.spec.tsx b/client/src/components/Nav/Settings/__tests__/Sidebar.spec.tsxindex 402f9cedd6..c64c29baae 100644--- a/client/src/components/Nav/Settings/__tests__/Sidebar.spec.tsx+++ b/client/src/components/Nav/Settings/__tests__/Sidebar.spec.tsx@@ -18,6 +18,7 @@ const ctx: SettingsContextValue = {emailEnabled: true,allowEmailChange: true,passkeyLoginEnabled: false,+ isTwoFactorPolicyProvider: true,twoFactorEnabled: false,allowAccountDeletion: true,aboutEnabled: false,diff --git a/client/src/components/Nav/Settings/__tests__/context.spec.tsx b/client/src/components/Nav/Settings/__tests__/context.spec.tsxnew file mode 100644index 0000000000..c6add06fe1--- /dev/null+++ b/client/src/components/Nav/Settings/__tests__/context.spec.tsx@@ -0,0 +1,78 @@+import { RecoilRoot } from 'recoil';+import { renderHook } from '@testing-library/react';+import type { TUser } from 'librechat-data-provider';+import type { PropsWithChildren } from 'react';+import { useSettingsContext } from '../context';++type LegacyProviderUser = Omit<TUser, 'provider'> & { provider?: string | null };++let mockUser: LegacyProviderUser | undefined;++jest.mock('~/hooks', () => ({+ useAuthContext: () => ({ user: mockUser }),+ useHasAccess: () => false,+ useGetAgentsConfig: () => ({ agentsConfig: undefined }),+}));++jest.mock('~/hooks/usePersonalizationAccess', () => () => ({+ hasAnyPersonalizationFeature: false,+ hasMemoryOptOut: false,+}));++jest.mock('~/data-provider', () => ({+ useGetStartupConfig: () => ({ data: undefined }),+}));++jest.mock('../../SettingsTabs/ProviderKeys/useProviderKeys', () => () => []);++const baseUser: Omit<TUser, 'provider'> = {+ id: 'user-1',+ username: 'policy-user',+ email: '[email protected]',+ name: 'Policy User',+ avatar: '',+ role: 'USER',+ createdAt: '2026-01-01T00:00:00.000Z',+ updatedAt: '2026-01-01T00:00:00.000Z',+};++const wrapper = ({ children }: PropsWithChildren) => <RecoilRoot>{children}</RecoilRoot>;++function policyProviderFor(user: LegacyProviderUser | undefined): boolean {+ mockUser = user;+ return renderHook(() => useSettingsContext(), { wrapper }).result.current+ .isTwoFactorPolicyProvider;+}++const userWith = (provider: string | null | undefined): LegacyProviderUser => ({+ ...baseUser,+ provider,+});++describe('useSettingsContext two-factor policy scope', () => {+ afterEach(() => {+ mockUser = undefined;+ });++ it.each(['local', 'ldap', null, undefined])(+ 'derives the policy capability from an authenticated user with provider %s',+ (provider) => {+ expect(policyProviderFor(userWith(provider))).toBe(true);+ },+ );++ it('keeps a legacy user document with no provider field eligible', () => {+ expect(policyProviderFor(baseUser)).toBe(true);+ });++ it.each(['openid', 'google', 'saml'])(+ 'withholds the policy capability from federated provider %s',+ (provider) => {+ expect(policyProviderFor(userWith(provider))).toBe(false);+ },+ );++ it('withholds the policy capability when no authenticated user is loaded', () => {+ expect(policyProviderFor(undefined)).toBe(false);+ });+});diff --git a/client/src/components/Nav/Settings/__tests__/registry.spec.ts b/client/src/components/Nav/Settings/__tests__/registry.spec.tsindex 84edb5fcee..c857482a44 100644--- a/client/src/components/Nav/Settings/__tests__/registry.spec.ts+++ b/client/src/components/Nav/Settings/__tests__/registry.spec.ts@@ -1,5 +1,5 @@import { isValidElementType } from 'react-is';-import { SettingsTabValues } from 'librechat-data-provider';+import { SettingsTabValues, isTwoFactorPolicyProvider } from 'librechat-data-provider';import type { SettingsContextValue } from '../types';import en from '~/locales/en/translation.json';import { registry } from '../registry';@@ -20,6 +20,7 @@ const settingsContext: SettingsContextValue = {emailEnabled: true,allowEmailChange: true,passkeyLoginEnabled: false,+ isTwoFactorPolicyProvider: true,twoFactorEnabled: false,allowAccountDeletion: true,aboutEnabled: false,@@ -31,6 +32,14 @@ const settingsContext: SettingsContextValue = {replyNotificationSoundAllowed: true,};+const policyProviders = ['local', 'ldap', null, undefined];+const federatedProviders = ['openid', 'google', 'saml'];++const contextForProvider = (provider: string | null | undefined): SettingsContextValue => ({+ ...settingsContext,+ isTwoFactorPolicyProvider: isTwoFactorPolicyProvider(provider),+});+describe('settings registry', () => {it('has unique ids', () => {const ids = registry.map((e) => e.id);@@ -57,6 +66,49 @@ describe('settings registry', () => {}});+ describe('two-factor security visibility', () => {+ const twoFactorEntry = registry.find((entry) => entry.id === 'twoFactor');+ const backupCodesEntry = registry.find((entry) => entry.id === 'backupCodes');++ it.each(policyProviders)(+ 'shows two-factor authentication for policy provider %s',+ (provider) => {+ expect(twoFactorEntry?.show?.(contextForProvider(provider))).toBe(true);+ },+ );++ it.each(federatedProviders)(+ 'hides two-factor authentication for federated provider %s',+ (provider) => {+ expect(twoFactorEntry?.show?.(contextForProvider(provider))).toBe(false);+ },+ );++ it.each(policyProviders)('shows backup codes for enrolled policy provider %s', (provider) => {+ expect(+ backupCodesEntry?.show?.({ ...contextForProvider(provider), twoFactorEnabled: true }),+ ).toBe(true);+ });++ it.each(federatedProviders)(+ 'hides backup codes for enrolled federated provider %s',+ (provider) => {+ expect(+ backupCodesEntry?.show?.({ ...contextForProvider(provider), twoFactorEnabled: true }),+ ).toBe(false);+ },+ );++ it.each(policyProviders)(+ 'hides backup codes before enrollment for policy provider %s',+ (provider) => {+ expect(+ backupCodesEntry?.show?.({ ...contextForProvider(provider), twoFactorEnabled: false }),+ ).toBe(false);+ },+ );+ });+describe('Langfuse connection visibility', () => {const langfuseEntry = registry.find((entry) => entry.id === 'langfuseConnection');diff --git a/client/src/components/Nav/Settings/context.tsx b/client/src/components/Nav/Settings/context.tsxindex 6be7e0d49a..55aaaacdbc 100644--- a/client/src/components/Nav/Settings/context.tsx+++ b/client/src/components/Nav/Settings/context.tsx@@ -1,6 +1,11 @@import { useMemo } from 'react';import { useRecoilValue } from 'recoil';-import { AgentCapabilities, PermissionTypes, Permissions } from 'librechat-data-provider';+import {+ AgentCapabilities,+ Permissions,+ PermissionTypes,+ isTwoFactorPolicyProvider,+} from 'librechat-data-provider';import type { SettingsContextValue } from './types';import useProviderKeys from '../SettingsTabs/ProviderKeys/useProviderKeys';import { useHasAccess, useAuthContext, useGetAgentsConfig } from '~/hooks';@@ -34,6 +39,7 @@ export function useSettingsContext(): SettingsContextValue {const emailEnabled = startupConfig?.emailEnabled === true;const allowEmailChange = startupConfig?.allowEmailChange === true;const passkeyLoginEnabled = startupConfig?.passkeyLoginEnabled === true;+ const twoFactorPolicyProvider = user != null && isTwoFactorPolicyProvider(user.provider);const twoFactorEnabled = user?.twoFactorEnabled === true;const allowAccountDeletion = startupConfig?.allowAccountDeletion !== false;const aboutEnabled = startupConfig?.interface?.buildInfo !== false;@@ -69,6 +75,7 @@ export function useSettingsContext(): SettingsContextValue {emailEnabled,allowEmailChange,passkeyLoginEnabled,+ isTwoFactorPolicyProvider: twoFactorPolicyProvider,twoFactorEnabled,allowAccountDeletion,aboutEnabled,@@ -92,6 +99,7 @@ export function useSettingsContext(): SettingsContextValue {emailEnabled,allowEmailChange,passkeyLoginEnabled,+ twoFactorPolicyProvider,twoFactorEnabled,allowAccountDeletion,aboutEnabled,diff --git a/client/src/components/Nav/Settings/registry.tsx b/client/src/components/Nav/Settings/registry.tsxindex 019d69dd92..c7ee1271ae 100644--- a/client/src/components/Nav/Settings/registry.tsx+++ b/client/src/components/Nav/Settings/registry.tsx@@ -799,7 +799,7 @@ export const registry: SettingEntry[] = [tab: ACCOUNT,section: 'security',labelKey: 'com_ui_settings_label_2fa',- show: (ctx) => ctx.isLocalProvider,+ show: (ctx) => ctx.isTwoFactorPolicyProvider,Component: EnableTwoFactorItem,},{@@ -807,7 +807,7 @@ export const registry: SettingEntry[] = [tab: ACCOUNT,section: 'security',labelKey: 'com_ui_settings_label_backup_codes',- show: (ctx) => ctx.isLocalProvider && ctx.twoFactorEnabled,+ show: (ctx) => ctx.isTwoFactorPolicyProvider && ctx.twoFactorEnabled,Component: BackupCodesItem,},{diff --git a/client/src/components/Nav/Settings/types.ts b/client/src/components/Nav/Settings/types.tsindex 592df6a86b..b1f4a64612 100644--- a/client/src/components/Nav/Settings/types.ts+++ b/client/src/components/Nav/Settings/types.ts@@ -51,6 +51,7 @@ export interface SettingsContextValue {emailEnabled: boolean;allowEmailChange: boolean;passkeyLoginEnabled: boolean;+ isTwoFactorPolicyProvider: boolean;twoFactorEnabled: boolean;allowAccountDeletion: boolean;aboutEnabled: boolean;diff --git a/client/src/components/Nav/SettingsTabs/Account/DisableTwoFactorToggle.tsx b/client/src/components/Nav/SettingsTabs/Account/DisableTwoFactorToggle.tsxindex 73eaf0c5a1..1de57b3a74 100644--- a/client/src/components/Nav/SettingsTabs/Account/DisableTwoFactorToggle.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/DisableTwoFactorToggle.tsx@@ -1,11 +1,10 @@import React from 'react';-// import { motion } from 'framer-motion';-// import { LockIcon, UnlockIcon } from 'lucide-react';-import { Label, Button } from '@librechat/client';+import { Button, TooltipAnchor } from '@librechat/client';import { useLocalize } from '~/hooks';interface DisableTwoFactorToggleProps {enabled: boolean;+ required?: boolean;onChange: () => void;disabled?: boolean;buttonRef?: React.RefObject<HTMLButtonElement>;@@ -13,28 +12,46 @@ interface DisableTwoFactorToggleProps {export const DisableTwoFactorToggle: React.FC<DisableTwoFactorToggleProps> = ({enabled,+ required,onChange,disabled,buttonRef,}) => {const localize = useLocalize();+ const isDisableBlockedByPolicy = enabled && required === true;+ const buttonLabel = enabled ? localize('com_ui_2fa_disable') : localize('com_ui_2fa_enable');+ const actionButton = (+ <Button+ ref={buttonRef}+ variant={enabled ? 'destructive' : 'outline'}+ onClick={isDisableBlockedByPolicy ? undefined : onChange}+ disabled={disabled}+ aria-disabled={isDisableBlockedByPolicy || disabled || undefined}+ className={isDisableBlockedByPolicy ? 'cursor-not-allowed' : undefined}+ aria-haspopup="dialog"+ aria-controls="two-factor-authentication-dialog"+ >+ {buttonLabel}+ </Button>+ );return (<div className="flex items-center justify-between"><div className="flex items-center space-x-2">- <Label> {localize('com_nav_2fa')}</Label>+ <span className="text-text-primary text-sm">{localize('com_nav_2fa')}</span></div><div className="flex items-center gap-3">- <Button- ref={buttonRef}- variant={enabled ? 'destructive' : 'outline'}- onClick={onChange}- disabled={disabled}- aria-haspopup="dialog"- aria-controls="two-factor-authentication-dialog"- >- {enabled ? localize('com_ui_2fa_disable') : localize('com_ui_2fa_enable')}- </Button>+ {isDisableBlockedByPolicy ? (+ <TooltipAnchor+ description={localize('com_ui_2fa_required')}+ aria-label={`${buttonLabel}: ${localize('com_ui_2fa_required')}`}+ data-testid="required-2fa-disable-control"+ className="inline-flex cursor-not-allowed"+ render={actionButton}+ />+ ) : (+ actionButton+ )}</div></div>);diff --git a/client/src/components/Nav/SettingsTabs/Account/TwoFactorAuthentication.tsx b/client/src/components/Nav/SettingsTabs/Account/TwoFactorAuthentication.tsxindex 6baaa76c66..8d4fd77f4d 100644--- a/client/src/components/Nav/SettingsTabs/Account/TwoFactorAuthentication.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/TwoFactorAuthentication.tsx@@ -2,6 +2,11 @@ import React, { useCallback, useState, useRef } from 'react';import { useSetRecoilState } from 'recoil';import { SmartphoneIcon } from 'lucide-react';import { motion, AnimatePresence } from 'framer-motion';+import {+ isTwoFactorPolicyProvider,+ type TUser,+ type TVerify2FARequest,+} from 'librechat-data-provider';import {OGDialog,useToastContext,@@ -10,12 +15,12 @@ import {OGDialogTitle,Progress,} from '@librechat/client';-import type { TUser, TVerify2FARequest } from 'librechat-data-provider';import type { Variants } from 'framer-motion';import {useConfirmTwoFactorMutation,useDisableTwoFactorMutation,useEnableTwoFactorMutation,+ useGetStartupConfig,useVerifyTwoFactorMutation,} from '~/data-provider';import { SetupPhase, QRPhase, VerifyPhase, BackupPhase, DisablePhase } from './TwoFactorPhases';@@ -35,6 +40,7 @@ const phaseVariants: Variants = {const TwoFactorAuthentication: React.FC = () => {const localize = useLocalize();const { user } = useAuthContext();+ const { data: startupConfig } = useGetStartupConfig();const setUser = useSetRecoilState(store.user);const { showToast } = useToastContext();const showError = useTwoFactorError();@@ -54,16 +60,23 @@ const TwoFactorAuthentication: React.FC = () => {const { mutate: verify2FAMutate, isLoading: isVerifying } = useVerifyTwoFactorMutation();const { mutate: disable2FAMutate, isLoading: isDisabling } = useDisableTwoFactorMutation();- const steps = ['Setup', 'Scan QR', 'Verify', 'Backup'];- const phasesLabel: Record<Phase, string> = {- setup: 'Setup',- qr: 'Scan QR',- verify: 'Verify',- backup: 'Backup',- disable: '',+ const steps = [+ localize('com_ui_2fa_setup'),+ localize('com_ui_2fa_scan_qr'),+ localize('com_ui_verify'),+ localize('com_ui_backup_codes'),+ ];+ const phaseIndex: Record<Phase, number> = {+ setup: 0,+ qr: 1,+ verify: 2,+ backup: 3,+ disable: -1,};-- const currentStep = steps.indexOf(phasesLabel[phase]);+ const currentStep = phaseIndex[phase];+ const isTwoFactorRequired =+ startupConfig?.twoFactorAuthenticationRequired === true &&+ isTwoFactorPolicyProvider(user?.provider);const resetState = useCallback(() => {if (user?.twoFactorEnabled && otpauthUrl) {@@ -203,6 +216,7 @@ const TwoFactorAuthentication: React.FC = () => {><DisableTwoFactorToggleenabled={!!user?.twoFactorEnabled}+ required={isTwoFactorRequired}onChange={() => setDialogOpen(true)}disabled={isVerifying || isDisabling || isGenerating}buttonRef={buttonRef}@@ -226,23 +240,18 @@ const TwoFactorAuthentication: React.FC = () => {? localize('com_ui_2fa_disable'): localize('com_ui_2fa_setup')}</OGDialogTitle>- {user?.twoFactorEnabled && phase !== 'disable' && (+ {phase !== 'disable' && (<div className="mt-4 space-y-3"><Progress- value={(steps.indexOf(phasesLabel[phase]) / (steps.length - 1)) * 100}+ value={(currentStep / (steps.length - 1)) * 100}className="h-2 rounded-full"/>- <div className="flex justify-between text-sm">+ <div className="text-text-primary flex justify-between text-sm">{steps.map((step, index) => (<motion.spankey={step}- animate={{- color:- currentStep >= index- ? 'rgb(var(--text-primary))'- : 'rgb(var(--text-tertiary))',- }}- className="font-medium"+ animate={{ opacity: currentStep >= index ? 1 : 0.7 }}+ className="text-text-primary font-medium">{step}</motion.span>diff --git a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/BackupPhase.tsx b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/BackupPhase.tsxindex 48e6fc1bf6..82c3df65d4 100644--- a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/BackupPhase.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/BackupPhase.tsx@@ -1,7 +1,7 @@import React from 'react';import { motion } from 'framer-motion';import { Download } from 'lucide-react';-import { Button, Label } from '@librechat/client';+import { Button } from '@librechat/client';import { useLocalize } from '~/hooks';const fadeAnimation = {@@ -17,6 +17,7 @@ interface BackupPhaseProps {backupCodes: string[];onDownload: () => void;downloaded: boolean;+ isCompleting?: boolean;}export const BackupPhase: React.FC<BackupPhaseProps> = ({@@ -24,35 +25,43 @@ export const BackupPhase: React.FC<BackupPhaseProps> = ({onDownload,downloaded,onNext,+ isCompleting = false,}) => {const localize = useLocalize();return (- <motion.div {...fadeAnimation} className="space-y-6">- <Label className="break-keep text-sm">{localize('com_ui_download_backup_tooltip')}</Label>- <div className="grid grid-cols-2 gap-4 rounded-xl bg-surface-secondary p-6">+ <motion.div {...fadeAnimation} className="text-text-primary space-y-6">+ <p className="text-text-primary text-sm break-keep">+ {localize('com_ui_download_backup_tooltip')}+ </p>+ <div className="bg-surface-secondary grid grid-cols-2 gap-4 rounded-xl p-6">{backupCodes.map((code, index) => (<motion.divkey={code}initial={{ opacity: 0, y: 20 }}animate={{ opacity: 1, y: 0 }}transition={{ delay: index * 0.1 }}- className="rounded-lg bg-surface-tertiary p-3"+ className="bg-surface-tertiary rounded-lg p-3"><div className="flex items-center justify-between">- <span className="hidden text-sm text-text-secondary sm:inline">#{index + 1}</span>- <span className="font-mono text-lg">{code}</span>+ <span className="text-text-primary hidden text-sm sm:inline">#{index + 1}</span>+ <span className="text-text-primary font-mono text-lg">{code}</span></div></motion.div>))}</div><div className="flex gap-4">- <Button variant="outline" onClick={onDownload} className="flex-1 gap-2">+ <Button+ variant="outline"+ onClick={onDownload}+ className="flex-1 gap-2"+ aria-label={localize('com_ui_download_backup')}+ ><Download className="h-4 w-4" aria-hidden="true" /><span className="hidden sm:inline">{localize('com_ui_download_backup')}</span></Button>- <Button onClick={onNext} disabled={!downloaded} className="flex-1">- {localize('com_ui_complete_setup')}+ <Button onClick={onNext} disabled={!downloaded || isCompleting} className="flex-1">+ {isCompleting ? localize('com_ui_loading') : localize('com_ui_complete_setup')}</Button></div></motion.div>diff --git a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/DisablePhase.tsx b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/DisablePhase.tsxindex 2056ba5860..277e692d40 100644--- a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/DisablePhase.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/DisablePhase.tsx@@ -31,9 +31,12 @@ export const DisablePhase: React.FC<DisablePhaseProps> = ({ onDisable, isDisabliconst [useBackup, setUseBackup] = useState(false);return (- <motion.div {...fadeAnimation} className="space-y-8">+ <motion.div {...fadeAnimation} className="text-text-primary space-y-8"><div className="flex justify-center"><InputOTP+ aria-label={localize(+ useBackup ? 'com_ui_use_backup_code' : 'com_ui_2fa_verification_required',+ )}value={token}onChange={setToken}maxLength={useBackup ? 8 : 6}@@ -81,7 +84,7 @@ export const DisablePhase: React.FC<DisablePhaseProps> = ({ onDisable, isDisablitype="button"variant="link"onClick={() => setUseBackup(!useBackup)}- className="h-auto p-0 text-sm text-text-primary hover:underline"+ className="text-text-primary h-auto p-0 text-sm hover:underline">{useBackup ? localize('com_ui_use_2fa_code') : localize('com_ui_use_backup_code')}</Button>diff --git a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/QRPhase.tsx b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/QRPhase.tsxindex 5bce67034e..6a9b9d47af 100644--- a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/QRPhase.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/QRPhase.tsx@@ -1,7 +1,7 @@import React from 'react';import { motion } from 'framer-motion';import { QRCodeSVG } from 'qrcode.react';-import { Button, Label, SecretInput } from '@librechat/client';+import { Button, SecretInput } from '@librechat/client';import { useLocalize } from '~/hooks';const fadeAnimation = {@@ -23,19 +23,17 @@ export const QRPhase: React.FC<QRPhaseProps> = ({ secret, otpauthUrl, onNext })const localize = useLocalize();return (- <motion.div {...fadeAnimation} className="space-y-6">+ <motion.div {...fadeAnimation} className="text-text-primary space-y-6"><div className="flex flex-col items-center space-y-6"><motion.divinitial={{ scale: 0.8, opacity: 0 }}animate={{ scale: 1, opacity: 1 }}- className="rounded-2xl bg-surface-fixed p-4 shadow-lg"+ className="bg-surface-fixed rounded-2xl p-4 shadow-lg">- <QRCodeSVG value={otpauthUrl} size={240} />+ <QRCodeSVG value={otpauthUrl} size={240} title={localize('com_ui_2fa_scan_qr')} /></motion.div><div className="w-full space-y-3">- <Label className="text-sm font-medium text-text-secondary">- {localize('com_ui_secret_key')}- </Label>+ <p className="text-text-primary text-sm font-medium">{localize('com_ui_secret_key')}</p><SecretInputvalue={secret}readOnlydiff --git a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/SetupPhase.tsx b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/SetupPhase.tsxindex b7df1d65d7..0e4f72d7ad 100644--- a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/SetupPhase.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/SetupPhase.tsx@@ -22,9 +22,9 @@ export const SetupPhase: React.FC<SetupPhaseProps> = ({ isGenerating, onGenerateconst localize = useLocalize();return (- <motion.div {...fadeAnimation} className="space-y-6">- <div className="rounded-xl bg-surface-secondary p-6">- <h3 className="mb-4 flex justify-center text-lg font-medium">+ <motion.div {...fadeAnimation} className="text-text-primary space-y-6">+ <div className="bg-surface-secondary rounded-xl p-6 sm:-mx-4">+ <h3 className="text-text-primary mb-4 flex justify-center text-lg font-medium">{localize('com_ui_2fa_account_security')}</h3><Buttondiff --git a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/VerifyPhase.tsx b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/VerifyPhase.tsxindex b6c4acdb47..071522c506 100644--- a/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/VerifyPhase.tsx+++ b/client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/VerifyPhase.tsx@@ -1,5 +1,6 @@import React from 'react';import { motion } from 'framer-motion';+import { REGEXP_ONLY_DIGITS } from 'input-otp';import {Button,InputOTP,@@ -7,7 +8,6 @@ import {InputOTPSeparator,InputOTPSlot,} from '@librechat/client';-import { REGEXP_ONLY_DIGITS } from 'input-otp';import { useLocalize } from '~/hooks';const fadeAnimation = {@@ -34,9 +34,10 @@ export const VerifyPhase: React.FC<VerifyPhaseProps> = ({const localize = useLocalize();return (- <motion.div {...fadeAnimation} className="space-y-8">+ <motion.div {...fadeAnimation} className="text-text-primary space-y-8"><div className="flex justify-center"><InputOTP+ aria-label={localize('com_ui_2fa_verification_required')}value={token}onChange={onTokenChange}maxLength={6}diff --git a/client/src/components/Nav/SettingsTabs/Account/__tests__/DisableTwoFactorToggle.spec.tsx b/client/src/components/Nav/SettingsTabs/Account/__tests__/DisableTwoFactorToggle.spec.tsxnew file mode 100644index 0000000000..732f6c0e66--- /dev/null+++ b/client/src/components/Nav/SettingsTabs/Account/__tests__/DisableTwoFactorToggle.spec.tsx@@ -0,0 +1,39 @@+/**+ * @jest-environment @happy-dom/jest-environment+ */+import React from 'react';+import { fireEvent, render, screen } from '@testing-library/react';+import { DisableTwoFactorToggle } from '../DisableTwoFactorToggle';++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => key,+}));++describe('DisableTwoFactorToggle', () => {+ it('shows a disabled control with the policy reason when 2FA is required', async () => {+ const onChange = jest.fn();+ render(<DisableTwoFactorToggle enabled={true} required={true} onChange={onChange} />);++ const button = screen.getByRole('button', {+ name: 'com_ui_2fa_disable: com_ui_2fa_required',+ });+ const tooltipTrigger = screen.getByTestId('required-2fa-disable-control');++ expect(button).toHaveAttribute('aria-disabled', 'true');+ expect(button).toHaveClass('cursor-not-allowed');+ expect(tooltipTrigger).toHaveClass('cursor-not-allowed');+ expect(tooltipTrigger).toBe(button);++ fireEvent.mouseEnter(tooltipTrigger);+ fireEvent.mouseMove(tooltipTrigger, { screenX: 1 });+ expect(await screen.findByRole('tooltip')).toHaveTextContent('com_ui_2fa_required');+ fireEvent.click(button);+ expect(onChange).not.toHaveBeenCalled();+ });++ it('keeps the disable control when the deployment policy is optional', () => {+ render(<DisableTwoFactorToggle enabled={true} required={false} onChange={jest.fn()} />);++ expect(screen.getByRole('button', { name: 'com_ui_2fa_disable' })).toBeEnabled();+ });+});diff --git a/client/src/data-provider/Auth/mutations.ts b/client/src/data-provider/Auth/mutations.tsindex 02a3211fd6..361b76f31c 100644--- a/client/src/data-provider/Auth/mutations.ts+++ b/client/src/data-provider/Auth/mutations.ts@@ -296,3 +296,35 @@ export const useDeletePasskeyMutation = (): UseMutationResult<},);};+export const useEnableTwoFactorSetupMutation = (): UseMutationResult<+ t.TEnable2FAResponse,+ unknown,+ t.TEnable2FASetupRequest,+ unknown+> => useMutation((payload: t.TEnable2FASetupRequest) => dataService.enableTwoFactorSetup(payload));++export const useConfirmTwoFactorSetupMutation = (): UseMutationResult<+ t.TConfirm2FASetupResponse,+ unknown,+ t.TConfirm2FASetupRequest,+ unknown+> =>+ useMutation((payload: t.TConfirm2FASetupRequest) => dataService.confirmTwoFactorSetup(payload));++export const useAcknowledgeTwoFactorSetupMutation = (): UseMutationResult<+ t.TAcknowledge2FASetupResponse,+ unknown,+ t.TAcknowledge2FASetupRequest,+ unknown+> =>+ useMutation((payload: t.TAcknowledge2FASetupRequest) =>+ dataService.acknowledgeTwoFactorSetup(payload),+ );++export const useFinalizeTwoFactorSetupMutation = (): UseMutationResult<+ t.TFinalize2FASetupResponse,+ unknown,+ t.TFinalize2FASetupRequest,+ unknown+> =>+ useMutation((payload: t.TFinalize2FASetupRequest) => dataService.finalizeTwoFactorSetup(payload));diff --git a/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx b/client/src/hooks/Auth/__tests__/usePasskey.spec.tsxindex 447a432c3a..62ae019165 100644--- a/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx+++ b/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx@@ -1,4 +1,5 @@import { act, renderHook, waitFor } from '@testing-library/react';+import { clearTwoFactorSetupToken, readTwoFactorSetupToken } from 'librechat-data-provider';import { usePasskeySignIn } from '../usePasskey';type Deferred = {@@ -92,4 +93,42 @@ describe('usePasskeySignIn', () => {expect(mockGetPasskeyLoginOptions).toHaveBeenCalledTimes(2);expect(mockStartAuthentication).toHaveBeenCalledTimes(2);});++ describe('after the ceremony', () => {+ const signInWith = async (response: Record<string, unknown>) => {+ mockStartAuthentication.mockImplementation(({ useBrowserAutofill }) =>+ useBrowserAutofill ? deferred().promise : Promise.resolve({ id: 'credential' }),+ );+ mockVerifyPasskeyLogin.mockResolvedValue(response);+ const { result } = renderHook(() => usePasskeySignIn({ enabled: true }));+ await act(async () => {+ await result.current.signIn();+ });+ };++ afterEach(() => {+ clearTwoFactorSetupToken();+ });++ it('sends an account that must enroll to two-factor setup with its credential', async () => {+ await signInWith({+ code: 'TWO_FACTOR_ENROLLMENT_REQUIRED',+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });++ expect(mockNavigate).toHaveBeenCalledWith('/login/2fa/setup', { replace: true });+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ it('sends an enrolled account to the code challenge', async () => {+ await signInWith({ twoFAPending: true, tempToken: 'challenge-token' });++ expect(mockNavigate).toHaveBeenCalledWith('/login/2fa?tempToken=challenge-token', {+ replace: true,+ });+ expect(readTwoFactorSetupToken()).toBeFalsy();+ });+ });});diff --git a/client/src/hooks/Auth/usePasskey.ts b/client/src/hooks/Auth/usePasskey.tsindex 34bfa9d16c..29d1345b00 100644--- a/client/src/hooks/Auth/usePasskey.ts+++ b/client/src/hooks/Auth/usePasskey.ts@@ -1,7 +1,11 @@import { useCallback, useEffect, useRef, useState } from 'react';import { useNavigate } from 'react-router-dom';import { useToastContext } from '@librechat/client';-import { dataService } from 'librechat-data-provider';+import {+ dataService,+ clearTwoFactorSetupToken,+ persistTwoFactorSetupToken,+} from 'librechat-data-provider';import type {TPasskey,TPasskeyTransport,@@ -13,7 +17,13 @@ import type {PublicKeyCredentialRequestOptionsJSON,} from '@simplewebauthn/browser';import type { TranslationKeys } from '~/hooks/useLocalize';-import { SESSION_KEY, withBasePath, isSafeRedirect, REDIRECT_PARAM } from '~/utils/redirect';+import {+ SESSION_KEY,+ withBasePath,+ isSafeRedirect,+ REDIRECT_PARAM,+ persistRedirectToSession,+} from '~/utils/redirect';import { useRegisterPasskeyMutation } from '~/data-provider';import useLocalize from '~/hooks/useLocalize';@@ -117,6 +127,16 @@ export function usePasskeySignIn({ enabled }: { enabled: boolean }) {const complete = useCallback(async (credential: TPasskeyAuthenticationResponse, sessionId: string) => {const result = await dataService.verifyPasskeyLogin({ credential, sessionId });+ clearTwoFactorSetupToken();+ if (result.twoFASetupRequired === true && result.tempToken != null) {+ const redirectTo = new URLSearchParams(window.location.search).get(REDIRECT_PARAM);+ if (redirectTo) {+ persistRedirectToSession(redirectTo);+ }+ persistTwoFactorSetupToken(result.tempToken);+ navigate('/login/2fa/setup', { replace: true });+ return;+ }if (result.twoFAPending === true && result.tempToken != null) {navigate(`/login/2fa?tempToken=${encodeURIComponent(result.tempToken)}`, { replace: true });return;diff --git a/client/src/hooks/AuthContext.tsx b/client/src/hooks/AuthContext.tsxindex 2e343dc14f..69264b7097 100644--- a/client/src/hooks/AuthContext.tsx+++ b/client/src/hooks/AuthContext.tsx@@ -18,17 +18,21 @@ import {setTokenHeader,isSystemRoleName,buildLoginRedirectUrl,+ clearTwoFactorSetupToken,+ persistTwoFactorSetupToken,+ TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE,} from 'librechat-data-provider';import type * as t from 'librechat-data-provider';import type { ReactNode } from 'react';import {isSafeRedirect,getPostLoginRedirect,- dropStoredRedirect,- readStoredRedirect,+ clearPostLoginRedirect,+ persistRedirectToSession,clearComposerDraftStorage,clearRetainedFileDeletions,openFileDeletionRetention,+ isRequiredTwoFactorSetupRoute,} from '~/utils';import {useGetRole,@@ -61,6 +65,15 @@ const endSessionClientState = (): void => {clearRetainedFileDeletions();clearComposerDraftStorage();};+/**+ * Only recognized codes override the HTTP status used by the login error translation.+ */+const getLoginErrorText = (error: TResError): string | undefined => {+ const code = error?.response?.data?.code;+ return code === ErrorTypes.AUTH_CROSS_ORIGIN || code === TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE+ ? code+ : error?.message;+};const AuthContextProvider = ({authConfig,@@ -104,6 +117,12 @@ const AuthContextProvider = ({setIsAuthReady(true);if (isAuthenticated) {setQueriesEnabled(true);+ /**+ * Any accepted full-auth response supersedes a staged enrollment, whichever path minted+ * it. The setup endpoints trust the stored bearer independently of the session, so a+ * token left behind here would let this user finish the previous one's enrollment.+ */+ clearTwoFactorSetupToken();/** The clear on the way out latches retention shut so a DELETE that settles afterwards* cannot write the departing account's payload back in. This is the only place that* knows a new session exists to reopen it for. */@@ -117,16 +136,12 @@ const AuthContextProvider = ({endSessionClientState();}- const searchParams = new URLSearchParams(window.location.search);- const postLoginRedirect = getPostLoginRedirect(searchParams);-const logoutRedirect = logoutRedirectRef.current;logoutRedirectRef.current = undefined;+ /** Callers resolve the post-login destination, so it is consumed exactly once per sign-in. */const finalRedirect =- logoutRedirect ??- postLoginRedirect ??- (redirect && isSafeRedirect(redirect) ? redirect : null);+ logoutRedirect ?? (redirect && isSafeRedirect(redirect) ? redirect : null);if (finalRedirect == null) {return;@@ -136,24 +151,44 @@ const AuthContextProvider = ({}, 50),[navigate, setUser, setQueriesEnabled],);- const doSetError = useTimeout({ callback: (error) => setError(error as string | undefined) });+ const setErrorAfterTimeout = useCallback(+ (error: string | number | boolean | null) => setError(error as string | undefined),+ [],+ );+ const doSetError = useTimeout({ callback: setErrorAfterTimeout });- const loginUser = useLoginUserMutation({+ const { mutate: loginMutate } = useLoginUserMutation({onSuccess: (data: t.TLoginResponse) => {- const { user, token, twoFAPending, tempToken } = data;+ const { user, token, twoFAPending, twoFASetupRequired, tempToken } = data;+ /**+ * A sign-in supersedes whatever enrollment the tab was holding. An abandoned setup token+ * outlives the screen that staged it, so leaving it here would let the next visitor to the+ * setup route finish the previous user's enrollment and take the tab as them.+ */+ clearTwoFactorSetupToken();+ if (twoFASetupRequired) {+ const redirectTo = new URLSearchParams(window.location.search).get('redirect_to');+ if (redirectTo) {+ persistRedirectToSession(redirectTo);+ }+ persistTwoFactorSetupToken(tempToken ?? '');+ navigate('/login/2fa/setup', { replace: true });+ return;+ }if (twoFAPending) {navigate(`/login/2fa?tempToken=${tempToken}`, { replace: true });return;}setError(undefined);- setUserContext({ token, isAuthenticated: true, user, redirect: '/c/new' });+ const redirect =+ getPostLoginRedirect(new URLSearchParams(window.location.search)) ?? '/c/new';+ setUserContext({ token, isAuthenticated: true, user, redirect });},onError: (error: TResError | unknown) => {- const resError = error as TResError;- const code = resError.response?.data?.code;- doSetError(code === ErrorTypes.AUTH_CROSS_ORIGIN ? code : resError.message);+ clearTwoFactorSetupToken();+ doSetError(getLoginErrorText(error as TResError));// Preserve a valid redirect_to across login failures so the deep link survives retries.- // Cannot use buildLoginRedirectUrl() here — it reads the current pathname (already /login)+ // Cannot use buildLoginRedirectUrl() here: it reads the current pathname (already /login)// and would return plain /login, dropping the redirect_to destination.const redirectTo = new URLSearchParams(window.location.search).get('redirect_to');const loginPath =@@ -163,7 +198,7 @@ const AuthContextProvider = ({navigate(loginPath, { replace: true });},});- const logoutUser = useLogoutUserMutation({+ const { mutate: logoutMutate } = useLogoutUserMutation({onSuccess: (data) => {if (data.redirect) {/** data.redirect is the IdP's end_session_endpoint URL: an absolute URL generated@@ -199,19 +234,57 @@ const AuthContextProvider = ({const logout = useCallback((redirect?: string) => {+ clearPostLoginRedirect();+ clearTwoFactorSetupToken();if (redirect) {logoutRedirectRef.current = redirect;}- logoutUser.mutate(undefined);+ logoutMutate(undefined);+ },+ [logoutMutate],+ );++ const completeAuthentication = useCallback(+ (authenticatedToken: string, authenticatedUser: t.TUser) => {+ const redirect =+ getPostLoginRedirect(new URLSearchParams(window.location.search)) ?? '/c/new';+ /** The enrollment credential has done its job; do not leave it live in the tab. */+ clearTwoFactorSetupToken();+ setUser(authenticatedUser);+ setToken(authenticatedToken);+ setTokenHeader(authenticatedToken);+ setIsAuthenticated(true);+ setIsAuthReady(true);+ setQueriesEnabled(true);+ openFileDeletionRetention();+ navigate(redirect, { replace: true });},- [logoutUser],+ [navigate, setQueriesEnabled, setUser],);+ /**+ * The enrollment hand-off normally replaces the document, which discards the session it is+ * redirecting away from. Where session storage is blocked it has to keep the document instead,+ * so this provider stays mounted and that session survives: the user query stays enabled and+ * navigates to the login page the moment it fails, taking the user off the very screen the+ * server is demanding they complete. Land on the state a replaced document would have left, and+ * leave the setup token alone, since the in-memory mirror is then its only copy.+ */+ const clearAuthenticationForRedirect = useCallback(() => {+ endSessionClientState();+ setUser(undefined);+ setToken(undefined);+ setIsAuthenticated(false);+ }, [setUser]);+const userQuery = useGetUserQuery({ enabled: !!(token ?? '') });- const login = (data: t.TLoginUser) => {- loginUser.mutate(data);- };+ const login = useCallback(+ (data: t.TLoginUser) => {+ loginMutate(data);+ },+ [loginMutate],+ );const silentRefresh = useCallback(() => {if (authConfig?.test === true) {@@ -225,10 +298,29 @@ const AuthContextProvider = ({if (isExternalRedirectRef.current) {return;}- const { user, token = '' } = data ?? {};+ const { user, token = '', twoFASetupRequired, tempToken } = data ?? {};+ if (twoFASetupRequired && tempToken) {+ persistTwoFactorSetupToken(tempToken);+ /**+ * Already on the setup route, reached by an enforcement redirect that parked the+ * destination in the query. Replacing the route again would drop that query, and the+ * route itself is not a safe redirect to bank, so enrollment would end at `/c/new`.+ */+ if (isRequiredTwoFactorSetupRoute()) {+ return;+ }+ const baseUrl = apiBaseUrl();+ const rawPath = window.location.pathname;+ const strippedPath =+ baseUrl && (rawPath === baseUrl || rawPath.startsWith(baseUrl + '/'))+ ? rawPath.slice(baseUrl.length) || '/'+ : rawPath;+ const currentUrl = `${strippedPath}${window.location.search}${window.location.hash}`;+ persistRedirectToSession(currentUrl);+ navigate('/login/2fa/setup', { replace: true });+ return;+ }if (token) {- const storedRedirect = readStoredRedirect();- dropStoredRedirect();const baseUrl = apiBaseUrl();const rawPath = window.location.pathname;const strippedPath =@@ -238,7 +330,7 @@ const AuthContextProvider = ({const currentUrl = `${strippedPath}${window.location.search}`;const fallbackRedirect = isSafeRedirect(currentUrl) ? currentUrl : '/c/new';const redirect =- storedRedirect && isSafeRedirect(storedRedirect) ? storedRedirect : fallbackRedirect;+ getPostLoginRedirect(new URLSearchParams(window.location.search)) ?? fallbackRedirect;setUserContext({ user, token, isAuthenticated: true, redirect });return;}@@ -248,6 +340,9 @@ const AuthContextProvider = ({if (authConfig?.test === true) {return;}+ if (isRequiredTwoFactorSetupRoute()) {+ return;+ }if (authConfig?.optional !== true) {navigate(buildLoginRedirectUrl());}@@ -262,6 +357,9 @@ const AuthContextProvider = ({if (authConfig?.test === true) {return;}+ if (isRequiredTwoFactorSetupRoute()) {+ return;+ }if (authConfig?.optional !== true) {navigate(buildLoginRedirectUrl());}@@ -304,6 +402,7 @@ const AuthContextProvider = ({navigate,silentRefresh,setUserContext,+ doSetError,]);useEffect(() => {@@ -323,6 +422,21 @@ const AuthContextProvider = ({};}, [setUserContext, user]);+ useEffect(() => {+ const handleAuthRedirect = (event: CustomEvent<{ inDocument?: boolean }>) => {+ if (event.detail?.inDocument !== true) {+ return;+ }+ clearAuthenticationForRedirect();+ };++ window.addEventListener('authRedirectStarted', handleAuthRedirect as EventListener);++ return () => {+ window.removeEventListener('authRedirectStarted', handleAuthRedirect as EventListener);+ };+ }, [clearAuthenticationForRedirect]);+const memoedValue = useMemo(() => ({user,@@ -330,6 +444,7 @@ const AuthContextProvider = ({error,login,logout,+ completeAuthentication,setError,roles: {[SystemRoles.USER]: userRole,@@ -340,9 +455,6 @@ const AuthContextProvider = ({isAuthReady,}),- /** `login` is a plain function rebuilt every render, so depending on it would rebuild this- * context value every render and re-render every consumer of auth state. */- // eslint-disable-next-line react-hooks/exhaustive-deps[user,error,@@ -354,6 +466,9 @@ const AuthContextProvider = ({isCustomRole,userRoleName,customRole,+ login,+ logout,+ completeAuthentication,],);diff --git a/client/src/hooks/SSE/__tests__/sse.spec.ts b/client/src/hooks/SSE/__tests__/sse.spec.tsindex d03d1a5429..f9eff992ec 100644--- a/client/src/hooks/SSE/__tests__/sse.spec.ts+++ b/client/src/hooks/SSE/__tests__/sse.spec.ts@@ -67,6 +67,13 @@ class FakeXHR {const message = (data: object | string) =>`event: message\ndata: ${typeof data === 'string' ? data : JSON.stringify(data)}\n\n`;+const enrollmentPayload = {+ code: 'two_factor_enrollment_required',+ twoFASetupRequired: true,+ tempToken: 'setup-token',+};+const enrollmentBody = JSON.stringify(enrollmentPayload);+const turn = {server: '/api/assistants/v2/chat',payload: { text: 'Hello', conversationId: null, isContinued: false } as TPayload,@@ -212,6 +219,41 @@ describe('createSSETransport', () => {expect(events).toEqual([{ type: 'error', data: undefined }]);});+ it('leaves for setup on an enrollment 403 instead of reporting a stream error', () => {+ const redirect = jest.spyOn(request, 'redirectIfTwoFactorSetupPayload').mockReturnValue(true);+ send();+ current().status = 403;+ current().write(enrollmentBody);++ expect(redirect).toHaveBeenCalledWith(enrollmentBody);+ expect(events).toEqual([]);+ });++ it('reports a 403 that is not an enrollment response', () => {+ send();+ current().status = 403;+ current().write(JSON.stringify({ message: 'Forbidden' }));++ expect(events).toEqual([{ type: 'error', data: { message: 'Forbidden' } }]);+ });++ it('leaves for setup when the 401 refresh answers with enrollment', async () => {+ jest.spyOn(request, 'refreshToken').mockResolvedValue(enrollmentPayload as never);+ const redirect = jest.spyOn(request, 'redirectIfTwoFactorSetupPayload').mockReturnValue(true);+ const dispatchTokenUpdated = jest+ .spyOn(request, 'dispatchTokenUpdatedEvent')+ .mockImplementation(() => undefined);+ send();+ current().status = 401;+ current().write('Unauthorized');+ await new Promise(process.nextTick);++ expect(redirect).toHaveBeenCalledWith(enrollmentPayload);+ expect(xhrs).toHaveLength(1);+ expect(dispatchTokenUpdated).not.toHaveBeenCalled();+ expect(events).toEqual([]);+ });+it.each([['succeeds', () => Promise.resolve({ token: 'token-2' })],['fails', () => Promise.reject(new Error('refresh failed'))],@@ -495,6 +537,36 @@ describe('createSSETransport().reconnectToStream', () => {expect(events).toEqual([{ type: 'error', status: 401, data: undefined }]);});+ it('leaves for setup on an enrollment 403 instead of reporting a failure', () => {+ const redirect = jest.spyOn(request, 'redirectIfTwoFactorSetupPayload').mockReturnValue(true);+ attach();+ current().status = 403;+ current().write(enrollmentBody);++ expect(redirect).toHaveBeenCalledWith(enrollmentBody);+ expect(events).toEqual([]);+ });++ it('reports a 403 that is not an enrollment response with its status', () => {+ attach();+ current().status = 403;+ current().write(JSON.stringify({ message: 'Forbidden' }));++ expect(events).toEqual([{ type: 'error', status: 403, data: { message: 'Forbidden' } }]);+ });++ it('leaves for setup when the 401 refresh answers with enrollment', async () => {+ jest.spyOn(request, 'refreshToken').mockResolvedValue(enrollmentPayload as never);+ jest.spyOn(request, 'redirectIfTwoFactorSetupPayload').mockReturnValue(true);+ attach();+ current().status = 401;+ current().write('Unauthorized');+ await new Promise(process.nextTick);++ expect(xhrs).toHaveLength(1);+ expect(events).toEqual([]);+ });+it('stays closed when the caller aborts while a 401 refresh is in flight', async () => {jest.spyOn(request, 'refreshToken').mockResolvedValue({ token: 'token-2' } as never);const dispatchTokenUpdated = jestdiff --git a/client/src/hooks/SSE/__tests__/useResumableSSE.spec.ts b/client/src/hooks/SSE/__tests__/useResumableSSE.spec.tsindex aea019d690..9d5f1d8b12 100644--- a/client/src/hooks/SSE/__tests__/useResumableSSE.spec.ts+++ b/client/src/hooks/SSE/__tests__/useResumableSSE.spec.ts@@ -75,6 +75,7 @@ jest.mock('sse.js', () => {return { SSE };});+const mockRedirectIfTwoFactorSetupPayload = jest.fn((_payload: unknown) => false);const mockSetQueryData = jest.fn();const mockGetQueryData = jest.fn();const mockFetchQuery = jest.fn();@@ -311,6 +312,8 @@ jest.mock('librechat-data-provider', () => {}),refreshToken: jest.fn(),dispatchTokenUpdatedEvent: jest.fn(),+ redirectIfTwoFactorSetupPayload: (payload: unknown) =>+ mockRedirectIfTwoFactorSetupPayload(payload),},};});@@ -449,6 +452,8 @@ describe('useResumableSSE', () => {conversationId: CONV_ID,endpoint: 'agents',});+ mockRedirectIfTwoFactorSetupPayload.mockReset();+ mockRedirectIfTwoFactorSetupPayload.mockReturnValue(false);(request.post as jest.Mock).mockReset();(request.post as jest.Mock).mockResolvedValue({streamId: 'stream-123',@@ -4746,6 +4751,97 @@ describe('useResumableSSE', () => {unmount();});+ /**+ * The stream runs on a raw XHR, so the interceptor that turns an enrollment 403 into the setup+ * redirect never sees it. Without the explicit branch the condition looks like a transport+ * failure and burns the whole reconnect ladder on a request the server is bound to refuse.+ */+ const enrollmentBody = JSON.stringify({+ code: 'two_factor_enrollment_required',+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });++ it('leaves for setup on an enrollment 403 instead of reconnecting', async () => {+ jest.useFakeTimers();+ mockRedirectIfTwoFactorSetupPayload.mockReturnValue(true);+ const submission = buildSubmission();+ const chatHelpers = buildChatHelpers();++ const { unmount } = renderHook(() => useResumableSSE(submission, chatHelpers));+ await flushMicrotasks();++ const sse = getLastSSE();+ const sseCount = mockSSEInstances.length;++ await act(async () => {+ sse._emit('error', { responseCode: 403, data: enrollmentBody });+ });+ await advanceRetryTimer(60000);++ expect(mockRedirectIfTwoFactorSetupPayload).toHaveBeenCalledWith(enrollmentBody);+ expect(mockSSEInstances.length).toBe(sseCount);+ expect(mockErrorHandler).not.toHaveBeenCalled();+ unmount();+ });++ it('keeps reconnecting on a 403 that is not an enrollment response', async () => {+ jest.useFakeTimers();+ const submission = buildSubmission();+ const chatHelpers = buildChatHelpers();++ const { unmount } = renderHook(() => useResumableSSE(submission, chatHelpers));+ await flushMicrotasks();++ const sse = getLastSSE();+ const sseCount = mockSSEInstances.length;++ await act(async () => {+ sse._emit('error', { responseCode: 403, data: JSON.stringify({ message: 'Forbidden' }) });+ });+ await advanceRetryTimer(60000);++ /** Only enrollment may short-circuit; every other 403 keeps the existing recovery. */+ expect(mockSSEInstances.length).toBeGreaterThan(sseCount);+ unmount();+ });++ /**+ * An access token that expired first turns enforcement into a 401, so the refresh is where the+ * setup credential arrives. It answers successfully and without a token, which reads as a failed+ * refresh unless the payload is inspected.+ */+ it('leaves for setup when the 401 refresh answers with enrollment', async () => {+ jest.useFakeTimers();+ const enrollmentPayload = {+ code: 'two_factor_enrollment_required',+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ };+ (request.refreshToken as jest.Mock).mockResolvedValueOnce(enrollmentPayload);+ mockRedirectIfTwoFactorSetupPayload.mockReturnValue(true);+ const submission = buildSubmission();+ const chatHelpers = buildChatHelpers();++ const { unmount } = renderHook(() => useResumableSSE(submission, chatHelpers));+ await flushMicrotasks();++ const sse = getLastSSE();+ const sseCount = mockSSEInstances.length;++ await act(async () => {+ sse._emit('error', { responseCode: 401 });+ await Promise.resolve();+ });+ await advanceRetryTimer(60000);++ expect(mockRedirectIfTwoFactorSetupPayload).toHaveBeenCalledWith(enrollmentPayload);+ expect(sse.stream).toHaveBeenCalledTimes(1);+ expect(mockSSEInstances.length).toBe(sseCount);+ expect(mockErrorHandler).not.toHaveBeenCalled();+ unmount();+ });+it.each([undefined, 500, 503])('does not call errorHandler for responseCode %s (reconnect path)',async (responseCode) => {diff --git a/client/src/hooks/SSE/transport/sse.ts b/client/src/hooks/SSE/transport/sse.tsindex 26c1e032ea..83cac50ac3 100644--- a/client/src/hooks/SSE/transport/sse.ts+++ b/client/src/hooks/SSE/transport/sse.ts@@ -33,10 +33,18 @@ const emitFrame = (onEvent: EventCallback) => (e: MessageEvent) => {}};-/** Resolves to the refreshed token, or `null` when the refresh failed. */-async function refreshToken(): Promise<string | null> {+/**+ * Resolves to the refreshed token, `null` when the refresh failed, or `false` when it answered+ * with a two-factor setup credential and the page is leaving for setup. An access token that+ * expired first turns enrollment enforcement into a 401 the stream cannot read, so the refresh is+ * where enrollment surfaces: it succeeds without a token, which is not a failure to report.+ */+async function refreshToken(): Promise<string | null | false> {try {const refreshResponse = await request.refreshToken();+ if (request.redirectIfTwoFactorSetupPayload(refreshResponse)) {+ return false;+ }const refreshedToken = refreshResponse?.token ?? '';if (!refreshedToken) {throw new Error('Token refresh failed.');@@ -49,6 +57,13 @@ async function refreshToken(): Promise<string | null> {}}+/**+ * Enrollment enforcement answers the stream with a 403 no retry can clear, and this raw XHR+ * bypasses the fetch interceptor that turns it into the setup redirect elsewhere.+ */+const isTwoFactorSetupRefusal = (e: StreamErrorEvent): boolean =>+ e.responseCode === 403 && request.redirectIfTwoFactorSetupPayload(e.data);+/*** An HTTP failure body is often empty or HTML, so one that is not JSON is* `undefined`. An error event the server wrote keeps its raw text instead.@@ -101,12 +116,15 @@ export function createSSETransport({ token }: { token?: string }): ChatTransport* live until the retry settles, so an abort meanwhile must still cancel. */let refreshing = false;sse.addEventListener('error', async (e: StreamErrorEvent) => {+ if (isTwoFactorSetupRefusal(e)) {+ return;+ }if (e.responseCode === 401 && !refreshed) {refreshed = true;refreshing = true;const refreshedToken = await refreshToken();refreshing = false;- if (signal.aborted) {+ if (signal.aborted || refreshedToken === false) {return;}if (refreshedToken) {@@ -183,10 +201,13 @@ export function createSSETransport({ token }: { token?: string }): ChatTransportlet refreshed = false;sse.addEventListener('error', async (e: StreamErrorEvent) => {failureSeen = true;+ if (isTwoFactorSetupRefusal(e)) {+ return;+ }if (e.responseCode === 401 && !refreshed) {refreshed = true;const refreshedToken = await refreshToken();- if (signal.aborted) {+ if (signal.aborted || refreshedToken === false) {return;}if (refreshedToken) {diff --git a/client/src/hooks/__tests__/AuthContext.spec.tsx b/client/src/hooks/__tests__/AuthContext.spec.tsxindex 85d9fc6b2b..135fc80ac4 100644--- a/client/src/hooks/__tests__/AuthContext.spec.tsx+++ b/client/src/hooks/__tests__/AuthContext.spec.tsx@@ -7,6 +7,12 @@ import { getDefaultStore } from 'jotai';import { MemoryRouter } from 'react-router-dom';import { render, act } from '@testing-library/react';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import {+ FileSources,+ readTwoFactorSetupToken,+ clearTwoFactorSetupToken,+ persistTwoFactorSetupToken,+} from 'librechat-data-provider';import type { TAuthConfig } from '~/common';import {chatFilterStatusAtom,@@ -14,8 +20,13 @@ import {chatSortAtom,resetChatFilterSessionAtom,} from '~/components/Conversations/chatFilters';+import {+ SESSION_KEY,+ retainFileDeletion,+ clearRetainedFileDeletions,+ takeRetainedFileDeletions,+} from '~/utils';import { AuthContextProvider, useAuthContext } from '../AuthContext';-import { SESSION_KEY } from '~/utils';const mockNavigate = jest.fn();jest.mock('react-router-dom', () => ({@@ -42,6 +53,9 @@ let mockCapturedLogoutOptions: {};const mockRefreshMutate = jest.fn();+const mockLoginMutate = jest.fn();+const mockLogoutMutate = jest.fn();+let capturedAuthContext: ReturnType<typeof useAuthContext> | undefined;jest.mock('~/data-provider', () => ({useLoginUserMutation: jest.fn(@@ -50,7 +64,7 @@ jest.mock('~/data-provider', () => ({onError: (...args: unknown[]) => void;}) => {mockCapturedLoginOptions = options;- return { mutate: jest.fn() };+ return { mutate: mockLoginMutate };},),useLogoutUserMutation: jest.fn(@@ -59,7 +73,7 @@ jest.mock('~/data-provider', () => ({onError: (...args: unknown[]) => void;}) => {mockCapturedLogoutOptions = options;- return { mutate: jest.fn() };+ return { mutate: mockLogoutMutate };},),useRefreshTokenMutation: jest.fn(() => ({ mutate: mockRefreshMutate })),@@ -76,6 +90,7 @@ const authConfig: TAuthConfig = { loginRedirect: '/login', test: true };function TestConsumer() {const ctx = useAuthContext();+ capturedAuthContext = ctx;return (<divdata-testid="consumer"@@ -92,7 +107,7 @@ function renderProvider() {defaultOptions: { queries: { retry: false }, mutations: { retry: false } },});- return render(+ const tree = () => (<QueryClientProvider client={queryClient}><RecoilRoot><MemoryRouter>@@ -101,8 +116,10 @@ function renderProvider() {</AuthContextProvider></MemoryRouter></RecoilRoot>- </QueryClientProvider>,+ </QueryClientProvider>);+ const result = render(tree());+ return { ...result, rerenderProvider: () => result.rerender(tree()) };}/** Renders without test:true so silentRefresh actually runs */@@ -142,7 +159,7 @@ function renderOptionalProvider() {);}-describe('AuthContextProvider — test mode', () => {+describe('AuthContextProvider: test mode', () => {beforeEach(() => {jest.clearAllMocks();});@@ -153,9 +170,188 @@ describe('AuthContextProvider — test mode', () => {expect(getByTestId('consumer')).toHaveAttribute('data-auth-ready', 'true');expect(mockRefreshMutate).not.toHaveBeenCalled();});++ it('preserves auth context when mutation result objects change without an auth change', () => {+ const { rerenderProvider } = renderProvider();+ const previousContext = capturedAuthContext;++ rerenderProvider();++ expect(capturedAuthContext?.login).toBe(previousContext?.login);+ expect(capturedAuthContext?.logout).toBe(previousContext?.logout);+ expect(capturedAuthContext).toBe(previousContext);+ });});-describe('AuthContextProvider — login onError redirect handling', () => {+describe('AuthContextProvider two-factor login handoff', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ sessionStorage.clear();+ capturedAuthContext = undefined;+ window.history.replaceState({}, '', '/login');+ });++ afterEach(() => {+ sessionStorage.clear();+ window.history.replaceState({}, '', '/');+ });++ it('routes unenrolled users to required setup', () => {+ renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });+ });++ expect(mockNavigate).toHaveBeenCalledWith('/login/2fa/setup', { replace: true });+ /** The credential is handed over out of band, never through the address bar. */+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ it('retains a non-default destination through setup reload and consumes it after completion', () => {+ window.history.replaceState(+ {},+ '',+ '/login?redirect_to=%2Fc%2Fredirect-lifecycle-proof%3Fmodel%3Dtest',+ );+ const firstRender = renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+ });+ });++ expect(sessionStorage.getItem(SESSION_KEY)).toBe('/c/redirect-lifecycle-proof?model=test');+ firstRender.unmount();+ window.history.replaceState({}, '', '/login/2fa/setup');+ renderProvider();++ act(() => {+ capturedAuthContext?.completeAuthentication('auth-token', { id: 'user-1' } as never);+ });++ expect(mockNavigate).toHaveBeenLastCalledWith('/c/redirect-lifecycle-proof?model=test', {+ replace: true,+ });+ expect(sessionStorage.getItem(SESSION_KEY)).toBeNull();++ act(() => {+ capturedAuthContext?.completeAuthentication('auth-token', { id: 'user-1' } as never);+ });+ expect(mockNavigate).toHaveBeenLastCalledWith('/c/new', { replace: true });+ });++ it('keeps enrolled users on the existing verification route', () => {+ renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ tempToken: 'challenge-token',+ });+ });++ expect(mockNavigate).toHaveBeenCalledWith('/login/2fa?tempToken=challenge-token', {+ replace: true,+ });+ });++ /**+ * An abandoned setup token outlives the screen that staged it, so a later sign-in in the same tab+ * must not leave the previous user's enrollment credential available to finish.+ */+ it('drops an abandoned setup token when the next sign-in succeeds', () => {+ renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'abandoned-token',+ });+ });+ expect(readTwoFactorSetupToken()).toBe('abandoned-token');++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ token: 'other-user-token',+ user: { id: 'user-2' },+ });+ });++ expect(readTwoFactorSetupToken()).toBe('');+ });++ it('drops an abandoned setup token when the next sign-in is challenged', () => {+ renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'abandoned-token',+ });+ });++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ tempToken: 'challenge-token',+ });+ });++ expect(readTwoFactorSetupToken()).toBe('');+ });++ it('drops an abandoned setup token when the next sign-in fails', () => {+ renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'abandoned-token',+ });+ });++ act(() => {+ mockCapturedLoginOptions.onError({ response: { status: 401 } });+ });++ expect(readTwoFactorSetupToken()).toBe('');+ });++ it('still hands the fresh credential to a setup that follows another sign-in', () => {+ renderProvider();++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'first-token',+ });+ });++ act(() => {+ mockCapturedLoginOptions.onSuccess({+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'second-token',+ });+ });++ expect(readTwoFactorSetupToken()).toBe('second-token');+ });+});++describe('AuthContextProvider: login onError redirect handling', () => {beforeEach(() => {jest.clearAllMocks();window.history.replaceState({}, '', '/login');@@ -213,21 +409,24 @@ describe('AuthContextProvider — login onError redirect handling', () => {expect(mockNavigate).toHaveBeenCalledWith('/login', { replace: true });});- it('surfaces the cross-origin rejection code instead of the HTTP status message', () => {- jest.useFakeTimers();- const { getByTestId } = renderProvider();-- act(() => {- mockCapturedLoginOptions.onError({- message: 'Request failed with status code 403',- response: { data: { message: 'Cross-site request rejected', code: 'auth_cross_origin' } },+ it.each(['auth_cross_origin', 'TWO_FACTOR_FEDERATED_LOGIN_BLOCKED'])(+ 'surfaces the recognized %s rejection code instead of the HTTP status message',+ (code) => {+ jest.useFakeTimers();+ const { getByTestId } = renderProvider();++ act(() => {+ mockCapturedLoginOptions.onError({+ message: 'Request failed with status code 403',+ response: { data: { code } },+ });+ jest.advanceTimersByTime(400);});- jest.advanceTimersByTime(400);- });- expect(getByTestId('consumer')).toHaveAttribute('data-error', 'auth_cross_origin');- jest.useRealTimers();- });+ expect(getByTestId('consumer')).toHaveAttribute('data-error', code);+ jest.useRealTimers();+ },+ );it('keeps the HTTP status message for other rejections that carry a code', () => {jest.useFakeTimers();@@ -376,6 +575,50 @@ describe('AuthContextProvider — silentRefresh post-login redirect', () => {jest.useRealTimers();});+ /**+ * A federated sign-in lands here rather than through the login mutation, so the previous user's+ * abandoned enrollment credential has to be dropped on this path too.+ */+ it('drops an abandoned setup token when a refresh sign-in is accepted', () => {+ jest.useFakeTimers();+ persistTwoFactorSetupToken('abandoned-token');++ renderProviderLive();++ const [, refreshOptions] = mockRefreshMutate.mock.calls[0] as [+ unknown,+ { onSuccess: (data: unknown) => void },+ ];++ act(() => {+ refreshOptions.onSuccess({ user: { id: '1', role: 'USER' }, token: 'new-token' });+ });+ act(() => {+ jest.advanceTimersByTime(100);+ });++ expect(readTwoFactorSetupToken()).toBe('');+ jest.useRealTimers();+ });++ it('routes an unenrolled refresh session to setup and preserves the requested destination', () => {+ window.history.replaceState({}, '', '/c/requested?model=test#latest');+ renderProviderLive();+ const [, refreshOptions] = mockRefreshMutate.mock.calls[0] as [+ unknown,+ { onSuccess: (data: unknown) => void },+ ];++ act(() => {+ refreshOptions.onSuccess({ twoFASetupRequired: true, tempToken: 'setup token' });+ });++ expect(sessionStorage.getItem(SESSION_KEY)).toBe('/c/requested?model=test#latest');+ expect(mockNavigate).toHaveBeenCalledWith('/login/2fa/setup', { replace: true });+ /** Carried verbatim rather than URL-encoded, because it never enters a URL. */+ expect(readTwoFactorSetupToken()).toBe('setup token');+ });+it('navigates to current URL when no stored redirect exists', () => {jest.useFakeTimers();window.history.replaceState({}, '', '/c/new');@@ -399,6 +642,57 @@ describe('AuthContextProvider — silentRefresh post-login redirect', () => {jest.useRealTimers();});+ it('keeps the enforcement destination when refresh lands on the setup route', () => {+ window.history.replaceState({}, '', '/login/2fa/setup?redirect_to=%2Fc%2Frequested');+ persistTwoFactorSetupToken('setup-token');+ renderProviderLive();+ const [, refreshOptions] = mockRefreshMutate.mock.calls[0] as [+ unknown,+ { onSuccess: (data: unknown) => void },+ ];++ act(() => {+ refreshOptions.onSuccess({ twoFASetupRequired: true, tempToken: 'refreshed token' });+ });++ /** Replacing the route again would drop the query holding the only copy of the destination. */+ expect(mockNavigate).not.toHaveBeenCalled();+ expect(window.location.search).toBe('?redirect_to=%2Fc%2Frequested');+ /** The setup route is not a safe redirect, so it must never be banked as one either. */+ expect(sessionStorage.getItem(SESSION_KEY)).toBeNull();+ expect(readTwoFactorSetupToken()).toBe('refreshed token');+ });++ it('keeps a required setup route mounted when refresh fails after reload', () => {+ window.history.replaceState({}, '', '/login/2fa/setup');+ persistTwoFactorSetupToken('setup-token');+ renderProviderLive();+ const [, refreshOptions] = mockRefreshMutate.mock.calls[0] as [+ unknown,+ { onError: (error: Error) => void },+ ];++ act(() => refreshOptions.onError(new Error('No refresh session')));++ expect(mockNavigate).not.toHaveBeenCalled();+ expect(window.location.pathname).toBe('/login/2fa/setup');+ });++ it('keeps a required setup route mounted when refresh returns no token after reload', () => {+ window.history.replaceState({}, '', '/login/2fa/setup');+ persistTwoFactorSetupToken('setup-token');+ renderProviderLive();+ const [, refreshOptions] = mockRefreshMutate.mock.calls[0] as [+ unknown,+ { onSuccess: (data: unknown) => void },+ ];++ act(() => refreshOptions.onSuccess({}));++ expect(mockNavigate).not.toHaveBeenCalled();+ expect(window.location.pathname).toBe('/login/2fa/setup');+ });+it('does not re-trigger silentRefresh after successful redirect', () => {jest.useFakeTimers();sessionStorage.setItem(SESSION_KEY, '/c/abc?endpoint=bedrock');@@ -716,3 +1010,115 @@ describe('AuthContextProvider — custom role detection and fetching', () => {jest.useRealTimers();});});++describe('AuthContextProvider: enrollment hand-off that keeps the document', () => {+ const mockUseGetUserQuery = jest.requireMock('~/data-provider').useGetUserQuery;++ const dispatchHandoff = (inDocument: boolean) =>+ act(() => {+ window.dispatchEvent(+ new CustomEvent('authRedirectStarted', {+ detail: { href: '/login/2fa/setup', inDocument },+ }),+ );+ });++ const lastUserQueryConfig = () => {+ const calls = mockUseGetUserQuery.mock.calls;+ return calls[calls.length - 1][0];+ };++ beforeEach(() => {+ jest.clearAllMocks();+ sessionStorage.clear();+ clearTwoFactorSetupToken();+ capturedAuthContext = undefined;+ window.history.replaceState({}, '', '/c/some-chat');+ });++ afterEach(() => {+ clearRetainedFileDeletions();+ sessionStorage.clear();+ clearTwoFactorSetupToken();+ window.history.replaceState({}, '', '/');+ });++ it('finishes enrollment with a ready session that can retain its own failed deletions', () => {+ clearRetainedFileDeletions();+ const { getByTestId } = renderProviderLive();+ expect(getByTestId('consumer')).toHaveAttribute('data-auth-ready', 'false');++ act(() => {+ capturedAuthContext?.completeAuthentication('auth-token', { id: 'user-1' } as never);+ });+ const deletion = {+ file_id: 'enrolled-user-file',+ embedded: false,+ filepath: '/uploads/user-1/file.txt',+ source: FileSources.local,+ };+ retainFileDeletion(deletion);++ expect(getByTestId('consumer')).toHaveAttribute('data-auth-ready', 'true');+ expect(takeRetainedFileDeletions()).toEqual([deletion]);++ dispatchHandoff(true);+ expect(takeRetainedFileDeletions()).toEqual([]);+ retainFileDeletion(deletion);+ expect(takeRetainedFileDeletions()).toEqual([]);+ });++ /**+ * Where session storage is blocked the hand-off routes in place instead of replacing the+ * document, so this provider stays mounted and the session it redirects away from would live on.+ * An enabled user query leaves for the login page as soon as it fails, which would pull the user+ * off the enrollment the server is demanding.+ */+ it('releases the replaced session so its user query cannot navigate away', () => {+ const jotaiStore = getDefaultStore();+ jotaiStore.set(chatFilterStatusAtom, 'archived');+ jotaiStore.set(chatFilterTagsAtom, ['previous-session']);+ const { getByTestId } = renderProvider();++ act(() => {+ capturedAuthContext?.completeAuthentication('auth-token', { id: 'user-1' } as never);+ });+ expect(getByTestId('consumer').getAttribute('data-authenticated')).toBe('true');+ expect(lastUserQueryConfig()).toEqual(expect.objectContaining({ enabled: true }));++ dispatchHandoff(true);++ expect(getByTestId('consumer').getAttribute('data-authenticated')).toBe('false');+ expect(lastUserQueryConfig()).toEqual(expect.objectContaining({ enabled: false }));+ expect(jotaiStore.get(chatFilterStatusAtom)).toBe('active');+ expect(jotaiStore.get(chatFilterTagsAtom)).toEqual([]);+ });++ /** A replaced document discards the session on its own, so nothing is released early here. */+ it('leaves the session alone when the hand-off replaces the document', () => {+ const { getByTestId } = renderProvider();++ act(() => {+ capturedAuthContext?.completeAuthentication('auth-token', { id: 'user-1' } as never);+ });++ dispatchHandoff(false);++ expect(getByTestId('consumer').getAttribute('data-authenticated')).toBe('true');+ expect(lastUserQueryConfig()).toEqual(expect.objectContaining({ enabled: true }));+ });++ /** With storage blocked the in-memory mirror is the only copy the setup screen can read. */+ it('keeps the setup credential the surviving document is holding', () => {+ renderProvider();++ act(() => {+ capturedAuthContext?.completeAuthentication('auth-token', { id: 'user-1' } as never);+ });+ persistTwoFactorSetupToken('setup-token');++ dispatchHandoff(true);++ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });+});diff --git a/client/src/hooks/useTimeout.tsx b/client/src/hooks/useTimeout.tsxindex 456dfd1800..e008d14f1a 100644--- a/client/src/hooks/useTimeout.tsx+++ b/client/src/hooks/useTimeout.tsx@@ -1,4 +1,4 @@-import { useEffect, useRef } from 'react';+import { useEffect, useRef, useCallback } from 'react';type TUseTimeoutParams = {callback: (error: string | number | boolean | null) => void;@@ -9,20 +9,23 @@ type TTimeout = ReturnType<typeof setTimeout> | null;function useTimeout({ callback, delay = 400 }: TUseTimeoutParams) {const timeout = useRef<TTimeout>(null);- const callOnTimeout = (value?: string) => {- // Clear existing timeout- if (timeout.current !== null) {- clearTimeout(timeout.current);- }+ const callOnTimeout = useCallback(+ (value?: string) => {+ // Clear existing timeout+ if (timeout.current !== null) {+ clearTimeout(timeout.current);+ }- // Set new timeout- if (value != null && value) {- console.log(value);- timeout.current = setTimeout(() => {- callback(value);- }, delay);- }- };+ // Set new timeout+ if (value != null && value) {+ console.log(value);+ timeout.current = setTimeout(() => {+ callback(value);+ }, delay);+ }+ },+ [callback, delay],+ );// Clear timeout when the component unmountsuseEffect(() => {diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex c2e9973cc8..d5c24812b6 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -317,6 +317,7 @@"com_auth_error_login": "Unable to login with the information provided. Please check your credentials and try again.","com_auth_error_login_ban": "Your account has been temporarily banned due to violations of our service.","com_auth_error_login_cross_origin": "Sign-in was blocked because the request did not come from this site. Open the login page directly and try again.",+ "com_auth_error_login_federated_two_factor": "This account signs in through your identity provider. Use that option to continue.","com_auth_error_login_rl": "Too many login attempts in a short amount of time. Please try again later.","com_auth_error_login_server": "There was an internal server error. Please wait a few moments and try again.","com_auth_error_login_unverified": "Your account has not been verified. Please check your email for a verification link.",@@ -361,6 +362,10 @@"com_auth_to_reset_your_password": "to reset your password.","com_auth_to_try_again": "to try again.","com_auth_two_factor": "Check your preferred one-time password application for a code",+ "com_auth_two_factor_setup_expired": "This two-factor setup session is missing or expired. Return to sign in and try again.",+ "com_auth_two_factor_setup_finalize_error": "We could not finish signing you in. Your two-factor setup is saved. Try completing setup again.",+ "com_auth_two_factor_setup_required": "Two-Factor Authentication Required",+ "com_auth_two_factor_setup_required_description": "Your administrator requires two-factor authentication. Set it up before continuing.","com_auth_username": "Username (optional)","com_auth_username_max_length": "Username must be less than 20 characters","com_auth_username_min_length": "Username must be at least 2 characters",@@ -989,6 +994,8 @@"com_ui_2fa_enabled": "2FA has been enabled","com_ui_2fa_generate_error": "There was an error generating two-factor authentication settings","com_ui_2fa_invalid": "Invalid two-factor authentication code",+ "com_ui_2fa_required": "Required by administrator",+ "com_ui_2fa_scan_qr": "Scan QR Code","com_ui_2fa_setup": "Setup 2FA","com_ui_2fa_verification_required": "Enter your 2FA code to continue","com_ui_2fa_verified": "Successfully verified Two-Factor Authentication",diff --git a/client/src/routes/Layouts/Startup.tsx b/client/src/routes/Layouts/Startup.tsxindex 7775b770b4..5dfe1a222f 100644--- a/client/src/routes/Layouts/Startup.tsx+++ b/client/src/routes/Layouts/Startup.tsx@@ -1,7 +1,12 @@-import { useEffect, useState } from 'react';+import { useEffect, useRef, useState } from 'react';import { Outlet, useNavigate, useLocation } from 'react-router-dom';import type { TStartupConfig } from 'librechat-data-provider';-import { DEFAULT_APP_TITLE, REDIRECT_PARAM, hasStoredRedirect, setDocumentTitle } from '~/utils';+import {+ DEFAULT_APP_TITLE,+ setDocumentTitle,+ getPostLoginRedirect,+ isRequiredTwoFactorSetupRoute,+} from '~/utils';import { TranslationKeys, useLocalize } from '~/hooks';import { useGetStartupConfig } from '~/data-provider';import AuthLayout from '~/components/Auth/AuthLayout';@@ -12,6 +17,7 @@ const headerMap: Record<string, TranslationKeys> = {'/forgot-password': 'com_auth_reset_password','/reset-password': 'com_auth_reset_password','/login/2fa': 'com_auth_verify_your_identity',+ '/login/2fa/setup': 'com_auth_two_factor_setup_required',};export default function StartupLayout({ isAuthenticated }: { isAuthenticated?: boolean }) {@@ -29,18 +35,32 @@ export default function StartupLayout({ isAuthenticated }: { isAuthenticated?: bconst navigate = useNavigate();const location = useLocation();+ const navigateRef = useRef(navigate);+ navigateRef.current = navigate;++ /**+ * Only an already-authenticated arrival is this layout's to redirect. When authentication+ * completes while an auth route is mounted, the auth context has already consumed the pending+ * destination and navigated there; re-resolving it here would find nothing left and replace that+ * destination with `/c/new`. Mandatory enrollment is the one arrival that stays put: the user+ * holding a setup token is authenticated precisely until they enroll, so sending them on would+ * bounce them straight back out of the screen the server is demanding they complete.+ */useEffect(() => {- if (isAuthenticated) {- const hasPendingRedirect =- new URLSearchParams(window.location.search).has(REDIRECT_PARAM) || hasStoredRedirect();- if (!hasPendingRedirect) {- navigate('/c/new', { replace: true });- }+ if (!isAuthenticated || isRequiredTwoFactorSetupRoute()) {+ return;}+ const destination =+ getPostLoginRedirect(new URLSearchParams(window.location.search)) ?? '/c/new';+ navigateRef.current(destination, { replace: true });+ // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only by design; see comment above+ }, []);++ useEffect(() => {if (data) {setStartupConfig(data);}- }, [isAuthenticated, navigate, data]);+ }, [data]);useEffect(() => {setDocumentTitle(startupConfig?.appTitle || DEFAULT_APP_TITLE, true);diff --git a/client/src/routes/__tests__/StartupLayout.spec.tsx b/client/src/routes/__tests__/StartupLayout.spec.tsxindex 647c53006b..c95a2ec8ad 100644--- a/client/src/routes/__tests__/StartupLayout.spec.tsx+++ b/client/src/routes/__tests__/StartupLayout.spec.tsx@@ -1,7 +1,8 @@/* eslint-disable i18next/no-literal-string */import React from 'react';-import { render, waitFor } from '@testing-library/react';import { createMemoryRouter, RouterProvider } from 'react-router-dom';+import { fireEvent, render, screen, waitFor } from '@testing-library/react';+import { clearTwoFactorSetupToken, persistTwoFactorSetupToken } from 'librechat-data-provider';import StartupLayout from '~/routes/Layouts/Startup';import { SESSION_KEY } from '~/utils';@@ -32,6 +33,20 @@ function NewConversation() {return <div data-testid="new-conversation">New Conversation</div>;}+/** Reproduces the real sequence: the layout mounts unauthenticated, then authentication lands. */+function AuthFlipRoute() {+ const [isAuthenticated, setIsAuthenticated] = React.useState(false);++ return (+ <div>+ <button data-testid="authenticate" onClick={() => setIsAuthenticated(true)}>+ authenticate+ </button>+ <StartupLayout isAuthenticated={isAuthenticated} />+ </div>+ );+}+const createTestRouter = (initialEntry: string, isAuthenticated: boolean) =>createMemoryRouter([@@ -44,6 +59,10 @@ const createTestRouter = (initialEntry: string, isAuthenticated: boolean) =>path: '/c/new',element: <NewConversation />,},+ {+ path: '/c/:conversationId',+ element: <div data-testid="requested-conversation" />,+ },],{ initialEntries: [initialEntry] },);@@ -69,27 +88,50 @@ describe('StartupLayout — redirect race condition', () => {});});- it('does NOT navigate to /c/new when redirect_to URL param is present', async () => {+ it('navigates to the URL redirect when authentication completes', async () => {window.history.replaceState({}, '', '/login?redirect_to=%2Fc%2Fabc123');const router = createTestRouter('/login?redirect_to=%2Fc%2Fabc123', true);render(<RouterProvider router={router} />);- await new Promise((resolve) => setTimeout(resolve, 100));-- expect(router.state.location.pathname).toBe('/login');+ await waitFor(() => expect(router.state.location.pathname).toBe('/c/abc123'));});- it('does NOT navigate to /c/new when sessionStorage redirect is present', async () => {+ it('navigates to the stored redirect when authentication completes', async () => {window.history.replaceState({}, '', '/login');sessionStorage.setItem(SESSION_KEY, '/c/abc123');const router = createTestRouter('/login', true);render(<RouterProvider router={router} />);+ await waitFor(() => expect(router.state.location.pathname).toBe('/c/abc123'));+ expect(sessionStorage.getItem(SESSION_KEY)).toBeNull();+ });++ it('leaves the pending redirect alone when authentication completes after mount', async () => {+ window.history.replaceState({}, '', '/login');+ sessionStorage.setItem(SESSION_KEY, '/c/abc123');++ const router = createMemoryRouter(+ [+ {+ path: '/login',+ element: <AuthFlipRoute />,+ children: [{ index: true, element: <ChildRoute /> }],+ },+ { path: '/c/new', element: <NewConversation /> },+ { path: '/c/:conversationId', element: <div data-testid="requested-conversation" /> },+ ],+ { initialEntries: ['/login'] },+ );+ render(<RouterProvider router={router} />);++ fireEvent.click(screen.getByTestId('authenticate'));await new Promise((resolve) => setTimeout(resolve, 100));+ /** The auth context owns this transition, so the stored destination must still be intact. */expect(router.state.location.pathname).toBe('/login');+ expect(sessionStorage.getItem(SESSION_KEY)).toBe('/c/abc123');});it('does NOT navigate when not authenticated', async () => {@@ -103,3 +145,70 @@ describe('StartupLayout — redirect race condition', () => {expect(router.state.location.pathname).toBe('/login');});});++describe('StartupLayout: mandatory enrollment', () => {+ const createSetupRouter = (initialEntry: string) =>+ createMemoryRouter(+ [+ {+ path: '/login/2fa/setup',+ element: <StartupLayout isAuthenticated={true} />,+ children: [{ index: true, element: <ChildRoute /> }],+ },+ { path: '/c/new', element: <NewConversation /> },+ { path: '/c/:conversationId', element: <div data-testid="requested-conversation" /> },+ ],+ { initialEntries: [initialEntry] },+ );++ beforeEach(() => {+ sessionStorage.clear();+ clearTwoFactorSetupToken();+ });++ afterEach(() => {+ clearTwoFactorSetupToken();+ window.history.replaceState({}, '', '/');+ jest.restoreAllMocks();+ });++ /**+ * The in-document hand-off leaves the auth context authenticated, so without the exemption this+ * layout redirects the user straight back out of the setup the server is demanding.+ */+ it('stays on the setup route when an authenticated user holds a setup token', async () => {+ window.history.replaceState({}, '', '/login/2fa/setup');+ persistTwoFactorSetupToken('setup-token');++ const router = createSetupRouter('/login/2fa/setup');+ render(<RouterProvider router={router} />);++ await new Promise((resolve) => setTimeout(resolve, 100));++ expect(router.state.location.pathname).toBe('/login/2fa/setup');+ });++ it('keeps the pending destination banked while enrollment is outstanding', async () => {+ window.history.replaceState({}, '', '/login/2fa/setup');+ sessionStorage.setItem(SESSION_KEY, '/c/abc123');+ persistTwoFactorSetupToken('setup-token');++ const router = createSetupRouter('/login/2fa/setup');+ render(<RouterProvider router={router} />);++ await new Promise((resolve) => setTimeout(resolve, 100));++ expect(router.state.location.pathname).toBe('/login/2fa/setup');+ expect(sessionStorage.getItem(SESSION_KEY)).toBe('/c/abc123');+ });++ /** The exemption is the live credential, not the path, so a stale visit still moves on. */+ it('redirects an authenticated arrival that carries no setup token', async () => {+ window.history.replaceState({}, '', '/login/2fa/setup');++ const router = createSetupRouter('/login/2fa/setup');+ render(<RouterProvider router={router} />);++ await waitFor(() => expect(router.state.location.pathname).toBe('/c/new'));+ });+});diff --git a/client/src/routes/__tests__/skillsRoutes.spec.tsx b/client/src/routes/__tests__/skillsRoutes.spec.tsxindex f391a84921..18feeec50b 100644--- a/client/src/routes/__tests__/skillsRoutes.spec.tsx+++ b/client/src/routes/__tests__/skillsRoutes.spec.tsx@@ -7,6 +7,7 @@ jest.mock('~/components/Auth', () => ({ResetPassword: () => null,ApiErrorWatcher: () => null,TwoFactorScreen: () => null,+ TwoFactorSetupScreen: () => null,RequestPasswordReset: () => null,}));diff --git a/client/src/routes/index.tsx b/client/src/routes/index.tsxindex 873b3e86db..90106aa84d 100644--- a/client/src/routes/index.tsx+++ b/client/src/routes/index.tsx@@ -6,6 +6,7 @@ import {ResetPassword,ApiErrorWatcher,TwoFactorScreen,+ TwoFactorSetupScreen,RequestPasswordReset,} from '~/components/Auth';import { OAuthSuccess, OAuthError } from '~/components/OAuth';@@ -119,6 +120,10 @@ export const router = createBrowserRouter(path: 'login/2fa',element: <TwoFactorScreen />,},+ {+ path: 'login/2fa/setup',+ element: <TwoFactorSetupScreen />,+ },],},dashboardRoutes,diff --git a/client/src/utils/__tests__/getLoginError.test.ts b/client/src/utils/__tests__/getLoginError.test.tsnew file mode 100644index 0000000000..79e923936a--- /dev/null+++ b/client/src/utils/__tests__/getLoginError.test.ts@@ -0,0 +1,28 @@+import { TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE } from 'librechat-data-provider';+import getLoginError from '../getLoginError';++describe('getLoginError', () => {+ it('falls back to the generic message without error text', () => {+ expect(getLoginError('')).toBe('com_auth_error_login');+ });++ it.each([+ ['Request failed with status code 429', 'com_auth_error_login_rl'],+ ['Request failed with status code 403', 'com_auth_error_login_ban'],+ ['Request failed with status code 500', 'com_auth_error_login_server'],+ ['Request failed with status code 422', 'com_auth_error_login_unverified'],+ ['something unmapped', 'com_auth_error_login'],+ ])('maps %s', (errorText, expected) => {+ expect(getLoginError(errorText)).toBe(expected);+ });++ /**+ * A refused federated password login is also a 403, so it has to win over the ban case; that+ * mapping is the only thing standing between the user and a false "account banned" message.+ */+ it('reports a refused federated password login rather than a ban', () => {+ expect(getLoginError(TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE)).toBe(+ 'com_auth_error_login_federated_two_factor',+ );+ });+});diff --git a/client/src/utils/__tests__/redirect.test.ts b/client/src/utils/__tests__/redirect.test.tsindex 83667b0cf4..780bf083c8 100644--- a/client/src/utils/__tests__/redirect.test.ts+++ b/client/src/utils/__tests__/redirect.test.ts@@ -1,9 +1,11 @@import {+ isRequiredTwoFactorSetupRoute,persistRedirectToSession,+ clearPostLoginRedirect,getPostLoginRedirect,+ peekPostLoginRedirect,isSafeRedirect,withBasePath,- hasStoredRedirect,SESSION_KEY,} from '../redirect';@@ -43,6 +45,44 @@ describe('withBasePath', () => {});});+describe('isRequiredTwoFactorSetupRoute', () => {+ const setPathname = (pathname: string) => {+ window.history.replaceState({}, '', pathname);+ };++ afterEach(() => {+ sessionStorage.clear();+ setPathname('/');+ });++ /** The router matches these spellings, so the guard has to recognise them too. */+ it.each([+ '/login/2fa/setup',+ '/login/2fa/setup/',+ '/LOGIN/2FA/SETUP',+ '/Login/2FA/Setup/',+ '/librechat/login/2fa/setup/',+ ])('recognises %s as the enrollment screen', (pathname) => {+ sessionStorage.setItem('two_factor_setup_token', 'setup-token');+ setPathname(pathname);++ expect(isRequiredTwoFactorSetupRoute()).toBe(true);+ });++ it('does not claim the route without a live setup token', () => {+ setPathname('/login/2fa/setup/');++ expect(isRequiredTwoFactorSetupRoute()).toBe(false);+ });++ it('does not claim a route that merely contains the setup path', () => {+ sessionStorage.setItem('two_factor_setup_token', 'setup-token');+ setPathname('/login/2fa/setup/extra');++ expect(isRequiredTwoFactorSetupRoute()).toBe(false);+ });+});+describe('isSafeRedirect', () => {it('accepts a simple relative path', () => {expect(isSafeRedirect('/c/new')).toBe(true);@@ -217,6 +257,18 @@ describe('getPostLoginRedirect', () => {});});+describe('peekPostLoginRedirect', () => {+ beforeEach(() => sessionStorage.clear());++ it('preserves a safe stored destination across repeated setup mounts', () => {+ sessionStorage.setItem(SESSION_KEY, '/c/deep-link?model=test');++ expect(peekPostLoginRedirect(new URLSearchParams())).toBe('/c/deep-link?model=test');+ expect(peekPostLoginRedirect(new URLSearchParams())).toBe('/c/deep-link?model=test');+ expect(sessionStorage.getItem(SESSION_KEY)).toBe('/c/deep-link?model=test');+ });+});+describe('login error redirect_to preservation (AuthContext onError pattern)', () => {/** Mirrors the logic in AuthContext.tsx loginUser.onError */function buildLoginErrorPath(search: string): string {@@ -273,39 +325,101 @@ describe('persistRedirectToSession', () => {});});+/**+ * Embedded and private contexts deny session storage by throwing on access. The destination is a+ * convenience, so a denial must degrade rather than take down the sign-in that carries it.+ */describe('blocked session storage', () => {- /** Embedded and private contexts throw on access rather than answering null. */- const originalDescriptor = Object.getOwnPropertyDescriptor(window, 'sessionStorage');+ const denyStorage = () => {+ const denied = () => {+ throw new DOMException('denied', 'SecurityError');+ };+ jest.spyOn(Storage.prototype, 'setItem').mockImplementation(denied);+ jest.spyOn(Storage.prototype, 'getItem').mockImplementation(denied);+ jest.spyOn(Storage.prototype, 'removeItem').mockImplementation(denied);+ };beforeEach(() => {- Object.defineProperty(window, 'sessionStorage', {- configurable: true,- get() {- throw new DOMException('Storage is blocked in this context', 'SecurityError');- },- });+ clearPostLoginRedirect();});- afterAll(() => {- if (originalDescriptor != null) {- Object.defineProperty(window, 'sessionStorage', originalDescriptor);- }+ afterEach(() => {+ jest.restoreAllMocks();+ clearPostLoginRedirect();});- it('persisting a destination does not take down the sign-in', () => {- expect(() => persistRedirectToSession('/c/new')).not.toThrow();+ it('does not throw when persisting a destination', () => {+ denyStorage();+ expect(() => persistRedirectToSession('/c/abc123')).not.toThrow();});- it('a blocked store reads as empty so the URL param still resolves', () => {- const params = new URLSearchParams('redirect_to=%2Fc%2Fnew');- expect(getPostLoginRedirect(params)).toBe('/c/new');+ it('does not throw when consuming a destination', () => {+ denyStorage();+ expect(() => getPostLoginRedirect(new URLSearchParams())).not.toThrow();+ });++ it('does not throw when clearing a destination', () => {+ denyStorage();+ expect(() => clearPostLoginRedirect()).not.toThrow();});- it('no destination resolves when only the blocked store exists', () => {+ it('still resolves the URL destination while storage is denied', () => {+ denyStorage();+ expect(getPostLoginRedirect(new URLSearchParams('redirect_to=%2Fc%2Fabc123'))).toBe(+ '/c/abc123',+ );+ });++ /** The in-document hand-off never replaces the document, so the mirror still reaches it. */+ it('carries the destination in memory across a persist and consume pair', () => {+ denyStorage();+ persistRedirectToSession('/c/abc123');++ expect(getPostLoginRedirect(new URLSearchParams())).toBe('/c/abc123');+ });++ it('consumes the in-memory destination exactly once', () => {+ denyStorage();+ persistRedirectToSession('/c/abc123');++ expect(getPostLoginRedirect(new URLSearchParams())).toBe('/c/abc123');+ expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();+ });++ it('drops the in-memory destination on clear', () => {+ denyStorage();+ persistRedirectToSession('/c/abc123');+ clearPostLoginRedirect();++ expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();+ });++ it('still refuses an unsafe destination while storage is denied', () => {+ denyStorage();+ persistRedirectToSession('https://evil.com');+expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();});- it('hasStoredRedirect counts a blocked store as empty', () => {- expect(hasStoredRedirect()).toBe(false);+ /**+ * Storage answers here, so it is the authority. A mirror written on every persist would outlive+ * a destination cleared straight out of storage and resurrect it on the next sign-in.+ */+ it('does not resurrect a destination dropped straight from storage', () => {+ persistRedirectToSession('/c/abc123');+ sessionStorage.clear();++ expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();+ });++ it('does not let a denied write outlive a later working one', () => {+ denyStorage();+ persistRedirectToSession('/c/denied');+ jest.restoreAllMocks();++ persistRedirectToSession('/c/stored');+ sessionStorage.clear();++ expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();});});diff --git a/client/src/utils/getLoginError.ts b/client/src/utils/getLoginError.tsindex 602c6dfc85..28b47f6d32 100644--- a/client/src/utils/getLoginError.ts+++ b/client/src/utils/getLoginError.ts@@ -1,4 +1,4 @@-import { ErrorTypes } from 'librechat-data-provider';+import { ErrorTypes, TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE } from 'librechat-data-provider';import { TranslationKeys } from '~/hooks';const getLoginError = (errorText: string): TranslationKeys => {@@ -11,6 +11,9 @@ const getLoginError = (errorText: string): TranslationKeys => {switch (true) {case errorText === ErrorTypes.AUTH_CROSS_ORIGIN:return 'com_auth_error_login_cross_origin';+ /** Must precede the status cases: this is also a 403, but it is not a ban. */+ case errorText.includes(TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE):+ return 'com_auth_error_login_federated_two_factor';case errorText.includes('429'):return 'com_auth_error_login_rl';case errorText.includes('403'):diff --git a/client/src/utils/redirect.ts b/client/src/utils/redirect.tsindex 0cde6615d8..737547a5b9 100644--- a/client/src/utils/redirect.ts+++ b/client/src/utils/redirect.ts@@ -1,3 +1,5 @@+import { readTwoFactorSetupToken } from 'librechat-data-provider';+export const REDIRECT_PARAM = 'redirect_to';export const SESSION_KEY = 'post_login_redirect_to';@@ -31,35 +33,64 @@ function resolvesToSameOrigin(url: string): boolean {}}-/** Session storage is blocked outright in embedded and private contexts, where it throws on- * access rather than returning null. The destination is a convenience, never a credential, so a- * blocked store must cost the deep link, never the sign-in that carries it: every access- * degrades to "no destination stored". Every other session-storage consumer in the client is- * already guarded this way; the redirect flow was the one reaching for the store bare-handed. */-export const readStoredRedirect = (): string | null => {+interface PostLoginRedirectWindow extends Window {+ __librechatPostLoginRedirect?: string;+}++/**+ * Session storage is blocked outright in embedded and private contexts, where it throws on access+ * rather than returning null. The destination is a convenience, never a credential, so a blocked+ * store must never take down the sign-in that carries it: access degrades to an in-memory mirror,+ * which still reaches the hand-offs that stay inside the document.+ *+ * Storage stays authoritative whenever it answers, and the mirror is written only where storage+ * refused. Mirroring every write would let a destination that storage has since dropped come back+ * from the dead.+ */+const readStoredRedirect = (): string | null => {try {- return sessionStorage.getItem(SESSION_KEY);+ return window.sessionStorage.getItem(SESSION_KEY);} catch {- return null;+ return (window as PostLoginRedirectWindow).__librechatPostLoginRedirect ?? null;}};-export const dropStoredRedirect = (): void => {+const writeStoredRedirect = (value: string): void => {try {- sessionStorage.removeItem(SESSION_KEY);+ window.sessionStorage.setItem(SESSION_KEY, value);+ delete (window as PostLoginRedirectWindow).__librechatPostLoginRedirect;} catch {- // A blocked store holds nothing to drop.+ (window as PostLoginRedirectWindow).__librechatPostLoginRedirect = value;}};-const writeStoredRedirect = (value: string): void => {+const dropStoredRedirect = (): void => {+ delete (window as PostLoginRedirectWindow).__librechatPostLoginRedirect;try {- sessionStorage.setItem(SESSION_KEY, value);+ window.sessionStorage.removeItem(SESSION_KEY);} catch {- // The destination cannot cross a document swap in this context; the sign-in continues.+ // Ignore unavailable storage.}};+/** Suffix rather than whole path, so a deployment served under a basename still matches. */+const SETUP_PATH_SUFFIX = '/login/2fa/setup';++/**+ * The mandatory enrollment screen holding a live setup token is a destination in its own right, so+ * it is exempt from the post-login redirects that would otherwise send an authenticated but+ * unenrolled user on to the app.+ *+ * The router matches case-insensitively and ignores a trailing slash, so recognising the route by+ * its exact spelling would strand anyone whose URL differs only in those: the screen renders, this+ * reports it unprotected, and the redirect pulls them off a live enrollment. Normalize the same way+ * the router does before comparing.+ */+export function isRequiredTwoFactorSetupRoute(): boolean {+ const pathname = window.location.pathname.toLowerCase().replace(/\/+$/, '');+ return pathname.endsWith(SETUP_PATH_SUFFIX) && !!readTwoFactorSetupToken();+}+/** Validates that a redirect target is a safe relative path (not an absolute or protocol-relative URL) */export function isSafeRedirect(url: string): boolean {if (hasControlChar(url)) {@@ -75,23 +106,27 @@ export function isSafeRedirect(url: string): boolean {return resolvesToSameOrigin(url);}-/** Whether a destination is waiting to be consumed; storage that refuses to answer counts as none. */-export const hasStoredRedirect = (): boolean => readStoredRedirect() != null;-/*** Resolves the post-login redirect from URL params and sessionStorage,* cleans up both sources, and returns the validated target (or null).*/export function getPostLoginRedirect(searchParams: URLSearchParams): string | null {+ const target = peekPostLoginRedirect(searchParams);+ dropStoredRedirect();+ return target;+}++/** Drops a pending destination, so a later sign-in starts from a clean slate. */+export function clearPostLoginRedirect(): void {+ dropStoredRedirect();+}++export function peekPostLoginRedirect(searchParams: URLSearchParams): string | null {const urlRedirect = searchParams.get(REDIRECT_PARAM);const storedRedirect = readStoredRedirect();const target = urlRedirect ?? storedRedirect;- if (storedRedirect) {- dropStoredRedirect();- }-if (target == null || !isSafeRedirect(target)) {return null;}diff --git a/config/reset-password.js b/config/reset-password.jsindex 3144ade839..3081a24fb0 100644--- a/config/reset-password.js+++ b/config/reset-password.js@@ -2,6 +2,7 @@ const path = require('path');const bcrypt = require('bcryptjs');const readline = require('readline');const mongoose = require('mongoose');+const { createPasswordResetUpdate } = require('@librechat/api');const { createModels, createMethods } = require('@librechat/data-schemas');const { User, Passkey, Session } = createModels(mongoose);require('module-alias')({ base: path.resolve(__dirname, '..', 'api') });@@ -67,11 +68,8 @@ const resetPassword = async () => {*/const updated = await methods.updateUser(user._id.toString(),- {- password: hashedPassword,- /** Access tokens minted before this stamp stop verifying */- credentialsChangedAt: new Date(),- },+ /** Stamps credentialsChangedAt and drops any staged enrollment, as the web reset does. */+ createPasswordResetUpdate(hashedPassword),{},{ preserveExpiresAt: true },);diff --git a/e2e/playwright.config.mock.ts b/e2e/playwright.config.mock.tsindex 544ed50845..a94fda2745 100644--- a/e2e/playwright.config.mock.ts+++ b/e2e/playwright.config.mock.ts@@ -167,6 +167,7 @@ const vanillaOverrides = {ALLOW_SOCIAL_LOGIN: 'false',ALLOW_SOCIAL_REGISTRATION: 'false',ALLOW_SHARED_LINKS_PUBLIC: 'true',+ ENFORCE_TWO_FACTOR_AUTHENTICATION: 'false',STREAM_KEEP_COMPLETED_JOBS: 'true',FORK_IP_MAX: '100',FORK_USER_MAX: '100',diff --git a/e2e/specs/mock/scenarios/passkeys.spec.ts b/e2e/specs/mock/scenarios/passkeys.spec.tsindex 58f359b0a3..a0376d4139 100644--- a/e2e/specs/mock/scenarios/passkeys.spec.ts+++ b/e2e/specs/mock/scenarios/passkeys.spec.ts@@ -369,6 +369,48 @@ test.describe('passkeys', () => {await expect(page.getByTestId('nav-user')).toHaveCount(0);});+ test('a passkey sign-in on an account that must enroll opens two-factor setup @scenario:required-2fa-passkey-sign-in-hands-off-setup', async ({+ browser,+ playwright,+ baseURL,+ }) => {+ test.setTimeout(90000);+ const request = await playwright.request.newContext({ baseURL: passkeyBaseURL(baseURL) });+ user = await createFreshUser(request);+ context = await openContextFor(browser, request, passkeyBaseURL(baseURL));+ await request.dispose();+ const page = await context.newPage();+ await addVirtualAuthenticator(page);++ await addPasskey(page, user.password);+ await logOut(page);+ /**+ * The harness runs with enforcement off, so the ceremony is verified for real and the+ * answer is replaced with the payload the server returns under enforcement.+ */+ await context.route('**/api/auth/passkey/login/verify', async (route) => {+ const response = await route.fetch();+ expect(response.ok()).toBeTruthy();+ await route.fulfill({+ response,+ json: {+ code: 'TWO_FACTOR_ENROLLMENT_REQUIRED',+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'passkey-setup-token',+ },+ });+ });+ await signInWithPasskey(page);++ await expect(page).toHaveURL(/\/login\/2fa\/setup$/, { timeout: 15000 });+ expect(await page.evaluate(() => window.sessionStorage.getItem('two_factor_setup_token'))).toBe(+ 'passkey-setup-token',+ );+ await expect(page.getByRole('button', { name: 'Generate QR Code' })).toBeVisible();+ await expect(page.getByTestId('nav-user')).toHaveCount(0);+ });+test('a password reset revokes earlier access tokens and removes passkeys @scenario:password-reset-revokes-tokens-and-passkeys', async ({playwright,baseURL,diff --git a/e2e/specs/mock/scenarios/two-factor-required.spec.ts b/e2e/specs/mock/scenarios/two-factor-required.spec.tsnew file mode 100644index 0000000000..bfde7abb00--- /dev/null+++ b/e2e/specs/mock/scenarios/two-factor-required.spec.ts@@ -0,0 +1,320 @@+import { randomUUID } from 'node:crypto';+import { expect, test } from '@playwright/test';+import type { Route } from '@playwright/test';+import type { TStartupConfig, TUser } from 'librechat-data-provider';+import { NEW_CHAT_PATH } from '../helpers';+import { seedConversations, seedMessages } from '../db';+import { loginAdmin } from '../content-filters.helpers';++/**+ * Acceptance scenarios for deployment-wide 2FA enforcement. The mock harness starts the server+ * with ENFORCE_TWO_FACTOR_AUTHENTICATION disabled (an inherited deployment .env would otherwise+ * hold every other spec's user out of the app), so each policy response is produced at the route+ * boundary exactly as the server emits it under enforcement, matching two-factor-required.spec.ts.+ */++/** No query string: the setup credential is handed over out of band, never through the URL. */+const SETUP_ROUTE_PATTERN = /\/login\/2fa\/setup$/;+/** Enforcement redirects park the destination in the query, so the route may carry one. */+const SETUP_URL_PATTERN = /\/login\/2fa\/setup(?:\?[^#]*)?$/;+const LOGIN_ROUTE_PATTERN = /\/login$/;+const SETUP_TOKEN_STORAGE_KEY = 'two_factor_setup_token';++const ENFORCEMENT_PAYLOAD = {+ code: 'TWO_FACTOR_ENROLLMENT_REQUIRED',+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'scenario-setup-token',+};++const json = (route: Route, body: unknown, status = 200) =>+ route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) });++test.describe('required two-factor enrollment · unauthenticated arrival', () => {+ /** The PWA service worker serves API GETs itself, which would bypass every `page.route` below. */+ test.use({ storageState: { cookies: [], origins: [] }, serviceWorkers: 'block' });++ test('a password login hands an unenrolled user to setup instead of a session @scenario:required-2fa-login-hands-off-setup', async ({+ page,+ }, testInfo) => {+ test.setTimeout(60000);+ await page.route('**/api/auth/login', (route) => json(route, ENFORCEMENT_PAYLOAD));++ await page.goto('/login');+ await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');+ await page.getByRole('textbox', { name: 'Password' }).fill('password');+ await page.getByRole('button', { name: 'Continue' }).click();++ await expect(page).toHaveURL(SETUP_ROUTE_PATTERN);+ expect(page.url()).not.toContain('tempToken');+ expect(+ await page.evaluate((key) => window.sessionStorage.getItem(key), SETUP_TOKEN_STORAGE_KEY),+ ).toBe('scenario-setup-token');+ await expect(page.getByRole('button', { name: 'Generate QR Code' })).toBeVisible();+ await testInfo.attach('required-two-factor-setup', {+ body: await page.screenshot(),+ contentType: 'image/png',+ });+ });++ test('a direct visit to setup adopts the token a later refresh hands off @scenario:required-2fa-setup-adopts-refreshed-token', async ({+ page,+ }) => {+ test.setTimeout(60000);+ let releaseRefresh!: () => void;+ const refreshReleased = new Promise<void>((resolve) => {+ releaseRefresh = resolve;+ });+ /** Held until the screen has rendered without a credential, so the hand-off arrives late. */+ await page.route('**/api/auth/refresh', async (route) => {+ await refreshReleased;+ await json(route, ENFORCEMENT_PAYLOAD);+ });++ await page.goto('/login/2fa/setup');+ const expired = page.getByRole('alert').filter({ hasText: 'missing or expired' });+ await expect(expired).toBeVisible();++ releaseRefresh();++ await expect(page.getByRole('button', { name: 'Generate QR Code' })).toBeVisible();+ await expect(expired).toHaveCount(0);+ await expect(page).toHaveURL(SETUP_ROUTE_PATTERN);+ });++ test('completing enrollment lands on the original deep link @scenario:required-2fa-enrollment-preserves-deep-link', async ({+ page,+ request,+ }) => {+ test.setTimeout(90000);+ /** The separate API cookie jar leaves the browser unauthenticated until finalization. */+ const authToken = await loginAdmin(request);+ const userResponse = await request.get('/api/user', {+ headers: { Authorization: `Bearer ${authToken}` },+ });+ expect(userResponse.ok()).toBe(true);+ const enrolledUser = { ...((await userResponse.json()) as TUser), twoFactorEnabled: true };+ /** A real destination lets the app load it instead of correctly redirecting a missing chat. */+ const conversationId = randomUUID();+ const deepLink = `/c/${conversationId}?source=required-2fa-test`;+ const deepLinkPattern = new RegExp(`/c/${conversationId}\\?source=required-2fa-test$`);+ const transcriptMarker = 'Conversation restored after required two-factor enrollment';+ await seedConversations(enrolledUser.email, [+ { conversationId, title: 'Required enrollment destination', updatedAt: new Date() },+ ]);+ await seedMessages(enrolledUser.email, conversationId, [+ {+ messageId: randomUUID(),+ parentMessageId: '00000000-0000-0000-0000-000000000000',+ text: transcriptMarker,+ isCreatedByUser: false,+ sender: 'Assistant',+ },+ ]);+ /** Flips only once finalization has promoted the enrollment and minted the session. */+ let finalized = false;++ await page.route('**/api/auth/login', (route) => json(route, ENFORCEMENT_PAYLOAD));+ /** Before finalization the user holds no refresh session, exactly as the server leaves them+ * after a required-enrollment login; afterwards the promoted session refreshes normally. */+ await page.route('**/api/auth/refresh', async (route) => {+ if (!finalized) {+ await route.fulfill({+ status: 200,+ contentType: 'text/html; charset=utf-8',+ body: 'Refresh token not provided',+ });+ return;+ }+ await json(route, { token: authToken, user: enrolledUser });+ });+ await page.route('**/api/user', async (route) => {+ if (!finalized) {+ await json(route, { message: 'Unauthorized' }, 401);+ return;+ }+ await json(route, enrolledUser);+ });+ await page.route('**/api/roles/**', (route) => json(route, { name: 'USER', permissions: {} }));+ await page.route('**/api/auth/2fa/setup', (route) =>+ json(route, {+ otpauthUrl: 'otpauth://totp/LibreChat:[email protected]?secret=ABC123&issuer=LibreChat',+ backupCodes: ['backup01', 'backup02'],+ }),+ );+ await page.route('**/api/auth/2fa/setup/confirm', (route) =>+ json(route, {+ backupCodes: ['confirmed-backup01', 'confirmed-backup02'],+ acknowledgementToken: 'acknowledgement-token',+ }),+ );+ await page.route('**/api/auth/2fa/setup/acknowledge', (route) =>+ json(route, { finalizationToken: 'finalization-token' }),+ );+ await page.route('**/api/auth/2fa/setup/finalize', async (route) => {+ finalized = true;+ await json(route, { token: authToken, user: enrolledUser });+ });++ await page.goto(`/login?redirect_to=${encodeURIComponent(deepLink)}`);+ await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');+ await page.getByRole('textbox', { name: 'Password' }).fill('password');+ await page.getByRole('button', { name: 'Continue' }).click();++ await expect(page).toHaveURL(SETUP_ROUTE_PATTERN);+ await page.getByRole('button', { name: 'Generate QR Code' }).click();+ await expect(page.getByRole('img', { name: 'Scan QR Code' })).toBeVisible();+ await page.getByRole('button', { name: 'Continue' }).click();+ await page.getByLabel('Enter your 2FA code to continue').fill('123456');+ await page.getByRole('button', { name: 'Verify' }).click();++ const completeButton = page.getByRole('button', { name: 'Complete Setup' });+ await expect(completeButton).toBeDisabled();+ await page.getByRole('button', { name: 'Download Backup Codes' }).click();+ await expect(completeButton).toBeEnabled();+ const enrollmentDestination = page.waitForURL(deepLinkPattern);+ await completeButton.click();+ await enrollmentDestination;+ /** The authenticated shell mounts and settles here rather than bouncing back to /login. */+ await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible();+ await expect(+ page.locator('.message-render').filter({ hasText: transcriptMarker }),+ ).toBeVisible();+ /** Loading a conversation canonicalizes its URL after the complete destination is delivered. */+ await expect(page).toHaveURL(new RegExp(`/c/${conversationId}$`));+ });++ test('an expired setup credential returns the user to sign in @scenario:required-2fa-expired-credential-returns-to-signin', async ({+ page,+ }) => {+ test.setTimeout(60000);+ await page.addInitScript(([key, value]) => window.sessionStorage.setItem(key, value), [+ SETUP_TOKEN_STORAGE_KEY,+ 'spent-setup-token',+ ] as const);+ await page.route('**/api/auth/2fa/setup', (route) =>+ json(route, { message: 'Invalid or expired two-factor setup token' }, 401),+ );++ await page.goto('/login/2fa/setup');+ await page.getByRole('button', { name: 'Generate QR Code' }).click();++ /** The screen retires itself rather than replaying a credential the server can never accept. */+ await expect(page).toHaveURL(LOGIN_ROUTE_PATTERN);+ expect(+ await page.evaluate((key) => window.sessionStorage.getItem(key), SETUP_TOKEN_STORAGE_KEY),+ ).toBeNull();+ await expect(page.getByRole('textbox', { name: 'Email' })).toBeVisible();+ });+});++test.describe('required two-factor enrollment · authenticated arrival', () => {+ test('an enforcement 403 moves a loaded app into setup without a reload @scenario:required-2fa-enforcement-403-redirects-loaded-app', async ({+ page,+ }) => {+ test.setTimeout(60000);+ await page.route('**/api/convos**', (route) => json(route, ENFORCEMENT_PAYLOAD, 403));+ /** Under enforcement the refresh endpoint hands off to setup as well, so the hard navigation+ * that follows the redirect cannot silently refresh its way back into the app. */+ await page.route('**/api/auth/refresh', (route) => json(route, ENFORCEMENT_PAYLOAD));++ await page.goto(NEW_CHAT_PATH, { timeout: 15000 });++ await expect(page).toHaveURL(SETUP_URL_PATTERN, { timeout: 15000 });+ expect(+ await page.evaluate((key) => window.sessionStorage.getItem(key), SETUP_TOKEN_STORAGE_KEY),+ ).toBe('scenario-setup-token');+ await expect(page.getByRole('button', { name: 'Generate QR Code' })).toBeVisible();+ });++ test('a tab still moves into setup after a sibling tab started its hand-off @scenario:required-2fa-sibling-tab-hands-off-setup', async ({+ page,+ }) => {+ test.setTimeout(60000);+ let releaseEnforcement!: () => void;+ const enforcementReleased = new Promise<void>((resolve) => {+ releaseEnforcement = resolve;+ });+ /** Held until the sibling tab's navigation marker is in the shared storage. */+ await page.route('**/api/convos**', async (route) => {+ await enforcementReleased;+ await json(route, ENFORCEMENT_PAYLOAD, 403);+ });+ await page.route('**/api/auth/refresh', (route) => json(route, ENFORCEMENT_PAYLOAD));++ await page.goto(NEW_CHAT_PATH, { timeout: 15000 });+ await page.evaluate(() =>+ window.localStorage.setItem('librechat.auth.redirect.startedAt', String(Date.now())),+ );+ releaseEnforcement();++ await expect(page).toHaveURL(SETUP_URL_PATTERN, { timeout: 15000 });+ expect(+ await page.evaluate((key) => window.sessionStorage.getItem(key), SETUP_TOKEN_STORAGE_KEY),+ ).toBe('scenario-setup-token');+ await expect(page.getByRole('button', { name: 'Generate QR Code' })).toBeVisible();+ });++ test('a refresh hand-off moves a loaded app into setup @scenario:required-2fa-refresh-response-hands-off-setup', async ({+ page,+ }) => {+ test.setTimeout(60000);+ /** A 401 on a protected query is what drives the client into its refresh-recovery path. */+ await page.route('**/api/convos**', (route) => json(route, { message: 'Unauthorized' }, 401));+ await page.route('**/api/auth/refresh', (route) => json(route, ENFORCEMENT_PAYLOAD));++ await page.goto(NEW_CHAT_PATH, { timeout: 15000 });++ await expect(page).toHaveURL(SETUP_URL_PATTERN, { timeout: 15000 });+ expect(+ await page.evaluate((key) => window.sessionStorage.getItem(key), SETUP_TOKEN_STORAGE_KEY),+ ).toBe('scenario-setup-token');+ await expect(page.getByRole('button', { name: 'Generate QR Code' })).toBeVisible();+ });++ test('the Disable 2FA control stays visible and locked with its reason @scenario:required-2fa-disable-control-locked', async ({+ page,+ isMobile,+ }, testInfo) => {+ test.setTimeout(60000);+ await page.route('**/api/config', async (route) => {+ const response = await route.fetch();+ const config = (await response.json()) as TStartupConfig;+ config.twoFactorAuthenticationRequired = true;+ await route.fulfill({ response, json: config });+ });+ await page.route('**/api/user', async (route) => {+ const response = await route.fetch();+ const user = (await response.json()) as { twoFactorEnabled?: boolean };+ user.twoFactorEnabled = true;+ await route.fulfill({ response, json: user });+ });++ await page.goto(NEW_CHAT_PATH, { timeout: 15000 });+ if (isMobile) {+ await page.getByRole('button', { name: 'Open sidebar' }).click();+ }+ await page.getByTestId('nav-user').click();+ await page.getByRole('menuitem', { name: 'Settings' }).click();+ await page.getByRole('tab', { name: 'Account' }).click();++ const disableButton = page.getByRole('button', { name: 'Disable 2FA' });+ const tooltipTrigger = page.getByTestId('required-2fa-disable-control');+ await expect(disableButton).toBeVisible();+ await expect(disableButton).toBeDisabled();++ /** The reason reaches keyboard users, not just pointer users. */+ for (let tabCount = 0; tabCount < 20; tabCount++) {+ await page.keyboard.press('Tab');+ if (await tooltipTrigger.evaluate((element) => document.activeElement === element)) {+ break;+ }+ }+ await expect(tooltipTrigger).toBeFocused();+ await expect(page.getByRole('tooltip')).toHaveText('Required by administrator');+ await testInfo.attach('required-two-factor-disable-control', {+ body: await page.screenshot(),+ contentType: 'image/png',+ });+ });+});diff --git a/e2e/specs/mock/two-factor-required.spec.ts b/e2e/specs/mock/two-factor-required.spec.tsnew file mode 100644index 0000000000..e376a7637e--- /dev/null+++ b/e2e/specs/mock/two-factor-required.spec.ts@@ -0,0 +1,129 @@+import { expect, test } from '@playwright/test';+import type { Route } from '@playwright/test';++/** A non-default destination: reaching it proves the deep link outlived the whole enrollment. */+const DEEP_LINK = '/c/redirect-lifecycle-proof?model=test';+const DEEP_LINK_PATTERN = /\/c\/redirect-lifecycle-proof\?model=test$/;+/** No query string: the setup credential is handed over out of band, never through the URL. */+const SETUP_ROUTE_PATTERN = /\/login\/2fa\/setup$/;++const ENROLLED_USER = {+ id: 'user-1',+ _id: 'user-1',+ name: 'Two Factor User',+ username: 'twofactor',+ email: '[email protected]',+ provider: 'local',+ role: 'USER',+ emailVerified: true,+ twoFactorEnabled: true,+ createdAt: '2026-01-01T00:00:00.000Z',+ updatedAt: '2026-01-01T00:00:00.000Z',+};++const json = (route: Route, body: unknown, status = 200) =>+ route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) });++/** The PWA service worker serves API GETs itself, which would bypass every `page.route` below. */+test.use({ storageState: { cookies: [], origins: [] }, serviceWorkers: 'block' });++test.describe('required two-factor enrollment', () => {+ test('completes setup after backup acknowledgement and holds the deep link', async ({ page }) => {+ test.setTimeout(60000);+ /** Flips only once finalization has promoted the enrollment and minted the session. */+ let finalized = false;++ await page.route('**/api/auth/login', (route) =>+ json(route, { twoFAPending: true, twoFASetupRequired: true, tempToken: 'setup-token' }),+ );+ /** Before finalization the user holds no refresh session, exactly as the server leaves them+ * after a required-enrollment login; afterwards the promoted session refreshes normally. */+ await page.route('**/api/auth/refresh', async (route) => {+ if (!finalized) {+ await route.fulfill({+ status: 200,+ contentType: 'text/html; charset=utf-8',+ body: 'Refresh token not provided',+ });+ return;+ }+ await json(route, { token: 'auth-token', user: ENROLLED_USER });+ });+ await page.route('**/api/user', async (route) => {+ if (!finalized) {+ await json(route, { message: 'Unauthorized' }, 401);+ return;+ }+ await json(route, ENROLLED_USER);+ });+ await page.route('**/api/roles/**', (route) => json(route, { name: 'USER', permissions: {} }));+ await page.route('**/api/auth/2fa/setup', (route) =>+ json(route, {+ otpauthUrl: 'otpauth://totp/LibreChat:[email protected]?secret=ABC123&issuer=LibreChat',+ backupCodes: ['backup01', 'backup02'],+ }),+ );+ await page.route('**/api/auth/2fa/setup/confirm', (route) =>+ json(route, {+ backupCodes: ['confirmed-backup01', 'confirmed-backup02'],+ acknowledgementToken: 'acknowledgement-token',+ }),+ );+ await page.route('**/api/auth/2fa/setup/acknowledge', async (route) => {+ expect(route.request().postDataJSON()).toEqual({+ acknowledgementToken: 'acknowledgement-token',+ });+ await json(route, { finalizationToken: 'finalization-token' });+ });+ await page.route('**/api/auth/2fa/setup/finalize', async (route) => {+ expect(route.request().postDataJSON()).toEqual({ finalizationToken: 'finalization-token' });+ finalized = true;+ await json(route, { token: 'auth-token', user: ENROLLED_USER });+ });++ await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);+ await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');+ await page.getByRole('textbox', { name: 'Password' }).fill('password');+ await page.getByRole('button', { name: 'Continue' }).click();++ await expect(page).toHaveURL(SETUP_ROUTE_PATTERN);+ expect(await page.evaluate(() => window.sessionStorage.getItem('two_factor_setup_token'))).toBe(+ 'setup-token',+ );+ await page.reload();+ await expect(page).toHaveURL(SETUP_ROUTE_PATTERN);+ const generateButton = page.getByRole('button', { name: 'Generate QR Code' });+ const setupCardBox = await generateButton.locator('..').boundingBox();+ expect(setupCardBox?.width).toBeGreaterThanOrEqual(430);+ await generateButton.click();++ await expect(page.getByRole('img', { name: 'Scan QR Code' })).toBeVisible();+ await expect(page.getByLabel('Secret Key')).toHaveValue('ABC123');+ await page.getByRole('button', { name: 'Continue' }).click();+ await page.getByLabel('Enter your 2FA code to continue').fill('123456');+ await page.getByRole('button', { name: 'Verify' }).click();++ const completeButton = page.getByRole('button', { name: 'Complete Setup' });+ await expect(page).toHaveURL(SETUP_ROUTE_PATTERN);+ await expect(completeButton).toBeDisabled();+ const downloadPromise = page.waitForEvent('download');+ await page.getByRole('button', { name: 'Download Backup Codes' }).click();+ const download = await downloadPromise;+ expect(download.suggestedFilename()).toBe('backup-codes.txt');+ await expect(completeButton).toBeEnabled();+ await completeButton.click();++ await expect(page).toHaveURL(DEEP_LINK_PATTERN);+ /** The authenticated shell mounts and settles here rather than bouncing back to /login. */+ await expect(page.getByTestId('nav-user')).toBeVisible();+ /** A fixed window is the point: the destination must survive the follow-up auth traffic. */+ await page.waitForTimeout(3000);+ await expect(page).toHaveURL(DEEP_LINK_PATTERN);++ /** A reload now authenticates through the refreshed session and stays on the deep link. */+ await page.reload();+ await expect(page.getByTestId('nav-user')).toBeVisible();+ await page.waitForTimeout(3000);+ await expect(page).toHaveURL(DEEP_LINK_PATTERN);+ });+});diff --git a/e2e/specs/mock/two-factor.spec.ts b/e2e/specs/mock/two-factor.spec.tsindex 40da3dba61..c8a1f2a208 100644--- a/e2e/specs/mock/two-factor.spec.ts+++ b/e2e/specs/mock/two-factor.spec.ts@@ -1,4 +1,5 @@import { expect, test } from '@playwright/test';+import type { TStartupConfig } from 'librechat-data-provider';import { NEW_CHAT_PATH } from './helpers';/**@@ -86,4 +87,47 @@ test.describe('account settings · two-factor dialog', () => {`framer-motion threw while rendering the 2FA dialog: ${framerErrors.join(' | ')}`,).toEqual([]);});++ test('explains why an administrator-required 2FA control cannot be disabled', async ({+ page,+ }) => {+ await page.route('**/api/config', async (route) => {+ const response = await route.fetch();+ const config = (await response.json()) as TStartupConfig;+ config.twoFactorAuthenticationRequired = true;+ await route.fulfill({ response, json: config });+ });+ await page.route('**/api/user', async (route) => {+ const response = await route.fetch();+ const user = (await response.json()) as { twoFactorEnabled?: boolean };+ user.twoFactorEnabled = true;+ await route.fulfill({ response, json: user });+ });++ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });+ await page.getByTestId('nav-user').click();+ await page.getByRole('menuitem', { name: 'Settings' }).click();+ await page.getByRole('tab', { name: 'Account' }).click();++ const disableButton = page.getByRole('button', { name: 'Disable 2FA' });+ const tooltipTrigger = page.getByTestId('required-2fa-disable-control');++ await expect(disableButton).toBeDisabled();+ await expect(tooltipTrigger).toHaveCSS('cursor', 'not-allowed');++ for (let tabCount = 0; tabCount < 20; tabCount++) {+ await page.keyboard.press('Tab');+ if (await tooltipTrigger.evaluate((element) => document.activeElement === element)) {+ break;+ }+ }+ await expect(tooltipTrigger).toBeFocused();+ await expect(page.getByRole('tooltip')).toHaveText('Required by administrator');++ await page.keyboard.press('Tab');+ await expect(page.getByRole('tooltip')).toBeHidden();+ await page.mouse.move(0, 0);+ await tooltipTrigger.hover();+ await expect(page.getByRole('tooltip')).toHaveText('Required by administrator');+ });});diff --git a/eslint-suppressions.json b/eslint-suppressions.jsonindex 07cbcd1899..072fbfc2d3 100644--- a/eslint-suppressions.json+++ b/eslint-suppressions.json@@ -1198,7 +1198,7 @@},"client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/QRPhase.tsx": {"shadcn/no-restyle": {- "count": 4+ "count": 3}},"client/src/components/Nav/SettingsTabs/Account/TwoFactorPhases/VerifyPhase.tsx": {diff --git a/packages/api/src/apiKeys/middleware.auth.spec.ts b/packages/api/src/apiKeys/middleware.auth.spec.tsindex e78e94ed5c..787007cf61 100644--- a/packages/api/src/apiKeys/middleware.auth.spec.ts+++ b/packages/api/src/apiKeys/middleware.auth.spec.ts@@ -1,4 +1,5 @@import { Types } from 'mongoose';+import { TWO_FACTOR_ENROLLMENT_REQUIRED_CODE } from 'librechat-data-provider';import type { NextFunction, Response } from 'express';import type { ApiKeyAuthRequest } from './middleware';import { createRequireApiKeyAuth } from './middleware';@@ -68,6 +69,57 @@ describe('remote Agent API key authentication', () => {expect(next).toHaveBeenCalledWith();});+ describe('under required two-factor enforcement', () => {+ const original = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ });+ afterEach(() => {+ if (original === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = original;+ }+ });++ const authenticate = async (owner: Record<string, unknown>) => {+ const userId = new Types.ObjectId();+ const middleware = createRequireApiKeyAuth({+ validateAgentApiKey: jest.fn().mockResolvedValue({ userId, keyId: new Types.ObjectId() }),+ findUser: jest.fn().mockResolvedValue({ _id: userId, ...owner }),+ isPrincipalActive: jest.fn().mockResolvedValue(true),+ });+ const req = createRequest();+ const response = createResponse();+ const next = jest.fn() as NextFunction;+ await middleware(req, response.res, next);+ return { req, next, ...response };+ };++ it('refuses a key whose local owner has not enrolled', async () => {+ const { req, next, status, json } = await authenticate({ provider: 'local' });++ expect(status).toHaveBeenCalledWith(403);+ expect(json).toHaveBeenCalledWith({+ error: expect.objectContaining({ code: TWO_FACTOR_ENROLLMENT_REQUIRED_CODE }),+ });+ expect(req.user).toBeUndefined();+ expect(next).not.toHaveBeenCalled();+ });++ it('admits a key whose owner has enrolled', async () => {+ const { next } = await authenticate({ provider: 'local', twoFactorEnabled: true });++ expect(next).toHaveBeenCalledWith();+ });++ it('admits a key whose owner signs in through a federated provider', async () => {+ const { next } = await authenticate({ provider: 'openid' });++ expect(next).toHaveBeenCalledWith();+ });+ });+it('starts the user and deletion-fence reads together', async () => {const userId = new Types.ObjectId();let resolveUser!: (user: { _id: Types.ObjectId }) => void;diff --git a/packages/api/src/apiKeys/middleware.ts b/packages/api/src/apiKeys/middleware.tsindex f18c693bf6..ba6082726b 100644--- a/packages/api/src/apiKeys/middleware.ts+++ b/packages/api/src/apiKeys/middleware.ts@@ -1,8 +1,14 @@import { logger } from '@librechat/data-schemas';-import { ResourceType, PermissionBits, hasPermissions } from 'librechat-data-provider';+import {+ ResourceType,+ PermissionBits,+ hasPermissions,+ TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+} from 'librechat-data-provider';import type { Request, Response, NextFunction, RequestHandler } from 'express';import type { IUser } from '@librechat/data-schemas';import type { Types } from 'mongoose';+import { isTwoFactorEnrollmentRequired } from '~/auth/twoFactor';import { getRemoteAgentPermissions } from './service';export interface ApiKeyAuthDependencies {@@ -12,6 +18,7 @@ export interface ApiKeyAuthDependencies {} | null>;findUser: (query: { _id: string | Types.ObjectId }) => Promise<IUser | null>;isPrincipalActive: (userId: string) => Promise<boolean>;+ enrollmentRequired?: typeof isTwoFactorEnrollmentRequired;}export interface RemoteAgentAccessDependencies {@@ -107,6 +114,16 @@ export function createRequireApiKeyAuth(deps: ApiKeyAuthDependencies) {},});}+ /** A key outlives the enforcement switch, so it waits on enrollment like the owner's session. */+ if ((deps.enrollmentRequired ?? isTwoFactorEnrollmentRequired)(user)) {+ return res.status(403).json({+ error: {+ message: 'Two-factor authentication must be enabled for this account',+ type: 'permission_error',+ code: TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+ },+ });+ }req.user = user as IUser & { id: string };req.apiKeyId = keyValidation.keyId;diff --git a/packages/api/src/auth/enrollment.ts b/packages/api/src/auth/enrollment.tsnew file mode 100644index 0000000000..78c0fb74e1--- /dev/null+++ b/packages/api/src/auth/enrollment.ts@@ -0,0 +1,251 @@+import { logger } from '@librechat/data-schemas';+import { TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE } from 'librechat-data-provider';+import type { TwoFactorEnrollmentUpdate } from '@librechat/data-schemas';+import type { Request, Response } from 'express';+import type { TwoFactorEnrollmentDependencies, StoredTwoFactorAccount } from './twoFactor';+import type { UserDocumentId } from '~/auth/verification';+import {+ TOKEN_RETIREMENT_FIELDS,+ acknowledgeTwoFactorSetup,+ confirmTwoFactorSetup,+ finalizeTwoFactorSetup,+ generateTwoFactorSetupAcknowledgementToken,+ generateTwoFactorSetupFinalizationToken,+ isCredentialLoginBlockedByTwoFactorPolicy,+ isEnrollmentSupersededByRecovery,+ isTokenRetired,+ recheckMintedCredential,+ withdrawMintedSession,+ verifyTwoFactorLoginChallengeToken,+} from './twoFactor';+import { sanitizeUserForResponse } from './user';+import { clearCloudFrontCookies } from '~/cdn';++type LoginChallengeBody = { tempToken?: string; token?: string; backupCode?: string };+type SetupBody = { token?: string };+type ChallengeRequest = Request<Record<string, string>, object, LoginChallengeBody>;+type SetupRequest = Request<Record<string, string>, object, SetupBody> & {+ user?: { id: string };+ twoFactorEnrollmentNonce?: string;+};++export function clearEnrollmentNonces(+ update: TwoFactorEnrollmentUpdate,+): TwoFactorEnrollmentUpdate {+ return {+ ...update,+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ };+}++export interface EnrollmentControllerDependencies+ extends Omit<TwoFactorEnrollmentDependencies, 'getUserById' | 'getTOTPSecret' | 'verifyTOTP'> {+ getUserById: (userId: string, projection: string) => Promise<StoredTwoFactorAccount | null>;+ getTOTPSecret: (storedSecret: string | null | undefined) => Promise<string | null>;+ verifyTOTP: (secret: string | null, token: string) => Promise<boolean>;+ verifyBackupCode: (input: {+ user: StoredTwoFactorAccount;+ backupCode: string;+ }) => Promise<boolean>;+ deleteAllUserSessions: (input: { userId: string }) => Promise<object>;+ clearCloudFrontCookies: typeof clearCloudFrontCookies;+ setAuthTokens: (+ userId: UserDocumentId,+ res: Response,+ unused: null,+ req: Request,+ ) => Promise<string>;+}++interface EnrollmentControllers {+ verify2FAWithTempToken: (req: ChallengeRequest, res: Response) => Promise<Response>;+ confirm2FASetupWithTempToken: (req: SetupRequest, res: Response) => Promise<Response>;+ acknowledge2FASetup: (req: SetupRequest, res: Response) => Promise<Response>;+ finalize2FASetup: (req: SetupRequest, res: Response) => Promise<Response>;+}++export function createEnrollmentControllers(+ deps: EnrollmentControllerDependencies,+): EnrollmentControllers {+ const sanitizeUser = (user: StoredTwoFactorAccount) => ({+ ...sanitizeUserForResponse(user),+ id: user._id.toString(),+ });++ const revokeMintedSession = (+ res: Response,+ user: StoredTwoFactorAccount,+ userId: string,+ ): Promise<void> => withdrawMintedSession(res, user, userId, deps);++ const verify2FAWithTempToken = async (+ req: ChallengeRequest,+ res: Response,+ ): Promise<Response> => {+ try {+ const { tempToken, token, backupCode } = req.body;+ if (!tempToken) {+ return res.status(400).json({ message: 'Missing temporary token' });+ }++ const credential = verifyTwoFactorLoginChallengeToken(tempToken, process.env.JWT_SECRET);+ if (!credential) {+ return res.status(401).json({ message: 'Invalid or expired temporary token' });+ }++ const user = await deps.getUserById(credential.userId, '+totpSecret +backupCodes');+ if (!user || !user.twoFactorEnabled) {+ return res.status(400).json({ message: '2FA is not enabled for this user' });+ }++ if (isCredentialLoginBlockedByTwoFactorPolicy(user)) {+ logger.warn(+ `[verify2FAWithTempToken] Refused a password challenge for a federated record under required 2FA [provider: ${user.provider}]`,+ );+ return res.status(403).json({+ code: TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE,+ message: 'Sign in with your identity provider to continue.',+ });+ }++ if (isTokenRetired(credential, user)) {+ logger.warn(+ `[verify2FAWithTempToken] Challenge predates enrollment or password reset: userId=${credential.userId}`,+ );+ return res.status(401).json({ message: 'Invalid or expired temporary token' });+ }++ const secret = await deps.getTOTPSecret(user.totpSecret);+ let isVerified = false;+ if (token) {+ isVerified = await deps.verifyTOTP(secret, token);+ } else if (backupCode) {+ isVerified = await deps.verifyBackupCode({ user, backupCode });+ }++ if (!isVerified) {+ return res.status(401).json({ message: 'Invalid 2FA code or backup code' });+ }++ const userData = sanitizeUser(user);+ const authToken = await deps.setAuthTokens(user._id, res, null, req);+ const retirement = await recheckMintedCredential(+ () => deps.getUserById(credential.userId, TOKEN_RETIREMENT_FIELDS),+ () => revokeMintedSession(res, user, credential.userId),+ );+ if (isTokenRetired(credential, retirement)) {+ logger.warn(+ `[verify2FAWithTempToken] Password was reset while the challenge was being verified: userId=${credential.userId}`,+ );+ await revokeMintedSession(res, user, credential.userId);+ return res.status(401).json({ message: 'Invalid or expired temporary token' });+ }++ return res.status(200).json({ token: authToken, user: userData });+ } catch (err) {+ logger.error('[verify2FAWithTempToken]', err);+ return res.status(500).json({ message: 'Something went wrong' });+ }+ };++ const confirm2FASetupWithTempToken = async (+ req: SetupRequest,+ res: Response,+ ): Promise<Response> => {+ try {+ const userId = req.user?.id;+ if (!userId) {+ return res.status(401).json({ message: 'Invalid or expired two-factor setup token' });+ }++ const result = await confirmTwoFactorSetup(userId, req.body?.token, deps);+ if (!result.ok) {+ return res.status(result.status).json({ message: result.message });+ }++ const acknowledgementToken = generateTwoFactorSetupAcknowledgementToken(+ userId,+ result.acknowledgementNonce,+ process.env.JWT_SECRET!,+ );+ return res.status(200).json({ backupCodes: result.plainCodes, acknowledgementToken });+ } catch (err) {+ logger.error('[confirm2FASetupWithTempToken]', err);+ return res.status(500).json({ message: 'Something went wrong' });+ }+ };++ const acknowledge2FASetup = async (req: SetupRequest, res: Response): Promise<Response> => {+ try {+ const userId = req.user?.id;+ if (!userId) {+ return res+ .status(401)+ .json({ message: 'Invalid or expired two-factor acknowledgement token' });+ }++ const result = await acknowledgeTwoFactorSetup(userId, req.twoFactorEnrollmentNonce, deps);+ if (!result.ok) {+ return res.status(result.status).json({ message: result.message });+ }++ const finalizationToken = generateTwoFactorSetupFinalizationToken(+ userId,+ result.finalizationNonce,+ process.env.JWT_SECRET!,+ );+ return res.status(200).json({ finalizationToken });+ } catch (err) {+ logger.error('[acknowledge2FASetup]', err);+ return res.status(500).json({ message: 'Something went wrong' });+ }+ };++ const finalize2FASetup = async (req: SetupRequest, res: Response): Promise<Response> => {+ try {+ const userId = req.user?.id;+ if (!userId) {+ return res+ .status(401)+ .json({ message: 'Invalid or expired two-factor finalization token' });+ }++ const result = await finalizeTwoFactorSetup(userId, req.twoFactorEnrollmentNonce, deps);+ if (!result.ok) {+ return res.status(result.status).json({ message: result.message });+ }++ const userData = sanitizeUser(result.user);+ await deps.deleteAllUserSessions({ userId: result.user._id.toString() });+ const authToken = await deps.setAuthTokens(result.user._id, res, null, req);+ const retirement = await recheckMintedCredential(+ () => deps.getUserById(userId, TOKEN_RETIREMENT_FIELDS),+ () => revokeMintedSession(res, result.user, userId),+ );+ if (+ isEnrollmentSupersededByRecovery(+ result.user.twoFactorEnrolledAt,+ retirement?.credentialsChangedAt,+ )+ ) {+ await revokeMintedSession(res, result.user, userId);+ return res+ .status(401)+ .json({ message: 'Password was reset during setup, please sign in again' });+ }++ return res.status(200).json({ token: authToken, user: userData });+ } catch (err) {+ logger.error('[finalize2FASetup]', err);+ return res.status(500).json({ message: 'Something went wrong' });+ }+ };++ return {+ verify2FAWithTempToken,+ confirm2FASetupWithTempToken,+ acknowledge2FASetup,+ finalize2FASetup,+ };+}diff --git a/packages/api/src/auth/gates.spec.ts b/packages/api/src/auth/gates.spec.tsnew file mode 100644index 0000000000..ecc31a8247--- /dev/null+++ b/packages/api/src/auth/gates.spec.ts@@ -0,0 +1,61 @@+import { getTenantId, SYSTEM_TENANT_ID } from '@librechat/data-schemas';+import type { NextFunction, Request, Response } from 'express';+import { createRequiredTwoFactorGate } from './gates';++function createResponse(): { res: Response; status: jest.Mock; json: jest.Mock } {+ const status = jest.fn();+ const json = jest.fn();+ const res = { status, json } as unknown as Response;+ status.mockReturnValue(res);+ return { res, status, json };+}++describe('required two-factor gate', () => {+ const original = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ });+ afterEach(() => {+ if (original === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = original;+ }+ });++ /**+ * The gate runs before tenant middleware, so under strict tenant isolation an unscoped user read+ * throws and the hand-off becomes a 500.+ */+ it('reads the retirement cutoff in system scope and hands off to setup', async () => {+ let readScope: string | undefined;+ const gate = createRequiredTwoFactorGate({+ clearCloudFrontCookies: jest.fn(),+ warn: jest.fn(),+ generateSetupToken: () => 'setup-token',+ getUserById: jest.fn(async () => {+ readScope = getTenantId();+ return {};+ }),+ });+ const { res, status, json } = createResponse();+ const req = {+ path: '/api/convos',+ headers: {},+ user: { id: 'user-1', provider: 'local' },+ } as unknown as Request;+ const onAllowed = jest.fn();+ const next = jest.fn() as NextFunction;++ gate(req, res, next, onAllowed);+ await new Promise((resolve) => setImmediate(resolve));++ expect(readScope).toBe(SYSTEM_TENANT_ID);+ expect(status).toHaveBeenCalledWith(403);+ expect(json).toHaveBeenCalledWith(+ expect.objectContaining({ twoFASetupRequired: true, tempToken: 'setup-token' }),+ );+ expect(onAllowed).not.toHaveBeenCalled();+ expect(next).not.toHaveBeenCalled();+ });+});diff --git a/packages/api/src/auth/gates.ts b/packages/api/src/auth/gates.tsnew file mode 100644index 0000000000..e701fc0fb5--- /dev/null+++ b/packages/api/src/auth/gates.ts@@ -0,0 +1,154 @@+import jwt from 'jsonwebtoken';+import { runAsSystem } from '@librechat/data-schemas';+import { TWO_FACTOR_ENROLLMENT_REQUIRED_CODE } from 'librechat-data-provider';+import type { NextFunction, Request, Response } from 'express';+import type { TokenIssuance, TokenRetirementSignals, TwoFactorAccount } from './twoFactor';+import type { CloudFrontCookieScope } from '~/cdn/cloudfront-cookies';+import {+ generateTwoFactorSetupToken,+ isTokenRetired,+ isTwoFactorEnrollmentRequired,+ TOKEN_RETIREMENT_FIELDS,+} from './twoFactor';++type AuthUser = Pick<+ TwoFactorAccount,+ '_id' | 'id' | 'provider' | 'tenantId' | 'orgId' | 'storageRegion' | 'twoFactorEnabled'+>;++type AuthRequest = Request & { user?: AuthUser; authStrategy?: string };++export interface TwoFactorGateDependencies {+ clearCloudFrontCookies: (res: Response, scope: CloudFrontCookieScope) => void;+ getUserById: (userId: string, projection: string) => Promise<TokenRetirementSignals | null>;+ warn: (message: string) => void;+ generateSetupToken?: typeof generateTwoFactorSetupToken;+ enrollmentRequired?: typeof isTwoFactorEnrollmentRequired;+ tokenRetired?: typeof isTokenRetired;+}++export function clearEnrollmentViewer(+ req: AuthRequest,+ res: Response,+ user: AuthUser | null | undefined,+ deps: Pick<TwoFactorGateDependencies, 'clearCloudFrontCookies' | 'enrollmentRequired'>,+): boolean {+ if (!(deps.enrollmentRequired ?? isTwoFactorEnrollmentRequired)(user)) {+ return false;+ }+ deps.clearCloudFrontCookies(res, {+ userId: user?.id?.toString() ?? user?._id?.toString(),+ tenantId: user?.tenantId ?? user?.orgId,+ storageRegion: user?.storageRegion,+ });+ delete req.user;+ delete req.authStrategy;+ return true;+}++const normalizeRouteSegment = (value: string): string =>+ typeof value === 'string' ? value.toLowerCase().replace(/\/+$/, '') : '';++function isPolicyAllowlisted(req: Request): boolean {+ return (+ req.method === 'POST' &&+ normalizeRouteSegment(req.baseUrl) === '/api/auth' &&+ normalizeRouteSegment(req.path) === '/logout'+ );+}++function getAuthorizingCredential(req: Request): TokenIssuance {+ const authorization = req.headers.authorization;+ const value = Array.isArray(authorization) ? authorization[0] : authorization;+ const token = typeof value === 'string' ? value.replace(/^Bearer\s+/i, '') : '';+ const decoded = token ? jwt.decode(token) : null;+ const payload = decoded && typeof decoded === 'object' ? decoded : null;+ return {+ issuedAt: typeof payload?.iat === 'number' ? payload.iat : undefined,+ issuedAtMs: typeof payload?.issuedAtMs === 'number' ? payload.issuedAtMs : undefined,+ };+}++/** The cutoff read is deliberately after minting the setup token. */+export function createRequiredTwoFactorGate(deps: TwoFactorGateDependencies) {+ return (req: AuthRequest, res: Response, next: NextFunction, onAllowed: () => void): void => {+ if (+ !(deps.enrollmentRequired ?? isTwoFactorEnrollmentRequired)(req.user) ||+ isPolicyAllowlisted(req)+ ) {+ onAllowed();+ return;+ }++ void (async () => {+ const user = req.user;+ const userId = (user?.id?.toString() ?? user?._id?.toString()) as string;+ deps.clearCloudFrontCookies(res, {+ userId,+ tenantId: user?.tenantId ?? user?.orgId,+ storageRegion: user?.storageRegion,+ });+ const tempToken = (deps.generateSetupToken ?? generateTwoFactorSetupToken)(+ userId,+ process.env.JWT_SECRET as string,+ );+ /** Tenant context is established only after this gate, as the JWT strategy's own read is. */+ const retirement = await runAsSystem(() => deps.getUserById(userId, TOKEN_RETIREMENT_FIELDS));+ if ((deps.tokenRetired ?? isTokenRetired)(getAuthorizingCredential(req), retirement)) {+ deps.warn(+ `[requireJwtAuth] Password was reset while the request was in flight: userId=${userId}`,+ );+ res.status(401).json({ message: 'Unauthorized' });+ return;+ }+ res.status(403).json({+ code: TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken,+ });+ })().catch(next);+ };+}++export function continueAfterOptionalAuth(+ req: AuthRequest,+ res: Response,+ next: NextFunction,+ user: AuthUser,+ strategy: string,+ tenantContextMiddleware: (req: Request, res: Response, next: NextFunction) => void,+ deps: Pick<TwoFactorGateDependencies, 'clearCloudFrontCookies' | 'enrollmentRequired'>,+): void {+ if (clearEnrollmentViewer(req, res, user, deps)) {+ next();+ return;+ }+ req.user = user;+ req.authStrategy = strategy;+ tenantContextMiddleware(req, res, next);+}++/** Keeps the strategy callback and its accepted-user path in the caller. */+export function continueAfterBearerRetirement(+ user: TokenRetirementSignals,+ issuance: TokenIssuance,+ kind: 'jwt' | 'openidJwt',+ subject: string | undefined,+ done: (error: null, user: false, info?: { message: string }) => void,+ warn: (message: string) => void,+ onAllowed: () => Promise<void> | void,+ tokenRetired: typeof isTokenRetired = isTokenRetired,+): Promise<void> | void {+ if (tokenRetired(issuance, user)) {+ const label = kind === 'jwt' ? 'jwtLogin] JwtStrategy' : 'openIdJwtLogin] openId JwtStrategy';+ warn(`[${label} => token predates enrollment or password reset: ${subject}`);+ done(+ null,+ false,+ kind === 'openidJwt' ? { message: 'Token predates enrollment or password reset' } : undefined,+ );+ return;+ }+ return onAllowed();+}diff --git a/packages/api/src/auth/index.ts b/packages/api/src/auth/index.tsindex eaf2f21b94..97ec41de69 100644--- a/packages/api/src/auth/index.ts+++ b/packages/api/src/auth/index.ts@@ -20,3 +20,14 @@ export * from './emailChangeStore';export * from './passwordReset';export * from './reuse';export * from './openid/index';+export * from './twoFactor';+export * from './user';+export * from './localRefresh';+export * from './openid/reuseCredential';+export * from './passwordResetUpdate';+export * from './login';+export * from './enrollment';+export * from './gates';+export * from './share';+export * from './limiter';+export * from './tempuser';diff --git a/packages/api/src/auth/limiter.ts b/packages/api/src/auth/limiter.tsnew file mode 100644index 0000000000..16e8c2e70e--- /dev/null+++ b/packages/api/src/auth/limiter.ts@@ -0,0 +1,157 @@+import jwt from 'jsonwebtoken';+import { createHash } from 'node:crypto';+import { rateLimit } from 'express-rate-limit';+import { ViolationTypes } from 'librechat-data-provider';+import type { NextFunction, Request, Response } from 'express';+import type { Store } from 'express-rate-limit';+import type { TwoFactorTempRequest } from './tempuser';++type ViolationMessage = {+ type: ViolationTypes;+ max: string | number;+ limiter: string;+ windowInMinutes: number;+};++export interface TwoFactorLimiterDependencies {+ env: NodeJS.ProcessEnv;+ limiterCache: (prefix: string) => Store | undefined;+ removePorts: (req: Request) => string | undefined;+ logViolation: (+ req: Request,+ res: Response,+ type: ViolationTypes,+ message: ViolationMessage,+ score: string | number | undefined,+ ) => Promise<void>;+}++interface TwoFactorLimiterPolicy {+ namespace: string;+ windowMinutes: string | number;+ max: string | number;+ score: string | number | undefined;+ describeAttempts: string;+}++export function createTwoFactorLimiter(+ deps: TwoFactorLimiterDependencies,+ policy: TwoFactorLimiterPolicy,+) {+ const { namespace, max, score, describeAttempts } = policy;+ const windowMs = Number(policy.windowMinutes) * 60 * 1000;+ const windowInMinutes = windowMs / 60000;+ const message = `Too many ${describeAttempts}, please try again after ${windowInMinutes} minutes.`;++ const getEnrollmentToken = (req: TwoFactorTempRequest): string | undefined =>+ req.body?.[req.twoFactorTokenField ?? 'tempToken'];++ const getUserLimiterKey = (req: Request): string => {+ const tempReq = req as TwoFactorTempRequest;+ const userId = tempReq.user?.id ?? tempReq.user?._id;+ if (userId) {+ return `user:${userId.toString()}`;+ }+ const token = getEnrollmentToken(tempReq);+ if (typeof token === 'string' && token) {+ return `temp:${createHash('sha256').update(token).digest('hex')}`;+ }+ const ip = deps.removePorts(req);+ return ip ? `ip:${ip}` : 'ip:unknown';+ };++ const getTempTokenUserId = (token: string | undefined): string | null => {+ if (!token) {+ return null;+ }+ try {+ const payload = jwt.verify(token, deps.env.JWT_SECRET ?? '');+ return typeof payload === 'object' && typeof payload.userId === 'string'+ ? payload.userId+ : null;+ } catch {+ return null;+ }+ };++ const createHandler =+ (limiter: string) =>+ async (req: Request, res: Response): Promise<Response> => {+ const type = ViolationTypes.LOGINS;+ const errorMessage = { type, max, limiter, windowInMinutes };+ const tempReq = req as TwoFactorTempRequest;+ const userId = getTempTokenUserId(getEnrollmentToken(tempReq));+ if (userId && !tempReq.user) {+ tempReq.user = { id: userId };+ } else if (userId && tempReq.user && !tempReq.user.id && !tempReq.user._id) {+ tempReq.user.id = userId;+ }+ await deps.logViolation(req, res, type, errorMessage, score);+ return res.status(429).json({ message });+ };++ const ipLimiter = rateLimit({+ windowMs,+ max: Number(max),+ skip: (req) =>+ namespace === 'two_factor_setup' &&+ Boolean((req as TwoFactorTempRequest).user?.id ?? (req as TwoFactorTempRequest).user?._id),+ handler: createHandler('ip'),+ keyGenerator: deps.removePorts as (req: Request) => string,+ store: deps.limiterCache(`${namespace}_limiter`),+ });+ const userLimiter = rateLimit({+ windowMs,+ max: Number(max),+ handler: createHandler('user'),+ keyGenerator: getUserLimiterKey,+ store: deps.limiterCache(`${namespace}_user_limiter`),+ });++ return (req: Request, res: Response, next: NextFunction): void => {+ ipLimiter(req, res, (error) => {+ if (error) {+ next(error);+ return;+ }+ userLimiter(req, res, next);+ });+ };+}++export function createTwoFactorLimiters(deps: TwoFactorLimiterDependencies): {+ twoFactorTempLimiter: (req: Request, res: Response, next: NextFunction) => void;+ twoFactorSetupLimiter: (req: Request, res: Response, next: NextFunction) => void;+} {+ const {+ LOGIN_WINDOW = 5,+ LOGIN_MAX = 7,+ LOGIN_VIOLATION_SCORE,+ TWO_FACTOR_TEMP_WINDOW = LOGIN_WINDOW,+ TWO_FACTOR_TEMP_MAX = LOGIN_MAX,+ TWO_FACTOR_TEMP_VIOLATION_SCORE,+ TWO_FACTOR_SETUP_WINDOW = TWO_FACTOR_TEMP_WINDOW,+ TWO_FACTOR_SETUP_MAX = 20,+ TWO_FACTOR_SETUP_VIOLATION_SCORE,+ } = deps.env;++ return {+ twoFactorTempLimiter: createTwoFactorLimiter(deps, {+ namespace: 'two_factor_temp',+ windowMinutes: TWO_FACTOR_TEMP_WINDOW,+ max: TWO_FACTOR_TEMP_MAX,+ score: TWO_FACTOR_TEMP_VIOLATION_SCORE ?? LOGIN_VIOLATION_SCORE,+ describeAttempts: 'verification attempts',+ }),+ twoFactorSetupLimiter: createTwoFactorLimiter(deps, {+ namespace: 'two_factor_setup',+ windowMinutes: TWO_FACTOR_SETUP_WINDOW,+ max: TWO_FACTOR_SETUP_MAX,+ score:+ TWO_FACTOR_SETUP_VIOLATION_SCORE ??+ TWO_FACTOR_TEMP_VIOLATION_SCORE ??+ LOGIN_VIOLATION_SCORE,+ describeAttempts: 'two-factor setup requests',+ }),+ };+}diff --git a/packages/api/src/auth/localRefresh.ts b/packages/api/src/auth/localRefresh.tsnew file mode 100644index 0000000000..6156e65e0f--- /dev/null+++ b/packages/api/src/auth/localRefresh.ts@@ -0,0 +1,197 @@+import jwt from 'jsonwebtoken';+import { TWO_FACTOR_ENROLLMENT_REQUIRED_CODE } from 'librechat-data-provider';+import type { ISession, OIDCTokens } from '@librechat/data-schemas';+import type { Request, Response } from 'express';+import type { TokenIssuance, TwoFactorAccount } from './twoFactor';+import {+ generateTwoFactorSetupToken,+ isTokenRetired,+ recheckMintedCredential,+ withdrawMintedSession,+ isTwoFactorEnrollmentRequired,+ TOKEN_RETIREMENT_FIELDS,+} from './twoFactor';++const EXPIRED_REFRESH_MESSAGE = 'Refresh token expired or not found for this user';++type UserIdentifier = string | { toString(): string };++type RefreshUser = Pick<+ TwoFactorAccount,+ | '_id'+ | 'provider'+ | 'tenantId'+ | 'orgId'+ | 'storageRegion'+ | 'twoFactorEnabled'+ | 'twoFactorEnrolledAt'+ | 'credentialsChangedAt'+>;++type RefreshSession = Pick<ISession, 'expiration'> & { _id: UserIdentifier };+type SessionDeletionResult = { deletedCount?: number };+type AuthResponseSource = TwoFactorAccount & { __v?: number; federatedTokens?: OIDCTokens };++interface LocalRefreshDependencies {+ userProjection: string;+ getUserById: (userId: string, projection: string) => Promise<RefreshUser | null>;+ findSession: (+ query: { userId: string; refreshToken: string },+ options: { lean: false },+ ) => Promise<RefreshSession | null>;+ setAuthTokens: (+ userId: string,+ res: Response,+ session: RefreshSession | null,+ req: Request,+ ) => Promise<string>;+ deleteSession: (query: { sessionId: string }) => Promise<SessionDeletionResult>;+ deleteAllUserSessions: (query: { userId: string }) => Promise<SessionDeletionResult>;+ clearCloudFrontCookies: (+ res: Response,+ scope: { userId: string; tenantId?: string; storageRegion?: string },+ ) => void;+ generateTwoFactorSetupToken?: typeof generateTwoFactorSetupToken;+ isTwoFactorEnrollmentRequired?: typeof isTwoFactorEnrollmentRequired;+ warn: (message: string) => void;+ error: (message: string, cause: unknown) => void;+}++/**+ * Preserve the refresh response contract. The shared allowlist excludes `openidId`, which existing+ * OpenID refresh clients receive and the controller tests assert, so switching sanitizers here+ * would silently change the response shape.+ */+export function sanitizeUserForAuthResponse<T extends object>(+ user: T | null | undefined,+): Partial<T> {+ const hydrated = user as (T & { toObject?: () => AuthResponseSource }) | null | undefined;+ const source = (typeof hydrated?.toObject === 'function' ? hydrated.toObject() : hydrated) ?? {};+ const {+ password: _password,+ __v: _version,+ totpSecret: _totpSecret,+ backupCodes: _backupCodes,+ pendingTotpSecret: _pendingTotpSecret,+ pendingBackupCodes: _pendingBackupCodes,+ twoFactorAcknowledgementNonceHash: _acknowledgementHash,+ twoFactorFinalizationNonceHash: _finalizationHash,+ federatedTokens: _federatedTokens,+ ...safeUser+ } = source as AuthResponseSource;+ return safeUser as Partial<T>;+}++/** Handles only the local refresh branch after OpenID ownership has been resolved. */+export function createLocalRefreshHandler(deps: LocalRefreshDependencies) {+ const requiresEnrollment = deps.isTwoFactorEnrollmentRequired ?? isTwoFactorEnrollmentRequired;+ const mintSetupToken = deps.generateTwoFactorSetupToken ?? generateTwoFactorSetupToken;++ /**+ * The session lookup resolves before the response credential is minted. Recovery may land in+ * between, deleting the old session while the newly minted token postdates credentialsChangedAt.+ * Read the cutoff after minting so that race withdraws the resurrected session.+ */+ const isCredentialRetired = async (userId: string, credential: TokenIssuance) => {+ const current = await deps.getUserById(userId, TOKEN_RETIREMENT_FIELDS);+ return isTokenRetired(credential, current);+ };++ const revokeSession = (res: Response, user: RefreshUser, userId: string) =>+ withdrawMintedSession(res, user, userId, deps);++ const withdrawSession = async (res: Response, user: RefreshUser, userId: string) => {+ deps.warn(+ `[refreshController] Password was reset while the refresh was in flight: userId=${userId}`,+ );+ await revokeSession(res, user, userId);+ return res.status(401).send(EXPIRED_REFRESH_MESSAGE);+ };++ return async (+ req: Request,+ res: Response,+ refreshToken: string | undefined,+ ): Promise<Response | void> => {+ if (!refreshToken) {+ return res.status(200).send('Refresh token not provided');+ }++ try {+ const payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET ?? '');+ if (typeof payload === 'string' || typeof payload.id !== 'string') {+ throw new Error('Invalid refresh token payload');+ }+ const userId = payload.id;+ const user = await deps.getUserById(userId, deps.userProjection);+ if (!user) {+ return res.status(401).redirect('/login');+ }++ const credential: TokenIssuance = {+ issuedAt: payload.iat,+ issuedAtMs: typeof payload.issuedAtMs === 'number' ? payload.issuedAtMs : undefined,+ };+ /**+ * Enrollment stamps its cutoff before session revocation. Dating the incoming credential+ * closes that gap even if revocation fails, and also covers password recovery.+ */+ if (isTokenRetired(credential, user)) {+ deps.warn(+ `[refreshController] Refresh token predates enrollment or password reset: userId=${userId}`,+ );+ res.clearCookie('refreshToken');+ return res.status(401).send(EXPIRED_REFRESH_MESSAGE);+ }++ if (process.env.NODE_ENV === 'CI') {+ const token = await deps.setAuthTokens(userId, res, null, req);+ return res.status(200).send({ token, user: sanitizeUserForAuthResponse(user) });+ }++ const session = await deps.findSession({ userId, refreshToken }, { lean: false });+ if (session && session.expiration > new Date()) {+ if (requiresEnrollment(user)) {+ await deps.deleteSession({ sessionId: session._id.toString() });+ res.clearCookie('refreshToken');+ deps.clearCloudFrontCookies(res, {+ userId,+ tenantId: user.tenantId ?? user.orgId,+ storageRegion: user.storageRegion,+ });+ /** The setup token outranks the refresh credential that bought it. */+ const tempToken = mintSetupToken(userId, process.env.JWT_SECRET ?? '');+ if (await isCredentialRetired(userId, credential)) {+ return withdrawSession(res, user, userId);+ }+ return res.status(200).send({+ code: TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken,+ });+ }++ const token = await deps.setAuthTokens(userId, res, session, req);+ const retired = await recheckMintedCredential(+ () => isCredentialRetired(userId, credential),+ () => revokeSession(res, user, userId),+ );+ if (retired) {+ return withdrawSession(res, user, userId);+ }+ return res.status(200).send({ token, user: sanitizeUserForAuthResponse(user) });+ }+ if (req.query?.retry) {+ return res.status(403).send('No session found');+ }+ if (typeof payload.exp === 'number' && payload.exp < Date.now() / 1000) {+ return res.status(403).redirect('/login');+ }+ return res.status(401).send(EXPIRED_REFRESH_MESSAGE);+ } catch (error) {+ deps.error('[refreshController] Invalid refresh token:', error);+ return res.status(403).send('Invalid refresh token');+ }+ };+}diff --git a/packages/api/src/auth/login.ts b/packages/api/src/auth/login.tsnew file mode 100644index 0000000000..bc5d70bead--- /dev/null+++ b/packages/api/src/auth/login.ts@@ -0,0 +1,117 @@+import { logger } from '@librechat/data-schemas';+import {+ TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+ TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE,+} from 'librechat-data-provider';+import type { Request, Response } from 'express';+import type { StoredTwoFactorAccount } from './twoFactor';+import type { UserDocumentId } from '~/auth/verification';+import {+ TOKEN_RETIREMENT_FIELDS,+ recheckMintedCredential,+ withdrawMintedSession,+ generateTwoFactorSetupToken,+ hasPasswordResetSince,+ isCredentialLoginBlockedByTwoFactorPolicy,+ isTwoFactorEnrollmentRequired,+} from './twoFactor';+import { clearCloudFrontCookies } from '~/cdn';++type LoginUser = StoredTwoFactorAccount & { __v?: number };+type LoginRequest = Request & { user?: LoginUser };++export interface LoginDependencies {+ getUserById: (userId: string, projection: string) => Promise<StoredTwoFactorAccount | null>;+ deleteAllUserSessions: (input: { userId: string }) => Promise<object>;+ clearCloudFrontCookies: typeof clearCloudFrontCookies;+ generate2FATempToken: (userId: UserDocumentId) => string;+ setAuthTokens: (+ userId: UserDocumentId,+ res: Response,+ unused: null,+ req: Request,+ ) => Promise<string>;+}++export function createLoginController(deps: LoginDependencies) {+ const wasPasswordRevokedDuringLogin = async (user: LoginUser): Promise<boolean> => {+ const current = await deps.getUserById(user._id.toString(), TOKEN_RETIREMENT_FIELDS);+ return hasPasswordResetSince(user.credentialsChangedAt, current?.credentialsChangedAt);+ };++ const refuseRevokedLogin = (res: Response, user: LoginUser): Response => {+ logger.warn(+ `[loginController] Refused a login whose password was reset while it was in flight [userId: ${user._id}]`,+ );+ return res.status(401).json({ message: 'Invalid credentials' });+ };++ const withdrawLoginSession = (res: Response, user: LoginUser): Promise<void> =>+ withdrawMintedSession(res, user, user._id.toString(), deps);++ return async (req: LoginRequest, res: Response): Promise<Response> => {+ try {+ if (!req.user) {+ return res.status(400).json({ message: 'Invalid credentials' });+ }++ if (isCredentialLoginBlockedByTwoFactorPolicy(req.user)) {+ logger.warn(+ `[loginController] Refused a password login for a federated record under required 2FA [provider: ${req.user.provider}] [Request-IP: ${req.ip}]`,+ );+ return res.status(403).json({+ code: TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE,+ message: 'Sign in with your identity provider to continue.',+ });+ }++ if (req.user.twoFactorEnabled) {+ const tempToken = deps.generate2FATempToken(req.user._id);+ if (await wasPasswordRevokedDuringLogin(req.user)) {+ return refuseRevokedLogin(res, req.user);+ }+ return res.status(200).json({ twoFAPending: true, tempToken });+ }++ if (isTwoFactorEnrollmentRequired(req.user)) {+ deps.clearCloudFrontCookies(res, {+ userId: req.user._id.toString(),+ tenantId: req.user.tenantId ?? req.user.orgId,+ storageRegion: req.user.storageRegion,+ });+ const tempToken = generateTwoFactorSetupToken(+ req.user._id.toString(),+ process.env.JWT_SECRET!,+ );+ if (await wasPasswordRevokedDuringLogin(req.user)) {+ return refuseRevokedLogin(res, req.user);+ }+ return res.status(200).json({+ code: TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken,+ });+ }++ const { password: _p, totpSecret: _t, __v, ...user } = req.user;+ user.id = user._id.toString();++ const loginUser = req.user;+ const token = await deps.setAuthTokens(loginUser._id, res, null, req);+ const revoked = await recheckMintedCredential(+ () => wasPasswordRevokedDuringLogin(loginUser),+ () => withdrawLoginSession(res, loginUser),+ );+ if (revoked) {+ await withdrawLoginSession(res, loginUser);+ return refuseRevokedLogin(res, loginUser);+ }++ return res.status(200).send({ token, user });+ } catch (err) {+ logger.error('[loginController]', err);+ return res.status(500).json({ message: 'Something went wrong' });+ }+ };+}diff --git a/packages/api/src/auth/openid/reuseCredential.ts b/packages/api/src/auth/openid/reuseCredential.tsnew file mode 100644index 0000000000..5a48eddc5e--- /dev/null+++ b/packages/api/src/auth/openid/reuseCredential.ts@@ -0,0 +1,41 @@+import jwt from 'jsonwebtoken';+import { createHash } from 'node:crypto';+import type { TokenIssuance } from '../twoFactor';++export interface OpenIDReuseCredential extends TokenIssuance {+ userId: string;+}++/** Verify the identity cookie and, when supplied, bind it to the source refresh token. */+export function getValidOpenIDReuseCredential(+ parsedCookies: { openid_user_id?: string },+ jwtRefreshSecret: string | undefined,+ refreshToken?: string,+): OpenIDReuseCredential | null {+ if (!parsedCookies.openid_user_id || !jwtRefreshSecret) {+ return null;+ }++ try {+ const payload = jwt.verify(parsedCookies.openid_user_id, jwtRefreshSecret);+ if (typeof payload === 'string' || typeof payload.id !== 'string') {+ return null;+ }+ if (refreshToken != null) {+ if (typeof payload.refreshTokenHash !== 'string') {+ return null;+ }+ const hash = createHash('sha256').update(refreshToken).digest('base64url');+ if (payload.refreshTokenHash !== hash) {+ return null;+ }+ }+ return {+ userId: payload.id,+ issuedAt: payload.iat,+ issuedAtMs: typeof payload.issuedAtMs === 'number' ? payload.issuedAtMs : undefined,+ };+ } catch {+ return null;+ }+}diff --git a/packages/api/src/auth/passwordReset.spec.ts b/packages/api/src/auth/passwordReset.spec.tsindex 311f56dc34..dcc1f225ab 100644--- a/packages/api/src/auth/passwordReset.spec.ts+++ b/packages/api/src/auth/passwordReset.spec.ts@@ -77,7 +77,14 @@ describe('commitPasswordReset', () => {await expect(commitPasswordReset(deps, input)).resolves.toMatchObject({ ok: true });expect(deps.updateUser).toHaveBeenCalledWith('user-reset',- { password: 'hashed-password', credentialsChangedAt: expect.any(Date) },+ {+ password: 'hashed-password',+ credentialsChangedAt: expect.any(Date),+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ },{ email: '[email protected]' },);});diff --git a/packages/api/src/auth/passwordReset.ts b/packages/api/src/auth/passwordReset.tsindex 50fc044b99..b6d5efa735 100644--- a/packages/api/src/auth/passwordReset.ts+++ b/packages/api/src/auth/passwordReset.ts@@ -1,5 +1,7 @@import { logger } from '@librechat/data-schemas';import type { Request, Response } from 'express';+import type { PasswordResetUpdate } from './passwordResetUpdate';+import { createPasswordResetUpdate } from './passwordResetUpdate';import { EMAIL_CHANGE_TOKEN_TYPE } from './email';/** The stored reset token, in both the typed shape and the untyped legacy one. */@@ -23,7 +25,7 @@ export interface PasswordResetDeps {getUserById: (userId: string, select: string) => Promise<PasswordResetUser | null>;updateUser: (userId: string,- update: { password: string; credentialsChangedAt: Date },+ update: PasswordResetUpdate,expectedState: { email: string },) => Promise<PasswordResetUser | null>;deleteTokens: (query: { userId: string; type: string }) => Promise<unknown>;@@ -158,8 +160,7 @@ export async function commitPasswordReset(const user = await deps.updateUser(input.userId,- /** Stamped with the new password so access tokens issued before the reset stop verifying */- { password: deps.hashPassword(input.password), credentialsChangedAt: new Date() },+ createPasswordResetUpdate(deps.hashPassword(input.password)),{ email: account.email },);if (!user) {diff --git a/packages/api/src/auth/passwordResetUpdate.ts b/packages/api/src/auth/passwordResetUpdate.tsnew file mode 100644index 0000000000..1944ec739c--- /dev/null+++ b/packages/api/src/auth/passwordResetUpdate.ts@@ -0,0 +1,27 @@+import type { TwoFactorEnrollmentUpdate } from '@librechat/data-schemas';++export type PasswordResetUpdate = { password?: string; credentialsChangedAt?: Date | null } & Pick<+ TwoFactorEnrollmentUpdate,+ | 'pendingTotpSecret'+ | 'pendingBackupCodes'+ | 'twoFactorAcknowledgementNonceHash'+ | 'twoFactorFinalizationNonceHash'+>;++/**+ * Retire bearer credentials from the replaced password. Clearing the staged enrollment in this+ * same write prevents an old setup credential from promoting its secret after recovery.+ */+export function createPasswordResetUpdate(+ passwordHash: string,+ resetAt: Date = new Date(),+): PasswordResetUpdate {+ return {+ password: passwordHash,+ credentialsChangedAt: resetAt,+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ };+}diff --git a/packages/api/src/auth/share.ts b/packages/api/src/auth/share.tsnew file mode 100644index 0000000000..49bfd3fa98--- /dev/null+++ b/packages/api/src/auth/share.ts@@ -0,0 +1,146 @@+import jwt from 'jsonwebtoken';+import { SystemRoles } from 'librechat-data-provider';+import type { NextFunction, Request, Response } from 'express';+import type { StoredTwoFactorAccount, TokenIssuance } from './twoFactor';+import type { CloudFrontCookieScope } from '~/cdn/cloudfront-cookies';+import { isTokenRetired, isTwoFactorEnrollmentRequired } from './twoFactor';+import { clearEnrollmentViewer } from './gates';+import { isEnabled } from '~/utils';++type ShareUser = Pick<+ StoredTwoFactorAccount,+ | '_id'+ | 'id'+ | 'provider'+ | 'role'+ | 'tenantId'+ | 'orgId'+ | 'storageRegion'+ | 'twoFactorEnabled'+ | 'twoFactorEnrolledAt'+ | 'credentialsChangedAt'+>;+type ShareRequest = Request & {+ user?: ShareUser;+ authStrategy?: string;+ session?: { openidTokens?: { refreshToken?: string } };+};+type VerifiedUser = TokenIssuance & { userId: string };++export interface ShareFileAuthDependencies {+ parseCookie: (header: string) => Record<string, string>;+ getUserById: (userId: string, projection: string) => Promise<ShareUser | null>;+ findSession: (filter: { userId: string; refreshToken: string }) => Promise<object | null>;+ runAsSystem: <T>(fn: () => Promise<T>) => Promise<T>;+ clearCloudFrontCookies: (res: Response, scope: CloudFrontCookieScope) => void;+ warn: (message: string, detail?: string) => void;+ enrollmentRequired?: typeof isTwoFactorEnrollmentRequired;+ tokenRetired?: typeof isTokenRetired;+ enabled?: typeof isEnabled;+}++export function createOptionalShareFileAuth(deps: ShareFileAuthDependencies) {+ const verifySignedUser = (token: string | undefined): VerifiedUser | null => {+ try {+ const payload = jwt.verify(token ?? '', process.env.JWT_REFRESH_SECRET ?? '');+ if (typeof payload !== 'object' || typeof payload.id !== 'string') {+ return null;+ }+ return {+ userId: payload.id,+ issuedAt: typeof payload.iat === 'number' ? payload.iat : undefined,+ issuedAtMs: typeof payload.issuedAtMs === 'number' ? payload.issuedAtMs : undefined,+ };+ } catch {+ return null;+ }+ };++ const getRefreshTokenUser = async (token: string): Promise<VerifiedUser | null> => {+ const verified = verifySignedUser(token);+ if (!verified) {+ return null;+ }+ const session = await deps.runAsSystem(() =>+ deps.findSession({ userId: verified.userId, refreshToken: token }),+ );+ return session ? verified : null;+ };++ const getOpenIdUser = (+ parsed: Record<string, string>,+ req: ShareRequest,+ ): VerifiedUser | null => {+ if (+ parsed.token_provider !== 'openid' ||+ !(deps.enabled ?? isEnabled)(process.env.OPENID_REUSE_TOKENS)+ ) {+ return null;+ }+ const sessionRefreshToken = req.session?.openidTokens?.refreshToken;+ if (!parsed.refreshToken || parsed.refreshToken !== sessionRefreshToken) {+ return null;+ }+ return verifySignedUser(parsed.openid_user_id);+ };++ const clearCookies = (res: Response, user: ShareUser): void => {+ deps.clearCloudFrontCookies(res, {+ userId: user.id?.toString() ?? user._id?.toString(),+ tenantId: user.tenantId ?? user.orgId,+ storageRegion: user.storageRegion,+ });+ };++ return async (req: ShareRequest, res: Response, next: NextFunction): Promise<void> => {+ if (req.user) {+ clearEnrollmentViewer(req, res, req.user, deps);+ next();+ return;+ }++ try {+ const cookieHeader = req.headers.cookie;+ if (!cookieHeader) {+ next();+ return;+ }+ const parsed = deps.parseCookie(cookieHeader);+ const verified =+ getOpenIdUser(parsed, req) ||+ (parsed.refreshToken ? await getRefreshTokenUser(parsed.refreshToken) : null);+ if (!verified) {+ next();+ return;+ }++ // This read precedes the share tenant, so it must use system context.+ const user = await deps.runAsSystem(() =>+ deps.getUserById(verified.userId, '-password -__v -totpSecret -backupCodes'),+ );+ if (!user) {+ next();+ return;+ }+ if (+ (deps.enrollmentRequired ?? isTwoFactorEnrollmentRequired)(user) ||+ (deps.tokenRetired ?? isTokenRetired)(verified, user)+ ) {+ clearCookies(res, user);+ next();+ return;+ }+ user.id = user._id.toString();+ if (!user.role) {+ user.role = SystemRoles.USER;+ }+ req.user = user;+ } catch (error) {+ deps.warn(+ '[optionalShareFileAuth] cookie auth failed:',+ error instanceof Error ? error.message : undefined,+ );+ }+ next();+ };+}diff --git a/packages/api/src/auth/tempuser.ts b/packages/api/src/auth/tempuser.tsnew file mode 100644index 0000000000..5a1c271293--- /dev/null+++ b/packages/api/src/auth/tempuser.ts@@ -0,0 +1,33 @@+import jwt from 'jsonwebtoken';+import type { NextFunction, Request, Response } from 'express';++type TempTokenField = 'tempToken' | 'acknowledgementToken' | 'finalizationToken';+export type TwoFactorTempRequest = Request & {+ user?: { id?: string; _id?: { toString(): string } };+ twoFactorTokenField?: TempTokenField;+ body: Partial<Record<TempTokenField, string>>;+};++export function createTwoFactorTempUser(field: TempTokenField, env: NodeJS.ProcessEnv) {+ return (req: TwoFactorTempRequest, _res: Response, next: NextFunction): void => {+ req.twoFactorTokenField = field;+ if (req.user?.id || req.user?._id) {+ next();+ return;+ }+ const token = req.body?.[field];+ if (!token) {+ next();+ return;+ }+ try {+ const payload = jwt.verify(token, env.JWT_SECRET ?? '');+ if (typeof payload === 'object' && payload.userId) {+ req.user = { id: payload.userId };+ }+ } catch {+ // A malformed token keeps the IP quota active until the route rejects it.+ }+ next();+ };+}diff --git a/packages/api/src/auth/twoFactor.spec.ts b/packages/api/src/auth/twoFactor.spec.tsnew file mode 100644index 0000000000..9dc793e474--- /dev/null+++ b/packages/api/src/auth/twoFactor.spec.ts@@ -0,0 +1,1556 @@+import jwt from 'jsonwebtoken';+import { createHash } from 'node:crypto';+import type {+ IUser,+ TwoFactorEnrollmentGuard,+ TwoFactorEnrollmentUpdate,+} from '@librechat/data-schemas';+import type { NextFunction, Request, Response } from 'express';+import type {+ TokenIssuance,+ TwoFactorEnrollmentDependencies,+ TwoFactorEnrollmentRequest,+} from './twoFactor';+import {+ confirmTwoFactorSetup,+ finalizeTwoFactorSetup,+ acknowledgeTwoFactorSetup,+ TWO_FACTOR_TOKEN_PURPOSE,+ generateTwoFactorSetupFinalizationToken,+ generateTwoFactorSetupAcknowledgementToken,+ generateTwoFactorLoginChallengeToken,+ generateTwoFactorSetupToken,+ isTwoFactorEnrollmentRequired,+ isTwoFactorSetupEligible,+ isCredentialLoginBlockedByTwoFactorPolicy,+ isTokenRetired,+ isEnrollmentSupersededByRecovery,+ hasPasswordResetSince,+ requireTwoFactorSetupToken,+ createBlockRetiredSetupToken,+ requireTwoFactorSetupFinalizationToken,+ requireTwoFactorSetupAcknowledgementToken,+ verifyTwoFactorSetupToken,+ verifyTwoFactorSetupFinalizationToken,+ verifyTwoFactorSetupAcknowledgementToken,+ verifyTwoFactorLoginChallengeToken,+ blockTwoFactorDisableWhenRequired,+ withdrawMintedSession,+} from './twoFactor';++const jwtSecret = 'two-factor-setup-test-secret';+const nonce = 'test-nonce';++const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex');++describe('isTwoFactorEnrollmentRequired', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ });++ it.each(['local', 'ldap', undefined])('requires enrollment for %s users', (provider) => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';++ expect(isTwoFactorEnrollmentRequired({ provider, twoFactorEnabled: false })).toBe(true);+ });++ it.each(['openid', 'google', 'saml'])('preserves federated provider scope for %s', (provider) => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';++ expect(isTwoFactorEnrollmentRequired({ provider, twoFactorEnabled: false })).toBe(false);+ });++ it('does not require enrollment for enrolled users or when policy is disabled', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ expect(isTwoFactorEnrollmentRequired({ provider: 'local', twoFactorEnabled: true })).toBe(+ false,+ );++ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ expect(isTwoFactorEnrollmentRequired({ provider: 'local', twoFactorEnabled: false })).toBe(+ false,+ );+ });+});++describe('isTwoFactorSetupEligible', () => {+ it.each(['local', 'ldap', undefined])('allows %s users', (provider) => {+ expect(isTwoFactorSetupEligible({ provider })).toBe(true);+ });++ it.each(['openid', 'google', 'saml'])('rejects federated %s users', (provider) => {+ expect(isTwoFactorSetupEligible({ provider })).toBe(false);+ });+});++describe('isCredentialLoginBlockedByTwoFactorPolicy', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ });++ /**+ * A reset assigns a password without consulting `provider`, and the local strategy authenticates+ * on the password alone, so a federated record can be signed in with a password.+ */+ it.each(['openid', 'google', 'saml'])('blocks a %s record under enforcement', (provider) => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';++ expect(isCredentialLoginBlockedByTwoFactorPolicy({ provider })).toBe(true);+ });++ it.each(['local', 'ldap', undefined])('allows %s records under enforcement', (provider) => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';++ expect(isCredentialLoginBlockedByTwoFactorPolicy({ provider })).toBe(false);+ });++ it('blocks nothing when the policy is disabled', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';++ expect(isCredentialLoginBlockedByTwoFactorPolicy({ provider: 'openid' })).toBe(false);+ });++ it('treats a missing user as nothing to block', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';++ expect(isCredentialLoginBlockedByTwoFactorPolicy(null)).toBe(false);+ });+});++describe('isTokenRetired', () => {+ const enrolledAt = new Date('2026-01-01T00:00:10.500Z');+ const enrolledSecond = Math.floor(enrolledAt.getTime() / 1000);++ it('leaves accounts that never enrolled untouched', () => {+ expect(isTokenRetired({ issuedAt: 0 }, { twoFactorEnrolledAt: null })).toBe(false);+ expect(isTokenRetired({ issuedAt: 0 }, { twoFactorEnrolledAt: undefined })).toBe(false);+ });++ it('refuses a token issued before the enrolling second', () => {+ expect(+ isTokenRetired({ issuedAt: enrolledSecond - 1 }, { twoFactorEnrolledAt: enrolledAt }),+ ).toBe(true);+ });++ it('keeps the session minted within the enrolling second', () => {+ expect(isTokenRetired({ issuedAt: enrolledSecond }, { twoFactorEnrolledAt: enrolledAt })).toBe(+ false,+ );+ expect(+ isTokenRetired({ issuedAt: enrolledSecond + 1 }, { twoFactorEnrolledAt: enrolledAt }),+ ).toBe(false);+ });++ /**+ * `finalizeTwoFactorSetup` stamps the enrollment inside the promoting compare-and-swap, and the+ * session it hands back is minted after that write and a session sweep, so the survivor always+ * postdates the cutoff. A token dated to the millisecond therefore does not need the whole second+ * spared: keeping it would let a bearer minted just before the promotion outlive it, which is the+ * one thing enrollment retirement exists to stop.+ */+ it('retires a pre-enrollment bearer minted earlier in the enrolling second', () => {+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond, issuedAtMs: enrolledAt.getTime() - 1 },+ { twoFactorEnrolledAt: enrolledAt },+ ),+ ).toBe(true);+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond - 1, issuedAtMs: enrolledAt.getTime() - 1000 },+ { twoFactorEnrolledAt: enrolledAt },+ ),+ ).toBe(true);+ });++ it('keeps the session finalization mints, which postdates the enrollment stamp', () => {+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond, issuedAtMs: enrolledAt.getTime() },+ { twoFactorEnrolledAt: enrolledAt },+ ),+ ).toBe(false);+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond, issuedAtMs: enrolledAt.getTime() + 1 },+ { twoFactorEnrolledAt: enrolledAt },+ ),+ ).toBe(false);+ });++ it('accepts a stamp that arrives as a string or epoch value', () => {+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond - 1 },+ {+ twoFactorEnrolledAt: enrolledAt.toISOString(),+ },+ ),+ ).toBe(true);+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond - 1 },+ { twoFactorEnrolledAt: enrolledAt.getTime() },+ ),+ ).toBe(true);+ });++ it('refuses an undatable token once the account is enrolled', () => {+ expect(isTokenRetired({ issuedAt: undefined }, { twoFactorEnrolledAt: enrolledAt })).toBe(true);+ expect(isTokenRetired({ issuedAt: Number.NaN }, { twoFactorEnrolledAt: enrolledAt })).toBe(+ true,+ );+ });++ it('ignores an unparseable stamp rather than locking every session out', () => {+ expect(+ isTokenRetired({ issuedAt: enrolledSecond }, { twoFactorEnrolledAt: 'not-a-date' }),+ ).toBe(false);+ });++ describe('password recovery', () => {+ const resetAt = new Date('2026-02-02T00:00:10.500Z');+ const resetMs = resetAt.getTime();+ const resetSecond = Math.floor(resetMs / 1000);++ it('refuses a token minted for the credential the reset revoked', () => {+ expect(isTokenRetired({ issuedAt: resetSecond - 1 }, { credentialsChangedAt: resetAt })).toBe(+ true,+ );+ });++ it('keeps a token minted from the new credential', () => {+ expect(isTokenRetired({ issuedAt: resetSecond + 1 }, { credentialsChangedAt: resetAt })).toBe(+ false,+ );+ });++ it('retires a token minted earlier in the resetting second', () => {+ expect(+ isTokenRetired(+ { issuedAt: resetSecond, issuedAtMs: resetMs - 1 },+ { credentialsChangedAt: resetAt },+ ),+ ).toBe(true);+ });++ it('retires a token minted in the very millisecond of the reset', () => {+ expect(+ isTokenRetired(+ { issuedAt: resetSecond, issuedAtMs: resetMs },+ { credentialsChangedAt: resetAt },+ ),+ ).toBe(true);+ });++ /**+ * The session a sign-in lands in the resetting second buys is minted from the new credential,+ * so retiring it would 401 every request until the user signed in again.+ */+ it('keeps a token minted after the reset, even inside the same second', () => {+ expect(+ isTokenRetired(+ { issuedAt: resetSecond, issuedAtMs: resetMs + 1 },+ { credentialsChangedAt: resetAt },+ ),+ ).toBe(false);+ });++ /** Without the claim there is nothing to order within the second, so the whole second goes. */+ it('surrenders the resetting second for a token minted before the claim existed', () => {+ expect(isTokenRetired({ issuedAt: resetSecond }, { credentialsChangedAt: resetAt })).toBe(+ true,+ );+ expect(isTokenRetired({ issuedAt: undefined }, { credentialsChangedAt: resetAt })).toBe(true);+ });++ it('keeps the enrolling second while refusing the resetting one', () => {+ expect(+ isTokenRetired({ issuedAt: enrolledSecond }, { twoFactorEnrolledAt: enrolledAt }),+ ).toBe(false);+ expect(isTokenRetired({ issuedAt: resetSecond }, { credentialsChangedAt: resetAt })).toBe(+ true,+ );+ });++ it('leaves accounts that never reset untouched', () => {+ expect(isTokenRetired({ issuedAt: 0 }, { credentialsChangedAt: null })).toBe(false);+ expect(isTokenRetired({ issuedAt: 0 }, {})).toBe(false);+ expect(isTokenRetired({ issuedAt: 0 }, null)).toBe(false);+ expect(isTokenRetired({ issuedAt: resetSecond, issuedAtMs: resetMs }, {})).toBe(false);+ expect(isTokenRetired({ issuedAt: resetSecond, issuedAtMs: resetMs }, null)).toBe(false);+ });++ it('retires on whichever cutoff the token predates', () => {+ expect(+ isTokenRetired(+ { issuedAt: resetSecond - 1 },+ { twoFactorEnrolledAt: enrolledAt, credentialsChangedAt: resetAt },+ ),+ ).toBe(true);+ expect(+ isTokenRetired(+ { issuedAt: enrolledSecond - 1 },+ { twoFactorEnrolledAt: enrolledAt, credentialsChangedAt: resetAt },+ ),+ ).toBe(true);+ expect(+ isTokenRetired(+ { issuedAt: resetSecond + 1 },+ { twoFactorEnrolledAt: enrolledAt, credentialsChangedAt: resetAt },+ ),+ ).toBe(false);+ });++ it('refuses an undatable token once the account has reset', () => {+ expect(isTokenRetired({ issuedAt: undefined }, { credentialsChangedAt: resetAt })).toBe(true);+ });++ it('ignores an unparseable reset stamp rather than stranding the session', () => {+ expect(+ isTokenRetired(+ { issuedAt: resetSecond, issuedAtMs: resetMs },+ { credentialsChangedAt: 'not-a-date' },+ ),+ ).toBe(false);+ });+ });+});++describe('isEnrollmentSupersededByRecovery', () => {+ const enrolledAt = new Date('2026-01-01T00:00:10.500Z');++ it('reports nothing when either stamp is missing', () => {+ expect(isEnrollmentSupersededByRecovery(null, new Date())).toBe(false);+ expect(isEnrollmentSupersededByRecovery(enrolledAt, null)).toBe(false);+ expect(isEnrollmentSupersededByRecovery(undefined, undefined)).toBe(false);+ });++ it('reports a reset that landed after the enrollment was promoted', () => {+ expect(isEnrollmentSupersededByRecovery(enrolledAt, new Date(enrolledAt.getTime() + 1))).toBe(+ true,+ );+ });++ it('leaves an enrollment that followed an older reset alone', () => {+ expect(isEnrollmentSupersededByRecovery(enrolledAt, new Date(enrolledAt.getTime() - 1))).toBe(+ false,+ );+ });++ /** `iat` rounds to whole seconds, so a same-millisecond reset is the race, not a coincidence. */+ it('resolves a tie against the enrollment', () => {+ expect(isEnrollmentSupersededByRecovery(enrolledAt, new Date(enrolledAt.getTime()))).toBe(true);+ });++ it('accepts stamps that arrive as strings or epoch values', () => {+ expect(+ isEnrollmentSupersededByRecovery(enrolledAt.toISOString(), enrolledAt.getTime() + 1),+ ).toBe(true);+ });++ it('ignores an unparseable stamp rather than withdrawing every enrollment', () => {+ expect(isEnrollmentSupersededByRecovery('not-a-date', new Date())).toBe(false);+ expect(isEnrollmentSupersededByRecovery(enrolledAt, 'not-a-date')).toBe(false);+ });+});++describe('hasPasswordResetSince', () => {+ const seenAt = new Date('2026-01-01T00:00:10.500Z');++ it('reports a reset that landed after the authenticating read', () => {+ expect(hasPasswordResetSince(seenAt, new Date(seenAt.getTime() + 1))).toBe(true);+ });++ it('reports the first reset an account has ever had', () => {+ expect(hasPasswordResetSince(null, seenAt)).toBe(true);+ expect(hasPasswordResetSince(undefined, seenAt)).toBe(true);+ });++ it('leaves the stamp the authenticating read already saw alone', () => {+ expect(hasPasswordResetSince(seenAt, new Date(seenAt.getTime()))).toBe(false);+ expect(hasPasswordResetSince(seenAt, seenAt.toISOString())).toBe(false);+ });++ /** Nothing revoked the password, so an account that never reset one cannot be refused. */+ it('reports nothing when the record carries no reset at all', () => {+ expect(hasPasswordResetSince(null, null)).toBe(false);+ expect(hasPasswordResetSince(seenAt, undefined)).toBe(false);+ });++ it('accepts stamps that arrive as strings or epoch values', () => {+ expect(hasPasswordResetSince(seenAt.toISOString(), seenAt.getTime() + 1)).toBe(true);+ expect(hasPasswordResetSince(seenAt.getTime(), seenAt.toISOString())).toBe(false);+ });++ it('ignores an unparseable stamp rather than refusing every login', () => {+ expect(hasPasswordResetSince(seenAt, 'not-a-date')).toBe(false);+ });++ /** An unreadable prior stamp is no evidence of what the authenticating read saw. */+ it('treats an unparseable prior stamp as a reset it cannot rule out', () => {+ expect(hasPasswordResetSince('not-a-date', seenAt)).toBe(true);+ });+});++function createResponse(): Response {+ return {+ status: jest.fn().mockReturnThis(),+ json: jest.fn().mockReturnThis(),+ } as Partial<Response> as Response;+}++describe('two-factor setup tokens', () => {+ it('round-trips only a purpose-scoped login challenge token', () => {+ const loginToken = generateTwoFactorLoginChallengeToken('user-1', jwtSecret);+ const setupToken = generateTwoFactorSetupToken('user-1', jwtSecret);+ const acknowledgementToken = generateTwoFactorSetupAcknowledgementToken(+ 'user-1',+ nonce,+ jwtSecret,+ );+ const finalizationToken = generateTwoFactorSetupFinalizationToken('user-1', nonce, jwtSecret);++ expect(verifyTwoFactorLoginChallengeToken(loginToken, jwtSecret)).toEqual({+ userId: 'user-1',+ issuedAt: expect.any(Number),+ issuedAtMs: expect.any(Number),+ });+ expect(verifyTwoFactorLoginChallengeToken(setupToken, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorLoginChallengeToken(acknowledgementToken, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorLoginChallengeToken(finalizationToken, jwtSecret)).toBeUndefined();+ });++ it('dates a login challenge to the millisecond so a same-second reset can retire it', () => {+ const before = Date.now();+ const credential = verifyTwoFactorLoginChallengeToken(+ generateTwoFactorLoginChallengeToken('user-1', jwtSecret),+ jwtSecret,+ );+ const after = Date.now();++ expect(credential?.issuedAtMs).toBeGreaterThanOrEqual(before);+ expect(credential?.issuedAtMs).toBeLessThanOrEqual(after);+ expect(+ isTokenRetired(credential as TokenIssuance, {+ credentialsChangedAt: new Date(credential?.issuedAtMs as number),+ }),+ ).toBe(true);+ expect(+ isTokenRetired(credential as TokenIssuance, {+ credentialsChangedAt: new Date((credential?.issuedAtMs as number) - 1),+ }),+ ).toBe(false);+ });++ it('reads a legacy login challenge that predates the millisecond claim', () => {+ const legacyToken = jwt.sign(+ { userId: 'user-1', purpose: TWO_FACTOR_TOKEN_PURPOSE.LOGIN_CHALLENGE },+ jwtSecret,+ { expiresIn: '5m' },+ );++ expect(verifyTwoFactorLoginChallengeToken(legacyToken, jwtSecret)).toEqual({+ userId: 'user-1',+ issuedAt: expect.any(Number),+ issuedAtMs: undefined,+ });+ });++ it('round-trips a purpose-scoped setup token', () => {+ const token = generateTwoFactorSetupToken('user-2', jwtSecret);++ expect(verifyTwoFactorSetupToken(token, jwtSecret)).toEqual({+ userId: 'user-2',+ issuedAt: expect.any(Number),+ issuedAtMs: expect.any(Number),+ });+ });++ it('dates a setup token to the millisecond so a same-second reset can retire it', () => {+ const before = Date.now();+ const credential = verifyTwoFactorSetupToken(+ generateTwoFactorSetupToken('user-2', jwtSecret),+ jwtSecret,+ );+ const after = Date.now();++ expect(credential?.issuedAtMs).toBeGreaterThanOrEqual(before);+ expect(credential?.issuedAtMs).toBeLessThanOrEqual(after);+ });++ it('reads a legacy setup token that predates the millisecond claim', () => {+ const legacyToken = jwt.sign(+ { userId: 'user-2', purpose: TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_SETUP },+ jwtSecret,+ { expiresIn: '10m' },+ );++ expect(verifyTwoFactorSetupToken(legacyToken, jwtSecret)).toEqual({+ userId: 'user-2',+ issuedAt: expect.any(Number),+ issuedAtMs: undefined,+ });+ });++ it('rejects a normal 2FA challenge token for setup', () => {+ const token = jwt.sign(+ { userId: 'user-1', purpose: TWO_FACTOR_TOKEN_PURPOSE.LOGIN_CHALLENGE },+ jwtSecret,+ { expiresIn: '5m' },+ );++ expect(verifyTwoFactorSetupToken(token, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorSetupFinalizationToken(token, jwtSecret)).toBeUndefined();+ });++ it('rejects legacy purpose-less tokens', () => {+ const token = jwt.sign({ userId: 'user-1', twoFASetupRequired: true }, jwtSecret, {+ expiresIn: '5m',+ });++ expect(verifyTwoFactorSetupToken(token, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorSetupFinalizationToken(token, jwtSecret)).toBeUndefined();+ });++ it('rejects expired setup tokens', () => {+ const token = jwt.sign(+ { userId: 'user-1', purpose: TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_SETUP },+ jwtSecret,+ { expiresIn: -1 },+ );++ expect(verifyTwoFactorSetupToken(token, jwtSecret)).toBeUndefined();+ });++ it('round-trips only purpose-scoped finalization credentials', () => {+ const token = generateTwoFactorSetupFinalizationToken('user-1', nonce, jwtSecret);+ const setupToken = generateTwoFactorSetupToken('user-1', jwtSecret);++ expect(verifyTwoFactorSetupFinalizationToken(token, jwtSecret)).toEqual({+ userId: 'user-1',+ nonce,+ });+ expect(verifyTwoFactorSetupFinalizationToken(setupToken, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorSetupToken(token, jwtSecret)).toBeUndefined();+ });++ it('round-trips only purpose-scoped acknowledgement credentials', () => {+ const token = generateTwoFactorSetupAcknowledgementToken('user-1', nonce, jwtSecret);+ const setupToken = generateTwoFactorSetupToken('user-1', jwtSecret);+ const finalizationToken = generateTwoFactorSetupFinalizationToken('user-1', nonce, jwtSecret);++ expect(verifyTwoFactorSetupAcknowledgementToken(token, jwtSecret)).toEqual({+ userId: 'user-1',+ nonce,+ });+ expect(verifyTwoFactorSetupAcknowledgementToken(setupToken, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorSetupAcknowledgementToken(finalizationToken, jwtSecret)).toBeUndefined();+ });++ it.each([+ ['acknowledgement', generateTwoFactorSetupAcknowledgementToken],+ ['finalization', generateTwoFactorSetupFinalizationToken],+ ])('rejects a nonce-less %s credential', (_label, generate) => {+ const purpose =+ generate === generateTwoFactorSetupAcknowledgementToken+ ? TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_ACKNOWLEDGEMENT+ : TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_FINALIZATION;+ const token = jwt.sign({ userId: 'user-1', purpose }, jwtSecret, { expiresIn: '5m' });++ expect(verifyTwoFactorSetupAcknowledgementToken(token, jwtSecret)).toBeUndefined();+ expect(verifyTwoFactorSetupFinalizationToken(token, jwtSecret)).toBeUndefined();+ });+});++describe('requireTwoFactorSetupAcknowledgementToken', () => {+ beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ process.env.JWT_SECRET = jwtSecret;+ });++ it('attaches the acknowledgement identity and its one-time nonce', () => {+ const req = {+ body: {+ acknowledgementToken: generateTwoFactorSetupAcknowledgementToken(+ 'user-5',+ nonce,+ jwtSecret,+ ),+ },+ } as Request;+ const res = createResponse();+ const next = jest.fn();++ requireTwoFactorSetupAcknowledgementToken(req, res, next);++ expect(req.user).toEqual({ id: 'user-5' });+ expect((req as TwoFactorEnrollmentRequest).twoFactorEnrollmentNonce).toBe(nonce);+ expect(next).toHaveBeenCalledTimes(1);+ });++ it.each([+ generateTwoFactorSetupToken('user-5', jwtSecret),+ generateTwoFactorSetupFinalizationToken('user-5', nonce, jwtSecret),+ generateTwoFactorLoginChallengeToken('user-5', jwtSecret),+ ])('rejects a wrong-purpose token', (acknowledgementToken) => {+ const req = { body: { acknowledgementToken } } as Request;+ const res = createResponse();+ const next = jest.fn();++ requireTwoFactorSetupAcknowledgementToken(req, res, next);++ expect(res.status).toHaveBeenCalledWith(401);+ expect(next).not.toHaveBeenCalled();+ });+});++describe('requireTwoFactorSetupFinalizationToken', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ const originalSecret = process.env.JWT_SECRET;++ beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ process.env.JWT_SECRET = jwtSecret;+ });++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ if (originalSecret === undefined) {+ delete process.env.JWT_SECRET;+ } else {+ process.env.JWT_SECRET = originalSecret;+ }+ });++ it('attaches the finalization identity and its one-time nonce', () => {+ const req = {+ body: {+ finalizationToken: generateTwoFactorSetupFinalizationToken('user-4', nonce, jwtSecret),+ },+ } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupFinalizationToken(req, res, next);++ expect(req.user).toEqual({ id: 'user-4' });+ expect((req as TwoFactorEnrollmentRequest).twoFactorEnrollmentNonce).toBe(nonce);+ expect(next).toHaveBeenCalledTimes(1);+ });++ it('rejects invalid and wrong-purpose tokens', () => {+ const tokens = [+ 'invalid',+ generateTwoFactorSetupToken('user-4', jwtSecret),+ generateTwoFactorSetupAcknowledgementToken('user-4', nonce, jwtSecret),+ generateTwoFactorLoginChallengeToken('user-4', jwtSecret),+ jwt.sign({ userId: 'user-4' }, jwtSecret),+ ];++ for (const finalizationToken of tokens) {+ const req = { body: { finalizationToken } } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupFinalizationToken(req, res, next);++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ }+ });++ it('rejects finalization when global enforcement is disabled', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ const req = {+ body: {+ finalizationToken: generateTwoFactorSetupFinalizationToken('user-4', nonce, jwtSecret),+ },+ } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupFinalizationToken(req, res, next);++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });+});++describe('requireTwoFactorSetupToken', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ const originalSecret = process.env.JWT_SECRET;++ beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ process.env.JWT_SECRET = jwtSecret;+ });++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ if (originalSecret === undefined) {+ delete process.env.JWT_SECRET;+ } else {+ process.env.JWT_SECRET = originalSecret;+ }+ });++ it('attaches the setup user and continues for a valid token', () => {+ const req = {+ body: { tempToken: generateTwoFactorSetupToken('user-2', jwtSecret) },+ } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupToken(req, res, next);++ expect(req.user).toEqual({ id: 'user-2' });+ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+ });++ it('stamps the mint time, so a later account event can retire the token', () => {+ const req = {+ body: { tempToken: generateTwoFactorSetupToken('user-2', jwtSecret) },+ } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupToken(req, res, next);++ const setupRequest = req as TwoFactorEnrollmentRequest;+ const issuedAt = setupRequest.twoFactorSetupIssuedAt;+ const issuedAtMs = setupRequest.twoFactorSetupIssuedAtMs;+ expect(typeof issuedAt).toBe('number');+ expect(typeof issuedAtMs).toBe('number');+ expect(+ isTokenRetired({ issuedAt }, { credentialsChangedAt: new Date((issuedAt as number) * 1000) }),+ ).toBe(true);+ expect(+ isTokenRetired(+ { issuedAt },+ { credentialsChangedAt: new Date(((issuedAt as number) + 1) * 1000) },+ ),+ ).toBe(true);++ /** The millisecond claim is what still spares a setup token minted after the reset landed. */+ expect(+ isTokenRetired(+ { issuedAt, issuedAtMs },+ { credentialsChangedAt: new Date((issuedAtMs as number) - 1) },+ ),+ ).toBe(false);+ });++ it('rejects setup when the deployment policy is disabled', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ const req = {+ body: { tempToken: generateTwoFactorSetupToken('user-2', jwtSecret) },+ } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupToken(req, res, next);++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('rejects missing or invalid setup tokens', () => {+ const req = { body: { tempToken: 'invalid' } } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupToken(req, res, next);++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('rejects login challenge, acknowledgement, and finalization tokens', () => {+ const tokens = [+ jwt.sign({ userId: 'user-2', purpose: TWO_FACTOR_TOKEN_PURPOSE.LOGIN_CHALLENGE }, jwtSecret),+ generateTwoFactorSetupAcknowledgementToken('user-2', nonce, jwtSecret),+ generateTwoFactorSetupFinalizationToken('user-2', nonce, jwtSecret),+ ];++ for (const tempToken of tokens) {+ const req = { body: { tempToken } } as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ requireTwoFactorSetupToken(req, res, next);++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ }+ });+});++describe('createBlockRetiredSetupToken', () => {+ const resetAt = new Date('2026-02-02T00:00:10.500Z');+ const resetSecond = Math.floor(resetAt.getTime() / 1000);+ const getUserById = jest.fn();+ const blockRetiredSetupToken = createBlockRetiredSetupToken({ getUserById });++ const run = async (req: Partial<TwoFactorEnrollmentRequest>) => {+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;+ await blockRetiredSetupToken(req as Request, res, next);+ return { res, next };+ };++ beforeEach(() => {+ getUserById.mockReset();+ getUserById.mockResolvedValue({ _id: 'user-1' });+ });++ it('continues when nothing has retired the setup token', async () => {+ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond,+ });++ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+ });++ it('refuses a setup token minted before the password reset', async () => {+ getUserById.mockResolvedValue({ _id: 'user-1', credentialsChangedAt: resetAt });++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond - 1,+ });++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('admits a setup token minted after the password reset', async () => {+ getUserById.mockResolvedValue({ _id: 'user-1', credentialsChangedAt: resetAt });++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond + 1,+ });++ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+ });++ it('refuses a setup token minted earlier in the second the password reset landed', async () => {+ getUserById.mockResolvedValue({ _id: 'user-1', credentialsChangedAt: resetAt });++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond,+ twoFactorSetupIssuedAtMs: resetAt.getTime() - 1,+ });++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('admits a setup token minted later in the second the password reset landed', async () => {+ getUserById.mockResolvedValue({ _id: 'user-1', credentialsChangedAt: resetAt });++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond,+ twoFactorSetupIssuedAtMs: resetAt.getTime() + 1,+ });++ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+ });++ it('refuses a setup token minted before enrollment promoted the account', async () => {+ getUserById.mockResolvedValue({ _id: 'user-1', twoFactorEnrolledAt: resetAt });++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond - 1,+ });++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('refuses an undatable setup token once a cutoff is set', async () => {+ getUserById.mockResolvedValue({ _id: 'user-1', credentialsChangedAt: resetAt });++ const { res, next } = await run({ user: { id: 'user-1' } });++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('reads only the fields the cutoff needs', async () => {+ await run({ user: { id: 'user-1' }, twoFactorSetupIssuedAt: resetSecond });++ expect(getUserById).toHaveBeenCalledWith('user-1', 'twoFactorEnrolledAt credentialsChangedAt');+ });++ it('refuses when the named account no longer exists', async () => {+ getUserById.mockResolvedValue(null);++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond,+ });++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ });++ it('refuses when no setup user was stamped on the request', async () => {+ const { res, next } = await run({});++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(401);+ expect(getUserById).not.toHaveBeenCalled();+ });++ it('fails closed when the lookup throws', async () => {+ getUserById.mockRejectedValue(new Error('mongo is down'));++ const { res, next } = await run({+ user: { id: 'user-1' },+ twoFactorSetupIssuedAt: resetSecond,+ });++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(500);+ });+});++type BackupCode = NonNullable<IUser['backupCodes']>[number];++interface EnrollmentDocument {+ _id: string;+ provider?: string;+ twoFactorEnabled: boolean;+ twoFactorEnrolledAt?: Date;+ totpSecret?: string | null;+ backupCodes?: BackupCode[];+ pendingTotpSecret?: string | null;+ pendingBackupCodes?: BackupCode[];+ twoFactorAcknowledgementNonceHash?: string | null;+ twoFactorFinalizationNonceHash?: string | null;+}++const ELIGIBLE_PROVIDERS = new Set(['local', 'ldap']);++/**+ * A faithful in-memory stand-in for the guarded `updateTwoFactorEnrollment` write: it reproduces+ * the invariant filter (unenrolled, policy-eligible provider) plus exact-value predicates, so+ * replay and race behaviour is exercised for real rather than stubbed.+ */+function createEnrollmentStore(overrides: Partial<EnrollmentDocument> = {}) {+ let doc: EnrollmentDocument = {+ _id: 'user-3',+ provider: 'local',+ twoFactorEnabled: false,+ pendingTotpSecret: 'encrypted-secret',+ pendingBackupCodes: [{ codeHash: 'staged-hash', used: false }],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ ...overrides,+ };+ const writes: TwoFactorEnrollmentUpdate[] = [];++ const matchesGuard = (guard: TwoFactorEnrollmentGuard): boolean => {+ if (doc.twoFactorEnabled) {+ return false;+ }+ if (doc.provider != null && !ELIGIBLE_PROVIDERS.has(doc.provider)) {+ return false;+ }+ return Object.entries(guard).every(+ ([key, value]) =>+ JSON.stringify(doc[key as keyof EnrollmentDocument] ?? null) ===+ JSON.stringify(value ?? null),+ );+ };++ const deps: TwoFactorEnrollmentDependencies = {+ getUserById: jest.fn(async () => ({ ...doc }) as unknown as IUser),+ getTOTPSecret: jest.fn().mockResolvedValue('plain-secret'),+ verifyTOTP: jest.fn().mockResolvedValue(true),+ generateBackupCodes: jest.fn(async () => ({+ plainCodes: [`code-${writes.length + 1}`],+ codeObjects: [{ codeHash: `hash-${writes.length + 1}`, used: false, usedAt: null }],+ })),+ updateTwoFactorEnrollment: jest.fn(async (_userId, guard, update) => {+ if (!matchesGuard(guard)) {+ return null;+ }+ writes.push(update);+ doc = { ...doc, ...update };+ return { ...doc } as unknown as IUser;+ }),+ };++ return {+ deps,+ writes,+ read: () => ({ ...doc }),+ mutate: (patch: Partial<EnrollmentDocument>) => {+ doc = { ...doc, ...patch };+ },+ };+}++describe('required two-factor enrollment lifecycle', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;++ beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ });++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ });++ it('stages deliverable codes and an acknowledgement nonce without enabling 2FA', async () => {+ const store = createEnrollmentStore();++ const result = await confirmTwoFactorSetup('user-3', '123456', store.deps);++ expect(result.ok).toBe(true);+ if (!result.ok) {+ return;+ }+ expect(result.plainCodes).toEqual(['code-1']);+ expect(store.read()).toMatchObject({+ twoFactorEnabled: false,+ pendingTotpSecret: 'encrypted-secret',+ pendingBackupCodes: [{ codeHash: 'hash-1', used: false, usedAt: null }],+ twoFactorAcknowledgementNonceHash: sha256(result.acknowledgementNonce),+ twoFactorFinalizationNonceHash: null,+ });+ expect(store.read().totpSecret).toBeFalsy();+ expect(isTwoFactorEnrollmentRequired(result.user)).toBe(true);+ expect(store.deps.updateTwoFactorEnrollment).toHaveBeenCalledTimes(1);+ expect(store.deps.updateTwoFactorEnrollment).toHaveBeenCalledWith(+ 'user-3',+ {+ pendingTotpSecret: 'encrypted-secret',+ pendingBackupCodes: [{ codeHash: 'staged-hash', used: false }],+ },+ expect.objectContaining({ twoFactorFinalizationNonceHash: null }),+ );+ });++ it('stays retryable after a lost confirmation response, rotating codes and nonces', async () => {+ const store = createEnrollmentStore();++ const first = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ const second = await confirmTwoFactorSetup('user-3', '123456', store.deps);++ expect(first.ok && second.ok).toBe(true);+ if (!first.ok || !second.ok) {+ return;+ }+ expect(second.plainCodes).not.toEqual(first.plainCodes);+ expect(second.acknowledgementNonce).not.toBe(first.acknowledgementNonce);+ expect(store.read()).toMatchObject({+ twoFactorEnabled: false,+ twoFactorAcknowledgementNonceHash: sha256(second.acknowledgementNonce),+ });++ const stale = await acknowledgeTwoFactorSetup('user-3', first.acknowledgementNonce, store.deps);++ expect(stale).toEqual({+ ok: false,+ status: 400,+ message: 'This two-factor setup step expired. Confirm your code again.',+ });+ });++ it('rejects users who already have 2FA enabled', async () => {+ const store = createEnrollmentStore({ twoFactorEnabled: true });++ const result = await confirmTwoFactorSetup('user-3', '123456', store.deps);++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.deps.generateBackupCodes).not.toHaveBeenCalled();+ expect(store.deps.updateTwoFactorEnrollment).not.toHaveBeenCalled();+ });++ it('rejects a federated provider before generating anything', async () => {+ const store = createEnrollmentStore({ provider: 'openid' });++ const result = await confirmTwoFactorSetup('user-3', '123456', store.deps);++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.deps.generateBackupCodes).not.toHaveBeenCalled();+ });++ it('rejects an invalid TOTP without mutating the user', async () => {+ const store = createEnrollmentStore();+ (store.deps.verifyTOTP as jest.Mock).mockResolvedValue(false);++ const result = await confirmTwoFactorSetup('user-3', '000000', store.deps);++ expect(result).toEqual({ ok: false, status: 400, message: 'Invalid token' });+ expect(store.deps.generateBackupCodes).not.toHaveBeenCalled();+ expect(store.deps.updateTwoFactorEnrollment).not.toHaveBeenCalled();+ });++ it('rejects confirmation when the deployment policy flips off before the write', async () => {+ const store = createEnrollmentStore();+ (store.deps.verifyTOTP as jest.Mock).mockImplementation(async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ return true;+ });++ const result = await confirmTwoFactorSetup('user-3', '123456', store.deps);++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.deps.generateBackupCodes).toHaveBeenCalledTimes(1);+ expect(store.deps.updateTwoFactorEnrollment).not.toHaveBeenCalled();+ });++ it('fails closed when a concurrent setup regeneration moves the pending snapshot', async () => {+ const store = createEnrollmentStore();+ (store.deps.verifyTOTP as jest.Mock).mockImplementation(async () => {+ store.mutate({ pendingBackupCodes: [{ codeHash: 'regenerated', used: false }] });+ return true;+ });++ const result = await confirmTwoFactorSetup('user-3', '123456', store.deps);++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.read().twoFactorAcknowledgementNonceHash).toBeNull();+ });++ it('exchanges the acknowledgement nonce for a finalization nonce without enabling 2FA', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }++ const result = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );++ expect(result.ok).toBe(true);+ if (!result.ok) {+ return;+ }+ expect(store.read()).toMatchObject({+ twoFactorEnabled: false,+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: sha256(result.finalizationNonce),+ });+ expect(store.read().totpSecret).toBeFalsy();+ expect(isTwoFactorEnrollmentRequired(result.user)).toBe(true);+ });++ it('rejects a replayed acknowledgement credential without issuing anything', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const first = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!first.ok) {+ throw new Error('acknowledgement should succeed');+ }++ const replay = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );++ expect(replay.ok).toBe(false);+ expect(store.read().twoFactorFinalizationNonceHash).toBe(sha256(first.finalizationNonce));+ });++ it('rejects acknowledgement when the deployment policy is disabled', async () => {+ const store = createEnrollmentStore({ twoFactorAcknowledgementNonceHash: sha256('nonce-a') });+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';++ const result = await acknowledgeTwoFactorSetup('user-3', 'nonce-a', store.deps);++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.deps.updateTwoFactorEnrollment).not.toHaveBeenCalled();+ });++ it('promotes only at finalization and clears every enrollment field', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }++ const result = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(result.ok).toBe(true);+ expect(store.read()).toMatchObject({+ twoFactorEnabled: true,+ totpSecret: 'encrypted-secret',+ backupCodes: [{ codeHash: 'hash-1', used: false, usedAt: null }],+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ });+ expect(result.ok && isTwoFactorEnrollmentRequired(result.user)).toBe(false);+ });++ it('stamps the cutoff that retires pre-enrollment access tokens', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }+ const beforeFinalize = Date.now();++ const result = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(result.ok).toBe(true);+ const enrolledAt = store.read().twoFactorEnrolledAt;+ expect(enrolledAt).toBeInstanceOf(Date);+ expect((enrolledAt as Date).getTime()).toBeGreaterThanOrEqual(beforeFinalize);+ /** The token minted a moment earlier is now stale, the one finalization returns is not. */+ expect(+ isTokenRetired(+ { issuedAt: Math.floor(beforeFinalize / 1000) - 1 },+ { twoFactorEnrolledAt: enrolledAt as Date },+ ),+ ).toBe(true);+ expect(+ isTokenRetired(+ { issuedAt: Math.ceil(Date.now() / 1000) },+ { twoFactorEnrolledAt: enrolledAt as Date },+ ),+ ).toBe(false);+ });++ it('leaves the cutoff unset on the steps that do not promote', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ expect(store.read().twoFactorEnrolledAt).toBeUndefined();++ await acknowledgeTwoFactorSetup('user-3', confirmed.acknowledgementNonce, store.deps);++ expect(store.read().twoFactorEnrolledAt).toBeUndefined();+ });++ it('rejects a replayed finalization credential without a second promotion', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }+ await finalizeTwoFactorSetup('user-3', acknowledged.finalizationNonce, store.deps);+ const writesAfterFirst = store.writes.length;++ const replay = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(replay).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.writes).toHaveLength(writesAfterFirst);+ });++ it('rejects finalization carrying a stale nonce after a re-confirmation', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }+ await confirmTwoFactorSetup('user-3', '123456', store.deps);++ const result = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: 'This two-factor setup step expired. Confirm your code again.',+ });+ expect(store.read().twoFactorEnabled).toBe(false);+ });++ it('rejects finalization without a nonce before reading the user', async () => {+ const store = createEnrollmentStore();++ const result = await finalizeTwoFactorSetup('user-3', undefined, store.deps);++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: 'This two-factor setup step expired. Confirm your code again.',+ });+ expect(store.deps.getUserById).not.toHaveBeenCalled();+ });++ it.each([+ ['a federated provider transition', { provider: 'openid' }],+ ['an already-enabled transition', { twoFactorEnabled: true }],+ ])('rejects finalization after %s', async (_label, transition) => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }+ store.mutate(transition);++ const result = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.read().totpSecret).toBeFalsy();+ });++ it('rejects finalization when the deployment policy is disabled', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';++ const result = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(result).toEqual({+ ok: false,+ status: 400,+ message: '2FA setup is not available for this user',+ });+ expect(store.read().twoFactorEnabled).toBe(false);+ });++ it('rejects finalization once the pending setup has been cleared', async () => {+ const store = createEnrollmentStore();+ const confirmed = await confirmTwoFactorSetup('user-3', '123456', store.deps);+ if (!confirmed.ok) {+ throw new Error('confirmation should succeed');+ }+ const acknowledged = await acknowledgeTwoFactorSetup(+ 'user-3',+ confirmed.acknowledgementNonce,+ store.deps,+ );+ if (!acknowledged.ok) {+ throw new Error('acknowledgement should succeed');+ }+ store.mutate({ pendingTotpSecret: null, pendingBackupCodes: [] });++ const result = await finalizeTwoFactorSetup(+ 'user-3',+ acknowledged.finalizationNonce,+ store.deps,+ );++ expect(result).toEqual({ ok: false, status: 400, message: '2FA setup not initiated' });+ });+});++describe('blockTwoFactorDisableWhenRequired', () => {+ const originalPolicy = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;++ afterAll(() => {+ if (originalPolicy === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalPolicy;+ }+ });++ it('blocks disabling 2FA when it is required', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const req = {} as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ blockTwoFactorDisableWhenRequired(req, res, next);++ expect(next).not.toHaveBeenCalled();+ expect(res.status).toHaveBeenCalledWith(403);+ });++ it('allows disabling 2FA when it is optional', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';+ const req = {} as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ blockTwoFactorDisableWhenRequired(req, res, next);++ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+ });++ it('allows federated users to manage provider-exempt 2FA', () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ const req = { user: { provider: 'openid' } } as Partial<Request> as Request;+ const res = createResponse();+ const next = jest.fn() as jest.MockedFunction<NextFunction>;++ blockTwoFactorDisableWhenRequired(req, res, next);++ expect(next).toHaveBeenCalledTimes(1);+ expect(res.status).not.toHaveBeenCalled();+ });+});++describe('withdrawMintedSession', () => {+ /** A 500 that still carried the minted cookies could refresh once the database recovers. */+ it('clears the minted cookies even when the session deletion fails', async () => {+ const clearCookie = jest.fn();+ const res = { clearCookie } as unknown as Response;+ const clearCloudFrontCookies = jest.fn();+ const deletion = new Error('database unavailable');++ await expect(+ withdrawMintedSession(res, { tenantId: 'tenant-a' }, 'user-1', {+ deleteAllUserSessions: jest.fn().mockRejectedValue(deletion),+ clearCloudFrontCookies,+ }),+ ).rejects.toBe(deletion);++ expect(clearCookie).toHaveBeenCalledWith('refreshToken');+ expect(clearCookie).toHaveBeenCalledWith('token_provider');+ expect(clearCloudFrontCookies).toHaveBeenCalledWith(res, {+ userId: 'user-1',+ tenantId: 'tenant-a',+ storageRegion: undefined,+ });+ });+});diff --git a/packages/api/src/auth/twoFactor.ts b/packages/api/src/auth/twoFactor.tsnew file mode 100644index 0000000000..1cf864b647--- /dev/null+++ b/packages/api/src/auth/twoFactor.ts@@ -0,0 +1,785 @@+import jwt from 'jsonwebtoken';+import { logger } from '@librechat/data-schemas';+import { createHash, randomBytes } from 'node:crypto';+import { isTwoFactorPolicyProvider } from 'librechat-data-provider';+import type { TwoFactorEnrollmentGuard, TwoFactorEnrollmentUpdate } from '@librechat/data-schemas';+import type { NextFunction, Request, Response } from 'express';+import type { UserDocumentId } from '~/auth/verification';+import { isEnabled } from '~/utils';++const TWO_FACTOR_SETUP_TOKEN_EXPIRY = '10m';+const TWO_FACTOR_SETUP_ACKNOWLEDGEMENT_TOKEN_EXPIRY = '5m';+const TWO_FACTOR_SETUP_FINALIZATION_TOKEN_EXPIRY = '5m';+const TWO_FACTOR_LOGIN_CHALLENGE_TOKEN_EXPIRY = '5m';+const TWO_FACTOR_SETUP_UNAVAILABLE = '2FA setup is not available for this user';+const TWO_FACTOR_SETUP_NOT_INITIATED = '2FA setup not initiated';+const TWO_FACTOR_SETUP_STALE = 'This two-factor setup step expired. Confirm your code again.';+const TWO_FACTOR_INVALID_TOKEN = 'Invalid token';+const TWO_FACTOR_ENROLLMENT_PROJECTION =+ '+pendingTotpSecret +pendingBackupCodes _id twoFactorEnabled provider';++export const TWO_FACTOR_TOKEN_PURPOSE = {+ LOGIN_CHALLENGE: 'login_2fa_challenge',+ REQUIRED_SETUP: 'required_2fa_setup',+ REQUIRED_ACKNOWLEDGEMENT: 'required_2fa_acknowledgement',+ REQUIRED_FINALIZATION: 'required_2fa_finalization',+} as const;++interface TwoFactorSetupBody {+ tempToken?: string;+ acknowledgementToken?: string;+ finalizationToken?: string;+}++/**+ * The account events that retire every bearer token minted before them.+ *+ * Widened past the stored `Date`, because callers pass lean documents whose stamps can arrive+ * already serialized, and a cutoff that fails to parse must not lock every session out.+ */+export interface TokenRetirementSignals {+ twoFactorEnrolledAt?: Date | string | number | null;+ credentialsChangedAt?: Date | string | number | null;+}++/** A stored backup code: only its hash is persisted, and redemption marks it used. */+export interface TwoFactorBackupCode {+ codeHash: string;+ used: boolean;+ usedAt?: Date | null;+}++/**+ * The account fields the two-factor and credential routes read, as a plain shape: neither the+ * request's user nor the data-layer results carry Mongoose types across the package boundary.+ */+export interface TwoFactorAccount extends TokenRetirementSignals {+ _id?: UserDocumentId;+ id?: string;+ provider?: string;+ role?: string;+ tenantId?: string;+ orgId?: string;+ storageRegion?: string;+ password?: string;+ twoFactorEnabled?: boolean;+ totpSecret?: string;+ backupCodes?: TwoFactorBackupCode[];+ pendingTotpSecret?: string;+ pendingBackupCodes?: TwoFactorBackupCode[];+ twoFactorAcknowledgementNonceHash?: string | null;+ twoFactorFinalizationNonceHash?: string | null;+}++/** An account as the data layer returns it, always addressed by its document id. */+export type StoredTwoFactorAccount = TwoFactorAccount & { _id: UserDocumentId };++/** The user fields `isTokenRetired` needs, for callers that read with an explicit projection. */+export const TOKEN_RETIREMENT_FIELDS = 'twoFactorEnrolledAt credentialsChangedAt';++/** Identity plus the one-time nonce a required-enrollment credential carries. */+export interface TwoFactorEnrollmentCredential {+ userId: string;+ nonce: string;+}++/**+ * When a bearer token was minted, coarsely and exactly.+ *+ * `iat` is whole seconds, which cannot order a token against a cutoff that lands in the same+ * second. `issuedAtMs` is stamped at mint time to settle exactly that, and is absent on tokens+ * minted before the claim existed and on any this deployment did not sign.+ */+export interface TokenIssuance {+ issuedAt?: number;+ issuedAtMs?: number;+}++/** Identity plus the mint time that lets a later account event retire the credential. */+export interface TwoFactorTokenCredential extends TokenIssuance {+ userId: string;+}++/** An Express request that a required-enrollment credential has been validated for. */+export type TwoFactorEnrollmentRequest = Request & {+ user?: { id: string };+ twoFactorEnrollmentNonce?: string;+ twoFactorSetupIssuedAt?: number;+ twoFactorSetupIssuedAtMs?: number;+};++export type TwoFactorSetupUser = Pick<+ StoredTwoFactorAccount,+ '_id' | 'provider' | 'twoFactorEnabled' | 'pendingTotpSecret' | 'pendingBackupCodes'+>;++export interface TwoFactorEnrollmentDependencies {+ getUserById: (userId: string, projection: string) => Promise<TwoFactorSetupUser | null>;+ getTOTPSecret: (storedSecret: string) => Promise<string | null>;+ verifyTOTP: (secret: string, token: string) => Promise<boolean>;+ generateBackupCodes: () => Promise<{+ plainCodes: string[];+ codeObjects: TwoFactorBackupCode[];+ }>;+ updateTwoFactorEnrollment: (+ userId: string,+ guard: TwoFactorEnrollmentGuard,+ update: TwoFactorEnrollmentUpdate,+ ) => Promise<StoredTwoFactorAccount | null>;+}++type TwoFactorEnrollmentFailure = { ok: false; status: 400; message: string };++export type TwoFactorConfirmResult =+ | { ok: true; user: StoredTwoFactorAccount; plainCodes: string[]; acknowledgementNonce: string }+ | TwoFactorEnrollmentFailure;++export type TwoFactorAcknowledgeResult =+ | { ok: true; user: StoredTwoFactorAccount; finalizationNonce: string }+ | TwoFactorEnrollmentFailure;++export type TwoFactorFinalizeResult =+ | { ok: true; user: StoredTwoFactorAccount }+ | TwoFactorEnrollmentFailure;++const fail = (message: string): TwoFactorEnrollmentFailure => ({ ok: false, status: 400, message });++/** 256 bits of entropy, so the stored SHA-256 digest is not brute-forceable. */+const createEnrollmentNonce = (): string => randomBytes(32).toString('hex');++const hashEnrollmentNonce = (nonce: string): string =>+ createHash('sha256').update(nonce).digest('hex');++export function isTwoFactorEnrollmentRequired(+ user: Pick<TwoFactorAccount, 'twoFactorEnabled' | 'provider'> | null | undefined,+): boolean {+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION) || user?.twoFactorEnabled) {+ return false;+ }++ return isTwoFactorPolicyProvider(user?.provider);+}++export function isTwoFactorSetupEligible(+ user: Pick<TwoFactorAccount, 'provider'> | null | undefined,+): boolean {+ return isTwoFactorPolicyProvider(user?.provider);+}++/**+ * Whether a login that presented LibreChat-owned credentials must be refused outright.+ *+ * Only the local and LDAP strategies reach this point, so the credential was ours to check. A+ * record left on a federated provider can still carry a password, because a reset assigns one+ * without consulting `provider`, and the local strategy authenticates on the password alone. Such+ * a login satisfies neither the identity provider's MFA nor this policy, and enrollment cannot+ * remedy it because the account's credentials are not ours to promote. Under enforcement the+ * federated sign-in path is the only way in.+ */+export function isCredentialLoginBlockedByTwoFactorPolicy(+ user: Pick<TwoFactorAccount, 'provider'> | null | undefined,+): boolean {+ return (+ isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION) &&+ !isTwoFactorPolicyProvider(user?.provider)+ );+}++function isTokenIssuedBefore(+ issuance: TokenIssuance,+ cutoff: Date | string | number | null | undefined,+ retireTies: boolean,+): boolean {+ if (cutoff == null) {+ return false;+ }++ const cutoffMs = new Date(cutoff).getTime();+ if (Number.isNaN(cutoffMs)) {+ return false;+ }++ const { issuedAtMs } = issuance;+ if (typeof issuedAtMs === 'number' && Number.isFinite(issuedAtMs)) {+ return retireTies ? issuedAtMs <= cutoffMs : issuedAtMs < cutoffMs;+ }++ const { issuedAt } = issuance;+ if (typeof issuedAt !== 'number' || !Number.isFinite(issuedAt)) {+ return true;+ }++ const cutoffSeconds = Math.floor(cutoffMs / 1000);+ return retireTies ? issuedAt <= cutoffSeconds : issuedAt < cutoffSeconds;+}++/**+ * Whether a bearer token was minted before an account event that retires it.+ *+ * Bearer tokens carry no server-side state, so nothing stops honouring one the moment the account+ * changes underneath it. Two events have to. Enrollment, because a token issued while the account+ * still had no second factor was only ever accepted for that reason, so promotion has to retire it+ * rather than reinstate it. And password recovery, because the credential the token was minted for+ * has been revoked; `deleteAllUserSessions` already drops the refresh sessions on that path with+ * the same intent, and a stateless token must not outlive the password that bought it.+ *+ * Both cutoffs are compared at whatever resolution the token can prove, and they differ only in how+ * they resolve a tie. Enrollment keeps the token, because `finalizeTwoFactorSetup` stamps+ * `twoFactorEnrolledAt` inside the promoting compare-and-swap and the session it hands back is+ * minted after that write and a session sweep, so the survivor postdates the cutoff outright.+ * Recovery retires it, because it mints nothing that has to live through it: a token dated to the+ * resetting instant was bought with the credential the reset revoked. `issuedAtMs` is what makes+ * either tie exact, sparing a token minted later in the same second that the whole-second fallback+ * cannot tell apart, and retiring one minted earlier in it that the fallback would have spared.+ * Tokens carrying no `issuedAtMs` surrender that whole second until they expire, and a token that+ * cannot be dated at all is refused once any cutoff is set.+ */+export function isTokenRetired(+ issuance: TokenIssuance,+ user: TokenRetirementSignals | null | undefined,+): boolean {+ return (+ isTokenIssuedBefore(issuance, user?.twoFactorEnrolledAt, false) ||+ isTokenIssuedBefore(issuance, user?.credentialsChangedAt, true)+ );+}++export interface MintedSessionWithdrawal {+ deleteAllUserSessions: (query: { userId: string }) => Promise<unknown>;+ clearCloudFrontCookies: (+ res: Response,+ scope: { userId: string; tenantId?: string; storageRegion?: string },+ ) => void;+}++/**+ * Withdraws a session minted on this response. The cookies are cleared before the fallible session+ * deletion, so a deletion that throws cannot leave the outgoing response carrying the credential.+ */+export async function withdrawMintedSession(+ res: Response,+ user: Pick<TwoFactorAccount, 'tenantId' | 'orgId' | 'storageRegion'>,+ userId: string,+ deps: MintedSessionWithdrawal,+): Promise<void> {+ res.clearCookie('refreshToken');+ res.clearCookie('token_provider');+ deps.clearCloudFrontCookies(res, {+ userId,+ tenantId: user.tenantId ?? user.orgId,+ storageRegion: user.storageRegion,+ });+ await deps.deleteAllUserSessions({ userId });+}++/**+ * Runs the retirement recheck that follows a mint. The minted credential postdates every cutoff,+ * so a recheck that cannot complete withdraws it before failing rather than leaving it live.+ */+export async function recheckMintedCredential<T>(+ recheck: () => Promise<T>,+ withdraw: () => Promise<void>,+): Promise<T> {+ try {+ return await recheck();+ } catch (error) {+ await withdraw();+ throw error;+ }+}++/**+ * Whether password recovery landed after an enrollment was promoted.+ *+ * Recovery clears the staged enrollment in the same write that stamps `credentialsChangedAt`, so a reset+ * that lands first loses `finalizeTwoFactorSetup`'s compare-and-swap. One that lands in the gap+ * between that swap and the session hand-off does not, and the credential minted in that gap+ * postdates the cutoff, so `isTokenRetired` has nothing to catch it by. Comparing the two stamps is+ * what closes that ordering, and it is only meaningful against an enrollment just written.+ *+ * Compared at full resolution rather than the whole seconds `iat` forces, and ties resolve against+ * the enrollment: a reset stamped in the very millisecond of promotion is the race, not a race-free+ * coincidence.+ */+export function isEnrollmentSupersededByRecovery(+ enrolledAt: Date | string | number | null | undefined,+ credentialsChangedAt: Date | string | number | null | undefined,+): boolean {+ if (enrolledAt == null || credentialsChangedAt == null) {+ return false;+ }++ const enrolledMs = new Date(enrolledAt).getTime();+ const resetMs = new Date(credentialsChangedAt).getTime();+ if (Number.isNaN(enrolledMs) || Number.isNaN(resetMs)) {+ return false;+ }++ return resetMs >= enrolledMs;+}++/**+ * Whether password recovery landed after the read that authorized a password login.+ *+ * A password is not a bearer token: it carries no mint stamp, so `isTokenRetired` cannot order it+ * against `credentialsChangedAt`. The strategy compares the hash against a document it read beforehand,+ * and every credential the login hands back is stamped after that comparison, so a reset landing in+ * between produces a credential that postdates the cutoff and no downstream gate would retire it.+ * Comparing the stamp the authenticating read saw against the stamp the record carries once the+ * credential exists is what orders the two, and it is only meaningful against a read taken after+ * the mint. A record that reports no reset at all is treated as unchanged rather than as evidence,+ * so a lookup that comes back empty cannot lock out a login that nothing has revoked.+ */+export function hasPasswordResetSince(+ seenAt: Date | string | number | null | undefined,+ currentAt: Date | string | number | null | undefined,+): boolean {+ const currentMs = toTimestamp(currentAt);+ if (currentMs == null) {+ return false;+ }++ const seenMs = toTimestamp(seenAt);+ return seenMs == null || currentMs > seenMs;+}++function toTimestamp(value: Date | string | number | null | undefined): number | null {+ if (value == null) {+ return null;+ }++ const ms = new Date(value).getTime();+ return Number.isNaN(ms) ? null : ms;+}++/**+ * Mints a credential that names a user and dates itself to the millisecond.+ *+ * Both credentials minted this way are redeemable without the account password, so both have to be+ * refusable the moment recovery revokes it. `iat` alone cannot do that: it is whole seconds, so a+ * token minted in the same second as the reset is indistinguishable from one minted just before it+ * and would otherwise outlive the credential it was bought with. `issuedAtMs` orders the two.+ */+function generateDatedTwoFactorToken(+ userId: string,+ jwtSecret: string,+ purpose: string,+ expiresIn: jwt.SignOptions['expiresIn'],+): string {+ return jwt.sign({ userId, purpose, issuedAtMs: Date.now() }, jwtSecret, { expiresIn });+}++export function generateTwoFactorSetupToken(userId: string, jwtSecret: string): string {+ return generateDatedTwoFactorToken(+ userId,+ jwtSecret,+ TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_SETUP,+ TWO_FACTOR_SETUP_TOKEN_EXPIRY,+ );+}++export function generateTwoFactorLoginChallengeToken(userId: string, jwtSecret: string): string {+ return generateDatedTwoFactorToken(+ userId,+ jwtSecret,+ TWO_FACTOR_TOKEN_PURPOSE.LOGIN_CHALLENGE,+ TWO_FACTOR_LOGIN_CHALLENGE_TOKEN_EXPIRY,+ );+}++function verifyDatedTwoFactorToken(+ token: string | undefined,+ jwtSecret: string | undefined,+ purpose: string,+): TwoFactorTokenCredential | undefined {+ if (!token || !jwtSecret) {+ return undefined;+ }++ try {+ const payload = jwt.verify(token, jwtSecret);+ if (+ typeof payload !== 'object' ||+ payload.purpose !== purpose ||+ typeof payload.userId !== 'string' ||+ !payload.userId+ ) {+ return undefined;+ }+ return {+ userId: payload.userId,+ issuedAt: payload.iat,+ issuedAtMs: typeof payload.issuedAtMs === 'number' ? payload.issuedAtMs : undefined,+ };+ } catch {+ return undefined;+ }+}++export function verifyTwoFactorLoginChallengeToken(+ tempToken: string | undefined,+ jwtSecret: string | undefined,+): TwoFactorTokenCredential | undefined {+ return verifyDatedTwoFactorToken(tempToken, jwtSecret, TWO_FACTOR_TOKEN_PURPOSE.LOGIN_CHALLENGE);+}++export function generateTwoFactorSetupFinalizationToken(+ userId: string,+ nonce: string,+ jwtSecret: string,+): string {+ return jwt.sign(+ { userId, nonce, purpose: TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_FINALIZATION },+ jwtSecret,+ { expiresIn: TWO_FACTOR_SETUP_FINALIZATION_TOKEN_EXPIRY },+ );+}++export function generateTwoFactorSetupAcknowledgementToken(+ userId: string,+ nonce: string,+ jwtSecret: string,+): string {+ return jwt.sign(+ { userId, nonce, purpose: TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_ACKNOWLEDGEMENT },+ jwtSecret,+ { expiresIn: TWO_FACTOR_SETUP_ACKNOWLEDGEMENT_TOKEN_EXPIRY },+ );+}++function verifyEnrollmentCredential(+ token: string | undefined,+ jwtSecret: string | undefined,+ purpose: string,+): TwoFactorEnrollmentCredential | undefined {+ if (!token || !jwtSecret) {+ return undefined;+ }++ try {+ const payload = jwt.verify(token, jwtSecret);+ if (+ typeof payload !== 'object' ||+ payload.purpose !== purpose ||+ typeof payload.userId !== 'string' ||+ !payload.userId ||+ typeof payload.nonce !== 'string' ||+ !payload.nonce+ ) {+ return undefined;+ }+ return { userId: payload.userId, nonce: payload.nonce };+ } catch {+ return undefined;+ }+}++export function verifyTwoFactorSetupAcknowledgementToken(+ acknowledgementToken: string | undefined,+ jwtSecret: string | undefined,+): TwoFactorEnrollmentCredential | undefined {+ return verifyEnrollmentCredential(+ acknowledgementToken,+ jwtSecret,+ TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_ACKNOWLEDGEMENT,+ );+}++export function verifyTwoFactorSetupFinalizationToken(+ finalizationToken: string | undefined,+ jwtSecret: string | undefined,+): TwoFactorEnrollmentCredential | undefined {+ return verifyEnrollmentCredential(+ finalizationToken,+ jwtSecret,+ TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_FINALIZATION,+ );+}++export function verifyTwoFactorSetupToken(+ tempToken: string | undefined,+ jwtSecret: string | undefined,+): TwoFactorTokenCredential | undefined {+ return verifyDatedTwoFactorToken(tempToken, jwtSecret, TWO_FACTOR_TOKEN_PURPOSE.REQUIRED_SETUP);+}++export interface BlockRetiredSetupTokenDependencies {+ getUserById: (userId: string, projection: string) => Promise<TokenRetirementSignals | null>;+}++/**+ * Refuses a required-enrollment setup token that a later account event has retired.+ *+ * The setup token is the one credential in the enrollment chain carrying no server-side nonce, so+ * nothing else can date it. Password recovery revokes the credential it was minted for and strands+ * the staged enrollment, but a holder of the old credential could otherwise present a setup token+ * from before the reset, stage a secret of their own, and promote it over the recovered account.+ * The later steps are already covered, because recovery clears the nonce hashes they consume.+ *+ * Runs after `requireTwoFactorSetupToken`, which verifies the signature and stamps the request.+ */+export function createBlockRetiredSetupToken(deps: BlockRetiredSetupTokenDependencies) {+ return async (req: Request, res: Response, next: NextFunction): Promise<Response | void> => {+ try {+ const setupRequest = req as TwoFactorEnrollmentRequest;+ const userId = setupRequest.user?.id;+ if (!userId) {+ return res.status(401).json({ message: 'Invalid or expired two-factor setup token' });+ }++ const user = await deps.getUserById(userId, TOKEN_RETIREMENT_FIELDS);+ if (!user) {+ return res.status(401).json({ message: 'Invalid or expired two-factor setup token' });+ }++ if (+ isTokenRetired(+ {+ issuedAt: setupRequest.twoFactorSetupIssuedAt,+ issuedAtMs: setupRequest.twoFactorSetupIssuedAtMs,+ },+ user,+ )+ ) {+ logger.warn(+ `[blockRetiredSetupToken] Setup token predates enrollment or password reset: userId=${userId}`,+ );+ return res.status(401).json({ message: 'Invalid or expired two-factor setup token' });+ }++ next();+ } catch (err) {+ logger.error('[blockRetiredSetupToken]', err);+ return res.status(500).json({ message: 'Something went wrong' });+ }+ };+}++export function requireTwoFactorSetupToken(+ req: Request,+ res: Response,+ next: NextFunction,+): Response | void {+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION)) {+ return res.status(403).json({ message: 'Two-factor authentication setup is not required' });+ }++ const tempToken = (req.body as TwoFactorSetupBody | undefined)?.tempToken;+ const credential = verifyTwoFactorSetupToken(tempToken, process.env.JWT_SECRET);+ if (!credential) {+ return res.status(401).json({ message: 'Invalid or expired two-factor setup token' });+ }++ const setupRequest = req as TwoFactorEnrollmentRequest;+ setupRequest.user = { id: credential.userId };+ setupRequest.twoFactorSetupIssuedAt = credential.issuedAt;+ setupRequest.twoFactorSetupIssuedAtMs = credential.issuedAtMs;+ next();+}++export function requireTwoFactorSetupFinalizationToken(+ req: Request,+ res: Response,+ next: NextFunction,+): Response | void {+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION)) {+ return res.status(403).json({ message: 'Two-factor authentication setup is not required' });+ }++ const finalizationToken = (req.body as TwoFactorSetupBody | undefined)?.finalizationToken;+ const credential = verifyTwoFactorSetupFinalizationToken(+ finalizationToken,+ process.env.JWT_SECRET,+ );+ if (!credential) {+ return res.status(401).json({ message: 'Invalid or expired two-factor finalization token' });+ }++ const setupRequest = req as TwoFactorEnrollmentRequest;+ setupRequest.user = { id: credential.userId };+ setupRequest.twoFactorEnrollmentNonce = credential.nonce;+ next();+}++export function requireTwoFactorSetupAcknowledgementToken(+ req: Request,+ res: Response,+ next: NextFunction,+): Response | void {+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION)) {+ return res.status(403).json({ message: 'Two-factor authentication setup is not required' });+ }++ const acknowledgementToken = (req.body as TwoFactorSetupBody | undefined)?.acknowledgementToken;+ const credential = verifyTwoFactorSetupAcknowledgementToken(+ acknowledgementToken,+ process.env.JWT_SECRET,+ );+ if (!credential) {+ return res.status(401).json({ message: 'Invalid or expired two-factor acknowledgement token' });+ }++ const setupRequest = req as TwoFactorEnrollmentRequest;+ setupRequest.user = { id: credential.userId };+ setupRequest.twoFactorEnrollmentNonce = credential.nonce;+ next();+}++export function blockTwoFactorDisableWhenRequired(+ req: Request,+ res: Response,+ next: NextFunction,+): Response | void {+ if (+ !isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION) ||+ !isTwoFactorPolicyProvider(+ (req.user as Pick<TwoFactorAccount, 'provider'> | undefined)?.provider,+ )+ ) {+ next();+ return;+ }++ return res.status(403).json({+ message: 'Two-factor authentication is required and cannot be disabled',+ });+}++/**+ * Verifies the current pending TOTP secret and stages deliverable backup codes.+ *+ * Nothing is promoted here: `twoFactorEnabled` stays false and the live secret is untouched, so+ * every existing JWT and refresh session remains blocked until finalization. A lost response is+ * safe to retry with the same setup token and a current TOTP; each attempt rotates the pending+ * codes and mints a fresh acknowledgement nonce, invalidating any earlier one.+ */+export async function confirmTwoFactorSetup(+ userId: string,+ token: string | undefined,+ deps: TwoFactorEnrollmentDependencies,+): Promise<TwoFactorConfirmResult> {+ const user = await deps.getUserById(userId, TWO_FACTOR_ENROLLMENT_PROJECTION);+ if (!user || user.twoFactorEnabled || !isTwoFactorSetupEligible(user)) {+ return fail(TWO_FACTOR_SETUP_UNAVAILABLE);+ }+ if (!user.pendingTotpSecret || !user.pendingBackupCodes?.length) {+ return fail(TWO_FACTOR_SETUP_NOT_INITIATED);+ }+ if (!token) {+ return fail(TWO_FACTOR_INVALID_TOKEN);+ }++ const secret = await deps.getTOTPSecret(user.pendingTotpSecret);+ if (!secret) {+ return fail(TWO_FACTOR_SETUP_NOT_INITIATED);+ }+ if (!(await deps.verifyTOTP(secret, token))) {+ return fail(TWO_FACTOR_INVALID_TOKEN);+ }++ const { plainCodes, codeObjects } = await deps.generateBackupCodes();+ const acknowledgementNonce = createEnrollmentNonce();+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION)) {+ return fail(TWO_FACTOR_SETUP_UNAVAILABLE);+ }++ const updatedUser = await deps.updateTwoFactorEnrollment(+ userId,+ {+ pendingTotpSecret: user.pendingTotpSecret,+ pendingBackupCodes: user.pendingBackupCodes,+ },+ {+ pendingBackupCodes: codeObjects,+ twoFactorAcknowledgementNonceHash: hashEnrollmentNonce(acknowledgementNonce),+ twoFactorFinalizationNonceHash: null,+ },+ );+ if (!updatedUser) {+ return fail(TWO_FACTOR_SETUP_UNAVAILABLE);+ }++ return { ok: true, user: updatedUser, plainCodes, acknowledgementNonce };+}++/**+ * Consumes the acknowledgement nonce the user was handed with their backup codes and issues a+ * finalization nonce in its place. Still no promotion and still no session.+ */+export async function acknowledgeTwoFactorSetup(+ userId: string,+ acknowledgementNonce: string | undefined,+ deps: TwoFactorEnrollmentDependencies,+): Promise<TwoFactorAcknowledgeResult> {+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION)) {+ return fail(TWO_FACTOR_SETUP_UNAVAILABLE);+ }+ if (!acknowledgementNonce) {+ return fail(TWO_FACTOR_SETUP_STALE);+ }++ const finalizationNonce = createEnrollmentNonce();+ const updatedUser = await deps.updateTwoFactorEnrollment(+ userId,+ { twoFactorAcknowledgementNonceHash: hashEnrollmentNonce(acknowledgementNonce) },+ {+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: hashEnrollmentNonce(finalizationNonce),+ },+ );+ if (!updatedUser) {+ return fail(TWO_FACTOR_SETUP_STALE);+ }++ return { ok: true, user: updatedUser, finalizationNonce };+}++/**+ * The only step that promotes. It consumes the finalization nonce, the exact pending secret, and+ * the exact pending backup-code snapshot in one compare-and-swap, after revalidating deployment+ * policy and provider eligibility. A replayed credential finds no nonce and writes nothing.+ */+export async function finalizeTwoFactorSetup(+ userId: string,+ finalizationNonce: string | undefined,+ deps: TwoFactorEnrollmentDependencies,+): Promise<TwoFactorFinalizeResult> {+ if (!finalizationNonce) {+ return fail(TWO_FACTOR_SETUP_STALE);+ }++ const user = await deps.getUserById(userId, TWO_FACTOR_ENROLLMENT_PROJECTION);+ if (!user || user.twoFactorEnabled || !isTwoFactorSetupEligible(user)) {+ return fail(TWO_FACTOR_SETUP_UNAVAILABLE);+ }+ if (!user.pendingTotpSecret || !user.pendingBackupCodes?.length) {+ return fail(TWO_FACTOR_SETUP_NOT_INITIATED);+ }+ if (!isEnabled(process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION)) {+ return fail(TWO_FACTOR_SETUP_UNAVAILABLE);+ }++ const updatedUser = await deps.updateTwoFactorEnrollment(+ userId,+ {+ pendingTotpSecret: user.pendingTotpSecret,+ pendingBackupCodes: user.pendingBackupCodes,+ twoFactorFinalizationNonceHash: hashEnrollmentNonce(finalizationNonce),+ },+ {+ totpSecret: user.pendingTotpSecret,+ backupCodes: user.pendingBackupCodes,+ twoFactorEnabled: true,+ twoFactorEnrolledAt: new Date(),+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ },+ );+ if (!updatedUser) {+ return fail(TWO_FACTOR_SETUP_STALE);+ }++ return { ok: true, user: updatedUser };+}diff --git a/packages/api/src/auth/user.spec.ts b/packages/api/src/auth/user.spec.tsnew file mode 100644index 0000000000..929921b902--- /dev/null+++ b/packages/api/src/auth/user.spec.ts@@ -0,0 +1,72 @@+import type { IUser } from '@librechat/data-schemas';+import { PUBLIC_USER_RESPONSE_FIELDS, sanitizeUserForResponse } from './user';++describe('sanitizeUserForResponse', () => {+ const publicFields = {+ _id: 'user-1',+ email: '[email protected]',+ name: 'Test User',+ provider: 'local',+ role: 'USER',+ twoFactorEnabled: true,+ };++ it('keeps the fields a client is allowed to receive', () => {+ expect(sanitizeUserForResponse(publicFields as unknown as IUser)).toEqual(publicFields);+ });++ /** The queries behind these responses return the whole document, secrets included. */+ it('drops every field outside the allowlist', () => {+ const stored = {+ ...publicFields,+ password: 'password-hash',+ totpSecret: 'encrypted-secret',+ backupCodes: [{ codeHash: 'hash', used: false }],+ refreshToken: [{ refreshToken: 'live-session-token' }],+ federatedTokens: [{ provider: 'openid', accessToken: 'token' }],+ pendingTotpSecret: 'staged-secret',+ pendingBackupCodes: [{ codeHash: 'staged', used: false }],+ twoFactorAcknowledgementNonceHash: 'ack-hash',+ twoFactorFinalizationNonceHash: 'final-hash',+ twoFactorEnrolledAt: new Date(),+ __v: 0,+ };++ expect(sanitizeUserForResponse(stored as unknown as IUser)).toEqual(publicFields);+ });++ /** A field added to the schema later must stay out until it is named here deliberately. */+ it('drops a field the allowlist has never heard of', () => {+ const stored = { ...publicFields, someFieldAddedLater: 'sensitive' };++ expect(sanitizeUserForResponse(stored as unknown as IUser)).not.toHaveProperty(+ 'someFieldAddedLater',+ );+ });++ it('reads through a hydrated document', () => {+ const hydrated = {+ toObject: () => ({ ...publicFields, password: 'password-hash' }),+ };++ expect(sanitizeUserForResponse(hydrated)).toEqual(publicFields);+ });++ it('omits allowlisted fields the document does not carry', () => {+ const sanitized = sanitizeUserForResponse({ _id: 'user-1' } as unknown as IUser);++ expect(sanitized).toEqual({ _id: 'user-1' });+ expect(sanitized).not.toHaveProperty('email');+ });++ it('returns an empty object for a missing user', () => {+ expect(sanitizeUserForResponse(null)).toEqual({});+ expect(sanitizeUserForResponse(undefined)).toEqual({});+ });++ it('never names a credential field in the allowlist', () => {+ for (const field of ['password', 'totpSecret', 'backupCodes', 'refreshToken']) {+ expect(PUBLIC_USER_RESPONSE_FIELDS).not.toContain(field);+ }+ });+});diff --git a/packages/api/src/auth/user.ts b/packages/api/src/auth/user.tsnew file mode 100644index 0000000000..aa9203334d--- /dev/null+++ b/packages/api/src/auth/user.ts@@ -0,0 +1,61 @@+import type { TwoFactorAccount } from './twoFactor';++/**+ * Everything an authentication response may say about a user.+ *+ * An allowlist rather than a denylist, because the queries behind these responses do not reliably+ * project: a `select()` built only from `+field` tokens leaves Mongoose with no projection to send,+ * so the full stored document comes back, secrets and session records included. Subtracting known+ * secrets from that would silently leak every field added to the schema afterwards.+ */+export const PUBLIC_USER_RESPONSE_FIELDS = [+ '_id',+ 'id',+ 'name',+ 'username',+ 'email',+ 'emailVerified',+ 'avatar',+ 'provider',+ 'role',+ 'plugins',+ 'twoFactorEnabled',+ 'termsAccepted',+ 'personalization',+ 'favorites',+ 'skillStates',+ 'createdAt',+ 'updatedAt',+ 'tenantId',+] as const;++type PublicUserField = (typeof PUBLIC_USER_RESPONSE_FIELDS)[number];+export type PublicUser = Partial<Record<PublicUserField, unknown>>;++interface HydratedUser {+ toObject?: () => Record<string, unknown>;+}++/** Reduces a user document, hydrated or lean, to the fields a client is allowed to receive. */+export function sanitizeUserForResponse(+ user: TwoFactorAccount | HydratedUser | null | undefined,+): PublicUser {+ if (user == null) {+ return {};+ }++ const source = (+ typeof (user as HydratedUser).toObject === 'function'+ ? (user as HydratedUser).toObject?.()+ : user+ ) as Record<string, unknown>;++ const publicUser: PublicUser = {};+ for (const field of PUBLIC_USER_RESPONSE_FIELDS) {+ if (source[field] !== undefined) {+ publicUser[field] = source[field];+ }+ }++ return publicUser;+}diff --git a/packages/api/src/auth/userDocCache.ts b/packages/api/src/auth/userDocCache.tsindex 4fa91a4772..9ae331ec25 100644--- a/packages/api/src/auth/userDocCache.ts+++ b/packages/api/src/auth/userDocCache.ts@@ -131,6 +131,8 @@ function sanitizeUserForCache(user: Partial<IUser>): CachedAuthUser {delete sanitized.pendingTotpSecret;delete sanitized.backupCodes;delete sanitized.pendingBackupCodes;+ delete sanitized.twoFactorAcknowledgementNonceHash;+ delete sanitized.twoFactorFinalizationNonceHash;delete sanitized.federatedTokens;delete sanitized.openidTokens;diff --git a/packages/api/src/images/authorization.spec.ts b/packages/api/src/images/authorization.spec.tsindex 8f68909b8d..2c24a445ac 100644--- a/packages/api/src/images/authorization.spec.ts+++ b/packages/api/src/images/authorization.spec.ts@@ -69,11 +69,20 @@ function signOpenIdUser(userId: string, refreshToken: string): string {}describe('createImageAuthorizationMiddleware', () => {+ const originalEnforcement = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ afterAll(() => {+ if (originalEnforcement === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalEnforcement;+ }+ });let deps: ImageAuthorizationDeps;let response: Response;let next: jest.MockedFunction<NextFunction>;beforeEach(() => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'false';process.env.JWT_REFRESH_SECRET = 'image-authorization-secret';deps = createDeps();response = createResponse();@@ -94,6 +103,130 @@ describe('createImageAuthorizationMiddleware', () => {expect(deps.findSession).toHaveBeenCalledWith({ userId: VIEWER_ID, refreshToken: token });});+ describe('required enrollment and credential retirement', () => {+ const originalEnforcement = process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;++ afterEach(() => {+ if (originalEnforcement === undefined) {+ delete process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION;+ } else {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = originalEnforcement;+ }+ });++ it.each(['local', 'ldap', undefined])(+ 'refuses an unenrolled %s viewer without an extra owner read',+ async (provider) => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ (deps.getUserById as jest.Mock).mockResolvedValue({ provider, twoFactorEnabled: false });+ const middleware = createImageAuthorizationMiddleware({}, deps);++ await middleware(+ createRequest(`/images/${VIEWER_ID}/private.png`, `refreshToken=${signUser(VIEWER_ID)}`),+ response,+ next,+ );++ expect(next).not.toHaveBeenCalled();+ expect(response.status).toHaveBeenCalledWith(403);+ expect(deps.getUserById).toHaveBeenCalledTimes(1);+ },+ );++ it.each(['local', 'openid', 'legacy-openid'])(+ 'dates a %s credential against both account cutoffs',+ async (kind) => {+ const issuedAtMs = Date.now();+ const refreshToken =+ kind === 'local'+ ? jwt.sign({ id: VIEWER_ID, issuedAtMs }, process.env.JWT_REFRESH_SECRET as string, {+ expiresIn: '1h',+ })+ : 'provider-refresh';+ const marker = jwt.sign(+ {+ id: VIEWER_ID,+ issuedAtMs,+ ...(kind === 'openid'+ ? { refreshTokenHash: createHash('sha256').update(refreshToken).digest('base64url') }+ : {}),+ },+ process.env.JWT_REFRESH_SECRET as string,+ { expiresIn: '1h' },+ );+ (deps.isOpenIdReuseEnabled as jest.Mock).mockReturnValue(kind !== 'local');+ const cookie =+ kind === 'local'+ ? `refreshToken=${refreshToken}`+ : `refreshToken=${refreshToken}; token_provider=openid; openid_user_id=${marker}`;+ const req = Object.assign(createRequest(`/images/${VIEWER_ID}/private.png`, cookie), {+ session: { openidTokens: { refreshToken } },+ });+ const middleware = createImageAuthorizationMiddleware({}, deps);++ for (const field of ['twoFactorEnrolledAt', 'credentialsChangedAt']) {+ (deps.getUserById as jest.Mock).mockResolvedValue({+ [field]: new Date(issuedAtMs + 1),+ twoFactorEnabled: true,+ });+ await middleware(req, response, next);+ expect(next).not.toHaveBeenCalled();+ expect(response.status).toHaveBeenCalledWith(403);+ }+ (deps.getUserById as jest.Mock).mockResolvedValue({+ twoFactorEnrolledAt: new Date(issuedAtMs - 1),+ credentialsChangedAt: new Date(issuedAtMs - 1),+ twoFactorEnabled: true,+ });+ await middleware(req, response, next);+ expect(next).toHaveBeenCalledTimes(1);+ },+ );++ it('checks the authenticated viewer rather than the image owner and preserves public access', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ (deps.getUserById as jest.Mock).mockImplementation(async (id: string) => ({+ role: 'USER',+ tenantId: 'tenant-a',+ provider: 'local',+ twoFactorEnabled: id === OWNER_ID,+ }));+ (deps.getAgent as jest.Mock).mockResolvedValue({ _id: AGENT_DB_ID });+ (deps.hasPermission as jest.Mock).mockResolvedValue(false);+ const middleware = createImageAuthorizationMiddleware({}, deps);+ const req = createRequest(AGENT_PATH, `refreshToken=${signUser(VIEWER_ID)}`);+ await middleware(req, response, next);+ expect(next).not.toHaveBeenCalled();+ expect(deps.getUserPrincipals).not.toHaveBeenCalled();+ expect(deps.getUserById).toHaveBeenCalledTimes(2);++ (deps.hasPermission as jest.Mock).mockResolvedValue(true);+ await middleware(req, response, next);+ expect(next).toHaveBeenCalledTimes(1);+ expect(deps.hasPermission).toHaveBeenLastCalledWith(+ [{ principalType: 'public' }],+ expect.anything(),+ AGENT_DB_ID,+ expect.anything(),+ );+ });++ it('keeps federated users exempt from the enrollment policy', async () => {+ process.env.ENFORCE_TWO_FACTOR_AUTHENTICATION = 'true';+ (deps.getUserById as jest.Mock).mockResolvedValue({+ provider: 'openid',+ twoFactorEnabled: false,+ });+ const middleware = createImageAuthorizationMiddleware({}, deps);+ await middleware(+ createRequest(`/images/${VIEWER_ID}/private.png`, `refreshToken=${signUser(VIEWER_ID)}`),+ response,+ next,+ );+ expect(next).toHaveBeenCalledTimes(1);+ });+ });+it('rejects a signed refresh token whose session was revoked', async () => {(deps.findSession as jest.Mock).mockResolvedValue(null);const token = signUser(VIEWER_ID);@@ -368,9 +501,9 @@ describe('createImageAuthorizationMiddleware', () => {expect(deps.getUserById).toHaveBeenNthCalledWith(1,OWNER_ID,- 'role tenantId idOnTheSource avatar',+ 'role tenantId idOnTheSource avatar provider twoFactorEnabled twoFactorEnrolledAt credentialsChangedAt',);- expect(deps.getUserById).toHaveBeenNthCalledWith(2, VIEWER_ID, 'tenantId');+ expect(deps.getUserById).toHaveBeenCalledTimes(2);});it('denies the stored user avatar to a viewer from another tenant', async () => {diff --git a/packages/api/src/images/authorization.ts b/packages/api/src/images/authorization.tsindex 20f0b5cb09..78170b9a81 100644--- a/packages/api/src/images/authorization.ts+++ b/packages/api/src/images/authorization.ts@@ -11,17 +11,27 @@ import {import type { IAgent, IAssistant, AssistantQuery, SystemCapability } from '@librechat/data-schemas';import type { Request, Response, NextFunction, RequestHandler } from 'express';import type { FilterQuery, ProjectionType, Types } from 'mongoose';+import type { TokenIssuance, TwoFactorAccount, TwoFactorTokenCredential } from '~/auth/twoFactor';+import {+ isTokenRetired,+ isTwoFactorEnrollmentRequired,+ TOKEN_RETIREMENT_FIELDS,+} from '~/auth/twoFactor';const MAX_URL_LENGTH = 2048;const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/i;const AGENT_AVATAR_PATTERN = /^agent-(.+)-avatar-\d+\.[^/]+$/;+const IMAGE_USER_PROJECTION = `role tenantId idOnTheSource avatar provider twoFactorEnabled ${TOKEN_RETIREMENT_FIELDS}`;type Principal = {principalType: PrincipalType;principalId?: string | Types.ObjectId;};-type ImageUser = {+type ImageUser = Pick<+ TwoFactorAccount,+ 'provider' | 'twoFactorEnabled' | 'twoFactorEnrolledAt' | 'credentialsChangedAt'+> & {role?: string | null;tenantId?: string;idOnTheSource?: string | null;@@ -54,12 +64,12 @@ type ResolvedImageConfig = {type CookieAuthResult =| { status: 'missing' }| { status: 'invalid' }- | { status: 'authenticated'; userId: string };+ | ({ status: 'authenticated' } & TwoFactorTokenCredential);type OpenIdCookieAuthResult =| { status: 'invalid' }- | { status: 'legacy'; userId: string }- | { status: 'authenticated'; userId: string };+ | ({ status: 'legacy'; userId: string } & TokenIssuance)+ | ({ status: 'authenticated'; userId: string } & TokenIssuance);export interface ImageAuthorizationDeps {parseCookies: (cookieHeader: string) => Record<string, string | undefined>;@@ -159,14 +169,16 @@ function parseImagePath(originalUrl: string, basePath: string): ImagePath | null};}-function getSignedUserId(token: string | undefined): string | null {+function getSignedCredential(token: string | undefined): TwoFactorTokenCredential | null {const secret = process.env.JWT_REFRESH_SECRET;if (!token || !secret) {return null;}try {const payload = jwt.verify(token, secret) as JwtPayload;- return typeof payload.id === 'string' && OBJECT_ID_PATTERN.test(payload.id) ? payload.id : null;+ return typeof payload.id === 'string' && OBJECT_ID_PATTERN.test(payload.id)+ ? { userId: payload.id, issuedAt: payload.iat, issuedAtMs: payload.issuedAtMs }+ : null;} catch (error) {logger.warn('[imageAuthorization] Invalid signed user token', error);return null;@@ -187,11 +199,21 @@ function getSignedOpenIdUserId(return { status: 'invalid' };}if (typeof payload.refreshTokenHash !== 'string') {- return { status: 'legacy', userId: payload.id };+ return {+ status: 'legacy',+ userId: payload.id,+ issuedAt: payload.iat,+ issuedAtMs: payload.issuedAtMs,+ };}const refreshTokenHash = createHash('sha256').update(refreshToken).digest('base64url');return payload.refreshTokenHash === refreshTokenHash- ? { status: 'authenticated', userId: payload.id }+ ? {+ status: 'authenticated',+ userId: payload.id,+ issuedAt: payload.iat,+ issuedAtMs: payload.issuedAtMs,+ }: { status: 'invalid' };} catch (error) {logger.warn('[imageAuthorization] Invalid signed OpenID user token', error);@@ -231,7 +253,7 @@ async function authenticateRequest(}if (openIdAuth.status === 'legacy') {return refreshToken === req.session?.openidTokens?.refreshToken- ? { status: 'authenticated', userId: openIdAuth.userId }+ ? { ...openIdAuth, status: 'authenticated' }: { status: 'invalid' };}const session = await runAsSystem(() =>@@ -240,12 +262,14 @@ async function authenticateRequest(return session ? openIdAuth : { status: 'invalid' };}- const userId = getSignedUserId(refreshToken);- if (!userId) {+ const credential = getSignedCredential(refreshToken);+ if (!credential) {return { status: 'invalid' };}- const session = await runAsSystem(() => deps.findSession({ userId, refreshToken }));- return session ? { status: 'authenticated', userId } : { status: 'invalid' };+ const session = await runAsSystem(() =>+ deps.findSession({ userId: credential.userId, refreshToken }),+ );+ return session ? { status: 'authenticated', ...credential } : { status: 'invalid' };}function isSharedAssistant(assistant: AssistantImageRecord, configs: AssistantConfig[]): boolean {@@ -285,6 +309,7 @@ async function loadPrincipals(async function canViewAgentAvatar(imagePath: ImagePath,viewerId: string | undefined,+ viewer: ImageUser | null,owner: ImageUser,deps: ImageAuthorizationDeps,): Promise<boolean> {@@ -304,7 +329,6 @@ async function canViewAgentAvatar(return deps.hasPermission(publicPrincipal, ResourceType.AGENT, agent._id, PermissionBits.VIEW);}- const viewer = await runAsSystem(() => deps.getUserById(viewerId, 'role tenantId idOnTheSource'));if (!viewer || viewer.tenantId !== owner.tenantId) {return deps.hasPermission(publicPrincipal, ResourceType.AGENT, agent._id, PermissionBits.VIEW);}@@ -329,6 +353,7 @@ async function canViewAgentAvatar(async function canViewAssistantAvatar(imagePath: ImagePath,viewerId: string | undefined,+ viewer: ImageUser | null,owner: ImageUser,configs: AssistantConfig[],deps: ImageAuthorizationDeps,@@ -344,7 +369,6 @@ async function canViewAssistantAvatar(return false;}- const viewer = await runAsSystem(() => deps.getUserById(viewerId, 'role tenantId idOnTheSource'));if (!viewer || viewer.tenantId !== owner.tenantId) {return false;}@@ -401,18 +425,6 @@ function isStoredUserAvatar(return storedAvatar?.canonicalPath === imagePath.canonicalPath;}-async function canViewUserAvatar(- viewerId: string | undefined,- owner: ImageUser,- deps: ImageAuthorizationDeps,-): Promise<boolean> {- if (!viewerId) {- return false;- }- const viewer = await runAsSystem(() => deps.getUserById(viewerId, 'tenantId'));- return viewer != null && viewer.tenantId === owner.tenantId;-}-function denyRequest(res: Response, auth: CookieAuthResult): void {if (auth.status === 'missing') {res.status(401).send('Unauthorized');@@ -447,7 +459,7 @@ export function createImageAuthorizationMiddleware(}const owner = await runAsSystem(() =>- deps.getUserById(imagePath.ownerId, 'role tenantId idOnTheSource avatar'),+ deps.getUserById(imagePath.ownerId, IMAGE_USER_PROJECTION),);if (!owner) {if (options.secureImageLinks === false) {@@ -475,7 +487,19 @@ export function createImageAuthorizationMiddleware(}res.locals.privateImageCache = true;- const auth = await authPromise;+ let auth = await authPromise;+ let viewer: ImageUser | null = null;+ if (auth.status === 'authenticated') {+ const { userId } = auth;+ viewer =+ userId === imagePath.ownerId+ ? owner+ : await runAsSystem(() => deps.getUserById(userId, IMAGE_USER_PROJECTION));+ if (!viewer || isTokenRetired(auth, viewer) || isTwoFactorEnrollmentRequired(viewer)) {+ auth = { status: 'invalid' };+ viewer = null;+ }+ }const viewerId = auth.status === 'authenticated' ? auth.userId : undefined;if (viewerId === imagePath.ownerId) {next();@@ -484,15 +508,16 @@ export function createImageAuthorizationMiddleware(const authorizeSpecialAvatar = async (): Promise<boolean> => {if (imagePath.agentId) {- return canViewAgentAvatar(imagePath, viewerId, owner, deps);+ return canViewAgentAvatar(imagePath, viewerId, viewer, owner, deps);}if (isStoredUserAvatar(imagePath, owner, deps)) {- return canViewUserAvatar(viewerId, owner, deps);+ return viewer != null && viewer.tenantId === owner.tenantId;}if (imageConfig.assistantEndpoints.length > 0) {const canViewAssistant = await canViewAssistantAvatar(imagePath,viewerId,+ viewer,owner,imageConfig.assistantEndpoints,deps,diff --git a/packages/api/src/oauth/csrf.spec.ts b/packages/api/src/oauth/csrf.spec.tsindex 5fb21a886a..b512ff4735 100644--- a/packages/api/src/oauth/csrf.spec.ts+++ b/packages/api/src/oauth/csrf.spec.ts@@ -222,7 +222,10 @@ describe('setOpenIDMarkerCookies', () => {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' });+ expect(jwt.verify(signedUserId, 'marker-secret')).toMatchObject({+ id: 'user-123',+ issuedAtMs: expect.any(Number),+ });});/** Preserves the marker's binding to the durable refresh-token session: a marker signed for one@@ -244,6 +247,7 @@ describe('setOpenIDMarkerCookies', () => {expect(jwt.verify(signedUserId, 'marker-secret')).toMatchObject({id: 'user-123',refreshTokenHash: crypto.createHash('sha256').update('the-refresh-token').digest('base64url'),+ issuedAtMs: expect.any(Number),});});diff --git a/packages/api/src/oauth/csrf.ts b/packages/api/src/oauth/csrf.tsindex 4df6b1498f..08dd0bdf2e 100644--- a/packages/api/src/oauth/csrf.ts+++ b/packages/api/src/oauth/csrf.ts@@ -118,7 +118,7 @@ export function setOpenIDMarkerCookies(? crypto.createHash('sha256').update(refreshToken).digest('base64url'): undefined;const signedUserId = jwt.sign(- refreshTokenHash ? { id: userId, refreshTokenHash } : { id: userId },+ { id: userId, issuedAtMs: Date.now(), ...(refreshTokenHash ? { refreshTokenHash } : {}) },secret,{ expiresIn: refreshExpirySeconds },);diff --git a/packages/data-provider/specs/api-endpoints.spec.ts b/packages/data-provider/specs/api-endpoints.spec.tsindex 415206e09b..cbc97a927e 100644--- a/packages/data-provider/specs/api-endpoints.spec.ts+++ b/packages/data-provider/specs/api-endpoints.spec.ts@@ -6,6 +6,10 @@ import {buildLoginRedirectUrl,getSharedLinks,agentQueuedTurnsByConversation,+ enableTwoFactorSetup,+ confirmTwoFactorSetup,+ acknowledgeTwoFactorSetup,+ finalizeTwoFactorSetup,} from '../src/api-endpoints';describe('buildLoginRedirectUrl', () => {@@ -117,3 +121,12 @@ describe('agent queued turns', () => {expect(agentQueuedTurn('turn/a b')).toBe('/api/agents/chat/queued-turns/turn%2Fa%20b');});});++describe('required two-factor setup endpoints', () => {+ it('uses the purpose-specific setup paths', () => {+ expect(enableTwoFactorSetup()).toBe('/api/auth/2fa/setup');+ expect(confirmTwoFactorSetup()).toBe('/api/auth/2fa/setup/confirm');+ expect(acknowledgeTwoFactorSetup()).toBe('/api/auth/2fa/setup/acknowledge');+ expect(finalizeTwoFactorSetup()).toBe('/api/auth/2fa/setup/finalize');+ });+});diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.tsindex 16d2b05311..f520e8ffd8 100644--- a/packages/data-provider/src/api-endpoints.ts+++ b/packages/data-provider/src/api-endpoints.ts@@ -585,6 +585,10 @@ export const feedback = (conversationId: string, messageId: string) =>// Two-Factor Endpointsexport const enableTwoFactor = () => `${BASE_URL}/api/auth/2fa/enable`;+export const enableTwoFactorSetup = () => `${BASE_URL}/api/auth/2fa/setup`;+export const confirmTwoFactorSetup = () => `${BASE_URL}/api/auth/2fa/setup/confirm`;+export const acknowledgeTwoFactorSetup = () => `${BASE_URL}/api/auth/2fa/setup/acknowledge`;+export const finalizeTwoFactorSetup = () => `${BASE_URL}/api/auth/2fa/setup/finalize`;export const verifyTwoFactor = () => `${BASE_URL}/api/auth/2fa/verify`;export const confirmTwoFactor = () => `${BASE_URL}/api/auth/2fa/confirm`;export const disableTwoFactor = () => `${BASE_URL}/api/auth/2fa/disable`;diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.tsindex fbfd629f63..0b8d43e383 100644--- a/packages/data-provider/src/config.spec.ts+++ b/packages/data-provider/src/config.spec.ts@@ -23,6 +23,7 @@ import {resolveMCPAppRateLimits,resolveMCPAppsPolicy,endpointSchema,+ isTwoFactorPolicyProvider,resolveEndpointType,webSearchSchema,} from './config';@@ -386,6 +387,16 @@ describe('scheduled MCP preflight config', () => {});});+describe('isTwoFactorPolicyProvider', () => {+ it.each(['local', 'ldap', null, undefined])('includes provider %s', (provider) => {+ expect(isTwoFactorPolicyProvider(provider)).toBe(true);+ });++ it.each(['openid', 'google', 'saml'])('excludes federated provider %s', (provider) => {+ expect(isTwoFactorPolicyProvider(provider)).toBe(false);+ });+});+describe('excludedKeys', () => {it.each(['_id',diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 8cb0a15cca..597caeb977 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -75,6 +75,18 @@ export {export const defaultSocialLogins = ['google', 'facebook', 'openid', 'github', 'discord', 'saml'];+export const TWO_FACTOR_ENROLLMENT_REQUIRED_CODE = 'TWO_FACTOR_ENROLLMENT_REQUIRED' as const;++/** A federated record was refused a password login, so the only way in is its identity provider. */+export const TWO_FACTOR_FEDERATED_LOGIN_BLOCKED_CODE =+ 'TWO_FACTOR_FEDERATED_LOGIN_BLOCKED' as const;++const TWO_FACTOR_POLICY_PROVIDERS = new Set(['local', 'ldap']);++export function isTwoFactorPolicyProvider(provider: string | null | undefined): boolean {+ return provider == null || TWO_FACTOR_POLICY_PROVIDERS.has(provider);+}+/** How long a started social login may take to return to its callback before its `state` expires. */export const DEFAULT_OAUTH_STATE_TTL_MS = 10 * 60 * 1000;@@ -2863,6 +2875,7 @@ export type TStartupConfig = {registrationEnabled: boolean;socialLoginEnabled: boolean;passwordResetEnabled: boolean;+ twoFactorAuthenticationRequired?: boolean;emailEnabled: boolean;allowEmailChange: boolean;showBirthdayIcon: boolean;diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.tsindex 455c805c0a..08b89f7c1d 100644--- a/packages/data-provider/src/data-service.ts+++ b/packages/data-provider/src/data-service.ts@@ -1607,6 +1607,30 @@ export function enableTwoFactor(payload?: t.TEnable2FARequest): Promise<t.TEnablreturn request.post(endpoints.enableTwoFactor(), payload);}+export function enableTwoFactorSetup(+ payload: t.TEnable2FASetupRequest,+): Promise<t.TEnable2FAResponse> {+ return request.post(endpoints.enableTwoFactorSetup(), payload);+}++export function confirmTwoFactorSetup(+ payload: t.TConfirm2FASetupRequest,+): Promise<t.TConfirm2FASetupResponse> {+ return request.post(endpoints.confirmTwoFactorSetup(), payload);+}++export function acknowledgeTwoFactorSetup(+ payload: t.TAcknowledge2FASetupRequest,+): Promise<t.TAcknowledge2FASetupResponse> {+ return request.post(endpoints.acknowledgeTwoFactorSetup(), payload);+}++export function finalizeTwoFactorSetup(+ payload: t.TFinalize2FASetupRequest,+): Promise<t.TFinalize2FASetupResponse> {+ return request.post(endpoints.finalizeTwoFactorSetup(), payload);+}+export function verifyTwoFactor(payload: t.TVerify2FARequest): Promise<t.TVerify2FAResponse> {return request.post(endpoints.verifyTwoFactor(), payload);}diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.tsindex 592c6a5ede..04c3883ff2 100644--- a/packages/data-provider/src/index.ts+++ b/packages/data-provider/src/index.ts@@ -77,6 +77,7 @@ export * from './svg';/* general helpers */export * from './utils';export * from './actions';+export * from './twoFactor';export { default as createPayload } from './createPayload';// /* react query hooks */// export * from './react-query/react-query-service';diff --git a/packages/data-provider/src/request.spec.ts b/packages/data-provider/src/request.spec.tsnew file mode 100644index 0000000000..0175af45fb--- /dev/null+++ b/packages/data-provider/src/request.spec.ts@@ -0,0 +1,147 @@+/**+ * @jest-environment jsdom+ */+import { readTwoFactorSetupToken, clearTwoFactorSetupToken } from './twoFactor';+import { getTokenHeader, setTokenHeader } from './headers-helpers';+import { TWO_FACTOR_ENROLLMENT_REQUIRED_CODE } from './config';+import request from './request';++interface AuthRecoveryWindow extends Window {+ __librechatAuthRecovery?: unknown;+}++const enrollmentBody = {+ code: TWO_FACTOR_ENROLLMENT_REQUIRED_CODE,+ twoFAPending: true,+ twoFASetupRequired: true,+ tempToken: 'setup-token',+};++const blockStorage = () =>+ jest.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {+ throw new Error('storage blocked');+ });++describe('two-factor enrollment responses outside the interceptors', () => {+ let pushState: jest.SpyInstance;+ let redirectEvents: CustomEvent<{ href: string; inDocument: boolean }>[];++ const captureRedirectEvent = (event: Event) => {+ redirectEvents.push(event as CustomEvent<{ href: string; inDocument: boolean }>);+ };++ beforeEach(() => {+ window.localStorage.clear();+ window.sessionStorage.clear();+ clearTwoFactorSetupToken();+ setTokenHeader(undefined);+ delete (window as AuthRecoveryWindow).__librechatAuthRecovery;+ window.history.pushState(null, '', '/c/new');+ pushState = jest.spyOn(window.history, 'pushState');+ redirectEvents = [];+ window.addEventListener('authRedirectStarted', captureRedirectEvent);+ });++ afterEach(() => {+ window.removeEventListener('authRedirectStarted', captureRedirectEvent);+ jest.restoreAllMocks();+ });++ it('opens setup from a parsed enrollment body', () => {+ expect(request.redirectIfTwoFactorSetupPayload(enrollmentBody)).toBe(true);+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ /** Stream transports hand over the raw body, so the helper has to parse it itself. */+ it('opens setup from an enrollment body that arrives as text', () => {+ expect(request.redirectIfTwoFactorSetupPayload(JSON.stringify(enrollmentBody))).toBe(true);+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ it('ignores a 403 body that is not an enrollment response', () => {+ expect(request.redirectIfTwoFactorSetupPayload({ message: 'Forbidden' })).toBe(false);+ expect(readTwoFactorSetupToken()).toBe('');+ expect(pushState).not.toHaveBeenCalled();+ });++ it('ignores a body that is not JSON at all', () => {+ expect(request.redirectIfTwoFactorSetupPayload('<html>gateway</html>')).toBe(false);+ expect(readTwoFactorSetupToken()).toBe('');+ expect(pushState).not.toHaveBeenCalled();+ });++ it('ignores an enrollment body with no usable token', () => {+ expect(request.redirectIfTwoFactorSetupPayload({ ...enrollmentBody, tempToken: ' ' })).toBe(+ false,+ );+ expect(pushState).not.toHaveBeenCalled();+ });++ /**+ * Session storage outlives the document, so the redirect may replace it and clear the app state+ * along the way. Routing in place here would leave that stale state behind.+ */+ it('replaces the document when the token reached durable storage', () => {+ request.redirectIfTwoFactorSetupPayload(enrollmentBody);++ expect(window.sessionStorage.getItem('two_factor_setup_token')).toBe('setup-token');+ expect(pushState).not.toHaveBeenCalled();+ expect(redirectEvents).toHaveLength(1);+ expect(redirectEvents[0].detail.inDocument).toBe(false);+ });++ /**+ * With storage blocked the in-memory mirror is the only copy, and replacing the document would+ * destroy it, stranding the setup screen on its expired state with no way back.+ */+ it('keeps the document when only the in-memory mirror holds the token', () => {+ const setItem = blockStorage();++ expect(request.redirectIfTwoFactorSetupPayload(enrollmentBody)).toBe(true);++ setItem.mockRestore();+ expect(pushState).toHaveBeenCalledTimes(1);+ expect(window.location.pathname).toBe('/login/2fa/setup');+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ /**+ * The surviving document keeps the app mounted, so the hand-off has to say so: the session it+ * redirects away from is still live and nothing else would tell the app to let it go.+ */+ it('reports the surviving document to the app before routing in place', () => {+ const setItem = blockStorage();++ request.redirectIfTwoFactorSetupPayload(enrollmentBody);++ setItem.mockRestore();+ expect(redirectEvents).toHaveLength(1);+ expect(redirectEvents[0].detail.inDocument).toBe(true);+ expect(redirectEvents[0].detail.href).toContain('/login/2fa/setup');+ });++ it('redirects once while a redirect is already under way', () => {+ const setItem = blockStorage();++ request.redirectIfTwoFactorSetupPayload(enrollmentBody);+ request.redirectIfTwoFactorSetupPayload(enrollmentBody);++ setItem.mockRestore();+ expect(pushState).toHaveBeenCalledTimes(1);+ });++ /**+ * Another tab writes the shared navigation marker first. This tab holds its own setup token and+ * drops its own bearer, so it has to navigate too: without a bearer its 401s skip recovery.+ */+ it('still navigates when another tab already started a redirect', () => {+ window.localStorage.setItem('librechat.auth.redirect.startedAt', String(Date.now()));+ setTokenHeader('retired-bearer');++ expect(request.redirectIfTwoFactorSetupPayload(enrollmentBody)).toBe(true);++ expect(readTwoFactorSetupToken()).toBe('setup-token');+ expect(getTokenHeader()).toBeUndefined();+ expect(redirectEvents).toHaveLength(1);+ });+});diff --git a/packages/data-provider/src/request.ts b/packages/data-provider/src/request.tsindex 4291ae0b0c..acc8473502 100644--- a/packages/data-provider/src/request.ts+++ b/packages/data-provider/src/request.ts@@ -2,6 +2,8 @@import axios from 'axios';import type { AxiosRequestConfig, AxiosResponse } from 'axios';import type * as t from './types';+import { TWO_FACTOR_ENROLLMENT_REQUIRED_CODE } from './config';+import { persistTwoFactorSetupToken } from './twoFactor';import { setTokenHeader } from './headers-helpers';import * as endpoints from './api-endpoints';@@ -188,6 +190,90 @@ const isAuthRedirectInProgress = () => {);};+/** Stream transports surface the body as text, while axios and fetch have already parsed it. */+const parseSetupPayload = (payload: unknown): unknown => {+ if (typeof payload !== 'string') {+ return payload;+ }++ try {+ return JSON.parse(payload);+ } catch {+ return null;+ }+};++const getTwoFactorSetupToken = (payload: unknown): string | null => {+ if (typeof payload !== 'object' || payload == null) {+ return null;+ }++ const response = payload as {+ code?: unknown;+ twoFASetupRequired?: unknown;+ tempToken?: unknown;+ };+ if (+ response.code !== TWO_FACTOR_ENROLLMENT_REQUIRED_CODE ||+ response.twoFASetupRequired !== true ||+ typeof response.tempToken !== 'string' ||+ !response.tempToken.trim()+ ) {+ return null;+ }++ return response.tempToken.trim();+};++/**+ * The setup token and the bearer it replaces are both tab-scoped, so a hand-off another tab+ * started does nothing for this one: once the bearer is dropped, 401s skip recovery and the tab+ * would stay on the app until reloaded. Only this tab's own navigation dedupes the hand-off.+ */+const isTabRedirectInProgress = () => {+ const startedAt = getAuthRecoveryState().lastRedirectStartedAt;+ return startedAt > 0 && Date.now() - startedAt < AUTH_REDIRECT_DEDUPE_MS;+};++const redirectToTwoFactorSetupOnce = (tempToken: string) => {+ const isDurable = persistTwoFactorSetupToken(tempToken);+ setTokenHeader(undefined);+ if (isTabRedirectInProgress()) {+ return;+ }++ const loginRedirect = endpoints.buildLoginRedirectUrl();+ const redirectTo = new URL(loginRedirect, window.location.origin).searchParams.get('redirect_to');+ const searchParams = new URLSearchParams();+ if (redirectTo) {+ searchParams.set('redirect_to', redirectTo);+ }+ const query = searchParams.toString();++ const href = `${endpoints.apiBaseUrl()}/login/2fa/setup${query ? `?${query}` : ''}`;+ setAuthRedirectStartedAt();+ window.dispatchEvent(+ new CustomEvent(AUTH_REDIRECT_EVENT, { detail: { href, inDocument: !isDurable } }),+ );+ if (isDurable) {+ window.location.href = href;+ return;+ }++ /**+ * Session storage refused the token, so only the in-memory mirror holds it and replacing the+ * document would throw it away, stranding the setup screen on its expired state. Move the router+ * instead: the history entry is the same one the hard navigation would have produced, and the+ * router picks it up either from this event or, if it has yet to mount, from the location.+ *+ * The document surviving is also why the event above reports the hand-off as in-document: the+ * session this redirect replaces would otherwise live on in whatever state the app already+ * holds, which a replaced document would have discarded.+ */+ window.history.pushState(null, '', href);+ window.dispatchEvent(new PopStateEvent('popstate'));+};+const dispatchAuthRecoveryEvent = (state: 'started' | 'finished') => {window.dispatchEvent(new CustomEvent(AUTH_RECOVERY_EVENT, { detail: { state } }));};@@ -212,6 +298,11 @@ const startAuthRecovery = (retryRefresh?: boolean) => {dispatchAuthRecoveryEvent('started');state.refreshPromise = refreshToken(retryRefresh).then((response) => {+ const setupToken = getTwoFactorSetupToken(response);+ if (setupToken) {+ redirectToTwoFactorSetupOnce(setupToken);+ return null;+ }const token = response?.token ?? '';if (!token) {return null;@@ -234,7 +325,9 @@ const redirectToLoginOnce = () => {const href = endpoints.apiBaseUrl() + endpoints.buildLoginRedirectUrl();setAuthRedirectStartedAt();- window.dispatchEvent(new CustomEvent(AUTH_REDIRECT_EVENT, { detail: { href } }));+ window.dispatchEvent(+ new CustomEvent(AUTH_REDIRECT_EVENT, { detail: { href, inDocument: false } }),+ );window.location.href = href;};@@ -305,6 +398,35 @@ const withAuthorization = (options: RequestInit | undefined, token: string | nulreturn { ...options, headers };};+/**+ * Enforcement reaches the SSE hooks as an error event rather than a `Response`, because the stream+ * transport is a raw `XMLHttpRequest` with neither the axios interceptor nor `_authenticatedFetch`+ * in front of it. They hand the event body here so an enrollment 403 opens setup instead of being+ * reported as a generic transport failure and retried against a condition that cannot clear.+ */+const redirectIfTwoFactorSetupPayload = (payload: unknown): boolean => {+ const setupToken = getTwoFactorSetupToken(parseSetupPayload(payload));+ if (!setupToken) {+ return false;+ }++ redirectToTwoFactorSetupOnce(setupToken);+ return true;+};++const redirectIfTwoFactorSetupRequired = async (response: Response): Promise<boolean> => {+ if (response.status !== 403) {+ return false;+ }++ return redirectIfTwoFactorSetupPayload(+ await response+ .clone()+ .json()+ .catch(() => null),+ );+};+async function _authenticatedFetch(url: string, options?: RequestInit): Promise<Response> {if (typeof window === 'undefined') {return fetch(url, options);@@ -312,6 +434,9 @@ async function _authenticatedFetch(url: string, options?: RequestInit): Promise<const token = (await refreshBeforeRequest(url)) ?? getBearerToken();const response = await fetch(url, withAuthorization(options, token));+ if (await redirectIfTwoFactorSetupRequired(response)) {+ return response;+ }if (response.status !== 401 ||isAuthRecoveryEndpoint(url) ||@@ -335,7 +460,9 @@ async function _authenticatedFetch(url: string, options?: RequestInit): Promise<}await response.body?.cancel().catch(() => undefined);- return fetch(url, withAuthorization(options, refreshedToken));+ const retriedResponse = await fetch(url, withAuthorization(options, refreshedToken));+ await redirectIfTwoFactorSetupRequired(retriedResponse);+ return retriedResponse;}if (typeof window !== 'undefined') {@@ -358,6 +485,14 @@ if (typeof window !== 'undefined') {return Promise.reject(error);}+ if (error.response.status === 403) {+ const setupToken = getTwoFactorSetupToken(error.response.data);+ if (setupToken) {+ redirectToTwoFactorSetupOnce(setupToken);+ return Promise.reject(error);+ }+ }+const isRefreshRequest = originalRequest.url?.includes('/api/auth/refresh') === true;if (isAuthRecoveryEndpoint(originalRequest.url) && !isRefreshRequest) {return Promise.reject(error);@@ -432,4 +567,5 @@ export default {authenticatedFetch: _authenticatedFetch,refreshToken,dispatchTokenUpdatedEvent,+ redirectIfTwoFactorSetupPayload,};diff --git a/packages/data-provider/src/twoFactor.spec.ts b/packages/data-provider/src/twoFactor.spec.tsnew file mode 100644index 0000000000..6865756d01--- /dev/null+++ b/packages/data-provider/src/twoFactor.spec.ts@@ -0,0 +1,83 @@+/**+ * @jest-environment jsdom+ */+import {+ clearTwoFactorSetupToken,+ persistTwoFactorSetupToken,+ readTwoFactorSetupToken,+} from './twoFactor';++const STORAGE_KEY = 'two_factor_setup_token';++describe('two-factor setup token hand-off', () => {+ beforeEach(() => {+ window.sessionStorage.clear();+ clearTwoFactorSetupToken();+ });++ it('round-trips a token without touching the URL', () => {+ persistTwoFactorSetupToken('setup-token');++ expect(readTwoFactorSetupToken()).toBe('setup-token');+ expect(window.sessionStorage.getItem(STORAGE_KEY)).toBe('setup-token');+ expect(window.location.search).toBe('');+ });++ it('reads nothing before a token is handed over', () => {+ expect(readTwoFactorSetupToken()).toBe('');+ });++ it('trims the surrounding whitespace a transport may add', () => {+ persistTwoFactorSetupToken(' setup-token ');++ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ it('drops the credential from both storage and memory when cleared', () => {+ persistTwoFactorSetupToken('setup-token');++ clearTwoFactorSetupToken();++ expect(readTwoFactorSetupToken()).toBe('');+ expect(window.sessionStorage.getItem(STORAGE_KEY)).toBeNull();+ });++ it('falls back to the in-memory mirror when session storage is unavailable', () => {+ persistTwoFactorSetupToken('setup-token');+ const getItem = jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {+ throw new Error('storage blocked');+ });++ expect(readTwoFactorSetupToken()).toBe('setup-token');++ getItem.mockRestore();+ });++ it('survives a persist that session storage refuses', () => {+ const setItem = jest.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {+ throw new Error('storage blocked');+ });++ expect(() => persistTwoFactorSetupToken('setup-token')).not.toThrow();+ setItem.mockRestore();+ expect(readTwoFactorSetupToken()).toBe('setup-token');+ });++ it('reports that a stored token outlives the current document', () => {+ expect(persistTwoFactorSetupToken('setup-token')).toBe(true);+ });++ /**+ * The mirror lives on `window`, so a caller that is about to replace the document has to know it+ * is the only copy left. Reporting the refusal is what keeps that navigation in the same page.+ */+ it('reports a refused persist so the caller can keep the document', () => {+ const setItem = jest.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {+ throw new Error('storage blocked');+ });++ expect(persistTwoFactorSetupToken('setup-token')).toBe(false);++ setItem.mockRestore();+ });+});diff --git a/packages/data-provider/src/twoFactor.ts b/packages/data-provider/src/twoFactor.tsnew file mode 100644index 0000000000..430f33b9be--- /dev/null+++ b/packages/data-provider/src/twoFactor.ts@@ -0,0 +1,70 @@+/**+ * Hand-off channel for the required-enrollment setup token.+ *+ * The token is a bearer credential in its own right: it can generate a TOTP secret of the+ * holder's choosing and then drive confirm, acknowledge, and finalize into a real session, with+ * no victim secret involved. Carrying it in the query string would leave it in browser history,+ * in access and reverse-proxy logs, and potentially in a Referer header, so it is handed to the+ * setup screen out of band instead.+ *+ * Session storage survives the hard navigation the response interceptor performs and is scoped to+ * the one tab. The in-memory mirror keeps the flow working where storage is blocked, which is why+ * persisting reports whether it reached durable storage: a navigation that replaces the document+ * would drop the mirror, so the interceptor stays inside the document when only the mirror holds.+ */++const SETUP_TOKEN_STORAGE_KEY = 'two_factor_setup_token';+const SETUP_TOKEN_EVENT = 'librechat:two-factor-setup-token';++interface TwoFactorSetupWindow extends Window {+ __librechatTwoFactorSetupToken?: string;+}++/**+ * Returns whether the token reached storage that outlives the current document. Callers that were+ * about to replace the document need to know, because the in-memory mirror does not survive that.+ */+export function persistTwoFactorSetupToken(tempToken: string): boolean {+ const trimmed = tempToken.trim();+ (window as TwoFactorSetupWindow).__librechatTwoFactorSetupToken = trimmed;+ let durable = true;+ try {+ window.sessionStorage.setItem(SETUP_TOKEN_STORAGE_KEY, trimmed);+ } catch {+ // Session storage can be blocked in embedded or private contexts.+ durable = false;+ }+ window.dispatchEvent(new Event(SETUP_TOKEN_EVENT));+ return durable;+}++/**+ * Notifies a mounted setup screen when a token arrives after it rendered, as when a refresh on the+ * setup route itself hands one off without navigating. Returns the unsubscribe function.+ */+export function subscribeTwoFactorSetupToken(listener: () => void): () => void {+ window.addEventListener(SETUP_TOKEN_EVENT, listener);+ return () => window.removeEventListener(SETUP_TOKEN_EVENT, listener);+}++export function readTwoFactorSetupToken(): string {+ try {+ const stored = window.sessionStorage.getItem(SETUP_TOKEN_STORAGE_KEY)?.trim();+ if (stored) {+ return stored;+ }+ } catch {+ // Fall through to the in-memory mirror.+ }++ return (window as TwoFactorSetupWindow).__librechatTwoFactorSetupToken?.trim() ?? '';+}++export function clearTwoFactorSetupToken(): void {+ delete (window as TwoFactorSetupWindow).__librechatTwoFactorSetupToken;+ try {+ window.sessionStorage.removeItem(SETUP_TOKEN_STORAGE_KEY);+ } catch {+ // Ignore unavailable storage.+ }+}diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.tsindex 960d6b647d..236fa9882e 100644--- a/packages/data-provider/src/types.ts+++ b/packages/data-provider/src/types.ts@@ -784,7 +784,9 @@ export type TLoginResponse = {token?: string;user?: TUser;twoFAPending?: boolean;+ twoFASetupRequired?: boolean;tempToken?: string;+ code?: 'TWO_FACTOR_ENROLLMENT_REQUIRED';};/** Shared payload for any operation that requires OTP or backup-code verification. */@@ -801,6 +803,37 @@ export type TEnable2FAResponse = {message?: string;};+export type TEnable2FASetupRequest = {+ tempToken: string;+};++export type TConfirm2FASetupRequest = {+ tempToken: string;+ token: string;+};++export type TConfirm2FASetupResponse = {+ backupCodes: string[];+ acknowledgementToken: string;+};++export type TAcknowledge2FASetupRequest = {+ acknowledgementToken: string;+};++export type TAcknowledge2FASetupResponse = {+ finalizationToken: string;+};++export type TFinalize2FASetupRequest = {+ finalizationToken: string;+};++export type TFinalize2FASetupResponse = {+ token: string;+ user: TUser;+};+export type TVerify2FARequest = TOTPVerificationPayload;export type TVerify2FAResponse = {@@ -1032,8 +1065,12 @@ export type TEmailChangeResponse = {};export type TRefreshTokenResponse = {- token: string;- user: TUser;+ token?: string;+ user?: TUser;+ twoFAPending?: boolean;+ twoFASetupRequired?: boolean;+ tempToken?: string;+ code?: 'TWO_FACTOR_ENROLLMENT_REQUIRED';};export type TCheckUserKeyResponse = {diff --git a/packages/data-schemas/src/methods/session.ts b/packages/data-schemas/src/methods/session.tsindex 5b8b42cae0..bc89c19bbe 100644--- a/packages/data-schemas/src/methods/session.ts+++ b/packages/data-schemas/src/methods/session.ts@@ -301,6 +301,9 @@ export function createSessionMethods(mongoose: typeof import('mongoose')): {payload: {id: session.user,sessionId: session._id,+ /** `iat` is whole seconds, too coarse to order this token against a password reset that+ * lands in the same second. `isTokenRetired` reads this claim to settle that exactly. */+ issuedAtMs: Date.now(),},secret: process.env.JWT_REFRESH_SECRET!,expirationTime: Math.floor((expiresIn - Date.now()) / 1000),diff --git a/packages/data-schemas/src/methods/user.methods.spec.ts b/packages/data-schemas/src/methods/user.methods.spec.tsindex 1ba6b2812d..ecdfe87a66 100644--- a/packages/data-schemas/src/methods/user.methods.spec.ts+++ b/packages/data-schemas/src/methods/user.methods.spec.ts@@ -762,6 +762,314 @@ describe('User Methods - Database Tests', () => {});});+ describe('updateTwoFactorEnrollment', () => {+ const ACK_HASH = 'acknowledgement-nonce-hash';+ const FINAL_HASH = 'finalization-nonce-hash';++ async function createEnrollingUser(+ email: string,+ overrides: Partial<t.IUser> = {},+ ): Promise<{ id: string; pendingBackupCodes: NonNullable<t.IUser['pendingBackupCodes']> }> {+ const user = await User.create({+ name: 'Enrolling User',+ email,+ provider: 'local',+ twoFactorEnabled: false,+ pendingTotpSecret: 'pending-secret',+ pendingBackupCodes: [{ codeHash: 'staged-hash', used: false }],+ ...overrides,+ });+ const id = user._id.toString();+ const stored = await User.findById(user._id).select('+pendingBackupCodes').lean<t.IUser>();+ return { id, pendingBackupCodes: stored?.pendingBackupCodes ?? [] };+ }++ function readEnrollment(userId: string) {+ return User.findById(userId)+ .select(+ '+totpSecret +backupCodes +pendingTotpSecret +pendingBackupCodes +twoFactorAcknowledgementNonceHash +twoFactorFinalizationNonceHash',+ )+ .lean<t.IUser>();+ }++ test('stages rotated backup codes and an acknowledgement nonce without enabling 2FA', async () => {+ const { id, pendingBackupCodes } = await createEnrollingUser('[email protected]');++ const updated = await methods.updateTwoFactorEnrollment(+ id,+ { pendingTotpSecret: 'pending-secret', pendingBackupCodes },+ {+ pendingBackupCodes: [{ codeHash: 'deliverable-hash', used: false, usedAt: null }],+ twoFactorAcknowledgementNonceHash: ACK_HASH,+ twoFactorFinalizationNonceHash: null,+ },+ );+ const stored = await readEnrollment(id);++ expect(updated).not.toBeNull();+ expect(stored?.twoFactorEnabled).toBe(false);+ expect(stored?.totpSecret).toBeFalsy();+ expect(stored?.pendingTotpSecret).toBe('pending-secret');+ expect(stored?.pendingBackupCodes).toMatchObject([{ codeHash: 'deliverable-hash' }]);+ expect(stored?.twoFactorAcknowledgementNonceHash).toBe(ACK_HASH);+ expect(stored?.twoFactorFinalizationNonceHash).toBeNull();+ });++ test('updates legacy enrolling users whose two-factor flag is missing', async () => {+ const { id, pendingBackupCodes } = await createEnrollingUser('[email protected]');+ const objectId = new mongoose.Types.ObjectId(id);+ await User.collection.updateOne({ _id: objectId }, { $unset: { twoFactorEnabled: '' } });++ const legacyUser = await User.collection.findOne({ _id: objectId });+ expect(legacyUser).not.toHaveProperty('twoFactorEnabled');++ const updated = await methods.updateTwoFactorEnrollment(+ id,+ { pendingTotpSecret: 'pending-secret', pendingBackupCodes },+ { twoFactorAcknowledgementNonceHash: ACK_HASH },+ );+ const stored = await readEnrollment(id);++ expect(updated).not.toBeNull();+ expect(stored?.twoFactorAcknowledgementNonceHash).toBe(ACK_HASH);+ });++ test('a second confirmation on the stale snapshot loses the race and writes nothing', async () => {+ const { id, pendingBackupCodes } = await createEnrollingUser('[email protected]');+ const guard = { pendingTotpSecret: 'pending-secret', pendingBackupCodes };++ const first = await methods.updateTwoFactorEnrollment(id, guard, {+ pendingBackupCodes: [{ codeHash: 'first-hash', used: false, usedAt: null }],+ twoFactorAcknowledgementNonceHash: 'first-ack',+ });+ const second = await methods.updateTwoFactorEnrollment(id, guard, {+ pendingBackupCodes: [{ codeHash: 'second-hash', used: false, usedAt: null }],+ twoFactorAcknowledgementNonceHash: 'second-ack',+ });+ const stored = await readEnrollment(id);++ expect(first).not.toBeNull();+ expect(second).toBeNull();+ expect(stored?.pendingBackupCodes).toMatchObject([{ codeHash: 'first-hash' }]);+ expect(stored?.twoFactorAcknowledgementNonceHash).toBe('first-ack');+ });++ test('consumes the acknowledgement nonce exactly once and keeps 2FA disabled', async () => {+ const { id } = await createEnrollingUser('[email protected]', {+ twoFactorAcknowledgementNonceHash: ACK_HASH,+ });++ const first = await methods.updateTwoFactorEnrollment(+ id,+ { twoFactorAcknowledgementNonceHash: ACK_HASH },+ {+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: FINAL_HASH,+ },+ );+ const replay = await methods.updateTwoFactorEnrollment(+ id,+ { twoFactorAcknowledgementNonceHash: ACK_HASH },+ {+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: 'replayed-finalization-hash',+ },+ );+ const stored = await readEnrollment(id);++ expect(first).not.toBeNull();+ expect(replay).toBeNull();+ expect(stored?.twoFactorEnabled).toBe(false);+ expect(stored?.twoFactorFinalizationNonceHash).toBe(FINAL_HASH);+ });++ test('promotes the pending enrollment once and clears every enrollment field', async () => {+ const { id, pendingBackupCodes } = await createEnrollingUser('[email protected]', {+ twoFactorFinalizationNonceHash: FINAL_HASH,+ expiresAt: new Date(Date.now() + 604800 * 1000),+ });+ const guard = {+ pendingTotpSecret: 'pending-secret',+ pendingBackupCodes,+ twoFactorFinalizationNonceHash: FINAL_HASH,+ };+ const promotion = {+ totpSecret: 'pending-secret',+ backupCodes: pendingBackupCodes,+ twoFactorEnabled: true,+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ };++ const promoted = await methods.updateTwoFactorEnrollment(id, guard, promotion);+ const replay = await methods.updateTwoFactorEnrollment(id, guard, promotion);+ const stored = await readEnrollment(id);++ expect(promoted).not.toBeNull();+ expect(promoted).toMatchObject({+ name: 'Enrolling User',+ email: '[email protected]',+ provider: 'local',+ twoFactorEnabled: true,+ });+ expect(promoted?.createdAt).toBeInstanceOf(Date);+ expect(replay).toBeNull();+ expect(stored).toMatchObject({+ twoFactorEnabled: true,+ totpSecret: 'pending-secret',+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ });+ expect(stored?.backupCodes).toMatchObject([{ codeHash: 'staged-hash' }]);+ expect(stored?.expiresAt).toBeUndefined();+ });++ test('persists the enrollment cutoff that retires pre-enrollment access tokens', async () => {+ const { id, pendingBackupCodes } = await createEnrollingUser('[email protected]', {+ twoFactorFinalizationNonceHash: FINAL_HASH,+ });+ const twoFactorEnrolledAt = new Date();++ const promoted = await methods.updateTwoFactorEnrollment(+ id,+ {+ pendingTotpSecret: 'pending-secret',+ pendingBackupCodes,+ twoFactorFinalizationNonceHash: FINAL_HASH,+ },+ {+ totpSecret: 'pending-secret',+ backupCodes: pendingBackupCodes,+ twoFactorEnabled: true,+ twoFactorEnrolledAt,+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ },+ );+ const stored = await readEnrollment(id);++ expect(promoted).not.toBeNull();+ /** A path the schema does not declare is dropped in silence, so assert the round trip. */+ expect(stored?.twoFactorEnrolledAt).toBeInstanceOf(Date);+ expect(stored?.twoFactorEnrolledAt?.getTime()).toBe(twoFactorEnrolledAt.getTime());+ });++ test('leaves the enrollment cutoff null until a promotion writes it', async () => {+ const { id } = await createEnrollingUser('[email protected]');++ const stored = await readEnrollment(id);++ expect(stored?.twoFactorEnrolledAt).toBeNull();+ });++ const concurrentTransitions: Array<[string, Partial<t.IUser>]> = [+ ['regenerated secret', { pendingTotpSecret: 'different-secret' }],+ [+ 'regenerated backup codes',+ { pendingBackupCodes: [{ codeHash: 'different-hash', used: false }] },+ ],+ ['federated provider transition', { provider: 'openid' }],+ ['already-enabled transition', { twoFactorEnabled: true }],+ ['cleared finalization nonce', { twoFactorFinalizationNonceHash: null }],+ ];++ test.each(concurrentTransitions)(+ 'does not promote after a concurrent %s',+ async (name, concurrentUpdate) => {+ const { id, pendingBackupCodes } = await createEnrollingUser(+ `raced-2fa-${name.replace(/ /g, '-')}@example.com`,+ { twoFactorFinalizationNonceHash: FINAL_HASH },+ );+ await User.findByIdAndUpdate(id, { $set: concurrentUpdate });++ const promoted = await methods.updateTwoFactorEnrollment(+ id,+ {+ pendingTotpSecret: 'pending-secret',+ pendingBackupCodes,+ twoFactorFinalizationNonceHash: FINAL_HASH,+ },+ {+ totpSecret: 'pending-secret',+ backupCodes: pendingBackupCodes,+ twoFactorEnabled: true,+ pendingTotpSecret: null,+ pendingBackupCodes: [],+ twoFactorAcknowledgementNonceHash: null,+ twoFactorFinalizationNonceHash: null,+ },+ );+ const stored = await readEnrollment(id);++ expect(promoted).toBeNull();+ expect(stored?.totpSecret).toBeFalsy();+ expect(stored?.twoFactorEnabled).toBe(concurrentUpdate.twoFactorEnabled === true);+ },+ );++ test('never exposes nonce state on an unprojected read', async () => {+ const { id } = await createEnrollingUser('[email protected]', {+ twoFactorAcknowledgementNonceHash: ACK_HASH,+ twoFactorFinalizationNonceHash: FINAL_HASH,+ });++ const user = await methods.getUserById(id);++ expect(user).not.toBeNull();+ expect(user).not.toHaveProperty('twoFactorAcknowledgementNonceHash');+ expect(user).not.toHaveProperty('twoFactorFinalizationNonceHash');+ expect(user).not.toHaveProperty('pendingTotpSecret');+ });++ test('invalidates cached auth user documents after a successful enrollment write', async () => {+ enableAuthUserDocCache();+ const { id, pendingBackupCodes } = await createEnrollingUser('[email protected]');+ const cache = {+ get: jest.fn().mockResolvedValue(['cached-auth-document']),+ delete: jest.fn().mockResolvedValue(true),+ };+ const methodsWithCache = createUserMethods(mongoose, {+ getCache: jest.fn().mockReturnValue(cache),+ });++ await methodsWithCache.updateTwoFactorEnrollment(+ id,+ { pendingTotpSecret: 'pending-secret', pendingBackupCodes },+ { twoFactorAcknowledgementNonceHash: ACK_HASH },+ );++ expect(cache.delete).toHaveBeenCalledWith('cached-auth-document');+ expect(cache.delete).toHaveBeenCalledWith(`${AUTH_USER_DOC_BY_ID_PREFIX}:${id}`);+ });++ test('leaves the auth user document cache untouched when the guard loses', async () => {+ enableAuthUserDocCache();+ const { id } = await createEnrollingUser('[email protected]');+ const cache = {+ get: jest.fn().mockResolvedValue(['cached-auth-document']),+ delete: jest.fn().mockResolvedValue(true),+ };+ const methodsWithCache = createUserMethods(mongoose, {+ getCache: jest.fn().mockReturnValue(cache),+ });++ const result = await methodsWithCache.updateTwoFactorEnrollment(+ id,+ { pendingTotpSecret: 'stale-secret' },+ { twoFactorAcknowledgementNonceHash: ACK_HASH },+ );++ expect(result).toBeNull();+ expect(cache.delete).not.toHaveBeenCalled();+ });+ });+describe('getUserById', () => {test('should get user by ID', async () => {const user = await User.create({diff --git a/packages/data-schemas/src/methods/user.test.ts b/packages/data-schemas/src/methods/user.test.tsindex 5e557805e4..fb2162aae4 100644--- a/packages/data-schemas/src/methods/user.test.ts+++ b/packages/data-schemas/src/methods/user.test.ts@@ -1,7 +1,7 @@import mongoose from 'mongoose';+import type { IUser } from '~/types';import { createUserMethods } from './user';import { signPayload } from '~/crypto';-import type { IUser } from '~/types';jest.mock('~/crypto', () => ({signPayload: jest.fn(),@@ -46,6 +46,7 @@ describe('User Methods', () => {username: mockUser.username,provider: mockUser.provider,email: mockUser.email,+ issuedAtMs: expect.any(Number),},secret: 'test-secret',expirationTime: 900, // 15 minutes in seconds (DEFAULT_SESSION_EXPIRY / 1000)@@ -64,6 +65,7 @@ describe('User Methods', () => {username: mockUser.username,provider: mockUser.provider,email: mockUser.email,+ issuedAtMs: expect.any(Number),},secret: 'test-secret',expirationTime: 900, // 15 minutes in seconds (DEFAULT_SESSION_EXPIRY / 1000)@@ -82,6 +84,7 @@ describe('User Methods', () => {username: mockUser.username,provider: mockUser.provider,email: mockUser.email,+ issuedAtMs: expect.any(Number),},secret: 'test-secret',expirationTime: 1800, // 30 minutes in seconds@@ -101,6 +104,7 @@ describe('User Methods', () => {username: mockUser.username,provider: mockUser.provider,email: mockUser.email,+ issuedAtMs: expect.any(Number),},secret: 'test-secret',expirationTime: 0, // 0 secondsdiff --git a/packages/data-schemas/src/methods/user.ts b/packages/data-schemas/src/methods/user.tsindex cfa9057a10..ee4ad522a0 100644--- a/packages/data-schemas/src/methods/user.ts+++ b/packages/data-schemas/src/methods/user.ts@@ -6,6 +6,7 @@ import {type StatefulCodeEnvironment,} from 'librechat-data-provider';import type { IUser, BalanceConfig, CreateUserRequest, UserDeleteResult } from '~/types';+import type { TwoFactorEnrollmentGuard, TwoFactorEnrollmentUpdate } from '~/types';import type { CacheStore } from '~/types';import { evictAuthUserDocs } from '~/utils/eviction';import { escapeRegExp } from '~/utils/string';@@ -19,6 +20,11 @@ export const USER_DELETION_FENCE_STALE_MS: number = 15 * 60_000;/** Bounds concurrent bulk deletions held for one owner at any moment. */const MAX_SUBAGENT_ADMISSION_FENCES = 32;+/** Providers whose credentials LibreChat owns, and therefore the only ones it can enroll in 2FA. */+const TWO_FACTOR_ENROLLMENT_PROVIDERS = [null, 'local', 'ldap'];+const TWO_FACTOR_ENROLLMENT_PROJECTION =+ '+totpSecret +backupCodes +pendingTotpSecret +pendingBackupCodes +twoFactorAcknowledgementNonceHash +twoFactorFinalizationNonceHash';+interface UserMethodDeps {getCache?: (key: string) => CacheStore | undefined;/** Resolves after the given milliseconds; tests pass one that need not wait out the cache TTL. */@@ -70,6 +76,11 @@ export function createUserMethods(samlId: string,profileData: Pick<Partial<IUser>, 'username' | 'name'>,) => Promise<IUser | null>;+ updateTwoFactorEnrollment: (+ userId: string,+ guard: TwoFactorEnrollmentGuard,+ updateData: TwoFactorEnrollmentUpdate,+ ) => Promise<IUser | null>;acceptTerms: (userId: string) => Promise<IUser | null>;searchUsers: ({searchPattern,@@ -114,6 +125,8 @@ export function createUserMethods(used: boolean;usedAt?: Date | null;}>;+ twoFactorAcknowledgementNonceHash?: string | null;+ twoFactorFinalizationNonceHash?: string | null;refreshToken?: Array<{refreshToken: string;}>;@@ -386,6 +399,36 @@ export function createUserMethods(return updated;}+ /**+ * Single compare-and-swap for every step of required two-factor enrollment. The filter always+ * pins the user to an unenrolled, policy-eligible provider, and `guard` adds the exact pending+ * secret, pending backup-code snapshot, or one-time nonce hash the caller observed. A step whose+ * predicate has moved returns `null` instead of writing.+ */+ async function updateTwoFactorEnrollment(+ userId: string,+ guard: TwoFactorEnrollmentGuard,+ updateData: TwoFactorEnrollmentUpdate,+ ): Promise<IUser | null> {+ const User = mongoose.models.User;+ const updated = await User.findOneAndUpdate(+ {+ _id: userId,+ twoFactorEnabled: { $ne: true },+ provider: { $in: TWO_FACTOR_ENROLLMENT_PROVIDERS },+ ...guard,+ },+ { $set: updateData, $unset: { expiresAt: '' } },+ { new: true, runValidators: true },+ )+ .select(TWO_FACTOR_ENROLLMENT_PROJECTION)+ .lean<IUser>();+ if (updated) {+ await invalidateAuthUserDocCache(userId);+ }+ return updated;+ }+/** Resolves false only when a cached document for the user may still be served. */async function invalidateAuthUserDocCache(userId: string): Promise<boolean> {if (!isAuthUserDocCacheEnabled()) {@@ -655,6 +698,9 @@ export function createUserMethods(username: user.username,provider: user.provider,email: user.email,+ /** `iat` is whole seconds, too coarse to order this token against a password reset that+ * lands in the same second. `isTokenRetired` reads this claim to settle that exactly. */+ issuedAtMs: Date.now(),},secret: process.env.JWT_SECRET,expirationTime: expires / 1000,@@ -760,6 +806,8 @@ export function createUserMethods(used: boolean;usedAt?: Date | null;}>;+ twoFactorAcknowledgementNonceHash?: string | null;+ twoFactorFinalizationNonceHash?: string | null;refreshToken?: Array<{refreshToken: string;}>;@@ -887,6 +935,7 @@ export function createUserMethods(updateUser,awaitAuthUserDocEviction,claimSamlIdentity,+ updateTwoFactorEnrollment,acceptTerms,searchUsers,getUserById,diff --git a/packages/data-schemas/src/schema/user.ts b/packages/data-schemas/src/schema/user.tsindex de4fbab159..d705ba71bf 100644--- a/packages/data-schemas/src/schema/user.ts+++ b/packages/data-schemas/src/schema/user.ts@@ -104,6 +104,10 @@ const userSchema: Schema<IUser> = new Schema<IUser>(type: Boolean,default: false,},+ twoFactorEnrolledAt: {+ type: Date,+ default: null,+ },totpSecret: {type: String,select: false,@@ -129,6 +133,16 @@ const userSchema: Schema<IUser> = new Schema<IUser>(credentialsChangedAt: {type: Date,},+ twoFactorAcknowledgementNonceHash: {+ type: String,+ select: false,+ default: null,+ },+ twoFactorFinalizationNonceHash: {+ type: String,+ select: false,+ default: null,+ },refreshToken: {type: [SessionSchema],},diff --git a/packages/data-schemas/src/types/user.ts b/packages/data-schemas/src/types/user.tsindex 2928d227f6..c589705e5e 100644--- a/packages/data-schemas/src/types/user.ts+++ b/packages/data-schemas/src/types/user.ts@@ -36,6 +36,11 @@ export interface IUser extends Document {plugins?: string[];openidIssuer?: string;twoFactorEnabled?: boolean;+ /**+ * When required enrollment promoted this account. Access tokens are stateless, so this is the+ * cutoff that retires the ones minted while the account still had no second factor.+ */+ twoFactorEnrolledAt?: Date | null;totpSecret?: string;backupCodes?: Array<{codeHash: string;@@ -48,8 +53,12 @@ export interface IUser extends Document {used: boolean;usedAt?: Date | null;}>;- /** Instant of the last credential change; access tokens issued before it are rejected */- credentialsChangedAt?: Date;+ /** Instant of the last credential change; bearer tokens issued before it are rejected */+ credentialsChangedAt?: Date | null;+ /** SHA-256 hash of the one-time nonce that authorizes the backup-code acknowledgement step. */+ twoFactorAcknowledgementNonceHash?: string | null;+ /** SHA-256 hash of the one-time nonce that authorizes required-enrollment finalization. */+ twoFactorFinalizationNonceHash?: string | null;refreshToken?: Array<{refreshToken: string;}>;@@ -82,6 +91,30 @@ export interface IUser extends Document {openidTokens?: OIDCTokens;}+/**+ * Predicates that bind a required two-factor enrollment mutation to the exact state its+ * caller observed. Every supplied field is ANDed into the compare-and-swap filter, so a+ * concurrent regeneration, acknowledgement, or finalization loses the race and fails closed.+ */+export interface TwoFactorEnrollmentGuard {+ pendingTotpSecret?: string;+ pendingBackupCodes?: NonNullable<IUser['pendingBackupCodes']>;+ twoFactorAcknowledgementNonceHash?: string;+ twoFactorFinalizationNonceHash?: string;+}++/** Fields a required two-factor enrollment step may write; `null` clears the stored value. */+export interface TwoFactorEnrollmentUpdate {+ totpSecret?: string | null;+ backupCodes?: NonNullable<IUser['backupCodes']>;+ twoFactorEnabled?: boolean;+ twoFactorEnrolledAt?: Date;+ pendingTotpSecret?: string | null;+ pendingBackupCodes?: NonNullable<IUser['pendingBackupCodes']>;+ twoFactorAcknowledgementNonceHash?: string | null;+ twoFactorFinalizationNonceHash?: string | null;+}+export interface OIDCTokens {access_token?: string;id_token?: string;