JWT Node.js — Why alg:none Still Bypasses Verification

Session-based authentication used to be the default — store a session ID in a cookie, look it up in a database on every request, and return the user. That works fine for a single server, but the moment you scale horizontally across multiple Node.js instances or split your backend into microservices, you have a problem: which server holds the session? You either need a shared Redis store or sticky sessions, both of which add operational complexity and latency. JWT sidesteps this entirely by making the token itself the source of truth.

A JSON Web Token is a self-contained credential. It carries a payload — user ID, roles, expiry — cryptographically signed by the server. Any service that knows the secret (or the public key) can verify it instantly without a network round-trip. That is not just convenient; it is architecturally significant. It decouples authentication from state, which is exactly what stateless, distributed systems need.

By the end you will be able to build a complete JWT auth system in Node.js from scratch — issuing access tokens, rotating refresh tokens securely, protecting routes with middleware, handling token expiry gracefully, and avoiding the subtle security mistakes that show up in production code reviews. We will also cover algorithm choices, key management, and the honest trade-offs JWTs carry that most tutorials skip.

JWT Signing and Verification — The Algorithm Trap

JWT signing produces a token in three parts: header containing the algorithm and type, payload containing the claims, and a signature computed over the first two parts. The signature is what makes the token tamper-proof — change a single byte in the payload and the signature no longer matches.

When signing with jwt.sign(payload, secret, options), keep the payload minimal: userId, role, and nothing else the downstream service does not immediately need. Set expiresIn — omitting it produces a token that never expires, which is not a feature. Use a secret of at least 32 random characters for HS256; anything shorter is brute-forceable given enough time and a leaked token.

When verifying with jwt.verify(token, secret, options), three options are non-negotiable in production: - algorithms: ['HS256'] — explicit allowlist, never rely on the library default - clockTolerance: 60 — jsonwebtoken has no built-in tolerance; without this, a 2-second NTP drift causes intermittent 401s that are maddening to diagnose - ignoreExpiration: false — this is the default, but it has been overridden in production configs more times than you would expect, usually by someone copying a test helper

Catch TokenExpiredError and JsonWebTokenError separately. Return 401 for an expired token — the client should attempt a refresh. Return 403 for an invalid signature — that is not a retry situation, it is a rejection.

The algorithm confusion attack deserves a clear explanation because it is subtle. When you use RS256, your auth service signs with a private key and distributes the public key so other services can verify tokens. The public key is, by definition, not secret. An attacker who knows your public key can do the following: take a valid token, change the header algorithm from RS256 to HS256, re-sign the entire thing using the public key as the HMAC secret, and submit it. If your verification code trusts the algorithm declared in the header and does not restrict which algorithms it accepts, the server will attempt to verify an HS256 token using the public key as the HMAC secret — which is exactly what the attacker signed it with. Verification passes. The fix is always the same: specify algorithms explicitly in jwt.verify and never let the header dictate the algorithm.

One more thing most tutorials omit: use different secrets for access tokens and refresh tokens. If an attacker recovers your access token secret through a misconfigured environment variable or a memory leak, they should not also be able to forge refresh tokens. Two secrets, two separate environment variables, rotated independently.

const jwt = require('jsonwebtoken');

// Production-grade JWT verification middleware for Express
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN

  if (!token) {
    return res.status(401).json({ error: 'Access token required' });
  }

  // Explicitly specify allowed algorithms — never accept 'none'
  // clockTolerance handles NTP drift between issuing and validating services
  // jsonwebtoken has no built-in tolerance; without this, 2-second drift = intermittent 401s
  jwt.verify(
    token,
    process.env.JWT_SECRET,
    {
      algorithms: ['HS256'],       // allowlist — rejects alg:none and RS256 confusion attacks
      clockTolerance: 60,          // 60 seconds leeway for server clock drift
      ignoreExpiration: false      // default, but be explicit — test helpers override this
    },
    (err, decoded) => {
      if (err) {
        if (err.name === 'TokenExpiredError') {
          // Client should attempt refresh — not a hard rejection
          return res.status(401).json({
            error: 'Token expired',
            code: 'TOKEN_EXPIRED'
          });
        }
        if (err.name === 'JsonWebTokenError') {
          // Invalid signature or malformed token — do not retry
          return res.status(403).json({
            error: 'Invalid token',
            code: 'INVALID_TOKEN'
          });
        }
        return res.status(403).json({ error: err.message });
      }

      req.user = decoded;
      next();
    }
  );
}

