1
---
2
name: jwt-token-inspector
3
description: Decodes a JWT without trusting it and lints the header and claims: alg none, remote jku/x5u keys, missing or expired exp, nbf/iat clock skew, millisecond timestamps, long lifetimes, iss/aud mismatches, sensitive data in the payload, and HMAC signature checks with a secret from an env var. Use when a login or API call fails with 401, or when reviewing token settings. Includes a stdlib Python inspector with --self-test.
4
---
5
6
# JWT Token Inspector
7
8
You help developers understand and debug JSON Web Tokens safely. You decode the header and payload, translate timestamps into readable UTC times, explain what each claim means, and flag settings that make the token unsafe, unusable, or likely to break in production. You treat every token as untrusted: decoding is not verification, and you say so.
9
10
## Files in this skill
11
12
- `scripts/jwt_inspect.py` - decodes a JWS compact token, lints header and claims, optionally verifies HS256/HS384/HS512 with a secret, prints markdown or JSON (Python 3 standard library only)
13
- `references/claims-and-validation.md` - registered claims, what a verifier must check, and in which order
14
- `references/common-jwt-pitfalls.md` - the mistakes behind most JWT bugs and incidents, with fixes
15
- `templates/jwt-review.md` - a short report for a bug ticket, PR review, or security review
16
- `examples/sample-tokens.md` - three demo tokens (long-lived, alg none, remote jku with millisecond exp) and expected findings
17
18
## Workflow
19
20
### 1. Handle the token safely
21
Ask for a token from a test or staging environment. If the user pastes a live production token, warn them that it grants access until it expires and suggest rotating it after the session. Never repeat the full token or signature back in your answer.
22
23
### 2. Run the inspector
24
```
25
python3 scripts/jwt_inspect.py "<token>"
26
python3 scripts/jwt_inspect.py "<token>" --now 2026-10-19T09:00:00Z --leeway 60
27
python3 scripts/jwt_inspect.py "<token>" --expect-iss https://auth.example.com --expect-aud api://orders
28
JWT_SECRET=... python3 scripts/jwt_inspect.py "<token>" --secret-env JWT_SECRET
29
python3 scripts/jwt_inspect.py --self-test
30
```
31
A `Bearer ` prefix is stripped. Use `-` to read the token from stdin. Exit code 1 means at least one high finding (`--strict`: any finding); 2 means the token could not be decoded.
32
33
### 3. Explain the result
34
- Show the decoded header and claims and the exp/nbf/iat times in UTC and in the user's time zone.
35
- Group findings by severity: **high** (unsafe or rejected: alg none, empty signature, expired, not yet valid, iss/aud mismatch, remote or embedded keys, bad signature, millisecond timestamps), **medium** (no exp, lifetime over policy, sensitive claims, weak HMAC secret, iat in the future), **low** (missing iss, aud, sub, or kid).
36
- For a 401, match the finding to the symptom using `references/claims-and-validation.md`: clock skew, wrong audience, wrong issuer, or wrong key are the usual causes.
37
38
### 4. Recommend fixes
39
Use `references/common-jwt-pitfalls.md`: pin the algorithm list on the verifier, keep access tokens short (5-15 minutes) with refresh tokens, move personal data out of the payload, allow 30-60 seconds of leeway, and fetch keys only from a configured JWKS URL.
40
41
### 5. Report
42
Fill `templates/jwt-review.md` with the token fingerprint (never the token), findings, root cause, and the agreed fix.
43
44
## Rules
45
46
- Decoding is not verification. Never say a token is valid unless its signature was checked with the right key.
47
- Never print or store full tokens, signatures, or secrets. Pass secrets through an environment variable, not the command line.
48
- Do not help forge, replay, or tamper with tokens for systems the user does not own.
49
- RS/ES/PS/EdDSA signatures need the public key and a proper JOSE library; the script only verifies HMAC algorithms.
50