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

django_clerk_users/webhooks/handlers.py

@@ -0,0 +1,346 @@
+"""
+Webhook event handlers for Clerk.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from django.core.cache import cache
+from django.db import transaction
+
+from django_clerk_users.settings import CLERK_WEBHOOK_DEDUP_TIMEOUT
+from django_clerk_users.webhooks.signals import (
+    clerk_session_created,
+    clerk_session_ended,
+    clerk_user_created,
+    clerk_user_deleted,
+    clerk_user_updated,
+)
+
+if TYPE_CHECKING:
+    from django_clerk_users.models import AbstractClerkUser
+
+logger = logging.getLogger(__name__)
+
+
+def parse_clerk_timestamp(timestamp: int | str | datetime | None) -> datetime | None:
+    """
+    Parse a Clerk timestamp into a datetime object.
+
+    Clerk can send timestamps in various formats:
+    - Unix milliseconds (integer): 1704067200000
+    - ISO string: "2025-01-15T10:30:00Z"
+    - datetime object: already parsed
+
+    Args:
+        timestamp: The timestamp to parse.
+
+    Returns:
+        A timezone-aware datetime object or None.
+    """
+    if timestamp is None:
+        return None
+
+    if isinstance(timestamp, datetime):
+        if timestamp.tzinfo is None:
+            return timestamp.replace(tzinfo=timezone.utc)
+        return timestamp
+
+    if isinstance(timestamp, int):
+        # Unix milliseconds
+        return datetime.fromtimestamp(timestamp / 1000, tz=timezone.utc)
+
+    if isinstance(timestamp, str):
+        # ISO format string
+        try:
+            dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt
+        except ValueError:
+            logger.warning(f"Failed to parse timestamp: {timestamp}")
+            return None
+
+    return None
+
+
+def is_duplicate_webhook(event_type: str, instance_id: str) -> bool:
+    """
+    Check if this webhook has already been processed.
+
+    Uses cache to prevent duplicate processing within a short window.
+
+    Args:
+        event_type: The Clerk event type.
+        instance_id: The webhook instance ID.
+
+    Returns:
+        True if this is a duplicate, False otherwise.
+    """
+    cache_key = f"webhook:{event_type}:{instance_id}"
+    if cache.get(cache_key):
+        return True
+    cache.set(cache_key, True, timeout=CLERK_WEBHOOK_DEDUP_TIMEOUT)
+    return False
+
+
+@transaction.atomic
+def handle_user_created(data: dict[str, Any]) -> "AbstractClerkUser | None":
+    """
+    Handle user.created webhook event.
+
+    Args:
+        data: The webhook event data.
+
+    Returns:
+        The created user or None if creation failed.
+    """
+    from django_clerk_users.utils import update_or_create_clerk_user
+
+    clerk_user_id = data.get("id")
+    if not clerk_user_id:
+        logger.error("user.created webhook missing user ID")
+        return None
+
+    try:
+        user, created = update_or_create_clerk_user(clerk_user_id)
+
+        # Emit signal
+        clerk_user_created.send(
+            sender=user.__class__,
+            user=user,
+            clerk_data=data,
+        )
+
+        logger.info(f"User created via webhook: {user.email}")
+        return user
+
+    except Exception as e:
+        logger.error(f"Failed to handle user.created: {e}")
+        return None
+
+
+@transaction.atomic
+def handle_user_updated(data: dict[str, Any]) -> "AbstractClerkUser | None":
+    """
+    Handle user.updated webhook event.
+
+    Args:
+        data: The webhook event data.
+
+    Returns:
+        The updated user or None if update failed.
+    """
+    from django_clerk_users.caching import invalidate_clerk_user_cache
+    from django_clerk_users.utils import update_or_create_clerk_user
+
+    clerk_user_id = data.get("id")
+    if not clerk_user_id:
+        logger.error("user.updated webhook missing user ID")
+        return None
+
+    try:
+        # Invalidate cache before update
+        invalidate_clerk_user_cache(clerk_user_id)
+
+        user, created = update_or_create_clerk_user(clerk_user_id)
+
+        # Emit signal
+        clerk_user_updated.send(
+            sender=user.__class__,
+            user=user,
+            clerk_data=data,
+        )
+
+        logger.info(f"User updated via webhook: {user.email}")
+        return user
+
+    except Exception as e:
+        logger.error(f"Failed to handle user.updated: {e}")
+        return None
+
+
+@transaction.atomic
+def handle_user_deleted(data: dict[str, Any]) -> "AbstractClerkUser | None":
+    """
+    Handle user.deleted webhook event.
+
+    Performs a soft delete by setting is_active=False.
+
+    Args:
+        data: The webhook event data.
+
+    Returns:
+        The deleted user or None if deletion failed.
+    """
+    from django.contrib.auth import get_user_model
+
+    from django_clerk_users.caching import invalidate_clerk_user_cache
+
+    User = get_user_model()
+
+    clerk_user_id = data.get("id")
+    if not clerk_user_id:
+        logger.error("user.deleted webhook missing user ID")
+        return None
+
+    try:
+        # Invalidate cache
+        invalidate_clerk_user_cache(clerk_user_id)
+
+        user = User.objects.filter(clerk_id=clerk_user_id).first()
+        if not user:
+            logger.warning(f"User not found for deletion: {clerk_user_id}")
+            return None
+
+        # Soft delete
+        user.is_active = False
+        user.save(update_fields=["is_active", "updated_at"])
+
+        # Emit signal
+        clerk_user_deleted.send(
+            sender=user.__class__,
+            user=user,
+            clerk_data=data,
+        )
+
+        logger.info(f"User deleted via webhook: {user.email}")
+        return user
+
+    except Exception as e:
+        logger.error(f"Failed to handle user.deleted: {e}")
+        return None
+
+
+@transaction.atomic
+def handle_session_created(data: dict[str, Any]) -> None:
+    """
+    Handle session.created webhook event.
+
+    Updates the user's last_login timestamp.
+
+    Args:
+        data: The webhook event data.
+    """
+    from django.contrib.auth import get_user_model
+
+    User = get_user_model()
+
+    user_id = data.get("user_id")
+    if not user_id:
+        logger.error("session.created webhook missing user_id")
+        return
+
+    try:
+        user = User.objects.filter(clerk_id=user_id).first()
+        if not user:
+            logger.debug(f"User not found for session.created: {user_id}")
+            return
+
+        # Update last_login
+        user.last_login = parse_clerk_timestamp(data.get("created_at"))
+        user.save(update_fields=["last_login", "updated_at"])
+
+        # Emit signal
+        clerk_session_created.send(
+            sender=user.__class__,
+            user=user,
+            clerk_data=data,
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to handle session.created: {e}")
+
+
+@transaction.atomic
+def handle_session_ended(data: dict[str, Any]) -> None:
+    """
+    Handle session.ended/removed/revoked webhook events.
+
+    Updates the user's last_logout timestamp.
+
+    Args:
+        data: The webhook event data.
+    """
+    from django.contrib.auth import get_user_model
+
+    User = get_user_model()
+
+    user_id = data.get("user_id")
+    if not user_id:
+        logger.error("session.ended webhook missing user_id")
+        return
+
+    try:
+        user = User.objects.filter(clerk_id=user_id).first()
+        if not user:
+            logger.debug(f"User not found for session.ended: {user_id}")
+            return
+
+        # Update last_logout
+        user.last_logout = parse_clerk_timestamp(
+            data.get("abandoned_at") or data.get("updated_at")
+        )
+        user.save(update_fields=["last_logout", "updated_at"])
+
+        # Emit signal
+        clerk_session_ended.send(
+            sender=user.__class__,
+            user=user,
+            clerk_data=data,
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to handle session.ended: {e}")
+
+
+def process_webhook_event(event_type: str, data: dict[str, Any]) -> bool:
+    """
+    Process a Clerk webhook event.
+
+    This is the main entry point for webhook event handling.
+    It routes events to the appropriate handler.
+
+    Args:
+        event_type: The Clerk event type (e.g., "user.created").
+        data: The event data from the webhook payload.
+
+    Returns:
+        True if the event was handled successfully, False otherwise.
+    """
+    handlers = {
+        "user.created": handle_user_created,
+        "user.updated": handle_user_updated,
+        "user.deleted": handle_user_deleted,
+        "session.created": handle_session_created,
+        "session.ended": handle_session_ended,
+        "session.removed": handle_session_ended,
+        "session.revoked": handle_session_ended,
+    }
+
+    handler = handlers.get(event_type)
+    if handler:
+        try:
+            handler(data)
+            return True
+        except Exception as e:
+            logger.error(f"Error handling {event_type}: {e}")
+            return False
+
+    # Check if organizations app handles this event
+    if event_type.startswith(("organization", "organizationMembership", "organizationInvitation")):
+        try:
+            from django_clerk_users.organizations.webhooks import (
+                process_organization_event,
+            )
+
+            return process_organization_event(event_type, data)
+        except ImportError:
+            logger.debug(f"Organizations app not installed, skipping {event_type}")
+            return True
+
+    logger.debug(f"Unhandled webhook event type: {event_type}")
+    return True

django_clerk_users/webhooks/security.py

@@ -0,0 +1,108 @@
+"""
+Webhook security utilities for Clerk.
+
+Uses Svix for webhook signature verification.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from typing import TYPE_CHECKING, Any, Callable
+
+from django.http import HttpResponseBadRequest, HttpResponseForbidden
+from django.views.decorators.csrf import csrf_exempt
+from svix.webhooks import Webhook, WebhookVerificationError
+
+from django_clerk_users.exceptions import ClerkWebhookError
+from django_clerk_users.settings import CLERK_WEBHOOK_SIGNING_KEY
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
+logger = logging.getLogger(__name__)
+
+
+def verify_clerk_webhook(request: "HttpRequest") -> dict[str, Any]:
+    """
+    Verify a Clerk webhook signature using Svix.
+
+    Args:
+        request: The Django HTTP request containing the webhook payload.
+
+    Returns:
+        The verified webhook payload as a dictionary.
+
+    Raises:
+        ClerkWebhookError: If verification fails or signing key is not configured.
+    """
+    if not CLERK_WEBHOOK_SIGNING_KEY:
+        raise ClerkWebhookError(
+            "CLERK_WEBHOOK_SIGNING_KEY is not configured. "
+            "Set it in your Django settings to enable webhook verification."
+        )
+
+    try:
+        wh = Webhook(CLERK_WEBHOOK_SIGNING_KEY)
+
+        # Svix expects specific headers
+        headers = {
+            "svix-id": request.headers.get("svix-id", ""),
+            "svix-timestamp": request.headers.get("svix-timestamp", ""),
+            "svix-signature": request.headers.get("svix-signature", ""),
+        }
+
+        # Verify and parse the payload
+        payload = wh.verify(request.body, headers)
+        return payload
+
+    except WebhookVerificationError as e:
+        logger.warning(f"Webhook verification failed: {e}")
+        raise ClerkWebhookError(f"Webhook verification failed: {e}") from e
+    except Exception as e:
+        logger.error(f"Unexpected error during webhook verification: {e}")
+        raise ClerkWebhookError(f"Webhook verification error: {e}") from e
+
+
+def clerk_webhook_required(view_func: Callable) -> Callable:
+    """
+    Decorator that verifies Clerk webhook signatures.
+
+    Use this decorator on webhook view functions to automatically
+    verify the webhook signature and attach the verified payload
+    to the request.
+
+    Example:
+        from django_clerk_users.webhooks import clerk_webhook_required
+
+        @clerk_webhook_required
+        def my_webhook_view(request):
+            data = request.clerk_webhook_data
+            # Process the webhook...
+            return HttpResponse("OK")
+
+    The decorator:
+    1. Exempts the view from CSRF protection (webhooks can't have CSRF tokens)
+    2. Verifies the Svix signature
+    3. Attaches the verified payload to request.clerk_webhook_data
+    4. Returns 400/403 responses on verification failure
+    """
+
+    @csrf_exempt
+    @functools.wraps(view_func)
+    def wrapper(request: "HttpRequest", *args, **kwargs):
+        if request.method != "POST":
+            return HttpResponseBadRequest("Only POST requests are allowed")
+
+        try:
+            payload = verify_clerk_webhook(request)
+        except ClerkWebhookError as e:
+            logger.warning(f"Webhook verification failed: {e}")
+            return HttpResponseForbidden(str(e))
+
+        # Attach verified payload to request
+        request.clerk_webhook_data = payload  # type: ignore
+
+        return view_func(request, *args, **kwargs)
+
+    return wrapper

