@stim-cli/server 1.10.0 → 1.10.1

package/README.md

@@ -22,7 +22,12 @@ stim-server devices revoke <id>   # revoke a paired device
 
 `GET http://127.0.0.1:7787/health` answers requests from this Mac with the
 server's name, versions, protocol, `stimHome`, and the Tailscale state it
-started with. Stim Desktop uses it to find a running server. A request through
+started with. While Tailscale runs, it also carries `route`, read from
+`tailscale serve status --json` on each request: `routed` with the HTTPS
+`port` that proxies to the server, `funneled` with the Funnel `ports` that do,
+`missing`, or `unknown` with a `reason`; the last three carry the `port` the
+setup command would use. Stim Desktop uses it to find a running server and
+show its route. A request through
 `tailscale serve`, on a Tailscale address, or with a `Host` other than
 `127.0.0.1` or `localhost` gets HTTP 426, like any other plain HTTP request.
 
@@ -40,12 +45,23 @@ same tailnet or with the Mac shared to the phone's user.
 
 `stim-server` listens only on `127.0.0.1` and on the Mac's Tailscale
 addresses, never on every interface. Run this once so clients can use
-`wss://<mac>.<tailnet>.ts.net` with a valid certificate:
+`wss://<mac>.<tailnet>.ts.net:7443` with a valid certificate:
 
 ```bash
-tailscale serve --bg http://127.0.0.1:7787
+tailscale serve --bg --https=7443 http://127.0.0.1:7787
 ```
 
+The dedicated port 7443 keeps the server tailnet only and leaves port 443 to
+other apps. Do not serve `stim-server` on a port where Tailscale Funnel is on:
+Funnel makes every handler on that port reachable from the public internet.
+
+`stim-server` reads `tailscale serve status --json` at start and on every
+`pair`. It uses the HTTPS port whose `/` handler proxies to its loopback port,
+preferring 7443. Without such a route, it assumes 7443 and prints the command
+above, or the next free port when 7443 is taken. It never suggests a Funnel
+port. Any handler, at any path, or TCP forward that reaches the server on a
+Funnel port makes it public, and `pair` refuses.
+
 When Tailscale is not running, `stim-server` listens on loopback only and
 says so on stderr. Start Tailscale, then restart `stim-server`.
 
@@ -54,9 +70,13 @@ says so on stderr. Start Tailscale, then restart `stim-server`.
 `stim-server pair` prints the JSON that the pairing QR code encodes:
 
 ```json
-{ "v": 1, "name": "Janic's MacBook Pro", "endpoint": "wss://janics-mbp.tail1234.ts.net", "pairingToken": "..." }
+{ "v": 1, "name": "Janic's MacBook Pro", "endpoint": "wss://janics-mbp.tail1234.ts.net:7443", "pairingToken": "..." }
 ```
 
+The endpoint names the route's port, and omits it for 443. When a route to
+the server is on a port with Funnel on, `pair` refuses and exits 1 without
+creating a token.
+
 The pairing token works once and expires after 5 minutes. A client spends it in
 `hello` and receives a random device token, which it presents on every later
 connection. The server stores only the SHA-256 hash of each token.

package/dist/{protocol-dn2_TUeH.mjs → protocol-B3k9Ykuu.mjs}

@@ -366,6 +366,20 @@ function protocolJsonSchema() {
 						}
 					}
 				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"delayed"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "frame-delayed" },
