@browserbridge/bbx 1.7.6 → 1.7.8

package/PRIVACY.md

@@ -0,0 +1,92 @@
+# Browser Bridge (BBX) Privacy Policy
+
+Last updated: 2026-03-27
+
+## Overview
+
+Browser Bridge is a developer tool that lets a user-approved local agent inspect and interact with web pages in an explicitly enabled Chrome window. This policy describes how Browser Bridge handles data.
+
+## What Browser Bridge can access
+
+When you enable Browser Bridge for a Chrome window, Browser Bridge can access page data from tabs in that window as needed to fulfill your requests. Depending on the action you or your connected agent triggers, this can include:
+
+- Page metadata such as URL, title, viewport, and scroll position
+- DOM structure, element attributes, visible text, and layout information
+- Computed styles, matched rules, and accessibility-tree data
+- Console messages and uncaught page errors
+- Network request metadata captured from page `fetch` and `XMLHttpRequest` activity, such as URL, method, status, timing, and size
+- `localStorage` and `sessionStorage` values when explicitly requested
+- Screenshots or cropped image captures when explicitly requested
+- User-triggered interaction data such as clicks, typing, key presses, selection changes, and navigation actions
+
+Browser Bridge is designed for local debugging and automation of the browser state you intentionally expose to it.
+
+## How Browser Bridge uses data
+
+Browser Bridge uses this data only to provide its user-facing purpose: letting you inspect, test, and patch the currently enabled browser window from a connected developer tool or agent.
+
+The extension sends request and response data locally through:
+
+1. The Browser Bridge Chrome extension
+2. The Browser Bridge native messaging host running on your machine
+3. The local agent client or IDE that you intentionally connect
+
+Browser Bridge does not operate a Browser Bridge cloud service and does not send extension data to developer-operated remote servers.
+
+## Sharing and downstream processing
+
+Browser Bridge shares page data only with the local companion components and local client you choose to connect.
+
+Important:
+
+- Browser Bridge itself does not sell your data.
+- Browser Bridge itself does not use your data for advertising.
+- Browser Bridge itself does not transfer page data to Browser Bridge-operated remote infrastructure.
+- Your connected agent or IDE may, depending on its own configuration and provider, forward prompts, tool calls, or tool results to remote services. That downstream handling is controlled by the connected product, not by Browser Bridge.
+
+You should review the privacy and retention practices of any connected agent, IDE, or model provider you use with Browser Bridge.
+
+## Data retention
+
+Browser Bridge keeps data only as long as needed for the current local session and feature behavior.
+
+- Window enablement state is stored in session storage and cleared when disabled or when the browser session ends.
+- Action log entries are stored for the current browser session only.
+- Console and network buffers are bounded in memory and cleared when disabled or when the page state is reset.
+- Patch state and remembered element references are session-scoped and cleared on disable, page replacement, or navigation as needed.
+
+Browser Bridge does not provide Browser Bridge-hosted accounts, sync, or long-term server-side storage.
+
+## User control
+
+You control when Browser Bridge can access browser data.
+
+- Access is off by default.
+- You explicitly enable Browser Bridge for a Chrome window.
+- You can disable it at any time.
+- Restricted Chrome pages are not scriptable through Browser Bridge.
+
+## Remote code and runtime evaluation
+
+Browser Bridge does not load remotely hosted extension code.
+
+Browser Bridge can, when you explicitly invoke features such as page evaluation, execute user-requested expressions in the inspected page context through Chrome's documented Debugger API. That execution affects only the currently enabled browser window and is part of Browser Bridge's developer-tool functionality.
+
+## Security
+
+- Extension code is packaged with the extension; Browser Bridge does not fetch and execute remote extension scripts.
+- Communication with the companion host uses Chrome Native Messaging.
+- Access is limited to the explicitly enabled browser window.
+- The extension includes bounded buffers and session-scoped rollback for temporary page patches.
+
+## Chrome Web Store Limited Use statement
+
+The use of information received from Google APIs will adhere to the Chrome Web Store User Data Policy, including the Limited Use requirements.
+
+## Changes
+
+If Browser Bridge's data practices change, this policy will be updated before those changes are released.
+
+## Contact
+
+- GitHub Issues: https://github.com/koltyakov/browser-bridge/issues

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
 
@@ -143,6 +143,10 @@ Browser Bridge itself routes extension data locally through the Chrome extension
 
 Your connected agent or IDE may still forward tool calls or tool results to remote services under that product's own settings and privacy policy. See [PRIVACY.md](https://github.com/koltyakov/browser-bridge/blob/main/PRIVACY.md) for the Browser Bridge policy.
 