django_clerk_users/webhooks/signals.py

@@ -0,0 +1,42 @@
+"""
+Django signals for Clerk webhook events.
+
+These signals allow you to hook into Clerk events without modifying
+the core webhook handlers.
+
+Example usage:
+
+    from django.dispatch import receiver
+    from django_clerk_users.webhooks.signals import clerk_user_created
+
+    @receiver(clerk_user_created)
+    def handle_new_user(sender, user, clerk_data, **kwargs):
+        # Send welcome email, create related objects, etc.
+        send_welcome_email(user.email)
+"""
+
+from django.dispatch import Signal
+
+# User signals
+clerk_user_created = Signal()  # Provides: user, clerk_data
+clerk_user_updated = Signal()  # Provides: user, clerk_data
+clerk_user_deleted = Signal()  # Provides: user, clerk_data
+
+# Session signals
+clerk_session_created = Signal()  # Provides: user, clerk_data
+clerk_session_ended = Signal()  # Provides: user, clerk_data
+
+# Organization signals (used by organizations sub-app)
+clerk_organization_created = Signal()  # Provides: organization, clerk_data
+clerk_organization_updated = Signal()  # Provides: organization, clerk_data
+clerk_organization_deleted = Signal()  # Provides: organization, clerk_data
+
+# Membership signals (used by organizations sub-app)
+clerk_membership_created = Signal()  # Provides: membership, clerk_data
+clerk_membership_updated = Signal()  # Provides: membership, clerk_data
+clerk_membership_deleted = Signal()  # Provides: membership, clerk_data
+
+# Invitation signals (used by organizations sub-app)
+clerk_invitation_created = Signal()  # Provides: invitation, clerk_data
+clerk_invitation_accepted = Signal()  # Provides: invitation, clerk_data
+clerk_invitation_revoked = Signal()  # Provides: invitation, clerk_data

