Enterprise Authentication & Authorization System (Production Ready)

Build a production-ready authentication system similar to:

* Devfolio
* Unstop
* GitHub
* LinkedIn
* Google

This module is the foundation of the entire platform.

Every feature depends on authentication:

```txt
User Registration
Profile Creation
Event Registration
Organization Creation
Team Formation
Project Submission
Judging Portal
Admin Dashboard
Payments
Certificates
Community
```

---

# Business Requirements

## Goals

* Secure user authentication
* Protect platform resources
* Support millions of users
* Prevent account abuse
* Enable social login
* Support multiple organizations
* Enterprise-grade security

---

# Authentication Flow

```txt
User
 ↓
Signup
 ↓
Email Verification
 ↓
Profile Creation
 ↓
Login
 ↓
Access Token
 ↓
Refresh Token
 ↓
Authenticated Session
```

---

# Features

## User Registration

### Normal Signup

Fields:

```ts
Full Name
Email
Password
Confirm Password
Country
Terms Accepted
```

Validation:

```txt
Name: 3-100 chars

Email:
Valid format
Unique

Password:
Min 8 chars
Uppercase
Lowercase
Number
Special Character
```

---

## Social Login

### Google OAuth

```txt
Continue with Google
```

### GitHub OAuth

```txt
Continue with GitHub
```

### LinkedIn OAuth

```txt
Continue with LinkedIn
```

### Future

```txt
Microsoft
Discord
Apple
```

---

# Email Verification

After signup:

```txt
User Registers
↓
Email Sent
↓
Verification Link
↓
User Clicks Link
↓
Account Verified
```

Verification Link:

```txt
/auth/verify-email?token=xxxxx
```

---

# Login System

### Email Login

```ts
Email
Password
```

### Social Login

```txt
Google
GitHub
LinkedIn
```

---

# Forgot Password

Flow:

```txt
Forgot Password
↓
Email Link
↓
Token Validation
↓
Reset Password
↓
Success
```

Token Expiry:

```txt
15 Minutes
```

---

# Password Reset Rules

```txt
Minimum 8 chars

Uppercase
Lowercase
Number
Special Character
```

Prevent:

```txt
Reuse Last 5 Passwords
```

---

# Session Management

Every login creates a session.

User can view:

```txt
Current Device
Browser
IP Address
Country
Last Active
```

Example:

```txt
Chrome - Windows
Chrome - Linux
Mobile App
```

User actions:

```txt
Logout Device
Logout All Devices
```

---

# JWT Architecture

## Access Token

Purpose:

```txt
API Authorization
```

Expiry:

```txt
15 Minutes
```

Payload:

```ts
{
  userId: string;
  email: string;
  role: string;
}
```

---

## Refresh Token

Purpose:

```txt
Generate New Access Token
```

Expiry:

```txt
30 Days
```

Stored:

```txt
HttpOnly Cookie
```

---

# Security Layer

## Password Hashing

Use:

```txt
Argon2
```

Fallback:

```txt
bcrypt
```

Never store:

```txt
Plain Password
```

---

## Rate Limiting

Protect:

```txt
Login
Signup
Forgot Password
Verification
```

Example:

```txt
5 Attempts
Per Minute
```

---

## Brute Force Protection

After:

```txt
10 Failed Logins
```

Account:

```txt
Locked for 30 Minutes
```

---

## CAPTCHA

Enable when:

```txt
Multiple Failed Attempts
```

Use:

```txt
Cloudflare Turnstile
reCAPTCHA
```

---

# Two Factor Authentication (2FA)

Support:

```txt
Google Authenticator
Authy
Microsoft Authenticator
```

Flow:

```txt
Login
↓
Password Valid
↓
OTP Required
↓
Verify OTP
↓
Success
```

---

# Device Tracking

Store:

```ts
{
  id: string;
  userId: string;
  browser: string;
  os: string;
  ip: string;
  country: string;
  lastSeen: Date;
}
```

---

# Authorization (RBAC)

Roles:

```txt
SUPER_ADMIN
ADMIN
ORGANIZATION_OWNER
ORGANIZATION_ADMIN
JUDGE
MENTOR
VOLUNTEER
USER
```

---

# Permissions Matrix

### USER

```txt
View Events
Register Events
Create Team
Submit Projects
```

---

### JUDGE

```txt
Review Projects
Score Projects
```

---

### ORGANIZATION_ADMIN

```txt
Manage Events
Manage Team
Manage Mentors
```

---

### SUPER_ADMIN

```txt
Everything
```

---

# Database Schema

## User

```ts
{
  id: string;

  fullName: string;

  email: string;

  passwordHash: string;

  profileImage: string | null;

  role: string;

  emailVerified: boolean;

  twoFactorEnabled: boolean;

  status: string;

  createdAt: Date;

  updatedAt: Date;
}
```

---

## Session

```ts
{
  id: string;

  userId: string;

  refreshTokenHash: string;

  ipAddress: string;

  userAgent: string;

  expiresAt: Date;

  createdAt: Date;
}
```

---

## Email Verification