// Issuing access and refresh tokens
// Two separate secrets — access token compromise does not leak refresh signing capability
function generateTokens(userId, role) {
  const accessToken = jwt.sign(
    { userId, role },
    process.env.JWT_SECRET,           // access token secret
    { expiresIn: '15m', algorithm: 'HS256' }
  );

  // Refresh token — long-lived, stored hashed in database or Redis
  const refreshToken = jwt.sign(
    { userId, type: 'refresh' },
    process.env.JWT_REFRESH_SECRET,   // different secret — rotate independently
    { expiresIn: '7d', algorithm: 'HS256' }
  );

  return { accessToken, refreshToken };
}

Refresh Token Rotation — The Only Safe Way to Do Long-Lived Sessions

If you issue refresh tokens and never revoke them, they are permanent passwords. An attacker who intercepts one — via XSS, a compromised device, or a network log — can generate new access tokens for the full 7-day lifetime of the refresh token without ever re-authenticating. Refresh token rotation closes that window.

The principle is simple: each refresh request consumes the old token and produces a new one. The old token is deleted from the server-side store the moment it is used. If that same old token ever appears again, you know it was used by two parties — the legitimate user and someone who stole it. At that point you revoke everything for that user and force re-authentication.

The standard rotation flow: 1. Validate the incoming refresh token signature and expiry with jwt.verify. 2. Hash the raw token with SHA-256 and look it up in your store. If the hash is not there, the token was already rotated — trigger full revocation for that user. 3. Delete the old token hash from the store. This is the step most implementations skip, which means they are issuing new tokens without actually revoking old ones. 4. Generate a new access token and a new refresh token. 5. Hash the new refresh token and store it with a TTL matching the token's expiry. 6. Return the new pair to the client.

Why store a hash rather than the raw token? If your Redis instance or database is compromised, the attacker gets a list of hashes — not usable tokens. SHA-256 the token before storing it. The raw token only ever lives in memory during the rotation request and in the client's secure storage.

The TTL on stored hashes matters more than most people realise. If you store refresh token hashes without a TTL, every logout, every rotation, every expired token accumulates in your store forever. I have seen teams bring Redis to its knees with millions of orphaned token hashes that never expired. Match the hash TTL to the token expiry — 7 days for a 7-day refresh token. Redis will clean it up automatically.

One timing nuance worth understanding: if an attacker steals a refresh token at T=0, and the legitimate user refreshes at T=5 minutes, the attacker's copy becomes invalid at T=5. If the attacker tries to use the stolen token at T=3 — before the user refreshes — the attacker succeeds and the user's next refresh at T=5 will fail, triggering revocation. The theft window is between T=0 and whenever the legitimate user next refreshes. Short access token expiry (15 minutes) limits the damage during that window.

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

// In production: Redis with SETEX or a database table with expiry column
// This Map is illustrative — do not use in production
const refreshTokenStore = new Map(); // tokenHash -> { userId, expiresAt }

