JWT Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: jwt for comprehensive documentation.

Token Structure

header.payload.signature

Header: { "alg": "HS256", "typ": "JWT" } Payload: { "sub": "1234", "name": "John", "iat": 1516239022 } Signature: HMACSHA256(base64(header) + "." + base64(payload), secret)

Node.js Implementation

import jwt from 'jsonwebtoken';

const SECRET = process.env.JWT_SECRET!;

// Generate token function generateToken(user: User): string { return jwt.sign( { sub: user.id, email: user.email }, SECRET, { expiresIn: '1h' } ); }

// Verify token function verifyToken(token: string): JwtPayload { return jwt.verify(token, SECRET) as JwtPayload; }

// Refresh token pattern function generateRefreshToken(user: User): string { return jwt.sign( { sub: user.id, type: 'refresh' }, SECRET, { expiresIn: '7d' } ); }

Middleware

const authenticate = (req, res, next) => { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { return res.status(401).json({ error: 'Missing token' }); }

const token = authHeader.split(' ')[1]; try { req.user = verifyToken(token); next(); } catch (err) { res.status(401).json({ error: 'Invalid token' }); } };

When NOT to Use This Skill

• Session-based authentication - Use traditional server-side sessions with cookies

• OAuth 2.0 flows - Use oauth2 skill for third-party authentication

• NextAuth.js - Use nextauth skill for Next.js authentication

• Simple internal APIs - API keys might be sufficient

Best Practices

Do Don't

Use HTTPS Store in localStorage (use httpOnly cookies)

Short expiry (15m-1h) Put sensitive data in payload

Validate all claims Use weak secrets

Use refresh tokens Ignore expiration

Anti-Patterns

Anti-Pattern Why It's Bad Correct Approach

Storing JWT in localStorage Vulnerable to XSS attacks Use httpOnly cookies

Long-lived access tokens Security risk if compromised 15-minute expiry + refresh tokens

Weak secrets (< 32 bytes) Easy to brute force Use 256-bit random secret

Ignoring algorithm verification Algorithm confusion attacks Explicitly specify allowed algorithms

Putting passwords in payload Token is base64, not encrypted Only non-sensitive claims

No token revocation Can't logout users Implement blacklist or token versioning

Quick Troubleshooting

Issue Cause Solution

"Invalid signature" Wrong secret or algorithm Verify JWT_SECRET matches, check algorithm

"Token expired" exp claim in past Implement refresh token flow

"Missing token" Authorization header not sent Check Authorization: Bearer <token>

Token not recognized Malformed token Verify header.payload.signature format

CORS errors with cookies SameSite/Secure flags Set sameSite:'strict', secure:true

Logout doesn't work Tokens are stateless Implement revocation with Redis/DB

Standard Claims

Claim Purpose

sub

Subject (user ID)

iat

Issued at

exp

Expiration

iss

Issuer

aud

Audience

Production Readiness

Security Configuration

// Use asymmetric keys (RS256) for production import * as jose from 'jose';

// Generate key pair (run once, store securely) // openssl genrsa -out private.pem 2048 // openssl rsa -in private.pem -pubout -out public.pem

const privateKey = await jose.importPKCS8( process.env.JWT_PRIVATE_KEY!, 'RS256' ); const publicKey = await jose.importSPKI( process.env.JWT_PUBLIC_KEY!, 'RS256' );

// Sign token async function generateToken(user: User): Promise<string> { return new jose.SignJWT({ sub: user.id, email: user.email, }) .setProtectedHeader({ alg: 'RS256', typ: 'JWT' }) .setIssuedAt() .setIssuer(process.env.JWT_ISSUER!) .setAudience(process.env.JWT_AUDIENCE!) .setExpirationTime('15m') // Short-lived access token .sign(privateKey); }

// Verify token async function verifyToken(token: string): Promise<jose.JWTPayload> { const { payload } = await jose.jwtVerify(token, publicKey, { issuer: process.env.JWT_ISSUER!, audience: process.env.JWT_AUDIENCE!, }); return payload; }

Secure Token Storage

// Server-side: HttpOnly cookie for access token res.cookie('access_token', token, { httpOnly: true, // Prevents XSS access secure: true, // HTTPS only sameSite: 'strict', // CSRF protection maxAge: 15 * 60 * 1000, // 15 minutes path: '/', });

// Refresh token in separate cookie res.cookie('refresh_token', refreshToken, { httpOnly: true, secure: true, sameSite: 'strict', maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days path: '/api/auth/refresh', // Only sent to refresh endpoint });

Token Rotation & Revocation

// Refresh token rotation async function refreshTokens(refreshToken: string) { // Verify refresh token const payload = await verifyRefreshToken(refreshToken);

// Check if refresh token is in blacklist (revoked) if (await isTokenRevoked(refreshToken)) { throw new Error('Token revoked'); }

// Revoke old refresh token await revokeToken(refreshToken);

// Generate new tokens const user = await db.users.findUnique({ where: { id: payload.sub } }); return { accessToken: await generateToken(user), refreshToken: await generateRefreshToken(user), }; }

// Token revocation with Redis async function revokeToken(token: string): Promise<void> { const payload = await jose.decodeJwt(token); const ttl = payload.exp! - Math.floor(Date.now() / 1000); if (ttl > 0) { await redis.set(revoked:${token}, '1', 'EX', ttl); } }

// Logout: revoke all user tokens async function logoutAll(userId: string): Promise<void> { // Increment user's token version, invalidating all existing tokens await db.users.update({ where: { id: userId }, data: { tokenVersion: { increment: 1 } }, }); }

Algorithm Security

// NEVER allow 'none' algorithm // ALWAYS specify allowed algorithms explicitly const { payload } = await jose.jwtVerify(token, publicKey, { algorithms: ['RS256'], // Only allow RS256 issuer: process.env.JWT_ISSUER!, audience: process.env.JWT_AUDIENCE!, });

// Validate token type to prevent token confusion if (payload.type !== 'access') { throw new Error('Invalid token type'); }

Monitoring Metrics

Metric Alert Threshold

Token verification failures

100/min

Refresh token reuse attempts

10/min

Expired token requests

500/min

Invalid signature errors

50/min

Claims Validation

async function validateTokenClaims(payload: jose.JWTPayload): Promise<void> { // Check required claims if (!payload.sub || !payload.iat || !payload.exp) { throw new Error('Missing required claims'); }

// Check user still exists and is active const user = await db.users.findUnique({ where: { id: payload.sub } }); if (!user || !user.isActive) { throw new Error('User not found or inactive'); }

// Check token version (for logout-all functionality) if (payload.tokenVersion !== user.tokenVersion) { throw new Error('Token invalidated'); } }

Checklist

• Use RS256 (asymmetric) in production

• Short access token expiry (15 minutes)

• Refresh tokens with rotation

• HttpOnly cookies (not localStorage)

• Secure + SameSite cookie flags

• Token revocation mechanism

• Validate issuer and audience

• Specify allowed algorithms explicitly

• Include token version for logout-all

• Monitor verification failures

• Rate limit token endpoints

Reference Documentation

• Refresh Tokens

• Security Best Practices