🔐 Session Auth - Express.js Authentication Boilerplate

📚 Educational project for learning authentication patterns with Express.js, sessions, and CSRF protection.

An authentication system built with Express.js, featuring session-based authentication, CSRF protection, rate limiting, comprehensive logging, and extensive testing. Perfect for learning modern web authentication patterns.

🔄 Looking for a token-based alternative? Check out: https://github.com/n1kFord/jwt-auth

✨ Features

• 🔑 Session-based authentication with express-session
• 🛡️ CSRF protection (Synchronizer Token Pattern)
• 📦 Redis session store for production scalability
• 🗄️ MongoDB with Mongoose ODM
• 📝 Winston + Morgan logging with chalk styling
• 🧪 Comprehensive test suite with Jest & Supertest
• ✨ ESLint + Prettier for code quality
• 🚦 Rate limiting to prevent brute force attacks
• 🔐 Password hashing with bcrypt
• 🛡️ CORS configuration for cross-origin requests
• 📝 Input validation with express-validator
• 🔄 Session regeneration on login (prevents fixation attacks)

🛠️ Tech Stack

• Runtime: Node.js 20+
• Framework: Express.js 5.x
• Database: MongoDB + Mongoose
• Session Store: Redis (connect-redis)
• Logging: Winston, Morgan, Chalk
• Testing: Jest + Supertest
• Code Quality: ESLint + Prettier
• Security: bcrypt, CSRF, rate limiting, CORS

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (recommended)
• Node.js >= 20 (for local development)
• npm or yarn

With Docker (Recommended)

# Clone repository
git clone https://github.com/n1kFord/session-auth.git
cd session-auth

# Start all services (MongoDB, Redis, and API)
docker compose up -d

# Check logs
docker compose logs -f

# Stop services
docker compose down

# Stop and remove volumes (clears database)
docker compose down -v

Local Development

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Start MongoDB and Redis (using Docker)
docker compose up -d mongo redis

# Start development server
npm run dev

# Production mode
npm start

Environment Variables

# Server
PORT=8080
NODE_ENV=development

# MongoDB
MONGO_URI=mongodb://localhost:27017/authDB

# Redis
REDIS_CLIENT_URI=redis://localhost:6379

# Redis Secret
REDIS_SECRET=your_super_secret_redis_key_min_32_chars

📁 Project Structure

session-auth/
├── src/
│   ├── config/          # DB, Redis, session config
│   ├── middlewares/     # Auth, CSRF, validation, logging
│   ├── models/          # User model
│   ├── routers/         # /auth and /me endpoints
│   ├── utils/           # Helpers (csrf, hash, session)
│   ├── __tests__/       # Jest tests
│   └── index.js         # Entry point
├── logs/                # Winston log files
├── docker-compose.yml
├── Dockerfile
└── package.json

📝 Logging System

• Winston — file + console logging with levels (error, warn, info, debug)
• Morgan — HTTP request logging integrated with Winston
• Chalk — colored console output for better readability

🎨 Code Style

npm run lint        # Check code style
npm run format      # Auto-format with Prettier

🔌 API Endpoints

Authentication (/auth)

Method	Endpoint	Description	CSRF
POST	/register	Register user	❌
POST	/login	Login user	❌
POST	/logout	Logout user	❌

User Management (/me)

Method	Endpoint	Description	CSRF
GET	/	Get profile	❌
POST	/change-email	Change email	✅
POST	/change-password	Change password	✅
POST	/change-username	Change username	✅
POST	/change-bio	Change bio	✅
DELETE	/	Delete account	✅

📝 Examples

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

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

# Get profile (with CSRF)
curl -X GET http://localhost:8080/me/ \
  -H "X-XSRF-Token: your-csrf-token" \
  -H "Cookie: sessionId=your-session-id"

🧪 Testing

npm test

🐳 Docker

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

🛡️ Security

• Session-based with HTTP-only cookies
• CSRF protection (Synchronizer Token Pattern)
• Rate limiting — 100 req/15min, 10 login attempts
• Password hashing with bcrypt
• Session regeneration on login
• Input validation with express-validator

📄 License

This project is licensed under the MIT License.
Feel free to use, modify, and distribute with attribution.

💡 Created with care by @n1kFord

---

⭐ Star this repo if you found it helpful!