Token Introspection Utility

A small library that surfaces JOSE headers and JWT claims without performing any signature verification, enabling offline inspection of incoming tokens.

Capabilities

Header extraction without verification

• Given a compact JWT whose header includes alg HS256, typ JWT, and kid primary, the header extractor returns a mapping containing those keys without needing any signing secret. @test

Claim inspection without verification

• Given a JWT carrying claims such as sub user-123, role admin, and an expired exp, the claim extractor returns all claims exactly as encoded, even when the token is expired or signed with an unknown key. @test

Batch summarization

• Given a list of two JWT strings (one HMAC-based, one RSA-based), the summarizer produces two entries in the same order, each containing the raw header, raw claims, the header kid (or None if absent), and the sub claim (or None if absent). @test

Malformed token handling

• Passing a token missing one of the three JWT segments raises a ValueError mentioning a malformed token and does not attempt any verification. @test

Implementation

@generates

API

from dataclasses import dataclass
from typing import Any, Dict, List, Optional

@dataclass
class TokenSummary:
    header: Dict[str, Any]
    claims: Dict[str, Any]
    kid: Optional[str]
    subject: Optional[str]

def read_header(token: str) -> Dict[str, Any]:
    """Return the decoded header from a compact JWT/JWS without verifying its signature."""

def read_claims(token: str) -> Dict[str, Any]:
    """Return the decoded claims from a compact JWT without verifying its signature."""

def summarize_tokens(tokens: List[str]) -> List[TokenSummary]:
    """Return per-token summaries containing unverified headers/claims; preserve input order."""

Dependencies { .dependencies }

python-jose { .dependency }

Provides JOSE/JWT parsing utilities without requiring signature verification.