+						subscription: { type: "string" },
+						delayed: { type: "boolean" }
+					}
+				},
 				{
 					type: "object",
 					required: [

package/dist/protocol.d.mts

@@ -178,10 +178,19 @@ interface FrameEvent {
   /** Base64-encoded image bytes. */
   data: string;
 }
-type ServerEvent = StatusEvent | LogsEvent | FrameEvent | ErrorEvent;
+/**
+ * Captures for a `frames.subscribe` subscription are slow or a timed-out capture is being retried; the
+ * client keeps showing its last frame. Followed by `delayed: false` once captures recover.
+ */
+interface FrameDelayedEvent {
+  event: "frame-delayed";
+  subscription: string;
+  delayed: boolean;
+}
+type ServerEvent = StatusEvent | LogsEvent | FrameEvent | FrameDelayedEvent | ErrorEvent;
 type ServerMessage = ServerResponse | ServerEvent;
 type JsonSchema = Record<string, unknown>;
 /** The JSON Schema of every message on the wire, written to `dist/protocol.schema.json` at build time. */
 declare function protocolJsonSchema(): JsonSchema;
 //#endregion
-export { CAPABILITIES, Capability, ClientRequest, DeviceAuth, ERROR_CODES, ErrorCode, ErrorEvent, FrameEvent, FrameTarget, HelloParams, HelloResult, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_LOG_TAIL, METHODS, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, RequestId, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, UnsubscribeParams, WorkspaceParams, protocolJsonSchema };
+export { CAPABILITIES, Capability, ClientRequest, DeviceAuth, ERROR_CODES, ErrorCode, ErrorEvent, FrameDelayedEvent, FrameEvent, FrameTarget, HelloParams, HelloResult, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_LOG_TAIL, METHODS, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, RequestId, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, UnsubscribeParams, WorkspaceParams, protocolJsonSchema };

package/dist/protocol.mjs

@@ -1,2 +1,2 @@
-import { a as MAX_LOG_TAIL, c as PROTOCOL_VERSION, i as LOG_SOURCES, l as protocolJsonSchema, n as ERROR_CODES, o as METHODS, r as LOG_LEVELS, s as PROTOCOL_SCHEMA_FILE, t as CAPABILITIES } from "./protocol-dn2_TUeH.mjs";
+import { a as MAX_LOG_TAIL, c as PROTOCOL_VERSION, i as LOG_SOURCES, l as protocolJsonSchema, n as ERROR_CODES, o as METHODS, r as LOG_LEVELS, s as PROTOCOL_SCHEMA_FILE, t as CAPABILITIES } from "./protocol-B3k9Ykuu.mjs";
 export { CAPABILITIES, ERROR_CODES, LOG_LEVELS, LOG_SOURCES, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, protocolJsonSchema };

package/dist/protocol.schema.json

@@ -632,6 +632,26 @@
             }
           }
         },
