@stim-cli/server 1.23.1 → 1.24.0

package/README.md

@@ -547,8 +547,11 @@ are not carried over: phones pair again, and remote machines are approved
 again with a new setup ticket.
 
 Stim Desktop and other clients of the server's own user on the same machine do
-not pair. They connect to the Unix socket `$STIM_HOME/server/local.sock`, mode
-0600 in a 0700 directory, which serves only this user and needs no handshake.
+not pair. They connect to the Unix socket `$STIM_HOME/server/local.sock`. If
+that path exceeds the platform's limit (103 UTF-8 bytes on macOS, 107 on Linux), the socket instead lives at
+`/tmp/stim-sockets-<uid>/<sha256-of-normalized-socket-path>.sock`, so long hosted
+session homes remain usable and distinct homes keep distinct sockets. The
+socket is mode 0600 in a mode 0700 directory owned by this user and needs no handshake.
 That connection gets read and control. The Desktop-only methods (`route.setup`,
 `machines.update.*`, `device-host.sessions` and `device-host.sessions.stop`)
 work only there; on a server Desktop started, only after the private Desktop
@@ -556,8 +559,13 @@ bootstrap proof (see [Private Desktop bootstrap](#private-desktop-bootstrap)).
 Windows has no socket.
 
 The network address, `tailscale whois` and the `X-Forwarded-For` header that
-`tailscale serve` adds never authenticate. They only label a record (`from` in
-`stim-server devices`) and key the rate limits below.
+`tailscale serve` adds never authenticate. They label a record (`from` in
+`stim-server devices`) and key the rate limits below. Tailscale rewrites the
+header to the real tailnet source, so remote clients cannot forge it. A local
+process on the host can connect to the loopback port and forge it to lock one
+named peer, or the shared local bucket, out for the lockout window. It
+authenticates nothing and reads nothing. This is accepted because it needs
+local code execution on the host.
 
 A connection must finish the handshake and send `hello` within 5 seconds of
 each step. Five failed attempts from the same peer address within a minute
@@ -1143,6 +1151,12 @@ stream over WireGuard with socket backpressure; no public tunnel, Funnel or
 Tailscale serve configuration change is needed. The 64 KiB server message
 limit remains unchanged.
 
+An approved client calls `device-host.metro.ports` with `{ports}`, at most 256
+of them, before it starts Metro for an iOS Expo dev client, and the host
+answers `{busy}`: the listed ports that already accept loopback connections,
+apart from the client's own dev-client bridges. The feature
+`hosted-metro-ports` advertises it.
+
 Replaying the same open request keeps the port. Client disconnection leaves
 the bridge available for the same session while its server owner lives. Call
 `device-host.metro.close` to replace a gateway, then reopen on the same port;
@@ -1700,7 +1714,17 @@ connected since stim-server started keeps its directory when revoked.
   `ccache` or `none`) and `stimBuild`, after the whole manifest of `repo` was
   synced on this connection. A peer-cache-capable React Native caller can set
   `cacheArtifact: true` to retain a completed development archive when its cache
-  write and remote policies allow it. It returns `{ "job" }`. It fails with
+  write and remote policies allow it. With the `fingerprint-sources` feature, a
+  caller can send `fingerprintSources`, the `id` and `hash` of each source of
+  `fingerprint`, and a `fingerprint-mismatch` failure names the sources that
+  differ and the synced files prebuild or `pod install` rewrote. With the
+  `fingerprint-ignored` feature, it can send `fingerprintIgnored`, the paths
+  relative to `project` that its git ignores for `fingerprint` through
+  `.git/info/exclude` or a global excludes file, which the machine's synced
+  checkout has no copy of. With the `fingerprint-tracked` feature, it can
+  send `fingerprintTracked`, the top-level entry names of `project` that its
+  git tracks although an ignore pattern matches them, which the machine's
+  empty index would skip. It returns `{ "job" }`. It fails with
   `build-busy` while the offer would be declined, naming the reason, or while
   another build of the same client and repository runs, or while every one
   of this machine's `concurrency.maxBuilds` slots is held, and with
@@ -2497,7 +2521,6 @@ silent only when every notification it sums up is. An older server ignores
 `levels` and alerts for every event but `started`.
 
 The server and phone import the same pure rules from `@stim-cli/core/oversight`.
-The phone formats home attention messages locally from the facts the shared rule selects.
 `__tests__/oversight-agreement.test.ts` checks their categories, workspace names
 and needs-attention vectors. Notification delivery remains local to each.
 

package/dist/{protocol-BKpAsa9G.mjs → protocol-B8Ztv1K4.mjs}

@@ -2275,6 +2275,20 @@ function protocolJsonSchema() {
 						pattern: "^[a-f0-9]{64}$"
 					}
 				}, ["gatewayPort", "secret"])),
