django-clerk-users 0.0.1__tar.gz → 0.0.2__tar.gz

django_clerk_users-0.0.2/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: django-clerk-users
+Version: 0.0.2
+Summary: Integrate Clerk with Django
+Project-URL: Changelog, https://github.com/jmitchel3/django-clerk-users
+Project-URL: Documentation, https://github.com/jmitchel3/django-clerk-users
+Project-URL: Funding, https://github.com/jmitchel3/django-clerk-users
+Project-URL: Repository, https://github.com/jmitchel3/django-clerk-users
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.2
+Requires-Dist: clerk-backend-api>=1.0.0
+Requires-Dist: svix>=1.0.0
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == "drf"
+Dynamic: license-file
+
+# Django Clerk Users
+
+Integrate [Clerk](https://clerk.com) authentication with Django.
+
+> **Note:** This package is in early development (v0.0.2). APIs may change.
+
+## Features
+
+- Custom user model (`ClerkUser`) with Clerk integration
+- JWT token validation via Clerk SDK
+- Session-based authentication middleware (validates once, caches in session)
+- Webhook handling with Svix signature verification
+- Optional organizations support (separate sub-app)
+- Django REST Framework authentication (optional)
+
+## Installation
+
+```bash
+pip install django-clerk-users
+```
+
+For Django REST Framework support:
+
+```bash
+pip install django-clerk-users[drf]
+```
+
+## Quick Start
+
+### 1. Add to installed apps
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_clerk_users",
+    # Optional: for organization support
+    # "django_clerk_users.organizations",
+]
+```
+
+### 2. Configure settings
+
+```python
+# Required
+CLERK_SECRET_KEY = "sk_live_..."  # From Clerk Dashboard
+CLERK_WEBHOOK_SIGNING_KEY = "whsec_..."  # From Clerk Webhooks
+CLERK_FRONTEND_HOSTS = ["https://your-app.com"]  # Your frontend URLs
+
+# Optional
+CLERK_SESSION_REVALIDATION_SECONDS = 300  # Re-validate JWT every 5 minutes
+CLERK_CACHE_TIMEOUT = 300  # Cache timeout for user lookups
+```
+
+### 3. Set the user model
+
+```python
+AUTH_USER_MODEL = "django_clerk_users.ClerkUser"
+```
+
+Or extend the abstract model for custom fields:
+
+```python
+# myapp/models.py
+from django_clerk_users.models import AbstractClerkUser
+
+class CustomUser(AbstractClerkUser):
+    company = models.CharField(max_length=255, blank=True)
+
+    class Meta(AbstractClerkUser.Meta):
+        swappable = "AUTH_USER_MODEL"
+
+# settings.py
+AUTH_USER_MODEL = "myapp.CustomUser"
+```
+
+### 4. Add middleware
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django_clerk_users.middleware.ClerkAuthMiddleware",  # Add after AuthenticationMiddleware
+    # ...
+]
+```
+
+### 5. Add authentication backend
+
+```python
+AUTHENTICATION_BACKENDS = [
+    "django_clerk_users.authentication.ClerkBackend",
+]
+```
+
+### 6. Run migrations
+
+```bash
+python manage.py migrate
+```
+
+### 7. Configure webhooks
+
+Add the webhook URL to your `urls.py`:
+
+```python
+from django_clerk_users.webhooks import clerk_webhook_view
+
+urlpatterns = [
+    # ...
+    path("webhooks/clerk/", clerk_webhook_view, name="clerk_webhook"),
+]
+```
+
+Then configure your Clerk Dashboard to send webhooks to `https://your-app.com/webhooks/clerk/`.
+
+## Usage
+
+### Accessing the user in views
+
+```python
+def my_view(request):
+    if request.user.is_authenticated:
+        # Access Clerk user attributes
+        print(request.user.clerk_id)
+        print(request.user.email)
+        print(request.user.full_name)
+
+        # Access organization (if using organizations)
+        print(request.org)  # Organization ID from JWT
+```
+
+### Decorators
+
+```python
+from django_clerk_users.decorators import clerk_user_required
+
+@clerk_user_required
+def protected_view(request):
+    # Only authenticated Clerk users can access
+    return HttpResponse(f"Hello, {request.user.email}")
+```
+
+### Django REST Framework
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "django_clerk_users.authentication.ClerkAuthentication",
+    ],
+}
+```
+
+## Organizations (Optional)
+
+For Clerk organization support:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "django_clerk_users",
+    "django_clerk_users.organizations",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_clerk_users.middleware.ClerkAuthMiddleware",
+    "django_clerk_users.organizations.middleware.ClerkOrganizationMiddleware",
+]
+```
+
+## Management Commands
+
+```bash
+# Sync users from Clerk
+python manage.py sync_clerk_users
+
+# Sync organizations from Clerk
+python manage.py sync_clerk_organizations
+```
+
+## Configuration Reference
+
+| Setting | Required | Default | Description |
+|---------|----------|---------|-------------|
+| `CLERK_SECRET_KEY` | Yes | - | Your Clerk secret key |
+| `CLERK_WEBHOOK_SIGNING_KEY` | Yes* | - | Webhook signing secret (*required for webhooks) |
+| `CLERK_FRONTEND_HOSTS` | Yes | `[]` | Authorized frontend URLs |
+| `CLERK_SESSION_REVALIDATION_SECONDS` | No | `300` | JWT revalidation interval |
+| `CLERK_CACHE_TIMEOUT` | No | `300` | User cache timeout |
+| `CLERK_ORG_CACHE_TIMEOUT` | No | `900` | Organization cache timeout |
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR on [GitHub](https://github.com/jmitchel3/django-clerk-users).

django_clerk_users-0.0.2/README.md

@@ -0,0 +1,203 @@
+# Django Clerk Users
+
+Integrate [Clerk](https://clerk.com) authentication with Django.
+
+> **Note:** This package is in early development (v0.0.2). APIs may change.
+
+## Features
+
+- Custom user model (`ClerkUser`) with Clerk integration
+- JWT token validation via Clerk SDK
+- Session-based authentication middleware (validates once, caches in session)
+- Webhook handling with Svix signature verification
+- Optional organizations support (separate sub-app)
+- Django REST Framework authentication (optional)
+
+## Installation
+
+```bash
+pip install django-clerk-users
+```
+
+For Django REST Framework support:
+
+```bash
+pip install django-clerk-users[drf]
+```
+
+## Quick Start
+
+### 1. Add to installed apps
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_clerk_users",
+    # Optional: for organization support
+    # "django_clerk_users.organizations",
+]
+```
+
+### 2. Configure settings
+
+```python
+# Required
+CLERK_SECRET_KEY = "sk_live_..."  # From Clerk Dashboard
+CLERK_WEBHOOK_SIGNING_KEY = "whsec_..."  # From Clerk Webhooks
+CLERK_FRONTEND_HOSTS = ["https://your-app.com"]  # Your frontend URLs
+
+# Optional
+CLERK_SESSION_REVALIDATION_SECONDS = 300  # Re-validate JWT every 5 minutes
+CLERK_CACHE_TIMEOUT = 300  # Cache timeout for user lookups
+```
+
+### 3. Set the user model
+
+```python
+AUTH_USER_MODEL = "django_clerk_users.ClerkUser"
+```
+
+Or extend the abstract model for custom fields:
+
+```python
+# myapp/models.py
+from django_clerk_users.models import AbstractClerkUser
+
+class CustomUser(AbstractClerkUser):
+    company = models.CharField(max_length=255, blank=True)
+
+    class Meta(AbstractClerkUser.Meta):
+        swappable = "AUTH_USER_MODEL"
+
+# settings.py
+AUTH_USER_MODEL = "myapp.CustomUser"
+```
+
+### 4. Add middleware
+
+```python
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django_clerk_users.middleware.ClerkAuthMiddleware",  # Add after AuthenticationMiddleware
+    # ...
+]
+```
+
+### 5. Add authentication backend
+
+```python
+AUTHENTICATION_BACKENDS = [
+    "django_clerk_users.authentication.ClerkBackend",
+]
+```
+
+### 6. Run migrations
+
+```bash
+python manage.py migrate
+```
+
+### 7. Configure webhooks
+
+Add the webhook URL to your `urls.py`:
+
+```python
+from django_clerk_users.webhooks import clerk_webhook_view
+
+urlpatterns = [
+    # ...
+    path("webhooks/clerk/", clerk_webhook_view, name="clerk_webhook"),
+]
+```
+
+Then configure your Clerk Dashboard to send webhooks to `https://your-app.com/webhooks/clerk/`.
+
+## Usage
+
+### Accessing the user in views
+
+```python
+def my_view(request):
+    if request.user.is_authenticated:
+        # Access Clerk user attributes
+        print(request.user.clerk_id)
+        print(request.user.email)
+        print(request.user.full_name)
+
+        # Access organization (if using organizations)
+        print(request.org)  # Organization ID from JWT
+```
+
+### Decorators
+
+```python
+from django_clerk_users.decorators import clerk_user_required
+
+@clerk_user_required
+def protected_view(request):
+    # Only authenticated Clerk users can access
+    return HttpResponse(f"Hello, {request.user.email}")
+```
+
+### Django REST Framework
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "django_clerk_users.authentication.ClerkAuthentication",
+    ],
+}
+```
+
+## Organizations (Optional)
+
+For Clerk organization support:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "django_clerk_users",
+    "django_clerk_users.organizations",
+]
+
+MIDDLEWARE = [
+    # ...
+    "django_clerk_users.middleware.ClerkAuthMiddleware",
+    "django_clerk_users.organizations.middleware.ClerkOrganizationMiddleware",
+]
+```
+
+## Management Commands
+
+```bash
+# Sync users from Clerk
+python manage.py sync_clerk_users
+
+# Sync organizations from Clerk
+python manage.py sync_clerk_organizations
+```
+
+## Configuration Reference
+
+| Setting | Required | Default | Description |
+|---------|----------|---------|-------------|
+| `CLERK_SECRET_KEY` | Yes | - | Your Clerk secret key |
+| `CLERK_WEBHOOK_SIGNING_KEY` | Yes* | - | Webhook signing secret (*required for webhooks) |
+| `CLERK_FRONTEND_HOSTS` | Yes | `[]` | Authorized frontend URLs |
+| `CLERK_SESSION_REVALIDATION_SECONDS` | No | `300` | JWT revalidation interval |
+| `CLERK_CACHE_TIMEOUT` | No | `300` | User cache timeout |
+| `CLERK_ORG_CACHE_TIMEOUT` | No | `900` | Organization cache timeout |
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR on [GitHub](https://github.com/jmitchel3/django-clerk-users).

{django_clerk_users-0.0.1 → django_clerk_users-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-clerk-users"
-version = "0.0.1"
+version = "0.0.2"
 description = "Integrate Clerk with Django"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -15,19 +15,26 @@ classifiers = [
 ]
 dependencies = [
     "django>=4.2",
+    "clerk-backend-api>=1.0.0",
+    "svix>=1.0.0",
 ]
 
+[project.optional-dependencies]
+drf = ["djangorestframework>=3.14"]
 
-urls.Changelog = "https://github.com/jmitchel3/django-clerk-users"
-urls.Documentation = "https://github.com/jmitchel3/django-clerk-users"
-urls.Funding = "https://github.com/jmitchel3/django-clerk-users"
-urls.Repository = "https://github.com/jmitchel3/django-clerk-users"
+
+[project.urls]
+Changelog = "https://github.com/jmitchel3/django-clerk-users"
+Documentation = "https://github.com/jmitchel3/django-clerk-users"
+Funding = "https://github.com/jmitchel3/django-clerk-users"
+Repository = "https://github.com/jmitchel3/django-clerk-users"
 
 [dependency-groups]
 dev = [
     "pip>=25.3",
     "pre-commit>=4.4.0",
     "pytest>=9.0.0",
+    "pytest-django>=4.9",
     "rav>=0.1.1",
     "tox>=4.32.0",
     "tox-uv>=1.29.0",

django_clerk_users-0.0.2/src/django_clerk_users/__init__.py

@@ -0,0 +1,93 @@
+"""
+django-clerk-users: Integrate Clerk authentication with Django.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("django-clerk-users")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# Re-export default app config
+default_app_config = "django_clerk_users.apps.DjangoClerkUsersConfig"
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid loading Django models before apps are ready."""
+    # 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)
+
+    raise AttributeError(f"Module 'django_clerk_users' has no attribute '{name}'")
+
+
+__all__ = [
+    "__version__",
+    # 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-0.0.2/src/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-0.0.2/src/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-0.0.2/src/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