npm package: @prathammeena/express-auth-boilerplate
Description: Production-ready Express.js authentication boilerplate with JWT, email verification, MongoDB, TypeScript, and comprehensive testing
Author: Pratham Meena
Latest version: 1.0.0

# Random Quiz API

A production-ready authentication system built with Node.js, TypeScript, Express, MongoDB, and JWT.

## Features

- ✅ **User Registration** with email verification (OTP-based)
- ✅ **Email Verification** with resend capability
- ✅ **Login/Logout** with JWT access and refresh tokens
- ✅ **Token Refresh** mechanism
- ✅ **Password Change** (authenticated users)
- ✅ **Password Reset** with email OTP
- ✅ **User Profile** CRUD operations
- ✅ **Account Deletion**
- ✅ **Security**: Helmet, CORS, rate limiting, compression
- ✅ **Logging**: Winston + Morgan for structured logs
- ✅ **Validation**: Zod schemas
- ✅ **Testing**: Vitest + Supertest

## Prerequisites

- Node.js >= 18.18.0
- MongoDB running locally or remote connection
- SendGrid account (for email delivery)

## Installation

```bash
npm install
```

## Configuration

Copy `.env.example` to `.env` and configure:

```env
PORT=3000
MONGO_URI=mongodb://127.0.0.1:27017/random-quiz
NODE_ENV=development
LOG_LEVEL=info

# Generate strong secrets (use: openssl rand -base64 32)
JWT_ACCESS_SECRET=your-access-secret-here
JWT_REFRESH_SECRET=your-refresh-secret-here
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

BCRYPT_SALT_ROUNDS=12

EMAIL_VERIFICATION_TTL_MINUTES=15
PASSWORD_RESET_TTL_MINUTES=15

APP_URL=http://localhost:3000
CLIENT_URL=http://localhost:3000

# Get from SendGrid: https://sendgrid.com/
SENDGRID_API_KEY=your-sendgrid-api-key
SENDGRID_FROM_EMAIL=no-reply@yourdomain.com
SENDGRID_FROM_NAME=Random Quiz
```

## Scripts

```bash
# Development (with hot reload)
npm run dev

# Build
npm run build

# Production
npm start

# Lint
npm run lint

# Format
npm run format

# Test
npm run test
npm run test:watch
```

## API Endpoints

### Health Check
- `GET /api/health` - Service health check

### Authentication
- `POST /api/auth/register` - Register new user
- `POST /api/auth/verify-email` - Verify email with OTP
- `POST /api/auth/resend-verification` - Resend verification OTP
- `POST /api/auth/login` - Login user
- `POST /api/auth/refresh-token` - Refresh access token
- `POST /api/auth/logout` - Logout (revoke refresh token)
- `POST /api/auth/forgot-password` - Request password reset OTP
- `POST /api/auth/reset-password` - Reset password with OTP
- `POST /api/auth/change-password` - Change password (authenticated)

### User Profile
- `GET /api/users/me` - Get current user profile
- `PATCH /api/users/me` - Update user profile
- `DELETE /api/users/me` - Delete user account

## API Examples

### Register
```bash
POST /api/auth/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePass123!"
}
```

### Verify Email
```bash
POST /api/auth/verify-email
Content-Type: application/json

{
  "email": "john@example.com",
  "code": "123456"
}
```

### Login
```bash
POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Response:
{
  "success": true,
  "message": "Login successful",
  "data": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc..."
  }
}
```

### Get Profile (Authenticated)
```bash
GET /api/users/me
Authorization: Bearer <accessToken>
```

### Change Password (Authenticated)
```bash
POST /api/auth/change-password
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "currentPassword": "SecurePass123!",
  "newPassword": "NewSecurePass456!"
}
```

### Forgot Password
```bash
POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "john@example.com"
}
```

### Reset Password
```bash
POST /api/auth/reset-password
Content-Type: application/json

{
  "email": "john@example.com",
  "code": "123456",
  "newPassword": "NewSecurePass456!"
}
```

## Security Features

- **Helmet**: Sets secure HTTP headers
- **CORS**: Cross-origin resource sharing
- **Rate Limiting**: 100 requests per 15 minutes per IP
- **Compression**: Gzip compression for responses
- **JWT**: Secure token-based authentication
- **Bcrypt**: Password hashing with configurable salt rounds
- **Email Verification**: OTP-based email verification
- **Refresh Token Rotation**: Enhanced security with token rotation
- **Multi-device Support**: Track and manage multiple sessions

## Architecture

```
src/
├── config/          # Configuration (env, database)
├── controllers/     # Request handlers
├── middlewares/     # Express middlewares (auth, validation)
├── models/          # Mongoose schemas
├── routes/          # API routes
├── services/        # Business logic (email service)
├── types/           # TypeScript type definitions
├── utils/           # Utility functions (jwt, password, otp, logger)
└── validators/      # Zod validation schemas
```

## Testing

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch
```

## Logging

Logs are written to:
- `logs/error.log` - Error-level logs
- `logs/combined.log` - All logs
- Console (development only)

## License

ISC