JWT Doctor — token security & forensics for AI agents (MCP)

Paste a JWT, JWE, PASETO, Branca, a framework-signed session cookie (Flask/Django/Rails/Express), or a SAML assertion and get a security verdict an LLM cannot reliably reason about from raw base64/XML: is the algorithm safe, is the token forgeable, does the signature verify against the issuer's live keys, is the signing secret a publicly-known value, and does it match real JWT-library CVEs.

SAFE / WEAK / DANGEROUS + a concrete fix per finding. The token is never logged.

Hosted service: https://jwt-doctor.vercel.app — the deep audit runs server-side. This package is a thin MCP client: it sends the token to the hosted endpoint and renders the verdict. No analysis logic ships to your machine.

Why an MCP (the moat)

A model can base64-decode a JWT, but it cannot:

• crack the HMAC secret — JWT Doctor HMAC-verifies the token's real signature against a 45,000+ corpus of leaked/default/weak JWT secrets (framework defaults, jwt.io samples, SecLists jwt.secrets, rockyou heads, leet/affix mutations). A match is cryptographic proof the token is forgeable. The corpus grows server-side with zero client update.

• verify the signature live — it resolves the issuer's JWKS over the network (OIDC discovery / jku / x5u), fetches it, and cryptographically verifies the RS*/ES*/PS*/EdDSA signature; flags jku/x5u/jwk pointing at attacker domains (SSRF / key-injection). JWKS are cached by iss with key rotation recovery and kid-not-in-JWKS detection (rotated-out/forged kid).

• fingerprint real CVEs — maps the token shape to attributed advisories (alg-confusion, alg:none, jwk-injection CVE-2022-23529, ECDSA psychic signatures CVE-2022-21449, PyJWT CVE-2022-29217, JWE RSA1_5 Bleichenbacher, zip-bomb CVE-2023-48238, …) across jsonwebtoken / jose / PyJWT / golang-jwt / Nimbus, plus a heuristic library fingerprint.

• analyze JWE — encrypted tokens (5 parts): weak key-management (RSA1_5), CBC auth-tag caveats, zip:DEF decompression bombs, PBES2 p2c DoS, nested-JWT.

• detect header manipulation — none in any casing, RS↔HS confusion surface, kid path-traversal vs SQLi (distinct fixes), unsupported crit.

• grade the secret — for a cracked HS secret: entropy, charset, patterns and an offline crack-time estimate (hashcat HS256 economics), plus breach attribution — is the secret a known framework default / jwt.io sample / leaked placeholder (it was never private)?

• audit non-JWT formats — PASETO (v1–v4), Branca, and framework-signed session cookies: Flask/itsdangerous, Django, Rails, Express. For the HMAC-keyed cookies it cracks the app SECRET_KEY against the same corpus and proves the session is forgeable (automated flask-unsign-style attack).

• analyze SAML — XML Signature Wrapping (multi-assertion / partial signing), the comment-injection auth bypass, unsigned assertions, XXE (DOCTYPE), weak SHA-1/MD5 signature algorithms, missing replay window.

• live revocation (OCSP/CRL) — for an x5c/x5u chain it parses the certificate's AIA/CDP extensions and checks the cert is not revoked against the live responder — a forensic step an LLM cannot perform.

• mobile driving licence (mDL / ISO 18013-5) — decodes and audits ISO mDL / mdoc COSE structures, surfacing the trust and integrity issues specific to verifiable mobile credentials.

• COSE / CWT — CBOR-Object-Signing tokens: structure, algorithm, and signature posture for the IoT / WebAuthn token family.

• batch — audit up to 50 tokens in one paid call; flags every provably-forgeable token across a dump.

• cross-request fleet anomalies — up to 200 tokens from one issuer: detects attacks that only exist BETWEEN tokens — replayed jti, signing-key rotation/injection mid-stream, non-monotonic iat (forged/replayed batch), burst issuance (credential stuffing), and the same weak HMAC secret signing for multiple services (forge-once, use-everywhere lateral movement).

