Enterprise Authentication Backend

Production-ready authentication backend with JWT tokens, MFA support, role-based access control, password reset flows, audit logging, rate limiting, and comprehensive security features.

authenticationjwtmfarbacsecuritymongodbredisexpresstypescriptoauthtotpargon2

v1.0.0Authentication & Security

Overview

A production-ready authentication backend built with Express.js and TypeScript. Supports JWT access & refresh tokens with automatic rotation. TOTP-based Multi-Factor Authentication with QR code generation. Role-based access control (RBAC) with admin and user roles. Comprehensive password security with Argon2 hashing. Redis-powered rate limiting and token blacklisting. Email verification and password reset flows. Complete audit logging for security events. MongoDB integration with Mongoose ODM. OAuth2 ready (Google/GitHub integration stubs). Comprehensive Swagger API documentation. Docker containerization for easy deployment. Built with security-first approach and production scalability.

What This Does

Sets up a complete enterprise-grade authentication system with JWT tokens, MFA, RBAC, security features, and audit logging.

Files & Folders Created

File / Path	Description
/src/config/env.ts	Environment configuration with Zod validation.
/src/models/User.ts	User schema with roles, MFA settings, and security fields.
/src/models/AuditLog.ts	Security audit logging for critical actions.
/src/services/auth.service.ts	Core authentication logic (register, login, password management).
/src/services/token.service.ts	JWT token generation, validation, and refresh mechanisms.
/src/services/mfa.service.ts	TOTP setup, verification, and QR code generation.
/src/services/email.service.ts	Email verification and password reset notifications.
/src/services/audit.service.ts	Security event logging and tracking.
/src/controllers/auth.controller.ts	Authentication endpoint handlers.
/src/controllers/user.controller.ts	User management and profile operations.
/src/middlewares/auth.middleware.ts	JWT token validation and user extraction.
/src/middlewares/rbac.middleware.ts	Role-based access control enforcement.
/src/middlewares/rateLimit.ts	Redis-backed rate limiting protection.
/src/middlewares/validate.ts	Request validation using Zod schemas.
/src/routes/auth.routes.ts	Complete authentication API routes with Swagger docs.
/src/routes/user.routes.ts	User management routes with admin controls.
/src/utils/logger.ts	Winston logging configuration.
/.env.example	All required environment variables with descriptions.

Files to be modified

File / Path	Description
server.ts	Database connections (MongoDB + Redis), middleware setup, route mounting.
app.ts	Express configuration, Swagger setup, CORS, security headers.
.env	Authentication secrets, database URLs, email configuration.
package.json	Installs 20+ production dependencies (express, mongoose, redis, jwt, argon2, etc.).
docker-compose.yml	Complete containerization with MongoDB and Redis services.
Dockerfile	Production-ready Docker image configuration.

Configuration

# Environment Variables Configuration

# Server Configuration
PORT=3000                        # Server port (default: 3000)
NODE_ENV=development            # Environment: development | production | test
BASE_URL=http://localhost:3000  # Application base URL for redirects

# Database Configuration
MONGO_URI=mongodb://localhost:27017/auth-db  # MongoDB connection string
REDIS_URL=redis://localhost:6379            # Redis connection string

# JWT Security Configuration
JWT_ACCESS_SECRET=your_super_secret_access_key_here    # Access token signing secret
JWT_REFRESH_SECRET=your_super_secret_refresh_key_here  # Refresh token signing secret
JWT_ACCESS_EXPIRY=15m                                  # Access token expiry (15 minutes)
JWT_REFRESH_EXPIRY=7d                                  # Refresh token expiry (7 days)

# Email Service Configuration (for verification & password reset)
SMTP_HOST=smtp.ethereal.email    # SMTP server hostname
SMTP_PORT=587                    # SMTP server port
SMTP_USER=your_smtp_username     # SMTP authentication username
SMTP_PASS=your_smtp_password     # SMTP authentication password
FROM_EMAIL=noreply@yourapp.com   # Sender email address

