test(relay): bind test WebSocket servers to loopback

A control-handshake test that expects a timeout was instead getting 'Unexpected server response: 401' about once in fourteen runs. A slow machine cannot turn a timeout into a 401 -- that needs a real HTTP response, so the connection was reaching a different server. new WebSocketServer({ port: 0 }) binds the wildcard address while the client dials 127.0.0.1. On macOS those differ, and with SO_REUSEADDR a foreign process can hold the more specific 127.0.0.1:P and win the connection. Caught live: a wildcard bind took port 52584, which a running Orca app already held on loopback, and Orca answered the probe. A listener that checks a token answers 401. Ten constructions across seven files now pass host: '127.0.0.1', so the reservation covers the address the client dials and a duplicate bind is refused. Adds a ratchet, because this is not authors forgetting a convention: all 30+ .listen(0, ...) sites already pass '127.0.0.1', while 7 of 7 ws constructions did not. ws accepts { port } alone and binds the wildcard silently, so nothing told them. The guard pins the wildcard count, and pins separately at zero the option shapes it cannot read -- spreads and variable option objects fail rather than being exempted, and a recognized-construction floor catches the matcher going blind, which otherwise reads exactly like a clean tree. mobile/scripts/mock-server.ts stays on the wildcard deliberately: a phone reaches it over the LAN.
2026-09-29 16:02:50 +00:00 · 2026-09-01 19:05:42 -07:00
parent 8b7d778a2e
commit fdfe354045
14 changed files with 529 additions and 15 deletions
@@ -0,0 +1,14 @@
+# Files allowed to construct a `ws` server that binds a port without pinning `host`.
+#
+# `ws` accepts `{ port }` alone and silently binds the wildcard address. A server
+# reached over 127.0.0.1 must pin `host: '127.0.0.1'`, or a foreign loopback
+# listener can hold the same port and answer in its place -- which is how
+# relay-control-client.test.ts came to fail with a real HTTP 401 in a test that
+# was simulating silence.
+#
+# This list only shrinks. Adding a line also requires raising the pin in
+# websocket-server-loopback-bind.test.ts, which is deliberate friction.
+
+# Deliberate, not drift: this mock is dialled by a phone on the LAN, so it has to
+# be reachable on a real interface. A loopback bind would make it unreachable.
+mobile/scripts/mock-server.ts
@@ -0,0 +1,204 @@
+/**
+ * Read the top-level option keys of a call's object-literal argument out of raw
+ * source text.
+ *
+ * Text rather than an AST because typescript@7 no longer ships the classic
+ * compiler API and every installed parser is a transitive dependency. The
+ * tradeoff is handled by refusing to guess: any shape this cannot read comes
+ * back as `unreadable` with a reason, and callers must treat that as a failure
+ * rather than as an absence of keys.
+ */
+
+export type CallOptionKeys =
+  | { readonly readable: true; readonly keys: readonly string[] }
+  | { readonly readable: false; readonly reason: string }
+
+type ScanState = 'code' | 'line' | 'block' | 'single' | 'double' | 'template'
+
+function closesString(state: ScanState, current: string): boolean {
+  return (
+    (state === 'single' && current === "'") ||
+    (state === 'double' && current === '"') ||
+    (state === 'template' && current === '`')
+  )
+}
+
+function opensNonCode(current: string, next: string | undefined): ScanState | null {
+  if (current === '/' && next === '/') {
+    return 'line'
+  }
+  if (current === '/' && next === '*') {
+    return 'block'
+  }
+  if (current === "'") {
+    return 'single'
+  }
+  if (current === '"') {
+    return 'double'
+  }
+  if (current === '`') {
+    return 'template'
+  }
+  return null
+}
+
+/**
+ * Text between an open paren and its match, tracking strings and comments so a
+ * brace inside either cannot unbalance the count. Null when it never closes.
+ */
+function balancedArguments(text: string, openIndex: number): string | null {
+  let depth = 0
+  let state: ScanState = 'code'
+  for (let index = openIndex; index < text.length; index++) {
+    const current = text[index]
+    const next = text[index + 1]
+    if (state === 'code') {
+      const opened = opensNonCode(current, next)
+      if (opened) {
+        state = opened
+        if (opened === 'line' || opened === 'block') {
+          index++
+        }
+      } else if (current === '(' || current === '{' || current === '[') {
+        depth++
+      } else if (current === ')' || current === '}' || current === ']') {
+        depth--
+        if (depth === 0) {
+          return text.slice(openIndex + 1, index)
+        }
+        if (depth < 0) {
+          return null
+        }
+      }
+      continue
+    }
+    if (state === 'line') {
+      if (current === '\n') {
+        state = 'code'
+      }
+      continue
+    }
+    if (state === 'block') {
+      if (current === '*' && next === '/') {
+        state = 'code'
+        index++
+      }
+      continue
+    }
+    if (current === '\\') {
+      index++
+      continue
+    }
+    // Brace tracking inside `${}` would need its own depth; templates never
+    // appear as options, so report one as unreadable instead of guessing.
+    if (state === 'template' && current === '$' && next === '{') {
+      return null
+    }
+    if (closesString(state, current)) {
+      state = 'code'
+    }
+  }
+  return null
+}
+
+/** Keys at depth 0 of an object literal body, with anything non-identifier kept verbatim. */
+function objectLiteralKeys(body: string): string[] {
+  const keys: string[] = []
+  let depth = 0
+  let state: ScanState = 'code'
+  let inValue = false
+  let token = ''
+  const flush = (): void => {
+    const name = token.trim()
+    token = ''
+    if (name && depth === 0) {
+      keys.push(name)
+    }
+  }
+  for (let index = 0; index < body.length; index++) {
+    const current = body[index]
+    const next = body[index + 1]
+    if (state === 'code') {
+      const opened = opensNonCode(current, next)
+      if (opened) {
+        state = opened
+        if (opened === 'line' || opened === 'block') {
+          index++
+        }
+      } else if (current === '(' || current === '{' || current === '[') {
+        depth++
+        if (!inValue) {
+          token += current
+        }
+      } else if (current === ')' || current === '}' || current === ']') {
+        depth--
+        if (!inValue) {
+          token += current
+        }
+      } else if (current === ':' && depth === 0 && !inValue) {
+        flush()
+        inValue = true
+      } else if (current === ',' && depth === 0) {
+        // A shorthand or a spread ends here having never seen a colon.
+        if (inValue) {
+          inValue = false
+          token = ''
+        } else {
+          flush()
+        }
+      } else if (!inValue) {
+        token += current
+      }
+      continue
+    }
+    if (state === 'line') {
+      if (current === '\n') {
+        state = 'code'
+      }
+      continue
+    }
+    if (state === 'block') {
+      if (current === '*' && next === '/') {
+        state = 'code'
+        index++
+      }
+      continue
+    }
+    if (current === '\\') {
+      index++
+      continue
+    }
+    if (closesString(state, current)) {
+      state = 'code'
+    }
+  }
+  if (!inValue) {
+    flush()
+  }
+  return keys
+}
+
+/**
+ * Option keys of the call whose argument list opens at `parenIndex`, or the
+ * reason the shape could not be read. Spreads and computed keys land in the
+ * latter: either can carry a key this would otherwise report as absent.
+ */
+export function readCallOptionKeys(text: string, parenIndex: number): CallOptionKeys {
+  const args = balancedArguments(text, parenIndex)
+  if (args === null) {
+    return { readable: false, reason: 'argument list never closes' }
+  }
+  if (!args.trim()) {
+    return { readable: false, reason: 'called with no options argument' }
+  }
+  const trimmed = args.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    return { readable: false, reason: 'options are not an object literal' }
+  }
+  const keys = objectLiteralKeys(trimmed.slice(1, -1))
+  const unreadable = keys.find((key) => !/^[A-Za-z_$][\w$]*$/.test(key))
+  if (unreadable !== undefined) {
+    return { readable: false, reason: `unreadable option key \`${unreadable}\`` }
+  }
+  return { readable: true, keys }
+}
@@ -0,0 +1,172 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { readCallOptionKeys } from './call-site-option-keys'
+
+/**
+ * Locate every `new WebSocketServer(...)` in the tree and say, for each, whether
+ * it pins a bind address.
+ *
+ * `ws` accepts `{ port }` alone and silently binds the wildcard address, so a
+ * server the caller then dials on 127.0.0.1 sits at a port a foreign loopback
+ * listener can also hold -- and the more specific listener wins the connection,
+ * answering in that server's place.
+ *
+ * Anything unreadable is reported as `opaque` rather than skipped. A matcher
+ * that silently exempts the shapes it fails to parse is worse than no matcher,
+ * because it reads as coverage.
+ */
+
+export type BindSite = { path: string; line: number }
+export type OpaqueSite = BindSite & { reason: string }
+
+export type WebSocketServerBindScan = {
+  filesScanned: number
+  /** Every construction recognized, however it was then classified. */
+  constructions: number
+  /** Binds a port with no `host`: reachable at an address the dialer never named. */
+  wildcardBound: BindSite[]
+  /** Shape that could not be read; never treated as safe. */
+  opaque: OpaqueSite[]
+  /** Binds a port and pins `host`. */
+  loopbackBound: BindSite[]
+  /** No `port`: attaches to a server that owns the bind itself. */
+  attached: BindSite[]
+}
+
+const IGNORED_DIRECTORIES = new Set([
+  'node_modules',
+  'dist',
+  'out',
+  'build',
+  '.git',
+  '__fixtures__',
+  'coverage',
+  // Full snapshots of older releases; their bind sites are not this tree's to fix.
+  '.cross-version-checkouts'
+])
+const SCANNED_EXTENSIONS = /\.(?:ts|tsx|mts|cts)$/
+const SCANNED_ROOTS = ['src', 'mobile', 'config', 'tests']
+const WS_IMPORT_HINT = /from\s*['"]ws['"]/
+
+function collectSourceFiles(root: string, found: string[] = []): string[] {
+  let entries: ReturnType<typeof readdirSync<{ withFileTypes: true }>>
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return found
+  }
+  for (const entry of entries) {
+    if (IGNORED_DIRECTORIES.has(entry.name)) {
+      continue
+    }
+    const full = join(root, entry.name)
+    if (entry.isDirectory()) {
+      collectSourceFiles(full, found)
+    } else if (SCANNED_EXTENSIONS.test(entry.name)) {
+      found.push(full)
+    }
+  }
+  return found
+}
+
+/** Local names bound to ws's server class, following `as` aliases and namespace imports. */
+function webSocketServerNames(text: string): { direct: Set<string>; namespaces: Set<string> } {
+  const direct = new Set<string>()
+  const namespaces = new Set<string>()
+  // One statement at a time: a pattern reaching for `from 'ws'` would swallow
+  // every import above it and lose the specifier names in the blob.
+  for (const match of text.matchAll(/\bimport\b([\s\S]*?)\bfrom\s*(['"])([^'"]+)\2/g)) {
+    if (match[3] !== 'ws') {
+      continue
+    }
+    const clause = match[1]
+    if (/^\s*type\b/.test(clause)) {
+      continue
+    }
+    const namespace = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/)
+    if (namespace) {
+      namespaces.add(namespace[1])
+    }
+    const named = clause.match(/\{([\s\S]*)\}/)
+    if (!named) {
+      continue
+    }
+    for (const specifier of named[1].split(',')) {
+      const trimmed = specifier.trim()
+      if (!trimmed || /^type\s/.test(trimmed)) {
+        continue
+      }
+      const parts = trimmed.split(/\s+as\s+/)
+      // `Server` is ws's own alias for WebSocketServer.
+      if (parts[0].trim() === 'WebSocketServer' || parts[0].trim() === 'Server') {
+        direct.add((parts[1] ?? parts[0]).trim())
+      }
+    }
+  }
+  return { direct, namespaces }
+}
+
+function classify(
+  scan: WebSocketServerBindScan,
+  site: BindSite,
+  text: string,
+  paren: number
+): void {
+  const options = readCallOptionKeys(text, paren)
+  if (!options.readable) {
+    scan.opaque.push({ ...site, reason: options.reason })
+    return
+  }
+  if (!options.keys.includes('port')) {
+    scan.attached.push(site)
+    return
+  }
+  if (!options.keys.includes('host')) {
+    scan.wildcardBound.push(site)
+    return
+  }
+  scan.loopbackBound.push(site)
+}
+
+export function scanWebSocketServerBinds(repoRoot: string): WebSocketServerBindScan {
+  const files = SCANNED_ROOTS.flatMap((directory) => collectSourceFiles(join(repoRoot, directory)))
+  const scan: WebSocketServerBindScan = {
+    filesScanned: files.length,
+    constructions: 0,
+    wildcardBound: [],
+    opaque: [],
+    loopbackBound: [],
+    attached: []
+  }
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8')
+    // Filter on the import, not on the class name: `Server as Wss` never spells
+    // WebSocketServer, and keying on that name silently skipped the whole alias.
+    if (!WS_IMPORT_HINT.test(text)) {
+      continue
+    }
+    const { direct, namespaces } = webSocketServerNames(text)
+    if (!direct.size && !namespaces.size) {
+      continue
+    }
+    const path = relative(repoRoot, file).split('\\').join('/')
+    const patterns = [
+      ...[...direct].map((name) => new RegExp(`\\bnew\\s+${name}\\s*\\(`, 'g')),
+      ...[...namespaces].map(
+        (name) => new RegExp(`\\bnew\\s+${name}\\.(?:WebSocketServer|Server)\\s*\\(`, 'g')
+      )
+    ]
+    for (const pattern of patterns) {
+      for (const match of text.matchAll(pattern)) {
+        scan.constructions++
+        const line = text.slice(0, match.index).split('\n').length
+        classify(scan, { path, line }, text, match.index + match[0].length - 1)
+      }
+    }
+  }
+  return scan
+}
+
+export function formatSites(sites: readonly BindSite[]): string[] {
+  return sites.map((site) => `${site.path}:${site.line}`)
+}
@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { formatSites, scanWebSocketServerBinds } from './websocket-server-bind-scan'
+
+/**
+ * Hold the bind address at the tree level rather than per call site.
+ *
+ * Every one of the ~30 `.listen(0, ...)` calls in this repo already passes
+ * '127.0.0.1'; 7 of 7 `new WebSocketServer({ port })` calls did not. Authors know
+ * the convention -- `ws` just never asks, because `{ port }` alone binds the
+ * wildcard without a word. That silence is what this test replaces.
+ *
+ * The allowlist only shrinks. A new wildcard bind fails here even where it looks
+ * harmless today, because harmless-looking is exactly what the seven were.
+ */
+/** The ratchet, held as data so it reads as the list it is. */
+const WILDCARD_BIND_ALLOWLIST: readonly string[] = readFileSync(
+  join(__dirname, '__fixtures__', 'websocket-server-wildcard-bind-allowlist.txt'),
+  'utf8'
+)
+  .split('\n')
+  .map((line) => line.trim())
+  .filter((line) => line.length > 0 && !line.startsWith('#'))
+
+/**
+ * The true count of constructions that bind a port without pinning a host.
+ *
+ * May only ever be DECREASED, and only by pinning a host. Raising it is never
+ * the fix.
+ */
+const WILDCARD_BIND_PIN = 1
+
+/**
+ * A floor under the constructions the scanner still recognizes.
+ *
+ * This is the guard against the scanner going blind: an import pattern it stops
+ * following reports zero offenders and reads exactly like a clean tree. During
+ * development a single wrong regex dropped this from 24 to 3.
+ */
+const RECOGNIZED_CONSTRUCTION_FLOOR = 20
+
+describe('WebSocketServer loopback bind boundary', () => {
+  const repoRoot = resolve(__dirname, '..', '..')
+  const scan = scanWebSocketServerBinds(repoRoot)
+  const offenders = scan.wildcardBound.map((site) => site.path)
+
+  it('scans a plausible number of files', () => {
+    // A broken root or extension list would make the guard silently vacuous.
+    expect(scan.filesScanned).toBeGreaterThan(5_000)
+  })
+
+  it('still recognizes the known construction sites', () => {
+    expect(
+      scan.constructions,
+      `Only ${scan.constructions} WebSocketServer constructions were recognized; the floor is ` +
+        `${RECOGNIZED_CONSTRUCTION_FLOOR}. The scanner has probably stopped following an import ` +
+        'shape rather than the tree having lost that many servers.'
+    ).toBeGreaterThanOrEqual(RECOGNIZED_CONSTRUCTION_FLOOR)
+  })
+
+  it('can read the options of every construction it found', () => {
+    // An unreadable shape is never assumed safe: it could be hiding a host, or
+    // hiding the absence of one. Rewrite it as a plain object literal.
+    expect(
+      scan.opaque.map((site) => `${site.path}:${site.line} -- ${site.reason}`),
+      'WebSocketServer options that this guard cannot read.'
+    ).toEqual([])
+  })
+
+  it('has no wildcard-bound server outside the allowlist', () => {
+    const unlisted = scan.wildcardBound.filter(
+      (site) => !WILDCARD_BIND_ALLOWLIST.includes(site.path)
+    )
+    expect(
+      formatSites(unlisted),
+      "New WebSocketServer that binds a port without a host. Pass host: '127.0.0.1' so a foreign " +
+        'loopback listener cannot claim the port and answer in its place.'
+    ).toEqual([])
+  })
+
+  it('has no stale allowlist entry', () => {
+    // Why this direction matters too: an entry left behind after the file was
+    // fixed hides the next regression in that same path.
+    const stale = WILDCARD_BIND_ALLOWLIST.filter((path) => !offenders.includes(path))
+    expect(stale, 'Allowlist entry no longer binds the wildcard — delete the line.').toEqual([])
+  })
+
+  it('holds the wildcard-bind count at the pin', () => {
+    // Bounding by the allowlist's own length would prove nothing: the two move
+    // together, so appending a line to silence a failure would keep the bound
+    // satisfied. The pin is a literal so that widening takes a second edit.
+    expect(
+      scan.wildcardBound.length,
+      `${scan.wildcardBound.length} constructions bind the wildcard; the pin is ` +
+        `${WILDCARD_BIND_PIN}. Never raise the pin -- pass host: '127.0.0.1' instead.`
+    ).toBeLessThanOrEqual(WILDCARD_BIND_PIN)
+    // A pin left above reality is how a ratchet rots: it re-opens room for the
+    // next wildcard bind to land for free.
+    expect(
+      scan.wildcardBound.length,
+      `Only ${scan.wildcardBound.length} constructions bind the wildcard. Lower ` +
+        `WILDCARD_BIND_PIN to ${scan.wildcardBound.length} to keep the ground you just took.`
+    ).toBeGreaterThanOrEqual(WILDCARD_BIND_PIN)
+  })
+})
@@ -59,7 +59,8 @@ function e2eeDecrypt(encrypted: string, sharedKey: Uint8Array): string | null {
 // fail with EADDRINUSE; the full scenario restarts on the captured port
 // because the client keeps reconnecting to its original URL.
 function startServer(port = 0): Promise<WebSocketServer> {
-  const wss = new WebSocketServer({ port })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({ host: '127.0.0.1', port })
  wss.on('connection', (ws: ServerSocket) => {
    let sharedKey: Uint8Array | null = null
    let authenticated = false
@@ -61,7 +61,8 @@ describe('desktop relay E2EE integration', () => {
  })

  it('splices a simulated phone through CloudRelayTransport with real NaCl E2EE v2', async () => {
-    const relay = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const relay = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
    servers.push(relay)
    await new Promise<void>((resolve) => relay.once('listening', resolve))
    const address = relay.address()
@@ -99,7 +99,8 @@ describe('RelayControlClient', () => {
  })

  it('rejects a control handshake that never receives a proof response', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
    servers.push(server)
    await new Promise<void>((resolve) => server.once('listening', resolve))
    const address = server.address()
@@ -129,7 +130,7 @@ describe('RelayControlClient', () => {
  })

  it('settles an opening control immediately when ownership closes', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
    servers.push(server)
    await new Promise<void>((resolve) => server.once('listening', resolve))
    const address = server.address()
@@ -165,7 +166,7 @@ describe('RelayControlClient', () => {
  })

  it('proves the host key and drives control/data commands without URL credentials', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
    servers.push(server)
    await new Promise<void>((resolve) => server.once('listening', resolve))
    const address = server.address()
@@ -28,7 +28,8 @@ describe('CloudRelayTransport', () => {
  })

  it('authenticates one query-free host-data socket and forwards messages verbatim', async () => {
-    const server = new WebSocketServer({ port: 0, perMessageDeflate: false })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const server = new WebSocketServer({ host: '127.0.0.1', port: 0, perMessageDeflate: false })
    servers.push(server)
    await new Promise<void>((resolve) => server.once('listening', resolve))
    const address = server.address()
@@ -658,7 +658,8 @@ describe('WebRuntimeClient', () => {
    vi.stubGlobal('WebSocket', WebSocket)
    const serverKeys = generateKeyPair()
    const frame = new Uint8Array([9, 8, 7])
-    const wss = new WebSocketServer({ port: 0 })
+    // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+    const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
    const sockets = new Set<WebSocket>()
    wss.on('connection', (socket) => {
      sockets.add(socket)
@@ -539,7 +539,12 @@ async function createSubscriptionServer(
  const nextAuth = new Promise<unknown>((resolve) => {
    resolveAuth = resolve
  })
-  const wss = new WebSocketServer({ port: 0, autoPong: options.disableAutoPong !== true })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    autoPong: options.disableAutoPong !== true
+  })
  servers.push(wss)

  wss.on('connection', (ws) => {
@@ -625,7 +630,7 @@ async function createClosingServer(
  reason: string
 ): Promise<{ pairing: PairingOffer }> {
  const serverKeyPair = generateKeyPair()
-  const wss = new WebSocketServer({ port: 0 })
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
  servers.push(wss)
  wss.on('connection', (ws) => {
    ws.close(code, reason)
@@ -649,7 +654,7 @@ async function createClosingServer(

 async function createInvalidHandshakeServer(): Promise<{ pairing: PairingOffer }> {
  const serverKeyPair = generateKeyPair()
-  const wss = new WebSocketServer({ port: 0 })
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
  servers.push(wss)
  wss.on('connection', (ws) => {
    ws.once('message', () => ws.send(JSON.stringify({ type: 'not_orca' })))
@@ -680,7 +685,7 @@ async function createOneShotServer(
  } = {}
 ): Promise<{ pairing: PairingOffer }> {
  const serverKeyPair = generateKeyPair()
-  const wss = new WebSocketServer({ port: 0 })
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
  servers.push(wss)

  wss.on('connection', (ws) => {
@@ -352,7 +352,8 @@ describe('remote runtime outbound admission', () => {

 async function createServer(): Promise<{ pairing: PairingOffer; server: WebSocketServer }> {
  const keyPair = generateKeyPair()
-  const server = new WebSocketServer({ port: 0 })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const server = new WebSocketServer({ host: '127.0.0.1', port: 0 })
  servers.push(server)
  await new Promise<void>((resolve) => server.once('listening', resolve))
  const address = server.address() as AddressInfo
@@ -98,7 +98,8 @@ async function createServer(): Promise<TestServer> {
  const requests: unknown[] = []
  const auths: unknown[] = []
  let connectionCount = 0
-  const wss = new WebSocketServer({ port: 0 })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
  servers.push(wss)

  wss.on('connection', (ws) => {
@@ -60,7 +60,12 @@ export async function createSharedControlTestServer(
  const delayedResponses: (() => void)[] = []
  let connectionCount = 0
  let closedAfterFirstStreamingResponse = false
-  const wss = new WebSocketServer({ port: 0, autoPong: options.disableAutoPong !== true })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    autoPong: options.disableAutoPong !== true
+  })
  servers.push(wss)

  wss.on('connection', (ws) => {
@@ -262,7 +262,8 @@ async function createServer(options: ServerOptions = {}): Promise<{
  const nextRequest = new Promise<unknown>((resolve) => {
    resolveRequest = resolve
  })
-  const wss = new WebSocketServer({ port: 0 })
+  // host must match the 127.0.0.1 clients dial: a wildcard bind lets a foreign loopback listener claim the port and answer here.
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
  servers.push(wss)
  wss.on('connection', (ws) => {
    let sharedKey: Uint8Array | null = null