machine-bridge-mcp 1.1.5 → 1.2.1

package/src/local/browser-bridge.mjs

@@ -12,23 +12,13 @@ import {
   isAllowedExtensionOrigin, isAllowedLoopbackHost, loadOrCreatePairing,
   pairingHtml, savePairing, securityHeaders, sendJson,
 } from "./browser-pairing-store.mjs";
-import {
-  clampInt, normalizeBrowserAction, normalizeBrowserSelector, normalizeBrowserWait, normalizeFormAction,
-  normalizeInputMode, normalizeNavigationWait, normalizeTabCommand, optionalInteger, optionalString,
-  validateNavigationUrl,
-} from "./browser-command.mjs";
+import { clampInt } from "./browser-command.mjs";
+import { BrowserOperationService } from "./browser-operation-service.mjs";
 
 const MAX_PORT_ATTEMPTS = 10;
 const MAX_PENDING = 32;
-const MAX_SOURCE_BYTES = 4 * 1024 * 1024;
-const MAX_FORM_FIELDS = 200;
-const MAX_FIELD_VALUE_CHARS = 128 * 1024;
-const MAX_FORM_VALUE_BYTES = 4 * 1024 * 1024;
-const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
 const EXTENSION_HANDSHAKE_MS = 3_000;
 
-
-
 export class BrowserBridgeManager {
   constructor({ policy, authorizeTool = null, stateRoot = "", runProcess, readResourceText, readResourceBinary, throwIfCancelled = () => {} }) {
     this.policy = policy || {};
@@ -57,248 +47,46 @@ export class BrowserBridgeManager {
     this.port = 0;
     this.token = "";
     this.extensionPath = resolve(packageRoot, "browser-extension");
+    this.operationService = new BrowserOperationService({
+      authorizeTool: (tool) => this.authorizeTool(tool),
+      ensureStarted: (context) => this.ensureStarted(context),
+      request: (...args) => this.request(...args),
+      bridgeStatus: () => ({
+        port: this.port,
+        brokerRole: this.server ? "owner" : this.upstream?.readyState === 1 ? "client" : "unavailable",
+        extensionConnected: this.extensionConnected(),
+        extensionInfo: this.extensionStatusInfo(),
+        extensionReloadRequired: this.extensionReloadRequired(),
+      }),
+      extensionPath: this.extensionPath,
+      expectedExtensionVersion: EXPECTED_EXTENSION_VERSION,
+      runProcess: (...args) => this.runProcess(...args),
+      readResourceText: (name) => this.readResourceText(name),
+      readResourceBinary: (name) => this.readResourceBinary(name),
+    });
   }
 
-  async status(context = {}) {
-    this.authorizeTool("browser_status");
-    await this.ensureStarted(context);
-    return {
-      available: true,
-      connected: this.extensionConnected(),
-      broker_role: this.server ? "owner" : this.upstream?.readyState === 1 ? "client" : "unavailable",
-      endpoint: `ws://127.0.0.1:${this.port}/extension`,
-      pairing_url: `http://127.0.0.1:${this.port}/pair`,
-      extension_path: this.extensionPath,
-      expected_extension_version: EXPECTED_EXTENSION_VERSION,
-      extension_protocol: this.extensionStatusInfo()?.protocol || null,
-      extension_version: this.extensionStatusInfo()?.version || "",
-      extension_capabilities: this.extensionStatusInfo()?.capabilities || [],
-      extension_reload_required: this.extensionReloadRequired(),
-      supported_browsers: ["Chrome", "Chromium", "Microsoft Edge", "Brave", "Vivaldi", "other Chromium browsers with Manifest V3"],
-      controls_existing_profile: true,
-      controls_extension_profile: true,
-      launches_browser_process: false,
-      launches_separate_automation_profile: false,
-      profile_identity_verifiable: false,
-      uses_existing_tabs_and_login_state: true,
-      source_access: true,
-      semantic_snapshot_refs: true,
-      actionability_waits: true,
-      trusted_input: true,
-      input_modes: ["auto", "trusted", "dom"],
-      complex_form_fill: true,
-      tab_management: true,
-      explicit_waits: true,
-      screenshots: true,
-      restricted_pages: ["browser-internal pages", "extension stores", "some PDF/plugin viewers", "pages blocked by enterprise policy"],
-      security: {
-        loopback_only: true,
-        bearer_pairing_token: true,
-        arbitrary_extension_code_from_mcp: false,
-        resource_values_returned_to_model: false,
-      },
-    };
-  }
+  status(context = {}) { return this.operationService.status(context); }
 
-  async pair(args = {}, context = {}) {
-    this.authorizeTool("pair_browser_extension");
-    const status = await this.status(context);
-    if (args.open !== false) {
-      const command = process.platform === "darwin"
-        ? { cmd: "open", argv: [status.pairing_url] }
-        : process.platform === "win32"
-          ? { cmd: "cmd.exe", argv: ["/d", "/s", "/c", "start", "", status.pairing_url] }
-          : { cmd: "xdg-open", argv: [status.pairing_url] };
-      await this.runProcess(command.cmd, command.argv, 30_000, false, 128 * 1024, context);
-    }
-    return {
-      ...status,
-      opened_pairing_page: args.open !== false,
-      setup_steps: [
-        "Open the browser extensions page and enable developer mode.",
-        "Load the unpacked extension from extension_path once.",
-        "Open pairing_url; the installed extension stores the loopback endpoint and token locally.",
-        "After upgrades, reload the unpacked extension and accept any newly requested browser permission.",
-      ],
-    };
-  }
+  pair(args = {}, context = {}) { return this.operationService.pair(args, context); }
 
-  async listTabs(args = {}, context = {}) {
-    this.authorizeTool("browser_list_tabs");
-    const response = await this.request("list_tabs", {
-      currentWindow: args.current_window === true,
-      includePinned: args.include_pinned !== false,
-    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
-    return response;
-  }
+  listTabs(args = {}, context = {}) { return this.operationService.listTabs(args, context); }
 
-  async manageTabs(args = {}, context = {}) {
-    this.authorizeTool("browser_manage_tabs");
-    return this.request("manage_tabs", normalizeTabCommand(args), clampInt(args.timeout_seconds, 30, 1, 120), context);
-  }
+  manageTabs(args = {}, context = {}) { return this.operationService.manageTabs(args, context); }
 
-  async wait(args = {}, context = {}) {
-    this.authorizeTool("browser_wait");
-    const params = normalizeBrowserWait(args);
-    const conditionTimeoutSeconds = clampInt(args.timeout_seconds, 30, 1, 120);
-    return this.request("wait", params, conditionTimeoutSeconds + 5, context);
-  }
+  wait(args = {}, context = {}) { return this.operationService.wait(args, context); }
 
-  async getSource(args = {}, context = {}) {
-    this.authorizeTool("browser_get_source");
-    const response = await this.request("get_source", {
-      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
-      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
-      allFrames: args.all_frames === true,
-      maxBytes: clampInt(args.max_bytes, 1024 * 1024, 1, MAX_SOURCE_BYTES),
-    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
-    return response;
-  }
+  getSource(args = {}, context = {}) { return this.operationService.getSource(args, context); }
 
-  async inspectPage(args = {}, context = {}) {
-    this.authorizeTool("browser_inspect_page");
-    return this.request("inspect_page", {
-      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
-      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
-      allFrames: args.all_frames !== false,
-      maxElements: clampInt(args.max_elements, 300, 1, 1000),
-      includeValues: args.include_values === true,
-    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
-  }
+  inspectPage(args = {}, context = {}) { return this.operationService.inspectPage(args, context); }
 
-  async act(args = {}, context = {}) {
-    this.authorizeTool("browser_action");
-    const action = normalizeBrowserAction(args.action);
-    const rawUrl = optionalString(args.url, "url", 32768);
-    const payload = {
-      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
-      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
-      action,
-      selector: normalizeBrowserSelector(args.selector, action),
-      url: action === "navigate" ? validateNavigationUrl(rawUrl) : "",
-      value: null,
-      key: optionalString(args.key, "key", 100),
-      waitFor: normalizeNavigationWait(args.wait_for),
-      inputMode: normalizeInputMode(args.input_mode),
-      elementTimeoutMs: clampInt(args.element_timeout_seconds, 10, 1, 60) * 1000,
-    };
-    if (action !== "navigate" && rawUrl) throw new Error("url is only valid for navigate");
-    if (action !== "press" && payload.key) throw new Error("key is only valid for press");
-    if (payload.inputMode === "trusted" && !["click", "double_click", "hover", "press", "type_text"].includes(action)) {
-      throw new Error("input_mode=trusted supports click, double_click, hover, press, and type_text only");
-    }
-    if (args.value !== undefined) payload.value = boundedValue(args.value, "value");
-    if (args.value_resource !== undefined) {
-      if (payload.value !== null) throw new Error("value and value_resource are mutually exclusive");
-      payload.value = boundedValue(await this.readResourceText(validateResource(args.value_resource)), "value_resource");
-    }
-    if (payload.value !== null && !["fill", "select", "press", "type_text"].includes(action)) throw new Error(`value is not valid for browser action '${action}'`);
-    const pageAction = !["navigate", "reload", "back", "forward"].includes(action);
-    const defaultTimeout = pageAction ? Math.min(120, Math.max(30, payload.elementTimeoutMs / 1000 + 5)) : 30;
-    const response = await this.request("action", payload, clampInt(args.timeout_seconds, defaultTimeout, 1, 120), context);
-    return {
-      ...response,
-      value_source: args.value_resource !== undefined ? "local-resource" : payload.value === null ? "none" : "mcp-argument",
-      value_exposed: false,
-    };
-  }
+  act(args = {}, context = {}) { return this.operationService.act(args, context); }
 
-  async fillForm(args = {}, context = {}) {
-    this.authorizeTool("browser_fill_form");
-    if (!Array.isArray(args.fields) || !args.fields.length) throw new Error("fields must be a non-empty array");
-    if (args.fields.length > MAX_FORM_FIELDS) throw new Error(`fields contains more than ${MAX_FORM_FIELDS} entries`);
-    const fields = [];
-    let totalValueBytes = 0;
-    for (let index = 0; index < args.fields.length; index += 1) {
-      const input = args.fields[index];
-      if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`fields[${index}] must be an object`);
-      const allowed = new Set(["selector", "value", "value_resource", "action", "sensitive"]);
-      for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`unknown fields[${index}] property: ${key}`);
-      let value = input.value === undefined ? null : boundedValue(input.value, `fields[${index}].value`);
-      if (input.value_resource !== undefined) {
-        if (value !== null) throw new Error(`fields[${index}] value and value_resource are mutually exclusive`);
-        value = boundedValue(await this.readResourceText(validateResource(input.value_resource)), `fields[${index}].value_resource`);
-      }
-      if (value !== null) {
-        totalValueBytes += Buffer.byteLength(value);
-        if (totalValueBytes > MAX_FORM_VALUE_BYTES) throw new Error("form field values exceed 4 MiB total");
-      }
-      const action = input.action === undefined ? "fill" : normalizeFormAction(input.action);
-      if (value === null && !["check", "uncheck", "click"].includes(action)) throw new Error(`fields[${index}] requires value or value_resource`);
-      if (value !== null && !["fill", "select"].includes(action)) throw new Error(`fields[${index}] value is not valid for action '${action}'`);
-      fields.push({
-        selector: normalizeBrowserSelector(input.selector, action),
-        value,
-        action,
-        sensitive: input.sensitive === true || input.value_resource !== undefined,
-      });
-    }
-    const elementTimeoutSeconds = clampInt(args.element_timeout_seconds, 10, 1, 60);
-    return this.request("fill_form", {
-      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
-      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
-      fields,
-      submit: args.submit === true,
-      submitSelector: args.submit_selector ? normalizeBrowserSelector(args.submit_selector, "click") : null,
-      waitFor: normalizeNavigationWait(args.wait_for),
-      elementTimeoutMs: elementTimeoutSeconds * 1000,
-    }, clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180), context);
-  }
+  fillForm(args = {}, context = {}) { return this.operationService.fillForm(args, context); }
 
-  async uploadFiles(args = {}, context = {}) {
-    this.authorizeTool("browser_upload_files");
-    if (!Array.isArray(args.resources) || !args.resources.length || args.resources.length > 8) throw new Error("resources must contain 1 to 8 registered resource names");
-    const filenames = optionalStringArray(args.filenames, "filenames", 8, 255);
-    const mimeTypes = optionalStringArray(args.mime_types, "mime_types", 8, 200);
-    if (filenames.length > args.resources.length || mimeTypes.length > args.resources.length) throw new Error("filenames and mime_types cannot contain more entries than resources");
-    const files = [];
-    let total = 0;
-    for (const raw of args.resources) {
-      const name = validateResource(raw);
-      const resource = this.readResourceBinary(name);
-      total += resource.buffer.length;
-      if (total > 5 * 1024 * 1024) throw new Error("browser upload resources exceed 5 MiB total");
-      const suppliedFilename = filenames[files.length];
-      const derivedFilename = resource.path.split(/[\\/]/).pop() || name;
-      files.push({
-        filename: normalizeUploadFilename(suppliedFilename || derivedFilename, { derived: !suppliedFilename }),
-        mime: normalizeMimeType(mimeTypes[files.length] || "application/octet-stream"),
-        data: resource.buffer.toString("base64"),
-      });
-    }
-    const elementTimeoutSeconds = clampInt(args.element_timeout_seconds, 10, 1, 60);
-    const result = await this.request("upload_files", {
-      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
-      frameId: optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER),
-      selector: normalizeBrowserSelector(args.selector, "fill"),
-      files,
-      elementTimeoutMs: elementTimeoutSeconds * 1000,
-    }, clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180), context);
-    return { ...result, resource_names: args.resources.map(String), resource_contents_exposed: false };
-  }
+  uploadFiles(args = {}, context = {}) { return this.operationService.uploadFiles(args, context); }
 
-  async screenshot(args = {}, context = {}) {
-    this.authorizeTool("browser_screenshot");
-    const result = await this.request("screenshot", {
-      tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
-      format: args.format === "jpeg" ? "jpeg" : "png",
-      quality: clampInt(args.quality, 90, 1, 100),
-    }, clampInt(args.timeout_seconds, 30, 1, 120), context);
-    const data = String(result.data || "");
-    const match = /^data:(image\/(?:png|jpeg));base64,([A-Za-z0-9+/=]+)$/.exec(data);
-    if (!match) throw new Error("browser extension returned an invalid screenshot");
-    return {
-      $mcp: {
-        content: [{ type: "image", data: match[2], mimeType: match[1] }],
-        structuredContent: {
-          tab_id: result.tab_id,
-          url: result.url,
-          title: result.title,
-          mime_type: match[1],
-        },
-      },
-    };
-  }
+  screenshot(args = {}, context = {}) { return this.operationService.screenshot(args, context); }
 
   async request(method, params, timeoutSeconds, context = {}) {
     await this.ensureStarted(context);
@@ -783,42 +571,3 @@ export class BrowserBridgeManager {
   }
 
 }
-
-function normalizeUploadFilename(value, { derived = false } = {}) {
-  let name = String(value || "");
-  if (derived) name = name.replace(/[\u0000-\u001f\u007f/\\]+/g, "_").trim();
-  if (!name || name === "." || name === ".." || name.length > 255 || /[\u0000-\u001f\u007f/\\]/.test(name)) {
-    if (derived) return "upload.bin";
-    throw new Error("filenames entries must be safe single-component filenames of at most 255 characters");
-  }
-  return name;
-}
-
-function normalizeMimeType(value) {
-  const mime = String(value || "").trim().toLowerCase();
-  if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mime) || mime.length > 200) {
-    throw new Error("mime_types entries must be valid media types");
-  }
-  return mime;
-}
-
-function optionalStringArray(value, label, maxItems, maxLength) {
-  if (value === undefined || value === null) return [];
-  if (!Array.isArray(value) || value.length > maxItems) throw new Error(`${label} must be an array with at most ${maxItems} entries`);
-  return value.map((item, index) => {
-    if (typeof item !== "string" || item.includes("\0") || !item.length || item.length > maxLength) throw new Error(`${label}[${index}] must be a non-empty string of at most ${maxLength} characters`);
-    return item;
-  });
-}
-
-function boundedValue(value, label) {
-  const string = String(value);
-  if (string.includes("\0") || string.length > MAX_FIELD_VALUE_CHARS) throw new Error(`${label} exceeds the maximum length or contains a NUL byte`);
-  return string;
-}
-
-function validateResource(value) {
-  const name = String(value || "").trim();
-  if (!RESOURCE_NAME.test(name)) throw new Error("value_resource is invalid");
-  return name;
-}

package/src/local/browser-extension-protocol.mjs

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { packageRoot } from "./state.mjs";
@@ -9,6 +11,10 @@ const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
 ]);
 export const MAX_BROWSER_MESSAGE_BYTES = 8 * 1024 * 1024;
 
