Refine device authorization flow

- device/init returns a relative verification_path; the client joins it
  with its own origin
- Render the v2 approval screen via the named v2 router outlet (was blank)
- DevicePair: RSpinner, keyboard-accessible scope chips, scrollable scopes;
  DevicePairShell uses always-light overlay tokens (no hex)

Author: tmgast

backend/alembic/versions/0084_devices_client_device_identifier.py

@@ -1,7 +1,7 @@
 """Add client_device_identifier to devices
 
-Revision ID: 0080_devices_client_identifier
-Revises: 0079_add_rom_files_rom_id_index
+Revision ID: 0084_devices_client_identifier
+Revises: 0083_rom_category_soundtrack
 Create Date: 2026-04-24 00:00:00.000000
 
 """

backend/alembic/versions/0085_client_tokens_device_id.py

@@ -1,7 +1,7 @@
 """Add device_id FK to client_tokens
 
-Revision ID: 0081_client_tokens_device_id
-Revises: 0080_devices_client_identifier
+Revision ID: 0085_client_tokens_device_id
+Revises: 0084_devices_client_identifier
 Create Date: 2026-04-24 00:00:00.000000
 
 """

backend/docker-compose.test.yml

@@ -0,0 +1,37 @@
+# Local test infrastructure matching .github/workflows/pytest.yml.
+# Usage: docker compose -f docker-compose.test.yml up -d
+#        uv run pytest
+services:
+  mariadb:
+    image: mariadb:10.11
+    ports:
+      - "3306:3306"
+    environment:
+      MYSQL_USER: romm_test
+      MYSQL_PASSWORD: passwd
+      MYSQL_DATABASE: romm_test
+      MYSQL_ROOT_PASSWORD: passwd
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "mariadb-admin",
+          "ping",
+          "-h",
+          "127.0.0.1",
+          "-uroot",
+          "-ppasswd",
+        ]
+      interval: 5s
+      timeout: 2s
+      retries: 10
+
+  valkey:
+    image: valkey/valkey:7.2
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 2s
+      retries: 10

backend/endpoints/device_auth.py

@@ -38,7 +38,7 @@
     PENDING_TTL_SECONDS,
     POLL_DEFAULT_INTERVAL_SECONDS,
     FlowStatus,
-    build_verification_urls,
+    build_verification_paths,
     check_authorize_rate_limit,
     check_token_poll_rate_limit,
     consume_approved,
@@ -87,9 +87,7 @@ def device_auth_init(
         },
     )
 
