LibreChat/packages/api/src/auth/twoFactor.spec.ts
Marco Beretta 92432e95d5
Some checks are pending
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 Votes / vote (full suite) (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/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) Waiting to run
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Blocked by required conditions
🔐 feat: Enforce Required Two-Factor Authentication (#14731)
* feat: enforce required two-factor authentication

Require local and LDAP accounts to enroll in TOTP before they can use the
app when ENFORCE_TWO_FACTOR_AUTHENTICATION is set. Sign-in, refresh, bearer
verification, optional share auth and image authorization all route an
unenrolled account into a staged setup flow, and every bearer credential
minted before enrollment or a password reset is retired.

Password reset retirement uses the existing credentialsChangedAt stamp, and
commitPasswordReset clears any staged enrollment in the same write. Passkey
sign-in follows the same enrollment gate as password sign-in.

* test: cover passkey sign-in handing off to required enrollment

* refactor: keep Mongoose user types out of two-factor auth contracts

* fix: withdraw a minted session when its retirement recheck fails

* fix: hold Agent API keys and the reset CLI to the required two-factor policy

* fix: adopt a setup token handed off after the setup screen mounted

* fix: move every tab that receives an enrollment hand-off into setup

* fix: read the enrollment gate's retirement cutoff in system scope

* fix: clear minted session cookies before the fallible session deletion

* fix: adopt a setup token persisted before the setup screen subscribed
2026-10-01 23:39:51 +02:00

1556 lines
53 KiB
TypeScript

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,
});
});
});