fathom.verify_token

fathom.verify_token(token, public_key, *, typ=EVALUATION_TOKEN_TYPE)

Verify a JWT token and return the decoded payload.

Parameters:

Name	Type	Description	Default
token	str	Compact JWS.	required
public_key	Ed25519PublicKey	Ed25519 public key.	required
typ	str | None	The token kind the caller expects: "fathom.evaluation" (default, tokens from :meth:AttestationService.sign) or "fathom.event" (:meth:AttestationService.sign_event). A token of any other kind -- a chained-log line, an event offered as an evaluation -- is refused. None skips the kind check.	EVALUATION_TOKEN_TYPE

Raises AttestationError if verification fails, including for a key that is not an Ed25519 public key.

Source code in src/fathom/attestation.py

def verify_token(
    token: str,
    public_key: Ed25519PublicKey,
    *,
    typ: str | None = EVALUATION_TOKEN_TYPE,
) -> dict[str, Any]:
    """Verify a JWT token and return the decoded payload.

    Args:
        token: Compact JWS.
        public_key: Ed25519 public key.
        typ: The token kind the caller expects: ``"fathom.evaluation"``
            (default, tokens from :meth:`AttestationService.sign`) or
            ``"fathom.event"`` (:meth:`AttestationService.sign_event`). A
            token of any other kind -- a chained-log line, an event offered
            as an evaluation -- is refused. ``None`` skips the kind check.

    Raises AttestationError if verification fails, including for a key that
    is not an Ed25519 public key.
    """
    try:
        claims: dict[str, Any] = jwt.decode(token, public_key, algorithms=["EdDSA"])
    except jwt.PyJWTError as exc:
        raise AttestationError(f"Token verification failed: {exc}") from exc
    if typ is not None and claims.get("typ") != typ:
        raise AttestationError(
            f"Token verification failed: typ {claims.get('typ')!r}, expected {typ!r}"
        )
    return claims