turn: wire Cloudflare TURN relay via daemon-sole-minter (#6)

STUN-only couldn't connect external testers on cellular/symmetric-NAT/
corporate networks. Add a TURN relay fallback, gated so minting (a billable
resource) only happens for a party we can cryptographically verify.

The signaling worker can prove a daemon's Ed25519 identity but NOT a
client's, so the daemon is the SOLE minter and relays the creds to its
clients over the existing offer:

- signaling worker: POST /turn-credentials verifies a sig over
  `turn/v1/<pubkey>/<ts>` (distinct domain tag from the connect sig),
  mints from Cloudflare Realtime TURN (12h TTL), guarded by a separate
  RL_TURN limiter (10/60s by pubkey). Unset secrets → 503 → STUN fallback.
- daemon: getIceServers() mints+caches (10h TTL, 60s negative-cache,
  single-flight, prewarmed in start()), uses the creds for its pc AND
  relays the same list in the offer envelope.
- app: handleOffer applies the relayed iceServers via setConfiguration
  before createAnswer; the client never mints its own. fpSig still pins
  DTLS identity, so a tampering worker can't swap in a hostile relay.

Wire-neutral (offer envelope is worker-forwarded freeform, not a protocol
schema); rollout order-independent (old peers ignore the new field, unset
secrets degrade to STUN). Activate by setting TURN_KEY_ID + TURN_API_TOKEN
secrets, deploying the worker, and shipping daemon (menubar) + app.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: yyq1025

packages/app/src/lib/daemon-client.ts

@@ -515,10 +515,13 @@ export class Transport {
         onPeerJoined: (peer) => {
           if (peer.role === "daemon") onDaemonAvailable(peer);
         },
-        onOffer: (from, sdp, fpSig) => {
+        onOffer: (from, sdp, fpSig, iceServers) => {
           daemonPeerId = from;
+          // `iceServers` carries the daemon-minted TURN creds (it's the sole
+          // minter). handleOffer applies them before it gathers ICE so our
+          // candidates include the relay; absent them we stay STUN-only.
           void peer
-            .handleOffer(sdp, fpSig)
+            .handleOffer(sdp, fpSig, iceServers)
             .then(({ answerSdp, fpSig: ourSig }) => {
               signaling.send(from, "answer", { sdp: answerSdp, fpSig: ourSig });
             })

packages/app/src/lib/signaling-client.ts

@@ -39,8 +39,16 @@ export interface SignalingClientCallbacks {
   onPeerLeft?: (peer: SignalingPeer) => void;
   /** Daemon → client SDP offer. `fpSig` is the daemon's Ed25519 signature
    *  over the SDP's DTLS fingerprint; the owner MUST verify it against
-   *  the QR-known daemon pubkey before calling setRemoteDescription. */
-  onOffer?: (from: string, sdp: string, fpSig: string) => void;
+   *  the QR-known daemon pubkey before calling setRemoteDescription.
+   *  `iceServers` carries the daemon-minted TURN creds (the daemon is the
+   *  sole minter); the owner builds its peer connection with them. Absent
+   *  when the daemon couldn't mint — owner falls back to its STUN default. */
+  onOffer?: (
+    from: string,
+    sdp: string,
+    fpSig: string,
+    iceServers?: RTCIceServer[],
+  ) => void;
   /** Trickle-ICE candidate from a peer. */
   onCandidate?: (from: string, candidate: unknown) => void;
   /** Worker-side error (`peer_not_found`, `missing_to`, etc.). */
@@ -193,7 +201,12 @@ export class SignalingClient {
           typeof msg.sdp === "string" &&
           typeof msg.fpSig === "string"
         ) {
-          this.opts.onOffer?.(msg.from, msg.sdp, msg.fpSig);
+          // Daemon-relayed TURN creds (optional). Worker forwards the offer
+          // envelope verbatim, so this is whatever the daemon attached.
+          const iceServers = Array.isArray(msg.iceServers)
+            ? (msg.iceServers as RTCIceServer[])
+            : undefined;
+          this.opts.onOffer?.(msg.from, msg.sdp, msg.fpSig, iceServers);
         }
         return;
       }

packages/app/src/lib/webrtc-peer.ts

@@ -142,10 +142,22 @@ export class WebRTCPeer {
   async handleOffer(
     offerSdp: string,
     daemonFpSig: string,
+    iceServers?: RTCIceServer[],
   ): Promise<{ answerSdp: string; fpSig: string }> {
     if (this.closed) throw new Error("WebRTCPeer is closed");
     this.setState("received-offer");
 
+    // 0. Apply the daemon-relayed TURN creds BEFORE we createAnswer — that's
+    //    when this (answerer) side starts ICE gathering, so the relay must be
+    //    in the config by now for our candidates to include it. The daemon is
+    //    the sole minter; absent creds (mint unavailable) we keep the
+    //    STUN-only default the constructor set. The fpSig check below still
+    //    pins DTLS identity, so a tampering worker can't swap in a hostile
+    //    relay without invalidating the signature.
+    if (iceServers && iceServers.length > 0) {
+      this.pc.setConfiguration({ iceServers });
+    }
+
     // 1. Verify daemon's signature over the SDP fingerprint before we
     //    even acknowledge the offer. If signaling DO was compromised and
     //    swapped the fingerprint, this catches it pre-DTLS.

packages/daemon/src/webrtc-peer.ts

@@ -66,6 +66,20 @@ const DEFAULT_ICE_SERVERS: RTCIceServer[] = [
   { urls: "stun:stun.cloudflare.com:3478" },
 ];
 
+/**
+ * How long the daemon reuses a minted TURN cred before re-minting. The
+ * worker requests a 12h TTL from Cloudflare; we refresh at 10h so a
+ * connection never gets a cred that's about to expire mid-session.
+ */
+const TURN_CACHE_TTL_MS = 10 * 60 * 60 * 1000;
+/**
+ * Negative-cache window when minting fails (TURN unconfigured / outage).
+ * Without it every `peer.joined` would re-hit `/turn-credentials` and pay
+ * a round-trip before falling back to STUN; 60s lets an outage self-heal
+ * fast while sparing the common steady-state from per-connection minting.
+ */
+const TURN_NEGATIVE_TTL_MS = 60_000;
+
 /**
  * Max time from `peer.joined` to `authenticated` (= DataChannel open).
  * Normal path completes in well under 5s on a clean network; 30s gives
@@ -146,7 +160,15 @@ export class WebRTCPeerServer {
   private readonly isPairing: () => boolean;
   private readonly signalingHost: string;
   private readonly signalingScheme: "ws" | "wss";
+  /** STUN-only fallback list used when TURN minting is unavailable. */
   private readonly iceServers: RTCIceServer[];
+  /** Cached minted TURN ICE-server list (+ expiry). Null until first
+   *  fetch; on mint failure holds the STUN fallback with a short TTL. */
+  private turnCache: { iceServers: RTCIceServer[]; expiresAt: number } | null =
+    null;
+  /** Single-flight guard so concurrent `peer.joined` events share one
+   *  mint round-trip instead of each firing their own. */
+  private turnInFlight: Promise<RTCIceServer[]> | null = null;
 
   constructor(options: WebRTCPeerServerOptions) {
     this.identity = options.identity;
@@ -198,6 +220,12 @@ export class WebRTCPeerServer {
       });
     });
 
+    // Warm the TURN cache so the first `peer.joined` doesn't eat a mint
+    // round-trip in its setup budget. Fire-and-forget — getIceServers never
+    // throws (degrades to STUN), and a failure here just means the first
+    // connection re-attempts the mint.
+    void this.getIceServers();
+
     // Fire-and-forget. Daemon shouldn't refuse to start just because
     // signaling.sidecode.app is momentarily unreachable — PartySocket's
     // infinite retry will eventually connect when the network heals, and
@@ -313,7 +341,11 @@ export class WebRTCPeerServer {
       this.log("peer.paired", { clientId: peer.id, fingerprint });
     }
 
-    const pc = new RTCPeerConnection({ iceServers: this.iceServers });
+    // Mint/reuse TURN creds for THIS connection and reuse the exact same
+    // list for the client (relayed in the offer below) so both ends agree
+    // on relays. Falls back to STUN-only if minting is unavailable.
+    const iceServers = await this.getIceServers();
+    const pc = new RTCPeerConnection({ iceServers });
     const slot: PeerSlot = {
       clientId: peer.id,
       clientPubkey: peer.pubkey,
@@ -383,8 +415,13 @@ export class WebRTCPeerServer {
         Buffer.from(dtlsFingerprintTranscript(fp)),
         this.identity.privateKey,
       ).toString("base64url");
+      // Relay the SAME ICE-server list (incl. minted TURN creds) the daemon
+      // used — the client is not a verified party so it never mints its own;
+      // it just uses what the signed daemon hands it. fpSig still pins the
+      // DTLS identity, so a tampering signaling worker can't swap in a
+      // malicious relay without breaking the fingerprint signature.
       this.signaling?.send(
-        JSON.stringify({ to: peer.id, type: "offer", sdp, fpSig }),
+        JSON.stringify({ to: peer.id, type: "offer", sdp, fpSig, iceServers }),
       );
     } catch (err) {
       this.log("peer.offer.error", {
@@ -653,6 +690,86 @@ export class WebRTCPeerServer {
     this.log("peer.closed", { clientId: slot.clientId, reason });
   }
 
+  // ─── TURN credentials ───────────────────────────────────────────
+
+  /**
+   * Effective ICE-server list for a new peer connection: minted TURN
+   * (STUN + relay) when available, else the STUN-only fallback. Cached +
+   * single-flighted so a burst of `peer.joined` events shares one mint.
+   * Never throws — a TURN outage degrades to STUN, it doesn't break
+   * connections (they just won't traverse symmetric NAT).
+   */
+  private getIceServers(): Promise<RTCIceServer[]> {
+    const now = Date.now();
+    if (this.turnCache && this.turnCache.expiresAt > now) {
+      return Promise.resolve(this.turnCache.iceServers);
+    }
+    if (this.turnInFlight) return this.turnInFlight;
+
+    const p = this.fetchTurnCredentials().then((turn) => {
+      if (turn) {
+        this.turnCache = {
+          iceServers: turn,
+          expiresAt: Date.now() + TURN_CACHE_TTL_MS,
+        };
+        return turn;
+      }
+      // Negative-cache the STUN fallback briefly so an outage / unconfigured
+      // TURN doesn't re-mint on every connection.
+      this.turnCache = {
+        iceServers: this.iceServers,
+        expiresAt: Date.now() + TURN_NEGATIVE_TTL_MS,
+      };
+      return this.iceServers;
+    });
+    this.turnInFlight = p;
+    void p.finally(() => {
+      if (this.turnInFlight === p) this.turnInFlight = null;
+    });
+    return p;
+  }
+
+  /**
+   * Mint TURN credentials from the signaling worker's `/turn-credentials`
+   * endpoint. The daemon is the SOLE minter (clients get creds relayed in
+   * the offer), so we prove pubkey ownership with an Ed25519 signature over
+   * a `turn/v1/...` domain-tagged message — distinct from the signaling-
+   * connect signature so neither is replayable as the other. Returns the
+   * one-element ICE-server list on success, or null on any failure.
+   */
+  private async fetchTurnCredentials(): Promise<RTCIceServer[] | null> {
+    const scheme = this.signalingScheme === "wss" ? "https" : "http";
+    const url = `${scheme}://${this.signalingHost}/turn-credentials`;
+    const ts = Date.now();
+    const sig = cryptoSign(
+      null,
+      Buffer.from(`turn/v1/${this.identity.publicKeyB64}/${ts}`),
+      this.identity.privateKey,
+    ).toString("base64url");
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          pubkey: this.identity.publicKeyB64,
+          ts,
+          sig,
+        }),
+      });
+      if (!res.ok) {
+        this.log("turn.mint_unavailable", { status: res.status });
+        return null;
+      }
+      const data = (await res.json()) as { iceServers?: RTCIceServer };
+      if (!data.iceServers) return null;
+      this.log("turn.minted");
+      return [data.iceServers];
+    } catch (err) {
+      this.log("turn.fetch_error", { error: (err as Error).message });
+      return null;
+    }
+  }
+
   // ─── Helpers ────────────────────────────────────────────────────
 
   private knownClientByPubkey(pubkey: string) {