Relay Space WebRTC through short-lived TURN

README.md

@@ -50,8 +50,11 @@ ZeroGPU, the approach is invalidated rather than disguised as turn-based chat.
 - Gated model files are requested with the signed-in user's short-lived Hugging Face OAuth token; no broad
   repository-write token is stored in the Space.
 - Audio queues, transcript text, and scene state are session-only and are discarded when the session ends.
-- WebRTC uses Cloudflare's public STUN service for connection discovery. STUN receives network metadata but is not
-  an audio relay; no TURN relay or third-party inference/media API is configured in this spike.
+- Hugging Face Spaces requires a TURN relay for reliable WebRTC through its cloud firewall. When the signed-in user
+  connects the microphone, FastRTC exchanges that user's short-lived Hugging Face OAuth token for temporary
+  Cloudflare TURN credentials. Cloudflare can relay encrypted WebRTC traffic and receives connection metadata; it
+  does not receive plaintext prompts or model inference requests. No persistent Hugging Face token is stored as a
+  Space secret.
 - Version 1 provides only NVIDIA's bundled synthetic voice prompts. It does not clone uploaded voices.
 - Player audio is treated as untrusted dialogue, never as a system or director instruction.
 - Prompt-leak detection is best-effort and the fictional secret is deliberately harmless test data.

streaming_app.py

@@ -5,6 +5,7 @@ import json
 import multiprocessing
 import queue
 import tarfile
+import threading
 import time
 import uuid
 from pathlib import Path
@@ -14,7 +15,7 @@ import numpy as np
 import sentencepiece
 import spaces
 import torch
-from fastrtc import StreamHandler, WebRTC
+from fastrtc import StreamHandler, WebRTC, get_cloudflare_turn_credentials_async
 from huggingface_hub import hf_hub_download
 
 
@@ -28,9 +29,10 @@ INPUT_QUEUE_FRAMES = 12
 OUTPUT_QUEUE_FRAMES = 20
 WEBRTC_FRAME_RATE = 50
 OUTPUT_SAMPLE_RATE = 24_000
-RTC_CONFIGURATION = {
+SERVER_RTC_CONFIGURATION = {
     "iceServers": [{"urls": ["stun:stun.cloudflare.com:3478"]}],
 }
+TURN_TOKEN_TTL_SECONDS = 10 * 60
 
 ALL_VOICES = [
     "NATF0", "NATF1", "NATF2", "NATF3",
@@ -180,9 +182,46 @@ def get_models(token):
 
 _manager = multiprocessing.Manager()
 _bridge_registry = _manager.dict()
+_turn_token_lock = threading.Lock()
+_turn_oauth_token = None
+_turn_oauth_deadline = 0.0
 
 
-def new_bridge():
+def remember_turn_token(oauth_token):
+    """Keep the signed-in user's short-lived token only long enough to mint TURN credentials."""
+    global _turn_oauth_token, _turn_oauth_deadline
+    token = getattr(oauth_token, "token", None)
+    if not token:
+        raise gr.Error("Sign in with Hugging Face before starting the live engine.")
+    with _turn_token_lock:
+        _turn_oauth_token = token
+        _turn_oauth_deadline = time.monotonic() + TURN_TOKEN_TTL_SECONDS
+
+
+def clear_turn_token():
+    global _turn_oauth_token, _turn_oauth_deadline
+    with _turn_token_lock:
+        _turn_oauth_token = None
+        _turn_oauth_deadline = 0.0
+
+
+async def get_turn_configuration():
+    """Mint relay credentials at microphone-connect time without a persistent Space secret."""
+    with _turn_token_lock:
+        token = _turn_oauth_token
+        deadline = _turn_oauth_deadline
+    if not token or time.monotonic() >= deadline:
+        raise RuntimeError("Start the live engine before connecting the microphone.")
+    configuration = await get_cloudflare_turn_credentials_async(
+        hf_token=token,
+        ttl=TURN_TOKEN_TTL_SECONDS,
+    )
+    clear_turn_token()
+    return configuration
+
+
+def new_bridge(oauth_token: gr.OAuthToken | None):
+    remember_turn_token(oauth_token)
     input_queue = _manager.Queue(INPUT_QUEUE_FRAMES)
     output_queue = _manager.Queue(OUTPUT_QUEUE_FRAMES)
     stop_event = _manager.Event()
@@ -227,6 +266,7 @@ def stop_session(session_id):
     bridge = _bridge_registry.get(session_id) if session_id else None
     if bridge is not None:
         bridge[2].set()
+    clear_turn_token()
     return "Session stop requested. The microphone can now be disconnected."
 
 
@@ -460,6 +500,7 @@ def run_streaming_session(
 
     ready_event.clear()
     stop_event.set()
+    clear_turn_token()
     final_metrics = session_metrics(
         "complete",
         session_started,
@@ -520,8 +561,8 @@ with gr.Blocks(title="RoleForge Streaming Spike", theme=gr.themes.Soft(), css=CS
                 label="2. Connect microphone after Engine ready",
                 modality="audio",
                 mode="send-receive",
-                rtc_configuration=RTC_CONFIGURATION,
-                server_rtc_configuration=RTC_CONFIGURATION,
+                rtc_configuration=get_turn_configuration,
+                server_rtc_configuration=SERVER_RTC_CONFIGURATION,
                 full_screen=False,
             )
             gr.Markdown(