Drop-in authentication module for Express.js + MongoDB + TypeScript.

Copy the src/auth/ folder into your project, paste a single prompt to your AI coding agent, and it handles everything.

The AI agent will:

1. Ask which features you need
2. Collect your config (MongoDB URI, OAuth keys, etc.)
3. Install dependencies, create .env, wire into your Express app
4. Verify everything works

👉 Get the AI prompt →

Already have an Express + MongoDB project? 3 steps:

1. Download & Install

# Download the latest release from GitHub Releases:
# https://github.com/IamAshrafee/ModularAuth-Kit/releases
# Extract and copy the src/auth/ folder into your project.

npm install argon2 zod helmet cookie-parser    # skip any you already have

2. Add SESSION_SECRET to your existing .env

SESSION_SECRET=your-random-64-char-secret-here

3. Mount (2 lines in your existing app)

import { createConfig, createAuthModule } from './auth/index.js';

const config = createConfig({ session: { secure: false } }); // secure:true in prod
app.use('/auth', createAuthModule(config));

That's it. Your existing MongoDB connection is reused automatically. No extra DB setup needed.

💡 Already have mongoose.connect() in your project? The auth module piggybacks on it — it uses whatever Mongoose connection is already active. You don't need to call connectDatabase() or set MONGODB_URI again.

If this is a brand-new project, you also need MongoDB:

npm install express mongoose dotenv

// server.ts
import 'dotenv/config';
import mongoose from 'mongoose';

await mongoose.connect(process.env.MONGODB_URI!);
// ... then the 3 steps above

All features are disabled by default — enable only what you need:

createConfig({
  login: {
    identifiers: ['email', 'username'],
    allowGoogleOAuth: true,
  },
  passwordRecovery: { enabled: true },
  emailVerification: { enabled: true },
  loginHistory: { enabled: true },
  sessionManagement: { enabled: true },
  security: {
    accountLockout: {
      enabled: true,
      maxFailedAttempts: 5,
      lockDurationMinutes: 15,
    },
  },
});

• Runtime: Node.js 18+
• Framework: Express.js 5.x
• Database: MongoDB via Mongoose 9.x
• Language: TypeScript 5.x
• Validation: Zod 3.x
• Security: Helmet, argon2, cookie-parser

Full documentation lives in docs/:

• Getting Started
• Configuration
• API Reference
• Use Case Scenarios
• AI Integration Guide
• Security
• FAQ

src/auth/
├── index.ts            ← Entry point (createAuthModule)
├── services/           ← Business logic
├── http/controllers/   ← Request handlers
├── http/middleware/     ← Auth, validation, rate limiting
├── http/routes/        ← Route mounting
├── repositories/       ← Database access (swappable)
├── models/             ← Mongoose schemas
├── adapters/           ← Email, database adapters
└── utils/              ← Crypto, audit logger, device parser

MIT