+				request("device-host.metro.ports", {
+					type: "object",
+					required: ["ports"],
+					additionalProperties: false,
+					properties: { ports: {
+						type: "array",
+						maxItems: 256,
+						items: {
+							type: "integer",
+							minimum: 1,
+							maximum: 65535
+						}
+					} }
+				}),
 				request("device-host.metro.close", session({})),
 				request("device-host.frames.subscribe", session({
 					fps: {
@@ -3106,6 +3120,48 @@ function protocolJsonSchema() {
 							type: ["string", "null"],
 							minLength: 1
 						},
+						fingerprintSources: {
+							type: "array",
+							maxItems: 2e4,
+							description: "The id and hash of each source of fingerprint, to name the sources that differ.",
+							items: {
+								type: "object",
+								required: ["id", "hash"],
+								additionalProperties: false,
+								properties: {
+									id: {
+										type: "string",
+										minLength: 1,
+										maxLength: 1024
+									},
+									hash: {
+										type: ["string", "null"],
+										pattern: "^[0-9a-f]{1,128}$"
+									}
+								}
+							}
+						},
+						fingerprintIgnored: {
+							type: "array",
+							maxItems: 2e4,
+							description: "Paths relative to project that git ignores for fingerprint on the caller, such as through .git/info/exclude.",
+							items: {
+								type: "string",
+								minLength: 1,
+								maxLength: 1024
+							}
+						},
+						fingerprintTracked: {
+							type: "array",
+							maxItems: 2e4,
+							description: "Top-level entries of project that the caller git tracks for fingerprint although an ignore pattern matches them.",
+							items: {
+								type: "string",
+								minLength: 1,
+								maxLength: 255,
+								pattern: "^[^/\\u0000]+$"
+							}
+						},
 						native: { oneOf: [{
 							type: "object",
 							required: [

package/dist/protocol.mjs

@@ -1,3 +1,3 @@
-import { t as protocolJsonSchema } from "./protocol-BKpAsa9G.mjs";
+import { t as protocolJsonSchema } from "./protocol-B8Ztv1K4.mjs";
 export * from "@stim-cli/core/protocol";
 export { protocolJsonSchema };

package/dist/protocol.schema.json

@@ -1271,10 +1271,14 @@
               "native-gradle-artifact-cache",
               "native-gradle-peer-cache",
               "react-native-peer-cache",
+              "fingerprint-sources",
+              "fingerprint-ignored",
+              "fingerprint-tracked",
               "swiftpm-peer-cache",
               "build-dependency-cache",
               "hosted-android-data",
               "hosted-android-process",
+              "hosted-metro-ports",
               "server-update",
               "status-views",
               "desktop-reports",
@@ -3183,6 +3187,44 @@
             }
           }
         },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "device-host.metro.ports"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "ports"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "ports": {
+                  "type": "array",
+                  "maxItems": 256,
+                  "items": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535
+                  }
+                }
+              }
+            }
+          }
+        },
         {
           "type": "object",
           "required": [
@@ -7303,6 +7345,54 @@
                   ],
                   "minLength": 1
                 },
