JWT

Implement secure JWT authentication with proper validation and token handling.

Security Scan

This is an instruction-only documentation skill about secure JWT design and validation; its requirements and runtime instructions align with its stated purpose and it does not request credentials, installs, or external access.

Purpose & Capability

Name/description match the provided content: the files focus on JWT algorithms, validation, lifecycle, and common attacks. The skill requests no unrelated binaries, env vars, or config paths.

Instruction Scope

SKILL.md and supporting files provide guidance and checklists only (algorithm choice, claims, expiry, JWKS, etc.). They do not instruct the agent to read local secrets, contact arbitrary endpoints, exfiltrate data, or run commands. Recommendations to use standard JWT libraries are appropriate for the stated goal.

Install Mechanism

No install spec and no code files are included; nothing is written to disk or downloaded by the skill itself, which minimizes installation risk.

Credentials

The skill declares no required environment variables or credentials. The guidance references secrets and JWKS as implementation considerations but does not request access to them from the agent.

Persistence & Privilege

The skill is not force-included (always: false) and uses normal agent invocation settings. It does not request persistent privileges or modifications to other skills or system-wide config.

Assessment

This skill is documentation-only and appears coherent with its stated goal of secure JWT implementation: it won’t install software or ask for credentials. Consider these practical precautions before using it: (1) verify the skill source if you need to trust implementation guidance; (2) when implementing follow the recommended established libraries (keep them up-to-date) rather than hand-rolling JWT code; (3) never place secrets in JWT payloads and avoid logging tokens; (4) use HTTPS for JWKS endpoints, enforce algorithm allowlists (don’t trust the token's alg header), and implement short expiry plus refresh/rotation strategies; (5) if you copy any sample code from elsewhere, review it for vulnerabilities (e.g., acceptance of alg: none). Overall the skill is coherent and low-risk, but actual security depends on how you implement the recommendations.

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