AuthPool

A plug-and-play Node.js authentication server. One function call gives you Google OAuth, email/password login, JWT access tokens, rotating refresh tokens, CSRF protection, rate limiting, brute-force lockout, and role-based access control — all production-ready.

---

Install

npm install authpool

---

Quickstart

const { startAuthServer } = require("authpool");

startAuthServer({
  mongoURI:      process.env.MONGO_URI,
  jwtSecret:     process.env.JWT_SECRET,
  sessionSecret: process.env.SESSION_SECRET,
});

The server starts at http://localhost:5000. All auth routes are live immediately.

---

Environment Variables

Create a .env file in your project root. AuthPool loads it automatically — you don't need to call require('dotenv') yourself.

Variable	Required	Description
MONGO_URI	✅	MongoDB connection string
JWT_SECRET	✅	JWT signing secret (32+ random characters)
SESSION_SECRET	✅	Session cookie secret (different from JWT)
GOOGLE_CLIENT_ID	OAuth	Google OAuth client ID
GOOGLE_CLIENT_SECRET	OAuth	Google OAuth client secret
GOOGLE_CALLBACK_URL	OAuth	e.g. http://localhost:5000/auth/google/callback
PORT	—	Listening port (default: 5000)
CSRF_SECRET	—	Separate CSRF secret (defaults to SESSION_SECRET)
REDIS_URL	—	Redis connection URL

Missing required variables cause a clean startup error that lists exactly what's missing.

---

API Routes

Health

Method	Path	Description
GET	/	Returns { status: "ok" }

Auth

Method	Path	Auth required	Description
GET	/auth/csrf	—	Returns a CSRF token (also sent in response header)
POST	/auth/register	—	Create account with { email, password, name }
POST	/auth/login	—	Login with { email, password }
GET	/auth/google	—	Redirect to Google OAuth consent screen
GET	/auth/google/callback	—	OAuth callback — handled automatically
GET	/auth/protected	Bearer JWT	Test route — returns decoded token payload
GET	/auth/me	Bearer JWT	Returns full user record from MongoDB
GET	/auth/admin	Bearer JWT + admin role	Admin-only test route
POST	/auth/refresh	Cookie	Rotate refresh token, get new access token
GET	/auth/logout	—	Revoke refresh token and clear cookie
POST	/auth/logout-all	Bearer JWT	Invalidate all tokens across all devices

Register & Login responses

{ "accessToken": "<jwt>", "roles": ["user"] }

A refreshToken httpOnly cookie is also set automatically.

---

Full Configuration

const { startAuthServer } = require("authpool");

const { app, server } = await startAuthServer({
  // Required (or set via .env)
  mongoURI:      "mongodb://localhost:27017/myapp",
  jwtSecret:     "super-secret-32-char-minimum",
  sessionSecret: "another-secret-32-char-minimum",

  // Google OAuth (optional)
  googleClientID:     "...",
  googleClientSecret: "...",
  googleCallbackURL:  "http://localhost:5000/auth/google/callback",

  // Server
  port: 5000,

  // CORS
  corsOptions: {
    origin:      "http://localhost:3000",
    methods:     ["GET", "POST"],
    credentials: true,
  },

  // Rate limiting (these are the defaults — only override what you need)
  rateLimit: {
    global:   { windowMs: 15 * 60 * 1000, max: 300 },
    auth:     { windowMs: 60 * 1000,       max: 30  },
    slowdown: { windowMs: 60 * 1000, delayAfter: 3, delayMs: 300 },
  },

  // CSRF (enabled by default)
  csrf: {
    enabled:    true,
    headerName: "x-csrf-token",  // send this header on every mutating request
    cookieName: "authpool.csrf",
    secret:     "optional-separate-csrf-secret",
  },

  // Redis (optional but recommended for production)
  redis: {
    url: "redis://localhost:6379",
    // host: "localhost", port: 6379   ← alternative
    // enabled: false                  ← force in-memory
  },

  // Transform an OAuth profile before the DB upsert (optional)
  transformUser: (profile, provider) => ({
    googleId:   profile.id,
    email:      profile.emails?.[0]?.value,
    name:       profile.displayName,
    profilePic: profile.photos?.[0]?.value,
    roles:      ["user"],
    // add any custom fields here
  }),

  // Add your own routes after AuthPool finishes startup
  onReady: (app, server) => {
    app.get("/api/hello", (req, res) => res.json({ message: "custom route" }));
  },
});

---

Frontend Usage

1 — Register

const res = await fetch("http://localhost:5000/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-csrf-token": csrfToken },
  credentials: "include",   // sends the cookie
  body: JSON.stringify({ email, password, name }),
});
const { accessToken } = await res.json();

2 — Attach the token to requests

fetch("/api/protected-resource", {
  headers: { Authorization: `Bearer ${accessToken}` },
  credentials: "include",
});

3 — Refresh silently when the token expires

async function refresh() {
  const res = await fetch("http://localhost:5000/auth/refresh", {
    method: "POST",
    credentials: "include",   // the cookie is sent automatically
  });
  const { accessToken } = await res.json();
  return accessToken;
}

4 — CSRF token

Fetch once and reuse. A fresh token is also returned in the x-csrf-token header of every GET response.

const res = await fetch("http://localhost:5000/auth/csrf", { credentials: "include" });
const { csrfToken } = await res.json();
// Include as x-csrf-token header on every POST / PATCH / DELETE

---

Adding Protected Routes

Use the onReady hook to access the Express app and add routes after startup:

const verifyJWT       = require("authpool/src/middleware/verifyJWT");
const { authorizeRoles } = require("authpool/src/middleware/authorizeRoles");

startAuthServer({
  // ...config...
  onReady: (app) => {
    const JWT_SECRET = process.env.JWT_SECRET;

    // Any authenticated user
    app.get("/api/profile", verifyJWT(JWT_SECRET), (req, res) => {
      res.json({ user: req.user });
    });

    // Admin only
    app.get("/api/admin", verifyJWT(JWT_SECRET), authorizeRoles(["admin"]), (req, res) => {
      res.json({ message: "admin area" });
    });
  },
});

---

Security Summary

Feature	Default
Password hashing	bcrypt, 12 salt rounds
Access token expiry	15 minutes
Refresh token expiry	30 days, rotated on every use
Refresh token storage	SHA-256 hashed in MongoDB, httpOnly cookie
CSRF protection	Double-submit cookie (csrf-csrf)
Brute-force lockout	5 failures → 15-minute IP lockout
Rate limiting	Global 300/15 min, credential 30/min
HTTP headers	helmet defaults
Session storage	MongoDB (connect-mongo), not MemoryStore

---

Redis

Redis is optional. Without it everything works using in-process memory (single server only). With it, rate limiters, brute-force counters, and the JWT user cache scale across multiple instances and survive restarts.

# Local Redis via Docker
docker run -d -p 6379:6379 redis:7

REDIS_URL=redis://localhost:6379

Pass redis: { enabled: false } to force in-memory mode even when REDIS_URL is set (useful in tests).

---

TypeScript

Types are included at authpool/types/index.d.ts. Import AuthPoolOptions for full autocomplete:

import { startAuthServer, AuthPoolOptions } from "authpool";

const options: AuthPoolOptions = { /* ... */ };
await startAuthServer(options);

---

Requirements

• Node.js 18+
• MongoDB 5+ (local or Atlas)
• Redis (optional, recommended for production)

---

License

MIT