@browserbridge/bbx 1.0.1 → 1.1.0

package/packages/native-host/src/install-manifest.js

@@ -1,10 +1,14 @@
 // @ts-check
 
+import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { promisify } from 'node:util';
 
 import {
   APP_NAME,
+  BRIDGE_TCP_PORT_ENV,
+  DEFAULT_WINDOWS_TCP_PORT,
   getBridgeDir,
   getLauncherFilename,
   getManifestInstallDir,
@@ -13,9 +17,41 @@ import {
 
 export const DEFAULT_EXTENSION_ID_ENV = 'BROWSER_BRIDGE_EXTENSION_ID';
 export const BUILT_IN_EXTENSION_ID_SOURCE = 'built_in';
+export const INSTALL_NATIVE_MANIFEST_ERROR = 'INSTALL_NATIVE_MANIFEST_FAILED';
 
 /** @typedef {import('./config.js').SupportedBrowser} SupportedBrowser */
 /** @typedef {'env' | 'built_in' | 'none' | 'invalid_env'} ExtensionIdSource */
+/** @typedef {NodeJS.ErrnoException & { cause?: unknown }} MaybeErrnoError */
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @returns {string}
+ */
+function getWindowsRegistryExe() {
+  if (process.platform !== 'win32') {
+    return 'reg.exe';
+  }
+
+  const systemRoot = process.env.SystemRoot || process.env.WINDIR;
+  return systemRoot ? path.join(systemRoot, 'System32', 'reg.exe') : 'reg.exe';
+}
+
+export class NativeManifestInstallError extends Error {
+  /**
+   * @param {string} targetPath
+   * @param {unknown} cause
+   */
+  constructor(targetPath, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to install native host files at ${targetPath}: ${detail}`, { cause });
+    this.name = 'NativeManifestInstallError';
+    this.code = INSTALL_NATIVE_MANIFEST_ERROR;
+    this.targetPath = targetPath;
+    this.cause = cause;
+    this.errnoCode = /** @type {MaybeErrnoError | undefined} */ (cause)?.code;
+  }
+}
 
 /**
  * @typedef {{
@@ -28,6 +64,7 @@ export const BUILT_IN_EXTENSION_ID_SOURCE = 'built_in';
  *   stdout?: Pick<NodeJS.WriteStream, 'write'>,
  *   stderr?: Pick<NodeJS.WriteStream, 'write'>,
  *   preserveCustomExtensionId?: boolean | undefined,
+ *   writeRegistryValue?: ((keyPath: string, value: string) => Promise<void> | void) | undefined,
  *   env?: NodeJS.ProcessEnv
  * }} InstallManifestOptions
  */
@@ -38,10 +75,64 @@ export const BUILT_IN_EXTENSION_ID_SOURCE = 'built_in';
  *   installDir?: string | undefined,
  *   bridgeDir?: string | undefined,
  *   removeBridgeDir?: boolean | undefined,
+ *   deleteRegistryKey?: ((keyPath: string) => Promise<boolean> | boolean) | undefined,
  *   stdout?: Pick<NodeJS.WriteStream, 'write'>
  * }} UninstallManifestOptions
  */
 
+/**
+ * @param {SupportedBrowser} [browser='chrome']
+ * @returns {string}
+ */
+export function getWindowsRegistryKey(browser = 'chrome') {
+  const roots = {
+    chrome: 'HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts',
+    edge: 'HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts',
+    brave: 'HKCU\\Software\\BraveSoftware\\Brave-Browser\\NativeMessagingHosts',
+    chromium: 'HKCU\\Software\\Chromium\\NativeMessagingHosts',
+    // Arc is Chromium-based, and no verified Browser Company-specific native
+    // messaging registry path is documented in this repo yet.
+    arc: 'HKCU\\Software\\Chromium\\NativeMessagingHosts',
+  };
+
+  return `${roots[browser] || roots.chrome}\\${APP_NAME}`;
+}
+
+/**
+ * @param {string} keyPath
+ * @param {string} value
+ * @returns {Promise<void>}
+ */
+async function writeRegistryValue(keyPath, value) {
+  await execFileAsync(getWindowsRegistryExe(), [
+    'add',
+    keyPath,
+    '/ve',
+    '/t',
+    'REG_SZ',
+    '/d',
+    value,
+    '/f',
+  ]);
+}
+
+/**
+ * @param {string} keyPath
+ * @returns {Promise<boolean>}
+ */
+async function deleteRegistryKey(keyPath) {
+  try {
+    await execFileAsync(getWindowsRegistryExe(), ['delete', keyPath, '/f']);
+    return true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/unable to find|cannot find|was unable to find/i.test(message)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
 /**
  * Parse and validate a Chrome extension ID from a CLI argument.
  * Accepts a raw 32-char ID or a full `chrome-extension://<id>/` origin.
@@ -173,6 +264,7 @@ export async function installNativeManifest(options) {
     stdout = process.stdout,
     stderr = process.stderr,
     preserveCustomExtensionId = false,
+    writeRegistryValue: writeRegistryValueFn = writeRegistryValue,
     env = process.env,
   } = options;
 
@@ -196,7 +288,7 @@ export async function installNativeManifest(options) {
 
   const launcher =
     process.platform === 'win32'
-      ? `@echo off\r\n"${nodePath}" "${hostPath}" %*\r\n`
+      ? `@echo off\r\nset ${BRIDGE_TCP_PORT_ENV}=${DEFAULT_WINDOWS_TCP_PORT}\r\n"${nodePath}" "${hostPath}" %*\r\n`
       : `#!/bin/sh
 exec '${escapeSingleQuotes(nodePath)}' '${escapeSingleQuotes(hostPath)}' "$@"
 `;
@@ -228,16 +320,31 @@ exec '${escapeSingleQuotes(nodePath)}' '${escapeSingleQuotes(hostPath)}' "$@"
     allowed_origins: allowedOrigins,
   };
 
-  await fs.promises.mkdir(installDir, { recursive: true });
-  await fs.promises.mkdir(bridgeDir, { recursive: true });
-  await fs.promises.writeFile(launcherPath, launcher, 'utf8');
-  if (process.platform !== 'win32') {
-    await fs.promises.chmod(launcherPath, 0o755);
+  let failingPath = installDir;
+  try {
+    await fs.promises.mkdir(installDir, { recursive: true });
+    failingPath = bridgeDir;
+    await fs.promises.mkdir(bridgeDir, { recursive: true });
+    failingPath = launcherPath;
+    await fs.promises.writeFile(launcherPath, launcher, 'utf8');
+    if (process.platform !== 'win32') {
+      await fs.promises.chmod(launcherPath, 0o755);
+    }
+    failingPath = manifestPath;
+    await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    if (process.platform === 'win32') {
+      failingPath = getWindowsRegistryKey(browser);
+      await writeRegistryValueFn(getWindowsRegistryKey(browser), manifestPath);
+    }
+  } catch (error) {
+    throw new NativeManifestInstallError(failingPath, error);
   }
-  await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
 
   stdout.write(`Wrote ${manifestPath}\n`);
   stdout.write(`Wrote ${launcherPath}\n`);
+  if (process.platform === 'win32') {
+    stdout.write(`Registered ${getWindowsRegistryKey(browser)}\n`);
+  }
 
   if (!preservedCustomExtensionId && !parsedExtensionId && extensionIdArg == null && extensionId) {
     if (defaultExtensionId.source === 'env') {
@@ -281,15 +388,22 @@ export async function uninstallNativeManifest(options = {}) {
     installDir = getManifestInstallDir(browser),
     bridgeDir = getBridgeDir(),
     removeBridgeDir = false,
+    deleteRegistryKey: deleteRegistryKeyFn = deleteRegistryKey,
     stdout = process.stdout,
   } = options;
 
   const manifestPath = path.join(installDir, `${APP_NAME}.json`);
+  const registryKeyPath = process.platform === 'win32' ? getWindowsRegistryKey(browser) : null;
   const removedManifest = await removePathIfExists(manifestPath);
   if (removedManifest) {
     stdout.write(`Removed ${manifestPath}\n`);
   }
 
+  const removedRegistryKey = registryKeyPath ? await deleteRegistryKeyFn(registryKeyPath) : false;
+  if (removedRegistryKey && registryKeyPath) {
+    stdout.write(`Removed ${registryKeyPath}\n`);
+  }
+
   const removedBridgeDir = removeBridgeDir ? await removePathIfExists(bridgeDir) : false;
   if (removedBridgeDir) {
     stdout.write(`Removed ${bridgeDir}\n`);

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

@@ -1,16 +1,13 @@
 // @ts-check
 
-import { spawn } from 'node:child_process';
 import net from 'node:net';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { createFailure, ERROR_CODES } from '../../protocol/src/index.js';
-import { getSocketPath } from './config.js';
+import { createSocketBridgeTransport, getBridgeTransport } from './config.js';
+import { spawnBridgeDaemonProcess } from './daemon-process.js';
 import { createNativeMessageReader, writeJsonLine, writeNativeMessage } from './framing.js';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const daemonEntryPath = path.resolve(__dirname, '../bin/bridge-daemon.js');
+/** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
 
 /**
  * @typedef {{
@@ -112,13 +109,17 @@ function isHostActivity(message) {
 }
 
 /**
- * @param {{ socketPath?: string }} [options={}]
+ * @param {{ transport?: BridgeTransport, socketPath?: string }} [options={}]
  * @returns {Promise<void>}
  */
-export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
+export async function runNativeHost({
+  transport = getBridgeTransport(),
+  socketPath = undefined,
+} = {}) {
+  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
   let socket;
   try {
-    socket = await connectWithBootstrap(socketPath);
+    socket = await connectWithBootstrap(resolvedTransport);
   } catch (error) {
     await writeNativeMessage(process.stdout, {
       type: 'agent.response',
@@ -133,6 +134,16 @@ export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
 
   socket.setEncoding('utf8');
   bindBridgeSocketLifecycle(socket);
+  const handleStdinEnd = () => {
+    socket.destroy();
+  };
+  process.stdin.once('end', handleStdinEnd);
+  const cleanupStdinEndListener = () => {
+    process.stdin.removeListener('end', handleStdinEnd);
+  };
+  socket.once('close', cleanupStdinEndListener);
+  socket.once('end', cleanupStdinEndListener);
+  socket.once('error', cleanupStdinEndListener);
   await writeJsonLine(socket, { type: 'register', role: 'extension' });
 
   let lineBuffer = '';
@@ -186,55 +197,61 @@ export async function runNativeHost({ socketPath = getSocketPath() } = {}) {
     }
   });
 
-  createNativeMessageReader(process.stdin, (message) => {
-    void (async () => {
-      if (isHostBridgeRequest(message)) {
-        await writeJsonLine(socket, {
-          type: 'agent.request',
-          request: message.request,
-        });
-        return;
-      }
-      if (isHostStatusRequest(message)) {
-        await writeJsonLine(socket, {
-          type: 'extension.setup_status.request',
-          requestId: message.requestId,
-        });
-        return;
-      }
-      if (isHostIdentity(message)) {
-        await writeJsonLine(socket, {
-          type: 'extension.identity',
-          browserName: message.browserName,
-          profileLabel: message.profileLabel,
-        });
-        return;
-      }
-      if (isHostAccessUpdate(message)) {
-        await writeJsonLine(socket, {
-          type: 'extension.access_update',
-          accessEnabled: message.accessEnabled,
-        });
-        return;
-      }
-      if (isHostActivity(message)) {
+  createNativeMessageReader(
+    process.stdin,
+    (message) => {
+      void (async () => {
+        if (isHostBridgeRequest(message)) {
+          await writeJsonLine(socket, {
+            type: 'agent.request',
+            request: message.request,
+          });
+          return;
+        }
+        if (isHostStatusRequest(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.setup_status.request',
+            requestId: message.requestId,
+          });
+          return;
+        }
+        if (isHostIdentity(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.identity',
+            browserName: message.browserName,
+            profileLabel: message.profileLabel,
+          });
+          return;
+        }
+        if (isHostAccessUpdate(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.access_update',
+            accessEnabled: message.accessEnabled,
+          });
+          return;
+        }
+        if (isHostActivity(message)) {
+          await writeJsonLine(socket, {
+            type: 'extension.activity',
+            at: message.at,
+          });
+          return;
+        }
         await writeJsonLine(socket, {
-          type: 'extension.activity',
-          at: message.at,
+          type: 'extension.response',
+          response: message,
         });
-        return;
-      }
-      await writeJsonLine(socket, {
-        type: 'extension.response',
-        response: message,
+      })().catch((err) => {
+        console.error(
+          'native-host: stdin message handler failed:',
+          err instanceof Error ? err.message : err
+        );
       });
-    })().catch((err) => {
-      console.error(
-        'native-host: stdin message handler failed:',
-        err instanceof Error ? err.message : err
-      );
-    });
-  });
+    },
+    () => {
+      socket.destroy();
+    }
+  );
 }
 
 /**
@@ -270,28 +287,49 @@ export function bindBridgeSocketLifecycle(
 }
 
 /**
- * @param {string} socketPath
+ * @typedef {{
+ *   connectSocketFn?: (transport: BridgeTransport) => Promise<net.Socket>,
+ *   shouldBootstrapFn?: (error: unknown) => boolean,
+ *   spawnBridgeDaemonFn?: () => void,
+ *   delayFn?: (ms: number) => Promise<void>,
+ *   maxAttempts?: number,
+ * }} ConnectWithBootstrapOptions
+ */
+
+/**
+ * @param {BridgeTransport | string} transport
+ * @param {ConnectWithBootstrapOptions} [options]
  * @returns {Promise<net.Socket>}
  */
-async function connectWithBootstrap(socketPath) {
+export async function connectWithBootstrap(transport, options = {}) {
+  const {
+    connectSocketFn = connectSocket,
+    shouldBootstrapFn = shouldBootstrap,
+    spawnBridgeDaemonFn = spawnBridgeDaemon,
+    delayFn = delay,
+    maxAttempts = 10,
+  } = options;
+  const resolvedTransport =
+    typeof transport === 'string' ? createSocketBridgeTransport(transport) : transport;
+
   try {
-    return await connectSocket(socketPath);
+    return await connectSocketFn(resolvedTransport);
   } catch (error) {
-    if (!shouldBootstrap(error)) {
+    if (!shouldBootstrapFn(error)) {
       throw error;
     }
   }
 
-  spawnBridgeDaemon();
+  spawnBridgeDaemonFn();
 
   let lastError = null;
-  for (let attempt = 0; attempt < 10; attempt += 1) {
-    await delay(200);
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    await delayFn(200);
     try {
-      return await connectSocket(socketPath);
+      return await connectSocketFn(resolvedTransport);
     } catch (error) {
       lastError = error;
-      if (!shouldBootstrap(error)) {
+      if (!shouldBootstrapFn(error)) {
         throw error;
       }
     }
@@ -301,12 +339,15 @@ async function connectWithBootstrap(socketPath) {
 }
 
 /**
- * @param {string} socketPath
+ * @param {BridgeTransport} transport
  * @returns {Promise<net.Socket>}
  */
-function connectSocket(socketPath) {
+function connectSocket(transport) {
   return new Promise((resolve, reject) => {
-    const socket = net.createConnection(socketPath);
+    const socket =
+      transport.type === 'tcp'
+        ? net.createConnection({ host: transport.host, port: transport.port })
+        : net.createConnection(transport.socketPath);
     /**
      * @param {Error} error
      * @returns {void}
@@ -328,18 +369,14 @@ function connectSocket(socketPath) {
  * @returns {void}
  */
 function spawnBridgeDaemon() {
-  const child = spawn(process.execPath, [daemonEntryPath], {
-    detached: true,
-    stdio: 'ignore',
-  });
-  child.unref();
+  spawnBridgeDaemonProcess();
 }
 
 /**
  * @param {unknown} error
  * @returns {boolean}
  */
-function shouldBootstrap(error) {
+export function shouldBootstrap(error) {
   return (
     error instanceof Error &&
     'code' in error &&

package/packages/protocol/src/capabilities.js

@@ -17,6 +17,7 @@ export const CAPABILITIES = Object.freeze({
   CDP_DOM_SNAPSHOT: 'cdp.dom_snapshot',
   CDP_BOX_MODEL: 'cdp.box_model',
   CDP_STYLES: 'cdp.styles',
+  CDP_INPUT: 'cdp.input',
   AUTOMATION_INPUT: 'automation.input',
   TABS_MANAGE: 'tabs.manage',
   PERFORMANCE_READ: 'performance.read',
@@ -38,6 +39,7 @@ export const DEFAULT_CAPABILITIES = Object.freeze([
   CAPABILITIES.CDP_DOM_SNAPSHOT,
   CAPABILITIES.CDP_BOX_MODEL,
   CAPABILITIES.CDP_STYLES,
+  CAPABILITIES.CDP_INPUT,
   CAPABILITIES.TABS_MANAGE,
   CAPABILITIES.PERFORMANCE_READ,
   CAPABILITIES.NETWORK_READ,
@@ -99,6 +101,7 @@ export const METHOD_CAPABILITIES = Object.freeze({
   'cdp.get_dom_snapshot': CAPABILITIES.CDP_DOM_SNAPSHOT,
   'cdp.get_box_model': CAPABILITIES.CDP_BOX_MODEL,
   'cdp.get_computed_styles_for_node': CAPABILITIES.CDP_STYLES,
+  'cdp.dispatch_key_event': CAPABILITIES.CDP_INPUT,
   'performance.get_metrics': CAPABILITIES.PERFORMANCE_READ,
   'log.tail': null,
   'health.ping': null,

package/packages/protocol/src/defaults.js

@@ -65,6 +65,7 @@ export const DEBUGGER_BACKED_METHODS = new Set([
   'cdp.get_dom_snapshot',
   'cdp.get_box_model',
   'cdp.get_computed_styles_for_node',
+  'cdp.dispatch_key_event',
 ]);
 
 /**

package/packages/protocol/src/errors.js

@@ -25,6 +25,10 @@ export const ERROR_RECOVERY = Object.freeze({
     retry: false,
     hint: 'Access is off for this window. Ask the user to click Enable in the Browser Bridge popup or side panel. Do not request access again until that window is enabled.',
   },
+  [ERROR_CODES.RESULT_TRUNCATED]: {
+    retry: false,
+    hint: 'Result was truncated to fit the response budget. Narrow the query or raise the relevant budget if more detail is required.',
+  },
   [ERROR_CODES.ELEMENT_STALE]: {
     retry: false,
     alternativeMethod: 'dom.query',

package/packages/protocol/src/payload-cost.js

@@ -22,7 +22,9 @@ export function getUtf8ByteLength(value) {
   if (!value) {
     return 0;
   }
-  return textEncoder.encode(value).length;
+  return typeof Buffer !== 'undefined'
+    ? Buffer.byteLength(value, 'utf8')
+    : textEncoder.encode(value).length;
 }
 
 /**
@@ -45,14 +47,25 @@ export function estimateSerializedPayloadCost(serialized) {
 }
 
 /**
- * Estimate cost for a JSON-serializable payload.
+ * Serialize a JSON payload for transport-oriented cost estimation.
  *
  * @param {unknown} value
- * @returns {PayloadCost}
+ * @returns {string}
  */
-export function estimateJsonPayloadCost(value) {
+export function serializeJsonPayload(value) {
   if (typeof value === 'undefined') {
-    return estimateSerializedPayloadCost('');
+    return '';
   }
-  return estimateSerializedPayloadCost(JSON.stringify(value) ?? '');
+  return JSON.stringify(value) ?? '';
+}
+
+/**
+ * Estimate cost for a JSON-serializable payload.
+ *
+ * @param {unknown} value
+ * @param {string} [serialized]
+ * @returns {PayloadCost}
+ */
+export function estimateJsonPayloadCost(value, serialized = serializeJsonPayload(value)) {
+  return estimateSerializedPayloadCost(serialized);
 }