+                "fingerprintSources": {
+                  "type": "array",
+                  "maxItems": 20000,
+                  "description": "The id and hash of each source of fingerprint, to name the sources that differ.",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "hash"
+                    ],
+                    "additionalProperties": false,
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "hash": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "pattern": "^[0-9a-f]{1,128}$"
+                      }
+                    }
+                  }
+                },
+                "fingerprintIgnored": {
+                  "type": "array",
+                  "maxItems": 20000,
+                  "description": "Paths relative to project that git ignores for fingerprint on the caller, such as through .git/info/exclude.",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  }
+                },
+                "fingerprintTracked": {
+                  "type": "array",
+                  "maxItems": 20000,
+                  "description": "Top-level entries of project that the caller git tracks for fingerprint although an ignore pattern matches them.",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 255,
+                    "pattern": "^[^/\\u0000]+$"
+                  }
+                },
                 "native": {
                   "oneOf": [
                     {

package/dist/{stim-server-Z2tFBWaG.mjs → stim-server-Z40-_Git.mjs}

@@ -1,4 +1,4 @@
-import { n as protocol_exports } from "./protocol-BKpAsa9G.mjs";
+import { n as protocol_exports } from "./protocol-B8Ztv1K4.mjs";
 import { createRequire } from "node:module";
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { appendFileSync, chmodSync, closeSync, constants, copyFileSync, cpSync, createReadStream, existsSync, futimesSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, statfsSync, watch, writeFileSync, writeSync } from "node:fs";
@@ -3226,6 +3226,32 @@ function validFile(file) {
 const validRepo = (repo) => typeof repo === "string" && new RegExp(protocol_exports.BUILD_REPO_PATTERN).test(repo);
 const gb = (bytes) => (bytes / 1024 ** 3).toFixed(1);
 const optional = (value) => typeof value === "string" ? value : null;
+const MAX_FINGERPRINT_SOURCES = 2e4;
+function fingerprintSources(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.length > MAX_FINGERPRINT_SOURCES) return null;
+	return value.every((source) => isJsonObject(source) && Object.keys(source).every((key) => key === "id" || key === "hash") && typeof source.id === "string" && source.id.length > 0 && source.id.length <= MAX_PATH_CHARS && (source.hash === null || typeof source.hash === "string" && /^[0-9a-f]{1,128}$/.test(source.hash))) ? value : null;
+}
+function fingerprintIgnored(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.length > MAX_FINGERPRINT_SOURCES) return null;
+	const paths = [];
+	for (const path of value) {
+		if (typeof path !== "string" || path.length === 0 || path.length > MAX_PATH_CHARS) return null;
+		paths.push(path);
+	}
+	return paths;
+}
+function fingerprintTracked(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.length > MAX_FINGERPRINT_SOURCES) return null;
+	const names = [];
+	for (const name of value) {
+		if (!(typeof name === "string" && name.length > 0 && name.length <= 255 && name !== "." && name !== ".." && !/[/\0]/.test(name))) return null;
+		names.push(name);
+	}
+	return names;
+}
 const GRADLE_NAME = /^[A-Za-z0-9_-]{1,100}$/;
 const GRADLE_ROOT = /^[A-Za-z0-9._/ -]{1,200}$/;
 const GRADLE_MODULE = /^(:(?!\.\.?(?::|$))[A-Za-z0-9._-]+){1,20}$/;
@@ -3522,7 +3548,7 @@ var BuildHost = class {
 			},
 			warm: {
 				checkout: existsSync(join(area, "src")),
-				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, dependencies.packageName, params.lockfile, this.options.env),
+				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, params.lockfile, this.options.env),
 				build: false
 			},
 			...artifact !== void 0 ? { artifact } : {}
@@ -4305,7 +4331,13 @@ var BuildSession = class {
 			native = input;
 		}
 		if (native?.provider !== "gradle" && (typeof params.fingerprint !== "string" || !params.fingerprint)) return refusal("bad-request", "build.start needs params.fingerprint.");
+		const expectedSources = fingerprintSources(params.fingerprintSources);
+		if (expectedSources === null) return refusal("bad-request", `params.fingerprintSources must be at most ${MAX_FINGERPRINT_SOURCES} sources, each an id and a hex hash or null.`);
 		if (!native && [...this.files.values()].some((file) => file.kind === "directory")) return refusal("bad-request", "Directory entries require a native build request.");
+		const expectedIgnored = fingerprintIgnored(params.fingerprintIgnored);
+		if (expectedIgnored === null) return refusal("bad-request", `params.fingerprintIgnored must be at most ${MAX_FINGERPRINT_SOURCES} paths of at most ${MAX_PATH_CHARS} characters.`);
+		const expectedTracked = fingerprintTracked(params.fingerprintTracked);
+		if (expectedTracked === null) return refusal("bad-request", `params.fingerprintTracked must be at most ${MAX_FINGERPRINT_SOURCES} top-level entry names.`);
 		const android = platform === "android" ? androidOptions(params.android) : null;
 		if (platform === "android" && !android) return refusal("bad-request", "An android build needs params.android: variant and abi (string or null), gradleBuildCache, pch and compilerCache.");
 		let macos = null;
@@ -4333,7 +4365,6 @@ var BuildSession = class {
 				android,
 				macos,
 				project: params.project,
-				packageName: optional(params.packageName),
 				isExpo: params.isExpo === true,
 				cacheArtifact: params.cacheArtifact === true,
 				stimBuild: params.stimBuild,
@@ -4342,6 +4373,9 @@ var BuildSession = class {
 				iosProjectPath: optional(params.iosProjectPath),
 				runtime: optional(params.runtime),
 				expectedFingerprint: params.fingerprint,
+				...expectedSources ? { expectedSources } : {},
+				...expectedIgnored ? { expectedIgnored } : {},
+				...expectedTracked ? { expectedTracked } : {},
 				optimizations: isJsonObject(params.optimizations) ? params.optimizations : null
 			}
 		});
