Features — ModularAuth-Kit

Core

Email & Password Authentication

Register, login, logout, profile management, and password changes — all handled out of the box. Passwords are hashed with argon2id using OWASP-recommended parameters.

Enumeration protection uses identical error messages for "user not found" and "wrong password" to prevent email harvesting attacks.

7 endpoints, always available

POST  /auth/register
POST  /auth/login
POST  /auth/logout
POST  /auth/logout-all
GET   /auth/me
PATCH /auth/me
POST  /auth/change-password
          

Core

Server-Side Sessions

Sessions are stored in MongoDB — not in the cookie. The browser only receives an httpOnly, signed, SameSite cookie with the session ID.

Session IDs are rotated on login to prevent fixation attacks. Idle sessions expire after 30 minutes of inactivity.

Session config

createConfig({
  session: {
    cookieName: 'sid',
    maxAge: 604_800_000,     // 7 days
    idleTimeout: 1_800_000,  // 30 min
    rotateOnLogin: true,
    secure: true,            // HTTPS
    sameSite: 'lax',
  },
});
          

Opt-in

Password Recovery

Forgot password and reset password flows with cryptographically secure tokens. Tokens are hashed (SHA-256) before database storage and expire after 15 minutes.

The forgot-password response is always the same whether the email exists or not — preventing email enumeration.

Enable with one line

createConfig({
  passwordRecovery: { enabled: true },
});

// Adds:
// POST /auth/forgot-password
// POST /auth/reset-password
          

Opt-in

Email Verification

6-digit OTP sent by email. Use the console adapter in development (prints to terminal) and Nodemailer in production.

Optionally block unverified users from accessing protected routes with requiredForLogin.

Configuration

createConfig({
  emailVerification: {
    enabled: true,
    requiredForLogin: false,
  },
  email: { adapter: 'console' },
});

// Adds:
// POST /auth/verify-email
// POST /auth/resend-verification
          

Opt-in

Google OAuth 2.0

Direct HTTP implementation — no Passport.js dependency. Handles the full OAuth flow including automatic account linking when a Google email matches an existing account.

Configuration

createConfig({
  login: { allowGoogleOAuth: true },
});

// Set in .env:
// GOOGLE_CLIENT_ID=
// GOOGLE_CLIENT_SECRET=
// GOOGLE_CALLBACK_URL=

// Adds:
// GET /auth/google
// GET /auth/google/callback
          

Opt-in

Account Lockout

Temporarily locks an account after too many failed login attempts. The lock auto-expires — no admin intervention needed. Configurable attempt count and lock duration.

Configuration

createConfig({
  security: {
    accountLockout: {
      enabled: true,
      maxFailedAttempts: 5,
      lockDurationMinutes: 15,
    },
  },
});
          

API Reference

16 endpoints. One mount.

All endpoints

── Always Available ──────────────────────
POST   /auth/register          Create account
POST   /auth/login             Login
POST   /auth/logout            Logout
POST   /auth/logout-all        Logout all devices
GET    /auth/me                Get profile
PATCH  /auth/me                Update profile
POST   /auth/change-password   Change password

── Password Recovery (opt-in) ────────────
POST   /auth/forgot-password   Request reset
POST   /auth/reset-password    Reset with token

── Email Verification (opt-in) ───────────
POST   /auth/verify-email      Verify OTP
POST   /auth/resend-verification Resend

── Google OAuth (opt-in) ─────────────────
GET    /auth/google            Redirect
GET    /auth/google/callback   Callback

── Login History (opt-in) ────────────────
GET    /auth/login-history     Paginated

── Session Management (opt-in) ───────────
GET    /auth/sessions          List
DELETE /auth/sessions/:id      Revoke
        