async function rotateRefreshToken(oldRefreshToken, userId) {
  // 1. Validate signature and expiry first
  let decoded;
  try {
    decoded = jwt.verify(oldRefreshToken, process.env.JWT_REFRESH_SECRET, {
      algorithms: ['HS256']
    });
    if (decoded.userId !== userId) {
      // Token is valid but belongs to a different user — reject hard
      throw new Error('Token userId mismatch');
    }
  } catch (err) {
    return { error: 'Invalid refresh token' };
  }

  // 2. Hash the raw token for store lookup — never store raw tokens
  const tokenHash = crypto
    .createHash('sha256')
    .update(oldRefreshToken)
    .digest('hex');

  const storedToken = await getRefreshTokenFromStore(tokenHash);
  if (!storedToken) {
    // Hash not found — token already rotated or revoked
    // This is the theft detection signal: two parties used the same token
    await revokeAllUserTokens(userId);
    return { error: 'Refresh token already used — session revoked', revokeAll: true };
  }

  // 3. Delete old token hash — one-time use, non-negotiable
  await deleteRefreshTokenFromStore(tokenHash);

  // 4. Generate new token pair
  const newAccessToken = jwt.sign(
    { userId, role: decoded.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m', algorithm: 'HS256' }
  );

  const newRefreshToken = jwt.sign(
    { userId, type: 'refresh' },
    process.env.JWT_REFRESH_SECRET,
    { expiresIn: '7d', algorithm: 'HS256' }
  );

  // 5. Store new hash — TTL must match token expiry or store grows unboundedly
  const newTokenHash = crypto
    .createHash('sha256')
    .update(newRefreshToken)
    .digest('hex');

  const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
  await storeRefreshToken(newTokenHash, userId, Date.now() + sevenDaysMs);

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

// Called when theft is detected (rotated token reused) or on password change
async function revokeAllUserTokens(userId) {
  // Remove all refresh tokens for this user from the store
  await db.refreshTokens.deleteMany({ userId });

  // Add userId to access token denylist for the remaining access token lifetime
  // TTL = 15 minutes (access token expiry) — Redis cleans this up automatically
  await redis.setex(`revoked_user:${userId}`, 15 * 60, 'true');
}

Secure Token Storage: Cookies vs localStorage — The XSS Trade-off

Where you store JWTs on the client determines your exposure profile. The decision is not a matter of preference — it has concrete security consequences that show up in penetration test reports and breach post-mortems.

localStorage is the path of least resistance. It is synchronous, simple to use, and works the same way everywhere. It is also readable by any JavaScript running on the page — your own code, third-party analytics scripts, chat widgets, A/B testing libraries, and anything injected via XSS. If an attacker finds an XSS vector in your application, they can exfiltrate every token from every active session in a single script tag. The token works from any machine until it expires. You will not know it happened until users start reporting unexpected account activity.

This is not theoretical. A startup I know of stored JWTs in localStorage. They integrated a third-party analytics script. That vendor's CDN was compromised. The injected script read tokens from localStorage across thousands of active sessions and replicated them to an attacker-controlled endpoint. The tokens were valid for 24 hours. By the time the breach was detected, the window was closed but the damage was done. Switching to HttpOnly cookies was a two-day rework that should have been the default from day one.

HttpOnly cookies cannot be read by JavaScript — the browser enforces this at the kernel level. XSS cannot exfiltrate what JavaScript cannot access. The trade-off is CSRF: cookies are sent automatically with every request to the matching domain, so a malicious site can trick the user's browser into making authenticated requests. Set SameSite=Strict to block cross-origin cookie submission entirely. This solves CSRF without needing separate anti-CSRF tokens for most use cases.

The SameSite=Strict limitation: if your API and frontend run on different origins — api.example.com and app.example.com — SameSite=Strict blocks the cookie. Use SameSite=Lax for navigation requests or SameSite=None; Secure for cross-origin API calls, paired with explicit CSRF token validation.

For single-page applications, the recommended pattern in 2026 is the Backend for Frontend (BFF). The SPA never handles the token directly. The BFF — a thin Node.js service that sits between the SPA and the API — receives the token from the auth service, sets it as an HttpOnly cookie, and proxies API requests. The SPA makes requests to the BFF; the BFF attaches the token from the cookie. The SPA never sees the token, which means XSS in the SPA cannot steal it.

For mobile applications, use platform-native secure storage: iOS Keychain and Android Keystore. Both are hardware-backed on modern devices. Do not store tokens in AsyncStorage or SharedPreferences — those are unencrypted.

const express = require('express');
const jwt = require('jsonwebtoken');
const cookieParser = require('cookie-parser');

const app = express();
app.use(express.json());
app.use(cookieParser());

// Login: issue token as HttpOnly cookie, not in response body
app.post('/api/login', async (req, res) => {
  const { username, password } = req.body;

  const user = await authenticateUser(username, password);
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const accessToken = jwt.sign(
    { userId: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m', algorithm: 'HS256' }
  );

  // HttpOnly: JavaScript cannot read this — XSS cannot steal it
  // Secure: only transmitted over HTTPS
  // SameSite strict: browser will not send this cookie on cross-origin requests — CSRF blocked
  // maxAge matches token expiry — cookie clears itself when token expires
  res.cookie('access_token', accessToken, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production', // enforce HTTPS in production only
    sameSite: 'strict',
    maxAge: 15 * 60 * 1000  // 15 minutes in milliseconds
  });

  // Return user info but never the token itself
  res.json({ message: 'Login successful', userId: user.id });
});

// Middleware: read token from cookie, not Authorization header
function cookieAuthMiddleware(req, res, next) {
  const token = req.cookies.access_token;

  if (!token) {
    return res.status(401).json({ error: 'Not authenticated' });
  }

  jwt.verify(
    token,
    process.env.JWT_SECRET,
    { algorithms: ['HS256'], clockTolerance: 60 },
    (err, decoded) => {
      if (err) {
        if (err.name === 'TokenExpiredError') {
          return res.status(401).json({ error: 'Session expired', code: 'TOKEN_EXPIRED' });
        }
        return res.status(403).json({ error: 'Invalid session' });
      }
      req.user = decoded;
      next();
    }
  );
}

// Logout: clear the cookie server-side
app.post('/api/logout', (req, res) => {
  res.clearCookie('access_token', {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict'
  });
  res.json({ message: 'Logged out' });
});

app.get('/api/protected', cookieAuthMiddleware, (req, res) => {
  res.json({ user: req.user });
});

JWKS Endpoint and Public Key Distribution for RS256

When you move to RS256, you immediately face a distribution problem: every service that validates tokens needs the public key. Hardcoding it into each service is the obvious first move and it works exactly until you need to rotate the key. Then you are coordinating a redeployment across every service simultaneously, hoping nothing drifts out of sync.

JWKS (JSON Web Key Set, RFC 7517) solves this. The auth service publishes its public keys at a standard endpoint — /.well-known/jwks.json — in a standardised format. Validation services fetch that endpoint on startup, cache the response, and use the cached keys for verification. Key rotation becomes: add the new key to the JWKS, wait for all tokens signed with the old key to expire, then remove the old key. No coordinated redeployment. No downtime.

Each key in the JWKS has a kid (key ID) field. The JWT header also carries a kid field identifying which key was used to sign it. During verification, the validator reads the kid from the token header, finds the matching key in the cached JWKS, and verifies the signature. This is how you can have two keys active simultaneously during a rotation — tokens signed with either key are validated correctly.

Implementation steps: 1. Generate an RSA key pair with crypto.generateKeyPairSync (2048-bit minimum; 4096-bit if the tokens are long-lived). 2. Compute the kid as SHA-256 of the public key PEM — this gives you a stable, deterministic identifier. 3. Expose /.well-known/jwks.json returning the public key serialised as a JWK object. 4. Sign tokens with the private key, including the kid in the JWT header. 5. In validation services, fetch the JWKS on startup and cache it in memory. Refresh the cache in the background every hour — not on every request. 6. During verification, decode the token header to extract the kid, look up the matching JWK, convert it to PEM, and verify.

The caching gotcha: if you cache the JWKS with a very long TTL and the auth service rotates keys, validation services will reject new tokens until the cache expires. Short TTL (5-15 minutes) for the cache refresh interval is the right balance — it means at most 15 minutes of lag when a new key is published, without fetching the JWKS on every request.

The missing require gotcha: production JWKS implementations depend on a JWK-to-PEM conversion library. Do not write your own RSA key parser. Use jwks-rsa (for consumers) or node-jose (for both producers and consumers). The code below shows the structural pattern; reference the library for the actual conversion functions.

Never put private keys in the JWKS. This sounds obvious, but misconfigured key serialisation has leaked private keys through JWKS endpoints in real production systems. Audit your endpoint response before deploying.

const crypto = require('crypto');
const express = require('express');
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa'); // npm install jwks-rsa

// --- Auth Service: publish JWKS and sign tokens ---

// Generate RSA key pair — do this once, store keys securely (not in code)
const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
});

