Module P-2·25 min read

JWT structure, signing and verification, refresh token rotation, bcrypt cost factors, Express auth middleware, session vs stateless — and OAuth 2.0 social login.

Module P-2 — Authentication and Authorization

Q: When implementing refresh token rotation, what happens when a user attempts to use a refresh token that has already been used?

The operation fails, potentially indicating token theft, and the legitimate user will also need to re-authenticate. — Refresh token rotation issues a new refresh token each time one is used. If a previously used refresh token is presented again, it suggests that the token was either stolen or compromised. A secure system detects this reuse and denies the request, effectively forcing re-authentication.

Q: In an Express application, where should the "Ownership check" logic (e.g., verifying a user can only edit their own post) typically reside?

In the Service layer — Role-Based Access Control (RBAC) middleware checks global roles, but ownership logic (checking if a specific resource belongs to a specific user) requires business context and database access. Therefore, it belongs in the Service layer, not in generalized middleware or routing files.

Q: Which scenario strongly favors using stateful Session-based Authentication over stateless JWTs?

A monolith application requiring instant, reliable token revocation across all devices. — Stateless JWTs are difficult to revoke before their expiration time because they are validated mathematically by any server holding the secret. Sessions, however, are checked against a central store (like Redis) on every request, making them ideal when instant invalidation (like "log out all devices") is a hard requirement.

What this module covers: Authentication answers "who are you?" Authorization answers "what are you allowed to do?" These are two distinct concerns that most tutorials conflate. This module covers the complete production authentication stack: bcrypt for password hashing, JWT for stateless tokens, refresh token rotation for long-lived sessions, Express middleware for protecting routes, and role-based access control. By the end you will have a working auth system you can drop into any Node.js API.

Authentication vs Authorization

Before writing any code, get the terminology straight — confusing these two causes real security bugs:

Authentication — verifying identity. "Is this really Jatin?" Handled by login, tokens, sessions.
Authorization — verifying permission. "Is Jatin allowed to delete this post?" Handled by role checks, ownership checks, policies.

