Cloudflare Turnstile (CAPTCHA)

backend/.env.example

@@ -13,6 +13,10 @@ AWS_SES_REGION_NAME=region_name
 AWS_SES_REGION_ENDPOINT=region_endpoint
 DEFAULT_FROM_EMAIL=email
 
+# Cloudflare Turnstile secret key for CAPTCHA verification. This placeholder is the test
+# key provided by Cloudflare which always returns success on verification for development.
+CF_TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
+
 # The URL of the main site, used for generating links (no trailing slash)
 BASE_URL=https://example.com
 

backend/api/auth/views.py

@@ -19,6 +19,7 @@
 from api.decorators import (
     api_endpoint,
     require_account_auth,
+    require_captcha,
     validate_json_input,
     validate_output,
 )
@@ -51,6 +52,7 @@
 
 
 @api_endpoint("POST")
+@require_captcha
 @validate_json_input(RegisterAccountSerializer)
 @validate_output(MessageOutputSerializer)
 def register(request):
@@ -307,6 +309,7 @@ def check_account_auth(request):
 
 
 @api_endpoint("POST")
+@require_captcha
 @validate_json_input(EmailSerializer)
 @validate_output(MessageOutputSerializer)
 def start_password_reset(request):

backend/api/availability/views.py

@@ -15,6 +15,7 @@
     api_endpoint,
     check_auth,
     require_auth,
+    require_captcha,
     validate_json_input,
     validate_output,
     validate_query_param_input,
@@ -46,6 +47,7 @@ class InvalidTimeslotError(Exception):
 
 
 @api_endpoint("POST")
+@require_captcha
 @require_auth
 @validate_json_input(AvailabilityAddSerializer)
 @validate_output(MessageOutputSerializer)

backend/api/decorators.py

@@ -2,6 +2,7 @@
 import logging
 import uuid
 
+import requests
 from django.db import DatabaseError, transaction
 from rest_framework import serializers
 from rest_framework.decorators import api_view
@@ -11,6 +12,9 @@
 from api.models import UserAccount, UserSession
 from api.settings import (
     ACCOUNT_COOKIE_NAME,
+    CF_TURNSTILE_SECRET_KEY,
+    CF_TURNSTILE_VERIFY_URL,
+    DEBUG,
     GENERIC_ERR_RESPONSE,
     GUEST_COOKIE_NAME,
     ThrottleScopes,
@@ -19,6 +23,7 @@
     RateLimitError,
     check_rate_limit,
     delete_session_cookie,
+    get_client_ip_address,
     get_metadata,
     get_session,
     set_session_cookie,
@@ -517,3 +522,49 @@ def decorator(func):
         return func
 
     return decorator
+
+
+def require_captcha(func):
+    """
+    A decorator to check if the request has a valid Cloudflare Turnstile token.
+
+    If the token is invalid, an error response will be returned.
+    """
+
+    @functools.wraps(func)
+    def wrapper(request, *args, **kwargs):
+        client_token = (
+            request.data.get("captcha_token")
+            if isinstance(request.data, dict)
+            else None
+        )
+        if not client_token:
+            return Response(
+                {"error": {"general": ["CAPTCHA token is required."]}}, status=400
+            )
+
+        # Assemble payload, including client IP if possible for extra security
+        payload = {
+            "secret": CF_TURNSTILE_SECRET_KEY,
+            "response": client_token,
+        }
+        if client_ip := get_client_ip_address(request):
+            payload["remoteip"] = client_ip
+
+        try:
+            # Verify the token with Cloudflare Turnstile
+            response = requests.post(CF_TURNSTILE_VERIFY_URL, data=payload, timeout=5)
+            response.raise_for_status()
+            result = response.json()
+            if not result.get("success"):
+                return Response(
+                    {"error": {"general": ["CAPTCHA verification failed."]}}, status=400
+                )
+        except Exception as e:
+            logger.warning("CAPTCHA verification had a problem: %s", e)
+            return GENERIC_ERR_RESPONSE
+
+        return func(request, *args, **kwargs)
+
+    get_metadata(wrapper).captcha_required = True
+    return wrapper

backend/api/docs/utils.py

@@ -46,6 +46,8 @@ def get_readable_field_name(field_name):
             return "string"
         case "RegexField":
             return "string"
+        case "UUIDField":
+            return "string"
         case _:
             return "object"
 

backend/api/docs/views.py

@@ -17,6 +17,7 @@ class EndpointSerializer(serializers.Serializer):
     output_format = serializers.JSONField(allow_null=True)
     min_auth_required = serializers.CharField(allow_null=True)
     rate_limit = serializers.CharField(allow_null=True)
+    captcha_required = serializers.BooleanField()
 
 
 class DocsSerializer(serializers.Serializer):
@@ -49,6 +50,7 @@ def get_docs(request):
                 ),
                 "min_auth_required": metadata.min_auth_required,
                 "rate_limit": metadata.rate_limit,
