Javascript Genesis: 100 Chapters

Overview

JWT Authentication Middleware enforces access control by validating a Bearer token on protected routes, attaching the decoded claims to the request context, and optionally refreshing tokens via hooks. Use it when you need consistent authorization behavior across an Express (or Connect-compatible) API and want secure header handling.

Quick Reference

Parameters

Code Example

import express from "express";
import jwt from "jsonwebtoken";

function jwtAuthMiddleware({
  verify,
  refresh = { enabled: false },
  headers = {},
  attachClaimsTo = "auth",
  errorResponses = {},
} = {}) {
  const scheme = headers.authorizationScheme ?? "Bearer";
  const headerName = headers.authorizationHeader ?? "authorization";

  return async function jwtAuth(req, res, next) {
    const authHeader = req.headers[headerName];
    if (!authHeader || typeof authHeader !== "string") {
      return res.status(401).json(errorResponses.unauthorizedBody ?? { error: "missing_authorization" });
    }

    const [tokenScheme, token] = authHeader.split(" ");
    if (tokenScheme !== scheme || !token) {
      return res.status(401).json(errorResponses.unauthorizedBody ?? { error: "invalid_authorization_format" });
    }

    const options = {
      algorithms: verify.algorithms,
      issuer: verify.issuer,
      audience: verify.audience,
      clockTolerance: (verify.clockToleranceSeconds ?? 0),
    };

    try {
      const decoded = jwt.verify(token, verify.secretOrPublicKey, options); // throws on invalid/expired tokens
      req[attachClaimsTo] = { claims: decoded, token, exp: decoded.exp, iat: decoded.iat };
      return next();
    } catch (err) {
      // Token expired: optionally refresh via hook
      if (refresh.enabled && err && err.name === "TokenExpiredError" && typeof refresh.onRefresh === "function") {
        const result = await refresh.onRefresh({ expiredToken: token, req });
        if (!result?.accessToken) {
          return res.status(401).json(errorResponses.unauthorizedBody ?? { error: "refresh_failed" });
        }

        // Verify refreshed token before attaching claims
        const decoded = jwt.verify(result.accessToken, verify.secretOrPublicKey, options);
        req[attachClaimsTo] = { claims: decoded, token: result.accessToken, exp: decoded.exp, iat: decoded.iat };

        // Optional: expose refreshed access token to the client
        res.setHeader("X-Access-Token", result.accessToken);
        return next();
      }

      // Non-refreshable auth failures
      return res.status(401).json(errorResponses.unauthorizedBody ?? { error: "invalid_token" });
    }
  };
}

// Example usage
const app = express();
...