A user can be fully authenticated (we know who they are) and still be unauthorized (they don't have permission for this specific action). Both checks are needed, and they run in that order.

Passwords: Never Store Plaintext

If your database is ever breached, plaintext passwords give attackers instant access to every account — and to every other site where users reused that password. Always hash passwords with a slow, purpose-built algorithm.

bcrypt is the standard. It uses a configurable "cost factor" (work factor) that controls how long hashing takes. The higher the cost, the more computation an attacker needs to brute-force the hash.

bash

npm install bcrypt
npm install -D @types/bcrypt

javascript

import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12; // cost factor — each +1 doubles the time

// Hashing on registration
async function hashPassword(plaintext) {
  return bcrypt.hash(plaintext, SALT_ROUNDS);
}

// Verifying on login
async function verifyPassword(plaintext, hash) {
  return bcrypt.compare(plaintext, hash);  // returns true or false
}

// Usage
const hash = await hashPassword('mySecret123');
// → '$2b$12$eGqTPh7MqaXBCFk6GCTxfe7Gy3bnLKfVUOmV...' (60 char string)

const isValid = await verifyPassword('mySecret123', hash); // true
const isWrong = await verifyPassword('wrongPassword', hash); // false

Cost factor guidelines:

Environment	Recommended cost	Approx. time per hash
Development	10	~65ms
Production	12	~250ms
High-security	14	~1 second

At cost 12, a user waits ~250ms on login — imperceptible. An attacker trying to brute-force a leaked database hash faces 250ms per attempt. At scale, that's the difference between cracking a password in hours vs years.

Timing-safe comparison: bcrypt.compare is timing-safe — it takes the same amount of time regardless of whether the password is correct or not. This prevents timing attacks that infer the correct password by measuring response time differences.

JSON Web Tokens (JWT)

After a user authenticates, you need a way to identify them on subsequent requests without asking for their password again. JWT is the most common stateless solution.

bash

npm install jsonwebtoken
npm install -D @types/jsonwebtoken

JWT Structure

A JWT is a Base64-encoded string with three parts separated by dots: header.payload.signature

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzE2MjkwMDAwLCJleHAiOjE3MTYyOTM2MDB9.abc123...

Header — algorithm used (HS256, RS256)
Payload — claims: sub (subject/userId), role, iat (issued at), exp (expiry)
Signature — HMAC of header+payload using your secret key

The payload is Base64-encoded, not encrypted — anyone can decode and read it. Never put sensitive data (passwords, PII) in the payload. The signature guarantees it has not been tampered with.

Signing and verifying tokens

javascript

import jwt from 'jsonwebtoken';

const ACCESS_SECRET = process.env.JWT_ACCESS_SECRET;   // min 32 random chars
const REFRESH_SECRET = process.env.JWT_REFRESH_SECRET; // different secret

// Sign an access token — short-lived
export function signAccessToken(userId, role) {
  return jwt.sign(
    { sub: userId, role },
    ACCESS_SECRET,
    { expiresIn: '15m' }  // 15 minutes
  );
}

// Sign a refresh token — long-lived
export function signRefreshToken(userId) {
  return jwt.sign(
    { sub: userId },
    REFRESH_SECRET,
    { expiresIn: '7d' }   // 7 days
  );
}

// Verify a token — throws if invalid or expired
export function verifyAccessToken(token) {
  return jwt.verify(token, ACCESS_SECRET);
  // Returns decoded payload, e.g. { sub: 42, role: 'admin', iat: ..., exp: ... }
  // Throws JsonWebTokenError if invalid
  // Throws TokenExpiredError if expired
}

bash

# .env
JWT_ACCESS_SECRET=your-very-long-random-string-at-least-32-characters
JWT_REFRESH_SECRET=another-completely-different-random-string

Generate secure secrets:

bash

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

Why Two Tokens?

A single long-lived token is a security liability — if stolen, the attacker has access for days or weeks. The two-token pattern mitigates this:

Access token — short-lived (15 min). Sent with every API request. Verified entirely from the signature — no database lookup needed. If stolen, expires quickly.
Refresh token — long-lived (7 days). Stored securely. Used only to get a new access token when the old one expires. Can be invalidated by deleting it from the database.

text

Client                    API Server
  │                            │
  │──── POST /auth/login ──────►│
  │◄─── { accessToken, refreshToken } ─│
  │                            │
  │──── GET /posts (Authorization: Bearer <accessToken>) ──►│
  │◄─── 200 posts ─────────────│
  │                            │
  │   (15 minutes later, accessToken expires)
  │                            │
  │──── POST /auth/refresh (refreshToken in body/cookie) ──►│
  │◄─── { newAccessToken } ────│

The Complete Auth Flow

User registration

javascript

// src/services/auth.service.js
import bcrypt from 'bcrypt';
import { signAccessToken, signRefreshToken } from '../utils/jwt.js';
import * as usersRepo from '../repositories/users.repository.js';
import * as tokensRepo from '../repositories/tokens.repository.js';
import { AppError } from '../errors/AppError.js';

const SALT_ROUNDS = 12;

export async function register({ name, email, password }) {
  // Check for existing user
  const existing = await usersRepo.findByEmail(email);
  if (existing) throw new AppError('Email already registered', 409);

  // Hash the password
  const passwordHash = await bcrypt.hash(password, SALT_ROUNDS);

  // Create the user
  const user = await usersRepo.create({ name, email, passwordHash });

  // Issue tokens
  const accessToken = signAccessToken(user.id, user.role);
  const refreshToken = signRefreshToken(user.id);

  // Store refresh token (so we can invalidate it later)
  await tokensRepo.create({ userId: user.id, token: refreshToken });

  return { user: { id: user.id, name: user.name, email: user.email }, accessToken, refreshToken };
}

javascript

export async function login({ email, password }) {
  // Find the user
  const user = await usersRepo.findByEmail(email);
  if (!user) throw new AppError('Invalid email or password', 401);
  // Note: same error for "user not found" and "wrong password"
  // Never tell attackers which one it is

  // Verify password
  const isValid = await bcrypt.compare(password, user.passwordHash);
  if (!isValid) throw new AppError('Invalid email or password', 401);

  // Issue new tokens
  const accessToken = signAccessToken(user.id, user.role);
  const refreshToken = signRefreshToken(user.id);

  await tokensRepo.create({ userId: user.id, token: refreshToken });

  return { user: { id: user.id, name: user.name, email: user.email }, accessToken, refreshToken };
}

Token refresh

javascript

export async function refresh(incomingRefreshToken) {
  // Verify the refresh token is valid and not expired
  let payload;
  try {
    payload = jwt.verify(incomingRefreshToken, process.env.JWT_REFRESH_SECRET);
  } catch {
    throw new AppError('Invalid or expired refresh token', 401);
  }

  // Check it exists in the database (not been revoked)
  const stored = await tokensRepo.findByToken(incomingRefreshToken);
  if (!stored) throw new AppError('Refresh token revoked', 401);

  // Rotation: delete old token, issue new pair
  await tokensRepo.deleteByToken(incomingRefreshToken);

  const user = await usersRepo.findById(payload.sub);
  const newAccessToken = signAccessToken(user.id, user.role);
  const newRefreshToken = signRefreshToken(user.id);

  await tokensRepo.create({ userId: user.id, token: newRefreshToken });

  return { accessToken: newAccessToken, refreshToken: newRefreshToken };
}

Refresh token rotation: every time a refresh token is used, it is deleted and a new one is issued. If a stolen refresh token is used, the legitimate user's next refresh will fail (their token was also invalidated). This is how you detect token theft.

Logout

javascript

export async function logout(refreshToken) {
  await tokensRepo.deleteByToken(refreshToken);
  // Access tokens cannot be invalidated (they're stateless)
  // They expire on their own after 15 minutes
}

The Authentication Middleware

This middleware extracts the JWT from the Authorization header, verifies it, and attaches the decoded user to req.user.

javascript

// src/middleware/auth.js
import { verifyAccessToken } from '../utils/jwt.js';
import { UnauthorizedError } from '../errors/AppError.js';

export function authenticate(req, res, next) {
  const authHeader = req.headers['authorization'];

  // Expect: "Authorization: Bearer <token>"
  if (!authHeader?.startsWith('Bearer ')) {
    return next(new UnauthorizedError('Authorization header required'));
  }

  const token = authHeader.slice(7); // remove "Bearer "

  try {
    const payload = verifyAccessToken(token);
    req.user = { id: payload.sub, role: payload.role };
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return next(new UnauthorizedError('Token expired'));
    }
    return next(new UnauthorizedError('Invalid token'));
  }
}

