🔒 feat: Two-Factor Authentication with Backup Codes & QR support

api/models/schema/userSchema.js

@@ -39,6 +39,12 @@ const Session = mongoose.Schema({
   },
 });
 
+const backupCodeSchema =  mongoose.Schema({
+  codeHash: { type: String, required: true },
+  used: { type: Boolean, default: false },
+  usedAt: { type: Date, default: null },
+});
+
 /** @type {MongooseSchema<MongoUser>} */
 const userSchema = mongoose.Schema(
   {
@@ -121,6 +127,13 @@ const userSchema = mongoose.Schema(
       type: Array,
       default: [],
     },
+    totpSecret: {
+      type: String,
+    },
+    backupCodes: {
+      type: [backupCodeSchema],
+      default: [],
+    },
     refreshToken: {
       type: [Session],
     },

api/server/controllers/TwoFactorController.js

@@ -0,0 +1,145 @@
+const { webcrypto } = require('node:crypto');
+const {
+  generateTOTPSecret,
+  generateBackupCodes,
+  verifyTOTP,
+} = require('~/server/services/twoFactorService');
+const { updateUser, getUserById } = require('~/models');
+const { logger } = require('~/config');
+
+/**
+ * Computes SHA-256 hash for the given input using WebCrypto
+ * @param {string} input
+ * @returns {Promise<string>} - Hex hash string
+ */
+const hashBackupCode = async (input) => {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await webcrypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+};
+
+const enable2FAController = async (req, res) => {
+  const safeAppTitle = (process.env.APP_TITLE || 'LibreChat').replace(/\s+/g, '');
+
+  try {
+    const userId = req.user.id;
+    const secret = generateTOTPSecret();
+    const { plainCodes, codeObjects } = await generateBackupCodes();
+
+    const user = await updateUser(
+      userId,
+      { totpSecret: secret, backupCodes: codeObjects },
+    );
+
+    const otpauthUrl = `otpauth://totp/${safeAppTitle}:${user.email}?secret=${secret}&issuer=${safeAppTitle}`;
+
+    res.status(200).json({
+      otpauthUrl,
+      backupCodes: plainCodes,
+    });
+  } catch (err) {
+    logger.error('[enable2FAController]', err);
+    res.status(500).json({ message: err.message });
+  }
+};
+
+const verify2FAController = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    const { token, backupCode } = req.body;
+    const user = await getUserById(userId);
+    if (!user || !user.totpSecret) {
+      return res.status(400).json({ message: '2FA not initiated' });
+    }
+
+    if (token && (await verifyTOTP(user.totpSecret, token))) {
+      return res.status(200).json();
+    } else if (backupCode) {
+      const backupCodeInput = backupCode.trim();
+      const hashedInput = await hashBackupCode(backupCodeInput);
+      const matchingCode = user.backupCodes.find(
+        (codeObj) => codeObj.codeHash === hashedInput && codeObj.used === false,
+      );
+
+      if (matchingCode) {
+        const updatedBackupCodes = user.backupCodes.map((codeObj) => {
+          if (codeObj.codeHash === hashedInput && codeObj.used === false) {
+            return { ...codeObj, used: true, usedAt: new Date() };
+          }
+          return codeObj;
+        });
+
+        await updateUser(user._id, { backupCodes: updatedBackupCodes });
+        return res.status(200).json();
+      }
+    }
+
+    return res.status(400).json({ message: 'Invalid token.' });
+  } catch (err) {
+    logger.error('[verify2FAController]', err);
+    res.status(500).json({ message: err.message });
+  }
+};
+
+const confirm2FAController = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    const { token } = req.body;
+    const user = await getUserById(userId);
+
+    if (!user || !user.totpSecret) {
+      return res.status(400).json({ message: '2FA not initiated' });
+    }
+
+    if (await verifyTOTP(user.totpSecret, token)) {
+      return res.status(200).json();
+    }
+
+    return res.status(400).json({ message: 'Invalid token.' });
+  } catch (err) {
+    logger.error('[confirm2FAController]', err);
+    res.status(500).json({ message: err.message });
+  }
+};
+
+const disable2FAController = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    await updateUser(
+      userId,
+      { totpSecret: null, backupCodes: [] },
+    );
+    res.status(200).json();
+  } catch (err) {
+    logger.error('[disable2FAController]', err);
+    res.status(500).json({ message: err.message });
+  }
+};
+
+const regenerateBackupCodesController = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    const { plainCodes, codeObjects } = await generateBackupCodes();
+    await updateUser(
+      userId,
+      {  backupCodes: codeObjects },
+    );
+    res.status(200).json({
+      backupCodes: plainCodes,
+      backupCodesHash: codeObjects,
+    });
+  } catch (err) {
+    logger.error('[regenerateBackupCodesController]', err);
+    res.status(500).json({ message: err.message });
+  }
+};
+
+module.exports = {
+  enable2FAController,
+  verify2FAController,
+  confirm2FAController,
+  disable2FAController,
+  regenerateBackupCodesController,
+};

api/server/controllers/UserController.js

