django-bolt 0.1.0__cp310-abi3-win_amd64.whl

django_bolt/auth/revocation.py

@@ -0,0 +1,286 @@
+"""
+Token revocation support for Django-Bolt.
+
+Provides flexible revocation strategies that users can choose based on their needs.
+Revocation is OPTIONAL - only checked if user provides a handler.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Set
+from datetime import timedelta
+
+
+class RevocationStore(ABC):
+    """
+    Base class for token revocation storage.
+
+    Implementations can use in-memory, Django cache, database, Redis, etc.
+    """
+
+    @abstractmethod
+    async def is_revoked(self, jti: str) -> bool:
+        """
+        Check if a token (by JTI) is revoked.
+
+        Args:
+            jti: JWT ID (unique token identifier)
+
+        Returns:
+            True if token is revoked, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def revoke(self, jti: str, ttl: Optional[int] = None) -> None:
+        """
+        Revoke a token by its JTI.
+
+        Args:
+            jti: JWT ID to revoke
+            ttl: Time-to-live in seconds (optional, for cleanup)
+        """
+        pass
+
+    async def revoke_all(self, user_id: str) -> None:
+        """
+        Revoke all tokens for a user (optional, not all stores support this).
+
+        Args:
+            user_id: User identifier
+        """
+        raise NotImplementedError("This revocation store does not support revoke_all")
+
+
+class InMemoryRevocation(RevocationStore):
+    """
+    Simple in-memory revocation store.
+
+    ⚠️  WARNING: Only works in single-process mode. Not suitable for production
+    with multiple workers. Use DjangoCacheRevocation for multi-process setups.
+
+    Good for:
+    - Development
+    - Testing
+    - Single-process deployments
+
+    Example:
+        ```python
+        from django_bolt.auth import JWTAuthentication
+        from django_bolt.auth.revocation import InMemoryRevocation
+
+        revocation = InMemoryRevocation()
+
+        auth = JWTAuthentication(
+            secret=settings.SECRET_KEY,
+            revocation_store=revocation,
+        )
+
+        # In logout endpoint
+        @api.post("/logout")
+        async def logout(request):
+            jti = request["context"]["auth_claims"]["jti"]
+            await revocation.revoke(jti)
+            return {"message": "Logged out"}
+        ```
+    """
+
+    def __init__(self):
+        self._revoked: Set[str] = set()
+
+    async def is_revoked(self, jti: str) -> bool:
+        return jti in self._revoked
+
+    async def revoke(self, jti: str, ttl: Optional[int] = None) -> None:
+        self._revoked.add(jti)
+        # TTL not supported in memory (would need background cleanup)
+
+    def clear(self) -> None:
+        """Clear all revoked tokens (useful for testing)."""
+        self._revoked.clear()
+
+
+class DjangoCacheRevocation(RevocationStore):
+    """
+    Django cache-based revocation store.
+
+    Works with ANY Django cache backend:
+    - Redis (django.core.cache.backends.redis.RedisCache)
+    - Memcached (django.core.cache.backends.memcached.PyMemcacheCache)
+    - Database (django.core.cache.backends.db.DatabaseCache)
+    - File-based (django.core.cache.backends.filebased.FileBasedCache)
+    - Local memory (django.core.cache.backends.locmem.LocMemCache)
+
+    ✅ Production-ready: Works across multiple processes/workers
+    ✅ Fast: Uses Django's cache framework (Redis ~50k ops/sec)
+    ✅ Automatic cleanup: TTL handled by cache backend
+
+    Example:
+        ```python
+        # settings.py
+        CACHES = {
+            'default': {
+                'BACKEND': 'django.core.cache.backends.redis.RedisCache',
+                'LOCATION': 'redis://127.0.0.1:6379/1',
+            }
+        }
+
+        # api.py
+        from django_bolt.auth import JWTAuthentication
+        from django_bolt.auth.revocation import DjangoCacheRevocation
+
+        auth = JWTAuthentication(
+            secret=settings.SECRET_KEY,
+            revocation_store=DjangoCacheRevocation(cache_alias='default'),
+        )
+        ```
+    """
+
+    def __init__(self, cache_alias: str = 'default', key_prefix: str = 'revoked:'):
+        """
+        Initialize Django cache-based revocation.
+
+        Args:
+            cache_alias: Django cache alias to use (default: 'default')
+            key_prefix: Prefix for cache keys (default: 'revoked:')
+        """
+        self.cache_alias = cache_alias
+        self.key_prefix = key_prefix
+        self._cache = None
+
+    @property
+    def cache(self):
+        """Lazy-load cache to avoid import issues."""
+        if self._cache is None:
+            from django.core.cache import caches
+            self._cache = caches[self.cache_alias]
+        return self._cache
+
+    async def is_revoked(self, jti: str) -> bool:
+        key = f"{self.key_prefix}{jti}"
+        # Django cache get is sync, but fast
+        return self.cache.get(key) is not None
+
+    async def revoke(self, jti: str, ttl: Optional[int] = None) -> None:
+        key = f"{self.key_prefix}{jti}"
+        # TTL defaults to 30 days (longer than most refresh tokens)
+        timeout = ttl or (86400 * 30)
+        self.cache.set(key, "1", timeout=timeout)
+
+
+class DjangoORMRevocation(RevocationStore):
+    """
+    Database-based revocation store using Django ORM.
+
+    ⚠️  Slower than cache-based solutions (~1k-5k ops/sec vs 50k ops/sec).
+    Only use if you don't have cache infrastructure.
+
+    Requires creating a model:
+    ```python
+    # myapp/models.py
+    from django.db import models
+
+    class RevokedToken(models.Model):
+        jti = models.CharField(max_length=255, unique=True, db_index=True)
+        revoked_at = models.DateTimeField(auto_now_add=True)
+        expires_at = models.DateTimeField(db_index=True)
+
+        class Meta:
+            indexes = [
+                models.Index(fields=['jti']),
+                models.Index(fields=['expires_at']),
+            ]
+    ```
+
+    Then run migrations:
+    ```bash
+    python manage.py makemigrations
+    python manage.py migrate
+    ```
+
+    Usage:
+    ```python
+    from django_bolt.auth.revocation import DjangoORMRevocation
+
+    revocation = DjangoORMRevocation(model='myapp.RevokedToken')
+
+    auth = JWTAuthentication(
+        secret=settings.SECRET_KEY,
+        revocation_store=revocation,
+    )
+    ```
+
+    ⚠️  Remember to add a cleanup task to delete expired tokens:
+    ```python
+    # Periodic task (celery, cron, etc.)
+    from datetime import datetime, timezone
+
+    async def cleanup_expired_tokens():
+        await RevokedToken.objects.filter(
+            expires_at__lt=datetime.now(timezone.utc)
+        ).adelete()
+    ```
+    """
+
+    def __init__(self, model: str):
+        """
+        Initialize ORM-based revocation.
+
+        Args:
+            model: String path to model (e.g., 'myapp.RevokedToken')
+        """
+        self.model_path = model
+        self._model = None
+
+    @property
+    def model(self):
+        """Lazy-load model to avoid import issues."""
+        if self._model is None:
+            from django.apps import apps
+            app_label, model_name = self.model_path.split('.')
+            self._model = apps.get_model(app_label, model_name)
+        return self._model
+
+    async def is_revoked(self, jti: str) -> bool:
+        return await self.model.objects.filter(jti=jti).aexists()
+
+    async def revoke(self, jti: str, ttl: Optional[int] = None) -> None:
+        from datetime import datetime, timezone, timedelta
+
+        expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl or 86400 * 30)
+
+        await self.model.objects.aupdate_or_create(
+            jti=jti,
+            defaults={'expires_at': expires_at}
+        )
+
+
+def create_revocation_handler(store: RevocationStore):
+    """
+    Create a revoked_token_handler from a RevocationStore.
+
+    This is a convenience function to convert a RevocationStore into
+    a callable that can be passed to JWTAuthentication.
+
+    Args:
+        store: RevocationStore instance
+
+    Returns:
+        Async callable that checks if token is revoked
+
+    Example:
+        ```python
+        from django_bolt.auth.revocation import InMemoryRevocation, create_revocation_handler
+
+        store = InMemoryRevocation()
+        handler = create_revocation_handler(store)
+
+        auth = JWTAuthentication(
+            secret=settings.SECRET_KEY,
+            revoked_token_handler=handler,
+        )
+        ```
+    """
+    async def handler(jti: str) -> bool:
+        return await store.is_revoked(jti)
+
+    return handler

