JWT handling practices documented and followed

Severity: Recommended

JWTs have many footguns - storage location, expiration, refresh flow, signing algorithms. Teams should document their chosen practices and periodically verify compliance.

Check automatically:

1. Find JWT-related documentation:

# Look for JWT docs in common locations
find . -type f \( -name "*.md" -o -name "*.txt" \) -exec grep -liE "jwt|json web token|access.?token|refresh.?token" {} \; 2>/dev/null

# Check for auth/security docs
ls -la docs/*auth* docs/*security* docs/*jwt* README*.md SECURITY.md 2>/dev/null

2. Identify JWT library in use:

# Common JWT libraries
grep -E "jsonwebtoken|jose|jwt-decode|@auth0/|next-auth|passport-jwt" package.json

3. Find JWT implementation code:

# Token creation/signing
grep -rE "jwt\.sign|signJwt|createToken|generateToken|new SignJWT" --include="*.ts" --include="*.js" src/ 2>/dev/null

# Token verification
grep -rE "jwt\.verify|verifyJwt|validateToken|jwtVerify" --include="*.ts" --include="*.js" src/ 2>/dev/null

4. Check JWT configuration (expiration, algorithm):

# Expiration settings
grep -rE "expiresIn|exp:|maxAge.*token" --include="*.ts" --include="*.js" src/ 2>/dev/null

# Algorithm settings (RS256/ES256 preferred over HS256 for production)
grep -rE "algorithm.*HS256|algorithm.*RS256|algorithm.*ES256|alg:" --include="*.ts" --include="*.js" src/ 2>/dev/null

5. Check where tokens are stored (ties back to CSS-001/002):

# Client-side token storage
grep -rE "localStorage.*token|sessionStorage.*token|token.*localStorage" --include="*.ts" --include="*.tsx" --include="*.js" src/ 2>/dev/null

6. Check for refresh token flow:

grep -rE "refreshToken|refresh_token|tokenRefresh|rotateToken" --include="*.ts" --include="*.js" src/ 2>/dev/null

Ask user:

• "Is JWT usage documented anywhere (Notion, Confluence, README)?"
• "When was the last time JWT practices were reviewed?"
• "Are you using short-lived access tokens + refresh tokens?"

Key JWT best practices to verify:

• Short expiration for access tokens (15min-1hr)
• Refresh tokens stored server-side or in HttpOnly cookies
• Strong signing algorithm (RS256/ES256 preferred over HS256)
• Tokens not stored in localStorage
• Token revocation strategy exists

Cross-reference with:

• CSS-001 (tokens should be in HttpOnly cookies)
• CSS-002 (tokens should NOT be in localStorage)
• SEC-XXX (signing key rotation)

Pass criteria:

• JWT practices documented (in repo or external docs)
• Implementation matches documented practices
• Short-lived access tokens with refresh flow, OR
• Session-based auth (no long-lived JWTs)

Fail criteria:

• No documentation of JWT practices
• Long-lived JWTs (>24hr) without refresh mechanism
• JWTs stored in localStorage
• Using none algorithm or weak signing

Evidence to capture:

• JWT library in use
• Token expiration configuration
• Signing algorithm
• Storage location (cookies vs localStorage)
• Documentation location (if exists)
• Refresh token strategy (if any)

---