• hardening scorecard — every deep audit returns an A–F token-security maturity grade across signing / key-management / claims / lifetime / sender-constraint, plus the top-3 prioritised fixes.

• proof-of-possession — verifies DPoP (RFC 9449) and mTLS (RFC 8705) end-to-end: recomputes the DPoP proof JWK thumbprint vs cnf.jkt, and (BYO client cert) recomputes the cert SHA-256 thumbprint vs cnf.x5t#S256.

• verifiable credentials / SD-JWT — recomputes every selective-disclosure digest under _sd_alg, flags forged/tampered claims, verifies the holder Key-Binding JWT signature against cnf, and checks aud/nonce/freshness.

• WebAuthn / passkey attestation — CBOR-decodes the attestationObject, parses authenticatorData, classifies the format, and cryptographically verifies the packed attestation signature against the x5c leaf.

• OAuth 2.1 / JAR / RAR / PKCE — audits a signed authorization request object (JAR, RFC 9101): unsigned/HS-from-public-client, request-object substitution, PKCE absent/plain, RAR wildcards, insecure redirect_uri, implicit grant.

• remediation in 9 ecosystems — every fix ships copy-paste snippets for Node (jsonwebtoken/jose), Python, Go, Java (Nimbus + jjwt), .NET, Ruby, PHP, Rust.

Related MCP server: MCPPentestBOT

Tiers

Both tiers run server-side on the hosted service. The free tier is rate-limited; the deep tier (the crack corpus, the network calls, and the CVE data) runs behind payment and never ships to the client.

Install (MCP)

{
  "mcpServers": {
    "jwt-doctor": {
      "command": "npx",
      "args": ["-y", "jwt-doctor-mcp"],
      "env": { "JWT_DOCTOR_KEY": "<your-deep-tier-key, optional>" }
    }
  }
}

Tools: check_jwt — { target: string, deep?: boolean, … } (one token; deep accepts OIDC/PASETO/DPoP/client_cert_pem companions), check_jwt_batch — { tokens: string[] } (up to 50, deep), and analyze_token_fleet — { tokens: string[] } (up to 200, cross-request anomaly detection). Without a key, the deep tools return instructions to unlock; the free verdict needs no key.

Example

check_jwt { "target": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMifQ.dozjg..." }
→ verdict: WEAK — HS256, no exp, missing aud/iss. (free)

check_jwt { "target": "<same token>", "deep": true }
→ verdict: DANGEROUS — secret "secret" cracked from corpus (forgeable in <1s),
   matches CVE pattern, A–F grade: F, top-3 fixes attached. (paid)

Pay for the deep tier (two lanes, pick one)

• 🪙 x402 (AI agents with a wallet): GET /pro/run?target=<t>&deep=true — pay per call in USDC on Base; any x402-aware client satisfies the 402 challenge transparently. No signup, no key.

• 💳 Stripe (humans/teams): buy a prepaid key at https://jwt-doctor.vercel.app/pro/checkout, then set JWT_DOCTOR_KEY in the MCP env above.

Hosted HTTP surface

• GET /run?target=<t> — free, rate-limited.

• GET /pro/run?target=<t>&deep=true — deep tier (x402 or prepaid key).

• POST /pro/batch — deep batch, body { tokens: string[] } (≤50).

• POST /pro/analyze-batch — cross-request fleet anomalies, body { tokens } (≤200).

• POST /mcp — MCP-over-HTTP (streamable-http).

Honesty

JWT Doctor analyzes structure, claims, declared algorithms, and the live signature (when a key is reachable). It does not decrypt JWEs (no key) and never logs the token. The secret-crack never asserts "forged" without a real HMAC match; live verification reports network failures as such, never as a false "safe".

License

MIT — see LICENSE.