// Stable kid: SHA-256 fingerprint of the public key PEM
const kid = crypto.createHash('sha256').update(publicKey).digest('hex');

const authApp = express();

// JWKS endpoint — public keys only, never private
// Validation services fetch and cache this; no auth required on this endpoint
authApp.get('/.well-known/jwks.json', (req, res) => {
  // node-jose or manual JWK construction
  // Shown here as the structure — use a library for real RSA parameter extraction
  const jwk = {
    kty: 'RSA',
    use: 'sig',
    alg: 'RS256',
    kid: kid,
    // n and e are the RSA public key parameters in Base64Url encoding
    // Use node-jose: JWK.asKey(publicKey, 'pem').then(k => k.toJSON())
    n: '<base64url-encoded-modulus>',
    e: 'AQAB'
  };

  res.json({ keys: [jwk] });
});

// Sign tokens with private key — include kid in header
function signJwt(userId, role) {
  return jwt.sign(
    { userId, role },
    privateKey,
    {
      algorithm: 'RS256',
      keyid: kid,         // included in JWT header — validators use this to pick the right key
      expiresIn: '15m'
    }
  );
}

// --- Validation Service: fetch JWKS and verify tokens ---

// jwks-rsa handles caching, rotation, and rate limiting automatically
const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cache: true,
  cacheMaxEntries: 5,
  cacheMaxAge: 10 * 60 * 1000  // 10 minute cache — short enough to pick up rotated keys
});

async function verifyJwt(token) {
  // Decode header first to extract kid — no verification at this stage
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded || !decoded.header.kid) {
    throw new Error('Token missing kid — cannot select verification key');
  }

  // Fetch matching public key from cache (fetches from JWKS endpoint if cache miss)
  const key = await client.getSigningKey(decoded.header.kid);
  const publicKey = key.getPublicKey();

  // Verify with explicit algorithm — never trust the header's algorithm declaration
  return jwt.verify(token, publicKey, { algorithms: ['RS256'] });
}