@@ -6823,6 +6857,28 @@ function hostedDeviceExclusions(records) {
 		key: hostedDeviceId(record.device)
 	}] : []);
 }
+/** macOS lets 127.0.0.1 bind beside a wildcard listener and takes its loopback traffic, so probe by connecting. */
+function loopbackAccepts(port) {
+	const accepts = (host) => new Promise((resolve) => {
+		const socket = connect({
+			host,
+			port
+		});
+		const done = (open) => {
+			socket.destroy();
+			resolve(open);
+		};
+		socket.setTimeout(1e3, () => done(true));
+		socket.once("connect", () => done(true));
+		socket.once("error", (error) => done(![
+			"ECONNREFUSED",
+			"EADDRNOTAVAIL",
+			"EAFNOSUPPORT",
+			"ENETUNREACH"
+		].includes(error.code ?? "")));
+	});
+	return Promise.all([accepts("127.0.0.1"), accepts("::1")]).then((open) => open.includes(true));
+}
 /** Owns hosted reservations, not build jobs or viewer connections. Native work runs in the packaged CLI child. */
 var DeviceHost = class {
 	owned = /* @__PURE__ */ new Map();
@@ -7190,15 +7246,20 @@ var DeviceHost = class {
 				await this.restoreAndroidMetro(record, owned);
 				return { result: { port } };
 			}
+			const devClientPort = record.platform === "ios" ? params.clientMetroPort : void 0;
 			const bridge = createMetroBridge({
 				peer,
 				gatewayPort: params.gatewayPort,
 				secret: params.secret
 			});
-			const ready = new Promise((resolve, reject) => {
-				bridge.server.once("error", reject);
-				bridge.server.listen(record.metroPort ?? 0, "127.0.0.1", () => resolve(bridge.server.address().port));
-			});
+			const inUse = () => Object.assign(/* @__PURE__ */ new Error(`Port ${devClientPort} is in use on the hosting Mac, and an Expo dev client loads its bundle from the client's Metro port.`), { code: "device-busy" });
+			const ready = (async () => {
+				if (devClientPort !== void 0 && await loopbackAccepts(devClientPort)) throw inUse();
+				return new Promise((resolve, reject) => {
+					bridge.server.once("error", (error) => reject(devClientPort !== void 0 && error.code === "EADDRINUSE" ? inUse() : error));
+					bridge.server.listen(devClientPort ?? record.metroPort ?? 0, "127.0.0.1", () => resolve(bridge.server.address().port));
+				});
+			})();
 			const metro = {
 				bridge,
 				ready,
@@ -7224,7 +7285,7 @@ var DeviceHost = class {
 				throw error;
 			}
 		} catch (error) {
-			return refused$1("action-failed", error.message);
+			return refused$1(error.code === "device-busy" ? "device-busy" : "action-failed", error.message);
 		}
 	}
 	async restoreAndroidMetro(record, owned) {
@@ -7253,6 +7314,24 @@ var DeviceHost = class {
 			if (owned.data === settled) delete owned.data;
 		}
 	}
+	/** Names the ports a new dev-client bridge could not bind, apart from this client's own dev-client bridges. */
+	async metroPorts(client, params) {
+		if (this.closed || !this.options.allowed(client)) return refused$1("forbidden", "Current device-host approval is required.");
+		if (!isJsonObject(params) || !Array.isArray(params.ports) || params.ports.length > 256 || params.ports.some((port) => typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) return refused$1("bad-request", "Metro ports needs at most 256 TCP ports.");
+		try {
+			const ports = [...new Set(params.ports)];
+			const sessions = new Set(readHostedSessions().flatMap((record) => record.client === client ? [record.id] : []));
+			const own = new Set([...this.owned].flatMap(([id, { metro }]) => sessions.has(id) && metro?.port !== void 0 && metro.port === metro.clientMetroPort ? [metro.port] : []));
+			const busy = [];
+			const queue = ports.filter((port) => !own.has(port));
+			await Promise.all(Array.from({ length: 16 }, async () => {
+				for (let port = queue.shift(); port !== void 0; port = queue.shift()) if (await loopbackAccepts(port)) busy.push(port);
+			}));
+			return { result: { busy: busy.toSorted((a, b) => a - b) } };
+		} catch (error) {
+			return refused$1("action-failed", error.message);
+		}
+	}
 	async metroClose(client, params) {
 		if (!this.options.allowed(client)) return refused$1("forbidden", "Current device-host approval is required.");
 		if (!isJsonObject(params) || typeof params.session !== "string") return refused$1("bad-request", "Metro close needs a session.");
@@ -16909,7 +16988,7 @@ async function startServer(options) {
 				});
 			}
 			if (method.startsWith("device-host.input.")) return input(id, method.slice(12), raw, session);
