🔑 fix: Require OTP Verification for 2FA Re-Enrollment and Backup Code Regeneration (#12223)

* fix: require OTP verification for 2FA re-enrollment and backup code regeneration

* fix: require OTP verification for account deletion when 2FA is enabled

* refactor: Improve code formatting and readability in TwoFactorController and UserController

- Reformatted code in TwoFactorController and UserController for better readability by aligning parameters and breaking long lines.
- Updated test cases in deleteUser.spec.js and TwoFactorController.spec.js to enhance clarity by formatting object parameters consistently.

* refactor: Consolidate OTP and backup code verification logic in TwoFactorController and UserController

- Introduced a new `verifyOTPOrBackupCode` function to streamline the verification process for TOTP tokens and backup codes across multiple controllers.
- Updated the `enable2FA`, `disable2FA`, and `deleteUserController` methods to utilize the new verification function, enhancing code reusability and readability.
- Adjusted related tests to reflect the changes in verification logic, ensuring consistent behavior across different scenarios.
- Improved error handling and response messages for verification failures, providing clearer feedback to users.

* chore: linting

* refactor: Update BackupCodesItem component to enhance OTP verification logic

- Consolidated OTP input handling by moving the 2FA verification UI logic to a more consistent location within the component.
- Improved the state management for OTP readiness, ensuring the regenerate button is only enabled when the OTP is ready.
- Cleaned up imports by removing redundant type imports, enhancing code clarity and maintainability.

* chore: lint

* fix: stage 2FA re-enrollment in pending fields to prevent disarmament window

enable2FA now writes to pendingTotpSecret/pendingBackupCodes instead of
overwriting the live fields. confirm2FA performs the atomic swap only after
the new TOTP code is verified. If the user abandons mid-flow, their
existing 2FA remains active and intact.

api/server/services/twoFactorService.js

@@ -153,9 +153,11 @@ const generateBackupCodes = async (count = 10) => {
  * @param {Object} params
  * @param {Object} params.user
  * @param {string} params.backupCode
+ * @param {boolean} [params.persist=true] - Whether to persist the used-mark to the database.
+ *   Pass `false` when the caller will immediately overwrite `backupCodes` (e.g. re-enrollment).
  * @returns {Promise<boolean>}
  */
-const verifyBackupCode = async ({ user, backupCode }) => {
+const verifyBackupCode = async ({ user, backupCode, persist = true }) => {
   if (!backupCode || !user || !Array.isArray(user.backupCodes)) {
     return false;
   }
@@ -165,17 +167,50 @@ const verifyBackupCode = async ({ user, backupCode }) => {
     (codeObj) => codeObj.codeHash === hashedInput && !codeObj.used,
   );
 
-  if (matchingCode) {
+  if (!matchingCode) {
+    return false;
+  }
+
+  if (persist) {
     const updatedBackupCodes = user.backupCodes.map((codeObj) =>
       codeObj.codeHash === hashedInput && !codeObj.used
         ? { ...codeObj, used: true, usedAt: new Date() }
         : codeObj,
     );
-    // Update the user record with the marked backup code.
     await updateUser(user._id, { backupCodes: updatedBackupCodes });
-    return true;
   }
-  return false;
+  return true;
+};
+
+/**
+ * Verifies a user's identity via TOTP token or backup code.
+ * @param {Object} params
+ * @param {Object} params.user - The user document (must include totpSecret and backupCodes).
+ * @param {string} [params.token] - A 6-digit TOTP token.
+ * @param {string} [params.backupCode] - An 8-character backup code.
+ * @param {boolean} [params.persistBackupUse=true] - Whether to mark the backup code as used in the DB.
+ * @returns {Promise<{ verified: boolean, status?: number, message?: string }>}
+ */
+const verifyOTPOrBackupCode = async ({ user, token, backupCode, persistBackupUse = true }) => {
+  if (!token && !backupCode) {
+    return { verified: false, status: 400 };
+  }
+
+  if (token) {
+    const secret = await getTOTPSecret(user.totpSecret);
+    if (!secret) {
+      return { verified: false, status: 400, message: '2FA secret is missing or corrupted' };
+    }
+    const ok = await verifyTOTP(secret, token);
+    return ok
+      ? { verified: true }
+      : { verified: false, status: 401, message: 'Invalid token or backup code' };
+  }
+
+  const ok = await verifyBackupCode({ user, backupCode, persist: persistBackupUse });
+  return ok
+    ? { verified: true }
+    : { verified: false, status: 401, message: 'Invalid token or backup code' };
 };
 
 /**
@@ -213,11 +248,12 @@ const generate2FATempToken = (userId) => {
 };
 
 module.exports = {
-  generateTOTPSecret,
-  generateTOTP,
-  verifyTOTP,
+  verifyOTPOrBackupCode,
+  generate2FATempToken,
   generateBackupCodes,
+  generateTOTPSecret,
   verifyBackupCode,
   getTOTPSecret,
-  generate2FATempToken,
+  generateTOTP,
+  verifyTOTP,
 };