jwt-policy-guard

Policy-first JWT verification and issuing for Python 3.9+. The package builds on PyJWT's maintained cryptographic implementation and adds an immutable application policy so security decisions do not come from attacker-controlled token headers.

Created by Luis Aneuris Tavarez De Jesus.

Why this exists

JWT signature verification is only one part of token security. Applications must also constrain algorithms, bind keys to a trusted issuer, validate audiences, require time claims, distinguish token types, and enforce their own scopes and roles. jwt-policy-guard makes those decisions explicit and reusable.

Installation

pip install jwt-policy-guard

Verify tokens

from datetime import timedelta
from jwt_policy_guard import JwtPolicy, JwtVerifier, JwksKeyProvider

policy = JwtPolicy(
    algorithms=("RS256",),
    issuer="https://identity.example.com/",
    audiences=("payments-api",),
    required_scopes=frozenset({"payments:read"}),
    max_token_age=timedelta(minutes=15),
)

verifier = JwtVerifier(
    policy,
    JwksKeyProvider("https://identity.example.com/.well-known/jwks.json"),
)
verified = verifier.verify(encoded_token)

print(verified.subject)
verified.require_roles({"operator"})

Issue application-owned tokens

from datetime import timedelta
from jwt_policy_guard import JwtIssuer

issuer = JwtIssuer(
    issuer="https://identity.example.com/",
    audiences=("payments-api",),
    key=private_key,
    algorithm="RS256",
    key_id="2026-09-primary",
)

token = issuer.issue(
    "customer-42",
    expires_in=timedelta(minutes=10),
    scopes={"payments:read"},
    roles={"customer"},
    claims={"tenant": "acme"},
)

Security guarantees

• No unsecured none algorithm.
• Symmetric and asymmetric algorithms cannot be mixed in one policy.
• The allow-list never comes from the token header.
• Trusted issuer, intended audience, registered time claims, and explicit typ.
• Optional maximum token age, subject pattern, required scopes, and roles.
• HTTPS-only JWKS by default with PyJWT key caching and rotation support.
• Read-only verified claims and a typed exception hierarchy.

This library follows the deployment guidance in RFC 8725. It does not replace TLS, secure key storage, key rotation, token revocation, or application authorization. Never log raw tokens.

Development

python -m pip install -e '.[dev]'
ruff check .
mypy src
pytest
python -m build
twine check dist/*

License

MIT