MERN Secure Admin Authentication: JWT Access Tokens, Rotating Refresh Tokens and Express Middleware

node -v
npm -v

docker run -d --name mongo -p 27017:27017 mongo

mkdir admin-auth
cd admin-auth
npm init -y
npm install express mongoose bcrypt jsonwebtoken cookie-parser express-rate-limit helmet

"scripts": {
  "dev": "node --env-file=.env --watch server.js",
  "start": "node --env-file=.env server.js",
  "create-admin": "node --env-file=.env scripts/createAdmin.js"
}

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

PORT=4000
MONGO_URI=mongodb://127.0.0.1:27017/admin-auth
JWT_SECRET_KEY=paste-the-64-byte-hex-value-here
JWT_EXPIRES=15m
REFRESH_TOKEN_DAYS=7
BCRYPT_ROUNDS=12
NODE_ENV=development

node_modules/
.env

const mongoose = require('mongoose');
const bcrypt = require('bcrypt');

const adminSchema = new mongoose.Schema(
  {
    name: { type: String, required: true, trim: true },
    email: { type: String, required: true, unique: true, lowercase: true, trim: true },
    phoneNumber: { type: String, unique: true, sparse: true, trim: true },
    password: { type: String, required: true, select: false },
    designation: { type: String, trim: true },
    refreshTokenHash: { type: String, select: false },
    refreshTokenExpiresAt: { type: Date, select: false },
  },
  { timestamps: true }
);

// Hash the password whenever it is new or changed.
adminSchema.pre('save', async function () {
  if (!this.isModified('password')) return;
  const rounds = parseInt(process.env.BCRYPT_ROUNDS || '12', 10);
  this.password = await bcrypt.hash(this.password, rounds);
});

// The only fields we ever send to the client.
adminSchema.methods.toSafeJSON = function () {
  return {
    id: this._id,
    name: this.name,
    email: this.email,
    phoneNumber: this.phoneNumber,
    designation: this.designation,
  };
};

module.exports = mongoose.model('Admin', adminSchema);

const crypto = require('crypto');
const jwt = require('jsonwebtoken');

const REFRESH_COOKIE = 'refreshToken';
const refreshDays = parseInt(process.env.REFRESH_TOKEN_DAYS || '7', 10);
const refreshMs = refreshDays * 24 * 60 * 60 * 1000;

// Short-lived JWT. "sub" (subject) is the standard claim for the user id.
function signAccessToken(admin) {
  return jwt.sign({ sub: admin._id.toString(), role: 'admin' }, process.env.JWT_SECRET_KEY, {
    algorithm: 'HS256',
    expiresIn: process.env.JWT_EXPIRES || '15m',
  });
}

// Refresh tokens are random bytes, not JWTs: they only need to be unguessable.
const createRefreshToken = () => crypto.randomBytes(48).toString('hex');

// Store only a hash, so a database leak does not expose working tokens.
const hashToken = (token) => crypto.createHash('sha256').update(token).digest('hex');

const refreshExpiry = () => new Date(Date.now() + refreshMs);

function setRefreshCookie(res, token) {
  res.cookie(REFRESH_COOKIE, token, {
    httpOnly: true, // JavaScript in the browser cannot read it
    secure: process.env.NODE_ENV === 'production', // HTTPS only in production
    sameSite: 'strict', // not sent on requests from other sites
    path: '/api/admin', // only sent to the auth routes
    maxAge: refreshMs,
  });
}

const clearRefreshCookie = (res) => res.clearCookie(REFRESH_COOKIE, { path: '/api/admin' });

module.exports = {
  REFRESH_COOKIE,
  signAccessToken,
  createRefreshToken,
  hashToken,
  refreshExpiry,
  setRefreshCookie,
  clearRefreshCookie,
};

const bcrypt = require('bcrypt');
const Admin = require('../models/Admin');
const t = require('../utils/tokens');

// A real hash to compare against when the account does not exist, so a
// failed lookup takes about as long as a wrong password.
const DUMMY_HASH = bcrypt.hashSync('dummy-password-for-timing', 12);
const INVALID = { message: 'Invalid credentials' };

