@browserbridge/bbx 1.6.0 → 1.6.2

package/package.json

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

package/packages/agent-client/src/cli.js

@@ -4,12 +4,16 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import {
   applyWindowsTcpTransportDefaults,
+  getProxyConfigPath,
+  readProxyConfig,
   SUPPORTED_BROWSERS,
 } from '../../native-host/src/config.js';
+import { writeBridgeAuthToken } from '../../native-host/src/auth-token.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 import { uninstallNativeManifest } from '../../native-host/src/install-manifest.js';
 import {
@@ -47,6 +51,15 @@ import {
   removeMcpConfig,
 } from './mcp-config.js';
 import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
+import {
+  addRemoteDestination,
+  createBridgeClientForDestination,
+  listBridgeDestinations,
+  normalizeDestinationId,
+  parseRemoteEndpoint,
+  readRemoteConfig,
+  removeRemoteDestination,
+} from './remotes.js';
 import { collectSetupStatus } from './setup-status.js';
 import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
 
@@ -382,6 +395,16 @@ if (command === 'mcp') {
   process.exit(1);
 }
 
+if (command === 'proxy') {
+  await handleProxyCommand(rest);
+  process.exit(0);
+}
+
+if (command === 'remote') {
+  await handleRemoteCommand(rest);
+  process.exit(0);
+}
+
 const clientTimeoutMs = getClientTimeoutOverride();
 applyWindowsTcpTransportDefaults();
 const client = new BridgeClient(
@@ -828,6 +851,247 @@ async function main() {
   }
 }
 
+/**
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+async function handleProxyCommand(args) {
+  const [subcommand, ...restArgs] = args;
+  if (subcommand === 'enable') {
+    const options = parseProxyEnableArgs(restArgs);
+    const token = options.token ?? randomUUID();
+    await writeBridgeAuthToken(token);
+    const configPath = getProxyConfigPath();
+    await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.promises.writeFile(
+      configPath,
+      `${JSON.stringify(
+        {
+          enabled: true,
+          port: options.port,
+          bindHost: options.bindHost,
+          token,
+        },
+        null,
+        2
+      )}\n`,
+      { encoding: 'utf8', mode: 0o600 }
+    );
+    const result = await restartBridgeDaemon();
+    const exampleHost = getProxyExampleHost(options.bindHost);
+    process.stdout.write(
+      [
+        `Browser Bridge proxy enabled on ${options.bindHost}:${options.port}.`,
+        '',
+        `Token: ${token}`,
+        `Config: ${configPath}`,
+        `Daemon: ${result.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
+        '',
+        'On your dev machine, add this remote:',
+        '',
+        `bbx remote add <name> <host:port> --token ${token}`,
+        '',
+        'Example:',
+        '',
+        `bbx remote add remote-bbx ${exampleHost}:${options.port} --token ${token}`,
+        '',
+      ].join('\n')
+    );
+    return;
+  }
+
+  if (subcommand === 'disable') {
+    const configPath = getProxyConfigPath();
+    await fs.promises.rm(configPath, { force: true });
+    const result = await restartBridgeDaemon();
+    process.stdout.write(
+      `Browser Bridge proxy disabled. Daemon ${result.previouslyRunning ? 'restarted' : 'started'}.\n`
+    );
+    return;
+  }
+
+  if (subcommand === 'status') {
+    const config = readProxyConfig();
+    if (!config) {
+      process.stdout.write('Browser Bridge proxy is disabled.\n');
+      return;
+    }
+    process.stdout.write(
+      [
+        `Browser Bridge proxy is enabled on ${config.bindHost}:${config.port}.`,
+        `Config: ${getProxyConfigPath()}`,
+        '',
+      ].join('\n')
+    );
+    return;
+  }
+
+  throw new Error('Usage: bbx proxy <enable|disable|status>');
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ port: number, bindHost: string, token?: string }}
+ */
+function parseProxyEnableArgs(args) {
+  /** @type {{ port: number, bindHost: string, token?: string }} */
+  const options = { port: 9223, bindHost: '0.0.0.0' };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--port') {
+      options.port = parseIntArg(args[++index] || '', 'port');
+      continue;
+    }
+    if (arg === '--bind-host') {
+      options.bindHost = args[++index] || '';
+      if (!options.bindHost.trim()) {
+        throw new Error('--bind-host requires a value.');
+      }
+      continue;
+    }
+    if (arg === '--token') {
+      options.token = args[++index] || '';
+      if (!options.token.trim()) {
+        throw new Error('--token requires a value.');
+      }
+      continue;
+    }
+    throw new Error(`Unknown proxy enable option "${arg}".`);
+  }
+  if (options.port < 1 || options.port > 65535) {
+    throw new Error('port must be an integer between 1 and 65535.');
+  }
+  return options;
+}
+
+/**
+ * @param {string} bindHost
+ * @returns {string}
+ */
+function getProxyExampleHost(bindHost) {
+  if (bindHost !== '0.0.0.0' && bindHost !== '::') {
+    return bindHost;
+  }
+
+  for (const entries of Object.values(os.networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      if (!entry.internal && entry.family === 'IPv4') {
+        return entry.address;
+      }
+    }
+  }
+
+  return '<host>';
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+async function handleRemoteCommand(args) {
+  const [subcommand, ...restArgs] = args;
+  if (subcommand === 'add') {
+    const [name, endpoint, ...optionArgs] = restArgs;
+    if (!name || !endpoint) {
+      throw new Error('Usage: bbx remote add <name> <host:port> --token <token>');
+    }
+    const token = parseRemoteTokenOption(optionArgs);
+    const { host, port } = parseRemoteEndpoint(endpoint);
+    const remote = await addRemoteDestination({
+      id: normalizeDestinationId(name),
+      host,
+      port,
+      token,
+    });
+    process.stdout.write(
+      `Remote destination "${remote.id}" saved (${remote.host}:${remote.port}).\n`
+    );
+    return;
+  }
+
+  if (subcommand === 'remove') {
+    const [name] = restArgs;
+    if (!name) {
+      throw new Error('Usage: bbx remote remove <name>');
+    }
+    const removed = await removeRemoteDestination(name);
+    process.stdout.write(
+      removed
+        ? `Remote destination "${name}" removed.\n`
+        : `Remote destination "${name}" was not configured.\n`
+    );
+    return;
+  }
+
+  if (subcommand === 'list') {
+    const config = await readRemoteConfig();
+    if (config.remotes.length === 0) {
+      process.stdout.write('No remote destinations configured.\n');
+      return;
+    }
+    process.stdout.write(
+      `${config.remotes.map((remote) => `${remote.id}\t${remote.host}:${remote.port}`).join('\n')}\n`
+    );
+    return;
+  }
+
+  if (subcommand === 'test') {
+    const [name] = restArgs;
+    if (!name) {
+      throw new Error('Usage: bbx remote test <name>');
+    }
+    const remoteClient = await createBridgeClientForDestination(name);
+    try {
+      await remoteClient.connect();
+      const response = await remoteClient.request({ method: 'health.ping' });
+      process.stdout.write(
+        response.ok
+          ? `Remote destination "${name}" is reachable.\n`
+          : `Remote destination "${name}" failed: ${response.error.message}\n`
+      );
+    } finally {
+      await remoteClient.close();
+    }
+    return;
+  }
+
+  if (subcommand === 'destinations') {
+    const destinations = await listBridgeDestinations();
+    process.stdout.write(
+      `${destinations
+        .map((destination) =>
+          destination.local
+            ? `${destination.id}\tlocal`
+            : `${destination.id}\t${destination.host}:${destination.port}`
+        )
+        .join('\n')}\n`
+    );
+    return;
+  }
+
+  throw new Error('Usage: bbx remote <add|remove|list|test|destinations>');
+}
+
+/**
+ * @param {string[]} args
+ * @returns {string}
+ */
+function parseRemoteTokenOption(args) {
+  let token = '';
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--token') {
+      token = args[++index] || '';
+      continue;
+    }
+    throw new Error(`Unknown remote add option "${arg}".`);
+  }
+  if (!token.trim()) {
+    throw new Error('Usage: bbx remote add <name> <host:port> --token <token>');
+  }
+  return token.trim();
+}
+
 /**
  * @param {unknown} error
  * @returns {string}

package/packages/agent-client/src/command-registry.js

@@ -257,6 +257,10 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Diagnose install, daemon, extension, and access readiness',
       'bbx restart                                                        Restart the local Browser Bridge daemon',
+      'bbx proxy enable [--port 9223] [--bind-host 0.0.0.0]              Enable opt-in TCP proxy mode and print a token',
+      'bbx proxy disable                                                  Disable proxy mode and restart the daemon',
+      'bbx remote add <name> <host:port> --token <token>                  Add a remote Browser Bridge destination (example: remote-bbx 192.168.56.20:9223)',
+      'bbx remote list                                                    List remote destinations',
       'bbx access-request                                                 Request Browser Bridge access for the focused window',
       'bbx logs                                                           Recent bridge logs',
       'bbx tabs                                                           List available tabs',

package/packages/agent-client/src/remotes.js

@@ -0,0 +1,202 @@
+// @ts-check
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { createTcpBridgeTransport, getBridgeDir } from '../../native-host/src/config.js';
+import { normalizeBridgeAuthToken } from '../../native-host/src/auth-token.js';
+import { BridgeClient } from './client.js';
+
+const REMOTES_FILENAME = 'remotes.json';
+const LOCAL_DESTINATION_ID = 'local';
+export const DEFAULT_REMOTE_PORT = 9223;
+
+/**
+ * @typedef {{ id: string, host: string, port: number, token: string }} RemoteDestination
+ */
+
+/**
+ * @typedef {{ remotes: RemoteDestination[] }} RemoteConfig
+ */
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getRemoteConfigPath(env = process.env) {
+  return path.join(getBridgeDir(env), REMOTES_FILENAME);
+}
+
+/**
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizeDestinationId(id) {
+  const normalized = id.trim();
+  if (!/^[A-Za-z0-9_.-]{1,64}$/u.test(normalized) || normalized === LOCAL_DESTINATION_ID) {
+    throw new Error('Remote name must be 1-64 letters, numbers, dots, dashes, or underscores.');
+  }
+  return normalized;
+}
+
+/**
+ * @param {string} endpoint
+ * @returns {{ host: string, port: number }}
+ */
+export function parseRemoteEndpoint(endpoint) {
+  const trimmed = endpoint.trim();
+  const match = /^(.+):(\d{1,5})$/u.exec(trimmed);
+  const host = (match ? match[1] : trimmed).trim().replace(/^\[|\]$/gu, '');
+  const port = match ? Number.parseInt(match[2], 10) : DEFAULT_REMOTE_PORT;
+  if (!host || /[\s/]/u.test(host)) {
+    throw new Error('Remote host must be a hostname or IP address.');
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('Remote port must be an integer between 1 and 65535.');
+  }
+  return { host, port };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {RemoteDestination | null}
+ */
+function normalizeRemote(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (
+    typeof record.id !== 'string' ||
+    typeof record.host !== 'string' ||
+    typeof record.port !== 'number' ||
+    typeof record.token !== 'string'
+  ) {
+    return null;
+  }
+  const token = normalizeBridgeAuthToken(record.token);
+  if (!token) {
+    return null;
+  }
+  try {
+    const id = normalizeDestinationId(record.id);
+    const { host, port } = parseRemoteEndpoint(`${record.host}:${record.port}`);
+    return { id, host, port, token };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ configPath?: string, readFile?: typeof fs.promises.readFile }} [options={}]
+ * @returns {Promise<RemoteConfig>}
+ */
+export async function readRemoteConfig(options = {}) {
+  const configPath = options.configPath ?? getRemoteConfigPath();
+  const readFile = options.readFile ?? fs.promises.readFile.bind(fs.promises);
+  try {
+    const parsed = JSON.parse(await readFile(configPath, 'utf8'));
+    /** @type {RemoteDestination[]} */
+    const remotes = [];
+    if (Array.isArray(parsed?.remotes)) {
+      for (const entry of parsed.remotes) {
+        const remote = normalizeRemote(entry);
+        if (remote) {
+          remotes.push(remote);
+        }
+      }
+    }
+    return { remotes };
+  } catch (error) {
+    if (
+      error &&
+      typeof error === 'object' &&
+      /** @type {{ code?: unknown }} */ (error).code === 'ENOENT'
+    ) {
+      return { remotes: [] };
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {RemoteConfig} config
+ * @param {{ configPath?: string, writeFile?: typeof fs.promises.writeFile, mkdir?: typeof fs.promises.mkdir }} [options={}]
+ * @returns {Promise<void>}
+ */
+export async function writeRemoteConfig(config, options = {}) {
+  const configPath = options.configPath ?? getRemoteConfigPath();
+  const writeFile = options.writeFile ?? fs.promises.writeFile.bind(fs.promises);
+  const mkdir = options.mkdir ?? fs.promises.mkdir.bind(fs.promises);
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify({ remotes: config.remotes }, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+}
+
+/**
+ * @param {RemoteDestination} remote
+ * @returns {Promise<RemoteDestination>}
+ */
+export async function addRemoteDestination(remote) {
+  const config = await readRemoteConfig();
+  const existing = config.remotes.findIndex((entry) => entry.id === remote.id);
+  if (existing === -1) {
+    config.remotes.push(remote);
+  } else {
+    config.remotes[existing] = remote;
+  }
+  await writeRemoteConfig(config);
+  return remote;
+}
+
+/**
+ * @param {string} id
+ * @returns {Promise<boolean>}
+ */
+export async function removeRemoteDestination(id) {
+  const normalizedId = normalizeDestinationId(id);
+  const config = await readRemoteConfig();
+  const next = config.remotes.filter((remote) => remote.id !== normalizedId);
+  await writeRemoteConfig({ remotes: next });
+  return next.length !== config.remotes.length;
+}
+
+/**
+ * @returns {Promise<Array<{ id: string, local: boolean, host: string | null, port: number | null }>>}
+ */
+export async function listBridgeDestinations() {
+  const config = await readRemoteConfig();
+  return [
+    { id: LOCAL_DESTINATION_ID, local: true, host: null, port: null },
+    ...config.remotes.map((remote) => ({
+      id: remote.id,
+      local: false,
+      host: remote.host,
+      port: remote.port,
+    })),
+  ];
+}
+
+/**
+ * @param {string | null | undefined} destinationId
+ * @param {{ defaultTimeoutMs?: number }} [options={}]
+ * @returns {Promise<BridgeClient>}
+ */
+export async function createBridgeClientForDestination(destinationId, options = {}) {
+  if (!destinationId || destinationId === LOCAL_DESTINATION_ID) {
+    return new BridgeClient(options);
+  }
+  const config = await readRemoteConfig();
+  const remote = config.remotes.find((entry) => entry.id === destinationId);
+  if (!remote) {
+    throw new Error(`Unknown Browser Bridge destination "${destinationId}".`);
+  }
+  return new BridgeClient({
+    ...options,
+    transport: createTcpBridgeTransport(remote.port, remote.host),
+    authToken: remote.token,
+    restartDaemonOnVersionMismatch: false,
+  });
+}