Merge pull request #4565 from Infisical/feat/ENG-3660

Improve 2FA flow
2026-09-22 13:39:35 +00:00 · 2025-09-23 20:25:12 -03:00
parent be324a7ed5 49d9bb99bc
commit c040e7f37e
11 changed files with 461 additions and 157 deletions
--- a/backend/src/server/routes/v1/user-router.ts
+++ b/backend/src/server/routes/v1/user-router.ts
@@ -255,7 +255,9 @@ export const registerUserRouter = async (server: FastifyZodProvider) => {
        totp: z.string()
      }),
      response: {
-        200: z.object({})
+        200: z.object({
+          recoveryCodes: z.string().array()
+        })
      }
    },
    onRequest: verifyAuth([AuthMode.JWT], {
--- a/backend/src/server/routes/v2/mfa-router.ts
+++ b/backend/src/server/routes/v2/mfa-router.ts
@@ -1,5 +1,7 @@
+import { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";

+import { TUsers } from "@app/db/schemas";
 import { getConfig } from "@app/lib/config/env";
 import { crypto } from "@app/lib/crypto";
 import { BadRequestError, NotFoundError } from "@app/lib/errors";
@@ -7,11 +9,54 @@ import { mfaRateLimit } from "@app/server/config/rateLimiter";
 import { addAuthOriginDomainCookie } from "@app/server/lib/cookie";
 import { AuthModeMfaJwtTokenPayload, AuthTokenType, MfaMethod } from "@app/services/auth/auth-type";

+const handleMfaVerification = async (
+  req: FastifyRequest & { mfa: { userId: string; orgId?: string; user: TUsers } },
+  res: FastifyReply,
+  server: FastifyZodProvider,
+  mfaToken: string,
+  mfaMethod: MfaMethod,
+  isRecoveryCode?: boolean
+) => {
+  const userAgent = req.headers["user-agent"];
+  const mfaJwtToken = req.headers.authorization?.replace("Bearer ", "");
+  if (!userAgent) throw new Error("user agent header is required");
+  if (!mfaJwtToken) throw new Error("authorization header is required");
+  const appCfg = getConfig();
+
+  const { user, token } = await server.services.login.verifyMfaToken({
+    userAgent,
+    mfaJwtToken,
+    ip: req.realIp,
+    userId: req.mfa.userId,
+    orgId: req.mfa.orgId,
+    mfaToken,
+    mfaMethod,
+    isRecoveryCode
+  });
+
+  void res.setCookie("jid", token.refresh, {
+    httpOnly: true,
+    path: "/",
+    sameSite: "strict",
+    secure: appCfg.HTTPS_ENABLED
+  });
+
+  addAuthOriginDomainCookie(res);
+
+  return {
+    ...user,
+    token: token.access,
+    protectedKey: user.protectedKey || null,
+    protectedKeyIV: user.protectedKeyIV || null,
+    protectedKeyTag: user.protectedKeyTag || null
+  };
+};
+
 export const registerMfaRouter = async (server: FastifyZodProvider) => {
  const cfg = getConfig();

  server.decorateRequest("mfa", null);
-  server.addHook("preParsing", async (req, res) => {
+  server.addHook("preValidation", async (req, res) => {
    const authorizationHeader = req.headers.authorization;

    if (!authorizationHeader || !authorizationHeader.startsWith("Bearer ")) {
@@ -109,38 +154,36 @@ export const registerMfaRouter = async (server: FastifyZodProvider) => {
      }
    },
    handler: async (req, res) => {
-      const userAgent = req.headers["user-agent"];
-      const mfaJwtToken = req.headers.authorization?.replace("Bearer ", "");
-      if (!userAgent) throw new Error("user agent header is required");
-      if (!mfaJwtToken) throw new Error("authorization header is required");
-      const appCfg = getConfig();
+      return handleMfaVerification(req, res, server, req.body.mfaToken, req.body.mfaMethod);
+    }
+  });

-      const { user, token } = await server.services.login.verifyMfaToken({
-        userAgent,
-        mfaJwtToken,
-        ip: req.realIp,
-        userId: req.mfa.userId,
-        orgId: req.mfa.orgId,
-        mfaToken: req.body.mfaToken,
-        mfaMethod: req.body.mfaMethod
-      });
-
-      void res.setCookie("jid", token.refresh, {
-        httpOnly: true,
-        path: "/",
-        sameSite: "strict",
-        secure: appCfg.HTTPS_ENABLED
-      });
-
-      addAuthOriginDomainCookie(res);
-
-      return {
-        ...user,
-        token: token.access,
-        protectedKey: user.protectedKey || null,
-        protectedKeyIV: user.protectedKeyIV || null,
-        protectedKeyTag: user.protectedKeyTag || null
-      };
+  server.route({
+    url: "/mfa/verify/recovery-code",
+    method: "POST",
+    config: {
+      rateLimit: mfaRateLimit
+    },
+    schema: {
+      body: z.object({
+        recoveryCode: z.string().trim().length(8, "Recovery code must be 8 characters")
+      }),
+      response: {
+        200: z.object({
+          encryptionVersion: z.number().default(1).nullable().optional(),
+          protectedKey: z.string().nullish(),
+          protectedKeyIV: z.string().nullish(),
+          protectedKeyTag: z.string().nullish(),
+          publicKey: z.string().nullish(),
+          encryptedPrivateKey: z.string().nullish(),
+          iv: z.string().nullish(),
+          tag: z.string().nullish(),
+          token: z.string()
+        })
+      }
+    },
+    handler: async (req, res) => {
+      return handleMfaVerification(req, res, server, req.body.recoveryCode, MfaMethod.TOTP, true);
    }
  });
 };
--- a/backend/src/services/auth/auth-login-service.ts
+++ b/backend/src/services/auth/auth-login-service.ts
@@ -684,7 +684,8 @@ export const authLoginServiceFactory = ({
    mfaJwtToken,
    ip,
    userAgent,
-    orgId
+    orgId,
+    isRecoveryCode = false
  }: TVerifyMfaTokenDTO) => {
    const appCfg = getConfig();
    const user = await userDAL.findById(userId);
@@ -698,16 +699,21 @@ export const authLoginServiceFactory = ({
          code: mfaToken
        });
      } else if (mfaMethod === MfaMethod.TOTP) {
-        if (mfaToken.length === 6) {
-          await totpService.verifyUserTotp({
-            userId,
-            totp: mfaToken
-          });
-        } else {
+        if (isRecoveryCode) {
          await totpService.verifyWithUserRecoveryCode({
            userId,
            recoveryCode: mfaToken
          });
+        } else {
+          if (mfaToken.length !== 6) {
+            throw new BadRequestError({
+              message: "Please use a valid TOTP code."
+            });
+          }
+          await totpService.verifyUserTotp({
+            userId,
+            totp: mfaToken
+          });
        }
      }
    } catch (err) {
--- a/backend/src/services/auth/auth-login-type.ts
+++ b/backend/src/services/auth/auth-login-type.ts
@@ -24,6 +24,7 @@ export type TVerifyMfaTokenDTO = {
  ip: string;
  userAgent: string;
  orgId?: string;
+  isRecoveryCode?: boolean;
 };

 export type TOauthLoginDTO = {
--- a/backend/src/services/totp/totp-service.ts
+++ b/backend/src/services/totp/totp-service.ts
@@ -131,15 +131,20 @@ export const totpServiceFactory = ({ totpConfigDAL, kmsService, userDAL }: TTotp
      secret
    });

-    if (isValid) {
-      await totpConfigDAL.updateById(totpConfig.id, {
-        isVerified: true
-      });
-    } else {
+    if (!isValid) {
      throw new BadRequestError({
        message: "Invalid TOTP token"
      });
    }
+
+    await totpConfigDAL.updateById(totpConfig.id, {
+      isVerified: true
+    });
+
+    const recoveryCodes = decryptWithRoot(totpConfig.encryptedRecoveryCodes).toString().split(",");
+    return {
+      recoveryCodes
+    };
  };

  const verifyUserTotp = async ({ userId, totp }: TVerifyUserTotpDTO) => {
--- a/frontend/src/components/auth/Mfa.tsx
+++ b/frontend/src/components/auth/Mfa.tsx
@@ -5,10 +5,12 @@ import { t } from "i18next";

 import Error from "@app/components/basic/Error";
 import TotpRegistration from "@app/components/mfa/TotpRegistration";
+import { createNotification } from "@app/components/notifications";
 import SecurityClient from "@app/components/utilities/SecurityClient";
-import { Button, Input } from "@app/components/v2";
-import { useSendMfaToken } from "@app/hooks/api";
-import { checkUserTotpMfa, verifyMfaToken } from "@app/hooks/api/auth/queries";
+import { Button, Tooltip } from "@app/components/v2";
+import { isInfisicalCloud } from "@app/helpers/platform";
+import { useLogoutUser, useSendMfaToken } from "@app/hooks/api";
+import { checkUserTotpMfa, verifyMfaToken, verifyRecoveryCode } from "@app/hooks/api/auth/queries";
 import { MfaMethod } from "@app/hooks/api/auth/types";

 // The style for the verification code input
@@ -17,10 +19,10 @@ const codeInputProps = {
    fontFamily: "monospace",
    margin: "4px",
    MozAppearance: "textfield",
-    width: "48px",
+    width: "55px",
    borderRadius: "5px",
    fontSize: "24px",
-    height: "48px",
+    height: "55px",
    paddingLeft: "7",
    backgroundColor: "#0d1117",
    color: "white",
@@ -60,11 +62,13 @@ type Props = {

 export const Mfa = ({ successCallback, closeMfa, hideLogo, email, method }: Props) => {
  const [mfaCode, setMfaCode] = useState("");
+  const [showRecoveryCodeInput, setShowRecoveryCodeInput] = useState(false);
  const navigate = useNavigate();
  const [isLoading, setIsLoading] = useState(false);
  const [isLoadingResend, setIsLoadingResend] = useState(false);
  const [triesLeft, setTriesLeft] = useState<number | undefined>(undefined);
  const [shouldShowTotpRegistration, setShouldShowTotpRegistration] = useState(false);
+  const logout = useLogoutUser(true);

  const sendMfaToken = useSendMfaToken();

@@ -79,35 +83,57 @@ export const Mfa = ({ successCallback, closeMfa, hideLogo, email, method }: Prop
    }
  }, []);

+  const getExpectedCodeLength = () => {
+    if (method === MfaMethod.EMAIL) return 6;
+    if (method === MfaMethod.TOTP) return showRecoveryCodeInput ? 8 : 6;
+    return 6;
+  };
+
+  const isCodeComplete = mfaCode.length === getExpectedCodeLength();
+
  const verifyMfa = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();

+    if (!mfaCode.trim() || !isCodeComplete) return;
+
    setIsLoading(true);
    try {
-      const { token } = await verifyMfaToken({
-        email,
-        mfaCode,
-        mfaMethod: method
-      });
+      let result;
+
+      if (method === MfaMethod.TOTP && showRecoveryCodeInput) {
+        result = await verifyRecoveryCode(mfaCode.trim());
+      } else {
+        result = await verifyMfaToken({
+          email,
+          mfaCode: mfaCode.trim(),
+          mfaMethod: method
+        });
+      }

      SecurityClient.setMfaToken("");
-      SecurityClient.setToken(token);
+      SecurityClient.setToken(result.token);

      await successCallback();
      if (closeMfa) {
        closeMfa();
      }
    } catch {
-      if (triesLeft) {
-        setTriesLeft((left) => {
-          if (triesLeft === 1) {
-            navigate({ to: "/" });
-
-            SecurityClient.setMfaToken("");
-            SecurityClient.setToken("");
-          }
-          return (left as number) - 1;
-        });
+      if (typeof triesLeft === "number") {
+        const newTriesLeft = triesLeft - 1;
+        setTriesLeft(newTriesLeft);
+        if (newTriesLeft <= 0) {
+          createNotification({
+            text: "User is temporary locked due to multiple failed login attempts. Try again later. You can also reset your password now to proceed.",
+            type: "error"
+          });
+          setIsLoading(false);
+          SecurityClient.setMfaToken("");
+          SecurityClient.setToken("");
+          SecurityClient.setSignupToken("");
+          await logout.mutateAsync();
+          navigate({ to: "/login" });
+          return;
+        }
      } else {
        setTriesLeft(2);
      }
@@ -147,7 +173,7 @@ export const Mfa = ({ successCallback, closeMfa, hideLogo, email, method }: Prop
  }

  return (
-    <div className="mx-auto w-max pb-4 pt-4 md:mb-16 md:px-8">
+    <div className="mx-auto w-max pb-6 pt-6 md:mb-16 md:px-8">
      {!hideLogo && (
        <Link to="/">
          <div className="mb-4 flex justify-center">
@@ -162,79 +188,134 @@ export const Mfa = ({ successCallback, closeMfa, hideLogo, email, method }: Prop
        </>
      )}
      {method === MfaMethod.TOTP && (
-        <>
-          <p className="text-l mb-4 flex max-w-xs justify-center text-center font-bold text-bunker-100">
-            Authenticator MFA Required
+        <div className="mb-8 text-center">
+          <h2 className="mb-3 text-xl font-semibold text-bunker-100">Two-Factor Authentication</h2>
+          <p className="mx-auto max-w-md text-sm leading-relaxed text-bunker-300">
+            {showRecoveryCodeInput
+              ? "Enter one of your backup recovery codes"
+              : "Enter the verification code from your authenticator app"}
          </p>
-          <p className="text-l flex max-w-xs justify-center text-center text-bunker-300">
-            Open the authenticator app on your mobile device to get your verification code or enter
-            a recovery code.
-          </p>
-        </>
+        </div>
      )}
      <form onSubmit={verifyMfa}>
-        <div className="mx-auto hidden w-max min-w-[20rem] md:block">
+        <div className="mx-auto hidden md:block" style={{ minWidth: "600px" }}>
          {method === MfaMethod.EMAIL && (
-            <ReactCodeInput
-              name=""
-              inputMode="tel"
-              type="text"
-              fields={6}
-              onChange={setMfaCode}
-              className="mb-2 mt-6"
-              {...codeInputProps}
-            />
+            <div className="flex justify-center">
+              <ReactCodeInput
+                name=""
+                inputMode="tel"
+                type="text"
+                fields={6}
+                onChange={setMfaCode}
+                className="mb-2 mt-6"
+                {...codeInputProps}
+              />
+            </div>
          )}
          {method === MfaMethod.TOTP && (
-            <div className="mb-4 mt-6">
-              <Input value={mfaCode} onChange={(e) => setMfaCode(e.target.value)} />
+            <div className="mb-6 mt-8 flex justify-center">
+              <ReactCodeInput
+                key={showRecoveryCodeInput ? "recovery" : "totp"}
+                name=""
+                inputMode="tel"
+                type="text"
+                fields={showRecoveryCodeInput ? 8 : 6}
+                onChange={setMfaCode}
+                className="mb-2"
+                {...codeInputProps}
+              />
            </div>
          )}
        </div>
-        <div className="mx-auto mt-4 block w-max min-w-[18rem] md:hidden">
+        <div className="mx-auto mt-4 block md:hidden" style={{ minWidth: "400px" }}>
          {method === MfaMethod.EMAIL && (
-            <ReactCodeInput
-              name=""
-              inputMode="tel"
-              type="text"
-              fields={6}
-              onChange={setMfaCode}
-              className="mb-2 mt-2"
-              {...codeInputPropsPhone}
-            />
+            <div className="flex justify-center">
+              <ReactCodeInput
+                name=""
+                inputMode="tel"
+                type="text"
+                fields={6}
+                onChange={setMfaCode}
+                className="mb-2 mt-2"
+                {...codeInputPropsPhone}
+              />
+            </div>
          )}
          {method === MfaMethod.TOTP && (
-            <div className="mb-4 mt-2">
-              <Input value={mfaCode} onChange={(e) => setMfaCode(e.target.value)} />
+            <div className="mb-6 mt-4 flex justify-center">
+              <ReactCodeInput
+                key={showRecoveryCodeInput ? "recovery-mobile" : "totp-mobile"}
+                name=""
+                inputMode="tel"
+                type="text"
+                fields={showRecoveryCodeInput ? 8 : 6}
+                onChange={setMfaCode}
+                className="mb-2"
+                {...codeInputPropsPhone}
+              />
            </div>
          )}
        </div>
        {typeof triesLeft === "number" && (
          <Error text={`Invalid code. You have ${triesLeft} attempt(s) remaining.`} />
        )}
-        <div className="mx-auto mt-2 flex w-1/4 min-w-[20rem] max-w-xs flex-col items-center justify-center text-center text-sm md:max-w-md md:text-left lg:w-[19%]">
-          <div className="text-l w-full py-1 text-lg">
-            <Button
-              size="sm"
-              type="submit"
-              isFullWidth
-              className="h-14"
-              colorSchema="primary"
-              variant="outline_bg"
-              isLoading={isLoading}
-            >
-              {String(t("mfa.verify"))}
-            </Button>
-          </div>
+        <div className="mx-auto mt-6 flex w-full max-w-sm flex-col items-center justify-center text-center">
+          <Button
+            size="md"
+            type="submit"
+            isFullWidth
+            className="h-11 rounded-lg font-medium shadow-sm transition-all duration-200 hover:shadow-md"
+            colorSchema="primary"
+            variant="outline_bg"
+            isLoading={isLoading}
+            isDisabled={!isCodeComplete || (typeof triesLeft === "number" && triesLeft <= 0)}
+          >
+            {String(t("mfa.verify"))}
+          </Button>
        </div>
      </form>
      {method === MfaMethod.TOTP && (
-        <div className="mt-2 flex flex-row justify-center text-sm text-bunker-400">
-          <Link to="/verify-email">
-            <span className="cursor-pointer duration-200 hover:text-bunker-200 hover:underline hover:decoration-primary-700 hover:underline-offset-4">
-              Lost your recovery codes? Reset your account
-            </span>
-          </Link>
+        <div className="mt-6 flex flex-col items-center gap-4 text-sm">
+          <button
+            type="button"
+            onClick={() => {
+              setShowRecoveryCodeInput(!showRecoveryCodeInput);
+              setMfaCode("");
+            }}
+            className="text-bunker-400 transition-colors duration-200 hover:text-bunker-200 hover:underline hover:decoration-primary-700 hover:underline-offset-4"
+          >
+            {showRecoveryCodeInput ? "Use authenticator code" : "Use a recovery code"}
+          </button>
+          <div className="text-center text-sm">
+            <Tooltip
+              position="bottom"
+              content={
+                <div className="max-w-xs text-center text-xs">
+                  {isInfisicalCloud() ? (
+                    <>
+                      <div className="mb-2">Account Recovery Required</div>
+                      <div className="mb-2 text-gray-300">
+                        Contact support with valid proof of account ownership to initiate recovery
+                      </div>
+                      <div className="mt-1">support@infisical.com</div>
+                    </>
+                  ) : (
+                    <>
+                      <div className="mb-2">Account Recovery Required</div>
+                      <div className="text-gray-300">
+                        Contact your instance administrator with valid proof of account ownership to
+                        initiate recovery
+                      </div>
+                    </>
+                  )}
+                </div>
+              }
+            >
+              <span className="cursor-help text-bunker-400 transition-colors duration-200 hover:text-bunker-200">
+                Lost your recovery codes?
+              </span>
+            </Tooltip>
+          </div>
        </div>
      )}
      {method === MfaMethod.EMAIL && (
--- a/frontend/src/components/mfa/RecoveryCodesDownload.tsx
+++ b/frontend/src/components/mfa/RecoveryCodesDownload.tsx
@@ -0,0 +1,111 @@
+import { useState } from "react";
+import { faCopy, faDownload } from "@fortawesome/free-solid-svg-icons";
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
+
+import { Button, Modal, ModalContent } from "../v2";
+
+type Props = {
+  isOpen: boolean;
+  onClose: () => void;
+  recoveryCodes: string[];
+  onDownloadComplete: () => void;
+};
+
+export const RecoveryCodesDownload = ({
+  isOpen,
+  onClose,
+  recoveryCodes,
+  onDownloadComplete
+}: Props) => {
+  const [hasDownloaded, setHasDownloaded] = useState(false);
+  const [copied, setCopied] = useState(false);
+
+  const downloadRecoveryCodes = () => {
+    const content = [...recoveryCodes].join("\n");
+
+    const blob = new Blob([content], { type: "text/plain" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `infisical-recovery-codes-${new Date().toISOString().split("T")[0]}.txt`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+
+    setHasDownloaded(true);
+  };
+
+  const copyToClipboard = async () => {
+    const text = recoveryCodes.join("\n");
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (err) {
+      console.error("Failed to copy recovery codes:", err);
+    }
+  };
+
+  const handleClose = () => {
+    if (hasDownloaded) {
+      onDownloadComplete();
+      onClose();
+    }
+  };
+
+  return (
+    <Modal isOpen={isOpen} onOpenChange={hasDownloaded ? handleClose : () => {}}>
+      <ModalContent title="Recovery Codes" className="max-w-md">
+        <div className="space-y-4">
+          <div className="rounded border border-yellow bg-yellow/10 p-2 px-3 text-xs text-yellow">
+            Save these codes securely. Each can only be used once.
+          </div>
+
+          <div className="rounded-lg border border-mineshaft-600 bg-mineshaft-900 p-4">
+            <div className="grid grid-cols-2 gap-x-6 gap-y-2 font-mono text-sm">
+              {recoveryCodes.map((code, index) => (
+                <div key={code} className="flex items-center text-mineshaft-200">
+                  <span className="w-8 text-right text-mineshaft-400">{index + 1}.</span>
+                  <span className="pl-2">{code}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <div className="flex gap-3">
+            <Button
+              onClick={downloadRecoveryCodes}
+              className="flex flex-1 items-center justify-center gap-2"
+              colorSchema="primary"
+              variant="solid"
+            >
+              <FontAwesomeIcon icon={faDownload} className="mr-2 h-4 w-4" />
+              Download
+            </Button>
+
+            <Button
+              onClick={copyToClipboard}
+              className="flex flex-1 items-center justify-center gap-2"
+              colorSchema="secondary"
+              variant="outline"
+            >
+              <FontAwesomeIcon icon={faCopy} className="mr-2 h-4 w-4" />
+              {copied ? "Copied!" : "Copy"}
+            </Button>
+          </div>
+
+          {hasDownloaded ? (
+            <p className="text-center text-xs text-mineshaft-400">
+              Recovery codes downloaded. You can now close this modal.
+            </p>
+          ) : (
+            <p className="text-center text-xs text-mineshaft-400">
+              Download the recovery codes to continue.
+            </p>
+          )}
+        </div>
+      </ModalContent>
+    </Modal>
+  );
+};
--- a/frontend/src/components/mfa/TotpRegistration.tsx
+++ b/frontend/src/components/mfa/TotpRegistration.tsx
@@ -7,6 +7,7 @@ import { useVerifyUserTotpRegistration } from "@app/hooks/api/users/mutation";

 import { createNotification } from "../notifications";
 import { Button, ContentLoader, Input } from "../v2";
+import { RecoveryCodesDownload } from "./RecoveryCodesDownload";

 type Props = {
  onComplete?: () => Promise<void>;
@@ -19,20 +20,39 @@ const TotpRegistration = ({ onComplete, shouldCenterQr }: Props) => {
    useVerifyUserTotpRegistration();
  const [qrCodeUrl, setQrCodeUrl] = useState("");
  const [totp, setTotp] = useState("");
+  const [showRecoveryModal, setShowRecoveryModal] = useState(false);
+  const [recoveryCodes, setRecoveryCodes] = useState<string[]>([]);

  const handleTotpVerify = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
-    await verifyUserTotp({
-      totp
-    });
+    try {
+      const result = await verifyUserTotp({
+        totp
+      });

-    createNotification({
-      text: "Successfully configured mobile authenticator",
-      type: "success"
-    });
+      createNotification({
+        text: "Successfully configured mobile authenticator",
+        type: "success"
+      });

+      if (result.recoveryCodes && result.recoveryCodes.length > 0) {
+        setRecoveryCodes(result.recoveryCodes);
+        setShowRecoveryModal(true);
+      } else if (onComplete) {
+        onComplete();
+      }
+    } catch {
+      createNotification({
+        text: "Failed to verify TOTP code",
+        type: "error"
+      });
+    }
+  };
+
+  const handleRecoveryDownloadComplete = async () => {
+    setShowRecoveryModal(false);
    if (onComplete) {
-      onComplete();
+      await onComplete();
    }
  };

@@ -52,28 +72,37 @@ const TotpRegistration = ({ onComplete, shouldCenterQr }: Props) => {
  }

  return (
-    <div className="flex max-w-lg flex-col text-bunker-200">
-      <div className="mb-8">
-        1. Download a two-step verification app (Duo, Google Authenticator, etc.) and scan the QR
-        code.
-      </div>
-      <div className={twMerge("mb-8 flex items-center", shouldCenterQr && "justify-center")}>
-        <img src={qrCodeUrl} alt="registration-qr" />
-      </div>
-      <form onSubmit={handleTotpVerify}>
-        <div className="mb-4">2. Enter the resulting verification code</div>
-        <div className="mb-4 flex flex-row gap-2">
-          <Input
-            onChange={(e) => setTotp(e.target.value)}
-            value={totp}
-            placeholder="Verification code"
-          />
-          <Button isLoading={isVerifyLoading} type="submit">
-            Enable MFA
-          </Button>
+    <>
+      <div className="flex max-w-lg flex-col text-bunker-200">
+        <div className="mb-8">
+          1. Download a two-step verification app (Duo, Google Authenticator, etc.) and scan the QR
+          code.
        </div>
-      </form>
-    </div>
+        <div className={twMerge("mb-8 flex items-center", shouldCenterQr && "justify-center")}>
+          <img src={qrCodeUrl} alt="registration-qr" />
+        </div>
+        <form onSubmit={handleTotpVerify}>
+          <div className="mb-4">2. Enter the resulting verification code</div>
+          <div className="mb-4 flex flex-row gap-2">
+            <Input
+              onChange={(e) => setTotp(e.target.value)}
+              value={totp}
+              placeholder="Verification code"
+            />
+            <Button isLoading={isVerifyLoading} type="submit">
+              Enable MFA
+            </Button>
+          </div>
+        </form>
+      </div>
+
+      <RecoveryCodesDownload
+        isOpen={showRecoveryModal}
+        onClose={() => setShowRecoveryModal(false)}
+        recoveryCodes={recoveryCodes}
+        onDownloadComplete={handleRecoveryDownloadComplete}
+      />
+    </>
  );
 };

--- a/frontend/src/hooks/api/auth/queries.tsx
+++ b/frontend/src/hooks/api/auth/queries.tsx
@@ -183,6 +183,13 @@ export const useVerifyMfaToken = () => {
  });
 };

+export const verifyRecoveryCode = async (recoveryCode: string) => {
+  const { data } = await apiRequest.post("/api/v2/auth/mfa/verify/recovery-code", {
+    recoveryCode
+  });
+  return data;
+};
+
 export const verifySignupInvite = async (details: VerifySignupInviteDTO) => {
  const { data } = await apiRequest.post("/api/v1/invite-org/verify", details);
  return data;
--- a/frontend/src/hooks/api/users/mutation.tsx
+++ b/frontend/src/hooks/api/users/mutation.tsx
@@ -77,13 +77,16 @@ export const useUpdateUserProjectFavorites = () => {
 };

 export const useVerifyUserTotpRegistration = () => {
-  return useMutation({
+  return useMutation<{ recoveryCodes: string[] }, unknown, { totp: string }>({
    mutationFn: async ({ totp }: { totp: string }) => {
-      await apiRequest.post("/api/v1/user/me/totp/verify", {
-        totp
-      });
+      const { data } = await apiRequest.post<{ recoveryCodes: string[] }>(
+        "/api/v1/user/me/totp/verify",
+        {
+          totp
+        }
+      );

-      return {};
+      return data;
    }
  });
 };
--- a/frontend/src/pages/auth/SelectOrgPage/SelectOrgSection.tsx
+++ b/frontend/src/pages/auth/SelectOrgPage/SelectOrgSection.tsx
@@ -117,12 +117,28 @@ export const SelectOrganizationSection = () => {
        }
      }

-      const { token, isMfaEnabled, mfaMethod } = await selectOrg
-        .mutateAsync({
+      let token;
+      let isMfaEnabled;
+      let mfaMethod;
+
+      try {
+        const result = await selectOrg.mutateAsync({
          organizationId: organization.id,
          userAgent: callbackPort ? UserAgentType.CLI : undefined
-        })
-        .finally(() => setIsInitialOrgCheckLoading(false));
+        });
+        token = result.token;
+        isMfaEnabled = result.isMfaEnabled;
+        mfaMethod = result.mfaMethod;
+      } catch (error: any) {
+        setIsInitialOrgCheckLoading(false);
+        if (error?.response?.status === 403) {
+          await handleLogout();
+          return;
+        }
+        throw error;
+      } finally {
+        setIsInitialOrgCheckLoading(false);
+      }

      await router.invalidate();