Skip to main content

Module jwt

pylon_auth

Module jwt 

Source
Expand description

Stateless JWT sessions — alternative to opaque session tokens.

By default Pylon mints opaque random pylon_… tokens that must be looked up in the session store on every request. For deploys that can’t tolerate that round-trip (edge runtimes, CDN-backed routes, multi-region read replicas), Pylon can mint JWT-shaped sessions instead — verified by the local secret with no DB hit.

Trade-offs:

  • Pro: stateless verification (no DB read on every request)
  • Pro: clients can decode their own claims (without verifying) for UI personalization without a /me round-trip
  • Con: revocation requires either a denylist or a short TTL — a leaked JWT stays valid until its exp
  • Con: secret rotation needs both old + new keys to coexist for at least one session lifetime

Pylon uses HS256 (HMAC-SHA256) — symmetric, no key distribution. Apps that need RS256 / asymmetric verification across services should use the OIDC discovery / JWKS path on Wave 5.

Spec: https://www.rfc-editor.org/rfc/rfc7519 + RFC 7515 (JWS).

Structs§

JwtClaims
Standard claims pylon mints. Apps that want extra claims can extend via the Custom variant.

Enums§

JwtError

Functions§

looks_like_jwt
Convenience: detect whether a bearer token looks like a JWT (three .-separated base64url segments) so the dispatcher can route between session store and JWT verifier without trying both.
mint
Mint a JWT-shaped session token. The output is the header.claims.sig triplet, ready to be returned in Authorization: Bearer … form. Client doesn’t need to know the difference from an opaque session token.
verify
Verify + decode a JWT. Checks signature, alg, expiry, and issuer (when supplied). Returns the parsed claims or a structured error.