JWT Security Best Practices

import jwt from "jsonwebtoken";
import crypto from "crypto";
import fs from "fs";

// RECOMMENDED: Asymmetric signing with RS256
// Only the auth server has the private key
// All services can verify with the public key
const privateKey = fs.readFileSync("./keys/private.pem");
const publicKey = fs.readFileSync("./keys/public.pem");

interface TokenPayload {
  userId: string;
  role: string;
  permissions: string[];
}

function createAccessToken(payload: TokenPayload): string {
  return jwt.sign(
    {
      sub: payload.userId,
      role: payload.role,
      permissions: payload.permissions,
      // Token ID for revocation tracking
      jti: crypto.randomUUID(),
    },
    privateKey,
    {
      algorithm: "RS256",
      expiresIn: "15m", // Short-lived access tokens
      issuer: "https://auth.myapp.com",
      audience: "https://api.myapp.com",
      notBefore: 0, // Valid immediately
    }
  );
}

function createRefreshToken(userId: string): string {
  const tokenId = crypto.randomUUID();

  // Store refresh token metadata in database for revocation
  db.query(
    "INSERT INTO refresh_tokens (id, user_id, expires_at) VALUES ($1, $2, $3)",
    [tokenId, userId, new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)]
  );

  return jwt.sign(
    { sub: userId, jti: tokenId, type: "refresh" },
    privateKey,
    {
      algorithm: "RS256",
      expiresIn: "7d",
      issuer: "https://auth.myapp.com",
    }
  );
}

// Secure JWT verification
function verifyAccessToken(token: string): TokenPayload {
  try {
    const decoded = jwt.verify(token, publicKey, {
      // CRITICAL: Always specify allowed algorithms
      // This prevents the "alg: none" attack and algorithm confusion attacks
      algorithms: ["RS256"],

      // Verify issuer matches your auth server
      issuer: "https://auth.myapp.com",

      // Verify audience matches this service
      audience: "https://api.myapp.com",

      // Clock tolerance for slight server time differences
      clockTolerance: 10, // 10 seconds

      // Require these claims to be present
      complete: false,
    });

    return decoded as TokenPayload;
  } catch (error) {
    if (error instanceof jwt.TokenExpiredError) {
      throw new AuthError("Token expired", 401);
    }
    if (error instanceof jwt.JsonWebTokenError) {
      throw new AuthError("Invalid token", 401);
    }
    throw new AuthError("Token verification failed", 401);
  }
}

// Middleware for Express
function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith("Bearer ")) {
    return res.status(401).json({ error: "Missing authorization header" });
  }

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

  try {
    const payload = verifyAccessToken(token);
    req.user = payload;
    next();
  } catch (error) {
    return res.status(401).json({ error: error.message });
  }
}

// Strategy 1: Token Blocklist (for critical revocations)
class TokenBlocklist {
  private redis: RedisClient;

  async revoke(jti: string, expiresAt: number): Promise<void> {
    // Store in blocklist until the token would have expired anyway
    const ttl = expiresAt - Math.floor(Date.now() / 1000);
    if (ttl > 0) {
      await this.redis.setEx(`blocklist:${jti}`, ttl, "revoked");
    }
  }

  async isRevoked(jti: string): Promise<boolean> {
    const result = await this.redis.get(`blocklist:${jti}`);
    return result !== null;
  }
}

// Strategy 2: Token Version (per-user revocation)
// Store a token version number in the database for each user
// Increment it when you need to invalidate all their tokens
async function verifyTokenVersion(userId: string, tokenVersion: number) {
  const user = await db.query(
    "SELECT token_version FROM users WHERE id = $1",
    [userId]
  );
  if (user.rows[0].token_version !== tokenVersion) {
    throw new AuthError("Token has been revoked");
  }
}

// Strategy 3: Short-lived tokens + refresh token rotation
// Access tokens expire in 15 minutes
// Refresh tokens are single-use and stored in database
async function rotateRefreshToken(oldRefreshToken: string) {
  const decoded = jwt.verify(oldRefreshToken, publicKey, {
    algorithms: ["RS256"],
  });

  // Check if refresh token exists and is not used
  const stored = await db.query(
    "SELECT * FROM refresh_tokens WHERE id = $1 AND used = false",
    [decoded.jti]
  );

  if (!stored.rows.length) {
    // Token reuse detected! Possible token theft
    // Revoke ALL refresh tokens for this user
    await db.query(
      "DELETE FROM refresh_tokens WHERE user_id = $1",
      [decoded.sub]
    );
    throw new SecurityError("Refresh token reuse detected - all sessions revoked");
  }

  // Mark old token as used
  await db.query("UPDATE refresh_tokens SET used = true WHERE id = $1", [decoded.jti]);

  // Issue new tokens
  const accessToken = createAccessToken({ userId: decoded.sub, role: decoded.role, permissions: decoded.permissions });
  const refreshToken = createRefreshToken(decoded.sub);

  return { accessToken, refreshToken };
}