@browserbridge/bbx 1.7.6 → 1.7.7

package/README.md

@@ -114,7 +114,7 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
 
-MCP mode is self-contained: the server exposes tools, startup instructions, and prompt templates, so a separate CLI skill is not required for MCP guidance.
+MCP mode is self-contained: the server exposes tools and startup instructions, so a separate CLI skill is not required for MCP guidance.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.6",
+  "version": "1.7.7",
   "private": false,
   "keywords": [
     "agent-tools",

package/packages/mcp-server/src/guidance.js

@@ -1,10 +1,5 @@
 // @ts-check
 
-import * as z from 'zod/v4';
-
-/** @typedef {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} McpServer */
-/** @typedef {import('@modelcontextprotocol/sdk/types.js').GetPromptResult} GetPromptResult */
-
 export const MCP_SERVER_INSTRUCTIONS = [
   "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through typed MCP tools.",
   'In permission-ask hosts, use browser_call as the default Browser Bridge MCP tool so the user can approve one BBX tool instead of separate browser_status, browser_page, browser_dom, browser_input, and other tools.',
@@ -15,231 +10,8 @@ export const MCP_SERVER_INSTRUCTIONS = [
   'Escalate to screenshot.capture_element, screenshot.capture_region, dom.get_accessibility_tree, page.evaluate, viewport.resize, or CDP only when structured reads cannot answer the question.',
   'Use patch.apply_styles or patch.apply_dom for temporary experiments, and rollback patches before finishing unless the user asks to keep them.',
   'Only use the specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
+  '',
+  'Page investigation: read page state, scoped DOM, and relevant page text first, batching independent reads. Find targets by text or role when selectors are unknown. Add styles, console, or network reads only when they directly answer the objective, and use screenshots or evaluation only when structured evidence is insufficient.',
+  'Layout debugging: locate the target, read only relevant computed properties and its box model, and inspect matched rules only when the cascade is unclear. Prototype the smallest fix with a reversible style patch, verify the result, check for new console errors, then rollback before editing source unless the user asks to keep the patch.',
+  'Flow verification: read initial page state, locate controls semantically, reuse elementRef values, interact through input tools, and wait for navigation or UI state changes. Verify the final DOM or page text plus console and network state when relevant. Do not create a new tab unless requested or required by the flow.',
 ].join('\n');
-
-export const MCP_GUIDANCE_PROMPT_NAMES = Object.freeze([
-  'browser_bridge_guide',
-  'browser_bridge_investigate',
-  'browser_bridge_debug_layout',
-  'browser_bridge_verify_flow',
-]);
-
-/**
- * Register Browser Bridge MCP prompt templates. These are the MCP-mode equivalent
- * of a lightweight skill: discoverable by clients without requiring filesystem
- * skill installation or shell access.
- *
- * @param {McpServer} server
- * @returns {void}
- */
-export function registerBridgeMcpGuidance(server) {
-  server.registerPrompt(
-    'browser_bridge_guide',
-    {
-      title: 'Use Browser Bridge MCP',
-      description:
-        'General Browser Bridge MCP workflow guidance. Prefer this over CLI skill setup.',
-    },
-    createGuidePrompt
-  );
-
-  server.registerPrompt(
-    'browser_bridge_investigate',
-    {
-      title: 'Investigate Current Page',
-      description:
-        'Inspect the current page with structured reads before screenshots or evaluation.',
-      argsSchema: {
-        objective: z.string().optional().describe('What to find, verify, or explain'),
-        selector: z
-          .string()
-          .optional()
-          .describe('Optional CSS selector to scope the first DOM read'),
-        scope: z.enum(['quick', 'normal', 'deep']).optional().describe('Investigation depth'),
-      },
-    },
-    createInvestigatePrompt
-  );
-
-  server.registerPrompt(
-    'browser_bridge_debug_layout',
-    {
-      title: 'Debug Layout Or Styling',
-      description: 'Diagnose a visual, spacing, sizing, visibility, or CSS issue in the live tab.',
-      argsSchema: {
-        target: z.string().optional().describe('Element, component, text, or selector to inspect'),
-        symptom: z.string().optional().describe('Observed layout or styling problem'),
-      },
-    },
-    createDebugLayoutPrompt
-  );
-
-  server.registerPrompt(
-    'browser_bridge_verify_flow',
-    {
-      title: 'Verify User Flow',
-      description:
-        'Drive a user flow through MCP input tools and verify page, console, and network state.',
-      argsSchema: {
-        flow: z.string().optional().describe('User flow to exercise'),
-        successCriteria: z.string().optional().describe('Expected successful outcome'),
-      },
-    },
-    createVerifyFlowPrompt
-  );
-}
-
-/**
- * @returns {GetPromptResult}
- */
-function createGuidePrompt() {
-  return createUserPrompt(
-    'Browser Bridge MCP workflow guide.',
-    [
-      'Use Browser Bridge MCP for this browser task.',
-      '',
-      'Rules:',
-      '1. Prefer MCP over `bbx`; do not shell out unless setup, doctor, logs, or raw CLI debugging is explicitly needed.',
-      '2. In permission-ask hosts, use `browser_call` as the default tool so the user can approve one BBX MCP tool instead of separate tools for status, page, DOM, input, and patches.',
-      '3. Start with `browser_call` method `health.ping`. If access is disabled, call `browser_call` method `access.request` once, ask the user to click Enable, then retry once.',
-      '4. Start with structured reads via `browser_call`: `page.get_state`, `dom.query`, `dom.find_by_text`, `dom.find_by_role`, and `styles.get_computed`. Use `browser_batch` for parallel reads.',
-      '5. `browser_call` accepts `budgetPreset`; explicit method limits override preset values. Keep limits tight and widen only when results are truncated.',
-      '6. Reuse `elementRef` values returned by DOM tools instead of rescanning.',
-      '7. Escalate to screenshots, accessibility tree, `page.evaluate`, viewport resize, or CDP only when structured reads cannot answer.',
-      '8. Use `patch.apply_styles` or `patch.apply_dom` for temporary experiments and rollback before finishing unless the user asks to keep patches.',
-      '9. Only use specialized Browser Bridge MCP tools directly when the host has already allowed them or the user explicitly wants typed tool calls.',
-      '',
-      'Return concise findings with evidence. Edit source code only after the live page behavior is understood.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {{ objective?: string, selector?: string, scope?: 'quick' | 'normal' | 'deep' }} args
- * @returns {GetPromptResult}
- */
-function createInvestigatePrompt(args) {
-  const objective = normalizeTextArg(
-    args.objective,
-    'inspect the current page and report findings'
-  );
-  const selector = normalizeTextArg(
-    args.selector,
-    'none; start with main, body, or semantic search'
-  );
-  const scope = normalizeTextArg(args.scope, 'normal');
-
-  return createUserPrompt(
-    'Browser Bridge MCP page investigation workflow.',
-    [
-      'Investigate the current page with Browser Bridge MCP.',
-      '',
-      `Objective: ${objective}`,
-      `Scope: ${scope}`,
-      `Initial selector: ${selector}`,
-      '',
-      'Workflow:',
-      '1. Call `browser_status` to confirm daemon, extension, and access readiness.',
-      '2. If access is disabled, call `browser_access` once, ask the user to click Enable, then retry once.',
-      '3. Use `browser_batch` for independent structured reads, usually `page.get_state`, a scoped `dom.query`, and `page.get_text` when page copy matters.',
-      '4. Use `browser_dom` `find_text` or `find_role` when the target is known by label but not selector.',
-      '5. Add `browser_styles_layout`, `browser_page` console, or `browser_page` network only when they directly answer the objective.',
-      '6. Escalate to screenshots, accessibility tree, or evaluate only when structured reads are insufficient.',
-      '',
-      'Return concise findings, relevant evidence, and the next source-code action if a fix is needed.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {{ target?: string, symptom?: string }} args
- * @returns {GetPromptResult}
- */
-function createDebugLayoutPrompt(args) {
-  const target = normalizeTextArg(args.target, 'the affected element or component');
-  const symptom = normalizeTextArg(args.symptom, 'the observed layout or styling problem');
-
-  return createUserPrompt(
-    'Browser Bridge MCP layout debugging workflow.',
-    [
-      'Debug a layout or styling issue in the live tab with Browser Bridge MCP.',
-      '',
-      `Target: ${target}`,
-      `Symptom: ${symptom}`,
-      '',
-      'Workflow:',
-      '1. Call `browser_status` first and resolve access if needed.',
-      '2. Locate the target with `browser_dom` `query`, `find_text`, or `find_role` using a quick budget.',
-      '3. Read only relevant computed styles with `browser_styles_layout` action `computed` and specific `properties`.',
-      '4. Read dimensions with `browser_styles_layout` action `box_model`; use matched rules only when the cascade is unclear.',
-      '5. Prototype the smallest visual fix with `browser_patch` action `apply_styles` and `verify: true` when useful.',
-      '6. Check `browser_page` console for new errors after interaction or patching.',
-      '7. Roll back temporary patches unless the user explicitly wants them kept, then edit source with the confirmed fix.',
-      '',
-      'Avoid screenshots until DOM, computed styles, and box model evidence are insufficient.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {{ flow?: string, successCriteria?: string }} args
- * @returns {GetPromptResult}
- */
-function createVerifyFlowPrompt(args) {
-  const flow = normalizeTextArg(args.flow, 'the requested user flow');
-  const successCriteria = normalizeTextArg(
-    args.successCriteria,
-    'visible success state, no console errors, and expected network behavior'
-  );
-
-  return createUserPrompt(
-    'Browser Bridge MCP user-flow verification workflow.',
-    [
-      'Verify a user flow in the current real browser tab with Browser Bridge MCP.',
-      '',
-      `Flow: ${flow}`,
-      `Success criteria: ${successCriteria}`,
-      '',
-      'Workflow:',
-      '1. Call `browser_status` and resolve access if needed.',
-      '2. Read `browser_page` state so you know the current URL and title before interacting.',
-      '3. Locate controls semantically with `browser_dom` `find_role` or `find_text`; reuse returned `elementRef` values.',
-      '4. Interact with `browser_input` actions such as `click`, `type`, `set_checked`, `select_option`, and `press_key`.',
-      '5. After navigation or UI changes, wait with `browser_dom` action `wait` or `browser_page` action `wait_for_load`.',
-      '6. Verify final page text/DOM plus `browser_page` console and network if the flow depends on API calls.',
-      '7. Do not create new tabs unless the user requested a fresh page or the flow requires one.',
-      '',
-      'Report the verified result, evidence, and any blocking failures.',
-    ].join('\n')
-  );
-}
-
-/**
- * @param {string} description
- * @param {string} text
- * @returns {GetPromptResult}
- */
-function createUserPrompt(description, text) {
-  return {
-    description,
-    messages: [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text,
-        },
-      },
-    ],
-  };
-}
-
-/**
- * @param {string | undefined} value
- * @param {string} fallback
- * @returns {string}
- */
-function normalizeTextArg(value, fallback) {
-  const text = typeof value === 'string' ? value.trim() : '';
-  return text || fallback;
-}

package/packages/mcp-server/src/server.js

@@ -44,7 +44,7 @@ import {
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
-import { MCP_SERVER_INSTRUCTIONS, registerBridgeMcpGuidance } from './guidance.js';
+import { MCP_SERVER_INSTRUCTIONS } from './guidance.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -109,8 +109,6 @@ export function createBridgeMcpServer() {
     }
   );
 
-  registerBridgeMcpGuidance(server);
-
   server.registerTool(
     'browser_status',
     {

package/packages/native-host/bin/bridge-daemon.js

@@ -44,7 +44,8 @@ try {
   await writeDaemonPidFile(process.pid);
 } catch (error) {
   // A stale root-owned pid file (e.g. after a sudo install) must not take down
-  // a daemon that is already listening; `bbx` falls back to lsof for the pid.
+  // a daemon that is already listening; `bbx` falls back to endpoint-owner
+  // discovery (lsof/ss on the socket, verified TCP listener lookup) for the pid.
   process.stderr.write(
     `Could not write daemon pid file: ${error instanceof Error ? error.message : String(error)}\n`
   );

package/packages/native-host/src/auth-token.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -34,6 +34,27 @@ export function normalizeBridgeAuthToken(value) {
   return TOKEN_PATTERN.test(token) || UUID_TOKEN_PATTERN.test(token) ? token : null;
 }
 
+/**
+ * Compare a candidate auth token against the expected token in constant time.
+ * Both sides are hashed before comparison so neither token length nor a
+ * matching prefix is observable through timing, which matters when the daemon
+ * listens on TCP (proxy mode exposes it beyond localhost).
+ *
+ * @param {unknown} candidate
+ * @param {string | null | undefined} expected
+ * @returns {boolean}
+ */
+export function bridgeAuthTokensEqual(candidate, expected) {
+  const normalizedCandidate = normalizeBridgeAuthToken(candidate);
+  if (!normalizedCandidate || typeof expected !== 'string' || !expected) {
+    return false;
+  }
+  return timingSafeEqual(
+    createHash('sha256').update(normalizedCandidate).digest(),
+    createHash('sha256').update(expected).digest()
+  );
+}
+
 /**
  * @param {{ env?: NodeJS.ProcessEnv, readFile?: typeof fs.promises.readFile }} [options={}]
  * @returns {Promise<string | null>}

package/packages/native-host/src/config.js

@@ -120,30 +120,65 @@ function normalizePort(value) {
 }
 
 /**
+ * @param {string} configPath
+ * @param {string} reason
+ * @returns {void}
+ */
+function warnProxyConfigIgnored(configPath, reason) {
+  console.error(`browser-bridge: ignoring proxy config at ${configPath}: ${reason}`);
+}
+
+/**
+ * Read the opt-in TCP proxy config. A missing file and `enabled: false` are
+ * the normal quiet cases; anything else that prevents using the config gets a
+ * stderr warning so a corrupt file does not silently fall back to the socket
+ * transport. An invalid `bindHost` rejects the whole config rather than
+ * defaulting to `0.0.0.0`, so a typo in a value meant to restrict binding
+ * cannot widen exposure to all interfaces.
+ *
  * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {BridgeProxyConfig | null}
  */
 export function readProxyConfig(env = process.env) {
+  const configPath = getProxyConfigPath(env);
+  /** @type {unknown} */
+  let parsed;
   try {
-    const parsed = JSON.parse(fs.readFileSync(getProxyConfigPath(env), 'utf8'));
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      return null;
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    if (/** @type {{ code?: unknown }} */ (error)?.code !== 'ENOENT') {
+      warnProxyConfigIgnored(configPath, error instanceof Error ? error.message : String(error));
     }
-    const record = /** @type {Record<string, unknown>} */ (parsed);
-    const port = normalizePort(record.port);
-    const bindHost = normalizeHost(record.bindHost) ?? '0.0.0.0';
-    if (record.enabled !== true || port === null) {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    warnProxyConfigIgnored(configPath, 'expected a JSON object');
+    return null;
+  }
+  const record = /** @type {Record<string, unknown>} */ (parsed);
+  if (record.enabled !== true) {
+    return null;
+  }
+  const port = normalizePort(record.port);
+  if (port === null) {
+    warnProxyConfigIgnored(configPath, 'invalid "port" value');
+    return null;
+  }
+  let bindHost = '0.0.0.0';
+  if (record.bindHost != null) {
+    const normalized = normalizeHost(record.bindHost);
+    if (!normalized) {
+      warnProxyConfigIgnored(configPath, 'invalid "bindHost" value');
       return null;
     }
-    return {
-      enabled: true,
-      port,
-      bindHost,
-      ...(typeof record.token === 'string' ? { token: record.token } : {}),
-    };
-  } catch {
-    return null;
+    bindHost = normalized;
   }
+  return {
+    enabled: true,
+    port,
+    bindHost,
+    ...(typeof record.token === 'string' ? { token: record.token } : {}),
+  };
 }
 
 /**

package/packages/native-host/src/daemon-process.js

@@ -260,8 +260,9 @@ export async function stopBridgeDaemon(options = {}) {
     previousPid = endpointOwnerPid;
     previouslyRunning = true;
   } else if (reachable) {
-    // TCP endpoints do not expose an owner pid. In that case daemon
-    // reachability is the evidence supporting the recorded pid.
+    // When the endpoint owner is not discoverable (no verified TCP listener,
+    // lsof and ss both unavailable), daemon reachability is the evidence
+    // supporting the recorded pid.
     previousPid = pidFromFile;
     previouslyRunning = true;
   }
@@ -442,28 +443,40 @@ function resolveDaemonTransport(options) {
   return getBridgeTransport(env);
 }
 
+/**
+ * @typedef {{
+ *   execFileFn?: typeof execFileAsync,
+ *   platform?: NodeJS.Platform,
+ *   readFileFn?: typeof fs.promises.readFile,
+ * }} FindDaemonPidOptions
+ */
+
 /**
  * @param {BridgeTransport} transport
+ * @param {FindDaemonPidOptions} [options={}]
  * @returns {Promise<number | null>}
  */
-export async function findDaemonPidByTransport(transport) {
-  if (transport.type !== 'socket') {
-    return null;
+export async function findDaemonPidByTransport(transport, options = {}) {
+  if (transport.type === 'socket') {
+    return findDaemonPidBySocket(transport.socketPath, options);
   }
-  return findDaemonPidBySocket(transport.socketPath);
+  return findDaemonPidByTcpPort(transport.port, options);
 }
 
 /**
  * @param {string} socketPath
+ * @param {FindDaemonPidOptions} [options={}]
  * @returns {Promise<number | null>}
  */
-export async function findDaemonPidBySocket(socketPath) {
-  if (process.platform === 'win32') {
+export async function findDaemonPidBySocket(socketPath, options = {}) {
+  const { execFileFn = execFileAsync, platform = process.platform } = options;
+  if (platform === 'win32') {
+    // Named pipes do not expose an owner pid through a filesystem path.
     return null;
   }
 
   try {
-    const { stdout } = await execFileAsync('lsof', ['-t', '--', socketPath]);
+    const { stdout } = await execFileFn('lsof', ['-t', '--', socketPath]);
     const pid = Number.parseInt(
       stdout
         .split(/\r?\n/u)
@@ -473,13 +486,208 @@ export async function findDaemonPidBySocket(socketPath) {
     );
     return Number.isInteger(pid) && pid > 0 ? pid : null;
   } catch (error) {
-    if (isCommandNotFoundError(error) || isLsofNoResultsError(error)) {
+    if (isCommandNotFoundError(error)) {
+      // macOS always ships lsof; minimal Linux installs often do not, so fall
+      // back to iproute2's ss which is effectively universal there.
+      return platform === 'linux' ? findLinuxSocketOwnerPidWithSs(socketPath, execFileFn) : null;
+    }
+    if (isLsofNoResultsError(error)) {
       return null;
     }
     throw error;
   }
 }
 
+/**
+ * @param {string} socketPath
+ * @param {typeof execFileAsync} execFileFn
+ * @returns {Promise<number | null>}
+ */
+async function findLinuxSocketOwnerPidWithSs(socketPath, execFileFn) {
+  try {
+    const { stdout } = await execFileFn('ss', ['-x', '-l', '-p', 'src', socketPath]);
+    for (const line of stdout.split(/\r?\n/u)) {
+      if (!line.includes(socketPath)) {
+        continue;
+      }
+      const match = /pid=(\d+)/u.exec(line);
+      const pid = match ? Number.parseInt(match[1], 10) : Number.NaN;
+      if (Number.isInteger(pid) && pid > 0) {
+        return pid;
+      }
+    }
+    return null;
+  } catch {
+    // ss is a best-effort fallback; the caller degrades to the pid file.
+    return null;
+  }
+}
+
+/**
+ * Find the pid of the bridge daemon listening on a local TCP port (the default
+ * transport on Windows and the opt-in proxy transport elsewhere). Unlike a
+ * bridge-owned socket path, a TCP port could be held by an unrelated process,
+ * so a candidate pid is only returned after its command line is confirmed to
+ * reference the bridge daemon entrypoint. Discovery is opportunistic: any
+ * tooling failure yields null and the caller degrades to the pid file.
+ *
+ * @param {number} port
+ * @param {FindDaemonPidOptions} [options={}]
+ * @returns {Promise<number | null>}
+ */
+export async function findDaemonPidByTcpPort(port, options = {}) {
+  const {
+    execFileFn = execFileAsync,
+    platform = process.platform,
+    readFileFn = fs.promises.readFile,
+  } = options;
+
+  if (platform === 'win32') {
+    return findWindowsTcpDaemonPid(port, execFileFn);
+  }
+
+  const candidatePids = await findPosixTcpListenerPids(port, execFileFn, platform);
+  for (const pid of candidatePids) {
+    const command = await getPosixProcessCommand(pid, execFileFn, platform, readFileFn);
+    if (command.includes(DAEMON_ENTRY_BASENAME)) {
+      return pid;
+    }
+  }
+  return null;
+}
+
+const DAEMON_ENTRY_BASENAME = 'bridge-daemon';
+
+/**
+ * @returns {string}
+ */
+function getWindowsPowerShellExe() {
+  const systemRoot = process.env.SystemRoot || process.env.WINDIR;
+  return systemRoot
+    ? path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+    : 'powershell.exe';
+}
+
+/**
+ * Resolve and verify the listening daemon pid in a single PowerShell call.
+ * Get-NetTCPConnection is locale-independent, unlike netstat's state column.
+ * `$listenerPid` deliberately avoids PowerShell's reserved `$PID` variable.
+ *
+ * @param {number} port
+ * @param {typeof execFileAsync} execFileFn
+ * @returns {Promise<number | null>}
+ */
+async function findWindowsTcpDaemonPid(port, execFileFn) {
+  const script = [
+    `$listenerPids = @(Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue | ForEach-Object { $_.OwningProcess } | Sort-Object -Unique)`,
+    'foreach ($listenerPid in $listenerPids) {',
+    `  $commandLine = (Get-CimInstance Win32_Process -Filter "ProcessId=$listenerPid" -ErrorAction SilentlyContinue).CommandLine`,
+    `  if ($commandLine -like '*${DAEMON_ENTRY_BASENAME}*') { Write-Output $listenerPid; break }`,
+    '}',
+  ].join(' ');
+
+  try {
+    const { stdout } = await execFileFn(getWindowsPowerShellExe(), [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      script,
+    ]);
+    const pid = Number.parseInt(
+      stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .find(Boolean) ?? '',
+      10
+    );
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {number} port
+ * @param {typeof execFileAsync} execFileFn
+ * @param {NodeJS.Platform} platform
+ * @returns {Promise<number[]>}
+ */
+async function findPosixTcpListenerPids(port, execFileFn, platform) {
+  try {
+    const { stdout } = await execFileFn('lsof', ['-nP', '-t', `-iTCP:${port}`, '-sTCP:LISTEN']);
+    return parsePidLines(stdout);
+  } catch (error) {
+    if (isCommandNotFoundError(error) && platform === 'linux') {
+      return findLinuxTcpListenerPidsWithSs(port, execFileFn);
+    }
+    return [];
+  }
+}
+
+/**
+ * @param {number} port
+ * @param {typeof execFileAsync} execFileFn
+ * @returns {Promise<number[]>}
+ */
+async function findLinuxTcpListenerPidsWithSs(port, execFileFn) {
+  try {
+    const { stdout } = await execFileFn('ss', ['-t', '-l', '-n', '-p', 'sport', '=', `:${port}`]);
+    /** @type {number[]} */
+    const pids = [];
+    for (const match of stdout.matchAll(/pid=(\d+)/gu)) {
+      const pid = Number.parseInt(match[1], 10);
+      if (Number.isInteger(pid) && pid > 0 && !pids.includes(pid)) {
+        pids.push(pid);
+      }
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {number} pid
+ * @param {typeof execFileAsync} execFileFn
+ * @param {NodeJS.Platform} platform
+ * @param {typeof fs.promises.readFile} readFileFn
+ * @returns {Promise<string>}
+ */
+async function getPosixProcessCommand(pid, execFileFn, platform, readFileFn) {
+  if (platform === 'linux') {
+    // /proc avoids depending on a full procps ps (busybox lacks -ww/command=).
+    try {
+      const cmdline = await readFileFn(`/proc/${pid}/cmdline`, 'utf8');
+      return String(cmdline).replaceAll('\0', ' ');
+    } catch {
+      return '';
+    }
+  }
+  try {
+    const { stdout } = await execFileFn('ps', ['-ww', '-p', String(pid), '-o', 'command=']);
+    return stdout;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {string} stdout
+ * @returns {number[]}
+ */
+function parsePidLines(stdout) {
+  /** @type {number[]} */
+  const pids = [];
+  for (const line of stdout.split(/\r?\n/u)) {
+    const pid = Number.parseInt(line.trim(), 10);
+    if (Number.isInteger(pid) && pid > 0 && !pids.includes(pid)) {
+      pids.push(pid);
+    }
+  }
+  return pids;
+}
+
 /**
  * @param {{
  *   transport: BridgeTransport,

package/packages/native-host/src/daemon.js

@@ -39,11 +39,7 @@ import {
   getBridgeTransport,
   getSocketPath,
 } from './config.js';
-import {
-  ensureBridgeAuthToken,
-  normalizeBridgeAuthToken,
-  readBridgeAuthToken,
-} from './auth-token.js';
+import { bridgeAuthTokensEqual, ensureBridgeAuthToken, readBridgeAuthToken } from './auth-token.js';
 import { normalizeDaemonLogger } from './daemon-logger.js';
 import { writeJsonLine } from './framing.js';
 
@@ -341,7 +337,7 @@ export class BridgeDaemon {
       return;
     }
 
-    if (this.isAuthRequired() && normalizeBridgeAuthToken(message.authToken) !== this.authToken) {
+    if (this.isAuthRequired() && !bridgeAuthTokensEqual(message.authToken, this.authToken)) {
       this.logger.error('socket registration rejected', { role: message.role ?? null });
       void writeJsonLine(socket, {
         type: 'registration_failed',