-    verification_url, verification_url_complete = build_verification_urls(
-        request, user_code
-    )
+    verification_path, verification_path_complete = build_verification_paths(user_code)
 
     log.info(
         f"device_auth.init client={payload.client} "
@@ -100,8 +98,8 @@ def device_auth_init(
     return DeviceAuthInitResponse(
         device_code=device_code,
         user_code=user_code,
-        verification_url=verification_url,
-        verification_url_complete=verification_url_complete,
+        verification_path=verification_path,
+        verification_path_complete=verification_path_complete,
         expires_in=PENDING_TTL_SECONDS,
         interval=POLL_DEFAULT_INTERVAL_SECONDS,
     )
@@ -198,12 +196,14 @@ def approve(
         client_version = data.get("client_version")
         if client_version is not None:
             update_data["client_version"] = client_version
-        db_device_handler.update_device(
-            device_id=existing.id,
-            user_id=request.user.id,
-            data=update_data,
+        device = (
+            db_device_handler.update_device(
+                device_id=existing.id,
+                user_id=request.user.id,
+                data=update_data,
+            )
+            or existing
         )
-        device = existing
     else:
         device = db_device_handler.add_device(
             Device(

backend/endpoints/responses/device_auth.py

@@ -15,8 +15,15 @@ class DeviceAuthInitPayload(BaseModel):
 class DeviceAuthInitResponse(BaseModel):
     device_code: str
     user_code: str
-    verification_url: str
-    verification_url_complete: str
+    verification_path: str = Field(
+        description=(
+            "Relative web-UI path (/pair/device). The client joins it with the "
+            "origin it was configured to reach; the server is origin-agnostic."
+        )
+    )
+    verification_path_complete: str = Field(
+        description="Same path with ?user_code= appended, for QR display."
+    )
     expires_in: int
     interval: int
 

backend/tests/endpoints/test_device_auth.py

@@ -70,8 +70,8 @@ def test_valid_request_returns_all_fields(self, client):
 
         assert len(body["device_code"]) == df.DEVICE_CODE_BYTES * 2
         assert len(body["user_code"]) == df.USER_CODE_LENGTH
-        assert body["verification_url"].endswith("/pair/device")
-        assert body["user_code"] in body["verification_url_complete"]
+        assert body["verification_path"].endswith("/pair/device")
+        assert body["user_code"] in body["verification_path_complete"]
         assert body["expires_in"] == df.PENDING_TTL_SECONDS
         assert body["interval"] == df.POLL_DEFAULT_INTERVAL_SECONDS
 
@@ -550,18 +550,17 @@ def test_per_ip_rate_limit(self, client):
         assert last_status == status.HTTP_429_TOO_MANY_REQUESTS
 
 
-class TestVerificationUrls:
-    def test_verification_url_is_server_origin(self, client):
-        # Never echoes client-supplied callback data — verification_url is
-        # always the server's own origin + /pair/device. This is the XSS
-        # surface removal the plan leans on.
+class TestVerificationPaths:
+    def test_verification_path_is_relative(self, client):
+        # The path is a fixed server constant (/pair/device); client metadata
+        # like the device name is never interpolated into it.
         body = _authorize(
             client,
             payload={**AUTHORIZE_PAYLOAD, "name": "javascript:alert(1)"},
         )
-        assert body["verification_url"].endswith("/pair/device")
-        assert "javascript:" not in body["verification_url"]
-        assert "javascript:" not in body["verification_url_complete"]
+        assert body["verification_path"] == "/pair/device"
+        assert "://" not in body["verification_path"]
+        assert "javascript:" not in body["verification_path_complete"]
 
 
 class TestHelperFunctions:
@@ -711,9 +710,9 @@ def test_grout_pairs_ingests_play_session(
         )
         assert start_resp.status_code == status.HTTP_201_CREATED
         init = start_resp.json()
-        assert init["verification_url"].endswith("/pair/device")
+        assert init["verification_path"].endswith("/pair/device")
 
-        # Device displays QR from verification_url_complete; user scans; user
+        # Device displays QR from verification_path_complete; user scans; user
         # is routed to /pair/device?user_code=... and authenticates.
 
         # --- 2. Web UI fetches pending metadata ---

backend/utils/device_auth.py

@@ -11,6 +11,7 @@
 from typing import Any, Final
 
 from fastapi import HTTPException, Request, status
+from yarl import URL
 
 from handler.redis_handler import sync_cache
 from utils.client_tokens import PAIR_ALPHABET
@@ -54,16 +55,19 @@ def generate_user_code() -> str:
     return "".join(secrets.choice(PAIR_ALPHABET) for _ in range(USER_CODE_LENGTH))
 
 
-def build_verification_urls(request: Request, user_code: str) -> tuple[str, str]:
-    """Build server-origin URLs only — never from client input.
+def build_verification_paths(user_code: str) -> tuple[str, str]:
+    """Return the web-UI approval paths.
 
-    This is intentional: no user-supplied callback URLs, so no javascript:/data:
-    XSS surface on the approval page.
+    Only a fixed relative path is returned; the client joins it with the origin
+    it was configured to reach, so the server stays origin-agnostic (in
+    development the web UI and API run on different ports). The path is a server
+    constant and never incorporates client input.
     """
-    base = str(request.base_url).rstrip("/")
-    verification_url = f"{base}/pair/device"
-    verification_url_complete = f"{verification_url}?user_code={user_code}"
-    return verification_url, verification_url_complete
+    verification_path = "/pair/device"
+    verification_path_complete = str(
+        URL(verification_path).with_query(user_code=user_code)
+    )
+    return verification_path, verification_path_complete
 
 
 def check_authorize_rate_limit(request: Request) -> None: