Secure Auth Monorepo

A full-stack application featuring a secure, production-ready authentication microservice built with NestJS and a dynamic React frontend powered by Vite.

Architecture

This monorepo consists of two main applications:

• Backend (/backend): NestJS, TypeORM (PostgreSQL), and Redis.
• Frontend (/frontend): React, TypeScript, Vite.

Backend Features

• Robust Architecture: Built on NestJS, backed by PostgreSQL via TypeORM, and utilizing Redis for caching and rate limiting.
• Secure Authentication Flow:
  • Password hashing via Argon2.
  • Short-lived JWT Access Tokens.
  • Long-lived, hashed Refresh Tokens securely rotated via HttpOnly, Strict SameSite cookies.
• Account Verification & Recovery:
  • Email confirmation required for login (via Nodemailer).
  • Secure password reset flow using tokens tied to current password hashes.
• Two-Factor Authentication (2FA/TOTP):
  • Full TOTP flow using authenticator apps.
  • Multi-step login process supporting temporary tokens when 2FA is enabled.
• Advanced Defense-in-Depth Security:
  • CSRF Protection: Custom Double Submit Cookie middleware.
  • Rate Limiting: Redis-backed global rate limiting via @nestjs/throttler to prevent brute-force attacks.
  • Helmet: Essential HTTP security headers configured.
  • Data Sanitization: Global ValidationPipe strictly validating and stripping unexpected DTO properties.
  • Strict CORS: Configured to restrict origins and support credentials.

Frontend Features

• Modern Stack: React 18 with TypeScript and Vite for fast builds and HMR.
• Authentication State: Handles JWT token management, refresh token rotation, and CSRF cookie synchronization seamlessly.
• Protected Routes: Secure access to authenticated areas like user profiles.
• 2FA Integration: Multi-step login UI for enabling and using two-factor authentication.

Prerequisites

• Docker and docker-compose
• Node.js (v18+ recommended)
• npm or yarn

Getting Started

1. Environment Configuration

Copy the .env.example file to .env inside the backend directory:

cd backend
cp .env.example .env

Update the backend/.env file with your specific secrets. For local development, you can generate random secrets for the JWTs and configure Ethereal Email credentials for testing email flows.

2. Running the Application via Docker (Recommended)

To start the infrastructure (PostgreSQL, Redis), the backend API, and the frontend in one go, simply run from the project root:

docker-compose up -d --build

• Frontend: Available at http://localhost:5173
• Backend API: Available at http://localhost:3000

3. Running Locally (Alternative)

If you prefer to run the apps directly on your host machine while using Docker for the database and Redis:

1. Start infrastructure from the root:

   docker-compose up -d db redis

2. Start the Backend:

   cd backend
   npm install
   npm run start:dev

3. Start the Frontend:

   cd frontend
   npm install
   npm run dev

Backend API Endpoints Overview

All endpoints are prefixed with /auth. State-changing requests (POST/PUT/PATCH/DELETE) require the X-CSRF-Token header, which must match the csrf-token cookie issued by the server.

• POST /auth/register - Register a new user.
• POST /auth/login - Authenticate and receive an Access Token & Refresh Cookie. (If 2FA is enabled, returns a temporary token).
• POST /auth/logout - Invalidate tokens and clear cookies.
• POST /auth/refresh - Rotate the refresh token and receive a new access token.
• GET /auth/confirm - Confirm a newly registered email address.
• POST /auth/forgot-password - Request a password reset link.
• POST /auth/reset-password - Reset password using the provided token.
• POST /auth/2fa/generate - Generate a TOTP secret and QR code.
• POST /auth/2fa/turn-on - Enable 2FA on the account.
• POST /auth/2fa/authenticate - Submit the 2FA code during the second step of login.

License

This project is MIT licensed.