django-clerk-users 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

django_clerk_users/__init__.py

@@ -1,22 +1,93 @@
+"""
+django-clerk-users: Integrate Clerk authentication with Django.
+"""
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("django-clerk-users")
 except PackageNotFoundError:
-    # Package is not installed
     __version__ = "unknown"
 
+# Re-export default app config
+default_app_config = "django_clerk_users.apps.DjangoClerkUsersConfig"
+
 
-def __getattr__(name):
+def __getattr__(name: str):
     """Lazy import to avoid loading Django models before apps are ready."""
-    if name == "hello_world":
-        from django_clerk_users.main import hello_world
+    # Models
+    if name == "AbstractClerkUser":
+        from django_clerk_users.models import AbstractClerkUser
+
+        return AbstractClerkUser
+    if name == "ClerkUser":
+        from django_clerk_users.models import ClerkUser
+
+        return ClerkUser
+    if name == "ClerkUserManager":
+        from django_clerk_users.models import ClerkUserManager
+
+        return ClerkUserManager
+
+    # Client
+    if name == "get_clerk_client":
+        from django_clerk_users.client import get_clerk_client
+
+        return get_clerk_client
+
+    # Exceptions
+    if name in (
+        "ClerkError",
+        "ClerkConfigurationError",
+        "ClerkAuthenticationError",
+        "ClerkTokenError",
+        "ClerkWebhookError",
+        "ClerkAPIError",
+        "ClerkUserNotFoundError",
+        "ClerkOrganizationNotFoundError",
+    ):
+        from django_clerk_users import exceptions
+
+        return getattr(exceptions, name)
+
+    # Testing utilities
+    if name in (
+        "ClerkTestClient",
+        "ClerkTestMixin",
+        "TestUserData",
+        "make_test_email",
+        "make_test_phone",
+        "TEST_OTP_CODE",
+    ):
+        from django_clerk_users import testing
+
+        return getattr(testing, name)
 
-        return hello_world
-    raise AttributeError(f"Module 'django_clerk' has no attribute '{name}'")
+    raise AttributeError(f"Module 'django_clerk_users' has no attribute '{name}'")
 
 
 __all__ = [
     "__version__",
-    "hello_world",
+    # Models
+    "AbstractClerkUser",
+    "ClerkUser",
+    "ClerkUserManager",
+    # Client
+    "get_clerk_client",
+    # Exceptions
+    "ClerkError",
+    "ClerkConfigurationError",
+    "ClerkAuthenticationError",
+    "ClerkTokenError",
+    "ClerkWebhookError",
+    "ClerkAPIError",
+    "ClerkUserNotFoundError",
+    "ClerkOrganizationNotFoundError",
+    # Testing utilities
+    "ClerkTestClient",
+    "ClerkTestMixin",
+    "TestUserData",
+    "make_test_email",
+    "make_test_phone",
+    "TEST_OTP_CODE",
 ]

django_clerk_users/apps.py

@@ -0,0 +1,20 @@
+from django.apps import AppConfig
+
+
+class DjangoClerkUsersConfig(AppConfig):
+    name = "django_clerk_users"
+    verbose_name = "Django Clerk Users"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import checks to register them with Django
+        from django_clerk_users import checks  # noqa: F401
+
+        # Disconnect Django's update_last_login signal
+        # Clerk manages authentication externally
+        from django.contrib.auth import get_user_model
+        from django.contrib.auth.models import update_last_login
+        from django.contrib.auth.signals import user_logged_in
+
+        User = get_user_model()
+        user_logged_in.disconnect(update_last_login, sender=User)

django_clerk_users/authentication/__init__.py

@@ -0,0 +1,24 @@
+"""
+Authentication backends and utilities for django-clerk-users.
+"""
+
+from django_clerk_users.authentication.backends import ClerkBackend
+from django_clerk_users.authentication.utils import (
+    get_clerk_payload_from_request,
+    get_or_create_user_from_payload,
+)
+
+__all__ = [
+    "ClerkBackend",
+    "get_clerk_payload_from_request",
+    "get_or_create_user_from_payload",
+]
+
+# Conditionally export DRF authentication if available
+try:
+    from django_clerk_users.authentication.drf import ClerkAuthentication
+
+    __all__.append("ClerkAuthentication")
+except ImportError:
+    # DRF is not installed
+    pass