@@ -19,7 +19,9 @@ const { Transaction } = require('~/models/Transaction');
 const { logger } = require('~/config');
 
 const getUserController = async (req, res) => {
-  res.status(200).send(req.user);
+  const userData = req.user.toObject ? req.user.toObject() : { ...req.user };
+  delete userData.totpSecret;
+  res.status(200).send(userData);
 };
 
 const getTermsStatusController = async (req, res) => {

api/server/controllers/auth/LoginController.js

@@ -1,12 +1,19 @@
 const { setAuthTokens } = require('~/server/services/AuthService');
 const { logger } = require('~/config');
+const { generate2FATempToken } = require('~/server/services/twoFactorService');
+const { getUserById } = require('~/models');
 
 const loginController = async (req, res) => {
   try {
     if (!req.user) {
       return res.status(400).json({ message: 'Invalid credentials' });
     }
 
+    if (req.user.backupCodes.length > 0) {
+      const tempToken = generate2FATempToken(req.user._id);
+      return res.status(200).json({ twoFAPending: true, tempToken });
+    }
+
     const { password: _, __v, ...user } = req.user;
     user.id = user._id.toString();
 

api/server/controllers/auth/TwoFactorAuthController.js

@@ -0,0 +1,84 @@
+const jwt = require('jsonwebtoken');
+const { webcrypto } = require('node:crypto');
+const { verifyTOTP } = require('~/server/services/twoFactorService');
+const { setAuthTokens } = require('~/server/services/AuthService');
+const { getUserById, updateUser } = require('~/models');
+const { logger } = require('~/config');
+
+/**
+ * Computes SHA-256 hash for the given input using WebCrypto
+ * @param {string} input
+ * @returns {Promise<string>} - Hex hash string
+ */
+const hashBackupCode = async (input) => {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await webcrypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+};
+
+const verify2FA = async (req, res) => {
+  try {
+    const { tempToken, token, backupCode } = req.body;
+    if (!tempToken) {
+      return res.status(400).json({ message: 'Missing temporary token' });
+    }
+
+    let payload;
+    try {
+      payload = jwt.verify(tempToken, process.env.JWT_SECRET);
+    } catch (err) {
+      return res.status(401).json({ message: 'Invalid or expired temporary token' });
+    }
+
+    const user = await getUserById(payload.userId);
+    // Ensure that the user exists and has backup codes (i.e. 2FA enabled)
+    if (!user || !(user.backupCodes && user.backupCodes.length > 0)) {
+      return res.status(400).json({ message: '2FA is not enabled for this user' });
+    }
+
+    let verified = false;
+
+    if (token && (await verifyTOTP(user.totpSecret, token))) {
+      verified = true;
+    } else if (backupCode) {
+      const hashedInput = await hashBackupCode(backupCode.trim());
+      const matchingCode = user.backupCodes.find(
+        (codeObj) => codeObj.codeHash === hashedInput && !codeObj.used,
+      );
+
+      if (matchingCode) {
+        verified = true;
+        const updatedBackupCodes = user.backupCodes.map((codeObj) =>
+          codeObj.codeHash === hashedInput && !codeObj.used
+            ? { ...codeObj, used: true, usedAt: new Date() }
+            : codeObj,
+        );
+
+        await updateUser(user._id, { backupCodes: updatedBackupCodes });
+      }
+    }
+
+    if (!verified) {
+      return res.status(401).json({ message: 'Invalid 2FA code or backup code' });
+    }
+
+    // Prepare user data for response.
+    // If the user is a plain object (from lean queries), we create a shallow copy.
+    const userData = user.toObject ? user.toObject() : { ...user };
+    // Remove sensitive fields
+    delete userData.password;
+    delete userData.__v;
+    delete userData.totpSecret; // Ensure totpSecret is not returned
+    userData.id = user._id.toString();
+
+    const authToken = await setAuthTokens(user._id, res);
+    return res.status(200).json({ token: authToken, user: userData });
+  } catch (err) {
+    logger.error('[verify2FA]', err);
+    return res.status(500).json({ message: 'Something went wrong' });
+  }
+};
+
+module.exports = { verify2FA };

api/server/routes/auth.js

@@ -7,6 +7,13 @@ const {
 } = require('~/server/controllers/AuthController');
 const { loginController } = require('~/server/controllers/auth/LoginController');
 const { logoutController } = require('~/server/controllers/auth/LogoutController');
+const { verify2FA } = require('~/server/controllers/auth/TwoFactorAuthController');
+const {
+  enable2FAController,
+  verify2FAController,
+  disable2FAController,
+  regenerateBackupCodesController, confirm2FAController,
+} = require('~/server/controllers/TwoFactorController');
 const {
   checkBan,
   loginLimiter,
@@ -50,4 +57,11 @@ router.post(
 );
 router.post('/resetPassword', checkBan, validatePasswordReset, resetPasswordController);
 
+router.get('/2fa/enable', requireJwtAuth, enable2FAController);
+router.post('/2fa/verify', requireJwtAuth, verify2FAController);
+router.post('/2fa/verify-temp', checkBan, verify2FA);
+router.post('/2fa/confirm', requireJwtAuth, confirm2FAController);
+router.post('/2fa/disable', requireJwtAuth, disable2FAController);
+router.post('/2fa/backup/regenerate', requireJwtAuth, regenerateBackupCodesController);
+
 module.exports = router;