django-bolt 0.1.0__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

django_bolt/auth/guards.py

@@ -0,0 +1,224 @@
+"""
+Permission/guard system for Django-Bolt.
+
+Provides DRF-inspired permission classes (called "guards" in Litestar terminology)
+that are compiled to Rust types for zero-GIL performance.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+
+class BasePermission(ABC):
+    """
+    Base class for permission guards.
+
+    Guards are evaluated in Rust after authentication to determine if
+    a request should be allowed. This happens before the Python handler
+    is called, enabling early 403 responses without GIL overhead.
+    """
+
+    @property
+    @abstractmethod
+    def guard_name(self) -> str:
+        """Return the guard type name for Rust compilation"""
+        pass
+
+    @abstractmethod
+    def to_metadata(self) -> Dict[str, Any]:
+        """
+        Compile this permission guard into metadata for Rust.
+
+        Returns a dict that will be parsed by Rust into typed enums.
+        """
+        pass
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        """
+        Check if the authenticated user has permission (Python fallback).
+
+        This is primarily for documentation/compatibility. The actual check
+        happens in Rust for performance.
+        """
+        return True
+
+
+class AllowAny(BasePermission):
+    """
+    Allow any request, authenticated or not.
+
+    This is the default permission when no guards are specified.
+    Using this explicitly bypasses any global default permissions.
+    """
+
+    @property
+    def guard_name(self) -> str:
+        return "allow_any"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {"type": "allow_any"}
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        return True
+
+
+class IsAuthenticated(BasePermission):
+    """
+    Require that the request is authenticated.
+
+    Returns 401 if no authentication was successful.
+    """
+
+    @property
+    def guard_name(self) -> str:
+        return "is_authenticated"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {"type": "is_authenticated"}
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        return auth_context is not None and auth_context.user_id is not None
+
+
+class IsAdminUser(BasePermission):
+    """
+    Require that the authenticated user is an admin/superuser.
+
+    Returns 403 if user is not admin.
+    Requires JWT token to include 'is_superuser' or 'is_admin' claim.
+    """
+
+    @property
+    def guard_name(self) -> str:
+        return "is_admin"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {"type": "is_admin"}
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        return auth_context is not None and auth_context.is_admin
+
+
+class IsStaff(BasePermission):
+    """
+    Require that the authenticated user is staff.
+
+    Returns 403 if user is not staff.
+    Requires JWT token to include 'is_staff' claim.
+    """
+
+    @property
+    def guard_name(self) -> str:
+        return "is_staff"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {"type": "is_staff"}
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        return auth_context is not None and auth_context.is_staff
+
+
+class HasPermission(BasePermission):
+    """
+    Require that the authenticated user has a specific permission.
+
+    Args:
+        permission: Permission string (e.g., "app.view_model", "api.create_resource")
+
+    For JWT: token should include "permissions" claim as list of strings
+    For API keys: configured via key_permissions mapping in APIKeyAuthentication
+    """
+
+    def __init__(self, permission: str):
+        self.permission = permission
+
+    @property
+    def guard_name(self) -> str:
+        return "has_permission"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {
+            "type": "has_permission",
+            "permission": self.permission,
+        }
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        if auth_context is None or auth_context.permissions is None:
+            return False
+        return self.permission in auth_context.permissions
+
+
+class HasAnyPermission(BasePermission):
+    """
+    Require that the authenticated user has at least one of the specified permissions.
+
+    Args:
+        permissions: List of permission strings
+    """
+
+    def __init__(self, *permissions: str):
+        self.permissions = list(permissions)
+
+    @property
+    def guard_name(self) -> str:
+        return "has_any_permission"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {
+            "type": "has_any_permission",
+            "permissions": self.permissions,
+        }
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        if auth_context is None or auth_context.permissions is None:
+            return False
+        return any(perm in auth_context.permissions for perm in self.permissions)
+
+
+class HasAllPermissions(BasePermission):
+    """
+    Require that the authenticated user has all of the specified permissions.
+
+    Args:
+        permissions: List of permission strings
+    """
+
+    def __init__(self, *permissions: str):
+        self.permissions = list(permissions)
+
+    @property
+    def guard_name(self) -> str:
+        return "has_all_permissions"
+
+    def to_metadata(self) -> Dict[str, Any]:
+        return {
+            "type": "has_all_permissions",
+            "permissions": self.permissions,
+        }
+
+    def has_permission(self, auth_context: Optional[Any]) -> bool:
+        if auth_context is None or auth_context.permissions is None:
+            return False
+        return all(perm in auth_context.permissions for perm in self.permissions)
+
+
+def get_default_permission_classes() -> List[BasePermission]:
+    """
+    Get default permission classes from Django settings.
+
+    Looks for BOLT_DEFAULT_PERMISSION_CLASSES in settings. If not found,
+    returns [AllowAny()] (no restrictions by default).
+    """
+    try:
+        from django.conf import settings
+        from django.core.exceptions import ImproperlyConfigured
+        try:
+            if hasattr(settings, 'BOLT_DEFAULT_PERMISSION_CLASSES'):
+                return settings.BOLT_DEFAULT_PERMISSION_CLASSES
+        except ImproperlyConfigured:
+            # Settings not configured, return default
+            pass
+    except (ImportError, AttributeError):
+        pass
+
+    return [AllowAny()]

django_bolt/auth/jwt_utils.py

@@ -0,0 +1,212 @@
+"""
+JWT utility functions for Django-Bolt.
+
+Provides helper functions to create JWT tokens for Django users and
+extract user information from request context.
+"""
+import time
+import jwt
+from typing import Any, Dict, Optional
+from django.contrib.auth import get_user_model
+
+
+def create_jwt_for_user(
+    user,
+    secret: Optional[str] = None,
+    algorithm: str = "HS256",
+    expires_in: int = 3600,
+    extra_claims: Optional[Dict[str, Any]] = None
+) -> str:
+    """
+    Create a JWT token for a Django User.
+
+    Args:
+        user: Django User model instance
+        secret: JWT secret key. If None, uses Django's SECRET_KEY
+        algorithm: JWT algorithm (default: "HS256")
+        expires_in: Token expiration time in seconds (default: 3600 = 1 hour)
+        extra_claims: Additional claims to include in the token
+
+    Returns:
+        JWT token string
+
+    Standard claims included:
+        - sub: user.id (subject - user primary key)
+        - exp: expiration time (current time + expires_in)
+        - iat: issued at time (current timestamp)
+        - is_staff: user.is_staff
+        - is_superuser: user.is_superuser
+        - username: user.username (for reference)
+        - email: user.email (if available)
+
+    Example:
+        ```python
+        from django.contrib.auth import get_user_model
+        from django_bolt.jwt_utils import create_jwt_for_user
+
+        User = get_user_model()
+        user = await User.objects.aget(username="john")
+
+        # Create a basic token
+        token = create_jwt_for_user(user)
+
+        # Create token with custom expiration and extra claims
+        token = create_jwt_for_user(
+            user,
+            expires_in=7200,  # 2 hours
+            extra_claims={
+                "permissions": ["read", "write"],
+                "role": "admin",
+                "tenant_id": "acme-corp"
+            }
+        )
+        ```
+    """
+    # Use Django SECRET_KEY if no secret provided
+    if secret is None:
+        from django.conf import settings
+        secret = settings.SECRET_KEY
+
+    # Build standard claims
+    now = int(time.time())
+    payload = {
+        "sub": str(user.id),  # Subject: user ID as string
+        "exp": now + expires_in,  # Expiration time
+        "iat": now,  # Issued at
+        "is_staff": user.is_staff,
+        "is_superuser": user.is_superuser,
+        "username": user.username,
+    }
+
+    # Add email if available
+    if hasattr(user, 'email') and user.email:
+        payload["email"] = user.email
+
+    # Add first/last name if available
+    if hasattr(user, 'first_name') and user.first_name:
+        payload["first_name"] = user.first_name
+    if hasattr(user, 'last_name') and user.last_name:
+        payload["last_name"] = user.last_name
+
+    # Merge extra claims
+    if extra_claims:
+        payload.update(extra_claims)
+
+    return jwt.encode(payload, secret, algorithm=algorithm)
+
+
+async def get_current_user(request: Dict[str, Any]):
+    """
+    Dependency function to extract and fetch Django User from request context.
+
+    This is a reusable dependency that can be used with Depends() to inject
+    the current authenticated Django User into your handlers.
+
+    Args:
+        request: Request dictionary with context
+
+    Returns:
+        Django User instance or None if not authenticated or not found
+
+    Example:
+        ```python
+        from django_bolt import BoltAPI
+        from django_bolt.auth import JWTAuthentication
+        from django_bolt.permissions import IsAuthenticated
+        from django_bolt.params import Depends
+        from django_bolt.jwt_utils import get_current_user
+
+        api = BoltAPI()
+
+        @api.get(
+            "/me",
+            auth=[JWTAuthentication()],
+            guards=[IsAuthenticated()]
+        )
+        async def get_my_profile(user=Depends(get_current_user)):
+            return {
+                "id": user.id,
+                "username": user.username,
+                "email": user.email,
+                "is_staff": user.is_staff,
+            }
+        ```
+    """
+    User = get_user_model()
+    context = request.get("context", {})
+    user_id = context.get("user_id")
+
+    if not user_id:
+        return None
+
+    try:
+        # Fetch User from database using async ORM
+        user = await User.objects.aget(pk=user_id)
+        return user
+    except (User.DoesNotExist, ValueError, TypeError):
+        return None
+
+
+def extract_user_id_from_context(request: Dict[str, Any]) -> Optional[str]:
+    """
+    Extract user_id from request context.
+
+    Args:
+        request: Request dictionary with context
+
+    Returns:
+        User ID as string or None if not present
+
+    Example:
+        ```python
+        @api.get("/data")
+        async def get_data(request: dict):
+            user_id = extract_user_id_from_context(request)
+            if user_id:
+                # Use user_id for filtering, logging, etc.
+                data = await MyModel.objects.filter(user_id=user_id).all()
+                return {"data": data}
+            return {"error": "Not authenticated"}
+        ```
+    """
+    context = request.get("context", {})
+    return context.get("user_id")
+
+
+def get_auth_context(request: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Get the full authentication context from request.
+
+    Args:
+        request: Request dictionary with context
+
+    Returns:
+        Authentication context dictionary containing:
+        - user_id: User identifier
+        - is_staff: Staff status boolean
+        - is_admin: Admin/superuser status boolean
+        - auth_backend: Authentication backend used (jwt, api_key, etc.)
+        - permissions: List of permissions (if available)
+        - auth_claims: JWT claims dict (if JWT auth was used)
+
+    Example:
+        ```python
+        @api.get("/admin/stats")
+        async def admin_stats(request: dict):
+            auth_ctx = get_auth_context(request)
+
+            if not auth_ctx.get("is_admin"):
+                return {"error": "Admin access required"}
+
+            # Use user_id for audit logging
+            user_id = auth_ctx["user_id"]
+            backend = auth_ctx["auth_backend"]
+
+            return {
+                "authenticated_as": user_id,
+                "via": backend,
+                "stats": {...}
+            }
+        ```
+    """
+    return request.get("context", {})