How to Deep Dive Two-Factor Authentication: What Works

// TOTP Registration and Verification Flow
// Dependencies: node-2fa@3.2.1, express@4.18.2, mongoose@7.6.0, express-rate-limit@7.1.0, bcrypt@5.1.1
const express = require('express');
const router = express.Router();
const { generateSecret, verifyToken } = require('node-2fa');
const User = require('../models/User'); // Mongoose user model
const rateLimit = require('express-rate-limit');
const bcrypt = require('bcrypt');

// Rate limit TOTP verification to 5 attempts per 15 minutes per IP
const totpVerifyLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,
  message: { error: 'Too many TOTP verification attempts, try again in 15 minutes' },
  standardHeaders: true,
  legacyHeaders: false,
});

/**
 * Register TOTP for a user - generates secret, returns QR code and backup codes
 * POST /api/2fa/totp/register
 * Requires: Authenticated user (req.user set by auth middleware)
 */
router.post('/totp/register', async (req, res) => {
  try {
    // Validate user is authenticated
    if (!req.user || !req.user.id) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const userId = req.user.id;

    // Check if user already has TOTP enabled
    const existingUser = await User.findById(userId).select('totpSecret');
    if (existingUser.totpSecret) {
      return res.status(409).json({ error: 'TOTP is already enabled for this account' });
    }

    // Generate TOTP secret with 160-bit entropy (NIST compliant)
    const secret = generateSecret({
      name: 'Acme Auth App', // Display name in authenticator apps
      account: req.user.email, // Account identifier in app
    });

    // Generate 10 backup codes, hashed for storage
    const backupCodes = [];
    const hashedBackupCodes = [];
    for (let i = 0; i < 10; i++) {
      const code = Math.random().toString(36).substring(2, 10).toUpperCase();
      backupCodes.push(code);
      // Hash backup code with bcrypt (10 rounds) before storage
      const hashedCode = await bcrypt.hash(code, 10);
      hashedBackupCodes.push(hashedCode);
    }

    // Save secret and hashed backup codes to user document
    await User.findByIdAndUpdate(userId, {
      totpSecret: secret.secret,
      totpBackupCodes: hashedBackupCodes,
      totpEnabled: false, // Only enable after first successful verification
    });

    // Return QR code URL and plaintext backup codes (show only once!)
    return res.status(200).json({
      qrCodeUrl: secret.qr, // Data URI for QR code
      secret: secret.secret, // Plaintext secret for manual entry
      backupCodes, // Plaintext backup codes - never store these
    });
  } catch (err) {
    console.error('TOTP registration error:', err);
    return res.status(500).json({ error: 'Internal server error during TOTP registration' });
  }
});

/**
 * Verify TOTP token and enable 2FA for user
 * POST /api/2fa/totp/verify
 * Body: { token: string } (6-digit TOTP token from authenticator app)
 * Requires: Authenticated user
 */
router.post('/totp/verify', totpVerifyLimiter, async (req, res) => {
  try {
    if (!req.user || !req.user.id) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const { token } = req.body;
    if (!token || !/^\d{6}$/.test(token)) {
      return res.status(400).json({ error: 'Valid 6-digit TOTP token is required' });
    }

    const user = await User.findById(req.user.id).select('totpSecret totpEnabled');
    if (!user.totpSecret) {
      return res.status(400).json({ error: 'TOTP is not registered for this account' });
    }

    // Verify token with 1 step skew (30s window) per NIST 800-63B, reduces failure rate vs no skew
    const verified = verifyToken(user.totpSecret, token, { skew: 1 });

    if (!verified) {
      return res.status(401).json({ error: 'Invalid TOTP token' });
    }

    // Enable TOTP for user if not already enabled
    if (!user.totpEnabled) {
      await User.findByIdAndUpdate(req.user.id, { totpEnabled: true });
    }

    return res.status(200).json({ success: true, message: 'TOTP verified and 2FA enabled' });
  } catch (err) {
    console.error('TOTP verification error:', err);
    return res.status(500).json({ error: 'Internal server error during TOTP verification' });
  }
});

