Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
TypeScript analyticsaudience-segmentationchartscohort-analysisgoogle-analyticsproduct-analyticsstatisticsuser-journeyweb-analytics
Harden 2FA APi routes and UI when 2FA env var missing. Closes #4443.
Francis Cao0a77e50da122
diff --git a/src/app/(main)/admin/security/AdminSecurityPage.tsx b/src/app/(main)/admin/security/AdminSecurityPage.tsxindex a962787ae..a243ca4d7 100644--- a/src/app/(main)/admin/security/AdminSecurityPage.tsx+++ b/src/app/(main)/admin/security/AdminSecurityPage.tsx@@ -11,7 +11,9 @@ export function AdminSecurityPage() {const { mutateAsync: setGlobal } = useUpdateQuery('/admin/2fa/global');const queryClient = useQueryClient();- const isGlobalRequired = status?.requiredReason === 'global' || false;+ const isConfigured = status?.isConfigured;+ const isGlobalRequired = status?.globalRequired ?? false;+ const showConfigurationError = isConfigured === false;const handleToggle = async (value: boolean) => {await setGlobal({ required: value });@@ -27,15 +29,23 @@ export function AdminSecurityPage() {<Column gap="4"><Column gap="1"><Text weight="bold">{t(labels.twoFactorAuth)}</Text>- <Text>{t(messages.twoFactorAdminGlobalDescription)}</Text>+ <Text>+ {showConfigurationError+ ? t(messages.twoFactorErrorNotConfigured)+ : t(messages.twoFactorAdminGlobalDescription)}+ </Text></Column><Row alignItems="center" gap="3">- <Switch isSelected={isGlobalRequired} onChange={handleToggle} />+ <Switch+ isSelected={isGlobalRequired}+ isDisabled={!isConfigured && !isGlobalRequired}+ onChange={handleToggle}+ /><Text>{t(labels.twoFactorRequireGlobal)}</Text></Row>- {isGlobalRequired && (+ {isConfigured === true && isGlobalRequired && (<Text size="sm" color="muted">{t(messages.twoFactorOverrideNote)}</Text>diff --git a/src/app/(main)/admin/users/[userId]/UserTwoFactorSettings.tsx b/src/app/(main)/admin/users/[userId]/UserTwoFactorSettings.tsxindex 80832d18e..b67ba3418 100644--- a/src/app/(main)/admin/users/[userId]/UserTwoFactorSettings.tsx+++ b/src/app/(main)/admin/users/[userId]/UserTwoFactorSettings.tsx@@ -32,7 +32,9 @@ export function UserTwoFactorSettings({ userId }: { userId: string }) {const [showReset, setShowReset] = useState(false);const { data: globalStatus } = useTwoFactorStatusQuery(true);- const isGlobalRequired = globalStatus?.requiredReason === 'global';+ const isConfigured = globalStatus?.isConfigured;+ const isGlobalRequired = globalStatus?.globalRequired ?? false;+ const showConfigurationError = isConfigured === false;const { data: userTfaData } = useTwoFactorUserStatusQuery(userId);const { data: userData } = useUserQuery(userId);@@ -52,6 +54,18 @@ export function UserTwoFactorSettings({ userId }: { userId: string }) {queryClient.invalidateQueries({ queryKey: ['users', { userId }] });};+ const isToggleDisabled = isGlobalRequired || (!isConfigured && !twoFactorRequired);+ const toggle = (+ <Row alignItems="center" gap="3">+ <Switch+ isSelected={isGlobalRequired || twoFactorRequired}+ isDisabled={isToggleDisabled}+ onChange={handleToggle}+ />+ <Text>{t(labels.twoFactorRequireUser)}</Text>+ </Row>+ );+const handleReset = async () => {await resetUserTwoFactor(null, {onSuccess: async () => {@@ -75,27 +89,19 @@ export function UserTwoFactorSettings({ userId }: { userId: string }) {{t(messages.twoFactorRequireUserDescription)}</Text>+ {showConfigurationError && (+ <Text size="sm" color="muted">+ {t(messages.twoFactorErrorNotConfigured)}+ </Text>+ )}+{isGlobalRequired ? (<TooltipTrigger>- <Row alignItems="center" gap="3">- <Switch- isSelected={isGlobalRequired || twoFactorRequired}- isDisabled={isGlobalRequired}- onChange={handleToggle}- />- <Text>{t(labels.twoFactorRequireUser)}</Text>- </Row>+ {toggle}<Tooltip>{t(labels.twoFactorGlobalActiveTooltip)}</Tooltip></TooltipTrigger>) : (- <Row alignItems="center" gap="3">- <Switch- isSelected={isGlobalRequired || twoFactorRequired}- isDisabled={isGlobalRequired}- onChange={handleToggle}- />- <Text>{t(labels.twoFactorRequireUser)}</Text>- </Row>+ toggle)}{twoFactorEnabled && (diff --git a/src/app/(main)/settings/security/UserSecurityPage.tsx b/src/app/(main)/settings/security/UserSecurityPage.tsxindex 9d1426a88..9faa8232e 100644--- a/src/app/(main)/settings/security/UserSecurityPage.tsx+++ b/src/app/(main)/settings/security/UserSecurityPage.tsx@@ -19,6 +19,8 @@ export function UserSecurityPage() {const isEnabled = status?.isEnabled ?? false;const isRequired = status?.isRequired ?? false;+ const isConfigured = status?.isConfigured;+ const showConfigurationError = isConfigured === false;const handleToggle = (value: boolean) => {if (value) {@@ -55,13 +57,15 @@ export function UserSecurityPage() {)}</Row>- {isEnabled ? (+ {showConfigurationError ? (+ <Text>{t(messages.twoFactorErrorNotConfigured)}</Text>+ ) : isEnabled ? (<Text>{t(messages.twoFactorActiveDescription)}</Text>) : (<Text>{t(messages.twoFactorUserDescription)}</Text>)}- {isEnabled && isRequired ? (+ {isConfigured === true && isEnabled && isRequired ? (<TooltipTrigger><Row alignItems="center" gap="3"><Switch@@ -71,9 +75,11 @@ export function UserSecurityPage() {/><Text>{t(labels.twoFactorEnable)}</Text></Row>- <Tooltip>{t(messages.twoFactorRequiredMessage)}</Tooltip>+ <Tooltip>{t(messages.twoFactorRequiredMessage)}</Tooltip></TooltipTrigger>- ) : (+ ) : null}++ {isConfigured === true && !isEnabled ? (<Row alignItems="center" gap="3"><SwitchisSelected={isEnabled}@@ -82,9 +88,20 @@ export function UserSecurityPage() {/><Text>{t(labels.twoFactorEnable)}</Text></Row>- )}+ ) : null}++ {isConfigured === true && isEnabled && !isRequired ? (+ <Row alignItems="center" gap="3">+ <Switch+ isSelected={isEnabled}+ isDisabled={isEnabled && isRequired}+ onChange={handleToggle}+ />+ <Text>{t(labels.twoFactorEnable)}</Text>+ </Row>+ ) : null}- {isEnabled && isRequired && (+ {isConfigured === true && isEnabled && isRequired && (<Text size="sm" color="muted">{t(messages.twoFactorRequiredMessage)}</Text>diff --git a/src/app/(main)/teams/[teamId]/TeamTwoFactorSettings.tsx b/src/app/(main)/teams/[teamId]/TeamTwoFactorSettings.tsxindex b77a4b030..3431431a8 100644--- a/src/app/(main)/teams/[teamId]/TeamTwoFactorSettings.tsx+++ b/src/app/(main)/teams/[teamId]/TeamTwoFactorSettings.tsx@@ -13,7 +13,9 @@ export function TeamTwoFactorSettings({ teamId }: { teamId: string }) {const queryClient = useQueryClient();const { data: globalStatus } = useTwoFactorStatusQuery(true);- const isGlobalRequired = globalStatus?.requiredReason === 'global';+ const isConfigured = globalStatus?.isConfigured;+ const isGlobalRequired = globalStatus?.globalRequired ?? false;+ const showConfigurationError = isConfigured === false;const { data: teamData } = useTeamQuery(teamId);const { mutateAsync: setTeamRequired } = useUpdateQuery(`/admin/teams/${teamId}/2fa`);@@ -25,31 +27,35 @@ export function TeamTwoFactorSettings({ teamId }: { teamId: string }) {queryClient.invalidateQueries({ queryKey: ['teams', { teamId }] });};+ const isToggleDisabled = isGlobalRequired || (!isConfigured && !twoFactorRequired);+ const toggle = (+ <Row alignItems="center" gap="3">+ <Switch+ isSelected={isGlobalRequired || twoFactorRequired}+ isDisabled={isToggleDisabled}+ onChange={handleToggle}+ />+ <Text>{t(labels.twoFactorRequireTeam)}</Text>+ </Row>+ );+return (<Column gap="4"><Text weight="bold">{t(labels.twoFactorAuth)}</Text>+ {showConfigurationError && (+ <Text size="sm" color="muted">+ {t(messages.twoFactorErrorNotConfigured)}+ </Text>+ )}+{isGlobalRequired ? (<TooltipTrigger>- <Row alignItems="center" gap="3">- <Switch- isSelected={isGlobalRequired || twoFactorRequired}- isDisabled={isGlobalRequired}- onChange={handleToggle}- />- <Text>{t(labels.twoFactorRequireTeam)}</Text>- </Row>+ {toggle}<Tooltip>{t(labels.twoFactorGlobalActiveTooltip)}</Tooltip></TooltipTrigger>) : (- <Row alignItems="center" gap="3">- <Switch- isSelected={isGlobalRequired || twoFactorRequired}- isDisabled={isGlobalRequired}- onChange={handleToggle}- />- <Text>{t(labels.twoFactorRequireTeam)}</Text>- </Row>+ toggle)}<Text size="sm" color="muted">diff --git a/src/app/api/2fa/disable/route.test.ts b/src/app/api/2fa/disable/route.test.tsnew file mode 100644index 000000000..b183b1be5--- /dev/null+++ b/src/app/api/2fa/disable/route.test.ts@@ -0,0 +1,76 @@+import { beforeEach, expect, test, vi } from 'vitest';++const mocks = vi.hoisted(() => ({+ parseRequest: vi.fn(),+ isTwoFactorConfigured: vi.fn(),+}));++vi.mock('@/lib/request', () => ({+ parseRequest: mocks.parseRequest,+}));++vi.mock('@/lib/prisma', () => ({+ default: {+ client: {},+ },+}));++vi.mock('@/lib/two-factor/crypto', () => ({+ decryptSecret: vi.fn(),+ getTwoFactorConfigurationError: () => ({+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+ }),+ isTwoFactorConfigured: mocks.isTwoFactorConfigured,+}));++vi.mock('@/lib/two-factor/rate-limit', () => ({+ checkRateLimit: vi.fn(),+ recordFailedAttempt: vi.fn(),+ resetRateLimit: vi.fn(),+}));++vi.mock('@/lib/two-factor/replay-prevention', () => ({+ isOtpReplayed: vi.fn(),+ markOtpUsed: vi.fn(),+}));++vi.mock('@/lib/two-factor/totp', () => ({+ verifyTotp: vi.fn(),+}));++vi.mock('@/lib/password', () => ({+ checkPassword: vi.fn(),+}));++vi.mock('@/queries/prisma/user', () => ({+ getUser: vi.fn(),+}));++import { POST } from './route';++beforeEach(() => {+ mocks.parseRequest.mockReset();+ mocks.isTwoFactorConfigured.mockReset();++ mocks.isTwoFactorConfigured.mockReturnValue(true);+});++test('POST returns a configuration error after validating the caller', async () => {+ mocks.isTwoFactorConfigured.mockReturnValue(false);+ mocks.parseRequest.mockResolvedValue({+ auth: { user: { id: 'user-1' } },+ body: { password: 'secret', token: '123456' },+ error: undefined,+ });++ const response = await POST(new Request('http://localhost/api/2fa/disable', { method: 'POST' }));++ expect(mocks.parseRequest).toHaveBeenCalled();+ await expect(response.json()).resolves.toMatchObject({+ error: {+ code: 'two-factor-error-not-configured',+ },+ });+ expect(response.status).toBe(503);+});diff --git a/src/app/api/2fa/disable/route.ts b/src/app/api/2fa/disable/route.tsindex 27e60ca97..640abdbc0 100644--- a/src/app/api/2fa/disable/route.ts+++ b/src/app/api/2fa/disable/route.ts@@ -1,8 +1,8 @@import { z } from 'zod';import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';-import { badRequest, forbidden, json, notFound } from '@/lib/response';-import { decryptSecret } from '@/lib/two-factor/crypto';+import { badRequest, forbidden, json, notFound, serviceUnavailable } from '@/lib/response';+import { decryptSecret, getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { checkRateLimit, recordFailedAttempt, resetRateLimit } from '@/lib/two-factor/rate-limit';import { isOtpReplayed, markOtpUsed } from '@/lib/two-factor/replay-prevention';import { verifyTotp } from '@/lib/two-factor/totp';@@ -25,6 +25,10 @@ export async function POST(request: Request) {return error();}+ if (!isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+const userId = auth.user.id;const { password, token } = body;diff --git a/src/app/api/2fa/setup/confirm/route.test.ts b/src/app/api/2fa/setup/confirm/route.test.tsindex 1dfefbfa2..43325dfb2 100644--- a/src/app/api/2fa/setup/confirm/route.test.ts+++ b/src/app/api/2fa/setup/confirm/route.test.ts@@ -19,6 +19,7 @@ const mocks = vi.hoisted(() => {tx,generateBackupCodes: vi.fn(),decryptSecret: vi.fn(),+ isTwoFactorConfigured: vi.fn(),checkRateLimit: vi.fn(),recordFailedAttempt: vi.fn(),resetRateLimit: vi.fn(),@@ -49,6 +50,11 @@ vi.mock('@/lib/two-factor/backup-codes', () => ({vi.mock('@/lib/two-factor/crypto', () => ({decryptSecret: mocks.decryptSecret,+ getTwoFactorConfigurationError: () => ({+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+ }),+ isTwoFactorConfigured: mocks.isTwoFactorConfigured,}));vi.mock('@/lib/two-factor/rate-limit', () => ({@@ -75,6 +81,7 @@ beforeEach(() => {mocks.tx.twoFactorBackupCode.createMany.mockReset();mocks.generateBackupCodes.mockReset();mocks.decryptSecret.mockReset();+ mocks.isTwoFactorConfigured.mockReset();mocks.checkRateLimit.mockReset();mocks.recordFailedAttempt.mockReset();mocks.resetRateLimit.mockReset();@@ -94,6 +101,7 @@ beforeEach(() => {hashed: ['hash-1', 'hash-2'],});mocks.decryptSecret.mockReturnValue('plain-secret');+ mocks.isTwoFactorConfigured.mockReturnValue(true);mocks.checkRateLimit.mockResolvedValue({ allowed: true });mocks.recordFailedAttempt.mockResolvedValue({ lockedUntil: undefined });mocks.resetRateLimit.mockResolvedValue(undefined);@@ -134,6 +142,23 @@ test('POST confirms setup, enables 2FA, stores backup codes, and resets the rateexpect(response.status).toBe(200);});+test('POST reports a configuration error when the encryption key is missing', async () => {+ mocks.isTwoFactorConfigured.mockReturnValue(false);++ const response = await POST(+ new Request('http://localhost/api/2fa/setup/confirm', { method: 'POST' }),+ );++ expect(mocks.checkRateLimit).not.toHaveBeenCalled();+ expect(mocks.decryptSecret).not.toHaveBeenCalled();+ await expect(response.json()).resolves.toMatchObject({+ error: {+ code: 'two-factor-error-not-configured',+ },+ });+ expect(response.status).toBe(503);+});+test('POST records a failed attempt and skips writes when the token is invalid', async () => {mocks.verifyTotp.mockResolvedValue(false);diff --git a/src/app/api/2fa/setup/confirm/route.ts b/src/app/api/2fa/setup/confirm/route.tsindex ca3a6a6db..3b4987138 100644--- a/src/app/api/2fa/setup/confirm/route.ts+++ b/src/app/api/2fa/setup/confirm/route.ts@@ -1,9 +1,9 @@import { z } from 'zod';import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';-import { badRequest, json, notFound } from '@/lib/response';+import { badRequest, json, notFound, serviceUnavailable } from '@/lib/response';import { generateBackupCodes } from '@/lib/two-factor/backup-codes';-import { decryptSecret } from '@/lib/two-factor/crypto';+import { decryptSecret, getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { checkRateLimit, recordFailedAttempt, resetRateLimit } from '@/lib/two-factor/rate-limit';import { isOtpReplayed, markOtpUsed } from '@/lib/two-factor/replay-prevention';import { verifyTotp } from '@/lib/two-factor/totp';@@ -21,6 +21,10 @@ export async function POST(request: Request) {return error();}+ if (!isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+const userId = auth.user.id;const { token } = body;diff --git a/src/app/api/2fa/setup/initiate/route.test.ts b/src/app/api/2fa/setup/initiate/route.test.tsindex 055cb8d3f..018aeacb5 100644--- a/src/app/api/2fa/setup/initiate/route.test.ts+++ b/src/app/api/2fa/setup/initiate/route.test.ts@@ -34,6 +34,10 @@ vi.mock('@/lib/prisma', () => ({vi.mock('@/lib/two-factor/crypto', () => ({encryptSecret: mocks.encryptSecret,+ getTwoFactorConfigurationError: () => ({+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+ }),isTwoFactorConfigured: mocks.isTwoFactorConfigured,}));diff --git a/src/app/api/2fa/setup/initiate/route.ts b/src/app/api/2fa/setup/initiate/route.tsindex 2ad68da61..ed98db21f 100644--- a/src/app/api/2fa/setup/initiate/route.ts+++ b/src/app/api/2fa/setup/initiate/route.ts@@ -1,6 +1,10 @@import { parseRequest } from '@/lib/request';import { badRequest, json, notFound, serviceUnavailable } from '@/lib/response';-import { encryptSecret, isTwoFactorConfigured } from '@/lib/two-factor/crypto';+import {+ encryptSecret,+ getTwoFactorConfigurationError,+ isTwoFactorConfigured,+} from '@/lib/two-factor/crypto';import {generateOtpAuthUri,generateQrCodeDataUrl,@@ -22,10 +26,7 @@ export async function POST(request: Request) {// Secrets cannot be stored without an encryption keyif (!isTwoFactorConfigured()) {- return serviceUnavailable({- code: 'two-factor-error-not-configured',- message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',- });+ return serviceUnavailable(getTwoFactorConfigurationError());}const userId = auth.user.id;diff --git a/src/app/api/2fa/status/route.test.ts b/src/app/api/2fa/status/route.test.tsindex c1e4f090d..42522809b 100644--- a/src/app/api/2fa/status/route.test.ts+++ b/src/app/api/2fa/status/route.test.ts@@ -1,9 +1,15 @@import { beforeEach, expect, test, vi } from 'vitest';-import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';import { GET } from './route';const KEY = 'a'.repeat(64);+const mocks = vi.hoisted(() => ({+ findTwoFactorAuth: vi.fn(),+ findAppSetting: vi.fn(),+ findUser: vi.fn(),+ findTeamUsers: vi.fn(),+ findTeams: vi.fn(),+}));vi.mock('@/lib/request', () => ({parseRequest: vi.fn(),@@ -13,35 +19,34 @@ vi.mock('@/lib/prisma', () => ({default: {client: {twoFactorAuth: {- findUnique: vi.fn(),+ findUnique: mocks.findTwoFactorAuth,},appSetting: {- findUnique: vi.fn(),+ findUnique: mocks.findAppSetting,},user: {- findUnique: vi.fn(),+ findUnique: mocks.findUser,},teamUser: {- findMany: vi.fn(),+ findMany: mocks.findTeamUsers,},team: {- findMany: vi.fn(),+ findMany: mocks.findTeams,},},},}));const parseRequestMock = vi.mocked(parseRequest);-const prismaMock = vi.mocked(prisma, true);beforeEach(() => {vi.unstubAllEnvs();parseRequestMock.mockReset();- prismaMock.client.twoFactorAuth.findUnique.mockReset();- prismaMock.client.appSetting.findUnique.mockReset();- prismaMock.client.user.findUnique.mockReset();- prismaMock.client.teamUser.findMany.mockReset();- prismaMock.client.team.findMany.mockReset();+ mocks.findTwoFactorAuth.mockReset();+ mocks.findAppSetting.mockReset();+ mocks.findUser.mockReset();+ mocks.findTeamUsers.mockReset();+ mocks.findTeams.mockReset();parseRequestMock.mockResolvedValue({auth: {@@ -51,14 +56,14 @@ beforeEach(() => {},error: undefined,});- prismaMock.client.twoFactorAuth.findUnique.mockResolvedValue(null as any);- prismaMock.client.appSetting.findUnique.mockResolvedValue({+ mocks.findTwoFactorAuth.mockResolvedValue(null as any);+ mocks.findAppSetting.mockResolvedValue({key: 'twoFactorRequiredGlobal',value: 'true',} as any);- prismaMock.client.user.findUnique.mockResolvedValue({ twoFactorRequired: false } as any);- prismaMock.client.teamUser.findMany.mockResolvedValue([] as any);- prismaMock.client.team.findMany.mockResolvedValue([] as any);+ mocks.findUser.mockResolvedValue({ twoFactorRequired: false } as any);+ mocks.findTeamUsers.mockResolvedValue([] as any);+ mocks.findTeams.mockResolvedValue([] as any);});test('GET requires 2FA when it is globally enabled', async () => {@@ -69,6 +74,8 @@ test('GET requires 2FA when it is globally enabled', async () => {await expect(response.json()).resolves.toEqual({isEnabled: false,isRequired: true,+ isConfigured: true,+ globalRequired: true,requiredReason: 'global',});expect(response.status).toBe(200);@@ -79,10 +86,11 @@ test('GET does not require 2FA when the encryption key is missing', async () =>const response = await GET(new Request('http://localhost/api/2fa/status'));- expect(prismaMock.client.appSetting.findUnique).not.toHaveBeenCalled();await expect(response.json()).resolves.toEqual({isEnabled: false,isRequired: false,+ isConfigured: false,+ globalRequired: true,requiredReason: null,});expect(response.status).toBe(200);diff --git a/src/app/api/2fa/status/route.ts b/src/app/api/2fa/status/route.tsindex 57aa781bf..6666d142d 100644--- a/src/app/api/2fa/status/route.ts+++ b/src/app/api/2fa/status/route.ts@@ -11,7 +11,13 @@ export async function GET(request: Request) {}if (process.env.CLOUD_MODE) {- return json({ isEnabled: false, isRequired: false, requiredReason: null });+ return json({+ isEnabled: false,+ isRequired: false,+ requiredReason: null,+ isConfigured: false,+ globalRequired: false,+ });}const userId = auth.user.id;@@ -19,17 +25,30 @@ export async function GET(request: Request) {const twoFactor = await prisma.client.twoFactorAuth.findUnique({ where: { userId } });const isEnabled = twoFactor?.isEnabled ?? false;- // 2FA cannot be set up without an encryption key, so it is never required- if (!isTwoFactorConfigured()) {- return json({ isEnabled, isRequired: false, requiredReason: null });- }-- // Globally requiredconst globalSetting = await prisma.client.appSetting.findUnique({where: { key: 'twoFactorRequiredGlobal' },});const isGlobalRequired = globalSetting?.value === 'true';- if (isGlobalRequired) return json({ isEnabled, isRequired: true, requiredReason: 'global' });++ // 2FA cannot be set up without an encryption key, so it is never required+ if (!isTwoFactorConfigured()) {+ return json({+ isEnabled,+ isRequired: false,+ requiredReason: null,+ isConfigured: false,+ globalRequired: isGlobalRequired,+ });+ }+ if (isGlobalRequired) {+ return json({+ isEnabled,+ isRequired: true,+ requiredReason: 'global',+ isConfigured: true,+ globalRequired: true,+ });+ }// Required for this userconst userRecord = await prisma.client.user.findUnique({@@ -37,7 +56,15 @@ export async function GET(request: Request) {select: { twoFactorRequired: true },});const isUserRequired = userRecord?.twoFactorRequired ?? false;- if (isUserRequired) return json({ isEnabled, isRequired: true, requiredReason: 'user' });+ if (isUserRequired) {+ return json({+ isEnabled,+ isRequired: true,+ requiredReason: 'user',+ isConfigured: true,+ globalRequired: false,+ });+ }// Required for this user's teamsconst userTeams = await prisma.client.teamUser.findMany({ where: { userId } });@@ -48,7 +75,21 @@ export async function GET(request: Request) {}): [];const isTeamRequired = teamsWithRequirement.length > 0;- if (isTeamRequired) return json({ isEnabled, isRequired: true, requiredReason: 'team' });+ if (isTeamRequired) {+ return json({+ isEnabled,+ isRequired: true,+ requiredReason: 'team',+ isConfigured: true,+ globalRequired: false,+ });+ }- return json({ isEnabled, isRequired: false, requiredReason: null });+ return json({+ isEnabled,+ isRequired: false,+ requiredReason: null,+ isConfigured: true,+ globalRequired: false,+ });}diff --git a/src/app/api/2fa/verify/route.test.ts b/src/app/api/2fa/verify/route.test.tsindex c9c63f331..650d98fb9 100644--- a/src/app/api/2fa/verify/route.test.ts+++ b/src/app/api/2fa/verify/route.test.ts@@ -12,6 +12,7 @@ const mocks = vi.hoisted(() => ({updateBackupCodes: vi.fn(),verifyBackupCode: vi.fn(),decryptSecret: vi.fn(),+ isTwoFactorConfigured: vi.fn(),checkRateLimit: vi.fn(),recordFailedAttempt: vi.fn(),resetRateLimit: vi.fn(),@@ -60,6 +61,11 @@ vi.mock('@/lib/two-factor/backup-codes', () => ({vi.mock('@/lib/two-factor/crypto', () => ({decryptSecret: mocks.decryptSecret,+ getTwoFactorConfigurationError: () => ({+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+ }),+ isTwoFactorConfigured: mocks.isTwoFactorConfigured,}));vi.mock('@/lib/two-factor/rate-limit', () => ({@@ -97,6 +103,7 @@ beforeEach(() => {mocks.updateBackupCodes.mockReset();mocks.verifyBackupCode.mockReset();mocks.decryptSecret.mockReset();+ mocks.isTwoFactorConfigured.mockReset();mocks.checkRateLimit.mockReset();mocks.recordFailedAttempt.mockReset();mocks.resetRateLimit.mockReset();@@ -118,6 +125,7 @@ beforeEach(() => {mocks.findTwoFactorAuth.mockResolvedValue({ userId: 'user-1', isEnabled: true, secret: 'encrypted' });mocks.createSecureToken.mockReturnValue('full-auth-token');mocks.decryptSecret.mockReturnValue('plain-secret');+ mocks.isTwoFactorConfigured.mockReturnValue(true);mocks.checkRateLimit.mockResolvedValue({ allowed: true });mocks.recordFailedAttempt.mockResolvedValue({ lockedUntil: undefined });mocks.resetRateLimit.mockResolvedValue(undefined);@@ -153,3 +161,26 @@ test('POST accepts a token-only payload and completes 2FA verification', async (});expect(response.status).toBe(200);});++test('POST returns a configuration error when the encryption key is missing', async () => {+ mocks.isTwoFactorConfigured.mockReturnValue(false);++ const response = await POST(+ new Request('http://localhost/api/2fa/verify', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Authorization: 'Bearer partial-token',+ },+ body: JSON.stringify({ token: '123456' }),+ }),+ );++ expect(mocks.findTwoFactorAuth).not.toHaveBeenCalled();+ await expect(response.json()).resolves.toMatchObject({+ error: {+ code: 'two-factor-error-not-configured',+ },+ });+ expect(response.status).toBe(503);+});diff --git a/src/app/api/2fa/verify/route.ts b/src/app/api/2fa/verify/route.tsindex 14f45f7a3..b3c92fad1 100644--- a/src/app/api/2fa/verify/route.ts+++ b/src/app/api/2fa/verify/route.ts@@ -5,9 +5,9 @@ import { ROLES } from '@/lib/constants';import { secret } from '@/lib/crypto';import { createSecureToken, parseSecureToken } from '@/lib/jwt';import { parseRequest } from '@/lib/request';-import { badRequest, json, notFound, unauthorized } from '@/lib/response';+import { badRequest, json, notFound, serviceUnavailable, unauthorized } from '@/lib/response';import { verifyBackupCode } from '@/lib/two-factor/backup-codes';-import { decryptSecret } from '@/lib/two-factor/crypto';+import { decryptSecret, getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { checkRateLimit, recordFailedAttempt, resetRateLimit } from '@/lib/two-factor/rate-limit';import { isOtpReplayed, markOtpUsed } from '@/lib/two-factor/replay-prevention';import { verifyTotp } from '@/lib/two-factor/totp';@@ -34,6 +34,10 @@ export async function POST(request: Request) {return unauthorized({ code: 'two-factor-error-invalid-partial-token' });}+ if (!isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+const { body, error } = await parseRequest(request, schema, { skipAuth: true });if (error) {return error();diff --git a/src/app/api/admin/2fa/global/route.ts b/src/app/api/admin/2fa/global/route.tsindex 142b89e6e..96f64be67 100644--- a/src/app/api/admin/2fa/global/route.ts+++ b/src/app/api/admin/2fa/global/route.ts@@ -1,7 +1,8 @@import { z } from 'zod';import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';-import { json, notFound, unauthorized } from '@/lib/response';+import { json, notFound, serviceUnavailable, unauthorized } from '@/lib/response';+import { getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { canEnforceTwoFactorAuthForEveryone } from '@/permissions';export async function POST(request: Request) {@@ -23,6 +24,10 @@ export async function POST(request: Request) {const { required } = body;+ if (required && !isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+await prisma.client.appSetting.upsert({where: { key: 'twoFactorRequiredGlobal' },update: { value: String(required) },diff --git a/src/app/api/admin/teams/[teamId]/2fa/route.ts b/src/app/api/admin/teams/[teamId]/2fa/route.tsindex 58cb2aab1..306c4011c 100644--- a/src/app/api/admin/teams/[teamId]/2fa/route.ts+++ b/src/app/api/admin/teams/[teamId]/2fa/route.ts@@ -1,7 +1,8 @@import { z } from 'zod';import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';-import { json, notFound, unauthorized } from '@/lib/response';+import { json, notFound, serviceUnavailable, unauthorized } from '@/lib/response';+import { getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { canEnforceTwoFactorAuthForTeam } from '@/permissions';export async function POST(request: Request, { params }: { params: Promise<{ teamId: string }> }) {@@ -24,6 +25,10 @@ export async function POST(request: Request, { params }: { params: Promise<{ tea}const { required } = body;+ if (required && !isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+await prisma.client.team.update({where: { id: teamId },data: { twoFactorRequired: required },diff --git a/src/app/api/admin/users/[userId]/2fa/route.test.ts b/src/app/api/admin/users/[userId]/2fa/route.test.tsindex 763e6e0fa..ed70f24e5 100644--- a/src/app/api/admin/users/[userId]/2fa/route.test.ts+++ b/src/app/api/admin/users/[userId]/2fa/route.test.ts@@ -2,6 +2,7 @@ import { beforeEach, expect, test, vi } from 'vitest';import { canEnforceTwoFactorAuthForUser } from '@/permissions';import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';+import { isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { updateUser } from '@/queries/prisma/user';import { DELETE, GET, POST } from './route';@@ -17,6 +18,14 @@ vi.mock('@/queries/prisma/user', () => ({updateUser: vi.fn(),}));+vi.mock('@/lib/two-factor/crypto', () => ({+ getTwoFactorConfigurationError: () => ({+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+ }),+ isTwoFactorConfigured: vi.fn(),+}));+vi.mock('@/lib/prisma', () => ({default: {client: {@@ -40,12 +49,14 @@ vi.mock('@/lib/prisma', () => ({const parseRequestMock = vi.mocked(parseRequest);const canEnforceTwoFactorAuthForUserMock = vi.mocked(canEnforceTwoFactorAuthForUser);+const isTwoFactorConfiguredMock = vi.mocked(isTwoFactorConfigured);const updateUserMock = vi.mocked(updateUser);const prismaMock = vi.mocked(prisma, true);beforeEach(() => {parseRequestMock.mockReset();canEnforceTwoFactorAuthForUserMock.mockReset();+ isTwoFactorConfiguredMock.mockReset();updateUserMock.mockReset();prismaMock.client.twoFactorAuth.findUnique.mockReset();prismaMock.client.twoFactorAuth.deleteMany.mockReset();@@ -64,6 +75,7 @@ beforeEach(() => {error: undefined,});canEnforceTwoFactorAuthForUserMock.mockResolvedValue(true);+ isTwoFactorConfiguredMock.mockReturnValue(true);});test('GET returns whether 2FA is enabled for the target user', async () => {@@ -108,6 +120,34 @@ test('POST updates the user-level 2FA requirement flag', async () => {expect(response.status).toBe(200);});+test('POST rejects enabling a user-level 2FA requirement when the encryption key is missing', async () => {+ parseRequestMock.mockResolvedValue({+ auth: {+ user: {+ id: 'admin-1',+ isAdmin: true,+ },+ },+ body: {+ required: true,+ },+ error: undefined,+ });+ isTwoFactorConfiguredMock.mockReturnValue(false);++ const response = await POST(new Request('http://localhost/api/admin/users/user-1/2fa', { method: 'POST' }), {+ params: Promise.resolve({ userId: 'user-1' }),+ });++ expect(updateUserMock).not.toHaveBeenCalled();+ await expect(response.json()).resolves.toMatchObject({+ error: {+ code: 'two-factor-error-not-configured',+ },+ });+ expect(response.status).toBe(503);+});+test('DELETE clears the user 2FA configuration and related support tables', async () => {prismaMock.client.twoFactorAuth.deleteMany.mockResolvedValue({ count: 1 } as any);prismaMock.client.twoFactorBackupCode.deleteMany.mockResolvedValue({ count: 8 } as any);diff --git a/src/app/api/admin/users/[userId]/2fa/route.ts b/src/app/api/admin/users/[userId]/2fa/route.tsindex c2565a875..32828d1b4 100644--- a/src/app/api/admin/users/[userId]/2fa/route.ts+++ b/src/app/api/admin/users/[userId]/2fa/route.ts@@ -1,7 +1,8 @@import { z } from 'zod';import prisma from '@/lib/prisma';import { parseRequest } from '@/lib/request';-import { json, notFound, unauthorized } from '@/lib/response';+import { json, notFound, serviceUnavailable, unauthorized } from '@/lib/response';+import { getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { updateUser } from '@/queries/prisma/user';import { canEnforceTwoFactorAuthForUser } from '@/permissions';@@ -47,6 +48,10 @@ export async function POST(request: Request, { params }: { params: Promise<{ useconst { userId } = await params;const { required } = body;+ if (required && !isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+const user = await updateUser(userId, { twoFactorRequired: required });return json({ ok: true, userId: user.id, twoFactorRequired: required });diff --git a/src/app/api/auth/login/route.test.ts b/src/app/api/auth/login/route.test.tsnew file mode 100644index 000000000..649bcb135--- /dev/null+++ b/src/app/api/auth/login/route.test.ts@@ -0,0 +1,108 @@+import { beforeEach, expect, test, vi } from 'vitest';++const mocks = vi.hoisted(() => ({+ parseRequest: vi.fn(),+ getUserByUsername: vi.fn(),+ checkPassword: vi.fn(),+ findTwoFactorAuth: vi.fn(),+ createSecureToken: vi.fn(),+ secret: vi.fn(),+ hash: vi.fn(),+ getAllUserTeams: vi.fn(),+ saveAuth: vi.fn(),+ isTwoFactorConfigured: vi.fn(),+}));++vi.mock('@/lib/request', () => ({+ parseRequest: mocks.parseRequest,+}));++vi.mock('@/queries/prisma', () => ({+ getAllUserTeams: mocks.getAllUserTeams,+ getUserByUsername: mocks.getUserByUsername,+}));++vi.mock('@/lib/password', () => ({+ checkPassword: mocks.checkPassword,+}));++vi.mock('@/lib/prisma', () => ({+ default: {+ client: {+ twoFactorAuth: {+ findUnique: mocks.findTwoFactorAuth,+ },+ },+ },+}));++vi.mock('@/lib/jwt', () => ({+ createSecureToken: mocks.createSecureToken,+}));++vi.mock('@/lib/crypto', () => ({+ hash: mocks.hash,+ secret: mocks.secret,+}));++vi.mock('@/lib/auth', () => ({+ saveAuth: mocks.saveAuth,+}));++vi.mock('@/lib/redis', () => ({+ default: {+ enabled: false,+ },+}));++vi.mock('@/lib/two-factor/crypto', () => ({+ getTwoFactorConfigurationError: () => ({+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+ }),+ isTwoFactorConfigured: mocks.isTwoFactorConfigured,+}));++import { POST } from './route';++beforeEach(() => {+ mocks.parseRequest.mockReset();+ mocks.getUserByUsername.mockReset();+ mocks.checkPassword.mockReset();+ mocks.findTwoFactorAuth.mockReset();+ mocks.createSecureToken.mockReset();+ mocks.secret.mockReset();+ mocks.hash.mockReset();+ mocks.getAllUserTeams.mockReset();+ mocks.saveAuth.mockReset();+ mocks.isTwoFactorConfigured.mockReset();++ mocks.parseRequest.mockResolvedValue({+ body: { username: 'alice', password: 'secret' },+ error: undefined,+ });+ mocks.getUserByUsername.mockResolvedValue({+ id: 'user-1',+ username: 'alice',+ password: 'hashed-password',+ role: 'admin',+ createdAt: new Date('2026-08-01T00:00:00.000Z'),+ });+ mocks.checkPassword.mockReturnValue(true);+ mocks.findTwoFactorAuth.mockResolvedValue({ userId: 'user-1', isEnabled: true });+ mocks.isTwoFactorConfigured.mockReturnValue(true);+});++test('POST returns a configuration error instead of partial auth when 2FA is enabled but unavailable', async () => {+ mocks.isTwoFactorConfigured.mockReturnValue(false);++ const response = await POST(new Request('http://localhost/api/auth/login', { method: 'POST' }));++ expect(mocks.createSecureToken).not.toHaveBeenCalled();+ await expect(response.json()).resolves.toMatchObject({+ error: {+ code: 'two-factor-error-not-configured',+ },+ });+ expect(response.status).toBe(503);+});diff --git a/src/app/api/auth/login/route.ts b/src/app/api/auth/login/route.tsindex 208717f17..bb63e0fba 100644--- a/src/app/api/auth/login/route.ts+++ b/src/app/api/auth/login/route.ts@@ -7,7 +7,8 @@ import { checkPassword } from '@/lib/password';import prisma from '@/lib/prisma';import redis from '@/lib/redis';import { parseRequest } from '@/lib/request';-import { json, unauthorized } from '@/lib/response';+import { json, serviceUnavailable, unauthorized } from '@/lib/response';+import { getTwoFactorConfigurationError, isTwoFactorConfigured } from '@/lib/two-factor/crypto';import { getAllUserTeams, getUserByUsername } from '@/queries/prisma';export async function POST(request: Request) {@@ -39,6 +40,10 @@ export async function POST(request: Request) {: null;if (twoFactor?.isEnabled) {+ if (!isTwoFactorConfigured()) {+ return serviceUnavailable(getTwoFactorConfigurationError());+ }+const partialToken = createSecureToken({ userId: id, type: 'partial-auth' }, secret(), {expiresIn: '5m',});diff --git a/src/components/hooks/queries/useTwoFactorStatusQuery.ts b/src/components/hooks/queries/useTwoFactorStatusQuery.tsindex 17720fece..2f09feed0 100644--- a/src/components/hooks/queries/useTwoFactorStatusQuery.ts+++ b/src/components/hooks/queries/useTwoFactorStatusQuery.ts@@ -1,9 +1,17 @@import { useApi } from '../useApi';+export interface TwoFactorStatusData {+ isEnabled: boolean;+ isRequired: boolean;+ isConfigured: boolean;+ globalRequired: boolean;+ requiredReason: 'global' | 'user' | 'team' | null;+}+export function useTwoFactorStatusQuery(enabled: boolean) {const { get, useQuery } = useApi();- return useQuery({+ return useQuery<TwoFactorStatusData>({queryKey: ['2fa-status'],queryFn: () => get('/2fa/status'),enabled,diff --git a/src/lib/two-factor/crypto.ts b/src/lib/two-factor/crypto.tsindex 097c8b26a..52fba6db8 100644--- a/src/lib/two-factor/crypto.ts+++ b/src/lib/two-factor/crypto.ts@@ -2,6 +2,10 @@ import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';const ALGORITHM = 'aes-256-gcm';const KEY_REGEX = /^[0-9a-fA-F]{64}$/;+const TWO_FACTOR_CONFIGURATION_ERROR = {+ code: 'two-factor-error-not-configured',+ message: 'TWO_FACTOR_ENCRYPTION_KEY is missing or invalid',+} as const;/** Checks that TWO_FACTOR_ENCRYPTION_KEY holds a valid 256-bit key, without throwing. */export function isTwoFactorConfigured(): boolean {@@ -9,10 +13,14 @@ export function isTwoFactorConfigured(): boolean {return !!hex && KEY_REGEX.test(hex);}+export function getTwoFactorConfigurationError() {+ return TWO_FACTOR_CONFIGURATION_ERROR;+}+/** Loads and validates the 256-bit encryption key from TWO_FACTOR_ENCRYPTION_KEY. */function getKey(): Buffer {if (!isTwoFactorConfigured()) {- throw new Error('TWO_FACTOR_ENCRYPTION_KEY is missing or invalid');+ throw new Error(TWO_FACTOR_CONFIGURATION_ERROR.message);}return Buffer.from(process.env.TWO_FACTOR_ENCRYPTION_KEY, 'hex');}