JWT Authentication Module

⚡ Quick Start

1. Clone & Install

git clone https://github.com/hoangsonww/jwt-module.git
cd jwt-module
npm install

2. Configure Environment

PORT=5001
JWT_ACCESS_SECRET=your-access-secret-min-32-chars
JWT_REFRESH_SECRET=your-refresh-secret-min-32-chars
CORS_ORIGIN=http://localhost:3000
NODE_ENV=development

3. Run

# Development
PORT=5001 npx ts-node src/server.ts

# Production (build first)
npm run build
NODE_ENV=production node dist/server.js

# Docker
docker compose up --build

4. Test It

# Register
curl -X POST http://localhost:5001/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"Secret123"}'

# Login
curl -X POST http://localhost:5001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"Secret123"}'

# Access protected route
curl http://localhost:5001/auth/me \
  -H "Authorization: Bearer <access_token>"

🏗 Architecture Overview

The module follows a clean layered architecture with strict separation between the HTTP API layer and the authentication business logic.

Key Design Decisions

• No database: All state is in-memory Maps. This keeps the module self-contained and eliminates infrastructure dependencies.
• Interface-driven: The API layer consumes auth via the AuthService interface, making the auth implementation swappable.
• Layer separation: Business logic in src/auth/ never imports Express. HTTP concerns stay in src/api/.
• Error-first: Typed AuthError codes propagate from auth layer to HTTP via ERROR_STATUS_MAP.

🔀 Authentication Flows

Complete Auth Lifecycle

Account Lockout Flow

🔑 Token Management

Token Lifecycle States

Token Rotation

Token Configuration

⚠ Error Handling

Error Architecture

Error Code Reference

Response Shape

All error responses follow a consistent structure:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}

📚 API Reference

All endpoints accept and return JSON. The base URL is http://localhost:5001.

{
  "email": "user@example.com",
  "password": "Secret123"
}

{
  "tokens": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

{
  "email": "user@example.com",
  "password": "Secret123"
}

{
  "tokens": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }

{
  "tokens": {
    "accessToken": "new-access-token...",
    "refreshToken": "new-refresh-token..."
  }
}

Authorization: Bearer <access_token>

{
  "id": "clx9abc123def456",
  "email": "user@example.com",
  "createdAt": "2024-06-15T10:30:00.000Z"
}

{
  "newEmail": "newemail@example.com",
  "password": "Secret123"
}

{ "message": "Email updated successfully" }

{ "password": "Secret123" }

{ "message": "Account deleted successfully" }

{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }

{ "message": "Logged out successfully" }

{ "message": "All sessions revoked successfully" }

{
  "currentPassword": "OldSecret123",
  "newPassword": "NewSecret456"
}

{ "message": "Password changed successfully" }

{ "status": "ok" }

⏱ Rate Limiting

The API uses a per-IP sliding window rate limiter to prevent brute-force and abuse.

Rate Limited Endpoints

🛡 Security Features

🔐 Password Security

Password Policy

• Minimum 8 characters
• At least one letter (a-z or A-Z)
• At least one digit (0-9)
• Hashed with bcrypt using 12 salt rounds (~250ms per hash)
• Plaintext password never stored or logged

🚀 Deployment

Docker

# Build and run with Docker Compose
export JWT_ACCESS_SECRET="your-secret-here"
export JWT_REFRESH_SECRET="your-secret-here"
docker compose up --build -d

# Check health
curl http://localhost:5001/health

Kubernetes (Kustomize)

# Dev
kubectl apply -k k8s/overlays/dev

# Staging
kubectl apply -k k8s/overlays/staging

# Production
kubectl apply -k k8s/overlays/prod

Kubernetes (Helm)

# Install
helm install jwt-module k8s/helm -f k8s/helm/values-prod.yaml

# Upgrade
helm upgrade jwt-module k8s/helm -f k8s/helm/values-prod.yaml

AWS (Terraform + ECS Fargate)

cd aws/terraform
terraform init
terraform plan -var-file=environments/prod.tfvars
terraform apply -var-file=environments/prod.tfvars

Azure (Terraform + AKS)

cd azure/terraform
terraform init
terraform plan -var-file=environments/prod.tfvars
terraform apply -var-file=environments/prod.tfvars

⚙ Configuration Reference

🧪 Testing

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Run specific test file
npx jest --config jest.config.ts src/tests/auth-service.test.ts

Test Suite Overview

📈 Module Dependency Graph

🤝 Contributing

Development Setup

git clone https://github.com/hoangsonww/jwt-module.git
cd jwt-module
npm install
npm test                   # Verify everything passes
PORT=5001 npx ts-node src/server.ts   # Start dev server

Project Conventions

• All auth business logic goes in src/auth/ — never in the router
• New error codes: add to AuthErrorCode union in errors.ts AND to ERROR_STATUS_MAP in auth-router.ts
• New input schemas go in src/api/validation.ts using Zod
• Tests must clean up state in afterEach (see Testing section)
• No database or external service dependencies without an interface abstraction
• TypeScript strict mode — no any, no @ts-ignore

Adding a New Endpoint

1. Add the method to the AuthService interface in src/api/app.ts
2. Implement the logic in src/auth/auth-service.ts
3. Add Zod validation schema in src/api/validation.ts
4. Add the route in src/api/auth-router.ts
5. Add any new error codes to both errors.ts and ERROR_STATUS_MAP
6. Write tests covering happy path, edge cases, and error cases