django_clerk_users/webhooks/views.py

@@ -0,0 +1,76 @@
+"""
+Webhook views for Clerk events.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from django.http import HttpResponse, JsonResponse
+
+from django_clerk_users.webhooks.handlers import is_duplicate_webhook, process_webhook_event
+from django_clerk_users.webhooks.security import clerk_webhook_required
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest
+
+logger = logging.getLogger(__name__)
+
+
+@clerk_webhook_required
+def clerk_webhook_view(request: "HttpRequest") -> HttpResponse:
+    """
+    Handle Clerk webhook events.
+
+    This view receives webhook events from Clerk, verifies the signature,
+    and processes the event.
+
+    The @clerk_webhook_required decorator handles:
+    - CSRF exemption
+    - Signature verification
+    - Attaching verified payload to request.clerk_webhook_data
+
+    URL Configuration:
+        Add to your urls.py:
+
+        from django_clerk_users.webhooks import clerk_webhook_view
+
+        urlpatterns = [
+            path("webhooks/clerk/", clerk_webhook_view, name="clerk_webhook"),
+        ]
+
+    Returns:
+        200 OK on success
+        400 Bad Request on invalid payload
+        403 Forbidden on signature verification failure
+    """
+    data = request.clerk_webhook_data  # type: ignore
+
+    # Extract event metadata
+    event_type = data.get("type")
+    event_data = data.get("data", {})
+    event_id = data.get("id", "")
+
+    if not event_type:
+        logger.warning("Webhook received without event type")
+        return JsonResponse({"error": "Missing event type"}, status=400)
+
+    # Check for duplicate webhook
+    instance_id = event_data.get("id", event_id)
+    if is_duplicate_webhook(event_type, instance_id):
+        logger.debug(f"Duplicate webhook ignored: {event_type} {instance_id}")
+        return HttpResponse("OK (duplicate)", status=200)
+
+    logger.info(f"Processing webhook: {event_type}")
+
+    # Process the event
+    success = process_webhook_event(event_type, event_data)
+
+    if success:
+        return HttpResponse("OK", status=200)
+    else:
+        # Return 200 anyway to prevent Clerk from retrying
+        # Log the error for monitoring
+        logger.error(f"Webhook processing failed: {event_type}")
+        return HttpResponse("OK (processing failed)", status=200)