JWT Verification Verdict

Decides whether a JWT call site ACTUALLY AUTHENTICATES the token it reads. Pure function over how the call is written: no I/O, no crypto, no jsonwebtoken dependency.

THE MEASUREMENT. jsonwebtoken 9.0.3, real keys, real forgeries:

  1. A token the ATTACKER MINTED, signed with a secret they chose
     jwt.decode(forged)            {"sub":"user_123","role":"admin","iat":1786051195}
     jwt.verify(forged, SECRET)    THREW: invalid signature

  2. A token with NO SIGNATURE AT ALL (alg: none)
     jwt.decode(unsigned)          {"sub":"user_123","role":"admin"}
     jwt.verify(unsigned, SECRET)  THREW: jwt signature is required

  3. A VALID token whose payload was then EDITED
     jwt.decode(tampered).role     "admin"
     jwt.verify(tampered, SECRET)  THREW: invalid signature

  4. An EXPIRED but correctly signed token
     jwt.decode(expired)           returned the claims
     jwt.verify(expired, SECRET)   THREW: jwt expired

decode() returned a plausible, well-formed claims object for EVERY ONE. It does not throw and does not return null. The failure is not an exception -- it is role:"admin", in exactly the shape the calling code expects, from a token the attacker wrote.

THE ADVICE EVERYONE REPEATS IS NOT WHAT PROTECTS YOU. The classic algorithm-confusion attack: a server issues RS256 and verifies with its PUBLIC key, so an attacker signs an HS256 token using that public key as the HMAC secret. Measured:

    verify(forged, publicKey)  -- no algorithms option    REJECTED: invalid algorithm
    verify(forged, publicKey, {algorithms:["RS256"]})     REJECTED: invalid algorithm
    verify(real,   publicKey)  -- the genuine token       ACCEPTED

"Always pass algorithms" is stated almost universally as the thing standing between you and this attack. On 9.0.3 it is NOT -- the library infers the permitted family from the KEY TYPE and rejects the forgery either way. Pass it anyway as defence-in-depth, but a reader who believes it is what protects them has the wrong model of their own system, and the actual protection is a property of the LIBRARY VERSION -- the thing to pin and to re-check after an upgrade.

So unpinned algorithms is reported as ADVISORY, not critical. A tool that cries critical over correct code is switched off before it catches a real one. No claim is made about other libraries or older versions.

IT ALSO REPORTS: a key taken from the token's own jku/x5u/jwk header, which is CRITICAL even though the call is verify() -- the signature check then passes honestly over an input the attacker chose; unenforced expiry, because expiry IS revocation for a stateless token; and an unchecked audience, because a signature proves who MINTED the token, not who it was FOR.

VERIFIED: 19 tests, measured by running the suite, every mutation observed FAILING before restore -- including one that exposed a VACUOUS TEST in this package's own suite and was fixed.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateJwtCallSite(site: JwtCallSite): Verdict;

  export type VerifyCall = "verify" | "decode" | "unknown";
  export type Verdict = | { status: "AUTHENTICATED";