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

django_clerk_users/checks.py

@@ -0,0 +1,127 @@
+"""
+Django system checks for django-clerk-users configuration.
+"""
+
+from django.conf import settings
+from django.core.checks import Error, Warning, register
+
+
+@register()
+def check_clerk_secret_key(app_configs, **kwargs):
+    """Check that CLERK_SECRET_KEY is configured."""
+    errors = []
+    if not getattr(settings, "CLERK_SECRET_KEY", None):
+        errors.append(
+            Error(
+                "CLERK_SECRET_KEY is not configured.",
+                hint="Set CLERK_SECRET_KEY in your Django settings.",
+                id="django_clerk_users.E001",
+            )
+        )
+    return errors
+
+
+@register()
+def check_clerk_webhook_signing_key(app_configs, **kwargs):
+    """Check that CLERK_WEBHOOK_SIGNING_KEY is configured."""
+    warnings = []
+    if not getattr(settings, "CLERK_WEBHOOK_SIGNING_KEY", None):
+        warnings.append(
+            Warning(
+                "CLERK_WEBHOOK_SIGNING_KEY is not configured.",
+                hint=(
+                    "Set CLERK_WEBHOOK_SIGNING_KEY in your Django settings "
+                    "if you plan to use Clerk webhooks."
+                ),
+                id="django_clerk_users.W001",
+            )
+        )
+    return warnings
+
+
+@register()
+def check_auth_user_model(app_configs, **kwargs):
+    """Check that AUTH_USER_MODEL is configured for Clerk."""
+    warnings = []
+    auth_user_model = getattr(settings, "AUTH_USER_MODEL", "auth.User")
+
+    # Check if using a Clerk-compatible user model
+    if not (
+        auth_user_model.startswith("django_clerk_users.")
+        or "clerk" in auth_user_model.lower()
+    ):
+        warnings.append(
+            Warning(
+                f"AUTH_USER_MODEL is set to '{auth_user_model}'.",
+                hint=(
+                    "Consider using 'django_clerk_users.ClerkUser' or a custom model "
+                    "that extends AbstractClerkUser for full Clerk integration."
+                ),
+                id="django_clerk_users.W002",
+            )
+        )
+    return warnings
+
+
+@register()
+def check_middleware_installed(app_configs, **kwargs):
+    """Check that ClerkAuthMiddleware is installed."""
+    warnings = []
+    middleware = getattr(settings, "MIDDLEWARE", [])
+
+    clerk_middleware = "django_clerk_users.middleware.ClerkAuthMiddleware"
+    if clerk_middleware not in middleware:
+        warnings.append(
+            Warning(
+                "ClerkAuthMiddleware is not in MIDDLEWARE.",
+                hint=(
+                    f"Add '{clerk_middleware}' to MIDDLEWARE in your Django settings "
+                    "for automatic Clerk authentication."
+                ),
+                id="django_clerk_users.W003",
+            )
+        )
+    return warnings
+
+
+@register()
+def check_authentication_backend(app_configs, **kwargs):
+    """Check that ClerkBackend is in AUTHENTICATION_BACKENDS."""
+    warnings = []
+    backends = getattr(settings, "AUTHENTICATION_BACKENDS", [])
+
+    clerk_backend = "django_clerk_users.authentication.ClerkBackend"
+    if clerk_backend not in backends:
+        warnings.append(
+            Warning(
+                "ClerkBackend is not in AUTHENTICATION_BACKENDS.",
+                hint=(
+                    f"Add '{clerk_backend}' to AUTHENTICATION_BACKENDS in your "
+                    "Django settings."
+                ),
+                id="django_clerk_users.W004",
+            )
+        )
+    return warnings
+
+
+@register()
+def check_frontend_hosts(app_configs, **kwargs):
+    """Check that CLERK_FRONTEND_HOSTS is configured."""
+    warnings = []
+    frontend_hosts = getattr(settings, "CLERK_FRONTEND_HOSTS", [])
+    auth_parties = getattr(settings, "CLERK_AUTH_PARTIES", [])
+
+    if not frontend_hosts and not auth_parties:
+        warnings.append(
+            Warning(
+                "CLERK_FRONTEND_HOSTS is not configured.",
+                hint=(
+                    "Set CLERK_FRONTEND_HOSTS in your Django settings to the list of "
+                    "frontend URLs that will be sending authenticated requests "
+                    "(e.g., ['https://myapp.com', 'http://localhost:3000'])."
+                ),
+                id="django_clerk_users.W005",
+            )
+        )
+    return warnings

django_clerk_users/client.py

