Skip to content

README.md

Latest commit

 

History

History
124 lines (91 loc) · 6.17 KB

README.md

File metadata and controls

124 lines (91 loc) · 6.17 KB

🔐 Fullstack Authorization System

A production-ready, secure authentication system featuring Multi-Factor Authentication (2FA), OAuth2 providers, session management, and bot protection.

NestJS Next.js Docker

nodejs nestjs typescript prisma-orm postgresql redis docker oauth2 nextjs shadcn tailwindcss zod react-hook-forms feature-sliced-design

✨ Features

  • User Authentication: Traditional register and login with secure email/password or seamless OAuth2 integration (Google & GitHub).
  • Two-Factor Authentication (2FA): Enhanced security with optional 2FA via email-based one-time passwords (OTP).
  • Email Verification: Mandatory registration handshake via email verification links before system access is granted.
  • Password Recovery: Secure, token-based password reset functionality delivered straight to the user's inbox.
  • Bot Protection: Google reCAPTCHA v2/v3 integration safeguarding registration and login vectors.
  • Profile Management: User settings dashboard to update personal details (name, email) and toggle 2FA settings.
  • Session Management: Fast and secure server-side session store powered by Redis with strict revocation on logout.
  • Architecture & Design: Frontend built adhering to Feature-Sliced Design (FSD) architectural methodology for exceptional scalability.
  • Containerized Environment: Fully dockerized services orchestrated via Docker Compose for uniform local development.

🛠 Tech Stack

Backend

  • NestJS & Node.js — Scalable enterprise-grade backend architecture.
  • Prisma ORM — Modern database toolkit handling schemas, migrations, and type-safe queries.
  • PostgreSQL — Robust relational database for reliable user data persistence.
  • Redis — In-memory data store optimizing fast session handling and tokens.
  • Argon2 — State-of-the-art cryptographic password hashing.

Frontend

  • Next.js (App Router) — React framework optimized for Server-Side Rendering (SSR) and routing.
  • Tailwind CSS & Shadcn/ui — Beautiful, accessible, and easily customizable UI component ecosystem.
  • React Hook Form & Zod — Performance-focused forms paired with strict, schema-based runtime validation.

🔄 Core Authentication Flows

1. Registration

  1. User fills out the registration form protected by Google reCAPTCHA.
  2. Credentials are securely hashed using Argon2 and saved to PostgreSQL.
  3. A unique activation token is generated and dispatched via email.
  4. User must verify their email address to transition out of the pending state.

2. Login & 2FA

  1. User authenticates via standard credentials or an OAuth2 Provider (Google/GitHub).
  2. If 2FA is activated, the system halts the session and fires an OTP to the verified email.
  3. Upon entering the correct OTP, a secure session is stored in Redis and linked to the client browser.

3. Session Revocation (Logout)

  • Clicking "Logout" instantly purges the current session data inside Redis and clears client-side cookies, eliminating session fixation vulnerabilities.

🚀 Setup & Installation

Prerequisites

Ensure you have the following installed on your machine:

  • Docker Desktop and Docker Compose.
  • Optional: Node.js (v18+) if you wish to run services outside of containers.

Quickstart Step-by-Step

1. Create a directory and clone the repository:

mkdir fullstack-auth && cd fullstack-auth
git clone https://github.com/Liknox/fullstack-auth.git

2. Set up environment variables:

cp .env.example .env

Important

Open the newly created .env file and populate your missing OAuth client keys, Email SMTP credentials, and Google reCAPTCHA secrets.

3. Launch the containerized application:

docker compose --profile all up -d

Application Endpoints

Once the containers are healthy, you can access the ecosystem at:

  • Frontend Client: http://localhost:3000
  • Backend API Gateway: http://localhost:4000

💡 Usage Guide

  • Registration Gateway: Head over to /auth/register, solve the reCAPTCHA challenge, and inspect your inbox/logs for the activation link.
  • Accessing Dashboard: Log in at /auth/login. If you enabled 2FA within your settings, check your mail for the security code challenge.
  • Security Tweaks: Navigate to /dashboard/settings to update your user profile metadata or toggle 2FA constraints.
  • Credential Recovery: Use /auth/password-recovery to securely reset access to an account via an automated verification token email.