## 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