@@ -0,0 +1,32 @@
+"""
+Clerk SDK client singleton.
+"""
+
+from functools import lru_cache
+
+from clerk_backend_api import Clerk
+
+from django_clerk_users.exceptions import ClerkConfigurationError
+from django_clerk_users.settings import CLERK_SECRET_KEY
+
+
+@lru_cache(maxsize=1)
+def get_clerk_client() -> Clerk:
+    """
+    Get the Clerk SDK client instance.
+
+    Returns a cached singleton instance of the Clerk client.
+
+    Raises:
+        ClerkConfigurationError: If CLERK_SECRET_KEY is not set.
+    """
+    if not CLERK_SECRET_KEY:
+        raise ClerkConfigurationError(
+            "CLERK_SECRET_KEY is not set. Please configure it in your Django settings."
+        )
+    return Clerk(bearer_auth=CLERK_SECRET_KEY)
+
+
+def get_clerk_sdk() -> Clerk:
+    """Alias for get_clerk_client() for compatibility."""
+    return get_clerk_client()

django_clerk_users/decorators.py

@@ -0,0 +1,181 @@
+"""
+View decorators for django-clerk-users.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Callable
+
+from django.http import JsonResponse
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+
+def clerk_user_required(view_func: Callable) -> Callable:
+    """
+    Decorator that requires a Clerk-authenticated user.
+
+    Use this decorator on views that require authentication.
+    Returns a 401 response if the user is not authenticated.
+
+    Example:
+        from django_clerk_users.decorators import clerk_user_required
+
+        @clerk_user_required
+        def my_protected_view(request):
+            user = request.clerk_user
+            return JsonResponse({"email": user.email})
+
+    Args:
+        view_func: The view function to wrap.
+
+    Returns:
+        The wrapped view function.
+    """
+
+    @functools.wraps(view_func)
+    def wrapper(request: "HttpRequest", *args, **kwargs) -> "HttpResponse":
+        clerk_user = getattr(request, "clerk_user", None)
+
+        if not clerk_user or not clerk_user.is_authenticated:
+            return JsonResponse(
+                {"error": "Authentication required"},
+                status=401,
+            )
+
+        return view_func(request, *args, **kwargs)
+
+    return wrapper
+
+
+def clerk_org_required(view_func: Callable) -> Callable:
+    """
+    Decorator that requires an organization context.
+
+    Use this decorator on views that require both authentication
+    and an organization context. Returns a 401 response if not
+    authenticated, or a 403 response if no organization is set.
+
+    Example:
+        from django_clerk_users.decorators import clerk_org_required
+
+        @clerk_org_required
+        def my_org_view(request):
+            org_id = request.org
+            return JsonResponse({"org_id": org_id})
+
+    Args:
+        view_func: The view function to wrap.
+
+    Returns:
+        The wrapped view function.
+    """
+
+    @functools.wraps(view_func)
+    def wrapper(request: "HttpRequest", *args, **kwargs) -> "HttpResponse":
+        clerk_user = getattr(request, "clerk_user", None)
+
+        if not clerk_user or not clerk_user.is_authenticated:
+            return JsonResponse(
+                {"error": "Authentication required"},
+                status=401,
+            )
+
+        org = getattr(request, "org", None)
+        if not org:
+            return JsonResponse(
+                {"error": "Organization context required"},
+                status=403,
+            )
+
+        return view_func(request, *args, **kwargs)
+
+    return wrapper
+
+
+def clerk_staff_required(view_func: Callable) -> Callable:
+    """
+    Decorator that requires a staff user.
+
+    Use this decorator on views that require staff access.
+    Returns a 401 response if not authenticated, or a 403 response
+    if the user is not staff.
+
+    Example:
+        from django_clerk_users.decorators import clerk_staff_required
+
+        @clerk_staff_required
+        def admin_view(request):
+            return JsonResponse({"message": "Staff access granted"})
+
+    Args:
+        view_func: The view function to wrap.
+
+    Returns:
+        The wrapped view function.
+    """
+
+    @functools.wraps(view_func)
+    def wrapper(request: "HttpRequest", *args, **kwargs) -> "HttpResponse":
+        clerk_user = getattr(request, "clerk_user", None)
+
+        if not clerk_user or not clerk_user.is_authenticated:
+            return JsonResponse(
+                {"error": "Authentication required"},
+                status=401,
+            )
+
+        if not clerk_user.is_staff:
+            return JsonResponse(
+                {"error": "Staff access required"},
+                status=403,
+            )
+
+        return view_func(request, *args, **kwargs)
+
+    return wrapper
+
+
+def clerk_superuser_required(view_func: Callable) -> Callable:
+    """
+    Decorator that requires a superuser.
+
+    Use this decorator on views that require superuser access.
+    Returns a 401 response if not authenticated, or a 403 response
+    if the user is not a superuser.
+
+    Example:
+        from django_clerk_users.decorators import clerk_superuser_required
+
+        @clerk_superuser_required
+        def superuser_view(request):
+            return JsonResponse({"message": "Superuser access granted"})
+
+    Args:
+        view_func: The view function to wrap.
+
+    Returns:
+        The wrapped view function.
+    """
+
+    @functools.wraps(view_func)
+    def wrapper(request: "HttpRequest", *args, **kwargs) -> "HttpResponse":
+        clerk_user = getattr(request, "clerk_user", None)
+
+        if not clerk_user or not clerk_user.is_authenticated:
+            return JsonResponse(
+                {"error": "Authentication required"},
+                status=401,
+            )
+
+        if not clerk_user.is_superuser:
+            return JsonResponse(
+                {"error": "Superuser access required"},
+                status=403,
+            )
+
+        return view_func(request, *args, **kwargs)
+
+    return wrapper

django_clerk_users/exceptions.py

@@ -0,0 +1,51 @@
+"""
+Custom exceptions for django-clerk-users.
+"""
+
+
+class ClerkError(Exception):
+    """Base exception for all Clerk-related errors."""
+
+    pass
+
+
+class ClerkConfigurationError(ClerkError):
+    """Raised when Clerk is not properly configured."""
+
+    pass
+
+
+class ClerkAuthenticationError(ClerkError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class ClerkTokenError(ClerkAuthenticationError):
+    """Raised when JWT token validation fails."""
+
+    pass
+
+
+class ClerkWebhookError(ClerkError):
+    """Raised when webhook verification fails."""
+
+    pass
+
+
+class ClerkAPIError(ClerkError):
+    """Raised when Clerk API returns an error."""
+
+    pass
+
+
+class ClerkUserNotFoundError(ClerkError):
+    """Raised when a Clerk user cannot be found."""
+
+    pass
+
+
+class ClerkOrganizationNotFoundError(ClerkError):
+    """Raised when a Clerk organization cannot be found."""
+
+    pass

django_clerk_users/management/commands/migrate_users_to_clerk.py

@@ -0,0 +1,223 @@
+"""
+Management command to migrate existing Django users to Clerk.
+
+This command creates users in Clerk from your existing Django user database,
+allowing you to migrate to Clerk authentication without losing user data.
+
+Note: Passwords cannot be migrated. Users will need to reset their password
+or use OAuth/social login.
+"""
+
+from datetime import datetime
+
+from django.apps import apps
+from django.core.management.base import BaseCommand, CommandError
+
+from django_clerk_users.client import get_clerk_client
+
+
+class Command(BaseCommand):
+    help = "Migrate existing Django users to Clerk"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--source-model",
+            type=str,
+            default="auth.User",
+            help="Source user model in app.Model format (default: auth.User)",
+        )
+        parser.add_argument(
+            "--email",
+            type=str,
+            help="Migrate a specific user by email address",
+        )
+        parser.add_argument(
+            "--all",
+            action="store_true",
+            help="Migrate all users",
+        )
+        parser.add_argument(
+            "--created-before",
+            type=str,
+            help="Migrate users created before this date (YYYY-MM-DD)",
+        )
+        parser.add_argument(
+            "--skip-existing",
+            action="store_true",
+            help="Skip users that already exist in Clerk (by email)",
+        )
+        parser.add_argument(
+            "--skip-password-email",
+            action="store_true",
+            default=True,
+            help="Don't trigger password reset emails (default: True)",
+        )
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Show what would be migrated without making changes",
+        )
+        parser.add_argument(
+            "--limit",
+            type=int,
+            default=100,
+            help="Limit number of users to migrate (default: 100)",
+        )
+
+    def handle(self, *args, **options):
+        # Get the source model
+        source_model_path = options["source_model"]
+        try:
+            app_label, model_name = source_model_path.split(".")
+            SourceUser = apps.get_model(app_label, model_name)
+        except (ValueError, LookupError) as e:
+            raise CommandError(f"Invalid source model '{source_model_path}': {e}")
+
+        email = options["email"]
+        migrate_all = options["all"]
+        created_before = options["created_before"]
+        skip_existing = options["skip_existing"]
+        skip_password_email = options["skip_password_email"]
+        dry_run = options["dry_run"]
+        limit = options["limit"]
+
+        if not email and not migrate_all and not created_before:
+            raise CommandError(
+                "You must specify --email, --all, or --created-before"
+            )
+
+        clerk = get_clerk_client()
+
+        # Build queryset
+        queryset = SourceUser.objects.all()
+
+        if email:
+            queryset = queryset.filter(email=email)
+        elif created_before:
+            try:
+                before_date = datetime.strptime(created_before, "%Y-%m-%d")
+                queryset = queryset.filter(date_joined__lt=before_date)
+            except ValueError:
+                raise CommandError(
+                    "Invalid date format. Use YYYY-MM-DD"
+                )
+
+        queryset = queryset[:limit]
+
+        created_count = 0
+        skipped_count = 0
+        error_count = 0
+        linked_count = 0
+        total_count = 0
+
+        self.stdout.write(f"Migrating users from {source_model_path}...")
+        self.stdout.write(f"Found {queryset.count()} users to process")
+
+        if dry_run:
+            self.stdout.write(self.style.WARNING("DRY RUN - No changes will be made"))
+
+        for source_user in queryset:
+            total_count += 1
+            user_email = getattr(source_user, "email", None)
+
+            if not user_email:
+                self.stderr.write(
+                    self.style.WARNING(f"  Skipping user {source_user.pk}: no email")
+                )
+                skipped_count += 1
+                continue
+
+            first_name = getattr(source_user, "first_name", "") or ""
+            last_name = getattr(source_user, "last_name", "") or ""
+
+            # Check if user exists in Clerk
+            if skip_existing:
+                try:
+                    existing_users = clerk.users.list(email_address=[user_email])
+                    users_data = existing_users.data if hasattr(existing_users, "data") else existing_users
+                    if users_data:
+                        if dry_run:
+                            self.stdout.write(
+                                f"  Would skip (exists in Clerk): {user_email}"
+                            )
+                        else:
+                            self.stdout.write(f"  Skipping (exists in Clerk): {user_email}")
+                            # Try to link the user
+                            clerk_user = users_data[0]
+                            self._link_user(source_user, clerk_user)
+                            linked_count += 1
+                        skipped_count += 1
+                        continue
+                except Exception as e:
+                    self.stderr.write(
+                        self.style.WARNING(f"  Error checking if {user_email} exists: {e}")
+                    )
+
+            if dry_run:
+                self.stdout.write(f"  Would create: {user_email}")
+                continue
+
+            # Create user in Clerk
+            try:
+                clerk_user = clerk.users.create(
+                    email_address=[user_email],
+                    first_name=first_name if first_name else None,
+                    last_name=last_name if last_name else None,
+                    skip_password_requirement=True,
+                    skip_password_checks=True,
+                )
+
+                # Link Django user to Clerk
+                self._link_user(source_user, clerk_user)
+
+                created_count += 1
+                self.stdout.write(
+                    self.style.SUCCESS(f"  Created: {user_email}")
+                )
+
+            except Exception as e:
+                error_str = str(e)
+                if "email_address" in error_str.lower() and "taken" in error_str.lower():
+                    self.stdout.write(
+                        self.style.WARNING(f"  Email already exists in Clerk: {user_email}")
+                    )
+                    skipped_count += 1
+                else:
+                    error_count += 1
+                    self.stderr.write(
+                        self.style.ERROR(f"  Failed to create {user_email}: {e}")
+                    )
+
+        self.stdout.write("")
+        self.stdout.write(self.style.SUCCESS("Migration complete!"))
+        self.stdout.write(f"  Total processed: {total_count}")
+        if not dry_run:
+            self.stdout.write(f"  Created in Clerk: {created_count}")
+            self.stdout.write(f"  Linked existing: {linked_count}")
+        self.stdout.write(f"  Skipped: {skipped_count}")
+        self.stdout.write(f"  Errors: {error_count}")
+
+        if not dry_run and created_count > 0:
+            self.stdout.write("")
+            self.stdout.write(
+                self.style.WARNING(
+                    "Note: Migrated users will need to reset their password "
+                    "or use OAuth to sign in."
+                )
+            )
+
+    def _link_user(self, source_user, clerk_user):
+        """
+        Link a Django user to their Clerk user.
+
+        If the source user has a clerk_id field, update it.
+        """
+        clerk_id = getattr(clerk_user, "id", None)
+        if not clerk_id:
+            return
+
+        # Check if source user has clerk_id field
+        if hasattr(source_user, "clerk_id"):
+            source_user.clerk_id = clerk_id
+            source_user.save(update_fields=["clerk_id"])
+            self.stdout.write(f"    Linked clerk_id: {clerk_id}")