Stateless Auth (MongoDB)

This blueprint provides a complete stateless authentication system for Express applications using MongoDB and Mongoose. It features JWT-based access and refresh tokens, token rotation, and secure cookie management.

Installation Guide

npx servercn-cli add blueprint stateless-auth

During installation, select MongoDB (Mongoose) as your database.

Features

This blueprint comes packed with production-ready features organized into a clean, modular structure:

JWT Stateless Auth: Secure authentication using Access and Refresh tokens with automatic rotation.
Token Reuse Detection: Advanced security layer that detects and revokes compromised tokens.
OAuth 2.0 Support: Fully configured Google and GitHub social authentication.
OTP System: Integrated email-based One-Time Password service for sign-in and resets.
Profile Management: Built-in support for profile updates and Cloudinary-powered avatar uploads.
Security Suite: Comprehensive protection with Helmet headers, CORS, and multi-level rate limiting.
Validated Architecture: Model-View-Controller (MVC) or Feature-based patterns with full Zod validation.
Error Management: Standardized API response wrappers and centralized global error handling.
Health Monitoring: Dedicated endpoints for heartbeat and system status checks.

Project Structure

The blueprint implements a highly organized directory structure designed for scalability and maintainability:

src/
├── configs/          # Database, social auth, and environment setup
├── constants/        # Shared application constants and status codes
├── controllers/      # Route logic and request handling
├── helpers/          # Utility functions for cookies, tokens, etc.
├── middlewares/      # Auth verification, rate limiting, and security
├── models/           # Mongoose schemas for User, OTP, and Tokens
├── routes/           # API route definitions and versioning
├── services/         # Core business logic and 3rd-party integrations
├── types/            # TypeScript interface and type declarations
├── utils/            # Shared utilities (logger, error classes)
├── validators/       # Zod schemas for request validation
├── app.ts            # Express application setup
└── server.ts         # Server entry point and database connection

Architecture Support

This blueprint supports both MVC and Feature-based architectures.

MVC : Model, Controllers, Services..
Feature-based, Modules, Shared..

Security Features

Token Rotation: New refresh token issued on every refresh.
Reuse Detection: Old refresh tokens are invalidated if reused.
Secure Storage: tokens stored in httpOnly cookies.
Hashed Tokens: Refresh tokens are hashed before storage.