Blacklisting and Logout — The Stateless Trade-off

JWT's stateless nature is its primary architectural advantage. It is also the thing that makes logout harder than it should be. When a user logs out of a session-based system, you delete the session and the user is instantly deauthenticated. With JWTs, deleting the client-side token is cosmetic — the token itself is still cryptographically valid until its exp claim passes.

For most applications, this is fine. Short-lived access tokens (15 minutes) mean the maximum exposure window after logout is 15 minutes. The user has logged out. Their token will expire. If someone intercepts that token in the 15-minute window, they have a limited window to abuse it. This is an acceptable trade-off for the vast majority of use cases.

For some use cases, it is not acceptable. A user reports a compromised device. A password change triggered by a suspected breach. An administrator locking an account. These all require immediate token invalidation, and short TTLs alone do not provide that.

The denylist pattern handles this. Assign each JWT a jti (JWT ID) claim — a unique identifier generated at sign time. When you need to revoke a token, store the jti in Redis with a TTL equal to the token's remaining lifetime. During verification, after validating the signature and expiry, check whether the jti is in Redis. If it is, reject the request with a 401.

Two things will go wrong if you implement this carelessly. First: if you forget to set a TTL on the Redis key, the denylist grows without bound. Every revoked token adds a key that never expires. I have seen this bring down a Redis instance with 40 million keys that accumulated over six months. Always set the TTL to the remaining seconds until token expiry. Second: the denylist check must happen after signature verification, not before. If you check the denylist first with a jwt.decode (no verification), an attacker can craft a token with a jti that is not on the denylist and bypass it. Verify the signature first. Then check the denylist.

The performance cost of a denylist is real: one Redis round trip per authenticated request, adding 1-3ms. For most applications this is fine. For high-frequency internal service calls, consider whether you actually need instant revocation or whether short TTLs are sufficient. Be deliberate about the trade-off rather than adding the denylist by default.

const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const { createClient } = require('redis');

const redis = createClient({ url: process.env.REDIS_URL });

// Revoke an access token — store jti with TTL = remaining token lifetime
// Only call this after jwt.verify has confirmed the token is valid
async function revokeAccessToken(accessToken) {
  const decoded = jwt.decode(accessToken);
  if (!decoded || !decoded.jti || !decoded.exp) {
    throw new Error('Token missing jti or exp — cannot revoke');
  }

  const remainingSeconds = decoded.exp - Math.floor(Date.now() / 1000);
  if (remainingSeconds <= 0) {
    return; // already expired — nothing to revoke
  }

  // TTL must match remaining lifetime — never store without TTL
  // Missing TTL = denylist grows unboundedly = eventual Redis OOM
  await redis.setEx(`blacklist:${decoded.jti}`, remainingSeconds, 'revoked');
}

// Denylist check middleware — runs AFTER signature verification
// Do not run this before verifying the signature — decode alone can be spoofed
async function checkBlacklist(req, res, next) {
  const token = req.headers['authorization']?.split(' ')[1];
  if (!token) return next();

  // req.user is set by the JWT verification middleware that runs before this one
  // We use req.user.jti rather than decoding again — signature already verified
  const jti = req.user?.jti;
  if (!jti) return next(); // token has no jti — cannot check denylist

  const isRevoked = await redis.exists(`blacklist:${jti}`);
  if (isRevoked) {
    return res.status(401).json({ error: 'Token revoked', code: 'TOKEN_REVOKED' });
  }

  next();
}

// Logout: clear refresh token from store + optionally revoke access token
async function logout(req, res) {
  const userId = req.user.userId;
  const refreshToken = req.body.refreshToken;

  // Always: delete refresh token from store
  if (refreshToken) {
    const tokenHash = crypto
      .createHash('sha256')
      .update(refreshToken)
      .digest('hex');
    await deleteRefreshTokenFromStore(tokenHash);
  }

  // Optional: revoke access token for immediate invalidation
  // Adds Redis lookup per request — only worth it if instant revocation is required
  const accessToken = req.headers['authorization']?.split(' ')[1];
  if (accessToken) {
    await revokeAccessToken(accessToken);
  }

  res.json({ message: 'Logged out successfully' });
}

// Sign tokens with jti for revocation support
function generateAccessToken(userId, role) {
  return jwt.sign(
    {
      userId,
      role,
      jti: crypto.randomUUID() // unique token ID — required for denylist
    },
    process.env.JWT_SECRET,
    { expiresIn: '15m', algorithm: 'HS256' }
  );
}