https://github.com/devdogukan/nestjs-auth-app
https://github.com/devdogukan/nestjs-auth-app
Last synced: 27 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/devdogukan/nestjs-auth-app
- Owner: devdogukan
- Created: 2025-10-27T10:47:31.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-10-28T11:19:05.000Z (8 months ago)
- Last Synced: 2025-10-28T13:17:06.648Z (8 months ago)
- Language: TypeScript
- Size: 125 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚀 NestJS Authentication System - Complete Feature List
## ✨ Completed Features
### 🔐 Authentication
- ✅ **JWT Access Token** (15 minutes lifetime)
- ✅ **JWT Refresh Token** (7 days lifetime)
- ✅ **Register** - New user registration
- ✅ **Login** - User login
- ✅ **Logout** - Secure logout (refresh token cleanup)
- ✅ **Token Refresh** - Automatic token renewal
- ✅ **Bcrypt** password hashing
### 📧 Email Verification
- ✅ **Email Verification** - Post-registration email verification
- ✅ **Resend Verification** - Resend verification email
- ✅ **Welcome Email** - Welcome email after successful verification
- ✅ **Email Templates** - HTML email templates
- ✅ **Nodemailer** integration
### 🔑 Password Reset
- ✅ **Forgot Password** - Password recovery
- ✅ **Reset Password** - Token-based password reset
- ✅ **Token Expiration** - 1-hour token lifetime
- ✅ **One-time Token** - Single-use tokens
### 🗄️ Database Integration (PostgreSQL)
- ✅ **TypeORM** integration
- ✅ **PostgreSQL** database
- ✅ **Docker Compose** setup
- ✅ **Auto-sync** (for development)
- ✅ **UUID** primary keys
- ✅ **Timestamps** (createdAt, updatedAt)
### 👥 Role-Based Access Control (RBAC)
- ✅ **4 Different Roles:**
- `USER` - Regular user
- `MODERATOR` - Moderator
- `ADMIN` - Administrator
- `SUPER_ADMIN` - Super Administrator
- ✅ **@Roles() Decorator** - Endpoint-based authorization
- ✅ **RolesGuard** - Automatic role checking
- ✅ **Multiple role support** - A user can have multiple roles
### ⚡ Rate Limiting
- ✅ **Global Rate Limiting** - For all endpoints (via ThrottlerModule)
- ✅ **Configurable Limits** - TTL and limit settings via .env
- ✅ **ThrottlerGuard** - Global rate limiting protection
- ✅ **Custom Decorators:**
- `@SkipThrottle()` - Skip rate limiting (from @nestjs/throttler)
- `@Throttle()` - Custom rate limits per endpoint
### 🛡️ Security Features
- ✅ **Password Hashing** - Bcrypt (10 rounds)
- ✅ **JWT Signed Tokens** - Secret key signing
- ✅ **Refresh Token Rotation** - New token on each refresh
- ✅ **Email Case Insensitive** - Lowercase emails
- ✅ **User Deactivation** - Users can be deactivated
- ✅ **Token Invalidation** - Token invalidation on logout
### 📝 Validation & Error Handling
- ✅ **Class Validator** - DTO validation
- ✅ **Class Transformer** - Automatic transformation
- ✅ **Custom Error Messages** - Descriptive error messages
- ✅ **HTTP Status Codes** - Proper status codes
- ✅ **Global Validation Pipe** - For all endpoints
### 🎨 Custom Decorators
- ✅ `@CurrentUser()` - Active user information
- ✅ `@Roles(Role.ADMIN)` - Role checking
- ✅ `@Public()` - Public endpoint
- ✅ `@SkipThrottle()` - Skip rate limit (from @nestjs/throttler)
### 👤 User Management
- ✅ **Get All Users** - List all users (ADMIN)
- ✅ **Get User by ID** - User details (ADMIN)
- ✅ **Get My Profile** - My profile (USER)
- ✅ **Update Roles** - Role update (SUPER_ADMIN)
- ✅ **Activate/Deactivate** - User activation/deactivation (ADMIN)
- ✅ **Delete User** - Delete user (SUPER_ADMIN)
---
## 📁 Project Structure
```
src/
├── auth/
│ ├── decorators/
│ │ ├── current-user.decorator.ts # @CurrentUser() decorator
│ │ ├── public.decorator.ts # @Public() decorator
│ │ └── roles.decorator.ts # @Roles() decorator
│ ├── dto/
│ │ ├── forgot-password.dto.ts # Forgot password DTO
│ │ ├── login.dto.ts # Login DTO
│ │ ├── refresh-token.dto.ts # Refresh token DTO
│ │ ├── register.dto.ts # Register DTO
│ │ ├── resend-vertification.dto.ts # Resend verification DTO
│ │ ├── reset-password.dto.ts # Reset password DTO
│ │ ├── update-roles.dto.ts # Update roles DTO
│ │ └── verify-email.dto.ts # Verify email DTO
│ ├── enums/
│ │ └── role.enum.ts # Role definitions
│ ├── guards/
│ │ ├── jwt-auth.guard.ts # JWT authentication guard
│ │ ├── jwt-refresh.guard.ts # JWT refresh token guard
│ │ └── roles.guard.ts # Role-based authorization guard
│ ├── strategies/
│ │ ├── jwt.strategy.ts # JWT authentication strategy
│ │ └── jwt-refresh.strategy.ts # JWT refresh strategy
│ ├── auth.controller.spec.ts # Auth controller tests
│ ├── auth.controller.ts # Auth endpoints
│ ├── auth.service.spec.ts # Auth service tests
│ ├── auth.service.ts # Auth business logic
│ └── auth.module.ts # Auth module
│
├── users/
│ ├── entities/
│ │ └── user.entity.ts # User database entity
│ ├── users.controller.spec.ts # Users controller tests
│ ├── users.controller.ts # User management endpoints
│ ├── users.service.spec.ts # Users service tests
│ ├── users.service.ts # User CRUD operations
│ └── users.module.ts # Users module
│
├── email/
│ ├── email.service.spec.ts # Email service tests
│ ├── email.service.ts # Email sending service
│ └── email.module.ts # Email module
│
├── app.module.ts # Main application module
└── main.ts # Application bootstrap
test/
├── app.e2e-spec.ts # E2E tests
└── jest-e2e.json # Jest E2E configuration
```
---
## 🔧 Environment Variables
```env
# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=15m
JWT_REFRESH_SECRET=your-super-secret-refresh-key
JWT_REFRESH_EXPIRES_IN=7d
# Database Configuration
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=postgres
DATABASE_NAME=nestjs_auth
DATABASE_SYNC=true
# Email Configuration
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=noreply@yourapp.com
# Application Configuration
APP_NAME=NestJS Auth App
FRONTEND_URL=http://localhost:3001
PORT=3000
# Rate Limiting (Global - applies to all endpoints)
THROTTLER_TTL=60 # Time window in seconds
THROTTLER_LIMIT=10 # Maximum requests per time window
```
---
## 🎯 API Endpoints
### Authentication
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/auth/register` | ❌ | User registration |
| POST | `/auth/verify-email` | ❌ | Email verification |
| POST | `/auth/resend-verification` | ❌ | Resend verification email |
| POST | `/auth/login` | ❌ | Login |
| POST | `/auth/forgot-password` | ❌ | Forgot password |
| POST | `/auth/reset-password` | ❌ | Reset password |
| POST | `/auth/refresh` | 🔄 Refresh | Refresh token |
| POST | `/auth/logout` | ✅ JWT | Logout |
| GET | `/auth/profile` | ✅ JWT | My profile |
### User Management
| Method | Endpoint | Auth | Role | Description |
|--------|----------|------|------|-------------|
| GET | `/users` | ✅ JWT | ADMIN+ | Get all users |
| GET | `/users/me` | ✅ JWT | USER | Get my profile |
| GET | `/users/:id` | ✅ JWT | ADMIN+ | Get user details |
| PATCH | `/users/:id/roles` | ✅ JWT | SUPER_ADMIN | Update roles |
| PATCH | `/users/:id/activate` | ✅ JWT | ADMIN+ | Activate user |
| PATCH | `/users/:id/deactivate` | ✅ JWT | ADMIN+ | Deactivate user |
| DELETE | `/users/:id` | ✅ JWT | SUPER_ADMIN | Delete user |
---
## 📊 Rate Limit Configuration
Rate limiting is configured globally in `app.module.ts` using `@nestjs/throttler`:
```typescript
// app.module.ts - ThrottlerModule Configuration
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => [
{
name: "default",
ttl: Number(configService.getOrThrow("THROTTLER_TTL")) * 1000, // milliseconds
limit: Number(configService.getOrThrow("THROTTLER_LIMIT")),
},
],
}),
```
**Environment Variables:**
```env
THROTTLER_TTL=60 # Time window in seconds (converted to ms)
THROTTLER_LIMIT=10 # Max requests per time window
```
**Usage Examples:**
```typescript
// Skip throttling for specific endpoint
import { SkipThrottle } from '@nestjs/throttler';
@SkipThrottle()
@Get('unlimited')
async unlimitedEndpoint() { ... }
// Custom throttle for specific endpoint
import { Throttle } from '@nestjs/throttler';
@Throttle({ default: { limit: 3, ttl: 60000 } }) // 3 requests per minute
@Post('limited')
async limitedEndpoint() { ... }
```
---
## 🚀 Quick Start
### 1. Installation
```bash
npm install
```
### 2. Start Database
```bash
docker-compose up -d
```
### 3. Setup Environment
```bash
cp .env.example .env
# Edit .env file
```
### 4. Run Application
```bash
npm run start:dev
```
### 5. Create First Admin
```sql
INSERT INTO users (id, email, password, name, roles, "isEmailVerified", "isActive")
VALUES (
gen_random_uuid(),
'admin@admin.com',
'$2b$10$rG8Hq5HxYqGkL3BvUqKxaO5wKJYyGEzJL8Q7oPpZO8EEpN1x2LZfm',
'Super Admin',
'{super_admin,admin,user}',
true,
true
);
```
---
## 💡 Important Notes
### Production Preparation
1. ✅ Set `DATABASE_SYNC=false`
2. ✅ Create migrations
3. ✅ Strengthen secret keys
4. ✅ Configure CORS settings
5. ✅ Add Helmet middleware
6. ✅ Configure rate limiting
7. ✅ Set up logging system
8. ✅ Add health check endpoint
### Security Checklist
- ✅ Passwords are hashed (bcrypt)
- ✅ JWT tokens are signed
- ✅ Refresh token rotation active
- ✅ Rate limiting working
- ✅ Email verification required
- ✅ RBAC system active
- ✅ User deactivation available
- ✅ Validation on all endpoints
### Performance Improvements
- 🔄 Redis caching (TODO)
- 🔄 Redis for token blacklist (TODO)
- 🔄 Email queue system (TODO)
- 🔄 Database indexes (TODO)
---
## 📝 Next Steps (Optional)
1. **Social Login** - Google, GitHub, Facebook OAuth
2. **Two-Factor Authentication (2FA)** - With TOTP
3. **Session Management** - View/terminate active sessions
4. **Audit Logging** - Log all operations
5. **Email Templates Engine** - Dynamic emails with Handlebars
6. **Unit & E2E Tests** - Test coverage
7. **Monitoring** - Sentry, DataDog etc.
---