module.exports = router;

// WebAuthn (Passkey) Registration and Verification Flow
// Dependencies: @simplewebauthn/server@9.0.0, express@4.18.2, mongoose@7.6.0, cbor@8.1.0
const express = require('express');
const router = express.Router();
const {
  generateRegistrationOptions,
  verifyRegistrationResponse,
  generateAuthenticationOptions,
  verifyAuthenticationResponse,
} = require('@simplewebauthn/server');
const User = require('../models/User');
const { isoBase64URL } = require('@simplewebauthn/server/helpers');
const rateLimit = require('express-rate-limit');

// Rate limit WebAuthn attempts to 10 per hour per IP
const webauthnLimiter = rateLimit({
  windowMs: 60 * 60 * 1000,
  max: 10,
  message: { error: 'Too many WebAuthn attempts, try again in 1 hour' },
});

// RP (Relying Party) configuration - must match your domain
const rpName = 'Acme Auth';
const rpID = process.env.WEBAUTHN_RP_ID || 'localhost';
const origin = process.env.WEBAUTHN_ORIGIN || 'http://localhost:3000';

/**
 * Generate WebAuthn registration options for a user
 * POST /api/2fa/webauthn/register-options
 * Requires: Authenticated user
 */
router.post('/webauthn/register-options', async (req, res) => {
  try {
    if (!req.user || !req.user.id) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const user = await User.findById(req.user.id).select('email webauthnCredentials');
    if (!user) {
      return res.status(404).json({ error: 'User not found' });
    }

    // Get existing WebAuthn credentials for the user (to exclude already registered keys)
    const existingCredentials = user.webauthnCredentials?.map(cred => ({
      id: isoBase64URL.toBuffer(cred.credentialID),
      type: 'public-key',
      transports: cred.transports,
    })) || [];

    // Generate registration options per W3C WebAuthn spec
    const options = generateRegistrationOptions({
      rpName,
      rpID,
      userID: isoBase64URL.toBuffer(user.id),
      userName: user.email,
      userDisplayName: user.name || user.email,
      attestationType: 'none', // No attestation for consumer apps, use 'indirect' for enterprise
      excludeCredentials: existingCredentials,
      authenticatorSelection: {
        authenticatorAttachment: 'platform', // Prefer platform authenticators (TouchID, Windows Hello)
        requireResidentKey: false,
        userVerification: 'preferred', // Require user verification (PIN, biometrics)
      },
      supportedAlgorithmIDs: [-7, -257], // ES256 and RS256 (most widely supported)
    });

    // Save challenge to user session for verification
    req.session.webauthnChallenge = options.challenge;
    req.session.webauthnUserId = user.id;

    return res.status(200).json(options);
  } catch (err) {
    console.error('WebAuthn registration options error:', err);
    return res.status(500).json({ error: 'Internal server error generating WebAuthn options' });
  }
});

/**
 * Verify WebAuthn registration response from client
 * POST /api/2fa/webauthn/register-verify
 * Body: { response: AuthenticatorAttestationResponse }
 * Requires: Authenticated user, active session with challenge
 */
