Package Exports

@prathammeena/express-auth-boilerplate
@prathammeena/express-auth-boilerplate/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@prathammeena/express-auth-boilerplate) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

npm install

Configuration

Copy .env.example to .env and configure:

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

# 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

POST /api/auth/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Verify Email

POST /api/auth/verify-email
Content-Type: application/json

{
  "email": "john@example.com",
  "code": "123456"
}

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)

GET /api/users/me
Authorization: Bearer <accessToken>

Change Password (Authenticated)

POST /api/auth/change-password
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "currentPassword": "SecurePass123!",
  "newPassword": "NewSecurePass456!"
}

Forgot Password

POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "john@example.com"
}

Reset Password

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

# 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