LibreChat/api/server/controllers/__tests__/TwoFactorController.spec.js
Marco Beretta 76c25680ce
Some checks failed
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Vote Gate / Gate (push) Waiting to run
Codegraph E2E Votes / vote (shard 1/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 10/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 2/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 3/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 4/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 5/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 6/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 7/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 8/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 9/10) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/chat (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Has been cancelled
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Has been cancelled
🔐 fix: Retire Credentials by Their Committing Write and on Opt-In 2FA (#17504)
* fix: Retire Credentials by Their Committing Write and on Opt-In 2FA

Re-date password reset and enrollment cutoffs once the write that set them commits, so a credential minted while the write is in flight is retired. Opt-in 2FA confirmation now stamps twoFactorEnrolledAt and rotates the session like required enrollment. OpenID refresh ends a session established before a reset or enrollment instead of spending its IdP grant.

* fix: Bind Opt-In 2FA Rotation to the Caller's Refresh Session

Confirmation now requires the refresh session the request was issued with, rotates it in place and revokes only the others, so an access token on its own cannot trade enrollment for a long-lived session. The OpenID retirement check moves into the refresh recovery service and ends the session through the existing session-missing path, leaving the CJS controller unchanged.

* fix: Clear a Retired OpenID Session Against the User It Was Checked For

* refactor: Inject the Refresh Secret Into OpenID Recovery

* fix: Report a Reset Whose Cutoff Could Not Be Re-Dated

A failed re-stamp now propagates as RETIREMENT_RESTAMP_FAILED. The reset controller still revokes sessions and passkeys and answers CREDENTIAL_RETIREMENT_INCOMPLETE; the CLI re-stamps after its revocations and exits non-zero; enrollment revokes sessions before the re-stamp and mints nothing when it fails.

* fix: Re-Date the Reset Cutoff Only After the Link Is Consumed

The web reset re-stamps credentialsChangedAt in the controller once resetPassword has committed, consumed the token and sent the notice, so a failed re-stamp can no longer leave the link replayable. Revocations still run and the response reports CREDENTIAL_RETIREMENT_INCOMPLETE.

* fix: Retire Credentials on Every Exit Path After a Reset Commits

resetPasswordWithToken owns the post-commit steps: deleting the link and sending the notice no longer throw, and a link issued before the account's last credentialsChangedAt is refused, so it is spent even when its deletion fails. The reset write is conditioned on the cutoff it read, so one link commits once. The controller re-dates the cutoff and revokes sessions and passkeys whenever the password changed, and answers CREDENTIAL_RETIREMENT_INCOMPLETE if any of that fails.

* fix: Spend Undated Reset Links and Move the Reset Notice Into TypeScript

* fix: Tell the User When a Reset Could Not Sign Out Every Session

The reset page now recognizes CREDENTIAL_RETIREMENT_INCOMPLETE, shared from librechat-data-provider, and shows a localized warning that the new password is active with a sign-in action, instead of reporting the spent link as invalid.

* perf: Re-Date the Reset Cutoff From the Committed Write

The committed reset hands its credentialsChangedAt back through PasswordResetResult, so the controller re-stamps without a second user read.

* fix: Retire Every Superseded Credential Before Minting on 2FA Enrollment

Opt-in confirmation and setup finalization now revoke sessions, re-date twoFactorEnrolledAt and wait for the auth cache to drop the pre-enrollment document, running every step even when one fails. If any step fails they mint nothing and answer CREDENTIAL_RETIREMENT_INCOMPLETE; the settings dialog keeps 2FA on with a warning and the setup screen sends the user back to sign in with the new factor.

* test: Cover the Settings Warning When 2FA Enrollment Leaves Sessions Behind

* fix: Send the User Back to Sign In After an Incomplete Opt-In Enrollment

Enrollment retires the confirming tab's bearer, and an incomplete retirement mints no replacement, so the settings dialog now shows the backup codes and then signs out to the login page, whether the user completes setup or closes the dialog.

* test: Run the Retirement Warning Scenarios Against Their Own Signed-Out or Fresh Accounts

* test: Open the Sidebar Drawer Before the Account Menu on Phones

* fix: Report a Committed Opt-In Enrollment When Rotating the Session Fails

Once 2FA is promoted, a later failure in confirm2FA withdraws whatever session it may have minted and answers CREDENTIAL_RETIREMENT_INCOMPLETE, so the settings dialog hands over the backup codes and signs the user in again instead of reporting an invalid code.

* test: Prove an Incomplete Reset Does Not Resume the Retired Session

The Sign in action sends a browser with a live session through /login for about 150 ms before it lands in chat, so the signed-in version of the warning scenario only passed when the URL check caught that window. The warning scenario runs signed out, and a new scenario holds a pre-reset session and asserts its refresh is refused and the user stays on the login page.

* fix: Settle the Auth Cache After the CLI Reset's Final Cutoff Write

* test: Require the Login Form After Signing In From a Signed-Out Reset

* fix: Explain an Incomplete Session Retirement Before Restarting Sign-In After Required 2FA Setup

* perf: Start the Opt-In Enrollment User and Session Reads Together
2026-11-05 22:53:11 +01:00

416 lines
14 KiB
JavaScript

const mockGetUserById = jest.fn();
const mockUpdateUser = jest.fn();
const mockVerifyOTPOrBackupCode = jest.fn();
const mockGenerateTOTPSecret = jest.fn();
const mockGenerateBackupCodes = jest.fn();
const mockEncryptV3 = jest.fn();
const mockGetTOTPSecret = jest.fn();
const mockVerifyTOTP = jest.fn();
const mockDeleteAllUserSessions = jest.fn();
const mockSetAuthTokens = jest.fn();
const mockFindSession = jest.fn();
const CALLER_SESSION = { _id: 'session-1', expiration: new Date(Date.now() + 3_600_000) };
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
encryptV3: (...args) => mockEncryptV3(...args),
logger: { error: jest.fn(), warn: jest.fn() },
}));
jest.mock('~/server/services/AuthService', () => ({
setAuthTokens: (...args) => mockSetAuthTokens(...args),
}));
jest.mock('~/server/services/twoFactorService', () => ({
verifyOTPOrBackupCode: (...args) => mockVerifyOTPOrBackupCode(...args),
generateBackupCodes: (...args) => mockGenerateBackupCodes(...args),
generateTOTPSecret: (...args) => mockGenerateTOTPSecret(...args),
verifyBackupCode: jest.fn(),
getTOTPSecret: (...args) => mockGetTOTPSecret(...args),
verifyTOTP: (...args) => mockVerifyTOTP(...args),
}));
jest.mock('~/models', () => ({
getUserById: (...args) => mockGetUserById(...args),
updateUser: (...args) => mockUpdateUser(...args),
deleteAllUserSessions: (...args) => mockDeleteAllUserSessions(...args),
findSession: (...args) => mockFindSession(...args),
awaitAuthUserDocEviction: jest.fn(async () => undefined),
}));
const {
enable2FA,
confirm2FA,
disable2FA,
regenerateBackupCodes,
} = require('~/server/controllers/TwoFactorController');
function createRes() {
const res = {};
res.status = jest.fn().mockReturnValue(res);
res.json = jest.fn().mockReturnValue(res);
res.clearCookie = jest.fn();
return res;
}
const PLAIN_CODES = ['code1', 'code2', 'code3'];
const CODE_OBJECTS = [
{ codeHash: 'h1', used: false, usedAt: null },
{ codeHash: 'h2', used: false, usedAt: null },
{ codeHash: 'h3', used: false, usedAt: null },
];
beforeEach(() => {
jest.clearAllMocks();
mockGenerateTOTPSecret.mockReturnValue('NEWSECRET');
mockGenerateBackupCodes.mockResolvedValue({ plainCodes: PLAIN_CODES, codeObjects: CODE_OBJECTS });
mockEncryptV3.mockReturnValue('encrypted-secret');
mockGetTOTPSecret.mockResolvedValue('plain-secret');
mockVerifyTOTP.mockResolvedValue(true);
mockDeleteAllUserSessions.mockResolvedValue({ deletedCount: 2 });
mockSetAuthTokens.mockResolvedValue('rotated-token');
mockFindSession.mockResolvedValue(CALLER_SESSION);
});
const confirmRequest = (cookies = { refreshToken: 'caller-refresh' }) => ({
user: { id: 'user1' },
body: { token: '123456' },
headers: {},
cookies,
});
/** 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: 'a@b.com' });
mockUpdateUser.mockResolvedValue({ email: 'a@b.com' });
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({ _id: 'user1' });
const res = createRes();
await confirm2FA(confirmRequest(), res);
expect(res.status).toHaveBeenCalledWith(200);
expect(mockUpdateUser.mock.calls[0][1]).toMatchObject({
twoFactorEnabled: true,
pendingTotpSecret: null,
pendingBackupCodes: [],
...CLEARED_NONCES,
});
});
it('retires pre-enrollment sessions and hands back a rotated one', async () => {
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: false,
pendingTotpSecret: 'encrypted-secret',
pendingBackupCodes: CODE_OBJECTS,
});
mockUpdateUser.mockResolvedValue({ _id: 'user1' });
const res = createRes();
await confirm2FA(confirmRequest(), res);
const [, promotion, guard] = mockUpdateUser.mock.calls[0];
expect(promotion.twoFactorEnrolledAt).toBeInstanceOf(Date);
expect(guard).toEqual({ pendingTotpSecret: 'encrypted-secret' });
expect(mockFindSession).toHaveBeenCalledWith(
{ userId: 'user1', refreshToken: 'caller-refresh' },
{ lean: false },
);
expect(mockDeleteAllUserSessions).toHaveBeenCalledWith(
{ userId: 'user1' },
{ excludeCurrentSession: true, currentSessionId: 'session-1' },
);
expect(mockSetAuthTokens).toHaveBeenCalledWith(
'user1',
res,
CALLER_SESSION,
expect.any(Object),
);
expect(mockDeleteAllUserSessions.mock.invocationCallOrder[0]).toBeLessThan(
mockSetAuthTokens.mock.invocationCallOrder[0],
);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
token: 'rotated-token',
user: expect.objectContaining({ id: 'user1' }),
}),
);
});
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('confirm2FA session binding', () => {
it.each([
['no refresh cookie', {}, null],
['a refresh cookie without a stored session', { refreshToken: 'stolen' }, null],
])('refuses an access token with %s', async (_label, cookies, session) => {
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: false,
pendingTotpSecret: 'encrypted-secret',
});
mockFindSession.mockResolvedValue(session);
const res = createRes();
await confirm2FA(confirmRequest(cookies), res);
expect(res.status).toHaveBeenCalledWith(401);
expect(mockUpdateUser).not.toHaveBeenCalled();
expect(mockDeleteAllUserSessions).not.toHaveBeenCalled();
expect(mockSetAuthTokens).not.toHaveBeenCalled();
});
});
describe('enable2FA', () => {
it('allows first-time setup without token — writes to pending fields', async () => {
const req = { user: { id: 'user1' }, body: {} };
const res = createRes();
mockGetUserById.mockResolvedValue({ _id: 'user1', twoFactorEnabled: false, email: 'a@b.com' });
mockUpdateUser.mockResolvedValue({ email: 'a@b.com' });
await enable2FA(req, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ otpauthUrl: expect.any(String), backupCodes: PLAIN_CODES }),
);
expect(mockVerifyOTPOrBackupCode).not.toHaveBeenCalled();
const updateCall = mockUpdateUser.mock.calls[0][1];
expect(updateCall).toHaveProperty('pendingTotpSecret', 'encrypted-secret');
expect(updateCall).toHaveProperty('pendingBackupCodes', CODE_OBJECTS);
expect(updateCall).not.toHaveProperty('twoFactorEnabled');
expect(updateCall).not.toHaveProperty('totpSecret');
expect(updateCall).not.toHaveProperty('backupCodes');
});
it('re-enrollment writes to pending fields, leaving live 2FA intact', async () => {
const req = { user: { id: 'user1' }, body: { token: '123456' } };
const res = createRes();
const existingUser = {
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
email: 'a@b.com',
};
mockGetUserById.mockResolvedValue(existingUser);
mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: true });
mockUpdateUser.mockResolvedValue({ email: 'a@b.com' });
await enable2FA(req, res);
expect(mockVerifyOTPOrBackupCode).toHaveBeenCalledWith({
user: existingUser,
token: '123456',
backupCode: undefined,
persistBackupUse: false,
});
expect(res.status).toHaveBeenCalledWith(200);
const updateCall = mockUpdateUser.mock.calls[0][1];
expect(updateCall).toHaveProperty('pendingTotpSecret', 'encrypted-secret');
expect(updateCall).toHaveProperty('pendingBackupCodes', CODE_OBJECTS);
expect(updateCall).not.toHaveProperty('twoFactorEnabled');
expect(updateCall).not.toHaveProperty('totpSecret');
});
it('allows re-enrollment with valid backup code (persistBackupUse: false)', async () => {
const req = { user: { id: 'user1' }, body: { backupCode: 'backup123' } };
const res = createRes();
const existingUser = {
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
email: 'a@b.com',
};
mockGetUserById.mockResolvedValue(existingUser);
mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: true });
mockUpdateUser.mockResolvedValue({ email: 'a@b.com' });
await enable2FA(req, res);
expect(mockVerifyOTPOrBackupCode).toHaveBeenCalledWith(
expect.objectContaining({ persistBackupUse: false }),
);
expect(res.status).toHaveBeenCalledWith(200);
});
it('returns error when no token provided and 2FA is enabled', async () => {
const req = { user: { id: 'user1' }, body: {} };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
});
mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: false, status: 400 });
await enable2FA(req, res);
expect(res.status).toHaveBeenCalledWith(400);
expect(mockUpdateUser).not.toHaveBeenCalled();
});
it('returns 401 when invalid token provided and 2FA is enabled', async () => {
const req = { user: { id: 'user1' }, body: { token: 'wrong' } };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
});
mockVerifyOTPOrBackupCode.mockResolvedValue({
verified: false,
status: 401,
message: 'Invalid token or backup code',
});
await enable2FA(req, res);
expect(res.status).toHaveBeenCalledWith(401);
expect(res.json).toHaveBeenCalledWith({ message: 'Invalid token or backup code' });
expect(mockUpdateUser).not.toHaveBeenCalled();
});
});
describe('regenerateBackupCodes', () => {
it('returns 404 when user not found', async () => {
const req = { user: { id: 'user1' }, body: {} };
const res = createRes();
mockGetUserById.mockResolvedValue(null);
await regenerateBackupCodes(req, res);
expect(res.status).toHaveBeenCalledWith(404);
expect(res.json).toHaveBeenCalledWith({ message: 'User not found' });
});
it('requires OTP when 2FA is enabled', async () => {
const req = { user: { id: 'user1' }, body: { token: '123456' } };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
});
mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: true });
mockUpdateUser.mockResolvedValue({});
await regenerateBackupCodes(req, res);
expect(mockVerifyOTPOrBackupCode).toHaveBeenCalled();
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith({
backupCodes: PLAIN_CODES,
backupCodesHash: CODE_OBJECTS,
});
});
it('returns error when no token provided and 2FA is enabled', async () => {
const req = { user: { id: 'user1' }, body: {} };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
});
mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: false, status: 400 });
await regenerateBackupCodes(req, res);
expect(res.status).toHaveBeenCalledWith(400);
});
it('returns 401 when invalid token provided and 2FA is enabled', async () => {
const req = { user: { id: 'user1' }, body: { token: 'wrong' } };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
});
mockVerifyOTPOrBackupCode.mockResolvedValue({
verified: false,
status: 401,
message: 'Invalid token or backup code',
});
await regenerateBackupCodes(req, res);
expect(res.status).toHaveBeenCalledWith(401);
expect(res.json).toHaveBeenCalledWith({ message: 'Invalid token or backup code' });
});
it('includes backupCodesHash in response', async () => {
const req = { user: { id: 'user1' }, body: { token: '123456' } };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: true,
totpSecret: 'enc-secret',
});
mockVerifyOTPOrBackupCode.mockResolvedValue({ verified: true });
mockUpdateUser.mockResolvedValue({});
await regenerateBackupCodes(req, res);
const responseBody = res.json.mock.calls[0][0];
expect(responseBody).toHaveProperty('backupCodesHash', CODE_OBJECTS);
expect(responseBody).toHaveProperty('backupCodes', PLAIN_CODES);
});
it('allows regeneration without token when 2FA is not enabled', async () => {
const req = { user: { id: 'user1' }, body: {} };
const res = createRes();
mockGetUserById.mockResolvedValue({
_id: 'user1',
twoFactorEnabled: false,
});
mockUpdateUser.mockResolvedValue({});
await regenerateBackupCodes(req, res);
expect(mockVerifyOTPOrBackupCode).not.toHaveBeenCalled();
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith({
backupCodes: PLAIN_CODES,
backupCodesHash: CODE_OBJECTS,
});
});
});