@stim-cli/server 0.0.0 → 1.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
 # @stim-cli/server
 
-Placeholder. Install a version published with the other Stim packages.
+`stim-server` serves Stim state to paired read-only clients, such as the Stim
+phone app. It runs on the Mac, next to Stim, and changes no Stim state: it
+writes only its own pairing state under `$STIM_HOME/server/`.
+
+The design is in
+[`docs/specs/2026-09-25-stim-server-design.md`](../../docs/specs/2026-09-25-stim-server-design.md).
+
+## Commands
+
+```bash
+stim-server [--port <n>]          # serve paired clients, port 7787 by default
+stim-server pair [--port <n>]     # print a single-use pairing payload
+stim-server devices [list]        # list paired devices
+stim-server devices revoke <id>   # revoke a paired device
+```
+
+`pair --json` prints `{ "qr": <payload>, "expiresAt": "<ISO time>" }`, and
+`devices --json` prints `{ "devices": [...] }` with each device's `id`, `name`,
+`identity`, `pairedAt`, `lastSeenAt` and `capabilities`, never its token hash.
+
+`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. 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.
+
+`stim-server` runs the `stim` version this package was released with, not the
+one on your PATH. It reads the login shell's environment once at start, so
+`PATH`, `ANDROID_HOME`, and `STIM_*` variables match your terminal even when
+another app starts it.
+
+## Tailscale
+
+Tailscale carries and encrypts the traffic between the phone and the Mac, on
+the same Wi-Fi or across networks, and identifies each device. Stim adds no
+cryptography of its own. You need Tailscale on the Mac and on the phone, in the
+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:7443` with a valid certificate:
+
+```bash
+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`.
+
+## Pairing
+
+`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: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.
+
+At pairing, the server records the peer's tailnet node and user from
+`tailscale whois`. A device token presented from any other node is refused, so
+a leaked token alone is not enough. A device paired over loopback, from this
+Mac, is accepted only over loopback. `tailscale serve` connects from loopback
+and names the peer in `X-Forwarded-For`, which the server trusts only on
+loopback connections. Forward only `tailscale serve` in HTTP mode to the
+loopback port: a forwarder that omits that header, such as `tailscale serve
+--tcp`, `ssh -L`, or a tunnel, makes every remote peer look like this Mac.
+
+A connection must send `hello` within 5 seconds. Five failed attempts from the
+same peer within a minute block new connections from it for up to a minute.
+
+Paired devices live in `$STIM_HOME/server/devices.json`. Revoking a device
+closes its open connections.
+
+## Protocol
+
+JSON messages over a WebSocket. Requests are `{ "id", "method", "params" }`,
+answered by `{ "id", "result" }` or `{ "id", "error": { "code", "message" } }`.
+Events are `{ "event", "subscription", ... }`.
+
+- `hello` must come first. Params: `protocol` (1), `client` (`name`,
+  `version`), and `auth`, either `{ "pairingToken", "deviceName" }` or
+  `{ "deviceToken" }`. The result carries the server name and versions, the
+  granted capabilities (`read` only in protocol 1), the paired device, and the
+  new `deviceToken` when the hello paired.
+- `status.subscribe` returns a subscription id. Each `status` event carries a
+  full payload as `stim status --watch --json` prints it. All subscribers share
+  one `stim status --watch --json` child, which stops with the last
+  subscriber.
+- `logs.query` returns `{ "records" }`, and `logs.subscribe` sends `logs`
+  events: first the last `tail` matching records, then new ones in batches.
+  Both take the Stim Desktop log viewer's filters: `workspace` (required),
+  `sources` (`metro`, `client`, `device`, `build`), `slot`, `level` (the
+  minimum), `grep` (a regular expression), `errors`, and `tail` (1 to 5000,
+  5000 by default). Without `sources`, `errors` keeps the CLI's default error
+  scope. They run `stim logs --json` and `stim logs --json --follow` in the
+  workspace. Subscribers with the same workspace and filters share one
+  `--follow` child, which stops with the last of them.
+- `stats.get` and `settings.get` return the payload of `stim stats --json` and
+  `stim settings --json`, which masks sensitive values. Without `workspace`,
+  they run in the home directory and cover the machine only.
+- `frames.subscribe` takes `workspace`, `platform` (`ios` or `android`) and
+  `slot` (`default` when absent) and sends `frame` events: a JPEG screenshot,
+  base64 in `data`, with `width`, `height` and `capturedAt`. It serves only a
+  booted simulator or a running emulator that `stim status` lists as owned by
+  that workspace; any other device ends the subscription with a
+  `frames-failed` `error` event, and so does a device that stops or changes
+  owner. Simulators are captured with `xcrun simctl io <udid> screenshot`, of
+  the primary display, or of the default display when that `simctl` does not
+  accept `primary`. Emulators are captured through their gRPC `getScreenshot`,
+  found through the discovery file and token the emulator writes when Stim
+  boots it, scaled to fit 1280 pixels and converted with `sips`. An emulator
+  Stim booted before it passed `-grpc` has no endpoint. A frame is sent only
+  when the screen changed: up to 5 per second while it changes, backing off to
+  one capture per second while it does not, with capturing taking at most half
+  of each device's time. All subscribers of a device share one capture loop,
+  which sends a new subscriber the latest frame and stops with the last
+  subscriber, and at most two captures run at once. A client whose socket has
+  more than 1 MiB unsent skips frames and gets the newest once it catches up.
+- `unsubscribe` ends a subscription.
+- An `error` event ends a subscription whose source failed, or whose client
+  fell behind (`slow-client`); subscribe again.
+
+`workspace` is an environment `path` from a status payload. Any other path is
+refused with `unknown-workspace` and runs nothing. A connection holds at most
+32 subscriptions and runs at most 4 `logs.query`, `stats.get` and
+`settings.get` requests at a time. Those requests fail after 60 seconds or
+32 MiB of output, and closing the connection stops them. A `stim` child that
+ignores SIGTERM gets SIGKILL a second later. A log subscriber whose socket has more than
+4 MiB unsent gets no more batches until it catches up; past 20,000
+waiting records the server ends that subscription with `slow-client`.
+
+The error codes `unauthorized`, `pairing-expired`, and `protocol-unsupported`
+refuse the client until it pairs again or updates; clients retry the others.
+
+The package exports the message types, and the build writes their JSON Schema
+to `dist/protocol.schema.json`, exported as `@stim-cli/server/protocol.schema.json`.

package/dist/protocol-B3k9Ykuu.mjs

@@ -0,0 +1,407 @@
+//#region src/protocol.ts
+const PROTOCOL_VERSION = 1;
+const PROTOCOL_SCHEMA_FILE = "protocol.schema.json";
+const CAPABILITIES = ["read"];
+const METHODS = [
+	"hello",
+	"status.subscribe",
+	"logs.query",
+	"logs.subscribe",
+	"stats.get",
+	"settings.get",
+	"frames.subscribe",
+	"unsubscribe"
+];
+/**
+* `unauthorized`, `pairing-expired` and `protocol-unsupported` refuse the client until it pairs again or
+* updates; clients retry the others.
+*/
+const ERROR_CODES = [
+	"unauthorized",
+	"pairing-expired",
+	"protocol-unsupported",
+	"identity-unavailable",
+	"bad-request",
+	"unknown-method",
+	"already-authenticated",
+	"unknown-subscription",
+	"unknown-workspace",
+	"limit-exceeded",
+	"slow-client",
+	"status-failed",
+	"logs-failed",
+	"stim-failed",
+	"frames-failed"
+];
+const LOG_SOURCES = [
+	"metro",
+	"client",
+	"device",
+	"build"
+];
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+];
+const MAX_LOG_TAIL = 5e3;
+const requestId = { type: ["integer", "string"] };
+const protocolError = {
+	type: "object",
+	required: ["code", "message"],
+	additionalProperties: false,
+	properties: {
+		code: { enum: [...ERROR_CODES] },
+		message: { type: "string" }
+	}
+};
+function request(method, params) {
+	return {
+		type: "object",
+		required: params ? [
+			"id",
+			"method",
+			"params"
+		] : ["id", "method"],
+		additionalProperties: false,
+		properties: {
+			id: requestId,
+			method: { const: method },
+			params: params ?? {
+				type: "object",
+				maxProperties: 0
+			}
+		}
+	};
+}
+function optionalParams(method, params) {
+	return {
+		type: "object",
+		required: ["id", "method"],
+		additionalProperties: false,
+		properties: {
+			id: requestId,
+			method: { const: method },
+			params
+		}
+	};
+}
+/** The JSON Schema of every message on the wire, written to `dist/protocol.schema.json` at build time. */
+function protocolJsonSchema() {
+	return {
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		title: "Stim server protocol",
+		description: `Messages exchanged over the stim-server WebSocket, protocol version 1.`,
+		"x-stim-protocol": 1,
+		$defs: {
+			ProtocolError: protocolError,
+			HelloParams: {
+				type: "object",
+				required: [
+					"protocol",
+					"client",
+					"auth"
+				],
+				additionalProperties: false,
+				properties: {
+					protocol: { type: "integer" },
+					client: {
+						type: "object",
+						required: ["name", "version"],
+						properties: {
+							name: { type: "string" },
+							version: { type: "string" }
+						}
+					},
+					auth: { oneOf: [{
+						type: "object",
+						required: ["pairingToken", "deviceName"],
+						additionalProperties: false,
+						properties: {
+							pairingToken: { type: "string" },
+							deviceName: {
+								type: "string",
+								minLength: 1
+							}
+						}
+					}, {
+						type: "object",
+						required: ["deviceToken"],
+						additionalProperties: false,
+						properties: { deviceToken: { type: "string" } }
+					}] }
+				}
+			},
+			HelloResult: {
+				type: "object",
+				required: [
+					"protocol",
+					"server",
+					"capabilities",
+					"device"
+				],
+				additionalProperties: false,
+				properties: {
+					protocol: { type: "integer" },
+					server: {
+						type: "object",
+						required: [
+							"name",
+							"version",
+							"stim"
+						],
+						additionalProperties: false,
+						properties: {
+							name: { type: "string" },
+							version: { type: "string" },
+							stim: { type: "string" }
+						}
+					},
+					capabilities: {
+						type: "array",
+						items: { enum: [...CAPABILITIES] }
+					},
+					device: {
+						type: "object",
+						required: ["id", "name"],
+						additionalProperties: false,
+						properties: {
+							id: { type: "string" },
+							name: { type: "string" }
+						}
+					},
+					deviceToken: { type: "string" }
+				}
+			},
+			LogRecord: {
+				type: "object",
+				description: "One record as `stim logs --json` prints it.",
+				properties: {
+					ts: { type: "number" },
+					src: { type: "string" },
+					level: { type: "string" },
+					msg: { type: "string" }
+				}
+			},
+			LogFilter: {
+				type: "object",
+				required: ["workspace"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					sources: {
+						type: "array",
+						minItems: 1,
+						items: { enum: [...LOG_SOURCES] }
+					},
+					level: { enum: [...LOG_LEVELS] },
+					slot: {
+						type: "string",
+						minLength: 1
+					},
+					grep: {
+						type: "string",
+						description: "A regular expression matched against each message."
+					},
+					errors: { type: "boolean" },
+					tail: {
+						type: "integer",
+						minimum: 1,
+						maximum: MAX_LOG_TAIL,
+						default: MAX_LOG_TAIL
+					}
+				}
+			},
+			FrameTarget: {
+				type: "object",
+				required: ["workspace", "platform"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					platform: { enum: ["ios", "android"] },
+					slot: {
+						type: "string",
+						minLength: 1,
+						default: "default"
+					}
+				}
+			},
+			WorkspaceParams: {
+				type: "object",
+				additionalProperties: false,
+				properties: { workspace: {
+					type: "string",
+					description: "An environment path from a status payload."
+				} }
+			},
+			ClientRequest: { oneOf: [
+				request("hello", { $ref: "#/$defs/HelloParams" }),
+				request("status.subscribe"),
+				request("logs.query", { $ref: "#/$defs/LogFilter" }),
+				request("logs.subscribe", { $ref: "#/$defs/LogFilter" }),
+				request("frames.subscribe", { $ref: "#/$defs/FrameTarget" }),
+				optionalParams("stats.get", { $ref: "#/$defs/WorkspaceParams" }),
+				optionalParams("settings.get", { $ref: "#/$defs/WorkspaceParams" }),
+				request("unsubscribe", {
+					type: "object",
+					required: ["subscription"],
+					additionalProperties: false,
+					properties: { subscription: { type: "string" } }
+				})
+			] },
+			ServerResponse: { oneOf: [{
+				type: "object",
+				required: ["id", "result"],
+				additionalProperties: false,
+				properties: {
+					id: requestId,
+					result: { anyOf: [
+						{ $ref: "#/$defs/HelloResult" },
+						{
+							type: "object",
+							required: ["subscription"],
+							additionalProperties: false,
+							properties: { subscription: { type: "string" } }
+						},
+						{
+							type: "object",
+							required: ["records"],
+							additionalProperties: false,
+							properties: { records: {
+								type: "array",
+								items: { $ref: "#/$defs/LogRecord" }
+							} }
+						},
+						{
+							type: "object",
+							description: "The payload of `stim stats --json` or `stim settings --json`, or {} for unsubscribe."
+						}
+					] }
+				}
+			}, {
+				type: "object",
+				required: ["id", "error"],
+				additionalProperties: false,
+				properties: {
+					id: { type: [
+						"integer",
+						"string",
+						"null"
+					] },
+					error: { $ref: "#/$defs/ProtocolError" }
+				}
+			}] },
+			ServerEvent: { oneOf: [
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"payload"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "status" },
+						subscription: { type: "string" },
+						payload: {
+							type: "object",
+							description: "A full payload, as `stim status --watch --json` prints it."
+						}
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"records"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "logs" },
+						subscription: { type: "string" },
+						records: {
+							type: "array",
+							items: { $ref: "#/$defs/LogRecord" }
+						}
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"platform",
+						"slot",
+						"mime",
+						"width",
+						"height",
+						"capturedAt",
+						"data"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "frame" },
+						subscription: { type: "string" },
+						platform: { enum: ["ios", "android"] },
+						slot: { type: "string" },
+						mime: { const: "image/jpeg" },
+						width: { type: "integer" },
+						height: { type: "integer" },
+						capturedAt: {
+							type: "string",
+							format: "date-time"
+						},
+						data: {
+							type: "string",
+							contentEncoding: "base64"
+						}
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"delayed"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "frame-delayed" },
+						subscription: { type: "string" },
+						delayed: { type: "boolean" }
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"error"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "error" },
+						subscription: { type: "string" },
+						error: { $ref: "#/$defs/ProtocolError" }
+					}
+				}
+			] }
+		},
+		oneOf: [
+			{ $ref: "#/$defs/ClientRequest" },
+			{ $ref: "#/$defs/ServerResponse" },
+			{ $ref: "#/$defs/ServerEvent" }
+		]
+	};
+}
+//#endregion
+export { MAX_LOG_TAIL as a, PROTOCOL_VERSION as c, LOG_SOURCES as i, protocolJsonSchema as l, ERROR_CODES as n, METHODS as o, LOG_LEVELS as r, PROTOCOL_SCHEMA_FILE as s, CAPABILITIES as t };