Advanced MERN Authentication System

A personal full-stack authentication project built with MongoDB, Express.js, React, and Node.js. It demonstrates account registration, email verification, JWT-based sessions, protected routes, and password recovery.

Overview

This project was created to explore how a frontend application, backend API, database, browser cookies, and transactional email service work together during authentication.

The application supports account registration, six-digit email verification, login, logout, session restoration after page refreshes, protected routes, forgotten-password requests, and password resets through emailed links.

Features

• Account registration using name, email, and password
• Duplicate email checking during registration
• Password hashing with bcryptjs
• Six-digit email verification codes
• Account verification state tracking
• Login and logout workflows
• JWT-based authentication
• HTTP-only authentication cookies
• Session restoration after browser refreshes
• Protected frontend routes
• Credentialed Axios requests
• Forgot-password email workflow
• Time-limited password-reset tokens
• Password-reset confirmation emails
• Account dashboard with profile and login information

Technology Stack

Frontend

• React
• React Router
• Zustand
• Axios
• Tailwind CSS
• Framer Motion
• React Hot Toast
• Lucide React
• Vite

Backend

• Node.js
• Express.js
• MongoDB
• Mongoose
• JSON Web Token
• bcryptjs
• Cookie Parser
• CORS
• Mailtrap

Authentication Workflow

Registration and Email Verification

1. The user creates an account with a name, email address, and password.
2. The backend checks whether the email address is already registered.
3. The password is hashed before the user record is stored in MongoDB.
4. A six-digit verification code is generated.
5. Mailtrap sends the verification code to the registered email address.
6. The user submits the code through the verification page.
7. The backend validates the code and updates the account verification status.
8. A welcome email is sent after successful verification.

Login and Session Persistence

1. The user submits their email address and password.
2. The backend compares the password with the stored bcryptjs hash.
3. A signed JWT is stored in an HTTP-only browser cookie.
4. Axios sends authentication requests with credentials enabled.
5. Express CORS allows credentialed requests from the configured frontend origin.
6. When the application reloads, the frontend calls a protected authentication-check endpoint.
7. Zustand restores the authenticated user using the server response.

Password Recovery

1. The user requests a password reset using their email address.
2. The backend generates a random reset token.
3. The token and its expiry time are stored with the user record.
4. Mailtrap sends a password-reset link containing the token.
5. The backend validates the token before accepting a new password.
6. The new password is hashed before being saved.
7. The reset token is removed after the password is changed.
8. A confirmation email is sent after a successful reset.

Project Structure

Advanced-MERN-Stack-Authentication/
├── backend/
│   ├── controllers/
│   ├── db/
│   ├── mailtrap/
│   ├── middleware/
│   ├── models/
│   ├── routes/
│   ├── utils/
│   └── index.js
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── store/
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
├── package.json
└── README.md

Local Installation

1. Clone the Repository

git clone https://github.com/theShihamAhamed/Advanced-MERN-Stack-Authentication.git
cd Advanced-MERN-Stack-Authentication

2. Install Backend Dependencies

npm install

3. Install Frontend Dependencies

npm install --prefix frontend

4. Configure Environment Variables

Create a .env file in the project root.

PORT=5000
NODE_ENV=development
MONGO_URI=YOUR_MONGODB_CONNECTION_STRING
JWT_SECRET=YOUR_LONG_RANDOM_JWT_SECRET
MAILTRAP_TOKEN=YOUR_MAILTRAP_API_TOKEN
CLIENT_URL=http://localhost:5173

Use your own credentials and secrets. Do not commit the .env file or publish real database, JWT, or email-service credentials.

5. Start the Backend

npm run dev

The backend is configured to run locally at:

http://localhost:5000

6. Start the Frontend

Open a second terminal and run:

npm run dev --prefix frontend

The Vite frontend is available locally at:

http://localhost:5173

Authentication API Routes

All authentication routes use the /api/auth prefix.

POST /api/auth/signup
POST /api/auth/login
POST /api/auth/logout
POST /api/auth/verify-email
POST /api/auth/forgot-password
POST /api/auth/reset-password/:token
GET  /api/auth/check-auth

The authentication-check endpoint requires a valid JWT cookie.

Implementation Challenges

Email Integration

Integrating authentication emails required coordinating Mailtrap configuration, reusable email templates, verification codes, reset links, and token-expiry values. Separating email delivery into dedicated functions made each authentication workflow easier to manage and highlighted the importance of keeping email messages consistent with backend behaviour.

Session Persistence

Maintaining the user session after a page refresh was challenging because the JWT was stored in an HTTP-only cookie and could not be read directly by React. The application solves this by calling a protected authentication-check endpoint during startup and restoring the authenticated user in Zustand from the server response.

Credentialed Axios Requests

Sending the authentication cookie between the React client and Express API required several matching settings. Axios needed credentials enabled, Express CORS needed to allow credentialed requests, the permitted origin needed to match the frontend, and the backend needed to configure the cookie correctly. This demonstrated how browser cookies, CORS, API origins, and route protection work together.

Learning Outcomes

• Implementing JWT authentication with HTTP-only cookies
• Restoring authentication state after page refreshes
• Coordinating Axios credentials with Express CORS settings
• Protecting backend endpoints through authentication middleware
• Managing global authentication state with Zustand
• Hashing and comparing passwords with bcryptjs
• Generating and validating email verification codes
• Creating time-limited password-reset tokens
• Sending authentication emails through Mailtrap
• Connecting React authentication routes to an Express API
• Persisting account and token information with MongoDB and Mongoose

Current Limitations

• No automated test suite is currently included.
• No verified public deployment is available.
• The frontend API URL and backend CORS origin are configured for local development.
• The project has not undergone a professional security audit.
• Server-side request validation could be strengthened.
• Password-policy enforcement currently requires improvement.
• Production environment configuration requires additional setup.

Future Improvements

• Add automated controller, middleware, API integration, and frontend route tests
• Move the frontend API URL and CORS origin into environment variables
• Add a safe .env.example file
• Add server-side request validation and email normalization
• Enforce the password policy through the backend
• Hash password-reset tokens before storing them
• Return neutral password-recovery responses for unknown email addresses
• Add rate limiting to login, verification, and password-reset endpoints
• Align verification email text with the backend expiry configuration
• Add deployment configuration and continuous integration

Project Status

Completed as a personal authentication-focused learning project. Further improvements would focus on automated testing, configuration management, validation, security hardening, and deployment readiness.

Repository

View the project on GitHub