Usage in routes:

javascript

// Protected route — must be logged in
router.get('/profile', authenticate, usersController.getProfile);

// Public route — no authenticate middleware
router.post('/register', authController.register);
router.post('/login', authController.login);

Authorization: Role-Based Access Control

Authentication confirms identity. Authorization enforces what they can do. The most common approach is role-based access control (RBAC) — users have a role, roles have permissions.

javascript

// src/middleware/authorize.js

// Middleware factory: authorize(allowedRoles)
export function authorize(...allowedRoles) {
  return (req, res, next) => {
    // authenticate must run before authorize
    if (!req.user) {
      return next(new UnauthorizedError());
    }

    if (!allowedRoles.includes(req.user.role)) {
      return next(new ForbiddenError('Insufficient permissions'));
    }

    next();
  };
}

javascript

// src/routes/admin.routes.js
import { authenticate } from '../middleware/auth.js';
import { authorize } from '../middleware/authorize.js';

// Only admins
router.get('/stats', authenticate, authorize('admin'), adminController.getStats);

// Admins and moderators
router.delete('/posts/:id', authenticate, authorize('admin', 'moderator'), postsController.forceDelete);

// Any authenticated user
router.get('/feed', authenticate, postsController.getFeed);

Ownership checks

RBAC is not enough for "users can only edit their own posts". That requires an ownership check in the service:

javascript

// src/services/posts.service.js
export async function updatePost(postId, updates, requestingUserId) {
  const post = await postsRepo.findById(postId);
  if (!post) throw new NotFoundError('Post');

  // Ownership check — user can only edit their own posts
  if (post.authorId !== requestingUserId) {
    throw new ForbiddenError('You can only edit your own posts');
  }

  return postsRepo.update(postId, updates);
}

javascript

// src/controllers/posts.controller.js
export async function updatePost(req, res, next) {
  try {
    const post = await postsService.updatePost(
      parseInt(req.params.id),
      req.body,
      req.user.id,   // from authenticate middleware
    );
    res.json(post);
  } catch (err) {
    next(err);
  }
}

Ownership logic lives in the service, not the route or middleware. It has access to the full business context.

Auth Routes

javascript

// src/routes/auth.routes.js
import { Router } from 'express';
import * as authController from '../controllers/auth.controller.js';
import { authenticate } from '../middleware/auth.js';

