jwt

name	JWT
slug	jwt
version	1.0.1
description	Implement secure JWT authentication with proper validation, token lifecycle, and key management.
metadata	{"clawdbot":{"emoji":"🔐","os":["linux","darwin","win32"]}}

Quick Reference

Topic	File
Algorithm selection	algorithms.md
Token lifecycle	lifecycle.md
Validation checklist	validation.md
Common attacks	attacks.md

Security Fundamentals

• JWTs are signed, not encrypted—anyone can decode and read the payload; never store secrets in it
• Always verify signature before trusting claims—decode without verify is useless for auth
• The alg: none attack: reject tokens with algorithm "none"—some libraries accepted unsigned tokens
• Use strong secrets: HS256 needs 256+ bit key; short secrets are brute-forceable

Algorithm Choice

• HS256 (HMAC): symmetric, same key signs and verifies—good for single service
• RS256 (RSA): asymmetric, private key signs, public verifies—good for distributed systems
• ES256 (ECDSA): smaller signatures than RSA, same security—preferred for size-sensitive cases
• Never let the token dictate algorithm—verify against expected algorithm server-side

Required Claims

• exp (expiration): always set and verify—tokens without expiry live forever
• iat (issued at): when token was created—useful for invalidation policies
• nbf (not before): token not valid until this time—for scheduled access
• Clock skew: allow 30-60 seconds leeway when verifying time claims

Audience & Issuer

• iss (issuer): who created the token—verify to prevent cross-service token theft
• aud (audience): intended recipient—API should reject tokens for other audiences
• sub (subject): who the token represents—typically user ID
• Token confusion attack: without aud/iss validation, token for Service A works on Service B

Token Lifecycle

• Access tokens: short-lived (5-15 min)—limits damage if stolen
• Refresh tokens: longer-lived, stored securely—used only to get new access tokens
• Refresh token rotation: issue new refresh token on each use, invalidate old one
• Revocation is hard—JWTs are stateless; use short expiry + refresh, or maintain blacklist

Storage

• httpOnly cookie: immune to XSS, but needs CSRF protection
• localStorage: vulnerable to XSS, but simpler for SPAs
• Memory only: most secure, but lost on page refresh
• Never store in URL parameters—visible in logs, history, referrer headers

Validation Checklist

• Verify signature with correct algorithm (don't trust header's alg)
• Check exp is in future (with clock skew tolerance)
• Check iat is not unreasonably old (optional policy)
• Verify iss matches expected issuer
• Verify aud includes your service
• Check nbf if present

Common Mistakes

• Storing sensitive data in payload—it's just base64, not encrypted
• Huge payloads—JWTs go in headers; many servers limit header size to 8KB
• No expiration—indefinite tokens are security nightmares
• Same secret across environments—dev tokens work in production
• Logging tokens—they're credentials; treat as passwords

Key Rotation

• Use kid (key ID) claim to identify which key signed the token
• JWKS (JSON Web Key Set) endpoint for public key distribution
• Overlap period: accept old key while transitioning to new
• After rotation, old tokens still valid until they expire—plan accordingly

Implementation

• Use established libraries—don't implement JWT parsing yourself
• Libraries: jsonwebtoken (Node), PyJWT (Python), java-jwt (Java), golang-jwt (Go)
• Middleware should reject invalid tokens early—before any business logic