Buckets:

download
raw
7.18 kB
"""Token serializer strategies for session tokens.
Provides a simple serializer compatible with the existing
"session_id.signature.timestamp" format, and an optional JWT serializer.
The JWT serializer supports dependency injection to allow swapping in
compatible JWT backends (e.g., PyJWT or another library exposing
``encode``/``decode`` with similar signatures).
"""
from __future__ import annotations
import importlib
import logging
from datetime import datetime
from datetime import timezone
from typing import TYPE_CHECKING
from typing import Any
from typing import Protocol
from .models import SessionToken
if TYPE_CHECKING: # Import for typing only to avoid circular import concerns
from .config import SessionConfig
logger = logging.getLogger(__name__)
# Token format constant - 3 parts: session_id, signature, timestamp
TOKEN_PARTS_COUNT = 3
class TokenSerializer(Protocol):
"""Protocol for token serialization strategies."""
def to_string(self, token: SessionToken) -> str: # pragma: no cover - interface
"""Serialize a `SessionToken` to a string."""
def from_string(
self, token_str: str
) -> SessionToken: # pragma: no cover - interface
"""Parse a string into a `SessionToken` (with necessary verification)."""
class SimpleTokenSerializer:
"""Serializer for the default simple token format."""
def to_string(self, token: SessionToken) -> str:
"""Convert token to string format.
Format: {session_id}.{signature}.{timestamp}
Args:
token: SessionToken instance to serialize
Returns:
Token string in format {session_id}.{signature}.{timestamp}
"""
timestamp = int(token.issued_at.timestamp())
logger.debug("SimpleTokenSerializer to_string called; id=%s", token.session_id)
return f"{token.session_id}.{token.signature}.{timestamp}"
def from_string(self, token_str: str) -> SessionToken:
"""Parse token from string format.
Args:
token_str: Token string in format {session_id}.{signature}.{timestamp}
Returns:
SessionToken instance
Raises:
ValueError: If token format is invalid
"""
parts = token_str.split(".")
if len(parts) != TOKEN_PARTS_COUNT:
msg = "Invalid token format"
raise ValueError(msg)
session_id, signature, timestamp = parts
try:
issued_at = datetime.fromtimestamp(int(timestamp), tz=timezone.utc)
except (ValueError, OSError, OverflowError) as e:
msg = f"Invalid timestamp in token: {e}"
raise ValueError(msg) from e
logger.debug("SimpleTokenSerializer parsed from string; id=%s", session_id)
return SessionToken(
session_id=session_id, signature=signature, issued_at=issued_at
)
class JWTTokenSerializer:
"""JWT-based token serializer.
Encodes the session reference into a signed JWT with claims:
- sid: session id (custom claim)
- iat: issued at (epoch seconds)
- exp: expiry (epoch seconds), derived from config.session_ttl
Optionally:
- iss: issuer (if configured)
- aud: audience (if configured)
"""
def __init__(self, config: SessionConfig, jwt_module: Any | None = None) -> None:
"""Initialize a JWT-based serializer with optional backend injection.
Args:
config: Session configuration instance.
jwt_module: Optional JWT-compatible module providing ``encode`` and
``decode``; defaults to importing ``jwt`` (PyJWT).
"""
if jwt_module is not None:
self.jwt_encoder = jwt_module # pragma: no cover
else:
try:
self.jwt_encoder = importlib.import_module("jwt")
except ImportError as e: # pragma: no cover
msg = "JWT backend not available; install fastapi-cachex[jwt] or inject jwt_module"
raise ImportError(msg) from e
# Copy required parameters
self._secret = config.secret_key.get_secret_value()
self._algorithm = config.jwt_algorithm
self._issuer = config.jwt_issuer
self._audience = config.jwt_audience
self._leeway = config.jwt_leeway
self._session_ttl = config.session_ttl
def to_string(self, token: SessionToken) -> str:
"""Encode a `SessionToken` as a signed JWT string.
Uses claims `sid`, `iat`, `exp`, and optional `iss`/`aud`.
"""
iat = int(token.issued_at.timestamp())
# Use session's expires_at when available (supports sliding expiration)
if token.expires_at is not None:
exp = int(token.expires_at.timestamp())
else:
exp = iat + int(self._session_ttl)
payload: dict[str, object] = {
"sid": token.session_id,
"iat": iat,
"exp": exp,
}
if self._issuer:
payload["iss"] = self._issuer
if self._audience:
payload["aud"] = self._audience
encoded = self.jwt_encoder.encode(
payload, self._secret, algorithm=self._algorithm
)
logger.debug("JWT token encoded; sid=%s", token.session_id)
# PyJWT may return str in PyJWT>=2, ensure str
return str(encoded)
def from_string(self, token_str: str) -> SessionToken:
"""Decode and verify a JWT string into a `SessionToken`.
Verifies signature, `exp`, and `iat`, and optional `iss`/`aud`.
"""
options = {
"require": ["sid", "iat", "exp"],
"verify_signature": True,
"verify_exp": True,
"verify_iat": True,
}
kwargs: dict[str, object] = {
"algorithms": [self._algorithm],
"options": options,
"leeway": self._leeway,
"key": self._secret,
}
if self._issuer:
kwargs["issuer"] = self._issuer
if self._audience:
kwargs["audience"] = self._audience
try:
payload = self.jwt_encoder.decode(token_str, **kwargs)
except Exception as e: # Broad catch to normalize to ValueError
logger.debug("JWT decode failed: %s", e)
msg = "Invalid JWT token"
raise ValueError(msg) from e
try:
raw_sid = payload["sid"]
raw_iat = payload["iat"]
except Exception as e:
msg = "Invalid JWT payload"
raise ValueError(msg) from e
# Normalize types for mypy and runtime safety
sid = raw_sid if isinstance(raw_sid, str) else str(raw_sid)
if isinstance(raw_iat, int):
iat = raw_iat
else:
try:
iat = int(raw_iat)
except Exception as e:
msg = "Invalid JWT payload"
raise ValueError(msg) from e
issued_at = datetime.fromtimestamp(iat, tz=timezone.utc)
# For JWT path, signature is not used in downstream verification
return SessionToken(session_id=sid, signature="", issued_at=issued_at)

Xet Storage Details

Size:
7.18 kB
·
Xet hash:
ee3e96bd1b4078eca1ee08acf176dd4094f1276f7b8c729c4cef3d93f9908836

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.