🚀 AuthFlow

A production-ready, plug-and-play authentication & authorization API built with NestJS, PostgreSQL, Prisma, and PassportJS. Designed to eliminate repetitive auth boilerplate in your projects.

---

📋 Table of Contents

1. Overview
2. Features
3. Tech Stack
4. Prerequisites
5. Local Setup
6. Deploy on AWS EC2
7. API Endpoints
8. Future Improvements
9. License

---

📝 Overview

AuthFlow simplifies secure user management by providing a reusable backend for authentication and authorization. Out of the box, it supports:

• JWT, Google, and GitHub login strategies
• Email verification and resending
• Password reset workflow
• Token refresh
• File uploads via AWS S3
• Background tasks with BullMQ (Redis)
• Rate limiting and session cleanup

---

🎯 Features

• 🔐 Authentication: JWT, Google OAuth2, GitHub OAuth2
• ✅ Email Verification: Automatic verification and resend links
• 🔁 Token Refresh: 1h access tokens, 7d refresh tokens
• 🔄 Background Jobs: Email sending with BullMQ
• 🗂 File Uploads: Multer + Cloudinary
• 🚨 Rate Limiting: Protect endpoints from abuse
• 🧑‍💻 Admin Management: CRUD operations on users
• 🕒 Cron Jobs: Cleanup expired sessions
• 📄 API Docs: Swagger UI at /api

---

🛠️ Tech Stack

Layer	Technology
Backend	NestJS
Database	PostgreSQL + Prisma ORM
Auth	PassportJS (JWT, Google, GitHub)
Queue	BullMQ
Storage	Cloudinary
Cron	nest-scheduler
Docs	Swagger

---

🧰 Prerequisites

• Node.js >= 18.x
• Docker & Docker Compose
• Cloudinary Account (for file uploads)

---

🚀 Local Setup

1. Clone the repository

   git clone https://github.com/your-org/authflow.git
   cd authflow

2. Install dependencies

   npm install

3. Create **.env** file

   Copy .env.example to .env and update values:

   DATABASE_URL=postgresql://test_admin:test_pass@localhost:5433/test_db
   REDIS_HOST=localhost
   REDIS_PORT=6379
   REDIS_PASSWORD=redis_password
   JWT_SECRET=your_jwt_secret
   
   # OAuth Credentials
   GOOGLE_CLIENT_ID=your_google_id
   GOOGLE_CLIENT_SECRET=your_google_secret
   GITHUB_CLIENT_ID=your_github_id
   GITHUB_CLIENT_SECRET=your_github_secret
   
   # Cloudinary
   CLOUDINARY_CLOUD_NAME=your_cloud_name
   CLOUDINARY_API_KEY=your_api_key
   CLOUDINARY_API_SECRET=your_api_secret
   DEFAULT_PROFILE_PICTURE_URL=https://res.cloudinary.com/your_cloud/image/upload/v1/default-avatar.jpg

4. Start services

   docker-compose up -d

5. Generate Prisma client & run migrations

   npx prisma generate
   npx prisma migrate dev --name init

6. Run the application

   npm run start:dev

7. Access Swagger UI

   Visit http://localhost:3000/v1/api/docs in your browser.

---

☁️ Deploy on AWS EC2

1. Provision EC2 Instance

   • OS: Ubuntu 22.04+
   • Open ports: 22, 3000, 5433, 6379, 8001

2. SSH into Instance

   ssh -i your-key.pem ubuntu@your-ec2-ip

3. Install Docker & Compose

   sudo apt update && sudo apt install -y docker.io docker-compose
   sudo systemctl enable docker

4. Clone and Configure

   git clone https://github.com/ShejanMahamud/authflow.git
   cd authflow

   Create .env with production credentials.

5. Use Docker Compose

   version: '3.8'
   
   services:
     postgres:
       image: postgres:latest
       container_name: test_postgres
       ports:
         - '${POSTGRES_PORT}:5432'
       environment:
         POSTGRES_USER: ${POSTGRES_USER}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
         POSTGRES_DB: ${POSTGRES_DB}
       volumes:
         - pgdata:/var/lib/postgresql/data
       restart: unless-stopped
       env_file:
         - .env
   
     redis:
       image: redis/redis-stack:latest
       container_name: test_redis
       ports:
         - '${REDIS_PORT}:6379'
       command: redis-server --requirepass ${REDIS_PASSWORD}
       environment:
         REDIS_PASSWORD: ${POSTGRES_PASSWORD}
       volumes:
         - redisdata:/data
       restart: unless-stopped
       env_file:
         - .env
   
   volumes:
     pgdata:
     redisdata:

6. Start Containers

   docker-compose up -d

7. Install & Build

   npm install
   npm run build
   npm run start:prod

Tip: Use PM2, Dockerfile, or systemd for process management.

---

🔄 API Endpoints

Method	Endpoint	Description
POST	/auth/register	User registration
POST	/auth/login	Email/password login
POST	/auth/google	Google OAuth login
POST	/auth/github	GitHub OAuth login
GET	/auth/verify/:token	Email verification
POST	/auth/refresh-token	Refresh access token
POST	/auth/forgot-password	Initiate password reset
POST	/auth/reset-password	Complete password reset
POST	/auth/logout	Logout

For complete details, see Swagger UI.

---

🚧 Future Improvements

• TOTP-based 2FA
• Session/device management dashboard

---