@expo/serve-sim 0.1.54 → 0.2.0

package/dist/state.js

@@ -1 +1 @@
-import{tmpdir as Q}from"os";import{join as H}from"path";import{readdirSync as U,mkdirSync as V,writeFileSync as W,renameSync as X,readFileSync as Y,unlinkSync as Z}from"fs";var G=H(Q(),"serve-sim"),k=H(G,"server.json");function O(q){return H(G,`server-${q}.json`)}function x(q,z,B="/",C="127.0.0.1",K){let J=C==="0.0.0.0"||C==="::"?"127.0.0.1":C,M=B.replace(/^\/+/,"").replace(/\/+$/,""),N=M===""?"":`/${M}`;return{pid:process.pid,port:z,device:q,url:`http://${J}:${z}`,streamUrl:`http://${J}:${z}${N}/helper/${q}/stream.mjpeg`,wsUrl:`ws://${J}:${z}${N}/helper/${q}/ws`,...K?{streamSettings:K}:{}}}function P(q){V(G,{recursive:!0});let z=O(q.device),B=`${z}.${process.pid}.tmp`;W(B,JSON.stringify(q,null,2),{mode:384}),X(B,z)}function v(q,z){let B=O(q),C;try{C=JSON.parse(Y(B,"utf-8"))}catch{return}if(C.pid!==z)return;try{Z(B)}catch{}}function w(){try{return U(G).filter((q)=>q.startsWith("server-")&&q.endsWith(".json")).map((q)=>H(G,q))}catch{return[]}}export{P as writeServeSimState,O as stateFileForDevice,w as listStateFiles,x as inProcessServeSimState,v as clearServeSimState,k as STATE_FILE,G as STATE_DIR};
+import{tmpdir as M}from"os";import{join as G}from"path";import{readdirSync as N,mkdirSync as O,writeFileSync as Q,renameSync as R,readFileSync as T,unlinkSync as U}from"fs";function H(){return process.env.SERVE_SIM_STATE_DIR||G(M(),"serve-sim")}function K(q){return G(H(),`server-${q}.json`)}function Y(q,z){let A=(C)=>({url:C.url,streamUrl:C.streamUrl,wsUrl:C.wsUrl,port:C.port,device:C.device}),B=q.length===1?A(q[0]):{devices:q.map(A)};return z?{...B,token:z}:B}function Z(q,z,A="/",B="127.0.0.1",C){let E=B==="0.0.0.0"||B==="::"?"127.0.0.1":B,I=A.replace(/^\/+/,"").replace(/\/+$/,""),J=I===""?"":`/${I}`;return{pid:process.pid,port:z,device:q,url:`http://${E}:${z}`,streamUrl:`http://${E}:${z}${J}/helper/${q}/stream.mjpeg`,wsUrl:`ws://${E}:${z}${J}/helper/${q}/ws`,...C?{streamSettings:C}:{}}}function _(q){O(H(),{recursive:!0});let z=K(q.device),A=`${z}.${process.pid}.tmp`;Q(A,JSON.stringify(q,null,2),{mode:384}),R(A,z)}function $(q,z){let A=K(q),B;try{B=JSON.parse(T(A,"utf-8"))}catch{return}if(B.pid!==z)return;try{U(A)}catch{}}function L(){try{let q=H();return N(q).filter((z)=>z.startsWith("server-")&&z.endsWith(".json")).map((z)=>G(q,z))}catch{return[]}}export{_ as writeServeSimState,K as stateFileForDevice,H as stateDir,Y as previewStartupPayload,L as listStateFiles,Z as inProcessServeSimState,$ as clearServeSimState};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/serve-sim",
-  "version": "0.1.54",
+  "version": "0.2.0",
   "type": "module",
   "author": {
     "name": "Evan Bacon",
@@ -94,7 +94,8 @@
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.1.7",
     "typescript": "^5.7.0",
-    "werift": "^0.24.4"
+    "werift": "^0.24.4",
+    "zod": "^4.5.4"
   },
   "dependencies": {
     "inspect-webkit": "^0.0.5",

package/src/camera-helper.ts

@@ -1,9 +1,11 @@
 import { createHash } from "crypto";
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
-import { STATE_DIR } from "./state";
+import { stateDir } from "./state";
 
-export const CAMERA_STATE_DIR = join(STATE_DIR, "simcam");
+export function cameraStateDir(): string {
+  return join(stateDir(), "simcam");
+}
 const HELPER_TIMEOUT_MS = 3000;
 
 interface InjectedBundlesState {
@@ -28,11 +30,11 @@ export interface CameraStatusReply extends CameraHelperReply {
 }
 
 export function cameraHelperPidFile(udid: string): string {
-  return join(CAMERA_STATE_DIR, `${udid}.pid`);
+  return join(cameraStateDir(), `${udid}.pid`);
 }
 
 export function cameraHelperBundlesFile(udid: string): string {
-  return join(CAMERA_STATE_DIR, `${udid}.bundles.json`);
+  return join(cameraStateDir(), `${udid}.bundles.json`);
 }
 
 export function cameraHelperSocketFile(udid: string): string {

package/src/middleware.ts

@@ -1,10 +1,10 @@
+import { execFile, execSync, spawn, type ChildProcess } from "child_process";
 import { readdirSync, readFileSync, existsSync, unlinkSync, watch, type FSWatcher } from "fs";
 import { readFile, unlink } from "fs/promises";
-import { execSync, spawn, exec, execFile, type ChildProcess, type ExecException } from "child_process";
 import { tmpdir } from "os";
 import { join } from "path";
 import { createServer as createNetServer } from "net";
-import { createHash, randomBytes, timingSafeEqual } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import type { IncomingMessage, ServerResponse } from "http";
 import type { Socket } from "net";
 // `ws` (kept external in the build) supplies a WebSocket *client* for the
@@ -24,13 +24,14 @@ import {
   sendCorsPreflight,
   type HidSocket,
 } from "./device-session";
+import { assertPreviewAccess, assertUpgradeAccess } from "./session-auth";
 import {
-  eventLogEventForCommand,
+  eventLogEventForAction,
   readEventLog,
   recordEventLogEvent,
   subscribeEventLog,
 } from "./event-log";
-import { inProcessServeSimState, writeServeSimState, type ServeSimDeviceState, type StreamSettings } from "./state";
+import { inProcessServeSimState, stateDir, writeServeSimState, type ServeSimDeviceState, type StreamSettings } from "./state";
 import { debugMw } from "./debug";
 import {
   resolveDevicePlaceholderAsset,
@@ -54,7 +55,6 @@ export type SimMiddleware = WebMiddleware & {
 
 // Injected at build time as a base64-encoded string via `define`
 declare const __PREVIEW_HTML_B64__: string;
-const STATE_DIR = join(tmpdir(), "serve-sim");
 // Last logged result of a GET /api selection, used to suppress the
 // once-every-poll duplicate debugMw lines (the UI polls /api every ~2s).
 let lastApiLogKey: string | undefined;
@@ -117,8 +117,6 @@ type ShutdownRequestBody = { udid?: string };
 type StartRequestBody = { udid?: string };
 type ReleaseRequestBody = { targetId?: string };
 type HighlightRequestBody = { targetId?: string; on?: boolean };
-type ExecRequestBody = { command?: string };
-
 /** Re-exported alias for the canonical device-state record in `./state`. */
 export type ServeSimState = ServeSimDeviceState;
 
@@ -149,12 +147,16 @@ function eventLogSinceId(rawUrl: string): number | undefined {
   return Number.isFinite(since) ? since : undefined;
 }
 
-function recordCommandEvent(command: string, result: { exitCode?: number }): void {
+function recordActionEvent(
+  action: string,
+  params: Record<string, unknown> | undefined,
+  result: { exitCode?: number },
+): void {
   try {
-    const event = eventLogEventForCommand(command, result);
+    const event = eventLogEventForAction(action, params, result);
     if (event) recordEventLogEvent(event);
   } catch {
-    // Event-log recording is diagnostic; it must never break the exec path.
+    // Event-log recording is diagnostic; it must never break the action path.
   }
 }
 
@@ -359,7 +361,7 @@ function getPreferredDeviceUdid(): string | null {
 export async function readServeSimStates(): Promise<ServeSimState[]> {
   let files: string[];
   try {
-    files = readdirSync(STATE_DIR).filter(
+    files = readdirSync(stateDir()).filter(
       (f) => f.startsWith("server-") && f.endsWith(".json"),
     );
   } catch {
@@ -368,7 +370,7 @@ export async function readServeSimStates(): Promise<ServeSimState[]> {
   const booted = await getBootedUdids();
   const states: ServeSimState[] = [];
   for (const f of files) {
-    const path = join(STATE_DIR, f);
+    const path = join(stateDir(), f);
     try {
       const state: ServeSimState = JSON.parse(readFileSync(path, "utf-8"));
       try {
@@ -847,11 +849,25 @@ function serveHelperInProcess(
  * preview server itself serves the device's /helper routes in-process. Resolves
  * to an error string on boot failure, or null on success.
  */
+/** Carries the session token like the primary device's does, or its readers start failing. */
+export function gridDeviceState(
+  udid: string,
+  port: number,
+  base: string,
+  streamSettings?: StreamSettings,
+  sessionToken?: string,
+): ServeSimDeviceState {
+  const state = inProcessServeSimState(udid, port, base, "127.0.0.1", streamSettings);
+  return sessionToken ? { ...state, token: sessionToken } : state;
+}
+
 export async function startDeviceInProcess(
   udid: string,
   port: number,
   base: string,
   streamSettings?: StreamSettings,
+  /** Session token, when the server runs gated. */
+  sessionToken?: string,
 ): Promise<string | null> {
   // `simctl boot` errors when already booted — ignore and let bootstatus confirm.
   await new Promise<void>((resolve) => execFile("xcrun", ["simctl", "boot", udid], () => resolve()));
@@ -874,7 +890,7 @@ export async function startDeviceInProcess(
     });
     if (!booted) return `Device ${udid} failed to reach booted state`;
   }
-  writeServeSimState(inProcessServeSimState(udid, port, base, "127.0.0.1", streamSettings));
+  writeServeSimState(gridDeviceState(udid, port, base, streamSettings, sessionToken));
   return null;
 }
 
@@ -958,7 +974,6 @@ function attachHidInProcess(
 export function previewConfigForState(
   state: ServeSimState,
   base: string,
-  serveSimBin: string,
   execToken: string,
   streamSettingsOrCodec?: StreamSettings | string,
   proxyHelpers = false,
@@ -973,7 +988,6 @@ export function previewConfigForState(
   cameraStatusEndpoint: string;
   devtoolsEndpoint: string;
   streamSettingsEndpoint: string;
-  serveSimBin: string;
   gridApiEndpoint: string;
   gridCatalogEndpoint: string;
   gridStatusEndpoint: string;
@@ -995,8 +1009,11 @@ export function previewConfigForState(
   const streamSettings = typeof streamSettingsOrCodec === "object"
     ? streamSettingsOrCodec
     : httpStreamSettingsFromLegacyCodec(legacyCodec);
+  // Every serve-sim's state file is readable here and ?device= is caller-supplied, so neither the
+  // token nor the TURN credentials may ride along: that hands one instance's secrets to another.
+  const { token: _sessionToken, streamSettings: _foreignStreamSettings, ...publicState } = state;
   return {
-    ...state,
+    ...publicState,
     basePath: base,
     logsEndpoint: endpoint(base, "/logs", state.device),
     appStateEndpoint: endpoint(base, "/appstate", state.device),
@@ -1007,7 +1024,6 @@ export function previewConfigForState(
     cameraStatusEndpoint: `${base === "/" ? "" : base}/helper/${encodeURIComponent(state.device)}/camera/status`,
     devtoolsEndpoint: endpoint(base, "/devtools", state.device),
     streamSettingsEndpoint: streamSettingsEndpointFrom(state.streamUrl),
-    serveSimBin,
     gridApiEndpoint: gridApiBase,
     gridCatalogEndpoint: gridApiBase + "/catalog",
     gridStatusEndpoint: gridApiBase + "/status",
@@ -1475,6 +1491,8 @@ export interface SimMiddlewareOptions {
    * cross-origin pages cannot read it.
    */
   execToken?: string;
+  /** Off by default: a loopback-only server is already reachable to whoever is on the machine. */
+  requirePreviewToken?: boolean;
   /** Stream transport and codec settings for the preview. */
   streamSettings?: StreamSettings;
   /**
@@ -1507,20 +1525,6 @@ function httpStreamSettingsFromLegacyCodec(codec: string | undefined): StreamSet
   return undefined;
 }
 
-function safeEqualString(a: string, b: string): boolean {
-  const ab = Buffer.from(a);
-  const bb = Buffer.from(b);
-  if (ab.length !== bb.length) return false;
-  return timingSafeEqual(ab, bb);
-}
-
-function isJsonContentType(value: string | undefined): boolean {
-  if (!value) return false;
-  // `application/json; charset=utf-8` etc. — only the media type matters.
-  const mediaType = value.split(";", 1)[0]!.trim().toLowerCase();
-  return mediaType === "application/json";
-}
-
 /**
  * Connect-style middleware that serves the simulator preview UI.
  *
@@ -1580,23 +1584,35 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
   // can call /exec; cross-origin pages and LAN clients cannot, because they
   // can't read this value (it's only injected into the preview page's config).
   const execToken = options?.execToken ?? randomBytes(32).toString("base64url");
+  const requirePreviewToken = options?.requirePreviewToken ?? false;
   const metricsCorsOrigins = options?.metricsCorsOrigins ?? [];
 
   // Simulator-settings requests run in-process (just the underlying simctl /
   // ax-tool spawn) instead of round-tripping a full `node <cli>` exec per
   // sidebar interaction.
+  /** Validation messages are the caller's own input. A child's failure carries host paths. */
+  const sanitizeUiFailure = async <T,>(work: Promise<T>): Promise<T> => {
+    try {
+      return await work;
+    } catch (err) {
+      console.error("serve-sim ui request failed:", err);
+      throw new Error("the simulator rejected this UI request");
+    }
+  };
+
   const handleUiRequest: UiRequestHandler = async (payload) => {
     const p = (payload ?? {}) as { device?: string; option?: string; value?: string };
-    if (typeof p.device !== "string" || !/^[0-9A-Za-z-]+$/.test(p.device)) {
+    // Must start alphanumeric and stay bounded: a leading "-" is parsed as a flag by simctl.
+    if (typeof p.device !== "string" || !/^[0-9A-Za-z][0-9A-Za-z-]{0,255}$/.test(p.device)) {
       throw new Error("missing or invalid device udid");
     }
     if (p.option === undefined) {
-      return { status: await getUiStatus(p.device) };
+      return { status: await sanitizeUiFailure(getUiStatus(p.device)) };
     }
-    if (!UI_OPTIONS[p.option]) throw new Error(`unknown option: ${p.option}`);
+    if (!Object.hasOwn(UI_OPTIONS, p.option)) throw new Error(`unknown option: ${p.option}`);
     const value = typeof p.value === "string" ? normalizeUiValue(p.option, p.value) : null;
     if (value === null) throw new Error(`invalid value for ${p.option}: ${p.value}`);
-    await setUiOption(p.device, p.option, value);
+    await sanitizeUiFailure(setUiOption(p.device, p.option, value));
     try {
       recordEventLogEvent({
         device: p.device,
@@ -1612,6 +1628,8 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     }
     return { ok: true };
   };
+/** Reachable without the session token: liveness probes cannot carry one. */
+  const UNGATED_PATHS = ["/healthz", "/readyz"];
 
   const connectMiddleware = (async (req: SimReq, res: SimRes, next?: SimNext) => {
     const rawUrl: string = req.url ?? "";
@@ -1621,6 +1639,14 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     const selectedDevice = requestedDevice ?? options?.device ?? null;
     const devtoolsFrontendBase = base === "/" ? "/devtools-frontend" : `${base}/devtools-frontend`;
 
+    // Gated as a whole rather than per route, so a new route is protected by default.
+    if (
+      !UNGATED_PATHS.some((path) => url === base + path)
+      && !assertPreviewAccess(req, res, execToken, { required: requirePreviewToken, basePath: base })
+    ) {
+      return;
+    }
+
     const helperTarget = helperProxyTarget(rawUrl, helperPrefix);
     if (helperTarget) {
       const device = helperTarget.device ?? selectedDevice;
@@ -1647,8 +1673,12 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         return;
       }
       try {
+        // The gate accepts `?token=` here, so forward the rest of the query but never that.
+        const upstreamQuery = new URLSearchParams(qIndex === -1 ? "" : rawUrl.slice(qIndex + 1));
+        upstreamQuery.delete("token");
+        const upstreamSuffix = upstreamQuery.size === 0 ? "" : `?${upstreamQuery.toString()}`;
         const upstream = await fetch(
-          `https://chrome-devtools-frontend.appspot.com/serve_rev/@${DEVTOOLS_FRONTEND_REV}/${assetPath}${qIndex === -1 ? "" : rawUrl.slice(qIndex)}`,
+          `https://chrome-devtools-frontend.appspot.com/serve_rev/@${DEVTOOLS_FRONTEND_REV}/${assetPath}${upstreamSuffix}`,
         );
         const headers: Record<string, string> = {
           "Cache-Control": "public, max-age=604800",
@@ -1683,7 +1713,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
 
       if (state) {
         const remoteState = rewriteStateForRequestHost(state, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers);
-        const config = JSON.stringify(previewConfigForState(remoteState, base, serveSimBinPath(), execToken, streamSettings, proxyHelpers));
+        const config = JSON.stringify(previewConfigForState(remoteState, base, execToken, streamSettings, proxyHelpers));
         const configScript = `<script>window.__SIM_PREVIEW__=${config}</script>`;
         html = html.replace("<!--__SIM_PREVIEW_CONFIG__-->", configScript);
       }
@@ -1828,7 +1858,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
           watcherRetry = null;
           if (closed || res.writableEnded || watcher) return;
           try {
-            watcher = watch(STATE_DIR, onFsEvent);
+            watcher = watch(stateDir(), onFsEvent);
             watcher.on("error", () => {
               watcher?.close();
               watcher = null;
@@ -1933,7 +1963,13 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
           return;
         }
         const port = req.socket.localPort ?? 0;
-        void startDeviceInProcess(udid, port, base, streamSettings).then((error) => {
+        void startDeviceInProcess(
+          udid,
+          port,
+          base,
+          streamSettings,
+          requirePreviewToken ? execToken : undefined,
+        ).then((error) => {
           if (res.writableEnded) return;
           if (error) {
             res.writeHead(500, { "Content-Type": "application/json" });
@@ -2112,7 +2148,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         "Cache-Control": "no-store",
       });
       const remoteState = state ? rewriteStateForRequestHost(state, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers) : null;
-      res.end(JSON.stringify(remoteState ? previewConfigForState(remoteState, base, serveSimBinPath(), execToken, streamSettings, proxyHelpers) : null));
+      res.end(JSON.stringify(remoteState ? previewConfigForState(remoteState, base, execToken, streamSettings, proxyHelpers) : null));
       return;
     }
 
@@ -2248,7 +2284,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         const state = selectServeSimState(states, selectedDevice);
         const remoteState = state ? rewriteStateForRequestHost(state, hostForRequest(req), base, httpProtocolForRequest(req), proxyHelpers) : null;
         return JSON.stringify(
-          remoteState ? previewConfigForState(remoteState, base, serveSimBinPath(), execToken, streamSettings, proxyHelpers) : null,
+          remoteState ? previewConfigForState(remoteState, base, execToken, streamSettings, proxyHelpers) : null,
         );
       };
 
@@ -2292,7 +2328,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
           watcherRetry = null;
           if (closed || res.writableEnded || watcher) return;
           try {
-            watcher = watch(STATE_DIR, onFsEvent);
+            watcher = watch(stateDir(), onFsEvent);
             watcher.on("error", () => {
               watcher?.close();
               watcher = null;
@@ -2403,84 +2439,6 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
       return;
     }
 
-    // POST /exec — run a shell command on the host. Gated by a per-process
-    // bearer token injected only into the same-origin preview HTML, with
-    // Content-Type + Origin checks to block CORS-simple CSRF (a malicious
-    // page POSTing `text/plain` JSON to a dev server bound to a public iface)
-    // and LAN attackers who can reach the port but can't read the token.
-    if ((url === base + "/exec" || url === base + "/exec/") && req.method === "POST") {
-      // 1. Reject anything that isn't a JSON request, killing the
-      //    `enctype="text/plain"` CORS-simple form-POST path.
-      if (!isJsonContentType(req.headers["content-type"])) {
-        res.writeHead(415, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ stdout: "", stderr: "Unsupported Media Type", exitCode: 1 }));
-        return;
-      }
-      // 2. If the browser supplied an Origin, require it match this server.
-      //    Same-origin XHR from the preview page sets Origin to our own URL;
-      //    a cross-origin page's Origin won't match.
-      const origin = req.headers.origin;
-      if (origin) {
-        try {
-          const originHost = new URL(origin).host;
-          if (originHost !== req.headers.host) {
-            res.writeHead(403, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ stdout: "", stderr: "Cross-origin request blocked", exitCode: 1 }));
-            return;
-          }
-        } catch {
-          res.writeHead(403, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ stdout: "", stderr: "Invalid Origin", exitCode: 1 }));
-          return;
-        }
-      }
-      // 3. Require the per-session bearer token. Cross-origin pages cannot
-      //    read it from window.__SIM_PREVIEW__; non-browser callers must
-      //    have copied it from the CLI output.
-      const authHeader = req.headers.authorization ?? "";
-      const match = /^Bearer\s+(.+)$/i.exec(authHeader);
-      if (!match || !safeEqualString(match[1]!.trim(), execToken)) {
-        res.writeHead(401, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ stdout: "", stderr: "Unauthorized", exitCode: 1 }));
-        return;
-      }
-      let body = "";
-      let aborted = false;
-      req.on("data", (chunk: Buffer | string) => {
-        body += typeof chunk === "string" ? chunk : chunk.toString();
-        // Cheap belt-and-braces cap so a runaway POST can't OOM the dev server.
-        if (body.length > 4 * 1024 * 1024) {
-          aborted = true;
-          res.writeHead(413, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ stdout: "", stderr: "Payload Too Large", exitCode: 1 }));
-          req.destroy();
-        }
-      });
-      req.on("end", () => {
-        if (aborted) return;
-        let command = "";
-        try {
-          command = (JSON.parse(body) as ExecRequestBody).command ?? "";
-        } catch {}
-        if (!command) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ stdout: "", stderr: "Missing command", exitCode: 1 }));
-          return;
-        }
-        exec(command, { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
-          const exitCode = err ? (err as ExecException).code ?? 1 : 0;
-          recordCommandEvent(command, { exitCode });
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({
-            stdout: stdout.toString(),
-            stderr: stderr.toString(),
-            exitCode,
-          }));
-        });
-      });
-      return;
-    }
-
     // SSE: foreground-app change stream. Emits `{bundleId, pid}` events
     // parsed from SpringBoard's "Setting process visibility to: Foreground"
     // log line. Filtering is done here (not in the browser) so the SSE stream
@@ -2531,6 +2489,24 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     if (next) return next();
   }) as ConnectMiddleware;
   connectMiddleware.handleUpgrade = (req: SimReq, socket: Socket, head: Buffer) => {
+    // Upgrades skip the HTTP request path, and the HID and devtools sockets carry no token of
+    // their own, so gate them here too.
+    if (
+      !assertUpgradeAccess(
+        {
+          authorization: req.headers.authorization,
+          cookie: req.headers.cookie,
+          origin: req.headers.origin,
+          host: req.headers.host,
+          "sec-fetch-site": req.headers["sec-fetch-site"],
+        },
+        execToken,
+        { required: requirePreviewToken },
+      )
+    ) {
+      socket.destroy();
+      return;
+    }
     const rawUrl = req.url ?? "";
     const selectedDevice = queryDevice(rawUrl) ?? options?.device ?? null;
     const helperTarget = helperProxyTarget(rawUrl, helperPrefix);
@@ -2560,12 +2536,8 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
     }
     socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
   };
-  // WebSocket exec channel — same auth/origin policy as POST /exec, but off
-  // the browser's per-origin HTTP connection pool so multiple preview tabs
-  // (each holding MJPEG + SSE streams) can't starve exec actions. Servers
-  // mounting this middleware should forward `upgrade` events here (the
-  // built-in preview server does); the client falls back to POST /exec when
-  // the upgrade never completes.
+  // Off the browser's per-origin connection pool, so preview tabs holding MJPEG and SSE streams
+  // can't starve actions. Hosts mounting this middleware forward `upgrade` events here.
   const fetchMiddleware = (async (request: Request) => {
     return connectToFetch(connectMiddleware, request);
   }) as SimMiddleware;
@@ -2583,16 +2555,36 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
       `${base}/ax`,
     ],
     onUiRequest: handleUiRequest,
-    onCommandResult: (command, result) => recordCommandEvent(command, result),
+    serveSimBinPath: serveSimBinPath(),
+    onActionResult: (action, params, result) => recordActionEvent(action, params, result),
     onSseRequest(path, websocketRequest) {
       const url = new URL(path, websocketRequest.url);
+      // The exec channel already authenticated, so its fan-out carries the token past the gate.
       return fetchMiddleware(new Request(url, {
-        headers: { accept: "text/event-stream" },
+        headers: { accept: "text/event-stream", authorization: `Bearer ${execToken}` },
       }));
     },
   });
 
   fetchMiddleware.handleWebSocket = (request: Request, websocket: UpgradeHandlerWebSocket): boolean => {
+    // Embedded hosts forward accepted sockets and bypass the request gate. The exec channel
+    // re-checks the token in its first frame; the helper HID socket does not.
+    if (
+      !assertUpgradeAccess(
+        {
+          authorization: request.headers.get("authorization") ?? undefined,
+          cookie: request.headers.get("cookie") ?? undefined,
+          origin: request.headers.get("origin") ?? undefined,
+          host: request.headers.get("host") ?? undefined,
+          "sec-fetch-site": request.headers.get("sec-fetch-site") ?? undefined,
+        },
+        execToken,
+        { required: requirePreviewToken },
+      )
+    ) {
+      websocket.close();
+      return true;
+    }
     if (execWebSocketHandler(request, websocket)) return true;
     if (claimHelperHidSocket(request, websocket, {
       helperProxyTarget: (rawUrl) => helperProxyTarget(rawUrl, helperPrefix),

package/src/state.ts

@@ -9,16 +9,13 @@ export type {
   WebRtcStreamCodec,
 } from "./stream-settings";
 
-/** Directory where serve-sim stores runtime state. */
-export const STATE_DIR = join(tmpdir(), "serve-sim");
-
-/** Path to the serve-sim server state file (JSON with pid, port, URLs).
- *  @deprecated Use `stateFileForDevice(udid)` for multi-device support. Kept for backward compat. */
-export const STATE_FILE = join(STATE_DIR, "server.json");
+/** Directory where serve-sim stores runtime state. Override with `SERVE_SIM_STATE_DIR`. */
+export function stateDir(): string {
+  return process.env.SERVE_SIM_STATE_DIR || join(tmpdir(), "serve-sim");
+}
 
-/** Per-device state file: `/tmp/serve-sim/server-{udid}.json` */
 export function stateFileForDevice(udid: string): string {
-  return join(STATE_DIR, `server-${udid}.json`);
+  return join(stateDir(), `server-${udid}.json`);
 }
 
 /** Runtime record for a device streamed in-process by a preview server. */
@@ -30,6 +27,24 @@ export interface ServeSimDeviceState {
   streamUrl: string;
   wsUrl: string;
   streamSettings?: StreamSettings;
+  /** Present only under `--require-token`, so local subcommands can reach the gated socket. */
+  token?: string;
+}
+
+/** `--quiet` startup payload. Carries the session token only when the gate is on. */
+export function previewStartupPayload(
+  states: ServeSimDeviceState[],
+  token?: string,
+): Record<string, unknown> {
+  const view = (s: ServeSimDeviceState) => ({
+    url: s.url,
+    streamUrl: s.streamUrl,
+    wsUrl: s.wsUrl,
+    port: s.port,
+    device: s.device,
+  });
+  const base = states.length === 1 ? view(states[0]!) : { devices: states.map(view) };
+  return token ? { ...base, token } : base;
 }
 
 /**
@@ -65,11 +80,10 @@ export function inProcessServeSimState(
  *  Writes atomically (temp file + rename) so a concurrent reader never observes
  *  a truncated or partially-written file. */
 export function writeServeSimState(state: ServeSimDeviceState): void {
-  mkdirSync(STATE_DIR, { recursive: true });
+  mkdirSync(stateDir(), { recursive: true });
   const file = stateFileForDevice(state.device);
   const tmp = `${file}.${process.pid}.tmp`;
-  // WebRTC state can contain short-lived TURN credentials. Keep the file
-  // readable only by the account running serve-sim.
+  // Holds TURN credentials and, when gated, the session token.
   writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
   renameSync(tmp, file);
 }
@@ -89,9 +103,10 @@ export function clearServeSimState(udid: string, ownerPid: number): void {
 /** List all per-device state files in the state directory. */
 export function listStateFiles(): string[] {
   try {
-    return readdirSync(STATE_DIR)
+    const dir = stateDir();
+    return readdirSync(dir)
       .filter((f) => f.startsWith("server-") && f.endsWith(".json"))
-      .map((f) => join(STATE_DIR, f));
+      .map((f) => join(dir, f));
   } catch {
     return [];
   }