✨(backend) add roomkit viewset to start a room without WebRTC join

Introduce a new viewset that lets the roomkit start a room even when
no WebRTC participant has joined yet.

This is a first entry point that will be extended over time with
more actions a roomkit needs to be able to trigger.

Known limitations:

* The responsibility around SIP rules is currently split between
  the telephony feature and the roomkit one. This may need a
  refactor later on to consolidate ownership in a single place.
* The default throttle might be too low for production usage and
  will likely need to be revisited.

src/backend/core/roomkit/__init__.py

@@ -0,0 +1 @@
+"""Meet core roomkit API endpoints for meeting-room (SIP) device integration."""

src/backend/core/roomkit/authentication.py

@@ -0,0 +1,65 @@
+"""Authentication for the roomkit API of the Meet core app."""
+
+import logging
+import secrets
+
+from django.conf import settings
+
+from rest_framework.authentication import BaseAuthentication
+from rest_framework.exceptions import AuthenticationFailed
+
+from core.recording.event.authentication import MachineUser
+
+logger = logging.getLogger(__name__)
+
+
+class ServerToServerAuthentication(BaseAuthentication):
+    """Custom authentication class for roomkit server-to-server requests.
+
+    Validates the Authorization header against the roomkit server-to-server
+    token. A valid PIN code is intentionally not enough to authenticate: the
+    endpoints are restricted to the LiveKit SIP module's credentials.
+    """
+
+    AUTH_HEADER = "Authorization"
+    TOKEN_TYPE = "Bearer"  # noqa S105
+
+    def authenticate(self, request):
+        """Validate the Bearer token from the Authorization header.
+
+        Returns a (MachineUser, token) pair on success, and raises
+        AuthenticationFailed if the header is missing, malformed, or contains
+        an invalid token.
+        """
+        required_token = settings.ROOMKIT_SERVER_TO_SERVER_API_TOKEN
+        if not required_token:
+            raise AuthenticationFailed("Server-to-server token is not configured.")
+
+        auth_header = request.headers.get(self.AUTH_HEADER)
+        if not auth_header:
+            logger.warning(
+                "Roomkit authentication failed: missing Authorization header (ip: %s)",
+                request.META.get("REMOTE_ADDR"),
+            )
+            raise AuthenticationFailed("Authorization header is missing.")
+
+        # Validate token format and existence
+        auth_parts = auth_header.split(" ")
+        if len(auth_parts) != 2 or auth_parts[0] != self.TOKEN_TYPE:
+            raise AuthenticationFailed("Invalid authorization header.")
+
+        token = auth_parts[1]
+
+        # Use constant-time comparison to prevent timing attacks
+        if not secrets.compare_digest(token.encode(), required_token.encode()):
+            logger.warning(
+                "Roomkit authentication failed: invalid token (ip: %s)",
+                request.META.get("REMOTE_ADDR"),
+            )
+            raise AuthenticationFailed("Invalid server-to-server token.")
+
+        return MachineUser(username="roomkit"), token
+
+    def authenticate_header(self, request):
+        """Return the WWW-Authenticate header value."""
+        return f"{self.TOKEN_TYPE} realm='Roomkit server to server'"

src/backend/core/roomkit/serializers.py

@@ -0,0 +1,21 @@
+"""Serializers for the roomkit API of the Meet core app."""
+
+# pylint: disable=abstract-method
+
+from django.conf import settings
+
+from rest_framework import serializers
+
+from core.api.serializers import BaseValidationOnlySerializer
+
+
+class RoomKitJoinSerializer(BaseValidationOnlySerializer):
+    """Validate roomkit join requests from the LiveKit SIP module."""
+
+    pin_code = serializers.CharField(required=True)
+
+    def validate_pin_code(self, value):
+        """Ensure the PIN code matches the configured length."""
+        if len(value) != settings.ROOM_TELEPHONY_PIN_LENGTH:
+            raise serializers.ValidationError("PIN code length is invalid.")
+        return value

src/backend/core/roomkit/viewsets.py

@@ -0,0 +1,89 @@
+"""Roomkit API endpoints for meeting-room (SIP) device integration."""
+
+from logging import getLogger
+
+from rest_framework import decorators, viewsets
+from rest_framework import (
+    exceptions as drf_exceptions,
+)
+from rest_framework import (
+    response as drf_response,
+)
+from rest_framework import (
+    status as drf_status,
+)
+
+from core import analytics, models
+from core.api import permissions, throttling
+from core.api.feature_flag import FeatureFlag
+from core.services.telephony import TelephonyException, TelephonyService
+
+from . import authentication, serializers
+
+logger = getLogger(__name__)
+
+
+class RoomKitViewSet(viewsets.ViewSet):
+    """Server-to-server API endpoints for the roomkit integration.
+
+    Groups all interactions between roomkit (SIP) devices and the backend,
+    brokered by the LiveKit SIP module. All endpoints are authenticated
+    with the roomkit server-to-server tokens.
+    """
+
+    authentication_classes = [authentication.ServerToServerAuthentication]
+    permission_classes = [permissions.IsAuthenticated]
+
+    @decorators.action(
+        detail=False,
+        methods=["post"],
+        url_path="join",
+        throttle_classes=[throttling.RoomKitJoinRateThrottle],
+    )
+    @FeatureFlag.require("roomkit")
+    def join(self, request):
+        """Prepare a room for a meeting-room (SIP) device joining by PIN code.
+
+        Called by the LiveKit SIP module when a meeting-room device dials in
+        with a PIN code before any WebRTC participant has joined. Resolves the
+        room by PIN and creates its SIP dispatch rule, so the device can enter
+        without waiting for a WebRTC user.
+
+        The webhook-based creation path is kept: both converge on the same rule
+        through the shared TelephonyService.
+        """
+
+        serializer = serializers.RoomKitJoinSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+
+        try:
+            room = models.Room.objects.get(
+                pin_code=serializer.validated_data["pin_code"]
+            )
+        except models.Room.DoesNotExist as e:
+            raise drf_exceptions.NotFound("No room found for this PIN code.") from e
+
+        try:
+            created = TelephonyService().ensure_dispatch_rule(room)
+        except TelephonyException as e:
+            raise drf_exceptions.APIException("Could not create dispatch rule.") from e
+
+        analytics.capture(
+            request.user,
+            analytics.AnalyticsEvent.ROOMKIT_JOINED,
+            {
+                "room_id": str(room.pk),
+                "dispatch_rule_created": created,
+            },
+        )
+
+        logger.info(
+            "Roomkit join requested: room_id=%s, dispatch_rule_created=%s",
+            room.id,
+            created,
+        )
+
+        return drf_response.Response(
+            {"status": "success"},
+            status=drf_status.HTTP_200_OK,
+        )