function validatePassword(password) {
  if (typeof password !== 'string') return 'Password is required';
  if (password.length < 15) return 'Password must be at least 15 characters';
  if (Buffer.byteLength(password, 'utf8') > 72) return 'Password is too long';
  return null;
}

// Create a new session: store a fresh refresh token hash and set the cookie.
async function issueSession(res, admin) {
  const refresh = t.createRefreshToken();
  admin.refreshTokenHash = t.hashToken(refresh);
  admin.refreshTokenExpiresAt = t.refreshExpiry();
  await admin.save();
  t.setRefreshCookie(res, refresh);
  return t.signAccessToken(admin);
}

// POST /api/admin  (protected: only an existing admin can call this)
exports.createAdmin = async (req, res) => {
  const { name, email, phoneNumber, password, designation } = req.body ?? {};
  if (!name || !email) {
    return res.status(400).json({ message: 'name and email are required' });
  }
  const passwordError = validatePassword(password);
  if (passwordError) return res.status(400).json({ message: passwordError });

  // Only check the phone number if one was given.
  const conflicts = [{ email: email.toLowerCase() }];
  if (phoneNumber) conflicts.push({ phoneNumber });
  if (await Admin.exists({ $or: conflicts })) {
    return res.status(409).json({ message: 'An admin with that email or phone already exists' });
  }

  const admin = await Admin.create({ name, email, phoneNumber, password, designation });
  res.status(201).json({ admin: admin.toSafeJSON() });
};

// POST /api/admin/login
exports.login = async (req, res) => {
  const { identifier, password } = req.body ?? {};
  if (typeof identifier !== 'string' || typeof password !== 'string') {
    return res.status(400).json({ message: 'identifier and password are required' });
  }

  const query = identifier.includes('@')
    ? { email: identifier.toLowerCase().trim() }
    : { phoneNumber: identifier.trim() };
  const admin = await Admin.findOne(query).select('+password');

  // Same message, status and timing whether the account exists or not.
  const ok = await bcrypt.compare(password, admin ? admin.password : DUMMY_HASH);
  if (!admin || !ok) return res.status(401).json(INVALID);

  const accessToken = await issueSession(res, admin);
  res.json({ admin: admin.toSafeJSON(), accessToken });
};

// POST /api/admin/refresh
exports.refresh = async (req, res) => {
  const incoming = req.cookies[t.REFRESH_COOKIE];
  if (!incoming) return res.status(401).json({ message: 'Not authenticated' });

  const admin = await Admin.findOne({ refreshTokenHash: t.hashToken(incoming) })
    .select('+refreshTokenHash +refreshTokenExpiresAt');

  if (!admin || admin.refreshTokenExpiresAt < new Date()) {
    t.clearRefreshCookie(res);
    return res.status(401).json({ message: 'Session expired' });
  }

  // Rotation: replace the token, so the one just used can never work again.
  const accessToken = await issueSession(res, admin);
  res.json({ accessToken });
};

// POST /api/admin/logout
exports.logout = async (req, res) => {
  const incoming = req.cookies[t.REFRESH_COOKIE];
  if (incoming) {
    await Admin.updateOne(
      { refreshTokenHash: t.hashToken(incoming) },
      { $unset: { refreshTokenHash: '', refreshTokenExpiresAt: '' } }
    );
  }
  t.clearRefreshCookie(res);
  res.status(204).end();
};

// GET /api/admin/me
exports.me = async (req, res) => {
  const admin = await Admin.findById(req.admin.id);
  if (!admin) return res.status(401).json({ message: 'Not authenticated' });
  res.json({ admin: admin.toSafeJSON() });
};

const jwt = require('jsonwebtoken');