+                "captcha_required": metadata.captcha_required,
             }
         )
     return Response({"endpoints": endpoints})

backend/api/event/utils.py

@@ -33,6 +33,7 @@ def check_custom_code(code):
         "api",
         "dashboard",
         "forgot-password",
+        "guest-import",
         "login",
         "new-event",
         "settings",

backend/api/event/views.py

@@ -16,6 +16,7 @@
     api_endpoint,
     check_auth,
     require_auth,
+    require_captcha,
     sse_endpoint,
     validate_json_input,
     validate_output,
@@ -75,6 +76,7 @@
 
 
 @api_endpoint("POST")
+@require_captcha
 @require_auth
 @validate_json_input(DateEventCreateSerializer)
 @validate_output(EventCodeSerializer)
@@ -138,6 +140,7 @@ def create_date_event(request):
 
 
 @api_endpoint("POST")
+@require_captcha
 @require_auth
 @validate_json_input(WeekEventCreateSerializer)
 @validate_output(EventCodeSerializer)

backend/api/guest_import/serializers.py

@@ -0,0 +1,39 @@
+from rest_framework import serializers
+
+
+class GuestDataSummarySerializer(serializers.Serializer):
+    created_events = serializers.IntegerField()
+    participated_events = serializers.IntegerField()
+
+
+class GuestEventSerializer(serializers.Serializer):
+    url_code = serializers.CharField(allow_null=True)
+    public_id = serializers.UUIDField()
+    title = serializers.CharField()
+
+
+class GuestParticipationSerializer(serializers.Serializer):
+    url_code = serializers.CharField(allow_null=True)
+    public_id = serializers.UUIDField()
+    title = serializers.CharField()
+    guest_display_name = serializers.CharField()
+    account_display_name = serializers.CharField(allow_null=True)
+
+
+class GuestDataSerializer(serializers.Serializer):
+    created_events = serializers.ListField(
+        child=GuestEventSerializer(),
+        allow_empty=True,
+    )
+    participated_events = serializers.ListField(
+        child=GuestParticipationSerializer(),
+        allow_empty=True,
+    )
+
+
+class GuestImportDataSerializer(serializers.Serializer):
+    availability_choices = serializers.DictField(
+        required=True,
+        child=serializers.ChoiceField(required=True, choices=["guest", "account"]),
+        allow_empty=True,
+    )

backend/api/guest_import/urls.py

@@ -0,0 +1,9 @@
+from django.urls import path
+
+from . import views
+
+urlpatterns = [
+    path("get-summary/", views.get_summary),
+    path("get-data/", views.get_data),
+    path("import-data/", views.import_data),
+]

backend/api/guest_import/utils.py

@@ -0,0 +1,38 @@
+import logging
+
+from django.db import transaction
+
+from api.models import UserSession
+from api.settings import GUEST_COOKIE_NAME
+from api.utils import get_session, set_session_cookie, update_session_metadata
+
+logger = logging.getLogger("api")
+
+
+def get_guest_account(request, response):
+    """
+    Returns the guest account associated with the request, refreshing the session token
+    cookie and updating the metadata on the session.
+
+    If there is no guest account, this will return `None`.
+
+    This does NOT make the guest user available on the `request` object.
+    """
+    guest_token = request.COOKIES.get(GUEST_COOKIE_NAME)
+
+    if guest_token:
+        logger.debug("Guest session token: %s", guest_token)
+        try:
+            with transaction.atomic():
+                session = get_session(guest_token)
+                if not session:
+                    raise UserSession.DoesNotExist
+
+                update_session_metadata(request, session)
+        except UserSession.DoesNotExist:
+            logger.info("Guest session expired.")
+        else:
+            set_session_cookie(response, GUEST_COOKIE_NAME, session.session_token, True)
+            return session.user_account
+
+    return None