Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
feat(host): relay remote screens through Cloudflare
leepokai49b7016324b8
diff --git a/.github/workflows/screen-linux.yml b/.github/workflows/screen-linux.ymlnew file mode 100644index 00000000..e622031d--- /dev/null+++ b/.github/workflows/screen-linux.yml@@ -0,0 +1,27 @@+name: Linux screen helper++on:+ push:+ branches: [main]+ paths: ["apps/screen-linux/**", ".github/workflows/screen-linux.yml"]+ pull_request:+ paths: ["apps/screen-linux/**", ".github/workflows/screen-linux.yml"]++jobs:+ test:+ runs-on: ubuntu-24.04+ defaults:+ run:+ working-directory: apps/screen-linux+ steps:+ - uses: actions/checkout@v4+ - run: sudo apt-get update && sudo apt-get install -y --no-install-recommends libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev+ - uses: dtolnay/rust-toolchain@stable+ with:+ components: clippy, rustfmt+ - uses: Swatinem/rust-cache@v2+ with:+ workspaces: apps/screen-linux+ - run: cargo fmt --check+ - run: cargo clippy --all-targets -- -D warnings+ - run: cargo testdiff --git a/apps/screen-linux/src/main.rs b/apps/screen-linux/src/main.rsindex 0c3c7aac..d6ab3a57 100644--- a/apps/screen-linux/src/main.rs+++ b/apps/screen-linux/src/main.rs@@ -126,7 +126,7 @@ async fn handle(h: &Arc<Helper>, method: &str, p: &Value) -> Result<Value> {}let d = display()?;let fd = h.portal.pipewire_fd().await?;- let session = stream::Session::new(id.clone(), &d, fd, h.clone())?;+ let session = stream::Session::new(id.clone(), &d, fd, h.clone(), p)?;let answer = session.answer(sdp).await?;h.sessions.lock().await.insert(id, session);json!({"sdp": answer})diff --git a/apps/screen-linux/src/stream.rs b/apps/screen-linux/src/stream.rsindex 6f2ac651..74457386 100644--- a/apps/screen-linux/src/stream.rs+++ b/apps/screen-linux/src/stream.rs@@ -3,7 +3,7 @@use crate::portal::Display;use crate::{Helper, input};-use anyhow::{Context, Result, anyhow};+use anyhow::{Context, Result, anyhow, bail};use base64::Engine as _;use gst::prelude::*;use serde_json::{Value, json};@@ -29,7 +29,13 @@ pub struct Session {}impl Session {- pub fn new(id: String, display: &Display, fd: OwnedFd, helper: Arc<Helper>) -> Result<Self> {+ pub fn new(+ id: String,+ display: &Display,+ fd: OwnedFd,+ helper: Arc<Helper>,+ config: &Value,+ ) -> Result<Self> {let pipeline = gst::Pipeline::new();let src = gst::ElementFactory::make("pipewiresrc").property("fd", fd.into_raw_fd())@@ -46,13 +52,18 @@ impl Session {let scale = make("videoscale")?;let size = make("capsfilter")?;let rate = make("videorate")?;- rate.set_property("max-rate", 60i32);+ let fps = config["maxFramerate"].as_i64().unwrap_or(60).clamp(1, 60);+ rate.set_property("max-rate", i32::try_from(fps)?);rate.set_property("drop-only", true);let convert2 = make("videoconvert")?;let queue = make("queue")?;queue.set_property_from_str("leaky", "downstream");queue.set_property("max-size-buffers", 2u32);- let encoder = encoder()?;+ let bitrate = config["maxBitrateBps"]+ .as_u64()+ .unwrap_or(u64::from(BITRATE_KBPS) * 1000)+ .clamp(100_000, u64::from(BITRATE_KBPS) * 1000);+ let encoder = encoder(u32::try_from(bitrate / 1000)?)?;let parse = make("h264parse")?;let pay = make("rtph264pay")?;pay.set_property("config-interval", -1i32);@@ -70,6 +81,23 @@ impl Session {);let webrtc = make("webrtcbin")?;webrtc.set_property_from_str("bundle-policy", "max-bundle");+ if let Some(servers) = config["iceServers"].as_array() {+ for server in servers {+ for url in server["urls"].as_array().context("missing ICE URLs")? {+ let url = url.as_str().context("invalid ICE URL")?;+ let uri = ice_uri(+ url,+ server["username"].as_str(),+ server["credential"].as_str(),+ )?;+ if url.starts_with("stun:") {+ webrtc.set_property("stun-server", &uri);+ } else if !webrtc.emit_by_name::<bool>("add-turn-server", &[&uri]) {+ bail!("couldn't configure screen relay");+ }+ }+ }+ }let chain = [&src, &convert, &crop, &scale, &size, &rate, &convert2, &queue, &encoder, &parse, &pay,&rtp_caps, &webrtc,@@ -171,7 +199,7 @@ impl Session {self.webrtc.emit_by_name::<()>("set-local-description", &[&answer, &p]);done.await?;- for _ in 0..60 {+ for _ in 0..200 {if self.webrtc.property::<gst_webrtc::WebRTCICEGatheringState>("ice-gathering-state")@@ -192,6 +220,13 @@ impl Session {}pub fn close(self) {+ drop(self);+ }+}++impl Drop for Session {+ fn drop(&mut self) {+ // Negotiation failure must stop capture too, before the session enters the helper's map.let _ = self.pipeline.set_state(gst::State::Null);}}@@ -303,7 +338,36 @@ fn make(name: &str) -> Result<gst::Element> {.with_context(|| format!("GStreamer element {name} is missing"))}-fn encoder() -> Result<gst::Element> {+/// Convert WebRTC's ICE URL syntax to GStreamer's URI syntax without exposing credentials.+fn ice_uri(url: &str, username: Option<&str>, credential: Option<&str>) -> Result<String> {+ let (scheme, address) = url.split_once(':').context("invalid ICE URL")?;+ if scheme == "stun" {+ return Ok(format!("stun://{address}"));+ }+ if !matches!(scheme, "turn" | "turns") {+ bail!("unsupported ICE scheme");+ }+ let username = username.context("missing TURN username")?;+ let credential = credential.context("missing TURN credential")?;+ let escape = |s: &str| -> String {+ use std::fmt::Write as _;+ s.bytes().fold(String::new(), |mut out, byte| {+ if byte.is_ascii_alphanumeric() || b"-._~".contains(&byte) {+ out.push(char::from(byte));+ } else {+ let _ = write!(out, "%{byte:02X}");+ }+ out+ })+ };+ Ok(format!(+ "{scheme}://{}:{}@{address}",+ escape(username),+ escape(credential)+ ))+}++fn encoder(bitrate_kbps: u32) -> Result<gst::Element> {let name = ENCODERS.iter().find(|n| gst::ElementFactory::find(n).is_some())@@ -315,13 +379,13 @@ fn encoder() -> Result<gst::Element> {"x264enc" => {e.set_property_from_str("tune", "zerolatency");e.set_property_from_str("speed-preset", "veryfast");- e.set_property("bitrate", BITRATE_KBPS);+ e.set_property("bitrate", bitrate_kbps);e.set_property("key-int-max", 120u32);}- "openh264enc" => e.set_property("bitrate", BITRATE_KBPS * 1000),+ "openh264enc" => e.set_property("bitrate", bitrate_kbps * 1000),_ => {if e.has_property("bitrate") {- e.set_property_from_str("bitrate", &BITRATE_KBPS.to_string());+ e.set_property_from_str("bitrate", &bitrate_kbps.to_string());}}}@@ -365,3 +429,27 @@ pub async fn screenshot(fd: OwnedFd, d: &Display, width: u32, height: u32) -> Relet map = buffer.map_readable()?;Ok(base64::engine::general_purpose::STANDARD.encode(map.as_slice()))}++#[cfg(test)]+mod ice_tests {+ #![allow(clippy::unwrap_used)]+ use super::*;++ #[test]+ fn turn_uri_preserves_transport_and_escapes_credentials() {+ assert_eq!(+ ice_uri(+ "turns:turn.cloudflare.com:443?transport=tcp",+ Some("a:b"),+ Some("c+/@")+ )+ .unwrap(),+ "turns://a%3Ab:c%2B%2F%[email protected]:443?transport=tcp"+ );+ assert_eq!(+ ice_uri("stun:stun.cloudflare.com:3478", None, None).unwrap(),+ "stun://stun.cloudflare.com:3478"+ );+ assert!(ice_uri("turn:turn.cloudflare.com:3478", None, None).is_err());+ }+}diff --git a/apps/screen-macos/ScreenHelper.swift b/apps/screen-macos/ScreenHelper.swiftindex 925f1050..a230b684 100644--- a/apps/screen-macos/ScreenHelper.swift+++ b/apps/screen-macos/ScreenHelper.swift@@ -1,6 +1,7 @@import AppKitimport ApplicationServicesimport CoreGraphics+@preconcurrency import WebRTC/// Serves the host's screen requests (see `host/src/screen.rs` for the protocol).@MainActor@@ -52,7 +53,13 @@ final class ScreenHelper {case "answer":guard let id = p["session"] as? String, let sdp = p["sdp"] as? String else { throw HelperError("session and sdp are required") }if let s = sessions[id] { return ["sdp": try await s.answer(offer: sdp)] }- let s = Session(id: id, display: display(p["display"]), helper: self)+ let iceServers = (p["iceServers"] as? [[String: Any]] ?? []).compactMap { value -> RTCIceServer? in+ guard let urls = value["urls"] as? [String], !urls.isEmpty else { return nil }+ return RTCIceServer(urlStrings: urls, username: value["username"] as? String, credential: value["credential"] as? String)+ }+ let s = Session(id: id, display: display(p["display"]), helper: self, iceServers: iceServers,+ maxBitrate: min(16_000_000, max(100_000, p["maxBitrateBps"] as? Int ?? 16_000_000)),+ maxFramerate: min(60, max(1, p["maxFramerate"] as? Int ?? 60)))sessions[id] = sdo {let answer = try await s.answer(offer: sdp)diff --git a/apps/screen-macos/Session.swift b/apps/screen-macos/Session.swiftindex 7ff3b72f..d1d71ab6 100644--- a/apps/screen-macos/Session.swift+++ b/apps/screen-macos/Session.swift@@ -22,10 +22,15 @@ final class Session: NSObject {private var awake: IOPMAssertionID = 0private var clipboardCount = NSPasteboard.general.changeCountprivate var clipboardTask: Task<Void, Never>?+ private var gatherTask: Task<Void, Never>?+ private let maxBitrate: Int+ private let maxFramerate: Intvar display: CGDirectDisplayID { capture.display }- init(id: String, display: CGDirectDisplayID, helper: ScreenHelper) {+ init(id: String, display: CGDirectDisplayID, helper: ScreenHelper, iceServers: [RTCIceServer], maxBitrate: Int, maxFramerate: Int) {+ self.maxBitrate = maxBitrate+ self.maxFramerate = maxFramerateself.id = idself.helper = helperlet source = Self.factory.videoSource(forScreenCast: true)@@ -34,9 +39,8 @@ final class Session: NSObject {super.init()let config = RTCConfiguration()config.sdpSemantics = .unifiedPlan- // No STUN/TURN: the phone already reaches this computer (LAN / Tailscale), so host- // candidates connect; TCP candidates cover networks that drop UDP.- config.iceServers = []+ // ICE prefers direct candidates; TURN covers NAT/firewalls when needed.+ config.iceServers = iceServersconfig.tcpCandidatePolicy = .enabledconfig.continualGatheringPolicy = .gatherOnceconfig.bundlePolicy = .maxBundle@@ -58,9 +62,14 @@ final class Session: NSObject {let answer = try await pc.answer(for: RTCMediaConstraints(mandatoryConstraints: nil, optionalConstraints: nil))try await pc.setLocalDescription(answer)await waitForCandidates()+ guard self.pc === pc else { throw HelperError("session closed") }if !capturing {tune()try await capture.start()+ guard self.pc === pc else {+ await capture.stop()+ throw HelperError("session closed")+ }capturing = truekeepAwake(true)watchClipboard()@@ -74,8 +83,8 @@ final class Session: NSObject {let p = sender.parametersp.degradationPreference = NSNumber(value: RTCDegradationPreference.maintainResolution.rawValue)for e in p.encodings {- e.maxBitrateBps = 16_000_000- e.maxFramerate = 60+ e.maxBitrateBps = NSNumber(value: maxBitrate)+ e.maxFramerate = NSNumber(value: maxFramerate)e.networkPriority = .high}sender.parameters = p@@ -83,14 +92,17 @@ final class Session: NSObject {private func waitForCandidates() async {guard pc?.iceGatheringState != .complete else { return }- Task {- try? await Task.sleep(for: .seconds(3))+ gatherTask?.cancel()+ gatherTask = Task {+ do { try await Task.sleep(for: .seconds(10)) } catch { return }self.finishGathering()}await withCheckedContinuation { gathered = $0 }}private func finishGathering() {+ gatherTask?.cancel()+ gatherTask = nilgathered?.resume()gathered = nil}diff --git a/cloud/README.md b/cloud/README.mdindex d75ee987..2468b856 100644--- a/cloud/README.md+++ b/cloud/README.md@@ -63,3 +63,12 @@ npx wrangler deploy --env dev # → https://dev-api.codync.devNew computers are limited to 10 per IP per minute with the Workers Rate Limiting binding`REGISTER_LIMITER` (`[[ratelimits]]`; each environment needs its own `namespace_id`).++## Remote screen relay++`POST /v1/host/screen-ice` issues one-hour Cloudflare Realtime TURN credentials to a+signed host belonging to an active account. The host first checks the calling+device's screen permission. The Worker requires `TURN_KEY_ID`, `TURN_KEY_API_TOKEN`+(server-only secrets) and `TURN_LIMITER` (12 issuances per account per minute).+The credentials are never cached in HTTP caches or stored in D1. See+[Remote screen setup and verification](../docs/features/remote-screen.md).diff --git a/cloud/src/api.ts b/cloud/src/api.tsindex 9c31e944..2ec7623a 100644--- a/cloud/src/api.ts+++ b/cloud/src/api.ts@@ -644,6 +644,53 @@ export async function hostRegister(c: Ctx) {return { computerId: id, owned: !!existing?.owner_user_id };}+/** The host attests that this device passed its local screen authorization (including QR pairing).+ * Requiring a claimed, active account prevents anonymous host registration from issuing paid TURN.+ */+export async function hostScreenIce(c: Ctx): Promise<Response> {+ const comp = await host(c);+ const dk = key(body(c), "deviceKey", 32);+ const owner = comp.owner_user_id && await c.env.DB.prepare(+ "SELECT user_id FROM accounts WHERE user_id = ? AND status = 'active'",+ ).bind(comp.owner_user_id).first();+ if (!owner) throw new ApiError("forbidden", "Sign in on the computer to use remote screen relay.");+ if (!c.env.TURN_KEY_ID || !c.env.TURN_KEY_API_TOKEN || !c.env.TURN_LIMITER) {+ throw new ApiError("screenRelayUnavailable", "Remote screen relay is not configured on this cloud.", 503);+ }+ const limit = await c.env.TURN_LIMITER.limit({ key: comp.owner_user_id! });+ if (!limit.success) throw new ApiError("rateLimited", "Too many screen connections. Try again in a minute.");+ const ttl = 3600;+ try {+ const res = await fetch(+ `https://rtc.live.cloudflare.com/v1/turn/keys/${encodeURIComponent(c.env.TURN_KEY_ID)}/credentials/generate-ice-servers`,+ {+ method: "POST",+ headers: { Authorization: `Bearer ${c.env.TURN_KEY_API_TOKEN}`, "Content-Type": "application/json" },+ body: JSON.stringify({ ttl, customIdentifier: `${comp.id}:${dk}` }),+ signal: AbortSignal.timeout(8000),+ },+ );+ if (!res.ok) throw new Error("TURN provider refused");+ const data = await res.json() as { iceServers?: unknown };+ if (!Array.isArray(data.iceServers) || !data.iceServers.length || data.iceServers.length > 8) throw new Error("Invalid TURN response");+ const iceServers = data.iceServers.map((entry: { urls?: unknown; username?: unknown; credential?: unknown }) => {+ if (!entry || !Array.isArray(entry.urls) || !entry.urls.length || !entry.urls.every(+ (url: unknown) => typeof url === "string" && /^(stun:stun|turns?:turn)\.cloudflare\.com:\d+(\?transport=(udp|tcp))?$/.test(url),+ )) throw new Error("Invalid TURN servers");+ const turn = entry.urls.some((url: string) => url.startsWith("turn"));+ if (turn && (typeof entry.username !== "string" || !entry.username || typeof entry.credential !== "string" || !entry.credential)) {+ throw new Error("Invalid TURN credentials");+ }+ return { urls: entry.urls, ...(turn ? { username: entry.username, credential: entry.credential } : {}) };+ });+ if (!iceServers.some((s) => s.urls.some((u: string) => u.startsWith("turn")))) throw new Error("Missing TURN server");+ return Response.json({ iceServers, expiresAt: c.now + ttl * 1000 }, { headers: { "Cache-Control": "no-store" } });+ } catch {+ // Provider bodies and credential-bearing errors must never reach logs or clients.+ throw new ApiError("screenRelayUnavailable", "Remote screen relay is temporarily unavailable. Try again shortly.", 503);+ }+}+export async function hostState(c: Ctx) {const comp = await host(c);const owner = comp.owner_user_iddiff --git a/cloud/src/index.ts b/cloud/src/index.tsindex 7eaaace0..2ab0e840 100644--- a/cloud/src/index.ts+++ b/cloud/src/index.ts@@ -13,6 +13,10 @@ export interface Env {RELAY: DurableObjectNamespace<ComputerRelay>;/** Workers Rate Limiting binding for new computer registrations. */REGISTER_LIMITER?: RateLimit;+ /** Server-only Cloudflare Realtime TURN key and credential-issuing token. */+ TURN_KEY_ID?: string;+ TURN_KEY_API_TOKEN?: string;+ TURN_LIMITER?: RateLimit;CLERK_ISSUER: string;CLERK_SECRET_KEY?: string;/** dev / e2e only: networkless verification with this public key. */@@ -44,6 +48,7 @@ const routes: [string, RegExp, Handler][] = [["DELETE", new RegExp(`^/v1/access-requests/${ID}$`), api.cancelAccessRequest],["POST", /^\/v1\/host\/register$/, api.hostRegister],["GET", /^\/v1\/host\/state$/, api.hostState],+ ["POST", /^\/v1\/host\/screen-ice$/, api.hostScreenIce],["POST", new RegExp(`^/v1/host/access-requests/${ID}/nonce$`), api.hostNonce],["POST", new RegExp(`^/v1/host/access-requests/${ID}/decision$`), api.hostDecision],["POST", new RegExp(`^/v1/host/grants/${ID}/revoke$`), api.hostRevokeGrant],diff --git a/cloud/test/screen.test.ts b/cloud/test/screen.test.tsnew file mode 100644index 00000000..faa89f6f--- /dev/null+++ b/cloud/test/screen.test.ts@@ -0,0 +1,95 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import worker, { type Env } from "../src/index";+import { AUTHORITY, ORIGIN, env, newHost, type TestHost } from "./helpers";+import * as ref from "./ref";++const path = "/v1/host/screen-ice";+const deviceKey = ref.b64url(ref.signKey().pub);+const servers = [+ { urls: ["stun:stun.cloudflare.com:3478"] },+ { urls: ["turn:turn.cloudflare.com:3478?transport=udp", "turns:turn.cloudflare.com:443?transport=tcp"], username: "short-user", credential: "short-secret" },+];++async function claimedHost() {+ const host = await newHost();+ const userId = `turn_${crypto.randomUUID()}`;+ await env.DB.prepare("INSERT INTO accounts(user_id, created_at) VALUES (?, ?)").bind(userId, Date.now()).run();+ await env.DB.prepare("UPDATE computers SET owner_user_id = ? WHERE id = ?").bind(userId, host.cid).run();+ return { host, userId };+}++function request(host: TestHost, overrides: Partial<Env> = {}, body = { deviceKey }) {+ const bytes = ref.enc.encode(JSON.stringify(body));+ const sig = ref.signRequest(host.sign, { method: "POST", authority: AUTHORITY, pathAndQuery: path, body: bytes });+ return worker.fetch(new Request(ORIGIN + path, {+ method: "POST", headers: { "Codync-Sig": sig }, body: bytes,+ }), { ...env, TURN_KEY_ID: "test-key", TURN_KEY_API_TOKEN: "server-secret", ...overrides }, {} as ExecutionContext);+}++afterEach(() => vi.restoreAllMocks());++describe("screen relay credentials", () => {+ it("issues expiring credentials for a claimed host and tags device usage", async () => {+ const { host } = await claimedHost();+ const fetch = vi.spyOn(globalThis, "fetch").mockResolvedValue(Response.json({ iceServers: servers }));+ const start = Date.now();+ const res = await request(host);+ expect(res.status).toBe(200);+ expect(res.headers.get("Cache-Control")).toBe("no-store");+ const data = await res.json() as { iceServers: unknown; expiresAt: number };+ expect(data.iceServers).toEqual(servers);+ expect(data.expiresAt).toBeGreaterThanOrEqual(start + 3_600_000);+ expect(data.expiresAt).toBeLessThanOrEqual(Date.now() + 3_600_000);+ const [url, init] = fetch.mock.calls[0]!;+ expect(url).toBe("https://rtc.live.cloudflare.com/v1/turn/keys/test-key/credentials/generate-ice-servers");+ expect(JSON.parse(init!.body as string)).toEqual({ ttl: 3600, customIdentifier: `${host.cid}:${deviceKey}` });+ expect(JSON.stringify(data)).not.toContain("server-secret");+ });++ it("rejects anonymous registration, blocked computers and deleted accounts before contacting TURN", async () => {+ const fetch = vi.spyOn(globalThis, "fetch");+ const unclaimed = await newHost();+ expect((await request(unclaimed)).status).toBe(403);+ const { host, userId } = await claimedHost();+ await env.DB.prepare("UPDATE accounts SET status = 'deleted' WHERE user_id = ?").bind(userId).run();+ expect((await request(host)).status).toBe(403);+ await env.DB.prepare("UPDATE computers SET status = 'blocked' WHERE id = ?").bind(host.cid).run();+ expect((await request(host)).status).toBe(403);+ expect(fetch).not.toHaveBeenCalled();+ });++ it("requires host signature and a device identity", async () => {+ const res = await worker.fetch(new Request(ORIGIN + path, { method: "POST" }), env, {} as ExecutionContext);+ expect(res.status).toBe(401);+ const { host } = await claimedHost();+ expect((await request(host, {}, { deviceKey: "invalid" })).status).toBe(400);+ });++ it("reports missing setup and enforces the per-account issuance limit", async () => {+ const { host } = await claimedHost();+ expect((await request(host, { TURN_KEY_API_TOKEN: "" })).status).toBe(503);+ const fetch = vi.spyOn(globalThis, "fetch").mockImplementation(async () => Response.json({ iceServers: servers }));+ for (let i = 0; i < 12; i++) expect((await request(host)).status).toBe(200);+ expect((await request(host)).status).toBe(429);+ expect(fetch).toHaveBeenCalledTimes(12);+ });++ it.each([+ { iceServers: [] },+ { iceServers: [{ urls: ["turn:evil.example:3478"], username: "u", credential: "p" }] },+ { iceServers: [{ urls: ["turn:turn.cloudflare.com:3478"], username: "u" }] },+ { iceServers: [{ urls: ["stun:stun.cloudflare.com:3478"] }] },+ ])("rejects malformed provider responses", async (data) => {+ const { host } = await claimedHost();+ vi.spyOn(globalThis, "fetch").mockResolvedValue(Response.json(data));+ expect((await request(host)).status).toBe(503);+ });++ it("does not expose provider error bodies or secrets", async () => {+ const { host } = await claimedHost();+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("server-secret", { status: 401 }));+ const res = await request(host);+ expect(res.status).toBe(503);+ expect(await res.text()).not.toContain("server-secret");+ });+});diff --git a/cloud/wrangler.toml b/cloud/wrangler.tomlindex 8d47c5dd..8cd12f59 100644--- a/cloud/wrangler.toml+++ b/cloud/wrangler.toml@@ -29,6 +29,12 @@ name = "REGISTER_LIMITER"namespace_id = "1001"simple = { limit = 10, period = 60 }+# Credential issuance per account; separate from registration limits.+[[ratelimits]]+name = "TURN_LIMITER"+namespace_id = "1011"+simple = { limit = 12, period = 60 }+[triggers]crons = ["*/15 * * * *"]@@ -39,7 +45,7 @@ routes = [{ pattern = "dev-api.codync.dev", custom_domain = true }]vars = { CLERK_ISSUER = "https://sunny-mollusk-8651.clerk.accounts.dev" }d1_databases = [{ binding = "DB", database_name = "codync-dev", database_id = "0c03c398-3cec-4f06-a76e-998176ca19ae", migrations_dir = "migrations" }]durable_objects.bindings = [{ name = "RELAY", class_name = "ComputerRelay" }]-ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1002", simple = { limit = 10, period = 60 } }]+ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1002", simple = { limit = 10, period = 60 } }, { name = "TURN_LIMITER", namespace_id = "1012", simple = { limit = 12, period = 60 } }]triggers = { crons = ["*/15 * * * *"] }# local: wrangler dev / e2e with a local D1; CLERK_JWT_KEY is injected by the test (--var).@@ -48,4 +54,4 @@ name = "codync-cloud-local"vars = { CLERK_ISSUER = "https://clerk.test.local" }d1_databases = [{ binding = "DB", database_name = "codync-local", database_id = "local", migrations_dir = "migrations" }]durable_objects.bindings = [{ name = "RELAY", class_name = "ComputerRelay" }]-ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1003", simple = { limit = 10, period = 60 } }]+ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1003", simple = { limit = 10, period = 60 } }, { name = "TURN_LIMITER", namespace_id = "1013", simple = { limit = 12, period = 60 } }]diff --git a/docs/architecture/overview.md b/docs/architecture/overview.mdindex 5ee2f56d..785b30a0 100644--- a/docs/architecture/overview.md+++ b/docs/architecture/overview.md@@ -57,7 +57,7 @@ The product currently prioritizes one computer. Existing account-scoped aggregat`cloud/` implements `/v1`, Clerk authentication, computer registration/claim, host-approved access, WebSocket relay and mailbox. `relay/` implements APNs registration tickets and push forwarding. [Remote protocol](../reference/remote-relay.md) defines wire details; [Cloudflare testing](../guides/cloudflare-testing.md) distinguishes these paths during acceptance.-Remote screen uses the channel for signaling and WebRTC for media/input. Its traffic does not become a Cloudflare video relay. [Remote screen](../features/remote-screen.md) describes the helpers and current limitations.+Remote screen uses the channel for signaling and WebRTC for media/input. Cloudflare Realtime TURN forwards encrypted media/input when a cloud connection cannot establish a direct WebRTC path. [Remote screen](../features/remote-screen.md) describes the helpers and current limitations.## Release and environment boundariesdiff --git a/docs/features/remote-screen.md b/docs/features/remote-screen.mdindex 373e8820..ad35bf1f 100644--- a/docs/features/remote-screen.md+++ b/docs/features/remote-screen.md@@ -1,16 +1,58 @@# Remote screen-Remote screen lets a phone view and control a computer. Signaling travels through the host API (`screenOffer`); video and input use WebRTC. Passing a Cloudflare chat test does not prove that the media connection can traverse the current network. TURN is outside the current remote relay design.+Remote screen lets an authorized phone view and control a computer. Signaling travels through the end-to-end encrypted host API; video and input use WebRTC, including when a TURN server forwards the encrypted packets.++## Connection path++1. The phone calls `screenPrepare {relay}`. `relay` is true when its active host channel uses Cloudflare; direct LAN/Tailscale connections do not contact a STUN/TURN provider.+2. The host checks the `screen` scope and that screen access is enabled. For relay connections it signs `POST /v1/host/screen-ice {deviceKey}`. The Worker requires a registered, active computer belonging to an active account. The host attests the device's local authorization, so account grants and local QR pairing both work on a claimed computer.+3. The Worker issues Cloudflare Realtime credentials with a one-hour TTL, tags usage with `computerId:deviceKey`, and returns `Cache-Control: no-store`. Permanent TURN keys stay in Worker secrets.+4. The host reserves a random session ID bound to the calling device and keeps the exact ICE configuration in memory. The phone and helper use that configuration. Clients cannot supply arbitrary ICE servers to the host.+5. `screenOffer {session, sdp, display?}` carries the completed offer to the helper. Both peers gather for up to ten seconds. ICE prefers direct candidates and uses TURN when necessary, with UDP, TCP and TLS on port 443 available.+6. The phone reconnects with fresh credentials five minutes before expiry. The host checks active sessions every five seconds and closes expired sessions, revoked devices and expired account leases. A prepared session must start within one minute.++Connections prepared through the cloud use a **4 Mbps / 30 fps** encoding limit even if ICE subsequently finds a direct path. Direct sessions retain their platform defaults (Mac: 16 Mbps / 60 fps). These are encoding limits, not exact bandwidth or billing caps. TURN does not carry plaintext desktop content; WebRTC DTLS-SRTP and data-channel encryption remain between the phone and helper.++A cloud outage or missing TURN configuration produces an explicit error. A successful chat relay connection alone does not prove that media or input works.## Boundaries-- `host/src/screen.rs` coordinates access to the local helper.+- `host/src/screen.rs` coordinates access to the local helper and owns viewer sessions. Another device cannot renegotiate or close a session it does not own.- `apps/screen-macos/` is the macOS capture/input helper, installed through `SMAppService` and responsible for the OS permissions.-- `apps/screen-linux/` implements the Linux helper using desktop portals and GStreamer.+- `apps/screen-linux/` implements the Linux helper using desktop portals and GStreamer, including ICE URL conversion and TURN transport configuration.- Helpers communicate locally through `~/.codync/screen.sock`. SDP is non-trickle; input uses the `input` and `input-fast` data channels.- Screen access is off by default. Enabling through `setScreenEnabled` requires a loopback caller. Interactive OS permission prompts must be completed on the computer.-- Bots with their computer capability enabled receive the built-in `computer` MCP tools (`host/src/mcp.rs`). Their permission policy still applies.+- Bots with their computer capability enabled receive the built-in `computer` MCP tools (`host/src/mcp.rs`). Their permission policy still applies. An interactive phone can take over; bots may still look.+- Each device may hold four sessions; the host allows 32 total, including pending sessions. Credential issuance is limited to 12 requests per minute per account by `TURN_LIMITER` (Cloudflare's per-location rate limiter).+- Closing a session stops its media; issued TURN credentials remain usable until their one-hour TTL. Issuance limits and encoder limits do not constitute a hard monthly spending cap. Track Realtime egress by the credential's custom identifier.++## Cloud setup++Create a separate Cloudflare Realtime TURN key for each environment. Save its key ID as `TURN_KEY_ID` and its credential-issuing API token as `TURN_KEY_API_TOKEN`, both Worker secrets. Every environment needs the `TURN_LIMITER` binding in `cloud/wrangler.toml`.++From `cloud/`, for development:++```sh+npx wrangler secret put TURN_KEY_ID --env dev+npx wrangler secret put TURN_KEY_API_TOKEN --env dev+npm run deploy:dev+```++For production, omit `--env dev` and use `npm run deploy:main`. Secret prompts accept the values without putting them into shell history. Do not put them in the app, host database, checked-in files, or logs. Link the computer to a signed-in account before using TURN; unclaimed computers can still use direct screen connections.++References: [Cloudflare credential issuance](https://developers.cloudflare.com/realtime/turn/generate-credentials/), [usage analytics](https://developers.cloudflare.com/realtime/turn/analytics/), [pricing](https://developers.cloudflare.com/realtime/sfu/platform/pricing/).## Verification-Check screen permission, capture, input, disconnect and reconnect separately on each platform. Repeat over the intended remote network; a local screen preview or encrypted signaling success does not verify remote media. See [Cloudflare testing](../guides/cloudflare-testing.md) for transport checks and [architecture](../architecture/overview.md) for data flow.+Run cloud tests/type checking, host formatting/Clippy/tests, Swift package tests, and builds of the iOS app and Mac screen helper. Run Linux helper tests in a Linux environment with GStreamer and PipeWire development packages.++Live acceptance requires the configured Worker and fresh host/helper/phone builds:++- Check screen-recording and input permissions, capture, click/type/scroll, clipboard, display changes and closing the viewer.+- Repeat with the phone on cellular and the computer on a different network, without Tailscale. Verify a selected ICE candidate pair with `candidateType=relay` in WebRTC diagnostics and observe Realtime egress; signaling via Cloudflare alone is insufficient.+- Verify UDP-blocked connectivity using TURN over TCP/TLS 443.+- Verify Wi-Fi/cellular changes, reconnect after sleep and renewal before the one-hour expiry.+- Revoke the phone or disable screen access while streaming; input and media must stop. Verify a control-only device cannot call `screenPrepare` or `screenOffer`.+- Verify LAN/direct-only mode without internet access, and the explicit error when relay secrets are absent.++See [Cloudflare testing](../guides/cloudflare-testing.md) for transport checks and [architecture](../architecture/overview.md) for data flow.diff --git a/docs/reference/remote-relay.md b/docs/reference/remote-relay.mdindex 749f4c19..fb7f4ec3 100644--- a/docs/reference/remote-relay.md+++ b/docs/reference/remote-relay.md@@ -24,7 +24,7 @@ Shared deterministic [vectors](fixtures/remote-relay-vectors.json) and their [ge- SSH 目標設了 `ProxyJump`/`ProxyCommand` 時不做 keyscan、也不做 `SSH_ASKPASS` 首次確認:要求使用者先在終端機連過一次(host key 已在 `~/.ssh/known_hosts`)。少見情境,換來不必實作 askpass helper。- 推播選擇「加密 + NSE」而非「只送通用文字」:保留 Grok Bot 式的通知預覽。-明確不做(這一版):雲端保存聊天、Mac 當手機的 SSH gateway、手機原生 SSH、TURN、host 金鑰輪替後沿用舊授權、團隊共享。+明確不做(這一版):雲端保存聊天、Mac 當手機的 SSH gateway、手機原生 SSH、host 金鑰輪替後沿用舊授權、團隊共享。---@@ -310,7 +310,7 @@ blob = epk(32) ‖ sig(64) ‖ ct|---|---|---|| loopback 專用 | `setScreenEnabled`, `pairing`, `computerCall`, `teamCall`, `claimSign`, `unclaim`, `devices`, `revokeDevice`, `accessRequests`, `decideAccessRequest`, `cloudStatus`, `setCloud` | `Caller::Local`(loopback + token) || 配對中 | `pair` | 只在 pairing 狀態的 channel;配對完成後不可再呼叫 |-| screen scope | `screenOffer`, `screenClose`, `screenTakeover` | Local,或 scopes 含 `screen` 的裝置 |+| screen scope | `screenPrepare`, `screenOffer`, `screenClose`, `screenTakeover` | Local,或 scopes 含 `screen` 的裝置 || control scope | 其餘所有既有方法(`hello`, `sync`, `history`, `createBot`, `updateBot`, `deleteBot`, `markRead`, `send`, `stop`, `newSession`, `respondPermission`, `registerDevice`, `unregisterDevice`, `registerActivity`, `refreshBackends`, `usage`, `listDirs`, market/skills/connectors、`agentSetup`, `agentAuth`, `agentAuthenticate`, `setAgentEnv`, `termInput`, `termResize`, `termClose`, `screenStatus`) | Local,或 scopes 含 `control` 的裝置 |v1 發出的 grant 一律 `["control","screen"]`。@@ -541,4 +541,4 @@ The following implemented clarifications take precedence over the original contr- Copying `identity.json` creates competing connections for one computer identity; replacing host keys requires pairing again.- Revocation is enforced locally even when cloud synchronization fails; pending cloud revocations are retried.- Direct `ws://` still encrypts channel content, but exposes connection metadata to the local network.-- Mailbox retention is bounded and is not cloud transcript storage. TURN, phone-native SSH and team sharing are outside this contract.+- Mailbox retention is bounded and is not cloud transcript storage. Phone-native SSH and team sharing are outside this contract. Screen media uses the separate short-lived TURN flow in [Remote screen](../features/remote-screen.md).diff --git a/host/src/api/devices.rs b/host/src/api/devices.rsindex d05c92b9..d98d0ea7 100644--- a/host/src/api/devices.rs+++ b/host/src/api/devices.rs@@ -54,7 +54,7 @@ const LOCAL_ONLY: &[&str] = &["setCloud","setApproval",];-const SCREEN: &[&str] = &["screenOffer", "screenClose", "screenTakeover"];+const SCREEN: &[&str] = &["screenPrepare", "screenOffer", "screenClose", "screenTakeover"];/// A method the caller isn't allowed to call (403).#[derive(Debug)]@@ -226,6 +226,8 @@ mod tests {}assert!(permit(&both, "send").is_ok());assert!(permit(&both, "screenOffer").is_ok());+ assert!(permit(&both, "screenPrepare").is_ok());+ assert!(permit(&control, "screenPrepare").is_err());assert!(permit(&control, "screenOffer").is_err(), "screen needs the screen scope");assert!(permit(&control, "screenStatus").is_ok(), "status is control");assert!(permit(&Caller::Device { key: "k".into(), scopes: vec![] }, "hello").is_err());diff --git a/host/src/api/mod.rs b/host/src/api/mod.rsindex 52b0f5b8..e703be35 100644--- a/host/src/api/mod.rs+++ b/host/src/api/mod.rs@@ -815,12 +815,35 @@ pub async fn dispatch(hub: &Arc<Hub>, caller: &Caller, method: &str, b: Value) -json!({})}"screenStatus" => hub.screen.state(),+ "screenPrepare" => {+ if !hub.screen.enabled() {+ bail!("Remote screen is turned off on this computer.");+ }+ let ice = if b["relay"].as_bool().unwrap_or(false) {+ crate::remote::cloud::screen_ice(hub, caller.device_key()).await?+ } else {+ crate::screen::IceConfig::default()+ };+ let result = hub.screen.prepare(caller.device_key(), ice)?;+ let session = result["session"].as_str().context("missing screen session")?.to_owned();+ tokio::spawn(crate::screen::watch_viewer(hub.clone(), session, caller.device_key().to_owned()));+ result+ }"screenOffer" => {let display = b["display"].as_u64().and_then(|d| u32::try_from(d).ok());- hub.screen.offer(str_arg(&b, "sdp")?, b["session"].as_str(), display).await?+ let result =+ hub.screen.offer(caller.device_key(), str_arg(&b, "sdp")?, b["session"].as_str(), display).await?;+ if b["session"].as_str().is_none() {+ let session = result["session"].as_str().context("missing screen session")?.to_owned();+ tokio::spawn(crate::screen::watch_viewer(hub.clone(), session, caller.device_key().to_owned()));+ }+ result}"screenClose" => {- hub.screen.close(str_arg(&b, "session")?).await?;+ let session = str_arg(&b, "session")?;+ if hub.screen.owns_session(session, caller.device_key()) {+ hub.screen.close(session).await?;+ }json!({})}"screenTakeover" => {diff --git a/host/src/remote/cloud.rs b/host/src/remote/cloud.rsindex 02288dbc..3b6004ba 100644--- a/host/src/remote/cloud.rs+++ b/host/src/remote/cloud.rs@@ -268,6 +268,18 @@ pub async fn register(hub: &Hub, base: &str) -> Result<()> {Ok(())}+/// Short-lived media credentials, issued only after the host checks screen authorization.+pub async fn screen_ice(hub: &Hub, device_key: &str) -> Result<crate::screen::IceConfig> {+ let value =+ call(hub, &base(hub)?, Method::POST, "/v1/host/screen-ice", Some(&json!({"deviceKey": device_key}))).await?;+ let config: crate::screen::IceConfig =+ serde_json::from_value(value).context("invalid screen relay configuration")?;+ if config.ice_servers.is_empty() || config.expires_at <= now_ms() + 60_000 {+ bail!("the screen relay returned expired or empty credentials");+ }+ Ok(config)+}+// MARK: state (§4.3)#[derive(Deserialize)]diff --git a/host/src/screen.rs b/host/src/screen.rsindex 2e393c34..a91d4cc2 100644--- a/host/src/screen.rs+++ b/host/src/screen.rs@@ -14,9 +14,8 @@//! - `status` [`HelperStatus`]//! - `session {session, state: "connected" | "closed"}`//! - host → helper requests-//! - `answer {session, sdp, display?}` → `{sdp}`: non-trickle; the offer and-//! the answer carry every ICE candidate (host + TCP, no STUN/TURN: any-//! network that reaches this API reaches the helper).+//! - `answer {session, sdp, display?, iceServers, maxBitrateBps, maxFramerate}` → `{sdp}`:+//! non-trickle ICE, with short-lived STUN/TURN credentials for remote connections.//! - `close {session}`, `closeAll {}`//! - `screenshot {display, width, height}` → `{data}` (base64 JPEG, exactly//! that size)@@ -32,10 +31,10 @@use crate::LockExt;use crate::hub::Hub;-use anyhow::{Result, anyhow, bail};+use anyhow::{Context, Result, anyhow, bail};use serde::{Deserialize, Serialize};use serde_json::{Value, json};-use std::collections::{HashMap, HashSet};+use std::collections::HashMap;use std::sync::Arc;use std::sync::Mutex;use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};@@ -356,13 +355,43 @@ impl Control {}}+/// WebRTC ICE servers. Credentials are memory-only and must not be logged.+#[derive(Clone, Serialize, Deserialize)]+pub struct IceServer {+ pub urls: Vec<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub username: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub credential: Option<String>,+}++#[derive(Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct IceConfig {+ pub ice_servers: Vec<IceServer>,+ pub expires_at: i64,+}++impl Default for IceConfig {+ fn default() -> Self {+ Self { ice_servers: vec![], expires_at: crate::store::now_ms() + 3_600_000 }+ }+}++struct Viewer {+ owner: String,+ ice: IceConfig,+ started: bool,+ pending_until: i64,+}+pub struct Screen {enabled: AtomicBool,events: broadcast::Sender<Value>,link: Mutex<Option<Arc<Link>>>,status: Mutex<HelperStatus>,control: Mutex<Control>,- sessions: Mutex<HashSet<String>>,+ sessions: Mutex<HashMap<String, Viewer>>,next_link: AtomicU64,}@@ -391,6 +420,7 @@ impl Screen {pub fn state(&self) -> Value {let st = self.status.locked().clone();let connected = self.link.locked().is_some();+ let viewers = self.sessions.locked().values().filter(|v| v.started).count();let c = self.control.locked();json!({"enabled": self.enabled(),@@ -401,7 +431,7 @@ impl Screen {"displays": st.displays,"userControl": c.user,"agentBot": c.active_agent(),- "viewers": self.sessions.locked().len(),+ "viewers": viewers,})}@@ -427,18 +457,86 @@ impl Screen {// MARK: phone- /// Answers a WebRTC offer from the phone (a new session, or an ICE restart of `session`).- pub async fn offer(&self, sdp: &str, session: Option<&str>, display: Option<u32>) -> Result<Value> {+ /// Reserve one session before the phone gathers ICE; the host keeps the exact configuration.+ pub fn prepare(&self, owner: &str, ice: IceConfig) -> Result<Value> {+ self.link()?;+ let mut sessions = self.sessions.locked();+ let now = crate::store::now_ms();+ sessions.retain(|_, v| v.started || v.pending_until > now);+ if sessions.len() >= 32 || sessions.values().filter(|v| v.owner == owner).count() >= 4 {+ bail!("too many screen sessions; close another screen and try again");+ }+ let session = uuid::Uuid::new_v4().to_string();+ let result = json!({"session": session, "iceServers": ice.ice_servers, "expiresAt": ice.expires_at});+ sessions.insert(session, Viewer { owner: owner.to_owned(), ice, started: false, pending_until: now + 60_000 });+ Ok(result)+ }++ pub fn owns_session(&self, session: &str, owner: &str) -> bool {+ self.sessions.locked().get(session).is_some_and(|v| v.owner == owner)+ }++ /// Answers a prepared session or a direct offer from an older client.+ pub async fn offer(&self, owner: &str, sdp: &str, session: Option<&str>, display: Option<u32>) -> Result<Value> {let link = self.link()?;if !self.status.locked().capture {bail!("Codync isn't allowed to record this computer's screen yet. Allow it in System Settings there.");}- let session = session.map_or_else(|| uuid::Uuid::new_v4().to_string(), str::to_owned);- let res = link.request("answer", json!({"session": session, "sdp": sdp, "display": display})).await?;+ let session = match session {+ Some(id) => id.to_owned(),+ None => self.prepare(owner, IceConfig::default())?["session"]+ .as_str()+ .context("missing screen session")?+ .to_owned(),+ };+ let ice = {+ let sessions = self.sessions.locked();+ let viewer = sessions.get(&session).filter(|v| v.owner == owner).context("unknown screen session")?;+ let now = crate::store::now_ms();+ if viewer.ice.expires_at <= now || (!viewer.started && viewer.pending_until <= now) {+ bail!("screen connection expired; reconnect to continue");+ }+ viewer.ice.clone()+ };+ let remote = !ice.ice_servers.is_empty();+ let res = link+ .request(+ "answer",+ json!({+ "session": session, "sdp": sdp, "display": display, "iceServers": ice.ice_servers,+ "maxBitrateBps": if remote { 4_000_000 } else { 16_000_000 },+ "maxFramerate": if remote { 30 } else { 60 },+ }),+ )+ .await;+ let res = match res {+ Ok(res) => res,+ Err(error) => {+ // A helper can finish after the RPC times out. Keep retrying close until it acknowledges.+ if let Some(viewer) = self.sessions.locked().get_mut(&session) {+ viewer.ice.expires_at = 0;+ }+ if let Err(close_error) = self.close(&session).await {+ tracing::warn!(error = format!("{close_error:#}"), "couldn't close failed screen session");+ }+ return Err(error);+ }+ };let answer = res["sdp"].as_str().ok_or_else(|| anyhow!("the screen helper sent no answer"))?;- if self.sessions.locked().insert(session.clone()) {- self.emit();+ let accepted = {+ let mut sessions = self.sessions.locked();+ if let Some(viewer) = sessions.get_mut(&session) {+ viewer.started = true;+ true+ } else {+ false+ }+ };+ if !accepted || !self.enabled() {+ self.close(&session).await?;+ bail!("screen session closed while connecting");}+ self.emit();Ok(json!({"session": session, "sdp": answer}))}@@ -454,7 +552,7 @@ impl Screen {fn session_closed(&self, session: &str) {let removed = {let mut sessions = self.sessions.locked();- let removed = sessions.remove(session);+ let removed = sessions.remove(session).is_some();if sessions.is_empty() {// Nobody is watching: hand control back to the bots.self.control.locked().user = false;@@ -619,6 +717,29 @@ pub async fn computer(hub: &Arc<Hub>, bot: &str, tool: ComputerTool) -> Result<V}}+/// Media bypasses the API, so keep checking the device lease while a viewer is connected.+pub async fn watch_viewer(hub: Arc<Hub>, session: String, owner: String) {+ loop {+ tokio::time::sleep(Duration::from_secs(5)).await;+ let expired = {+ let sessions = hub.screen.sessions.locked();+ let Some(viewer) = sessions.get(&session) else { return };+ let now = crate::store::now_ms();+ viewer.ice.expires_at <= now || (!viewer.started && viewer.pending_until <= now)+ };+ let authorized = owner == "local"+ || crate::api::devices::authorize(&hub, &owner)+ .is_ok_and(|d| d.scopes.contains(&crate::store::Scope::Screen));+ if expired || !authorized || !hub.screen.enabled() {+ if let Err(error) = hub.screen.close(&session).await {+ tracing::warn!(error = format!("{error:#}"), "couldn't close expired screen session");+ continue;+ }+ return;+ }+ }+}+async fn shot(link: &Link, d: &Display) -> Result<Value> {let (width, height) = d.shot_size();let res = link.request("screenshot", json!({"display": d.id, "width": width, "height": height})).await?;@@ -852,12 +973,47 @@ mod tests {assert_eq!(t["children"][0]["frame"], json!([5.0, 5.0, 3.0, 3.0]));}+ #[test]+ fn prepared_sessions_are_bounded_and_do_not_count_as_viewers() {+ let (tx, _) = broadcast::channel(8);+ let screen = Screen::new(true, tx);+ let (tx, _) = mpsc::unbounded_channel();+ *screen.link.locked() =+ Some(Arc::new(Link { id: 1, tx, pending: Mutex::default(), next_id: AtomicI64::new(1) }));+ let config = IceConfig {+ ice_servers: vec![IceServer {+ urls: vec!["turns:turn.cloudflare.com:443?transport=tcp".into()],+ username: Some("u".into()),+ credential: Some("secret".into()),+ }],+ ..IceConfig::default()+ };+ let prepared = screen.prepare("phone", config).unwrap();+ let id = prepared["session"].as_str().unwrap();+ assert!(screen.owns_session(id, "phone"));+ assert!(!screen.owns_session(id, "other"));+ assert_eq!(prepared["iceServers"][0]["credential"], "secret");+ assert_eq!(screen.state()["viewers"], 0);+ assert!(!screen.state().to_string().contains("secret"));+ for _ in 0..3 {+ screen.prepare("phone", IceConfig::default()).unwrap();+ }+ assert!(screen.prepare("phone", IceConfig::default()).is_err());+ for viewer in screen.sessions.locked().values_mut() {+ viewer.pending_until = 0;+ }+ assert!(screen.prepare("phone", IceConfig::default()).is_ok());+ screen.enabled.store(false, Ordering::Relaxed);+ assert!(screen.prepare("phone", IceConfig::default()).is_err());+ }+#[tokio::test]async fn helper_roundtrip_over_the_socket() {let (tx, _) = broadcast::channel(8);let screen = Arc::new(Screen::new(true, tx));let (a, b) = UnixStream::pair().unwrap();- // Fake helper: reports a display, then answers every request with its method name.+ let (observed_tx, mut observed_rx) = mpsc::unbounded_channel();+ // Fake helper reports a display and records the host's ICE configuration.tokio::spawn(async move {let (rd, mut wr) = b.into_split();let status = json!({"jsonrpc": "2.0", "method": "status", "params": {"platform": "test", "capture": true, "displays": [retina()]}});@@ -865,6 +1021,7 @@ mod tests {let mut lines = BufReader::new(rd).lines();while let Ok(Some(l)) = lines.next_line().await {let m: Value = serde_json::from_str(&l).unwrap();+ observed_tx.send(m.clone()).unwrap();let res = json!({"jsonrpc": "2.0", "id": m["id"], "result": {"sdp": format!("answer to {}", m["params"]["sdp"].as_str().unwrap_or_default())}});wr.write_all(format!("{res}\n").as_bytes()).await.unwrap();}@@ -876,9 +1033,33 @@ mod tests {}tokio::time::sleep(Duration::from_millis(10)).await;}- let res = screen.offer("offer", None, None).await.unwrap();+ let res = screen.offer("local", "offer", None, None).await.unwrap();assert_eq!(res["sdp"], "answer to offer");assert_eq!(screen.state()["viewers"], 1);assert_eq!(screen.state()["displays"][0]["name"], "Built-in");+ let direct = observed_rx.recv().await.unwrap();+ assert_eq!(direct["params"]["iceServers"], json!([]));+ assert_eq!(direct["params"]["maxBitrateBps"], 16_000_000);+ let config = IceConfig {+ ice_servers: vec![IceServer {+ urls: vec!["turn:turn.cloudflare.com:3478?transport=udp".into()],+ username: Some("u".into()),+ credential: Some("p".into()),+ }],+ ..IceConfig::default()+ };+ screen.takeover(true);+ let prepared = screen.prepare("phone", config).unwrap();+ screen.session_closed(res["session"].as_str().unwrap());+ assert_eq!(screen.state()["userControl"], true, "renewal keeps takeover while the replacement is pending");+ let id = prepared["session"].as_str().unwrap();+ assert!(screen.offer("other", "offer", Some(id), None).await.is_err());+ screen.offer("phone", "offer", Some(id), None).await.unwrap();+ let remote = observed_rx.recv().await.unwrap();+ assert_eq!(remote["params"]["iceServers"], prepared["iceServers"]);+ assert_eq!(remote["params"]["maxBitrateBps"], 4_000_000);+ assert_eq!(remote["params"]["maxFramerate"], 30);+ screen.sessions.locked().get_mut(id).unwrap().ice.expires_at = 0;+ assert!(screen.offer("phone", "offer", Some(id), None).await.is_err());}}diff --git a/kit/Sources/CodyncKit/Client/ChannelTransport.swift b/kit/Sources/CodyncKit/Client/ChannelTransport.swiftindex 72e8784e..60e3cdd1 100644--- a/kit/Sources/CodyncKit/Client/ChannelTransport.swift+++ b/kit/Sources/CodyncKit/Client/ChannelTransport.swift@@ -24,6 +24,12 @@ public actor ChannelTransport: RemoteTransport {private let directBudget: Durationprivate let watchesNetwork: Bool+ /// The screen follows the active signaling route; direct-only connections never request TURN.+ public func screenRelayRequired() async throws -> Bool {+ try await ready(within: 20)+ return link?.route == .relay+ }+private var state: LinkState = .connectingprivate var lastSeen: Date?private var link: Link?diff --git a/kit/Sources/CodyncKit/Client/HostClient.swift b/kit/Sources/CodyncKit/Client/HostClient.swiftindex 564aca5c..5ff4f39e 100644--- a/kit/Sources/CodyncKit/Client/HostClient.swift+++ b/kit/Sources/CodyncKit/Client/HostClient.swift@@ -288,6 +288,11 @@ public extension HostClient {func screenStatus() async throws -> ScreenState { try await call("screenStatus") }+ func screenPrepare() async throws -> ScreenConnection {+ let relay = if let channel = transport as? ChannelTransport { try await channel.screenRelayRequired() } else { false }+ return try await call("screenPrepare", ["relay": relay])+ }+/// Sends a WebRTC offer (with all its ICE candidates); returns the session id and the answer./// Passing `session` restarts ICE on an existing session.func screenOffer(sdp: String, session: String?, display: UInt32?) async throws -> ScreenAnswer {diff --git a/kit/Sources/CodyncKit/Models/ScreenConnection.swift b/kit/Sources/CodyncKit/Models/ScreenConnection.swiftnew file mode 100644index 00000000..48b288a3--- /dev/null+++ b/kit/Sources/CodyncKit/Models/ScreenConnection.swift@@ -0,0 +1,15 @@+import Foundation++/// A host-owned screen session and its short-lived ICE configuration. Never persist credentials.+public struct ScreenConnection: Codable, Sendable {+ public var session: String+ public var iceServers: [ScreenIceServer]+ /// Unix milliseconds, matching the host/cloud API.+ public var expiresAt: Int64+}++public struct ScreenIceServer: Codable, Sendable {+ public var urls: [String]+ public var username: String?+ public var credential: String?+}diff --git a/kit/Sources/CodyncUI/Screen/ScreenSession.swift b/kit/Sources/CodyncUI/Screen/ScreenSession.swiftindex 4f6a89b1..eacdd4e6 100644--- a/kit/Sources/CodyncUI/Screen/ScreenSession.swift+++ b/kit/Sources/CodyncUI/Screen/ScreenSession.swift@@ -39,6 +39,10 @@ public final class ScreenSession {private var events: PeerEvents?private var gathered: CheckedContinuation<Void, Never>?private var recoverTask: Task<Void, Never>?+ private var gatherTask: Task<Void, Never>?+ private var renewTask: Task<Void, Never>?+ private var connectionTimer: Task<Void, Never>?+ private var generation = 0static let factory: RTCPeerConnectionFactory = {RTCInitializeSSL()@@ -57,19 +61,36 @@ public final class ScreenSession {do {try await connect()} catch {+ guard phase != .closed else { return }+ close()phase = .failed(error.localizedDescription)}}private func connect() async throws {+ let preparing = generation+ let connection = try await client.screenPrepare()+ guard generation == preparing, phase != .closed, !Task.isCancelled else {+ try? await client.screenClose(session: connection.session)+ throw CancellationError()+ }+ // Reserve the replacement before closing the old viewer so takeover survives renewal.+ let old = sessionteardown()+ let current = generation+ session = connection.session+ if let old { try? await client.screenClose(session: old) }+ try Task.checkCancellation()+ guard generation == current, phase != .closed else { throw CancellationError() }let config = RTCConfiguration()config.sdpSemantics = .unifiedPlan- config.iceServers = []+ config.iceServers = connection.iceServers.map {+ RTCIceServer(urlStrings: $0.urls, username: $0.username, credential: $0.credential)+ }config.tcpCandidatePolicy = .enabledconfig.continualGatheringPolicy = .gatherOnceconfig.bundlePolicy = .maxBundle- let events = PeerEvents(owner: self)+ let events = PeerEvents(owner: self, generation: current)guard let pc = Self.factory.peerConnection(with: config, constraints: Self.noConstraints, delegate: events) else {throw HostError.http(0, "Couldn't start the video connection.")}@@ -96,69 +117,96 @@ public final class ScreenSession {reliable?.delegate = eventstry await negotiate(pc)+ guard generation == current, phase != .closed else { throw CancellationError() }+ // Refresh both endpoints before TURN credentials expire, including an idle screen.+ let seconds = max(1, Double(connection.expiresAt) / 1000 - Date().timeIntervalSince1970 - 300)+ renewTask = Task { [weak self] in+ do { try await Task.sleep(for: .seconds(seconds)) } catch { return }+ guard let self, self.generation == current, self.phase != .closed else { return }+ self.phase = .reconnecting+ self.scheduleRecovery(after: .zero)+ }+ connectionTimer = Task { [weak self] in+ do { try await Task.sleep(for: .seconds(30)) } catch { return }+ guard let self, self.generation == current, self.phase != .live else { return }+ self.close()+ self.phase = .failed("Couldn't connect to the remote screen. Check the computer's connection and try again.")+ }}- /// Offer → host → answer. Also used for ICE restarts on the same session.+ /// Offer → host → answer with the reserved session’s ICE configuration.private func negotiate(_ pc: RTCPeerConnection) async throws {let offer = try await pc.offer(for: Self.noConstraints)try await pc.setLocalDescription(offer)await waitForCandidates(pc)+ try Task.checkCancellation()+ guard self.pc === pc, phase != .closed else { throw CancellationError() }let sdp = pc.localDescription?.sdp ?? offer.sdplet answer = try await client.screenOffer(sdp: sdp, session: session, display: display?.id)+ try Task.checkCancellation()+ guard self.pc === pc, phase != .closed else { throw CancellationError() }session = answer.sessiontry await pc.setRemoteDescription(RTCSessionDescription(type: .answer, sdp: answer.sdp))}private func waitForCandidates(_ pc: RTCPeerConnection) async {guard pc.iceGatheringState != .complete else { return }- Task {- try? await Task.sleep(for: .seconds(3))+ let current = generation+ gatherTask?.cancel()+ gatherTask = Task {+ do { try await Task.sleep(for: .seconds(10)) } catch { return }+ guard self.generation == current else { return }self.finishGathering()}await withCheckedContinuation { gathered = $0 }}- fileprivate func finishGathering() {+ fileprivate func finishGathering(generation: Int? = nil) {+ if let generation, generation != self.generation { return }+ gatherTask?.cancel()+ gatherTask = nilgathered?.resume()gathered = nil}- fileprivate func iceChanged(_ state: RTCIceConnectionState) {+ fileprivate func iceChanged(_ state: RTCIceConnectionState, generation: Int) {+ guard generation == self.generation, phase != .closed else { return }switch state {case .connected, .completed:- recoverTask?.cancel()- recoverTask = nil+ connectionTimer?.cancel()phase = .livelastError = nilcase .disconnected:- // Often recovers by itself (Wi-Fi ↔ cellular); restart ICE if it doesn't.+ // Often recovers by itself (Wi-Fi ↔ cellular); reconnect if it does not.phase = .reconnecting- scheduleRecovery(after: .seconds(2), restartIce: true)+ scheduleRecovery(after: .seconds(2))case .failed:phase = .reconnecting- scheduleRecovery(after: .zero, restartIce: false)+ scheduleRecovery(after: .zero)default:break}}- private func scheduleRecovery(after delay: Duration, restartIce: Bool) {+ private func scheduleRecovery(after delay: Duration) {recoverTask?.cancel()recoverTask = Task { [weak self] invar attempt = 0try? await Task.sleep(for: delay)while let self, !Task.isCancelled, self.phase == .reconnecting {do {- if restartIce, attempt == 0, let pc = self.pc {- pc.restartIce()- try await self.negotiate(pc)- } else {- try await self.connect()- }+ // Re-evaluate the signaling route after Wi-Fi/cellular changes and fetch fresh ICE credentials.+ try await self.connect()return} catch {+ guard !Task.isCancelled, self.phase != .closed else { return }log.info("screen reconnect failed: \(error.localizedDescription)")attempt += 1+ if attempt >= 3 {+ self.close()+ self.phase = .failed(error.localizedDescription)+ return+ }try? await Task.sleep(for: .seconds(min(Double(attempt) * 2, 10)))}}@@ -177,6 +225,9 @@ public final class ScreenSession {}private func teardown() {+ generation += 1+ renewTask?.cancel()+ connectionTimer?.cancel()finishGathering()reliable?.close()fast?.close()@@ -241,9 +292,11 @@ public final class ScreenSession {/// WebRTC delegate callbacks arrive on its signaling thread; this hops them to the main actor.private final class PeerEvents: NSObject, RTCPeerConnectionDelegate, RTCDataChannelDelegate, Sendable {private let owner: WeakBox+ private let generation: Int- @MainActor init(owner: ScreenSession) {+ @MainActor init(owner: ScreenSession, generation: Int) {self.owner = WeakBox(owner)+ self.generation = generation}func peerConnection(_ peerConnection: RTCPeerConnection, didChange stateChanged: RTCSignalingState) {}@@ -257,13 +310,15 @@ private final class PeerEvents: NSObject, RTCPeerConnectionDelegate, RTCDataChanfunc peerConnection(_ peerConnection: RTCPeerConnection, didChange newState: RTCIceConnectionState) {let owner = owner- Task { @MainActor in owner.value?.iceChanged(newState) }+ let generation = generation+ Task { @MainActor in owner.value?.iceChanged(newState, generation: generation) }}func peerConnection(_ peerConnection: RTCPeerConnection, didChange newState: RTCIceGatheringState) {guard newState == .complete else { return }let owner = owner- Task { @MainActor in owner.value?.finishGathering() }+ let generation = generation+ Task { @MainActor in owner.value?.finishGathering(generation: generation) }}func dataChannel(_ dataChannel: RTCDataChannel, didReceiveMessageWith buffer: RTCDataBuffer) {diff --git a/kit/Tests/CodyncKitTests/ChannelTransportTests.swift b/kit/Tests/CodyncKitTests/ChannelTransportTests.swiftindex e5303b6e..54c0d614 100644--- a/kit/Tests/CodyncKitTests/ChannelTransportTests.swift+++ b/kit/Tests/CodyncKitTests/ChannelTransportTests.swift@@ -238,6 +238,7 @@ private func waitFor(_ states: AsyncStream<LinkState>, _ match: (LinkState) -> Bcomputer.cloud = URL(string: "https://cloud.example.dev")let t = ChannelTransport(computer: computer, identity: v.identity, pairingCode: nil, dial: dial, watchesNetwork: false)await t.start()+ let screenRoute = Task { try await t.screenRelayRequired() }var it = sockets.makeAsyncIterator()// Some other host now answers at the saved LAN address; its reject isn't signed.let stranger = HostSide(try #require(await it.next()))@@ -249,6 +250,7 @@ private func waitFor(_ states: AsyncStream<LinkState>, _ match: (LinkState) -> Bawait relay.push(["t": "presence", "online": true, "lastSeenAt": NSNull()])try await relay.accept()#expect(await t.settled(within: .seconds(5)) == .ready(.relay))+ #expect(try await screenRoute.value)#expect(await !t.isStopped)await t.shutdown()}