router.post('/webauthn/register-verify', webauthnLimiter, async (req, res) => {
  try {
    if (!req.user || !req.user.id) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const { response } = req.body;
    if (!response) {
      return res.status(400).json({ error: 'WebAuthn response is required' });
    }

    // Retrieve and validate challenge from session
    const expectedChallenge = req.session.webauthnChallenge;
    if (!expectedChallenge) {
      return res.status(400).json({ error: 'No active WebAuthn registration session' });
    }

    const user = await User.findById(req.user.id).select('webauthnCredentials');
    const verification = await verifyRegistrationResponse({
      response,
      expectedChallenge,
      expectedOrigin: origin,
      expectedRPID: rpID,
      requireUserVerification: true,
    });

    if (!verification.verified) {
      return res.status(401).json({ error: 'WebAuthn registration verification failed' });
    }

    const { credential } = verification;
    // Check if credential is already registered
    const existingCred = user.webauthnCredentials?.find(cred => 
      isoBase64URL.fromBuffer(credential.id) === cred.credentialID
    );
    if (existingCred) {
      return res.status(409).json({ error: 'This authenticator is already registered' });
    }

    // Save new credential to user document
    const newCredential = {
      credentialID: isoBase64URL.fromBuffer(credential.id),
      publicKey: isoBase64URL.fromBuffer(credential.publicKey),
      counter: credential.counter,
      transports: credential.transports,
      createdAt: new Date(),
    };

    await User.findByIdAndUpdate(req.user.id, {
      $push: { webauthnCredentials: newCredential },
      webauthnEnabled: true,
    });

    // Clear challenge from session
    delete req.session.webauthnChallenge;
    delete req.session.webauthnUserId;

    return res.status(200).json({ success: true, message: 'WebAuthn authenticator registered' });
  } catch (err) {
    console.error('WebAuthn registration verification error:', err);
    return res.status(500).json({ error: 'Internal server error verifying WebAuthn registration' });
  }
});

module.exports = router;

// Backup Recovery Code Verification and Re-generation Flow
// Dependencies: express@4.18.2, mongoose@7.6.0, bcrypt@5.1.1, express-rate-limit@7.1.0
const express = require('express');
const router = express.Router();
const User = require('../models/User');
const bcrypt = require('bcrypt');
const rateLimit = require('express-rate-limit');

// Rate limit backup code verification to 3 attempts per hour per IP
const backupVerifyLimiter = rateLimit({
  windowMs: 60 * 60 * 1000,
  max: 3,
  message: { error: 'Too many backup code attempts, try again in 1 hour' },
  standardHeaders: true,
  legacyHeaders: false,
});

// Rate limit backup code re-generation to 1 attempt per day per user
const backupRegenLimiter = rateLimit({
  windowMs: 24 * 60 * 60 * 1000,
  max: 1,
  keyGenerator: (req) => req.user?.id || req.ip, // Rate limit by user ID if authenticated
  message: { error: 'Backup codes can only be regenerated once per day' },
});

/**
 * Verify a backup recovery code
 * POST /api/2fa/backup/verify
 * Body: { code: string } (8-character alphanumeric backup code)
 * Requires: Authenticated user with TOTP or WebAuthn enabled
 */
router.post('/backup/verify', backupVerifyLimiter, async (req, res) => {
  try {
    if (!req.user || !req.user.id) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    const { code } = req.body;
    if (!code || !/^[A-Z0-9]{8}$/.test(code)) {
      return res.status(400).json({ error: 'Valid 8-character backup code is required' });
    }

    const user = await User.findById(req.user.id).select('totpBackupCodes webauthnBackupCodes');
    if (!user) {
      return res.status(404).json({ error: 'User not found' });
    }

    // Check both TOTP and WebAuthn backup codes (unified pool)
    const allBackupCodes = [...(user.totpBackupCodes || []), ...(user.webauthnBackupCodes || [])];
    if (allBackupCodes.length === 0) {
      return res.status(400).json({ error: 'No backup codes available for this account' });
    }

    // Compare provided code against all hashed backup codes
    let matchedIndex = -1;
    for (let i = 0; i < allBackupCodes.length; i++) {
      const isMatch = await bcrypt.compare(code, allBackupCodes[i]);
      if (isMatch) {
        matchedIndex = i;
        break;
      }
    }

    if (matchedIndex === -1) {
      return res.status(401).json({ error: 'Invalid backup code' });
    }

    // Remove used backup code from storage (one-time use)
    const isTotpCode = matchedIndex < (user.totpBackupCodes?.length || 0);
    if (isTotpCode) {
      user.totpBackupCodes.splice(matchedIndex, 1);
      await user.save();
    } else {
      const webauthnIndex = matchedIndex - (user.totpBackupCodes?.length || 0);
      user.webauthnBackupCodes.splice(webauthnIndex, 1);
      await user.save();
    }

    return res.status(200).json({ 
      success: true, 
      message: 'Backup code verified. Remaining codes: ' + (allBackupCodes.length - 1)
    });
  } catch (err) {
    console.error('Backup code verification error:', err);
    return res.status(500).json({ error: 'Internal server error verifying backup code' });
  }
});