django_clerk_users/authentication/backends.py

@@ -0,0 +1,89 @@
+"""
+Django authentication backend for Clerk.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from django.contrib.auth import get_user_model
+from django.contrib.auth.backends import BaseBackend
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
+    from django_clerk_users.models import AbstractClerkUser
+
+logger = logging.getLogger(__name__)
+
+
+class ClerkBackend(BaseBackend):
+    """
+    Django authentication backend for Clerk.
+
+    This backend authenticates users by their Clerk ID rather than
+    username/password. It's designed to work with Clerk's JWT-based
+    authentication.
+
+    To use this backend, add it to AUTHENTICATION_BACKENDS in settings:
+
+        AUTHENTICATION_BACKENDS = [
+            'django_clerk_users.authentication.ClerkBackend',
+        ]
+    """
+
+    def authenticate(
+        self,
+        request: "HttpRequest | None" = None,
+        clerk_id: str | None = None,
+        **kwargs: Any,
+    ) -> "AbstractClerkUser | None":
+        """
+        Authenticate a user by their Clerk ID.
+
+        Args:
+            request: The current HTTP request (optional).
+            clerk_id: The Clerk user ID to authenticate.
+            **kwargs: Additional keyword arguments (ignored).
+
+        Returns:
+            The authenticated user or None if authentication fails.
+        """
+        if not clerk_id:
+            return None
+
+        User = get_user_model()
+
+        try:
+            user = User.objects.get(clerk_id=clerk_id)
+            if user.is_active:
+                return user
+            logger.debug(f"User {clerk_id} is inactive")
+            return None
+        except User.DoesNotExist:
+            logger.debug(f"No user found with clerk_id: {clerk_id}")
+            return None
+
+    def get_user(self, user_id: int) -> "AbstractClerkUser | None":
+        """
+        Get a user by their Django primary key.
+
+        This method is called by Django's authentication middleware
+        to restore the user from the session.
+
+        Args:
+            user_id: The user's primary key.
+
+        Returns:
+            The user instance or None if not found.
+        """
+        User = get_user_model()
+
+        try:
+            user = User.objects.get(pk=user_id)
+            if user.is_active:
+                return user
+            return None
+        except User.DoesNotExist:
+            return None

django_clerk_users/authentication/drf.py

@@ -0,0 +1,111 @@
+"""
+Django REST Framework authentication class for Clerk.
+
+This module requires djangorestframework to be installed.
+Install it with: pip install django-clerk-users[drf]
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
+    from django_clerk_users.models import AbstractClerkUser
+
+from django_clerk_users.authentication.utils import (
+    get_clerk_payload_from_request,
+    get_or_create_user_from_payload,
+)
+from django_clerk_users.exceptions import ClerkAuthenticationError, ClerkTokenError
+
+logger = logging.getLogger(__name__)
+
+# Defer DRF import - check at class instantiation time
+_drf_available = False
+_drf_import_error: str | None = None
+
+try:
+    from rest_framework import authentication, exceptions
+
+    _drf_available = True
+    _BaseAuthentication: Any = authentication.BaseAuthentication
+except ImportError:
+    _drf_import_error = (
+        "Django REST Framework is required for ClerkAuthentication. "
+        "Install it with: pip install django-clerk-users[drf]"
+    )
+    _BaseAuthentication = object
+
+
+class ClerkAuthentication(_BaseAuthentication):
+    """
+    Django REST Framework authentication class for Clerk.
+
+    This authentication class validates Clerk JWT tokens and returns
+    the corresponding Django user.
+
+    To use this class, add it to DEFAULT_AUTHENTICATION_CLASSES in settings:
+
+        REST_FRAMEWORK = {
+            'DEFAULT_AUTHENTICATION_CLASSES': [
+                'django_clerk_users.authentication.ClerkAuthentication',
+            ],
+        }
+    """
+
+    def __init__(self) -> None:
+        if not _drf_available:
+            raise ImportError(_drf_import_error)
+        super().__init__()
+
+    def authenticate(
+        self, request: "HttpRequest"
+    ) -> tuple["AbstractClerkUser", dict] | None:
+        """
+        Authenticate the request and return a tuple of (user, auth).
+
+        Args:
+            request: The incoming HTTP request.
+
+        Returns:
+            A tuple of (user, payload) if authentication succeeds,
+            or None if no authentication credentials were provided.
+
+        Raises:
+            AuthenticationFailed: If authentication fails.
+        """
+        try:
+            payload = get_clerk_payload_from_request(request)
+        except ClerkTokenError as e:
+            raise exceptions.AuthenticationFailed(str(e))
+
+        if payload is None:
+            return None
+
+        try:
+            user, _ = get_or_create_user_from_payload(payload)
+        except ClerkAuthenticationError as e:
+            raise exceptions.AuthenticationFailed(str(e))
+
+        if not user.is_active:
+            raise exceptions.AuthenticationFailed("User is inactive.")
+
+        # Attach the Clerk payload to the request for later use
+        request.clerk_payload = payload  # type: ignore
+
+        return (user, payload)
+
+    def authenticate_header(self, request: "HttpRequest") -> str:
+        """
+        Return a string to be used as the WWW-Authenticate header.
+
+        Args:
+            request: The incoming HTTP request.
+
+        Returns:
+            The authentication scheme identifier.
+        """
+        return "Bearer"