+        {
+          "type": "object",
+          "required": [
+            "event",
+            "subscription",
+            "delayed"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "event": {
+              "const": "frame-delayed"
+            },
+            "subscription": {
+              "type": "string"
+            },
+            "delayed": {
+              "type": "boolean"
+            }
+          }
+        },
         {
           "type": "object",
           "required": [

package/dist/stim-server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as MAX_LOG_TAIL, i as LOG_SOURCES, r as LOG_LEVELS, t as CAPABILITIES } from "./protocol-dn2_TUeH.mjs";
+import { a as MAX_LOG_TAIL, i as LOG_SOURCES, r as LOG_LEVELS, t as CAPABILITIES } from "./protocol-B3k9Ykuu.mjs";
 import { createRequire } from "node:module";
 import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
 import { homedir, hostname, tmpdir } from "node:os";
@@ -407,10 +407,15 @@ var FeedPool = class {
 };
 //#endregion
 //#region src/frames.ts
+const DEFAULT_FRAME_LIMITS = {
+	toolTimeoutMs: 3e4,
+	slowCaptureMs: 3e3,
+	failureBackoffMs: 3e3,
+	maxConsecutiveFailures: 3
+};
 const MIN_INTERVAL_MS = 200;
 const MAX_INTERVAL_MS = 1e3;
 const MAX_CAPTURES = 2;
-const TOOL_TIMEOUT_MS = 1e4;
 const MAX_EDGE = 1280;
 const JPEG_QUALITY = 70;
 function deviceKey(device) {
@@ -469,7 +474,14 @@ function jpegSize(bytes) {
 	}
 	return null;
 }
-function runTool(file, args, env, running) {
+/** A rejection with `transient: true` is a timeout on a machine that is merely busy, not a broken capturer. */
+function timeoutError(message) {
+	return Object.assign(new Error(message), { transient: true });
+}
+function isTransient(error) {
+	return error instanceof Error && error.transient === true;
+}
+function runTool(file, args, env, running, timeoutMs) {
 	return new Promise((resolve, reject) => {
 		const child = spawn(file, args, {
 			env,
@@ -485,8 +497,8 @@ function runTool(file, args, env, running) {
 		let stderr = "";
 		const timer = setTimeout(() => {
 			terminate(child);
-			reject(/* @__PURE__ */ new Error(`${file} ${args[0]} did not finish within ${TOOL_TIMEOUT_MS / 1e3} s.`));
-		}, TOOL_TIMEOUT_MS);
+			reject(timeoutError(`${file} ${args[0]} did not finish within ${timeoutMs / 1e3} s.`));
+		}, timeoutMs);
 		child.stdout.on("data", (chunk) => chunks.push(chunk));
 		child.stderr.setEncoding("utf8");
 		child.stderr.on("data", (chunk) => {
@@ -515,7 +527,7 @@ async function stopTools(running, tmp) {
 * can be the unlit one and comes back black; `primary` is the panel CoreDevice reports as primary. A simctl
 * that rejects `primary` gets the default display instead.
 */
-function simulatorCapturer(udid, env) {
+function simulatorCapturer(udid, env, limits) {
 	let tmp = null;
 	let display = ["--display=primary"];
 	let closed = false;
@@ -528,7 +540,7 @@ function simulatorCapturer(udid, env) {
 		"--type=jpeg",
 		...display,
 		output
-	], env, running);
+	], env, running, limits.toolTimeoutMs);
 	return {
 		capture: async () => {
 			tmp ??= mkdtempSync(join(serverDir(), "frames-"));
@@ -654,7 +666,7 @@ function screenshotImage(body) {
 	for (const entry of protoFields(message)) if (entry.field === 4 && "bytes" in entry) return Buffer.from(entry.bytes);
 	throw new Error("getScreenshot returned no image.");
 }
-function emulatorCapturer(serial, env) {
+function emulatorCapturer(serial, env, limits) {
 	let session = null;
 	let tmp = null;
 	const running = /* @__PURE__ */ new Set();
@@ -673,18 +685,26 @@ function emulatorCapturer(serial, env) {
 		const chunks = [];
 		let status;
 		let message;
+		let timedOut = false;
 		const record = (headers) => {
 			if (headers["grpc-status"] !== void 0) status = String(headers["grpc-status"]);
 			if (headers["grpc-message"] !== void 0) message = String(headers["grpc-message"]);
 		};
-		request.setTimeout(TOOL_TIMEOUT_MS, () => request.close());
+		request.setTimeout(limits.toolTimeoutMs, () => {
+			timedOut = true;
+			request.close();
+		});
 		request.on("response", record);
 		request.on("trailers", record);
 		request.on("data", (chunk) => chunks.push(chunk));
-		request.on("error", (error) => reject(/* @__PURE__ */ new Error(`getScreenshot failed on ${serial}: ${error.message}`)));
+		request.on("error", (error) => {
+			const text = `getScreenshot failed on ${serial}: ${error.message}`;
+			reject(timedOut ? timeoutError(text) : new Error(text));
+		});
 		request.on("close", () => {
 			if (status === "0") return resolve(Buffer.concat(chunks));
-			reject(/* @__PURE__ */ new Error(`getScreenshot failed on ${serial}: ${message ?? `status ${status ?? "missing"}`}`));
+			const text = `getScreenshot failed on ${serial}: ${message ?? `status ${status ?? "missing"}`}`;
+			reject(timedOut ? timeoutError(text) : new Error(text));
 		});
 		request.end(screenshotRequest());
 	});
@@ -712,7 +732,7 @@ function emulatorCapturer(serial, env) {
 						input,
 						"--out",
 						output
-					], env, running);
+					], env, running, limits.toolTimeoutMs);
 					return readFileSync(output);
 				}
 			};
@@ -749,18 +769,23 @@ var FrameSource = class {
 	interval = MIN_INTERVAL_MS;
 	timer = null;
 	stopped = false;
+	delayed = false;
+	consecutiveFailures = 0;
 	capturer;
 	limiter;
+	limits;
 	ended;
-	constructor(capturer, limiter, ended) {
+	constructor(capturer, limiter, limits, ended) {
 		this.capturer = capturer;
 		this.limiter = limiter;
+		this.limits = limits;
 		this.ended = ended;
 		this.tick();
 	}
 	add(listener) {
 		this.listeners.add(listener);
 		if (this.last) listener.frame(this.last);
+		if (this.delayed) listener.delayed(true);
 		return () => {
 			if (this.listeners.delete(listener) && this.listeners.size === 0) this.stop();
 		};
@@ -773,6 +798,11 @@ var FrameSource = class {
 		this.ended();
 		return this.capturer.close();
 	}
+	setDelayed(delayed) {
+		if (this.delayed === delayed) return;
+		this.delayed = delayed;
+		for (const listener of this.listeners) listener.delayed(delayed);
+	}
 	async tick() {
 		this.timer = null;
 		let took = 0;
@@ -797,11 +827,19 @@ var FrameSource = class {
 				return true;
 			});
 			if (this.stopped) return;
+			this.consecutiveFailures = 0;
+			this.setDelayed(took > this.limits.slowCaptureMs);
 			if (changed) for (const listener of this.listeners) listener.frame(this.last);
 			this.interval = changed ? MIN_INTERVAL_MS : Math.min(this.interval * 2, MAX_INTERVAL_MS);
 			this.timer = setTimeout(() => void this.tick(), Math.max(this.interval - took, took));
 		} catch (error) {
 			if (this.stopped) return;
+			if (isTransient(error) && this.consecutiveFailures + 1 < this.limits.maxConsecutiveFailures) {
+				this.consecutiveFailures++;
+				this.setDelayed(true);
+				this.timer = setTimeout(() => void this.tick(), this.limits.failureBackoffMs);
+				return;
+			}
 			const listeners = [...this.listeners];
 			this.stop();
 			for (const listener of listeners) listener.failed(error.message);
@@ -818,14 +856,16 @@ var FramePool = class {
 	sources = /* @__PURE__ */ new Map();
 	limiter = new Limiter(MAX_CAPTURES);
 	env;
-	constructor(env) {
+	limits;
+	constructor(env, limits = DEFAULT_FRAME_LIMITS) {
 		this.env = env;
+		this.limits = limits;
 	}
 	subscribe(device, listener) {
 		const key = deviceKey(device);
 		let source = this.sources.get(key);
 		if (!source) {
-			const created = new FrameSource(device.platform === "ios" ? simulatorCapturer(device.udid, this.env) : emulatorCapturer(device.serial, this.env), this.limiter, () => {
+			const created = new FrameSource(device.platform === "ios" ? simulatorCapturer(device.udid, this.env, this.limits) : emulatorCapturer(device.serial, this.env, this.limits), this.limiter, this.limits, () => {
 				if (this.sources.get(key) === created) this.sources.delete(key);
 			});
 			this.sources.set(key, created);
@@ -914,6 +954,8 @@ var LogBatcher = class {
 //#region src/tailscale.ts
 const MAC_APP_BINARY = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
 const TIMEOUT_MS = 3e3;
+/** The tailnet-only HTTPS port the setup command serves stim-server on. */
+const SERVE_PORT = 7443;
 function executable(path) {
 	try {
 		accessSync(path, constants.X_OK);
@@ -967,6 +1009,124 @@ function tailscaleStatus(binary, env) {
 		};
 	}
 }
+function reaches(address, target, hosts) {
+	if (typeof address !== "string") return null;
+	let url;
+	try {
+		url = new URL(address.includes("://") ? address : `tcp://${address}`);
+	} catch {
+		return null;
+	}
+	return hosts.has(url.hostname) && url.port === String(target) ? url : null;
+}
+function portOf(hostPort) {
+	return Number(hostPort.slice(hostPort.lastIndexOf(":") + 1));
+}
+/**
+* Reads `tailscale serve status --json`, an ipn.ServeConfig: `TCP` maps a port to `{ HTTPS }` or
+* `{ TCPForward }`, `Web` maps `<host>:<port>` to `{ Handlers: { <mount>: { Proxy } } }`,
+* `AllowFunnel` maps `<host>:<port>` to true, and `Foreground` holds the same shape per
+* foreground session. Any handler or TCP forward that reaches the server on a Funnel port exposes
+* it; only a `/` HTTP proxy on an HTTPS port is a route a client can use.
+*/
+function parseServeStatus(value, target, ips) {
+	if (!isJsonObject(value)) return {
+		state: "unknown",
+		reason: "it printed no serve config",
+		port: SERVE_PORT
+	};
+	const hosts = /* @__PURE__ */ new Set([
+		"127.0.0.1",
+		"localhost",
+		"[::1]",
+		"0.0.0.0",
+		"[::]",
+		...ips.map((ip) => ip.includes(":") ? `[${ip}]` : ip)
+	]);
+	const configs = [value, ...isJsonObject(value.Foreground) ? Object.values(value.Foreground) : []].filter(isJsonObject);
+	const used = /* @__PURE__ */ new Set();
+	const funneled = /* @__PURE__ */ new Set();
+	const reaching = /* @__PURE__ */ new Set();
+	const routes = /* @__PURE__ */ new Set();
+	for (const config of configs) {
+		const tcp = isJsonObject(config.TCP) ? config.TCP : {};
+		for (const [port, listener] of Object.entries(tcp)) {
+			used.add(Number(port));
+			if (isJsonObject(listener) && reaches(listener.TCPForward, target, hosts)) reaching.add(Number(port));
+		}
+		for (const [hostPort, allowed] of Object.entries(isJsonObject(config.AllowFunnel) ? config.AllowFunnel : {})) if (allowed === true) funneled.add(portOf(hostPort));
+		for (const [hostPort, web] of Object.entries(isJsonObject(config.Web) ? config.Web : {})) {
+			const port = portOf(hostPort);
+			const listener = tcp[String(port)];
+			const https = isJsonObject(listener) && listener.HTTPS === true;
+			const handlers = isJsonObject(web) && isJsonObject(web.Handlers) ? web.Handlers : {};
+			for (const [mount, handler] of Object.entries(handlers)) {
+				const url = isJsonObject(handler) ? reaches(handler.Proxy, target, hosts) : null;
+				if (!url) continue;
+				reaching.add(port);
+				if (https && mount === "/" && url.protocol === "http:" && url.pathname === "/") routes.add(port);
+			}
+		}
+	}
+	let free = SERVE_PORT;
+	while (used.has(free) || funneled.has(free)) free++;
+	const exposed = [...reaching].filter((port) => funneled.has(port)).toSorted((a, b) => a - b);
+	if (exposed.length) return {
+		state: "funneled",
+		ports: exposed,
+		port: free
+	};
+	const tailnet = [...routes].toSorted((a, b) => a - b);
+	if (tailnet.length) return {
+		state: "routed",
+		port: tailnet.includes(SERVE_PORT) ? SERVE_PORT : tailnet[0]
+	};
+	return {
+		state: "missing",
+		port: free
+	};
+}
+function serveRoute(binary, env, target, ips, timeoutMs = TIMEOUT_MS) {
+	if (!binary) return Promise.resolve({
+		state: "unknown",
+		reason: "the tailscale command was not found",
+		port: SERVE_PORT
+	});
+	return new Promise((resolve) => {
+		execFile(binary, [
+			"serve",
+			"status",
+			"--json"
+		], {
+			env,
+			timeout: timeoutMs,
+			killSignal: "SIGKILL",
+			encoding: "utf8"
+		}, (error, stdout) => {
+			let route;
+			try {
+				route = error ? {
+					state: "unknown",
+					reason: error.killed ? "it timed out" : error.message.split("\n")[0],
+					port: SERVE_PORT
+				} : parseServeStatus(stdout.trim() ? JSON.parse(stdout) : {}, target, ips);
+			} catch {
+				route = {
+					state: "unknown",
+					reason: "it printed output that is not JSON",
+					port: SERVE_PORT
+				};
+			}
+			resolve(route);
+		});
+	});
+}
+function tailnetEndpoint(dnsName, port) {
+	return port === 443 ? `wss://${dnsName}` : `wss://${dnsName}:${port}`;
+}
+function serveCommand(port, target) {
+	return `tailscale serve --bg --https=${port} http://127.0.0.1:${target}`;
+}
 /** Reads `tailscale whois --json`: the peer's node (`Node.StableID`, `Node.Name`) and user (`UserProfile.LoginName`). */
 function parseWhois(value) {
 	if (!isJsonObject(value) || !isJsonObject(value.Node)) return null;
@@ -1044,6 +1204,7 @@ const STATUS_FEED = {
 	keep: 1,
 	label: "stim status --watch"
 };
+const HEALTH_ROUTE_TIMEOUT_MS = 1e3;
 const COMMAND_LIMITS = {
 	timeoutMs: 6e4,
 	maxOutputBytes: 33554432
@@ -1110,7 +1271,11 @@ async function startServer(options) {
 	const limiter = new FailureLimiter(options.maxAuthFailures ?? 5, options.failureWindowMs ?? 6e4);
 	const authTimeoutMs = options.authTimeoutMs ?? 5e3;
 	const feeds = new FeedPool(options.stimCli, options.env);
-	const frames = new FramePool(options.env);
+	const frameLimits = {
+		...DEFAULT_FRAME_LIMITS,
+		...options.frameLimits
+	};
+	const frames = new FramePool(options.env, frameLimits);
 	const running = /* @__PURE__ */ new Set();
 	const logLimits = {
 		...LOG_LIMITS,
@@ -1389,6 +1554,13 @@ async function startServer(options) {
 					pending = frame;
 					if (!retry) flush();
 				},
+				delayed: (delayed) => {
+					if (!ended) send(socket, {
+						event: "frame-delayed",
+						subscription,
+						delayed
+					});
+				},
 				failed: end
 			};
 			let unsubscribeStatus = null;
@@ -1529,6 +1701,14 @@ async function startServer(options) {
 		stimHome: configDir(),
 		tailscale: healthTailscale(options.tailscaleState)
 	};
+	const answerHealth = async (response) => {
+		const tailscale = options.tailscaleState;
+		const route = tailscale.state === "running" && tailscale.dnsName ? await serveRoute(options.tailscale, options.env, addresses[0].port, tailscale.ips, HEALTH_ROUTE_TIMEOUT_MS) : void 0;
+		response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({
+			...health,
+			route
+		}));
+	};
 	const servers = [];
 	const addresses = [];
 	const close = async () => {
@@ -1547,7 +1727,7 @@ async function startServer(options) {
 		for (const host of options.hosts) {
 			const server = createServer((request, response) => {
 				if (localHealthRequest(request)) {
-					response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(health));
+					answerHealth(response);
 					return;
 				}
 				response.writeHead(426, { "content-type": "text/plain" }).end("stim-server speaks WebSocket only.\n");
@@ -1590,12 +1770,18 @@ function fail(message) {
 	console.error(`stim-server: ${message}`);
 	process.exit(1);
 }
-function tailscaleNote(tailscale, port) {
-	const remedy = `Remote clients cannot connect until Tailscale runs; then restart stim-server and run \`tailscale serve --bg http://127.0.0.1:${port}\` once.`;
+function tailscaleNote(tailscale) {
+	const remedy = `Remote clients cannot connect until Tailscale runs; then restart stim-server, which prints the \`tailscale serve\` command to run once.`;
 	if (tailscale.state === "not-running") return `Tailscale is not running (${tailscale.backendState}). ${remedy}`;
 	if (tailscale.state === "unavailable") return `Tailscale is unavailable: ${tailscale.reason}. ${remedy}`;
 	return null;
 }
+function routeNote(route, port) {
+	if (route.state === "missing") return `No \`tailscale serve\` route reaches port ${port}, so phones cannot connect yet. Run this once to serve it on a tailnet-only port: \`${serveCommand(route.port, port)}\``;
+	if (route.state === "unknown") return `Could not read \`tailscale serve status --json\` (${route.reason}); assuming stim-server is served on port ${route.port}.`;
+	if (route.state === "funneled") return `Tailscale Funnel is on for port ${route.ports.join(", ")}, which proxies to stim-server, so the server is reachable from the public internet. Remove that handler (see \`tailscale serve status\`), then serve stim-server on a tailnet-only port: \`${serveCommand(route.port, port)}\``;
+	return null;
+}
 function macName(tailscale) {
 	return tailscale.state === "running" && tailscale.hostName || hostname();
 }
@@ -1628,8 +1814,13 @@ async function serve(port) {
 	}
 	console.log(`stim-server ${pkg.version} (stim ${stim.version}, protocol 1)`);
 	for (const { host, port: bound } of server.addresses) console.log(`listening on ws://${host.includes(":") ? `[${host}]` : host}:${bound}`);
-	if (tailscale.state === "running" && tailscale.dnsName) console.log(`tailnet endpoint: wss://${tailscale.dnsName}`);
-	const note = tailscaleNote(tailscale, port);
+	let note = tailscaleNote(tailscale);
+	if (tailscale.state === "running" && tailscale.dnsName) {
+		const route = await serveRoute(tailscaleBinary, env, port, tailscale.ips);
+		if (route.state !== "funneled") console.log(`tailnet endpoint: ${tailnetEndpoint(tailscale.dnsName, route.port)}`);
+		note = routeNote(route, port);
+		if (route.state === "funneled") note = `${note} Pairing is refused until then.`;
+	}
 	if (note) console.error(note);
 	const shutdown = () => {
 		server.close().then(() => process.exit(0));
@@ -1638,14 +1829,23 @@ async function serve(port) {
 	process.on("SIGTERM", shutdown);
 	process.on("SIGHUP", shutdown);
 }
-function pair(port, json) {
-	const tailscale = tailscaleStatus(findTailscale(process.env), process.env);
+async function pair(port, json) {
+	const binary = findTailscale(process.env);
+	const tailscale = tailscaleStatus(binary, process.env);
+	let endpoint = `ws://127.0.0.1:${port}`;
+	let note = tailscaleNote(tailscale);
+	if (note) note = `${note} The endpoint above only works on this Mac.`;
+	if (tailscale.state === "running" && tailscale.dnsName) {
+		const route = await serveRoute(binary, process.env, port, tailscale.ips);
+		if (route.state === "funneled") fail(`refusing to pair. ${routeNote(route, port)}`);
+		endpoint = tailnetEndpoint(tailscale.dnsName, route.port);
+		note = routeNote(route, port);
+	}
 	const { token, expiresAt } = createPairingToken();
-	const running = tailscale.state === "running";
 	const payload = {
 		v: 1,
 		name: macName(tailscale),
-		endpoint: running && tailscale.dnsName ? `wss://${tailscale.dnsName}` : `ws://127.0.0.1:${port}`,
+		endpoint,
 		pairingToken: token
 	};
 	if (json) return void console.log(JSON.stringify({
@@ -1654,8 +1854,7 @@ function pair(port, json) {
 	}));
 	console.log(JSON.stringify(payload));
 	console.error(`The pairing token is single use and expires at ${expiresAt}.`);
-	const note = tailscaleNote(tailscale, port);
-	if (note) console.error(`${note} The endpoint above only works on this Mac.`);
+	if (note) console.error(note);
 }
 function describe(device) {
 	const from = device.identity.kind === "local" ? "this Mac" : `${device.identity.nodeName || device.identity.nodeId}${device.identity.user ? ` (${device.identity.user})` : ""}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/server",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "description": "Serves Stim status to paired read-only clients over Tailscale.",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
     "./protocol.schema.json": "./dist/protocol.schema.json"
   },
   "dependencies": {
-    "@stim-cli/core": "^1.10.0",
-    "stim": "1.10.0",
+    "@stim-cli/core": "^1.10.1",
+    "stim": "1.10.1",
     "ws": "^8.21.3"
   },
   "devDependencies": {