jwtlint 0.2.0__tar.gz

jwtlint-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baran Ayaztaş
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jwtlint-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: jwtlint
+Version: 0.2.0
+Summary: Offline static security analysis for JWTs.
+Author: Baran Ayaztas
+License: MIT
+Project-URL: Homepage, https://github.com/ReazGan/jwtlint
+Project-URL: Issues, https://github.com/ReazGan/jwtlint/issues
+Keywords: jwt,security,pentest,bug-bounty,appsec,static-analysis,jws
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.7
+Dynamic: license-file
+
+# jwtlint
+
+[![CI](https://github.com/ReazGan/jwtlint/actions/workflows/ci.yml/badge.svg)](https://github.com/ReazGan/jwtlint/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jwtlint)](https://pypi.org/project/jwtlint/)
+
+Offline static security analysis for JWTs (RFC 7519 / RFC 7515). Paste a
+token from Burp, a log line or an `Authorization` header and get a list of
+what's wrong with it. Parses the three base64url segments itself, no JWT
+library in the analysis path, no network calls.
+
+![jwtlint flagging a token with a jku header, a kid path traversal and a weak secret](https://raw.githubusercontent.com/ReazGan/jwtlint/main/docs/screenshot.svg)
+
+## Install
+
+```
+pip install jwtlint
+```
+
+or from source:
+
+```
+git clone https://github.com/ReazGan/jwtlint
+cd jwtlint
+pip install -e .
+```
+
+## Usage
+
+```
+$ jwtlint eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTQyIiwiaWF0IjoxNzg3MjY5OTY5LCJleHAiOjE3ODcyNzM1Njl9.0RVnIJ29GLfYPK3YfZNbLuhf_19F4nI71aeg0ZvZSr4
+header
+{
+  "alg": "HS256",
+  "typ": "JWT"
+}
+payload
+{
+  "exp": 1787273569,
+  "iat": 1787269969,
+  "sub": "user-42"
+}
+       jwtlint findings
+┏━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
+┃ sev      ┃ check ┃ finding ┃
+┡━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
+└──────────┴───────┴─────────┘
+
+0 findings
+```
+
+An `alg: none` forgery attempt (see the screenshot above for the full run):
+
+```
+$ jwtlint eyJhbGciOiAibm9uZSIsICJ0eXAiOiAiSldUIn0.eyJzdWIiOiAiYXR0YWNrZXIiLCAiYWRtaW4iOiB0cnVlLCAiaWF0IjogMTcwMDAwMDAwMH0.
+critical  alg-none  alg: 'none' — unsigned/forgeable token
+high      claims    No exp (expiration) claim
+
+2 findings — critical: 1  high: 1
+```
+
+Other flags:
+
+```
+jwtlint --file token.txt                 # read the token from a file instead of argv
+pbpaste | jwtlint                        # read from stdin ("Bearer ..." prefix is fine)
+jwtlint <token> --expect-alg RS256       # flag RS-to-HS confusion if the token uses HS*
+jwtlint <token> --crack                  # try the built-in weak-secret wordlist
+jwtlint <token> --crack wordlist.txt     # try a custom wordlist
+jwtlint <token> --json                   # findings as JSON instead of a table
+```
+
+Exit code is `1` if any finding is `critical` or `high` — usable as a CI gate.
+Malformed input (wrong segment count, bad base64url, bad JSON) exits `2` with
+a plain error message, not a stack trace.
+
+## Checks
+
+- **alg-none** — header specifies `alg: none` (case-insensitively — `None`,
+  `NONE`, etc. are all caught), the classic unsigned-token forgery.
+- **alg-confusion** — with `--expect-alg RS256` (or any RS/ES/PS algorithm),
+  flags a token that instead uses HS256/384/512 as a possible RS-to-HS key
+  confusion attack: a verifier that feeds its RSA/EC public key into HMAC
+  verification whenever the header says `alg: HS*` can be tricked into
+  accepting a token forged with that (public, therefore attacker-known) key
+  as the HMAC secret.
+- **header-injection** — key-selection headers the attacker controls:
+  `jku` / `x5u` (verifier fetches the key from a URL, also an SSRF vector),
+  an embedded `jwk` (CVE-2018-0114 style self-signed tokens), an embedded
+  `x5c` chain, and `kid` values that look like path traversal
+  (`../../dev/null`), SQL or shell injection.
+- **sensitive-data** — payload claims that look like passwords, API keys,
+  session ids or personal data (national id, IBAN, phone, card numbers with
+  a Luhn check). Payloads are base64url, not encrypted: anyone holding the
+  token can read them.
+- **claims** — missing `exp` (high, token never expires), an already-expired
+  `exp` (info, just noted), missing `iat` (low), `nbf` earlier than `iat`
+  (low), and unreasonably long-lived tokens — `exp - iat` over a year by
+  default, configurable with `--max-lifetime-days`.
+- **hmac-crack** (`--crack`, opt-in, fully offline) — for HS256/384/512
+  tokens, recomputes the HMAC signature for each line of a wordlist and
+  compares against the token's actual signature. Ships a built-in list of
+  ~50 common weak secrets used by default when `--crack` is passed with no
+  file.
+
+## In CI
+
+Exit code `1` on critical/high makes it a one-line gate, e.g. to make sure
+the tokens your test suite issues never carry secrets or skip `exp`:
+
+```yaml
+- run: pip install jwtlint
+- run: python scripts/issue_test_token.py | jwtlint
+```
+
+## Scope
+
+A lean, non-interactive, single-purpose static analyzer — decode a token,
+report what's wrong with it, exit. It doesn't talk to a server, doesn't try
+exploits, and doesn't cover every JWT attack technique.
+[`ticarpi/jwt_tool`](https://github.com/ticarpi/jwt_tool) is the heavier
+reference tool if you need full interactive exploitation tooling.
+
+## License
+
+MIT

jwtlint-0.2.0/README.md

@@ -0,0 +1,125 @@
+# jwtlint
+
+[![CI](https://github.com/ReazGan/jwtlint/actions/workflows/ci.yml/badge.svg)](https://github.com/ReazGan/jwtlint/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jwtlint)](https://pypi.org/project/jwtlint/)
+
+Offline static security analysis for JWTs (RFC 7519 / RFC 7515). Paste a
+token from Burp, a log line or an `Authorization` header and get a list of
+what's wrong with it. Parses the three base64url segments itself, no JWT
+library in the analysis path, no network calls.
+
+![jwtlint flagging a token with a jku header, a kid path traversal and a weak secret](https://raw.githubusercontent.com/ReazGan/jwtlint/main/docs/screenshot.svg)
+
+## Install
+
+```
+pip install jwtlint
+```
+
+or from source:
+
+```
+git clone https://github.com/ReazGan/jwtlint
+cd jwtlint
+pip install -e .
+```
+
+## Usage
+
+```
+$ jwtlint eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTQyIiwiaWF0IjoxNzg3MjY5OTY5LCJleHAiOjE3ODcyNzM1Njl9.0RVnIJ29GLfYPK3YfZNbLuhf_19F4nI71aeg0ZvZSr4
+header
+{
+  "alg": "HS256",
+  "typ": "JWT"
+}
+payload
+{
+  "exp": 1787273569,
+  "iat": 1787269969,
+  "sub": "user-42"
+}
+       jwtlint findings
+┏━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
+┃ sev      ┃ check ┃ finding ┃
+┡━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
+└──────────┴───────┴─────────┘
+
+0 findings
+```
+
+An `alg: none` forgery attempt (see the screenshot above for the full run):
+
+```
+$ jwtlint eyJhbGciOiAibm9uZSIsICJ0eXAiOiAiSldUIn0.eyJzdWIiOiAiYXR0YWNrZXIiLCAiYWRtaW4iOiB0cnVlLCAiaWF0IjogMTcwMDAwMDAwMH0.
+critical  alg-none  alg: 'none' — unsigned/forgeable token
+high      claims    No exp (expiration) claim
+
+2 findings — critical: 1  high: 1
+```
+
+Other flags:
+
+```
+jwtlint --file token.txt                 # read the token from a file instead of argv
+pbpaste | jwtlint                        # read from stdin ("Bearer ..." prefix is fine)
+jwtlint <token> --expect-alg RS256       # flag RS-to-HS confusion if the token uses HS*
+jwtlint <token> --crack                  # try the built-in weak-secret wordlist
+jwtlint <token> --crack wordlist.txt     # try a custom wordlist
+jwtlint <token> --json                   # findings as JSON instead of a table
+```
+
+Exit code is `1` if any finding is `critical` or `high` — usable as a CI gate.
+Malformed input (wrong segment count, bad base64url, bad JSON) exits `2` with
+a plain error message, not a stack trace.
+
+## Checks
+
+- **alg-none** — header specifies `alg: none` (case-insensitively — `None`,
+  `NONE`, etc. are all caught), the classic unsigned-token forgery.
+- **alg-confusion** — with `--expect-alg RS256` (or any RS/ES/PS algorithm),
+  flags a token that instead uses HS256/384/512 as a possible RS-to-HS key
+  confusion attack: a verifier that feeds its RSA/EC public key into HMAC
+  verification whenever the header says `alg: HS*` can be tricked into
+  accepting a token forged with that (public, therefore attacker-known) key
+  as the HMAC secret.
+- **header-injection** — key-selection headers the attacker controls:
+  `jku` / `x5u` (verifier fetches the key from a URL, also an SSRF vector),
+  an embedded `jwk` (CVE-2018-0114 style self-signed tokens), an embedded
+  `x5c` chain, and `kid` values that look like path traversal
+  (`../../dev/null`), SQL or shell injection.
+- **sensitive-data** — payload claims that look like passwords, API keys,
+  session ids or personal data (national id, IBAN, phone, card numbers with
+  a Luhn check). Payloads are base64url, not encrypted: anyone holding the
+  token can read them.
+- **claims** — missing `exp` (high, token never expires), an already-expired
+  `exp` (info, just noted), missing `iat` (low), `nbf` earlier than `iat`
+  (low), and unreasonably long-lived tokens — `exp - iat` over a year by
+  default, configurable with `--max-lifetime-days`.
+- **hmac-crack** (`--crack`, opt-in, fully offline) — for HS256/384/512
+  tokens, recomputes the HMAC signature for each line of a wordlist and
+  compares against the token's actual signature. Ships a built-in list of
+  ~50 common weak secrets used by default when `--crack` is passed with no
+  file.
+
+## In CI
+
+Exit code `1` on critical/high makes it a one-line gate, e.g. to make sure
+the tokens your test suite issues never carry secrets or skip `exp`:
+
+```yaml
+- run: pip install jwtlint
+- run: python scripts/issue_test_token.py | jwtlint
+```
+
+## Scope
+
+A lean, non-interactive, single-purpose static analyzer — decode a token,
+report what's wrong with it, exit. It doesn't talk to a server, doesn't try
+exploits, and doesn't cover every JWT attack technique.
+[`ticarpi/jwt_tool`](https://github.com/ticarpi/jwt_tool) is the heavier
+reference tool if you need full interactive exploitation tooling.
+
+## License
+
+MIT

jwtlint-0.2.0/jwtlint/__init__.py

@@ -0,0 +1,3 @@
+"""jwtlint — offline static analysis for JSON Web Tokens (RFC 7519/7515)."""
+
+__version__ = "0.1.0"

jwtlint-0.2.0/jwtlint/checks/__init__.py

@@ -0,0 +1,31 @@
+"""Static analysis checks run against a parsed JWT.
+
+Each check module exposes a `check(parsed, **options) -> list[Finding]`
+function. `run_all` wires them together in a fixed order.
+"""
+
+from __future__ import annotations
+
+from jwtlint.checks import alg_confusion, alg_none, claims, crack, header_injection, sensitive
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+
+def run_all(
+    parsed: ParsedToken,
+    expect_alg: str | None = None,
+    max_lifetime_seconds: int | None = None,
+    crack_wordlist: list[str] | None = None,
+) -> list[dict]:
+    findings: list[Finding] = []
+
+    findings.extend(alg_none.check(parsed))
+    findings.extend(alg_confusion.check(parsed, expect_alg=expect_alg))
+    findings.extend(header_injection.check(parsed))
+    findings.extend(claims.check(parsed, max_lifetime_seconds=max_lifetime_seconds))
+    findings.extend(sensitive.check(parsed))
+
+    if crack_wordlist is not None:
+        findings.extend(crack.check(parsed, wordlist=crack_wordlist))
+
+    return [f.to_dict() for f in findings]

jwtlint-0.2.0/jwtlint/checks/alg_confusion.py

@@ -0,0 +1,80 @@
+"""RS-to-HS algorithm confusion check.
+
+A static analyzer looking only at the token can't know what algorithm the
+server actually expects — that's server-side configuration, not something
+encoded in the token itself. `--expect-alg` lets the caller supply that
+context (e.g. "I know this service is configured for RS256").
+
+The attack: if a server verifies RS256/ES256 tokens using its RSA/EC
+*public* key, and an attacker submits an HS256 token instead, some JWT
+libraries will happily use whatever key material they're handed as the
+HMAC secret. Since the RSA public key is, by definition, public, the
+attacker can compute a valid HMAC signature over a forged token using the
+public key as the secret — and the server verifies it as authentic. This
+only matters if the verifier is naive enough to trust the `alg` from the
+attacker-controlled header instead of pinning the expected algorithm.
+"""
+
+from __future__ import annotations
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "alg-confusion"
+
+_HMAC_ALGS = {"HS256", "HS384", "HS512"}
+_ASYMMETRIC_ALGS = {"RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512"}
+
+
+def check(parsed: ParsedToken, expect_alg: str | None = None) -> list[Finding]:
+    if not expect_alg:
+        return []
+
+    alg = parsed.header.get("alg")
+    if not isinstance(alg, str):
+        return []
+
+    expect_alg_upper = expect_alg.upper()
+    alg_upper = alg.upper()
+
+    if alg_upper == expect_alg_upper:
+        return []
+
+    if alg_upper in _HMAC_ALGS and expect_alg_upper in _ASYMMETRIC_ALGS:
+        return [
+            Finding(
+                check=CHECK_NAME,
+                title=f"algorithm confusion risk: token uses {alg}, server expects {expect_alg}",
+                description=(
+                    f"This token's header specifies alg={alg} (HMAC), but the "
+                    f"server was told to expect {expect_alg} (RSA/EC, asymmetric). "
+                    "This is the classic RS-to-HS confusion attack: if the "
+                    "verifier passes its RSA/EC *public* key into an HMAC "
+                    "verification routine whenever the header says alg=HS*, an "
+                    "attacker can sign a forged token with HMAC-SHA256 using the "
+                    "public key (which is, by definition, known to the attacker) "
+                    "as the secret, and the server will treat it as validly "
+                    "signed. A safe verifier must pin the expected algorithm "
+                    "server-side and reject any token whose header claims a "
+                    "different one, rather than trusting alg from attacker-"
+                    "controlled input."
+                ),
+                severity="critical",
+                evidence={"token_alg": alg, "expected_alg": expect_alg},
+            )
+        ]
+
+    return [
+        Finding(
+            check=CHECK_NAME,
+            title=f"algorithm mismatch: token uses {alg}, server expects {expect_alg}",
+            description=(
+                f"The token's alg ({alg}) does not match the expected algorithm "
+                f"({expect_alg}). A verifier that doesn't strictly pin/allowlist "
+                "the algorithm may accept tokens signed under a weaker or "
+                "unintended scheme."
+            ),
+            severity="medium",
+            evidence={"token_alg": alg, "expected_alg": expect_alg},
+        )
+    ]

jwtlint-0.2.0/jwtlint/checks/alg_none.py

@@ -0,0 +1,60 @@
+"""`alg: none` check (CVE-class: JWT algorithm-none forgery).
+
+Some JWT libraries historically honored `"alg": "none"` (or accepted it
+case-insensitively — `"None"`, `"NONE"`, `"nOnE"`) and skipped signature
+verification entirely. An attacker who can set the header can then forge
+any payload with an empty signature segment. This is check #1 in basically
+every JWT security write-up because it's still found in the wild in custom
+or misconfigured verifiers.
+"""
+
+from __future__ import annotations
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "alg-none"
+
+
+def check(parsed: ParsedToken) -> list[Finding]:
+    alg = parsed.header.get("alg")
+    if not isinstance(alg, str):
+        return []
+
+    if alg.lower() != "none":
+        return []
+
+    findings = [
+        Finding(
+            check=CHECK_NAME,
+            title=f"alg: {alg!r} — unsigned/forgeable token",
+            description=(
+                "The header sets alg to a case-variant of 'none'. Libraries that "
+                "compare this case-insensitively (or that special-case 'none' "
+                "without validating the signature segment) will accept this token "
+                "with any payload and no valid signature — a classic auth bypass. "
+                "A safe verifier must reject 'none' outright and only accept an "
+                "algorithm it was explicitly configured to expect."
+            ),
+            severity="critical",
+            evidence={"alg": alg},
+        )
+    ]
+
+    if parsed.signature_segment.strip():
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="alg: none token carries a non-empty signature segment",
+                description=(
+                    "alg is 'none' but the signature segment is non-empty. This is "
+                    "unusual — a spec-compliant 'none' token has an empty third "
+                    "segment. The signature bytes present here are ignored by any "
+                    "verifier that honors alg: none, so they provide no protection."
+                ),
+                severity="low",
+                evidence={"alg": alg, "signature_segment_length": len(parsed.signature_segment)},
+            )
+        )
+
+    return findings

jwtlint-0.2.0/jwtlint/checks/base.py

@@ -0,0 +1,30 @@
+"""Shared types for check modules.
+
+Every check module in this package exposes a `check(parsed, **kwargs) ->
+list[Finding]` function and returns findings shaped like `Finding.to_dict()`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Severity = Literal["info", "low", "medium", "high", "critical"]
+
+
+@dataclass
+class Finding:
+    check: str
+    title: str
+    description: str
+    severity: Severity
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "check": self.check,
+            "title": self.title,
+            "description": self.description,
+            "severity": self.severity,
+            "evidence": self.evidence,
+        }

jwtlint-0.2.0/jwtlint/checks/claims.py

@@ -0,0 +1,146 @@
+"""Standard claim hygiene checks (RFC 7519 section 4.1).
+
+Covers: missing exp, already-expired exp (informational), missing iat, nbf
+that looks wrong relative to iat, and unreasonably long-lived tokens.
+"""
+
+from __future__ import annotations
+
+import time
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "claims"
+
+# A year, as a round default for "this token lives suspiciously long."
+DEFAULT_MAX_LIFETIME_SECONDS = 365 * 24 * 3600
+
+
+def _numeric_claim(payload: dict, name: str) -> float | None:
+    value = payload.get(name)
+    if isinstance(value, bool):  # bool is a subclass of int, exclude explicitly
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    return None
+
+
+def check(parsed: ParsedToken, max_lifetime_seconds: int | None = None) -> list[Finding]:
+    threshold = max_lifetime_seconds if max_lifetime_seconds is not None else DEFAULT_MAX_LIFETIME_SECONDS
+    payload = parsed.payload
+    findings: list[Finding] = []
+    now = time.time()
+
+    exp = _numeric_claim(payload, "exp")
+    iat = _numeric_claim(payload, "iat")
+    nbf = _numeric_claim(payload, "nbf")
+
+    if "exp" not in payload:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="No exp (expiration) claim",
+                description=(
+                    "The token has no exp claim, so it never expires by "
+                    "definition. A stolen or leaked token remains valid "
+                    "indefinitely unless revoked out-of-band. Every token "
+                    "issued to a client should carry a bounded expiration."
+                ),
+                severity="high",
+                evidence={},
+            )
+        )
+    elif exp is None:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="exp claim is not a valid NumericDate",
+                description=(
+                    "exp is present but is not a number (RFC 7519 requires exp to "
+                    "be a NumericDate — seconds since the Unix epoch). A verifier "
+                    "that fails to validate this type may treat the token as "
+                    "never expiring."
+                ),
+                severity="medium",
+                evidence={"exp": payload.get("exp")},
+            )
+        )
+    elif exp < now:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="Token is expired",
+                description=(
+                    f"exp ({exp:.0f}) is in the past relative to the current time "
+                    f"({now:.0f}). This isn't a vulnerability by itself — an "
+                    "expired token should be rejected by any correct verifier — "
+                    "it's just noted for context."
+                ),
+                severity="info",
+                evidence={"exp": exp, "now": now, "expired_seconds_ago": now - exp},
+            )
+        )
+
+    if "iat" not in payload:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="No iat (issued-at) claim",
+                description=(
+                    "The token has no iat claim. iat isn't required by the spec, "
+                    "but without it there's no record of when the token was "
+                    "issued, which makes it harder to reason about token age, "
+                    "detect replay of very old tokens, or audit issuance."
+                ),
+                severity="low",
+                evidence={},
+            )
+        )
+    elif iat is None:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="iat claim is not a valid NumericDate",
+                description="iat is present but is not a number (RFC 7519 NumericDate).",
+                severity="low",
+                evidence={"iat": payload.get("iat")},
+            )
+        )
+
+    if nbf is not None and iat is not None and nbf < iat:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="nbf predates iat",
+                description=(
+                    f"nbf ({nbf:.0f}) is earlier than iat ({iat:.0f}) — the token "
+                    "claims to be valid before it was issued. This is logically "
+                    "inconsistent and may indicate a clock issue on the issuer or "
+                    "a hand-crafted/forged token."
+                ),
+                severity="low",
+                evidence={"nbf": nbf, "iat": iat},
+            )
+        )
+
+    if exp is not None and iat is not None:
+        lifetime = exp - iat
+        if lifetime > threshold:
+            findings.append(
+                Finding(
+                    check=CHECK_NAME,
+                    title="Unusually long token lifetime",
+                    description=(
+                        f"exp - iat is {lifetime:.0f} seconds (~{lifetime / 86400:.0f} days), "
+                        f"above the {threshold} second (~{threshold / 86400:.0f} day) threshold. "
+                        "Long-lived tokens widen the window an attacker can use a "
+                        "stolen token, and make revocation more important since "
+                        "there's no natural expiry to rely on."
+                    ),
+                    severity="medium",
+                    evidence={"exp": exp, "iat": iat, "lifetime_seconds": lifetime, "threshold_seconds": threshold},
+                )
+            )
+
+    return findings