django_clerk_users/authentication/utils.py

@@ -0,0 +1,171 @@
+"""
+Authentication utilities for JWT token validation and user retrieval.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+from clerk_backend_api.security.types import AuthenticateRequestOptions
+from django.core.cache import cache
+
+from django_clerk_users.client import get_clerk_client
+from django_clerk_users.exceptions import ClerkAuthenticationError, ClerkTokenError
+from django_clerk_users.settings import CLERK_AUTH_PARTIES, CLERK_CACHE_TIMEOUT
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
+    from django_clerk_users.models import AbstractClerkUser
+
+logger = logging.getLogger(__name__)
+
+
+def get_bearer_token(request: "HttpRequest") -> str | None:
+    """
+    Extract the Bearer token from the Authorization header.
+
+    Args:
+        request: The Django HTTP request.
+
+    Returns:
+        The bearer token string or None if not present.
+    """
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return auth_header[7:]  # Remove "Bearer " prefix
+    return None
+
+
+def get_clerk_payload_from_request(request: "HttpRequest") -> dict[str, Any] | None:
+    """
+    Validate a Clerk JWT token and return the payload.
+
+    This function extracts the JWT from the Authorization header,
+    validates it using the Clerk SDK, and returns the decoded payload.
+    Results are cached to avoid repeated validation.
+
+    Args:
+        request: The Django HTTP request.
+
+    Returns:
+        The decoded JWT payload dict or None if validation fails.
+
+    Raises:
+        ClerkTokenError: If the token is invalid or expired.
+    """
+    token = get_bearer_token(request)
+    if not token:
+        return None
+
+    # Create a cache key based on the token hash (never store raw tokens)
+    token_hash = hashlib.sha256(token.encode()).hexdigest()
+    cache_key = f"clerk:payload:{token_hash}"
+
+    # Check cache first
+    cached_payload = cache.get(cache_key)
+    if cached_payload is not None:
+        return cached_payload
+
+    try:
+        clerk = get_clerk_client()
+
+        # Build auth options with authorized parties
+        auth_options = None
+        if CLERK_AUTH_PARTIES:
+            auth_options = AuthenticateRequestOptions(
+                authorized_parties=CLERK_AUTH_PARTIES
+            )
+
+        # Validate the token using Clerk SDK
+        request_state = clerk.authenticate_request(request, options=auth_options)
+
+        if not request_state.is_signed_in:
+            logger.debug("Clerk token validation failed: not signed in")
+            return None
+
+        payload = request_state.payload
+        if not payload:
+            logger.debug("Clerk token validation failed: no payload")
+            return None
+
+        # Calculate cache timeout based on token expiration
+        # This ensures we never use an expired token from cache
+        exp = payload.get("exp")
+        if exp:
+            current_time = int(time.time())
+            # Cache until 1 minute before expiration, with a minimum of 60s
+            # and maximum of CLERK_CACHE_TIMEOUT (default 5 minutes)
+            time_until_exp = exp - current_time
+            cache_timeout = max(60, min(time_until_exp - 60, CLERK_CACHE_TIMEOUT))
+        else:
+            # Default to cache timeout if no exp claim
+            cache_timeout = CLERK_CACHE_TIMEOUT
+
+        cache.set(cache_key, payload, timeout=cache_timeout)
+        logger.debug(f"Cached Clerk payload for {cache_timeout} seconds")
+
+        return payload
+
+    except Exception as e:
+        logger.warning(f"Clerk token validation error: {e}")
+        raise ClerkTokenError(f"Token validation failed: {e}") from e
+
+
+def get_or_create_user_from_payload(
+    payload: dict[str, Any],
+) -> tuple["AbstractClerkUser", bool]:
+    """
+    Get or create a Django user from a Clerk JWT payload.
+
+    Args:
+        payload: The decoded Clerk JWT payload.
+
+    Returns:
+        A tuple of (user, created) where created is True if the user was newly created.
+
+    Raises:
+        ClerkAuthenticationError: If the payload is invalid or user creation fails.
+    """
+    from django.contrib.auth import get_user_model
+
+    User = get_user_model()
+
+    clerk_user_id = payload.get("sub")
+    if not clerk_user_id:
+        raise ClerkAuthenticationError("Invalid payload: missing 'sub' claim")
+
+    # Try to get existing user first
+    user = User.objects.filter(clerk_id=clerk_user_id).first()
+    if user:
+        return user, False
+
+    # User doesn't exist - we need to create them
+    # Fetch full user data from Clerk API
+    try:
+        from django_clerk_users.utils import update_or_create_clerk_user
+
+        user, created = update_or_create_clerk_user(clerk_user_id)
+        return user, created
+    except Exception as e:
+        logger.error(f"Failed to create user from Clerk: {e}")
+        raise ClerkAuthenticationError(f"Failed to create user: {e}") from e
+
+
+def get_user_from_clerk_id(clerk_id: str) -> "AbstractClerkUser | None":
+    """
+    Get a Django user by their Clerk ID.
+
+    Args:
+        clerk_id: The Clerk user ID.
+
+    Returns:
+        The user instance or None if not found.
+    """
+    from django.contrib.auth import get_user_model
+
+    User = get_user_model()
+    return User.objects.filter(clerk_id=clerk_id).first()

django_clerk_users/caching.py

@@ -0,0 +1,161 @@
+"""
+Caching utilities for django-clerk-users.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from django.core.cache import cache
+
+from django_clerk_users.settings import CLERK_CACHE_TIMEOUT, CLERK_ORG_CACHE_TIMEOUT
+
+if TYPE_CHECKING:
+    from django_clerk_users.models import AbstractClerkUser
+
+logger = logging.getLogger(__name__)
+
+
+# Cache key prefixes
+USER_CACHE_PREFIX = "clerk:user:"
+ORG_CACHE_PREFIX = "clerk:org:"
+
+
+def get_user_cache_key(clerk_id: str) -> str:
+    """Get the cache key for a user."""
+    return f"{USER_CACHE_PREFIX}{clerk_id}"
+
+
+def get_org_cache_key(clerk_id: str) -> str:
+    """Get the cache key for an organization."""
+    return f"{ORG_CACHE_PREFIX}{clerk_id}"
+
+
+def get_cached_user(clerk_id: str, query_db: bool = True) -> "AbstractClerkUser | None":
+    """
+    Get a user from cache or database.
+
+    Args:
+        clerk_id: The Clerk user ID.
+        query_db: If True, query database on cache miss and cache the result.
+
+    Returns:
+        The user instance, or None if not found.
+    """
+    from django.contrib.auth import get_user_model
+
+    if not clerk_id:
+        return None
+
+    cache_key = get_user_cache_key(clerk_id)
+    cached_user = cache.get(cache_key)
+
+    if cached_user is not None:
+        # Cache hit - could be a User instance or False (cached "not found")
+        return cached_user if cached_user is not False else None
+
+    if not query_db:
+        return None
+
+    # Cache miss - query database
+    User = get_user_model()
+    try:
+        user = User.objects.get(clerk_id=clerk_id, is_active=True)
+        # Cache the user instance
+        cache.set(cache_key, user, timeout=CLERK_CACHE_TIMEOUT)
+        return user
+    except User.DoesNotExist:
+        # Cache the "not found" result to prevent repeated DB queries
+        cache.set(cache_key, False, timeout=CLERK_CACHE_TIMEOUT)
+        return None
+
+
+def set_cached_user(clerk_id: str, user: "AbstractClerkUser | None") -> None:
+    """
+    Cache a user by Clerk ID.
+
+    Args:
+        clerk_id: The Clerk user ID.
+        user: The user to cache, or None to cache "not found".
+    """
+    cache_key = get_user_cache_key(clerk_id)
+    # Cache False for "not found" to distinguish from "not cached"
+    value = user if user is not None else False
+    cache.set(cache_key, value, timeout=CLERK_CACHE_TIMEOUT)
+
+
+def invalidate_clerk_user_cache(clerk_id: str) -> None:
+    """
+    Invalidate the cache for a user.
+
+    Args:
+        clerk_id: The Clerk user ID.
+    """
+    cache_key = get_user_cache_key(clerk_id)
+    cache.delete(cache_key)
+    logger.debug(f"Invalidated user cache: {clerk_id}")
+
+
+def get_cached_organization(clerk_id: str, query_db: bool = True):
+    """
+    Get an organization from cache or database.
+
+    Args:
+        clerk_id: The Clerk organization ID.
+        query_db: If True, query database on cache miss and cache the result.
+
+    Returns:
+        The organization instance, or None if not found.
+    """
+    if not clerk_id:
+        return None
+
+    cache_key = get_org_cache_key(clerk_id)
+    cached_org = cache.get(cache_key)
+
+    if cached_org is not None:
+        # Cache hit - could be an Organization instance or False (cached "not found")
+        return cached_org if cached_org is not False else None
+
+    if not query_db:
+        return None
+
+    # Cache miss - query database
+    try:
+        from django_clerk_users.organizations.models import Organization
+
+        org = Organization.objects.get(clerk_id=clerk_id, is_active=True)
+        # Cache the organization instance
+        cache.set(cache_key, org, timeout=CLERK_ORG_CACHE_TIMEOUT)
+        return org
+    except Exception:
+        # Cache the "not found" result to prevent repeated DB queries
+        cache.set(cache_key, False, timeout=CLERK_ORG_CACHE_TIMEOUT)
+        return None
+
+
+def set_cached_organization(clerk_id: str, organization) -> None:
+    """
+    Cache an organization by Clerk ID.
+
+    Args:
+        clerk_id: The Clerk organization ID.
+        organization: The organization to cache, or None to cache "not found".
+    """
+    cache_key = get_org_cache_key(clerk_id)
+    # Cache False for "not found" to distinguish from "not cached"
+    value = organization if organization is not None else False
+    cache.set(cache_key, value, timeout=CLERK_ORG_CACHE_TIMEOUT)
+
+
+def invalidate_organization_cache(clerk_id: str) -> None:
+    """
+    Invalidate the cache for an organization.
+
+    Args:
+        clerk_id: The Clerk organization ID.
+    """
+    cache_key = get_org_cache_key(clerk_id)
+    cache.delete(cache_key)
+    logger.debug(f"Invalidated organization cache: {clerk_id}")