```ts
{
  id: string;

  userId: string;

  token: string;

  expiresAt: Date;
}
```

---

## Password Reset

```ts
{
  id: string;

  userId: string;

  token: string;

  expiresAt: Date;
}
```

---

## OAuth Account

```ts
{
  id: string;

  userId: string;

  provider: string;

  providerAccountId: string;
}
```

---

# API Endpoints

## Signup

```http
POST /api/auth/signup
```

---

## Verify Email

```http
POST /api/auth/verify-email
```

---

## Login

```http
POST /api/auth/login
```

---

## Logout

```http
POST /api/auth/logout
```

---

## Logout All Devices

```http
POST /api/auth/logout-all
```

---

## Refresh Token

```http
POST /api/auth/refresh
```

---

## Forgot Password

```http
POST /api/auth/forgot-password
```

---

## Reset Password

```http
POST /api/auth/reset-password
```

---

## Enable 2FA

```http
POST /api/auth/2fa/enable
```

---

## Verify 2FA

```http
POST /api/auth/2fa/verify
```

---

# Frontend Pages

## Public

```txt
/login
/signup
/forgot-password
/reset-password
/verify-email
```

---

## Protected

```txt
/dashboard
/settings/security
/settings/sessions
```

---

# UI Components

```txt
LoginForm
SignupForm
OAuthButtons
ForgotPasswordForm
ResetPasswordForm
EmailVerificationBanner
SessionManager
TwoFactorSetup
SecuritySettings
```

---

# Notifications

### Email

Send:

```txt
Welcome Email
Verify Email
Password Reset
Password Changed
New Login Detected
2FA Enabled
```

---

### In-App

```txt
Login Alerts
Security Alerts
Account Changes
```

---

# Audit Logging

Track:

```txt
Signup
Login
Logout
Password Change
Password Reset
Role Change
Email Change
2FA Changes
```

Schema:

```ts
{
  actorId: string;
  action: string;
  metadata: object;
  createdAt: Date;
}
```

---

# Performance Requirements

### API Response

```txt
< 200ms
```

### Authentication Success Rate

```txt
99.99%
```

### Concurrent Users

```txt
100,000+
```

---

# Security Requirements

### OWASP Compliance

Protect against:

```txt
SQL Injection
XSS
CSRF
Session Hijacking
Brute Force
Credential Stuffing
```

---

### Cookies

```txt
HttpOnly
Secure
SameSite=Strict
```

---

# Infrastructure

## Redis

Use for:

```txt
Session Cache
OTP Storage
Rate Limiting
Token Blacklist
```

---

## PostgreSQL

Store:

```txt
Users
Sessions
Roles
Audit Logs
```

---

# Tech Stack

### Frontend

* Next.js 15
* TypeScript
* Tailwind CSS
* ShadCN UI
* React Hook Form
* Zod

### Backend

* NestJS
* Prisma
* PostgreSQL
* Redis

### Security

* Argon2
* JWT
* Passport.js
* OAuth 2.0

### Email

* [[Resend](https://resend.com/?utm_source=chatgpt.com)](https://resend.com?utm_source=chatgpt.com)
* [[SendGrid](https://sendgrid.com/?utm_source=chatgpt.com)](https://sendgrid.com?utm_source=chatgpt.com)

---

# Acceptance Criteria

✅ User can signup with email/password
✅ Email verification works
✅ Social login works (Google/GitHub/LinkedIn)
✅ Login & logout work
✅ Refresh token rotation works
✅ Forgot password works
✅ Session management works
✅ RBAC implemented
✅ 2FA implemented
✅ Audit logging implemented
✅ Rate limiting enabled
✅ CAPTCHA protection enabled
✅ OWASP security checks passed
✅ Mobile responsive UI
✅ Production deployment ready


Uh oh!

Enterprise Authentication & Authorization System (Production Ready) #14

Description

Business Requirements

Goals

Authentication Flow

Features

User Registration

Normal Signup

Social Login

Google OAuth

GitHub OAuth

LinkedIn OAuth

Future

Email Verification

Login System

Email Login

Social Login

Forgot Password

Password Reset Rules

Session Management

JWT Architecture

Access Token

Refresh Token

Security Layer

Password Hashing

Rate Limiting

Brute Force Protection

CAPTCHA

Two Factor Authentication (2FA)

Device Tracking

Authorization (RBAC)

Permissions Matrix

USER

JUDGE

ORGANIZATION_ADMIN

SUPER_ADMIN

Database Schema

User

Session

Email Verification

Password Reset

OAuth Account

API Endpoints

Signup

Verify Email

Login

Logout

Logout All Devices

Refresh Token

Forgot Password

Reset Password

Enable 2FA

Verify 2FA

Frontend Pages

Public

Protected

UI Components

Notifications

Email

In-App

Audit Logging

Performance Requirements

API Response

Authentication Success Rate

Concurrent Users

Security Requirements

OWASP Compliance

Cookies

Infrastructure

Redis

PostgreSQL

Tech Stack

Frontend

Backend

Security

Email

Acceptance Criteria

Metadata

Metadata