Multi-Factor Authentication (MFA)

A robust multi-factor authentication system for Express, featuring OTP verification via email and secure JWT token handling.

authmfaotpemailexpresssecurityjwt

v2.0.0auth

Overview

Adds multi-factor authentication (MFA) to your Express app using email-based one-time passwords (OTPs). After successful email verification, JWT tokens are issued for session security. Includes OTP expiry handling, Nodemailer email delivery, and in-memory user storage for quick testing (replace with a real DB for production).

Installation

CLI

npx backternity add auth-multi-factor

What This Does

Installs ready-to-use routes, controllers, and services for multi-factor authentication using OTP verification and JWT.

Files & Folders Created

File / Path	Description
/routes/auth.js	Defines routes for register, login, verify, and profile endpoints.
/controllers/authController.js	Manages authentication and OTP verification flow.
/services/authService.js	Handles OTP generation, storage, JWT issuance, and user management.
/services/emailService.js	Sends OTPs via Nodemailer using your SMTP credentials.
/middleware/auth.js	Protects routes by verifying JWT tokens.
/.env.example	Example environment configuration for SMTP and JWT setup.

Files to be modified

File / Path	Description
server.js	Mounts /api/auth routes for MFA authentication endpoints.

Configuration

# JWT Configuration
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=7d

# OTP
OTP_EXPIRY_MINUTES=10

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM_NAME=Your App Name

PORT=3000
NODE_ENV=development

Frontend Integration

Here’s a complete Next.js example showing how to register, verify OTP, and handle JWT tokens using this MFA component.

POST/api/auth/register

Registers a user and sends an OTP to the provided email for verification.

POST/api/auth/login

Initiates login by verifying credentials and sending an OTP email.

POST/api/auth/verify

Verifies the OTP and returns a JWT token upon success.

GET/api/auth/me

Fetches the authenticated user’s details using JWT.

Example

// app/components/MFAFlow.jsx
'use client';
import { useState } from 'react';

export default function MFAFlow() {
  const [step, setStep] = useState('register');
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [otp, setOtp] = useState('');
  const [tempToken, setTempToken] = useState('');
  const [accessToken, setAccessToken] = useState('');
  const [message, setMessage] = useState('');

  async function handleRegister(e) {
    e.preventDefault();
    setMessage('');
    const res = await fetch('/api/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password }),
    });
    const data = await res.json();
    if (res.ok) {
      setTempToken(data.token);
      setStep('verify');
      setMessage('OTP sent to your email.');
    } else {
      setMessage(data.error || 'Registration failed.');
    }
  }

  async function handleVerify(e) {
    e.preventDefault();
    const res = await fetch('/api/auth/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ otp, tempToken }),
    });
    const data = await res.json();
    if (res.ok) {
      localStorage.setItem('accessToken', data.token);
      setAccessToken(data.token);
      setStep('authenticated');
      setMessage('Verification successful! Logged in.');
    } else {
      setMessage(data.error || 'OTP verification failed.');
    }
  }

  return (
    <div className="max-w-sm mx-auto bg-black/20 border border-white/10 rounded-xl p-6 text-white space-y-4">
      <h2 className="text-xl font-semibold">Multi-Factor Authentication</h2>

      {step === 'register' && (
        <form onSubmit={handleRegister} className="space-y-3">
          <input
            type="email"
            placeholder="Email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            className="w-full px-3 py-2 rounded-md bg-white/10 border border-white/20 focus:outline-none"
            required
          />
          <input
            type="password"
            placeholder="Password"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
            className="w-full px-3 py-2 rounded-md bg-white/10 border border-white/20 focus:outline-none"
            required
          />
          <button
            type="submit"
            className="w-full bg-emerald-500 hover:bg-emerald-600 text-white font-semibold py-2 rounded-md transition-colors"
          >
            Register
          </button>
        </form>
      )}

      {step === 'verify' && (
        <form onSubmit={handleVerify} className="space-y-3">
          <input
            type="text"
            placeholder="Enter OTP"
            value={otp}
            onChange={(e) => setOtp(e.target.value)}
            className="w-full px-3 py-2 rounded-md bg-white/10 border border-white/20 focus:outline-none"
            required
          />
          <button
            type="submit"
            className="w-full bg-emerald-500 hover:bg-emerald-600 text-white font-semibold py-2 rounded-md transition-colors"
          >
            Verify OTP
          </button>
        </form>
      )}

      {step === 'authenticated' && (
        <div className="p-3 bg-emerald-500/10 rounded-lg border border-emerald-500/20">
          <p className="text-sm text-emerald-300">✅ Logged in with JWT</p>
          <p className="text-xs break-all text-white/70 mt-2">
            {accessToken}
          </p>
        </div>
      )}

      {message && <p className="text-amber-400 text-sm">{message}</p>}
    </div>
  );
}

Usage

// Protect routes with JWT
const express = require('express');
const authMiddleware = require('./src/middleware/auth');
const app = express();

app.get('/api/me', authMiddleware, (req, res) => {
  res.json({ message: 'Protected route', user: req.user });
});