Default SEA binary server-v3 to only bind to localhost (#2091)

## Summary
- default the v3 server listener to localhost unless HOST is explicitly
set
- warn when HOST=0.0.0.0 opts into all-interface binding
- make the v4 SEA build choose a Node binary that contains the SEA fuse

## Validation
- pnpm --filter @browserbasehq/stagehand-server-v3 run build:esm-tests
- pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck
- pnpm --filter @browserbasehq/stagehand-server-v4 run typecheck
- pnpm --filter @browserbasehq/stagehand-server-v3 run test:unit --
packages/server-v3/dist/tests/unit/listenHost.test.js
- pnpm --filter @browserbasehq/stagehand-server-v4 run build:sea:esm --
--binary-name=stagehand-server-v4-localhost-binding-test

Leaving the full suite to CI.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Default `@browserbasehq/stagehand-server-v3` to listen on localhost
unless `HOST` is set, and warn on `HOST=0.0.0.0` to prevent accidental
exposure. Also make the `@browserbasehq/stagehand-server-v4` SEA build
use a Node binary that includes the SEA fuse for reliable builds.

- New Features
- Default listen host to `localhost` when `HOST` is unset or blank;
respect explicit values.
  - Warn when `HOST=0.0.0.0` to make all-interface binding explicit.

- Migration
- If you need external access, set `HOST=0.0.0.0` (or a specific
interface).

<sup>Written for commit 3cecdce.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

Author: pirate

.changeset/local-host-default.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand-server-v3": patch
+---
+
+Default the v3 server listener to localhost, respect explicit HOST values, and warn when HOST=0.0.0.0 exposes all interfaces.

packages/server-v3/src/lib/listenHost.ts

@@ -0,0 +1,25 @@
+export const DEFAULT_LISTEN_HOST = "localhost";
+export const ALL_INTERFACES_LISTEN_HOST = "0.0.0.0";
+
+const allInterfacesWarning =
+  "HOST=0.0.0.0 was passed explicitly, so the Stagehand server will listen on all network interfaces. Use HOST=localhost or HOST=127.0.0.1 unless you intend to expose this server beyond the local machine.";
+
+export type ListenHostConfig = {
+  host: string;
+  warning?: string;
+};
+
+export const getListenHostConfig = (
+  hostEnv = process.env.HOST,
+): ListenHostConfig => {
+  const host = hostEnv?.trim() || DEFAULT_LISTEN_HOST;
+
+  if (host === ALL_INTERFACES_LISTEN_HOST) {
+    return {
+      host,
+      warning: allInterfacesWarning,
+    };
+  }
+
+  return { host };
+};

packages/server-v3/src/server.ts

@@ -17,6 +17,7 @@ import {
 import { StatusCodes } from "http-status-codes";
 
 import { logging } from "./lib/logging/index.js";
+import { getListenHostConfig } from "./lib/listenHost.js";
 import {
   destroySessionStore,
   initializeSessionStore,
@@ -258,8 +259,13 @@ const start = async () => {
     appWithTypes.route(readinessRoute);
     await app.ready();
 
+    const listenHost = getListenHostConfig();
+    if (listenHost.warning) {
+      app.log.warn(listenHost.warning);
+    }
+
     await app.listen({
-      host: "0.0.0.0",
+      host: listenHost.host,
       port: parseInt(process.env.PORT ?? "3000", 10),
     });
     console.log("Routes registered:", app.printRoutes());

packages/server-v3/tests/unit/listenHost.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  ALL_INTERFACES_LISTEN_HOST,
+  DEFAULT_LISTEN_HOST,
+  getListenHostConfig,
+} from "../../src/lib/listenHost.js";
+
+describe("getListenHostConfig", () => {
+  it("defaults to localhost when HOST is not provided", () => {
+    assert.deepEqual(getListenHostConfig(undefined), {
+      host: DEFAULT_LISTEN_HOST,
+    });
+  });
+
+  it("defaults to localhost when HOST is blank", () => {
+    assert.deepEqual(getListenHostConfig("  "), {
+      host: DEFAULT_LISTEN_HOST,
+    });
+  });
+
+  it("respects explicit localhost host values", () => {
+    assert.deepEqual(getListenHostConfig("localhost"), {
+      host: "localhost",
+    });
+    assert.deepEqual(getListenHostConfig("127.0.0.1"), {
+      host: "127.0.0.1",
+    });
+  });
+
+  it("warns when HOST explicitly requests all interfaces", () => {
+    const config = getListenHostConfig(ALL_INTERFACES_LISTEN_HOST);
+
+    assert.equal(config.host, ALL_INTERFACES_LISTEN_HOST);
+    assert.match(config.warning ?? "", /listen on all network interfaces/);
+  });
+});

packages/server-v4/scripts/build-sea.ts

@@ -23,6 +23,7 @@ import esbuild from "esbuild";
 import { getRepoRootDir } from "./runtimePaths.js";
 
 const repoDir = getRepoRootDir();
+const seaFuse = "NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2";
 
 const argValue = (name: string) => {
   const prefix = `--${name}=`;
@@ -119,6 +120,14 @@ const runOptional = (
   spawnSync(cmd, args, { stdio: "ignore", ...opts });
 };
 
+const hasSeaFuse = (binaryPath: string): boolean => {
+  try {
+    return fs.readFileSync(binaryPath).includes(Buffer.from(seaFuse));
+  } catch {
+    return false;
+  }
+};
+
 const download = (url: string, dest: string): Promise<void> =>
   new Promise((resolve, reject) => {
     https
@@ -167,15 +176,20 @@ const resolveNodeBinary = async (): Promise<string> => {
       `Cross-platform builds are not supported. Host=${process.platform}, target=${targetPlatform}`,
     );
   }
-  if (targetArch === process.arch) {
+  if (targetArch === process.arch && hasSeaFuse(process.execPath)) {
     return process.execPath;
   }
+  if (targetArch === process.arch) {
+    console.warn(
+      `Current Node binary at ${process.execPath} does not include ${seaFuse}; falling back to the official ${process.version} distribution for SEA injection.`,
+    );
+  }
 
   const version = process.version;
   const distPlatform = targetPlatform === "win32" ? "win" : targetPlatform;
   const archiveBase = `node-${version}-${distPlatform}-${targetArch}`;
   const archiveExt = distPlatform === "win" ? "zip" : "tar.xz";
-  const tmpRoot = `${os.tmpdir()}/stagehand-sea/${archiveBase}`;
+  const tmpRoot = `${os.tmpdir()}/stagehand-server-v4-sea/${archiveBase}`;
   const archivePath = `${tmpRoot}/${archiveBase}.${archiveExt}`;
   const extractRoot = `${tmpRoot}/${archiveBase}`;
   const binaryPath =
@@ -184,6 +198,11 @@ const resolveNodeBinary = async (): Promise<string> => {
       : `${extractRoot}/bin/node`;
 
   if (fs.existsSync(binaryPath)) {
+    if (!hasSeaFuse(binaryPath)) {
+      throw new Error(
+        `Node binary at ${binaryPath} does not include ${seaFuse}; unable to build SEA binary. Delete ${tmpRoot} and retry.`,
+      );
+    }
     return binaryPath;
   }
 
@@ -208,6 +227,11 @@ const resolveNodeBinary = async (): Promise<string> => {
   if (!fs.existsSync(binaryPath)) {
     throw new Error(`Missing Node binary at ${binaryPath}`);
   }
+  if (!hasSeaFuse(binaryPath)) {
+    throw new Error(
+      `Node binary at ${binaryPath} does not include ${seaFuse}; unable to build SEA binary. Delete ${tmpRoot} and retry.`,
+    );
+  }
   return binaryPath;
 };
 
@@ -477,7 +501,7 @@ const main = async () => {
     "NODE_SEA_BLOB",
     `${repoDir}/packages/server-v4/dist/sea/sea-prep.blob`,
     "--sentinel-fuse",
-    "NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2",
+    seaFuse,
   ];
   if (targetPlatform === "darwin") {
     postjectArgs.push("--macho-segment-name", "NODE_SEA");