JWT Handling skill for Claude Code

Done well means: tokens are verified (never just decoded) with a pinned algorithm and the right key, every required claim is checked, lifetimes are short, keys rotate without downtime, and logout/revocation has an explicit answer. If you need instant revocation and only one backend consumes the token, reconsider: an opaque session ID may be simpler (see auth-sessions).

Hard rules

• Always pass an explicit algorithm allowlist to the verify call. Never derive the algorithm from the token header alone.
• Never accept alg: none. Never let an asymmetric public key be used as an HMAC secret (algorithm confusion: RS256 key accepted as HS256).
• decode without verification is for debugging only. Grep for it in production code.
• Require exp. Check iss and aud on every verification. Allow ≤ 60 s clock skew.
• Do not put secrets or sensitive PII in the payload: JWS payloads are base64url, not encrypted. Anyone holding the token can read them.
• Never fetch keys from a URL in the token (jku, x5u) or trust an embedded jwk header. Keys come from configuration or the issuer’s known JWKS endpoint.

Choosing algorithms and keys

Situation	Algorithm
One service issues and verifies	HS256 with a ≥ 256-bit random secret is acceptable; EdDSA/ES256 if others may verify later
Issuer and verifiers are different services	Asymmetric: EdDSA (Ed25519) or ES256; RS256/PS256 for broad compatibility (≥ 2048-bit RSA)
Third-party IdP tokens	Whatever the IdP publishes in JWKS, pinned to that list
Payload must be confidential	JWE, or do not put the data in the token

Verify correctly

Node (npm i jose):

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));

export async function verifyAccessToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://auth.example.com/",
    audience: "https://api.example.com",
    algorithms: ["ES256"],
    clockTolerance: 30,
    requiredClaims: ["exp", "sub"],
  });
  return payload;
}

Python (pip install "pyjwt[crypto]"):

import jwt
from jwt import PyJWKClient

jwks = PyJWKClient("https://auth.example.com/.well-known/jwks.json", cache_keys=True)

def verify(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token).key
    return jwt.decode(
        token, key,
        algorithms=["RS256"],
        audience="https://api.example.com",
        issuer="https://auth.example.com/",
        leeway=30,
        options={"require": ["exp", "iat", "iss", "aud", "sub"]},
    )

Go (github.com/golang-jwt/jwt/v5):

tok, err := jwt.Parse(raw, keyFunc,
    jwt.WithValidMethods([]string{"ES256"}),
    jwt.WithIssuer("https://auth.example.com/"),
    jwt.WithAudience("https://api.example.com"),
    jwt.WithExpirationRequired(),
    jwt.WithLeeway(30*time.Second),
)

Node jsonwebtoken: always pass { algorithms: [...], audience, issuer } to jwt.verify; jwt.decode does no verification.

After signature and claims pass, authorization is still separate: check scopes/roles for the operation and object-level ownership.

Issue correctly

• Claims: iss, sub (stable user ID, not email), aud (the intended API), exp, iat, jti (if you need revocation or replay detection), minimal custom claims.
• Header: alg, kid (always — needed for rotation), typ (at+jwt for access tokens per RFC 9068 helps prevent token confusion).
• Lifetimes: access tokens 5–15 minutes; refresh tokens hours to days, rotated on use, stored server-side or as opaque values with a DB record.
• Keep tokens small; they ride on every request and cookies cap near 4 KB.

Key rotation without downtime

1. Generate the new key pair; publish its public key in JWKS alongside the old (new kid).
2. Wait for verifier JWKS caches to refresh (cache TTL, typically ≤ 1 hour).
3. Start signing with the new key.
4. Keep the old public key published until the longest-lived token signed with it expires.
5. Remove the old key. For HS256, verifiers must accept both secrets during the overlap.

Verifiers should refetch JWKS on unknown kid (rate limited), which jose and PyJWKClient do.

Storage in browsers

Option	XSS impact	CSRF	Verdict
localStorage / sessionStorage	Token stolen and usable anywhere	None	Avoid for anything sensitive
JS memory + refresh via HttpOnly cookie	Token usable only while XSS runs; refresh cookie not readable	Protect refresh endpoint	Acceptable for SPAs without a backend
HttpOnly Secure SameSite cookie (BFF)	Not readable by script	Needs CSRF defenses	Preferred

Revocation strategies

Need	Approach
Logout on this device	Delete refresh token server-side; access token dies at exp (keep it short)
Logout everywhere / password change	Per-user token_version (or sessions_valid_after timestamp) checked on refresh; optionally on each request via cache
Kill a specific stolen token now	Denylist jti in Redis until its exp
Compromised signing key	Rotate key immediately and remove old kid from JWKS; all tokens signed with it fail

If every request must check a store to support revocation, you have rebuilt sessions; that is fine, but choose it deliberately.

Auditing existing code

grep -rnE "jwt\.decode\(|jsonwebtoken.*decode|jwt_decode|verify_signature\"?\s*:\s*False|verify\s*=\s*False" --include=*.{js,ts,py,go,java,rb} .
grep -rnE "algorithms\s*[:=]" --include=*.{js,ts,py} .       # confirm explicit allowlists
grep -rnE "jwt\.verify\([^,]+,[^,]+\)" --include=*.{js,ts} .  # verify without options
grep -rnE "localStorage\.(setItem|getItem)\(['\"](token|jwt|access)" --include=*.{js,ts,tsx} .

Inspect a token someone pasted (decodes only — never treat this as verification):

python3 scripts/jwt_inspect.py "<token>"
python3 scripts/jwt_inspect.py --file token.txt --max-lifetime 3600

The script prints header and payload, human-readable times, and flags: alg none or symmetric, jku/x5u/jwk/suspicious kid headers, missing exp/iss/aud, expired tokens, lifetimes above the threshold, and sensitive-looking claim names. It exits 1 when any high-risk flag is raised. Ask before pasting production tokens anywhere; they are live credentials until exp.

Gotchas

• aud can be a string or array; libraries handle both, hand-written checks often do not.
• Clock skew between services causes intermittent exp/nbf failures; sync NTP and use small leeway rather than large tolerances.
• kid used as a file path or SQL key in custom key lookup is an injection point.
• Base64url, not base64: - and _, no padding. Hand decoders break on this.
• Long-lived JWTs “because refresh is complicated” are the most common real-world flaw.

Verification

Write unit tests that build tokens locally and assert rejection for: wrong signature, alg: none, HS256 signed with the RSA public key, expired exp, future nbf, wrong iss, wrong aud, unknown kid. Assert a valid token passes. Run the audit greps and confirm every decode without verification is test or debug code.