Stateless Auth with MySQL (Drizzle)

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

Installation

pnpmnpmyarnbun

npx servercn-cli add blueprint stateless-auth

During installation, select MySQL (Drizzle) 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.

API Endpoints

All endpoints are the same for both MVC and Feature architectures.

Authentication Routes

Base URL: http://localhost:3000/api/v1/auth

OAuth Routes

Base URL: http://localhost:3000/api/auth

Health Check

Base URL: http://localhost:3000/api/v1/health

Project Structure

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

MVC Structure

src/
├── configs/          # Database, social auth, and environment setup
├── constants/        # Shared application constants and status codes
├── controllers/      # Route logic and request handling
├── drizzle/          # Drizzle ORM schema and database configuration
├── helpers/           # Utility functions for cookies, tokens, etc.
├── middlewares/      # Auth verification, rate limiting, and security
├── 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

Feature Structure

src/
├─ cron/
│  └─ cleanup-refresh-tokens.cron.ts
├─ docs/
│  └─ swagger.json
├─ drizzle/
│  ├─ migrations/
│  └─ schemas/
│     ├─ refresh-token.schema.ts
│     ├─ schema.helper.ts
│     ├─ user.schema.ts
│     └─ index.ts
├─ email-templates/
│  ├─ email-verification.ejs
│  └─ forgot-password.ejs
├─ modules/
│  ├─ auth/
│  ├─ health/
│  ├─ oauth/
│  ├─ otp/
│  └─ upload/
├─ routes/
│  └─ index.ts
├─ shared/
│  ├─ configs/
│  ├─ constants/
│  ├─ helpers/
│  ├─ middlewares/
│  └─ utils/
└─ types/
   ├─ global.d.ts
   ├─ app.ts
   └─ server.ts

Security Features

• Relational Integrity: Uses foreign keys to link tokens to users.
• Token Rotation: Every refresh cycle invalidates the previous token.
• Type Safety: Full TypeScript support with Drizzle ORM.
• Secure Cookies: HTTP-only and Secure flags for production environments.

Contributing

Found a bug or want to suggest improvements? Please contribute to the Servercn project!

Support

Need help? Join our Discord community or open an issue on GitHub.