https://github.com/priyansh-narang2308/2fa-auth
A secure MERN stack authentication system with both 1FA (username/password) and 2FA (TOTP) login flows. Built with Passport.js for primary authentication and Speakeasy for time-based OTP verification. Includes a modern React frontend, Node.js backend, and MongoDB for persistent user and 2FA data.
https://github.com/priyansh-narang2308/2fa-auth
mern-stack mongo passportjs speakeasyapi tailwindcss
Last synced: 3 months ago
JSON representation
A secure MERN stack authentication system with both 1FA (username/password) and 2FA (TOTP) login flows. Built with Passport.js for primary authentication and Speakeasy for time-based OTP verification. Includes a modern React frontend, Node.js backend, and MongoDB for persistent user and 2FA data.
- Host: GitHub
- URL: https://github.com/priyansh-narang2308/2fa-auth
- Owner: priyansh-narang2308
- Created: 2025-08-13T12:36:28.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-13T13:31:48.000Z (11 months ago)
- Last Synced: 2025-08-13T14:37:04.588Z (11 months ago)
- Topics: mern-stack, mongo, passportjs, speakeasyapi, tailwindcss
- Language: JavaScript
- Homepage: https://2fauthh.vercel.app
- Size: 73.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🔐 MERN 2FA Authentication System
A **full-stack authentication system** built using the **MERN stack** that supports **Two-Factor Authentication (2FA)** with **TOTP** verification using [Speakeasy](https://github.com/speakeasyjs/speakeasy) and [Passport.js](http://www.passportjs.org/) for secure user authentication.
This project demonstrates a complete **1FA (username/password)** and **2FA (TOTP)** authentication flow.
---
## 📜 Table of Contents
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Architecture Overview](#architecture-overview)
- [Authentication Flow](#authentication-flow)
- [Routes](#routes)
- [Installation & Setup](#installation--setup)
- [Environment Variables](#environment-variables)
---
## ✨ Features
- **User Registration & Login** using Passport.js
- **Session-based authentication**
- **Two-Factor Authentication (2FA)** using Speakeasy (TOTP)
- **MongoDB** for persistent storage of users & 2FA secrets
- **Frontend** built with **React + Vite**
- **Secure API routes** for authentication
- **QR Code generation** for easy 2FA setup
- **Logout & Session Management**
- **Status Check Endpoint** to verify authentication state
---
## 🛠 Tech Stack
**Frontend:**
- React (Vite)
- Axios
- Tailwind CSS / CSS Modules
**Backend:**
- Node.js + Express.js
- Passport.js
- Speakeasy (TOTP)
- MongoDB + Mongoose
- Express-Session
- bcrypt.js (password hashing)
---
## 📂 Architecture Overview
```plaintext
Frontend (React + Vite)
|
| API Requests (Axios)
v
Backend (Node.js + Express)
- Routes
- Controllers
- Passport.js Auth Strategies
- Speakeasy TOTP Handling
- MongoDB User Storage
```
## 🔄 Authentication Flow
### 1FA (Username/Password)
1. User submits login credentials.
2. Passport.js validates credentials against MongoDB.
3. Session is created.
### 2FA (TOTP)
1. After successful 1FA, if 2FA is enabled:
2. Backend sends prompt to enter OTP.
3. OTP is verified using Speakeasy.
4. If verified, full session access is granted.
## 📜 Routes
### Auth Routes (Passport.js)
POST /api/auth/register → Register new user
POST /api/auth/login → Login user
POST /api/auth/logout → Logout user
GET /api/auth/status → Check authentication status
### 2FA Routes (Speakeasy)
POST /api/auth/2fa/setup → Generate secret & QR code
POST /api/auth/2fa/verify → Verify TOTP
POST /api/auth/2fa/reset → Disable or reset 2FA
## ⚙ Installation & Setup
### Clone the repository
```bash
git clone https://github.com/priyansh-narang2308/2fa-auth.git
cd frontend
npm install
```
```bash
cd backend
npm install
```
```bash
npm run dev
```
## 🌱 Environment Variables
### Create a .env file in backend:
```bash
PORT=5000
MONGO_URI=mongodb://localhost:27017/2fa_auth
SESSION_SECRET=your_session_secret
JWT_SECRET=your_jwt
```