/**
 * Regenerate backup codes for a user (invalidates all existing codes)
 * POST /api/2fa/backup/regenerate
 * Requires: Authenticated user, recent 2FA verification (req.session.recent2fa = true)
 */
router.post('/backup/regenerate', backupRegenLimiter, async (req, res) => {
  try {
    if (!req.user || !req.user.id) {
      return res.status(401).json({ error: 'Authentication required' });
    }

    // Require recent 2FA verification to prevent unauthorized re-generation
    if (!req.session.recent2fa) {
      return res.status(403).json({ error: 'Recent 2FA verification required to regenerate backup codes' });
    }

    const user = await User.findById(req.user.id);
    if (!user) {
      return res.status(404).json({ error: 'User not found' });
    }

    // Generate 10 new backup codes
    const newPlaintextCodes = [];
    const newHashedCodes = [];
    for (let i = 0; i < 10; i++) {
      const code = Math.random().toString(36).substring(2, 10).toUpperCase().slice(0, 8);
      newPlaintextCodes.push(code);
      const hashedCode = await bcrypt.hash(code, 10);
      newHashedCodes.push(hashedCode);
    }

    // Save new codes, overwrite existing
    await User.findByIdAndUpdate(req.user.id, {
      totpBackupCodes: newHashedCodes, // Unify backup codes under TOTP field for simplicity
      webauthnBackupCodes: [], // Clear WebAuthn-specific backup codes
    });

    // Clear recent 2FA flag
    delete req.session.recent2fa;

    return res.status(200).json({
      backupCodes: newPlaintextCodes, // Plaintext - show only once!
      message: 'Backup codes regenerated. All previous codes are invalid.',
    });
  } catch (err) {
    console.error('Backup code regeneration error:', err);
    return res.status(500).json({ error: 'Internal server error regenerating backup codes' });
  }
});

module.exports = router;

// Hash backup code before storage
const plaintextCode = 'A1B2C3D4';
const hashedCode = await bcrypt.hash(plaintextCode, 10); // 10 rounds, adjust based on your CPU
// Store hashedCode in DB, never plaintextCode

// Distributed rate limit for TOTP verification using Redis
const RedisStore = require('rate-limit-redis');
const redisClient = require('./redis-client');
const totpLimiter = rateLimit({
  store: new RedisStore({
    client: redisClient,
    expiry: 15 * 60, // 15 minutes in seconds
  }),
  max: 5,
  keyGenerator: (req) => req.ip,
});

// Middleware to require fresh WebAuthn verification for high-value actions
const requireWebAuthn = async (req, res, next) => {
  if (!req.session.webauthnVerifiedAt || Date.now() - req.session.webauthnVerifiedAt > 300000) {
    return res.status(403).json({ error: 'Fresh WebAuthn verification required' });
  }
  next();
};

production-2fa/
├── src/
│   ├── models/
│   │   └── User.js # Mongoose user model with 2FA fields
│   ├── routes/
│   │   ├── totp.js # TOTP registration/verification routes (code example 1)
│   │   ├── webauthn.js # WebAuthn registration/verification routes (code example 2)
│   │   └── backup.js # Backup code routes (code example 3)
│   ├── middleware/
│   │   ├── auth.js # JWT authentication middleware
│   │   └── rate-limit.js # Shared rate limiting config
│   └── utils/
│       └── 2fa.js # Shared 2FA helper functions
├── tests/
│   ├── totp.test.js # TOTP integration tests
│   ├── webauthn.test.js # WebAuthn integration tests
│   └── backup.test.js # Backup code integration tests
├── .env.example # Example environment variables
├── package.json # Dependencies: node-2fa@3.2.1, @simplewebauthn/server@9.0.0, etc.
└── README.md # Setup and deployment instructions