+## Responsible Use
+
+Browser Bridge is intended for local development, debugging, and testing of web resources you own, control, or are explicitly authorized to test. Do not use it for web scraping, unauthorized data collection, or impersonating or acting as another user. You are responsible for the agents you connect, the actions they perform, and compliance with applicable laws, permissions, website terms, and third-party rights. See the [Responsible Use Agreement](https://github.com/koltyakov/browser-bridge/blob/main/RESPONSIBLE_USE.md).
+
 ## License
 
 MIT. See [LICENSE](https://github.com/koltyakov/browser-bridge/blob/main/LICENSE).

package/RESPONSIBLE_USE.md

@@ -0,0 +1,16 @@
+# Browser Bridge (BBX) Responsible Use Agreement
+
+Last updated: 2026-07-22
+
+Browser Bridge is intended for local development, debugging, and testing of websites, applications, and other web resources that you own, control, or have explicit permission to test.
+
+By using Browser Bridge, you agree that you will not use it to:
+
+- Scrape websites or perform bulk, automated, or unauthorized data collection.
+- Impersonate another user or act through another person's identity, credentials, account, or authenticated session without their explicit authorization.
+- Access systems or data without authorization, bypass access controls, violate privacy, or perform deceptive, fraudulent, abusive, or harmful actions.
+- Violate applicable laws, regulations, contractual obligations, website terms, or third-party rights.
+
+You are responsible for the browser windows you enable, the agents and services you connect, the instructions and actions they perform, the data they access or transmit, and any resulting impact. You must obtain all necessary permissions and consent and review the privacy and security practices of connected agents, IDEs, and model providers.
+
+Use Browser Bridge fairly, lawfully, and only within an authorized scope. This agreement does not modify the project's [MIT License](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,52 @@
+# Security Policy
+
+Browser Bridge gives coding agents structured access to a real browser profile. The daemon,
+native messaging host, Chrome extension, CLI, and MCP server are all part of the trusted
+path between an agent and the user's browser, so security reports are taken seriously.
+
+## Supported Versions
+
+Only the latest version published to npm (`@browserbridge/bbx`) and the Chrome Web Store
+receives security fixes. Older versions are not patched retroactively; upgrade to the
+latest release before reporting.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Report privately via GitHub's security advisory form:
+<https://github.com/koltyakov/browser-bridge/security/advisories/new>
+
+Include the affected component (daemon, native host, extension, CLI, MCP server), a
+reproduction, and the impact you believe it has. Reports are acknowledged as quickly as
+possible; fixes for confirmed vulnerabilities are prioritized over regular development.
+
+## Scope
+
+In scope:
+
+- The bridge daemon: transport auth (socket permissions, TCP auth token), request routing,
+  and the opt-in proxy/remote mode.
+- The native messaging host and its manifest installation.
+- The Chrome extension (MV3 service worker, content scripts, CDP usage).
+- The `bbx` CLI and MCP server, including config/skill installation paths.
+
+Out of scope:
+
+- Vulnerabilities in Chrome, Node.js, or other dependencies (report upstream).
+- Issues requiring an already-compromised machine or browser profile.
+- The inherent capability of the tool itself: an agent authorized to use Browser Bridge
+  can, by design, read and manipulate pages in the connected browser profile. See
+  [PRIVACY.md](https://github.com/koltyakov/browser-bridge/blob/main/PRIVACY.md) and
+  [docs/agent-permissions.md](https://github.com/koltyakov/browser-bridge/blob/main/docs/agent-permissions.md)
+  for the intended trust model.
+
+## Design Notes
+
+- By default the daemon listens on a user-owned Unix socket (mode `0700` directory) or,
+  on Windows, a named pipe / localhost TCP.
+- Any TCP listener requires a random 256-bit auth token stored with mode `0600`;
+  registration without it is rejected and the comparison is constant-time.
+- Proxy mode (LAN exposure) is opt-in via `bbx proxy enable` and always provisions a
+  token; an invalid `bindHost` in the config rejects the config rather than widening
+  the bind address.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -33,7 +33,10 @@
   },
   "files": [
     "LICENSE",
+    "PRIVACY.md",
+    "RESPONSIBLE_USE.md",
     "README.md",
+    "SECURITY.md",
     "packages/agent-client/src",
     "packages/mcp-server/src",
     "packages/native-host/bin",

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',