django_bolt/auth/token.py

@@ -0,0 +1,335 @@
+"""
+JWT Token handling for Django-Bolt.
+
+Provides a Token dataclass for encoding/decoding JWTs. The actual validation
+happens in Rust for performance, but this provides Python-side utilities for
+token creation and inspection.
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional, Set
+import msgspec
+
+
+def _normalize_datetime(value: datetime) -> datetime:
+    """
+    Convert datetime to UTC and strip microseconds for consistent JWT claims.
+
+    Args:
+        value: A datetime instance
+
+    Returns:
+        A normalized datetime in UTC without microseconds
+    """
+    if value.tzinfo is not None:
+        value = value.astimezone(timezone.utc)
+    return value.replace(microsecond=0, tzinfo=timezone.utc)
+
+
+@dataclass
+class Token:
+    """
+    JWT Token data structure.
+
+    This class represents a JWT token with standard claims (exp, sub, iat, etc.)
+    and optional custom claims. The actual encoding/decoding happens in Rust
+    for performance, but you can use this class to construct tokens in Python.
+
+    Standard Claims:
+        exp: Expiration time (required, must be in the future)
+        sub: Subject - usually user ID (required)
+        iat: Issued at time (auto-generated if not provided)
+        iss: Issuer - identifies who issued the token
+        aud: Audience - intended recipient(s)
+        jti: JWT ID - unique identifier for this token
+
+    Django-Bolt Custom Claims:
+        is_staff: Whether user is staff
+        is_superuser/is_admin: Whether user is admin
+        permissions: List of permission strings
+
+    Example:
+        >>> token = Token(
+        ...     sub="user123",
+        ...     exp=datetime.now(timezone.utc) + timedelta(hours=1),
+        ...     is_staff=True,
+        ...     permissions=["users.view", "users.edit"]
+        ... )
+        >>> encoded = token.encode(secret="my-secret", algorithm="HS256")
+    """
+
+    exp: datetime
+    """Expiration time - when the token expires (required, must be future)"""
+
+    sub: str
+    """Subject - typically the user ID or identifier (required)"""
+
+    iat: datetime = field(default_factory=lambda: _normalize_datetime(datetime.now(timezone.utc)))
+    """Issued at - timestamp when token was created"""
+
+    iss: Optional[str] = None
+    """Issuer - who issued the token (e.g., "my-auth-service")"""
+
+    aud: Optional[str] = None
+    """Audience - intended recipient (e.g., "my-api")"""
+
+    jti: Optional[str] = None
+    """JWT ID - unique identifier for this token (useful for revocation)"""
+
+    nbf: Optional[datetime] = None
+    """Not before - token is not valid before this time"""
+
+    # Django-Bolt specific claims
+    is_staff: Optional[bool] = None
+    """Whether the user is staff"""
+
+    is_superuser: Optional[bool] = None
+    """Whether the user is a superuser/admin"""
+
+    is_admin: Optional[bool] = None
+    """Alternative admin flag (checked along with is_superuser)"""
+
+    permissions: Optional[List[str]] = None
+    """List of permission strings (e.g., ["users.view", "posts.create"])"""
+
+    # Extra custom claims
+    extras: Dict[str, Any] = field(default_factory=dict)
+    """Any additional custom claims not covered by standard fields"""
+
+    # Internal flag to skip validation (used during decoding)
+    _skip_validation: bool = field(default=False, repr=False, compare=False)
+
+    def __post_init__(self):
+        """Validate token fields after initialization."""
+        # Validate sub is non-empty
+        if not self.sub or len(self.sub) < 1:
+            raise ValueError("sub (subject) must be a non-empty string")
+
+        # Normalize and validate exp
+        if isinstance(self.exp, datetime):
+            self.exp = _normalize_datetime(self.exp)
+            if not self._skip_validation:
+                now = _normalize_datetime(datetime.now(timezone.utc))
+                if self.exp.timestamp() <= now.timestamp():
+                    raise ValueError("exp (expiration) must be in the future")
+        else:
+            raise ValueError("exp must be a datetime object")
+
+        # Normalize iat
+        if isinstance(self.iat, datetime):
+            self.iat = _normalize_datetime(self.iat)
+            if not self._skip_validation:
+                now = _normalize_datetime(datetime.now(timezone.utc))
+                if self.iat.timestamp() > now.timestamp():
+                    raise ValueError("iat (issued at) must be current or past time")
+
+        # Normalize nbf if provided
+        if self.nbf is not None and isinstance(self.nbf, datetime):
+            self.nbf = _normalize_datetime(self.nbf)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert token to dictionary for encoding.
+
+        Returns:
+            Dictionary with all claims, converting datetimes to Unix timestamps
+        """
+        result = {}
+
+        # Standard claims
+        result["exp"] = int(self.exp.timestamp())
+        result["sub"] = self.sub
+        result["iat"] = int(self.iat.timestamp())
+
+        if self.iss is not None:
+            result["iss"] = self.iss
+        if self.aud is not None:
+            result["aud"] = self.aud
+        if self.jti is not None:
+            result["jti"] = self.jti
+        if self.nbf is not None:
+            result["nbf"] = int(self.nbf.timestamp())
+
+        # Django-Bolt custom claims
+        if self.is_staff is not None:
+            result["is_staff"] = self.is_staff
+        if self.is_superuser is not None:
+            result["is_superuser"] = self.is_superuser
+        if self.is_admin is not None:
+            result["is_admin"] = self.is_admin
+        if self.permissions is not None:
+            result["permissions"] = self.permissions
+
+        # Extra claims
+        result.update(self.extras)
+
+        return result
+
+    def encode(
+        self,
+        secret: str,
+        algorithm: str = "HS256",
+        headers: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """
+        Encode the token into a JWT string.
+
+        Note: This uses Python's jwt library for convenience. For production
+        token generation at scale, consider using Rust directly via PyO3.
+
+        Args:
+            secret: Secret key for signing
+            algorithm: JWT algorithm (HS256, HS384, HS512, RS256, etc.)
+            headers: Optional additional headers (e.g., {"kid": "key-id"})
+
+        Returns:
+            Encoded JWT string
+
+        Raises:
+            ValueError: If encoding fails
+        """
+        try:
+            import jwt
+            return jwt.encode(
+                payload=self.to_dict(),
+                key=secret,
+                algorithm=algorithm,
+                headers=headers,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to encode token: {e}") from e
+
+    @classmethod
+    def decode(
+        cls,
+        encoded_token: str,
+        secret: str,
+        algorithm: str = "HS256",
+        audience: Optional[str] = None,
+        issuer: Optional[str] = None,
+        verify_exp: bool = True,
+        verify_nbf: bool = True,
+    ) -> "Token":
+        """
+        Decode and validate a JWT token.
+
+        Note: In production, JWT validation happens in Rust for performance.
+        This method is provided for testing and Python-side token inspection.
+
+        Args:
+            encoded_token: The JWT string to decode
+            secret: Secret key for validation
+            algorithm: Expected algorithm
+            audience: Expected audience (if any)
+            issuer: Expected issuer (if any)
+            verify_exp: Verify expiration time
+            verify_nbf: Verify not-before time
+
+        Returns:
+            Decoded Token instance
+
+        Raises:
+            ValueError: If token is invalid or verification fails
+        """
+        try:
+            import jwt
+
+            options = {
+                "verify_signature": True,
+                "verify_exp": verify_exp,
+                "verify_nbf": verify_nbf,
+                "verify_aud": audience is not None,
+                "verify_iss": issuer is not None,
+            }
+
+            payload = jwt.decode(
+                jwt=encoded_token,
+                key=secret,
+                algorithms=[algorithm],
+                audience=audience if audience else None,
+                issuer=issuer if issuer else None,
+                options=options,
+            )
+
+            # Convert timestamps back to datetime
+            exp = datetime.fromtimestamp(payload["exp"], tz=timezone.utc)
+            iat = datetime.fromtimestamp(payload.get("iat", payload["exp"] - 3600), tz=timezone.utc)
+            nbf = None
+            if "nbf" in payload:
+                nbf = datetime.fromtimestamp(payload["nbf"], tz=timezone.utc)
+
+            # Extract known fields
+            known_fields = {
+                "exp", "sub", "iat", "iss", "aud", "jti", "nbf",
+                "is_staff", "is_superuser", "is_admin", "permissions"
+            }
+            extras = {k: v for k, v in payload.items() if k not in known_fields}
+
+            return cls(
+                exp=exp,
+                sub=payload["sub"],
+                iat=iat,
+                iss=payload.get("iss"),
+                aud=payload.get("aud"),
+                jti=payload.get("jti"),
+                nbf=nbf,
+                is_staff=payload.get("is_staff"),
+                is_superuser=payload.get("is_superuser"),
+                is_admin=payload.get("is_admin"),
+                permissions=payload.get("permissions"),
+                extras=extras,
+                _skip_validation=True,  # Skip validation when decoding
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to decode token: {e}") from e
+
+    @classmethod
+    def create(
+        cls,
+        sub: str,
+        expires_delta: Optional[timedelta] = None,
+        issuer: Optional[str] = None,
+        audience: Optional[str] = None,
+        is_staff: bool = False,
+        is_admin: bool = False,
+        permissions: Optional[List[str]] = None,
+        **extra_claims: Any,
+    ) -> "Token":
+        """
+        Convenient factory method to create a token.
+
+        Args:
+            sub: Subject (user ID)
+            expires_delta: How long until expiration (default: 1 hour)
+            issuer: Token issuer
+            audience: Token audience
+            is_staff: Staff flag
+            is_admin: Admin flag
+            permissions: List of permissions
+            **extra_claims: Any additional claims
+
+        Returns:
+            New Token instance
+        """
+        if expires_delta is None:
+            expires_delta = timedelta(hours=1)
+
+        now = datetime.now(timezone.utc)
+        exp = now + expires_delta
+
+        return cls(
+            exp=exp,
+            sub=sub,
+            iat=now,
+            iss=issuer,
+            aud=audience,
+            is_staff=is_staff,
+            is_admin=is_admin or is_staff,  # Admin implies staff
+            permissions=permissions,
+            extras=extra_claims,
+        )
+
+
+# Alias for backwards compatibility with Litestar-style naming
+JWTToken = Token