+/** @typedef {{protocol: number, version: string, capabilities: string[]}} ExtensionInfo */
+/** @typedef {{readyState: number, close: (code?: number, reason?: string) => unknown, send: (value: string) => unknown}} ProtocolSocket */
+
+/** @param {unknown} value @returns {ExtensionInfo | null} */
 export function normalizeCompatibleExtensionInfo(value) {
   const info = normalizeExtensionInfo(value);
   if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL || info.version !== EXPECTED_EXTENSION_VERSION) return null;
@@ -16,6 +22,7 @@ export function normalizeCompatibleExtensionInfo(value) {
   return info;
 }
 
+/** @param {Record<string, unknown>} message @returns {ExtensionInfo} */
 export function parseExtensionHello(message) {
   if (message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
     throw new Error(`extension protocol mismatch; expected ${BROWSER_EXTENSION_PROTOCOL}; reload the extension`);
@@ -30,6 +37,10 @@ export function parseExtensionHello(message) {
   return info;
 }
 
+/**
+ * @param {string | Buffer | Uint8Array} data
+ * @returns {{ok: true, message: Record<string, unknown>} | {ok: false, code: number, reason: string}}
+ */
 export function parseBrowserSocketMessage(data) {
   if (Buffer.byteLength(data) > MAX_BROWSER_MESSAGE_BYTES) return { ok: false, code: 1009, reason: "message too large" };
   let text;
@@ -44,10 +55,12 @@ export function parseBrowserSocketMessage(data) {
   return { ok: true, message };
 }
 
+/** @param {ProtocolSocket} socket @param {number} code @param {string} reason */
 export function closeProtocolSocket(socket, code, reason) {
   try { socket.close(code, reason); } catch {}
 }
 
+/** @param {ProtocolSocket | null | undefined} socket @param {unknown} value */
 export function safeSocketSend(socket, value) {
   if (!socket || socket.readyState !== 1) return false;
   try {
@@ -58,12 +71,14 @@ export function safeSocketSend(socket, value) {
   }
 }
 
+/** @param {unknown} value @returns {ExtensionInfo | null} */
 function normalizeExtensionInfo(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const protocol = Number(value.protocol);
-  const version = typeof value.version === "string" && value.version.length <= 100 ? value.version : "";
-  const capabilities = Array.isArray(value.capabilities)
-    ? [...new Set(value.capabilities.filter((entry) => typeof entry === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(entry)))].slice(0, 32)
+  const record = /** @type {Record<string, unknown>} */ (value);
+  const protocol = Number(record.protocol);
+  const version = typeof record.version === "string" && record.version.length <= 100 ? record.version : "";
+  const capabilities = Array.isArray(record.capabilities)
+    ? [...new Set(record.capabilities.filter((entry) => typeof entry === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(entry)))].slice(0, 32)
     : [];
   if (!Number.isInteger(protocol) || protocol < 1 || !version) return null;
   return { protocol, version, capabilities };