module.exports = function adminAuth(req, res, next) {
  const [scheme, token] = (req.headers.authorization || '').split(' ');
  if (scheme !== 'Bearer' || !token) {
    return res.status(401).json({ message: 'Not authenticated' });
  }

  try {
    // Pin the algorithm so a token signed any other way is rejected.
    const payload = jwt.verify(token, process.env.JWT_SECRET_KEY, { algorithms: ['HS256'] });
    if (payload.role !== 'admin') {
      return res.status(403).json({ message: 'Admins only' });
    }
    req.admin = { id: payload.sub };
    next();
  } catch {
    // Expired, tampered with, or signed with another key.
    return res.status(401).json({ message: 'Invalid or expired token' });
  }
};

const express = require('express');
const { rateLimit } = require('express-rate-limit');
const adminAuth = require('../middleware/adminAuth');
const c = require('../controllers/adminController');

const router = express.Router();

// At most 10 attempts per 15 minutes per IP address.
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  limit: 10,
  standardHeaders: 'draft-8',
  legacyHeaders: false,
  message: { message: 'Too many attempts, please try again later' },
});

router.post('/login', authLimiter, c.login);
router.post('/refresh', authLimiter, c.refresh);
router.post('/logout', c.logout);

router.get('/me', adminAuth, c.me);
router.post('/', adminAuth, c.createAdmin);

module.exports = router;

const express = require('express');
const mongoose = require('mongoose');
const helmet = require('helmet');
const cookieParser = require('cookie-parser');

const app = express();

// Only if you deploy behind a proxy or load balancer (most hosts do),
// so rate limiting sees the visitor's real IP address.
if (process.env.NODE_ENV === 'production') app.set('trust proxy', 1);

app.use(helmet());
app.use(express.json({ limit: '10kb' }));
app.use(cookieParser());

app.use('/api/admin', require('./routes/admin'));

// Error handler: has four arguments. Log the details, send a generic message.
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ message: 'Something went wrong' });
});

async function start() {
  await mongoose.connect(process.env.MONGO_URI);
  app.listen(process.env.PORT, () => {
    console.log(`Server running on http://localhost:${process.env.PORT}`);
  });
}

start();

npm run dev

const mongoose = require('mongoose');
const Admin = require('../models/Admin');

async function main() {
  const [name, email, password] = process.argv.slice(2);
  if (!name || !email || !password || password.length < 15 || Buffer.byteLength(password) > 72) {
    console.error('Usage: npm run create-admin -- "<name>" <email> "<password, 15+ characters>"');
    process.exit(1);
  }

  await mongoose.connect(process.env.MONGO_URI);
  await Admin.create({ name, email, password });
  console.log('Admin created:', email);
  await mongoose.disconnect();
}

main();

npm run create-admin -- "Jane Doe" jane@example.com "correct horse battery staple"

{ "identifier": "jane@example.com", "password": "correct horse battery staple" }

let accessToken = null;
let refreshing = null;

export function setAccessToken(token) {
  accessToken = token;
}

// Share one refresh between parallel requests: with rotation, two refreshes
// at once would make the second one fail and log the admin out.
function refreshAccessToken() {
  refreshing ??= fetch('/api/admin/refresh', { method: 'POST', credentials: 'include' })
    .then(async (res) => {
      accessToken = res.ok ? (await res.json()).accessToken : null;
      return res.ok;
    })
    .finally(() => {
      refreshing = null;
    });
  return refreshing;
}

export async function api(path, options = {}) {
  const send = () =>
    fetch(path, {
      ...options,
      credentials: 'include',
      headers: {
        'Content-Type': 'application/json',
        ...options.headers,
        ...(accessToken && { Authorization: `Bearer ${accessToken}` }),
      },
    });

  let res = await send();
  if (res.status === 401 && (await refreshAccessToken())) {
    res = await send();
  }
  return res;
}

admin-auth/
├── controllers/
│   └── adminController.js
├── middleware/
│   └── adminAuth.js
├── models/
│   └── Admin.js
├── routes/
│   └── admin.js
├── scripts/
│   └── createAdmin.js
├── utils/
│   └── tokens.js
├── .env               # secrets (do not commit)
├── .gitignore
├── package.json
└── server.js