const router = Router();

router.post('/register', authController.register);
router.post('/login', authController.login);
router.post('/refresh', authController.refresh);
router.post('/logout', authenticate, authController.logout);

export default router;

javascript

// src/controllers/auth.controller.js
import * as authService from '../services/auth.service.js';

export async function register(req, res, next) {
  try {
    const result = await authService.register(req.body);
    res.status(201).json(result);
  } catch (err) {
    next(err);
  }
}

export async function login(req, res, next) {
  try {
    const result = await authService.login(req.body);
    res.json(result);
  } catch (err) {
    next(err);
  }
}

export async function refresh(req, res, next) {
  try {
    const { refreshToken } = req.body;
    if (!refreshToken) return res.status(400).json({ error: 'refreshToken required' });
    const tokens = await authService.refresh(refreshToken);
    res.json(tokens);
  } catch (err) {
    next(err);
  }
}

export async function logout(req, res, next) {
  try {
    const { refreshToken } = req.body;
    if (refreshToken) await authService.logout(refreshToken);
    res.status(204).send();
  } catch (err) {
    next(err);
  }
}

Session-Based Auth vs Stateless JWT

You will encounter both in production. Choosing correctly matters:

	JWT (stateless)	Sessions (stateful)
Server state	None — self-contained token	Session store (Redis/DB)
Revocation	Hard — token valid until expiry	Instant — delete session
Horizontal scaling	Trivial — any server can verify	Needs shared session store
Token theft response	Wait for expiry	Delete session immediately
Complexity	Refresh token rotation required	Simpler — one session ID

Use JWT when: you have multiple services, horizontal scaling, or mobile clients. The statelessness simplifies architecture.

Use sessions when: you need instant revocation (e.g. "log out all devices"), you have a monolith, or your team is more familiar with sessions. Express + express-session + Redis is the standard stack.

For most modern APIs (especially mobile or multi-service), JWT with refresh token rotation is the right choice.

Security Checklist

Before shipping auth:

Passwords hashed with bcrypt, cost factor ≥ 12
JWT secrets are long (≥ 32 bytes), random, and different for access vs refresh
Access tokens expire in ≤ 15 minutes
Refresh tokens are stored in the database and rotated on use
Login returns the same error for "wrong email" and "wrong password" (prevents user enumeration)
Rate limiting on /auth/login and /auth/register (covered in P-6)
HTTPS enforced in production — tokens in plaintext over HTTP are useless
Refresh tokens sent in HttpOnly cookies rather than response body (prevents XSS theft)
Authorization header checked with startsWith('Bearer '), not split/regex

Summary

Passwords: always bcrypt with cost ≥ 12. Never MD5, SHA1, or plaintext. bcrypt.compare is timing-safe.
JWT: header.payload.signature. Payload is readable — never put secrets in it. Signature prevents tampering.
Two-token pattern: short-lived access tokens (15 min, stateless), long-lived refresh tokens (7 days, stored in DB). Rotation on use detects theft.
authenticate middleware extracts the Bearer token, verifies it, attaches req.user. Run it on every protected route.
Authorization: authorize('admin') middleware for role checks. Ownership checks belong in the service layer.
Same error message for "user not found" and "wrong password" — never reveal which one failed.
JWT vs sessions: JWT for multi-service/mobile, sessions for instant revocation in monoliths.

Next: TypeScript in Node.js — adding type safety to everything you have built so far.

Knowledge Check

When implementing refresh token rotation, what happens when a user attempts to use a refresh token that has already been used?

In an Express application, where should the "Ownership check" logic (e.g., verifying a user can only edit their own post) typically reside?

Which scenario strongly favors using stateful Session-based Authentication over stateless JWTs?

Test your knowledge with more question sets

PreviousModule P-1: Application Architecture and Project Structure Next Module P-3: TypeScript in Node.js

Discussion

Join the discussion

Loading comments...

Module P-2 — Authentication and Authorization

Authentication vs Authorization

Passwords: Never Store Plaintext

JSON Web Tokens (JWT)

JWT Structure

Signing and verifying tokens

Why Two Tokens?

The Complete Auth Flow

User registration

User login

Token refresh

Logout

The Authentication Middleware

Authorization: Role-Based Access Control

Ownership checks

Auth Routes

Session-Based Auth vs Stateless JWT

Security Checklist

Summary

Test your knowledge with more question sets

Discussion