# Security Notes:
# - Use strong, unique secrets for JWT tokens (32+ characters)
# - Enable SSL/TLS for SMTP in production
# - Use environment-specific MongoDB/Redis instances
# - Set NODE_ENV=production for production deployments

Frontend Integration

Here's an example of integrating the authentication system with a Next.js frontend using React hooks. All protected endpoints require Bearer token authentication with JWT tokens.

POST/auth/register

POST/auth/login

POST/auth/refresh

Refresh expired access token using refresh token.

POST/auth/verify-email

Verify user email address using verification token.

POST/auth/request-password-reset

Request password reset email with reset token.

POST/auth/reset-password

Reset password using reset token from email.

POST/auth/mfa/setup

Setup Multi-Factor Authentication with TOTP (requires login).

POST/auth/mfa/verify

Verify and enable MFA setup using TOTP token.

POST/auth/mfa/authenticate

Complete login with MFA token (after initial login).

GET/users/profile

Get current user profile information.

PUT/users/profile

Update user profile information.

GET/users

List all users (Admin only).

POST/users/{id}/roles

Assign roles to a user (Admin only).

Example

// app/components/AuthProvider.jsx
'use client';
import { createContext, useContext, useEffect, useState } from 'react';

const AuthContext = createContext();
const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000';

export function AuthProvider({ children }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [accessToken, setAccessToken] = useState(null);

  useEffect(() => {
    checkAuthStatus();
  }, []);

  async function checkAuthStatus() {
    const token = localStorage.getItem('accessToken');
    if (!token) {
      setLoading(false);
      return;
    }

    try {
      const response = await fetch(`${API_BASE_URL}/users/profile`, {
        headers: { Authorization: `Bearer ${token}` },
      });

      if (response.ok) {
        const userData = await response.json();
        setUser(userData);
        setAccessToken(token);
      } else {
        // Try to refresh token
        await refreshToken();
      }
    } catch (error) {
      console.error('Auth check failed:', error);
      localStorage.removeItem('accessToken');
    } finally {
      setLoading(false);
    }
  }

  async function refreshToken() {
    try {
      const response = await fetch(`${API_BASE_URL}/auth/refresh`, {
        method: 'POST',
        credentials: 'include', // Include cookies for refresh token
      });

      if (response.ok) {
        const data = await response.json();
        localStorage.setItem('accessToken', data.accessToken);
        setAccessToken(data.accessToken);
        setUser(data.user);
        return data.accessToken;
      } else {
        throw new Error('Token refresh failed');
      }
    } catch (error) {
      console.error('Token refresh failed:', error);
      localStorage.removeItem('accessToken');
      setUser(null);
      setAccessToken(null);
      return null;
    }
  }

  async function login(email, password) {
    try {
      const response = await fetch(`${API_BASE_URL}/auth/login`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify({ email, password }),
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.message || 'Login failed');
      }

      // Check if MFA is required
      if (data.mfaRequired) {
        return { mfaRequired: true, tempToken: data.tempToken };
      }

      // Regular login success
      localStorage.setItem('accessToken', data.accessToken);
      setAccessToken(data.accessToken);
      setUser(data.user);
      return { success: true, user: data.user };
    } catch (error) {
      console.error('Login failed:', error);
      throw error;
    }
  }

  async function authenticateMFA(tempToken, mfaToken) {
    try {
      const response = await fetch(`${API_BASE_URL}/auth/mfa/authenticate`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify({ tempToken, token: mfaToken }),
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.message || 'MFA authentication failed');
      }

      localStorage.setItem('accessToken', data.accessToken);
      setAccessToken(data.accessToken);
      setUser(data.user);
      return { success: true, user: data.user };
    } catch (error) {
      console.error('MFA authentication failed:', error);
      throw error;
    }
  }

  async function register(email, password, displayName) {
    try {
      const response = await fetch(`${API_BASE_URL}/auth/register`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password, displayName }),
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.message || 'Registration failed');
      }

      return { success: true, message: data.message };
    } catch (error) {
      console.error('Registration failed:', error);
      throw error;
    }
  }

  async function logout() {
    try {
      await fetch(`${API_BASE_URL}/auth/logout`, {
        method: 'POST',
        credentials: 'include',
      });
    } catch (error) {
      console.error('Logout error:', error);
    } finally {
      localStorage.removeItem('accessToken');
      setAccessToken(null);
      setUser(null);
    }
  }

  async function setupMFA() {
    try {
      const response = await fetch(`${API_BASE_URL}/auth/mfa/setup`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${accessToken}` },
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.message || 'MFA setup failed');
      }

      return data; // Returns { qrCode, secret, backupCodes }
    } catch (error) {
      console.error('MFA setup failed:', error);
      throw error;
    }
  }

  async function verifyMFA(token) {
    try {
      const response = await fetch(`${API_BASE_URL}/auth/mfa/verify`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify({ token }),
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.message || 'MFA verification failed');
      }

      // Refresh user data to reflect MFA enabled status
      await checkAuthStatus();
      return { success: true };
    } catch (error) {
      console.error('MFA verification failed:', error);
      throw error;
    }
  }

  const value = {
    user,
    loading,
    accessToken,
    login,
    register,
    logout,
    setupMFA,
    verifyMFA,
    authenticateMFA,
    refreshToken,
  };

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

// app/components/LoginForm.jsx
'use client';
import { useState } from 'react';
import { useAuth } from './AuthProvider';

export default function LoginForm() {
  const { login, authenticateMFA } = useAuth();
  const [formData, setFormData] = useState({ email: '', password: '' });
  const [mfaData, setMfaData] = useState({ tempToken: '', mfaToken: '' });
  const [showMFA, setShowMFA] = useState(false);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  async function handleLogin(e) {
    e.preventDefault();
    setError('');
    setLoading(true);

    try {
      const result = await login(formData.email, formData.password);

      if (result.mfaRequired) {
        setMfaData({ tempToken: result.tempToken, mfaToken: '' });
        setShowMFA(true);
      } else {
        // Login success
        window.location.href = '/dashboard';
      }
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  async function handleMFASubmit(e) {
    e.preventDefault();
    setError('');
    setLoading(true);

    try {
      await authenticateMFA(mfaData.tempToken, mfaData.mfaToken);
      window.location.href = '/dashboard';
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  if (showMFA) {
    return (
      <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
        <h2 className="text-2xl font-bold mb-6">Two-Factor Authentication</h2>
        <form onSubmit={handleMFASubmit} className="space-y-4">
          <div>
            <label className="block text-sm font-medium mb-2">
              Enter 6-digit code from your authenticator app
            </label>
            <input
              type="text"
              value={mfaData.mfaToken}
              onChange={(e) => setMfaData({ ...mfaData, mfaToken: e.target.value })}
              placeholder="123456"
              className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:border-blue-500"
              maxLength={6}
              required
            />
          </div>
          {error && (
            <div className="p-3 bg-red-100 border border-red-400 text-red-700 rounded">
              {error}
            </div>
          )}
          <button
            type="submit"
            disabled={loading}
            className="w-full bg-blue-500 hover:bg-blue-600 disabled:bg-gray-400 text-white font-semibold py-2 rounded-md"
          >
            {loading ? 'Verifying...' : 'Verify'}
          </button>
        </form>
      </div>
    );
  }

  return (
    <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow-md">
      <h2 className="text-2xl font-bold mb-6">Login</h2>
      <form onSubmit={handleLogin} className="space-y-4">
        <div>
          <label className="block text-sm font-medium mb-2">Email</label>
          <input
            type="email"
            value={formData.email}
            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
            className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:border-blue-500"
            required
          />
        </div>
        <div>
          <label className="block text-sm font-medium mb-2">Password</label>
          <input
            type="password"
            value={formData.password}
            onChange={(e) => setFormData({ ...formData, password: e.target.value })}
            className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:border-blue-500"
            required
          />
        </div>
        {error && (
          <div className="p-3 bg-red-100 border border-red-400 text-red-700 rounded">
            {error}
          </div>
        )}
        <button
          type="submit"
          disabled={loading}
          className="w-full bg-blue-500 hover:bg-blue-600 disabled:bg-gray-400 text-white font-semibold py-2 rounded-md"
        >
          {loading ? 'Logging in...' : 'Login'}
        </button>
      </form>
    </div>
  );
}

Usage

// server.js - Main application setup
import express from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import { fal } from '@fal-ai/client';

// Import routes
import paymentRoutes from './routes/payment.routes';
import { router as webhookRouter } from './routes/webhook.routes';
import { authMiddleware } from './middleware/auth.middleware';
import { FalAIModel } from './models/FalAIModel';
import { prismaClient } from './prisma';

dotenv.config();

// Configure Fal.AI
fal.config({
  credentials: process.env.FAL_KEY,
});

const app = express();
const PORT = process.env.PORT || 8080;

// Middleware
app.use(cors({
  origin: ['http://localhost:3000', process.env.FRONTEND_URL],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
}));
app.use(express.json());

// Initialize Fal.AI Model
const falAiModel = new FalAIModel();

// Routes (Protected with authMiddleware)
app.use('/payment', authMiddleware, paymentRoutes);
app.use('/api/webhook', webhookRouter); // Webhooks don't need auth

// Image Generation Routes
app.post('/ai/training', authMiddleware, async (req, res) => {
  try {
    const { zipUrl, name, type, age, ethinicity, eyeColor, bald } = req.body;
    
    const { request_id } = await falAiModel.trainModel(zipUrl, name);
    
    const model = await prismaClient.model.create({
      data: {
        name,
        type,
        age,
        ethinicity,
        eyeColor,
        bald,
        userId: req.userId!,
        zipUrl,
        falAiRequestId: request_id,
      },
    });
    
    res.json({ modelId: model.id });
  } catch (error) {
    console.error('Training error:', error);
    res.status(500).json({ message: 'Training failed' });
  }
});

app.post('/ai/generate', authMiddleware, async (req, res) => {
  try {
    const { modelId, prompt } = req.body;
    
    const model = await prismaClient.model.findUnique({
      where: { id: modelId },
    });
    
    if (!model || !model.tensorPath) {
      res.status(404).json({ message: 'Model not found' });
      return;
    }
    
    // Check credits
    const credits = await prismaClient.userCredit.findUnique({
      where: { userId: req.userId! },
    });
    
    if ((credits?.amount ?? 0) < 1) {
      res.status(402).json({ message: 'Insufficient credits' });
      return;
    }
    
    const { request_id } = await falAiModel.generateImage(prompt, model.tensorPath);
    
    const image = await prismaClient.outputImages.create({
      data: {
        prompt,
        userId: req.userId!,
        modelId,
        imageUrl: '',
        falAiRequestId: request_id,
      },
    });
    
    // Deduct credit
    await prismaClient.userCredit.update({
      where: { userId: req.userId! },
      data: { amount: { decrement: 1 } },
    });
    
    res.json({ imageId: image.id });
  } catch (error) {
    console.error('Generation error:', error);
    res.status(500).json({ message: 'Generation failed' });
  }
});

app.get('/models', authMiddleware, async (req, res) => {
  const models = await prismaClient.model.findMany({
    where: { userId: req.userId },
  });
  res.json({ models });
});

// Start server
app.listen(PORT, () => {
  console.log(`� Auth Backend running on port ${PORT}`);
});