-			const answer = method === "device-host.offer" ? await hostedDevices.offer(session.id, raw) : method === "device-host.reserve" ? await hostedDevices.reserve(session.id, raw) : method === "device-host.attach" ? hostedDevices.attach(session.id, raw) : method === "device-host.stop" ? hostedDevices.stop(session.id, raw) : method === "device-host.app.offer" ? hostedDevices.appOffer(session.id, raw) : method === "device-host.app.chunk" ? await hostedDevices.appChunk(session.id, raw) : method === "device-host.app.handoff" ? await hostedDevices.appHandoff(session.id, raw) : method === "device-host.app.launch" ? hostedDevices.appLaunch(session.id, raw) : method === "device-host.app.attach" ? hostedDevices.appAttach(session.id, raw) : method === "device-host.logs.query" ? await hostedDevices.logsQuery(session.id, raw) : method === "device-host.metro.open" ? await hostedDevices.metroOpen(session.id, raw, peer) : await hostedDevices.metroClose(session.id, raw);
+			const answer = method === "device-host.offer" ? await hostedDevices.offer(session.id, raw) : method === "device-host.reserve" ? await hostedDevices.reserve(session.id, raw) : method === "device-host.attach" ? hostedDevices.attach(session.id, raw) : method === "device-host.stop" ? hostedDevices.stop(session.id, raw) : method === "device-host.app.offer" ? hostedDevices.appOffer(session.id, raw) : method === "device-host.app.chunk" ? await hostedDevices.appChunk(session.id, raw) : method === "device-host.app.handoff" ? await hostedDevices.appHandoff(session.id, raw) : method === "device-host.app.launch" ? hostedDevices.appLaunch(session.id, raw) : method === "device-host.app.attach" ? hostedDevices.appAttach(session.id, raw) : method === "device-host.logs.query" ? await hostedDevices.logsQuery(session.id, raw) : method === "device-host.metro.open" ? await hostedDevices.metroOpen(session.id, raw, peer) : method === "device-host.metro.ports" ? await hostedDevices.metroPorts(session.id, raw) : await hostedDevices.metroClose(session.id, raw);
 			return send(socket, "error" in answer ? {
 				id,
 				error: answer.error

package/dist/stim-server.mjs

@@ -4,6 +4,6 @@ const encode = (version) => version.split(".", 3).reduce((sum, part) => sum * 1e
 if (encode(process.versions.node) < encode("22.12.0")) {
 	process.stderr.write(`STIM_NODE_UNSUPPORTED: stim-server needs Node 22.12.0 or later; this is Node ${process.versions.node} at ${process.execPath}. To run stim-server where a project pins an older Node, see https://stim.appandflow.com/docs/requirements#older-node-pins\n`);
 	process.exitCode = 1;
-} else import("./stim-server-Z2tFBWaG.mjs");
+} else import("./stim-server-Z40-_Git.mjs");
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/server",
-  "version": "1.23.1",
+  "version": "1.24.0",
   "description": "Serves Stim status to paired clients over Tailscale, and runs reload and stop for clients granted control.",
   "license": "MIT",
   "repository": {
@@ -28,13 +28,13 @@
     "./protocol.schema.json": "./dist/protocol.schema.json"
   },
   "dependencies": {
-    "@stim-cli/agent-driver": "^1.23.1",
-    "@stim-cli/agent-driver-agent-device": "^1.23.1",
-    "@stim-cli/cache": "^1.23.1",
-    "@stim-cli/core": "^1.23.1",
-    "@stim-cli/transport": "^1.23.1",
-    "@stim-cli/transport-tailscale": "^1.23.1",
-    "stim": "1.23.1",
+    "@stim-cli/agent-driver": "^1.24.0",
+    "@stim-cli/agent-driver-agent-device": "^1.24.0",
+    "@stim-cli/cache": "^1.24.0",
+    "@stim-cli/core": "^1.24.0",
+    "@stim-cli/transport": "^1.24.0",
+    "@stim-cli/transport-tailscale": "^1.24.0",
+    "stim": "1.24.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {