machine-bridge-mcp 0.13.0 → 0.15.0

package/src/local/browser-bridge.mjs

@@ -1,12 +1,17 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { WebSocket, WebSocketServer } from "ws";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
 import { assertStateMaintenanceAvailable, ownerOnlyFile, packageRoot } from "./state.mjs";
+import {
+  clampInt, normalizeBrowserAction, normalizeBrowserSelector, normalizeBrowserWait, normalizeFormAction,
+  normalizeInputMode, normalizeNavigationWait, normalizeTabCommand, optionalInteger, optionalString,
+  validateNavigationUrl,
+} from "./browser-command.mjs";
 
 const DEFAULT_PORT = 39393;
 const MAX_PORT_ATTEMPTS = 10;
@@ -18,6 +23,14 @@ const MAX_FIELD_VALUE_CHARS = 128 * 1024;
 const MAX_FORM_VALUE_BYTES = 4 * 1024 * 1024;
 const PAIRING_FILE = "browser-bridge.json";
 const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
+const BROWSER_EXTENSION_PROTOCOL = 3;
+const EXTENSION_HANDSHAKE_MS = 3_000;
+const EXTENSION_MANIFEST = JSON.parse(readFileSync(resolve(packageRoot, "browser-extension", "manifest.json"), "utf8"));
+const EXPECTED_EXTENSION_VERSION = String(EXTENSION_MANIFEST.version_name || EXTENSION_MANIFEST.version || "");
+if (!EXPECTED_EXTENSION_VERSION) throw new Error("packaged browser extension version is missing");
+const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
+  "semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
+]);
 
 export class BrowserBridgeManager {
   constructor({ policy, stateRoot = "", runProcess, readResourceText, readResourceBinary, throwIfCancelled = () => {} }) {
@@ -30,10 +43,15 @@ export class BrowserBridgeManager {
     this.server = null;
     this.wss = null;
     this.socket = null;
+    this.pendingExtensionSocket = null;
     this.upstream = null;
     this.runtimeClients = new Set();
     this.proxyRoutes = new Map();
     this.proxyExtensionConnected = false;
+    this.extensionInfo = null;
+    this.proxyExtensionInfo = null;
+    this.proxyExtensionReloadRequired = false;
+    this.extensionReloadRequiredFlag = false;
     this.recoveryTimer = null;
     this.stopping = false;
     this.pending = new Map();
@@ -47,16 +65,31 @@ export class BrowserBridgeManager {
     await this.ensureStarted(context);
     return {
       available: true,
-      connected: this.server ? this.socket?.readyState === 1 : this.proxyExtensionConnected,
+      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: {
@@ -86,6 +119,7 @@ export class BrowserBridgeManager {
         "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.",
       ],
     };
   }
@@ -98,6 +132,16 @@ export class BrowserBridgeManager {
     return response;
   }
 
+  async manageTabs(args = {}, context = {}) {
+    return this.request("manage_tabs", normalizeTabCommand(args), clampInt(args.timeout_seconds, 30, 1, 120), context);
+  }
+
+  async wait(args = {}, context = {}) {
+    const params = normalizeBrowserWait(args);
+    const conditionTimeoutSeconds = clampInt(args.timeout_seconds, 30, 1, 120);
+    return this.request("wait", params, conditionTimeoutSeconds + 5, context);
+  }
+
   async getSource(args = {}, context = {}) {
     const response = await this.request("get_source", {
       tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
@@ -130,17 +174,24 @@ export class BrowserBridgeManager {
       url: action === "navigate" ? validateNavigationUrl(rawUrl) : "",
       value: null,
       key: optionalString(args.key, "key", 100),
-      waitFor: normalizeWait(args.wait_for),
+      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"].includes(action)) throw new Error(`value is not valid for browser action '${action}'`);
-    const response = await this.request("action", payload, clampInt(args.timeout_seconds, 30, 1, 120), context);
+    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",
@@ -170,6 +221,7 @@ export class BrowserBridgeManager {
       }
       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,
@@ -177,14 +229,16 @@ export class BrowserBridgeManager {
         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: normalizeWait(args.wait_for),
-    }, clampInt(args.timeout_seconds, 60, 1, 180), context);
+      waitFor: normalizeNavigationWait(args.wait_for),
+      elementTimeoutMs: elementTimeoutSeconds * 1000,
+    }, clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180), context);
   }
 
   async uploadFiles(args = {}, context = {}) {
@@ -208,12 +262,14 @@ export class BrowserBridgeManager {
         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,
-    }, clampInt(args.timeout_seconds, 60, 1, 180), context);
+      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 };
   }
 
@@ -244,7 +300,7 @@ export class BrowserBridgeManager {
     await this.ensureStarted(context);
     this.throwIfCancelled(context);
     const transport = this.server ? this.socket : this.upstream;
-    const extensionConnected = this.server ? this.socket?.readyState === 1 : this.proxyExtensionConnected;
+    const extensionConnected = this.extensionConnected();
     if (!transport || transport.readyState !== 1 || !extensionConnected) {
       throw new Error("browser extension is not connected; call pair_browser_extension after loading the packaged extension");
     }
@@ -316,7 +372,7 @@ export class BrowserBridgeManager {
         const protocol = String(request.headers["sec-websocket-protocol"] || "");
         const origin = String(request.headers.origin || "");
         let role = "";
-        if (url.pathname === "/extension" && protocol === `mbm.${this.token}` && origin.startsWith("chrome-extension://")) role = "extension";
+        if (url.pathname === "/extension" && protocol === `mbm.${this.token}` && isAllowedExtensionOrigin(origin)) role = "extension";
         if (url.pathname === "/runtime" && protocol === `mbm-runtime.${this.token}` && !origin) role = "runtime";
         if (!role) {
           socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
@@ -368,12 +424,15 @@ export class BrowserBridgeManager {
         }
         const message = parsed.message;
         if (!settled) {
-          if (message.type !== "hello" || message.role !== "runtime") {
+          if (message.type !== "hello" || message.role !== "runtime" || message.protocol !== 1) {
             closeProtocolSocket(ws, 1002, "runtime hello required");
             return;
           }
           this.upstream = ws;
-          this.proxyExtensionConnected = message.extension_connected === true;
+          const claimedExtension = message.extension_connected === true;
+          this.proxyExtensionInfo = claimedExtension ? normalizeCompatibleExtensionInfo(message.extension_info) : null;
+          this.proxyExtensionConnected = claimedExtension && Boolean(this.proxyExtensionInfo);
+          this.proxyExtensionReloadRequired = message.extension_reload_required === true || (claimedExtension && !this.proxyExtensionInfo);
           finish(true);
           return;
         }
@@ -384,6 +443,8 @@ export class BrowserBridgeManager {
         if (this.upstream === ws) {
           this.upstream = null;
           this.proxyExtensionConnected = false;
+          this.proxyExtensionInfo = null;
+          this.proxyExtensionReloadRequired = false;
           this.rejectPending("browser broker disconnected");
           if (settled) this.scheduleBrokerRecovery();
         }
@@ -406,37 +467,93 @@ export class BrowserBridgeManager {
         }
       });
       ws.on("error", () => {});
-      safeSocketSend(ws, { type: "hello", role: "runtime", protocol: 1, extension_connected: this.socket?.readyState === 1 });
+      safeSocketSend(ws, {
+        type: "hello", role: "runtime", protocol: 1,
+        extension_connected: this.extensionConnected(),
+        extension_info: this.extensionStatusInfo(),
+        extension_reload_required: this.extensionReloadRequired(),
+      });
       return;
     }
-    if (this.socket && this.socket.readyState === 1) this.socket.close(4001, "superseded");
-    this.socket = ws;
+    if (this.pendingExtensionSocket && this.pendingExtensionSocket.readyState === 1) {
+      this.pendingExtensionSocket.close(4001, "superseded by a newer extension candidate");
+    }
+    this.pendingExtensionSocket = ws;
+    this.broadcastRuntimeStatus(this.extensionConnected());
+    ws.extensionReady = false;
+    ws.handshakeTimer = setTimeout(() => {
+      this.markExtensionReloadRequired();
+      closeProtocolSocket(ws, 1002, "extension hello required; reload the extension");
+    }, EXTENSION_HANDSHAKE_MS);
+    ws.handshakeTimer.unref?.();
     ws.on("message", (data) => this.handleExtensionMessage(ws, data));
     ws.on("close", () => {
+      clearTimeout(ws.handshakeTimer);
+      if (this.pendingExtensionSocket === ws) {
+        this.pendingExtensionSocket = null;
+        this.broadcastRuntimeStatus(this.extensionConnected());
+        return;
+      }
       if (this.socket !== ws) return;
       this.socket = null;
+      this.extensionInfo = null;
       this.rejectPending("browser extension disconnected");
-      for (const [id, route] of this.proxyRoutes) {
-        clearTimeout(route.timeout);
-        try { route.socket.send(JSON.stringify({ type: "response", id: route.id, ok: false, error: "browser extension disconnected" })); } catch {}
-        this.proxyRoutes.delete(id);
-      }
+      this.rejectProxyRoutes("browser extension disconnected");
       this.broadcastRuntimeStatus(false);
     });
     ws.on("error", () => {});
-    safeSocketSend(ws, { type: "hello", role: "extension", protocol: 1 });
-    this.broadcastRuntimeStatus(true);
+    safeSocketSend(ws, { type: "hello", role: "extension", protocol: BROWSER_EXTENSION_PROTOCOL });
   }
 
   handleExtensionMessage(socket, data) {
-    if (this.socket !== socket) return;
+    if (this.socket !== socket && this.pendingExtensionSocket !== socket) return;
     const parsed = parseBrowserSocketMessage(data);
     if (!parsed.ok) {
+      this.markExtensionReloadRequired();
       closeProtocolSocket(socket, parsed.code, parsed.reason);
       return;
     }
     const message = parsed.message;
+    if (message.type === "hello") {
+      if (socket.extensionReady) {
+        this.markExtensionReloadRequired();
+        closeProtocolSocket(socket, 1002, "duplicate extension hello");
+        return;
+      }
+      let info;
+      try { info = parseExtensionHello(message); }
+      catch (error) {
+        this.markExtensionReloadRequired();
+        closeProtocolSocket(socket, 1002, String(error?.message || error).slice(0, 120));
+        return;
+      }
+      clearTimeout(socket.handshakeTimer);
+      if (!safeSocketSend(socket, { type: "hello_ack", role: "extension", protocol: BROWSER_EXTENSION_PROTOCOL })) {
+        closeProtocolSocket(socket, 1011, "extension acknowledgement failed");
+        return;
+      }
+      this.extensionReloadRequiredFlag = false;
+      socket.extensionReady = true;
+      if (this.pendingExtensionSocket === socket) this.pendingExtensionSocket = null;
+      const previous = this.socket;
+      this.socket = socket;
+      this.extensionInfo = info;
+      if (previous && previous !== socket) {
+        this.rejectPending("browser extension was replaced; retry the browser request");
+        this.rejectProxyRoutes("browser extension was replaced; retry the browser request");
+        if (previous.readyState === 1) previous.close(4001, "superseded");
+      }
+      this.broadcastRuntimeStatus(true);
+      return;
+    }
+    if (!socket.extensionReady) {
+      this.markExtensionReloadRequired();
+      closeProtocolSocket(socket, 1002, "extension hello required; reload the extension");
+      return;
+    }
+    if (message.type === "ping") return;
     if (message.type !== "response" || typeof message.id !== "string") {
+      this.markExtensionReloadRequired();
       closeProtocolSocket(socket, 1002, "invalid extension protocol message");
       return;
     }
@@ -476,7 +593,7 @@ export class BrowserBridgeManager {
       closeProtocolSocket(socket, 1002, "invalid runtime protocol message");
       return;
     }
-    if (!this.socket || this.socket.readyState !== 1) {
+    if (!this.extensionConnected()) {
       safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension is not connected" });
       return;
     }
@@ -511,7 +628,10 @@ export class BrowserBridgeManager {
 
   handleUpstreamMessage(message) {
     if (message.type === "status" && typeof message.extension_connected === "boolean") {
-      this.proxyExtensionConnected = message.extension_connected;
+      const claimedExtension = message.extension_connected === true;
+      this.proxyExtensionInfo = claimedExtension ? normalizeCompatibleExtensionInfo(message.extension_info) : null;
+      this.proxyExtensionConnected = claimedExtension && Boolean(this.proxyExtensionInfo);
+      this.proxyExtensionReloadRequired = message.extension_reload_required === true || (claimedExtension && !this.proxyExtensionInfo);
       if (!this.proxyExtensionConnected) this.rejectPending("browser extension disconnected");
       return true;
     }
@@ -526,7 +646,11 @@ export class BrowserBridgeManager {
   }
 
   broadcastRuntimeStatus(connected) {
-    const message = { type: "status", extension_connected: connected };
+    const message = {
+      type: "status", extension_connected: connected,
+      extension_info: connected ? this.extensionStatusInfo() : null,
+      extension_reload_required: this.extensionReloadRequired(),
+    };
     for (const client of this.runtimeClients) safeSocketSend(client, message);
   }
 
@@ -552,7 +676,21 @@ export class BrowserBridgeManager {
       return;
     }
     if (url.pathname === "/healthz") {
-      sendJson(response, { ok: true, connected: this.socket?.readyState === 1, broker: "machine-bridge-browser" });
+      const extension = this.extensionStatusInfo();
+      sendJson(response, {
+        ok: true,
+        connected: this.extensionConnected(),
+        broker: "machine-bridge-browser",
+        expected_extension_version: EXPECTED_EXTENSION_VERSION,
+        extension_protocol: extension?.protocol || null,
+        extension_version: extension?.version || "",
+        extension_capabilities: extension?.capabilities || [],
+        extension_reload_required: this.extensionReloadRequired(),
+        controls_existing_profile: true,
+        controls_extension_profile: true,
+        machine_bridge_launches_browser: false,
+        profile_identity_verifiable: false,
+      });
       return;
     }
     if (url.pathname === "/pair") {
@@ -585,6 +723,14 @@ export class BrowserBridgeManager {
     this.pending.clear();
   }
 
+  rejectProxyRoutes(message) {
+    for (const [id, route] of this.proxyRoutes) {
+      clearTimeout(route.timeout);
+      safeSocketSend(route.socket, { type: "response", id: route.id, ok: false, error: message });
+      this.proxyRoutes.delete(id);
+    }
+  }
+
   stop() {
     this.stopping = true;
     clearTimeout(this.recoveryTimer);
@@ -592,9 +738,16 @@ export class BrowserBridgeManager {
     this.rejectPending("browser bridge stopped");
     try { this.upstream?.close(1001, "runtime stopped"); } catch {}
     try { this.socket?.close(1001, "runtime stopped"); } catch {}
+    try { this.pendingExtensionSocket?.close(1001, "runtime stopped"); } catch {}
     for (const client of this.runtimeClients) try { client.close(1001, "runtime stopped"); } catch {}
     this.upstream = null;
     this.socket = null;
+    this.pendingExtensionSocket = null;
+    this.extensionInfo = null;
+    this.proxyExtensionConnected = false;
+    this.proxyExtensionInfo = null;
+    this.proxyExtensionReloadRequired = false;
+    this.extensionReloadRequiredFlag = false;
     this.runtimeClients.clear();
     for (const route of this.proxyRoutes.values()) clearTimeout(route.timeout);
     this.proxyRoutes.clear();
@@ -604,6 +757,27 @@ export class BrowserBridgeManager {
     this.server = null;
   }
 
+  markExtensionReloadRequired() {
+    this.extensionReloadRequiredFlag = true;
+    this.broadcastRuntimeStatus(this.extensionConnected());
+  }
+
+  extensionConnected() {
+    return this.server
+      ? this.socket?.readyState === 1 && Boolean(this.extensionInfo)
+      : this.upstream?.readyState === 1 && this.proxyExtensionConnected && Boolean(this.proxyExtensionInfo);
+  }
+
+  extensionStatusInfo() {
+    return this.server ? this.extensionInfo : this.proxyExtensionInfo;
+  }
+
+  extensionReloadRequired() {
+    return this.server
+      ? this.extensionReloadRequiredFlag || (this.pendingExtensionSocket?.readyState === 1 && !this.extensionConnected())
+      : this.proxyExtensionReloadRequired;
+  }
+
   assertFull(tool) {
     if (this.policy.profile !== "full" || this.policy.execMode !== "shell" || this.policy.unrestrictedPaths !== true) {
       throw new Error(`${tool} requires the canonical full profile`);
@@ -611,6 +785,36 @@ export class BrowserBridgeManager {
   }
 }
 
+function normalizeCompatibleExtensionInfo(value) {
+  const info = normalizeExtensionInfo(value);
+  if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL || info.version !== EXPECTED_EXTENSION_VERSION) return null;
+  if (REQUIRED_EXTENSION_CAPABILITIES.some((capability) => !info.capabilities.includes(capability))) return null;
+  return info;
+}
+
+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`);
+  }
+  const info = normalizeExtensionInfo(message);
+  if (!info) throw new Error("invalid extension hello; reload the extension");
+  if (info.version !== EXPECTED_EXTENSION_VERSION) throw new Error(`extension version mismatch; expected ${EXPECTED_EXTENSION_VERSION}; reload the extension`);
+  const missing = REQUIRED_EXTENSION_CAPABILITIES.filter((capability) => !info.capabilities.includes(capability));
+  if (missing.length) throw new Error(`extension capability mismatch; reload the extension (${missing.join(",")})`);
+  return info;
+}
+
+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)
+    : [];
+  if (!Number.isInteger(protocol) || protocol < 1 || !version) return null;
+  return { protocol, version, capabilities };
+}
+
 async function loadOrCreatePairing(stateRoot) {
   if (!stateRoot) return { token: randomBytes(32).toString("base64url"), port: DEFAULT_PORT };
   assertStateMaintenanceAvailable(stateRoot);
@@ -648,7 +852,20 @@ async function savePairing(stateRoot, value) {
 }
 
 function pairingHtml(port, token) {
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="machine-bridge-browser-pair" content="1"><meta name="machine-bridge-browser-port" content="${port}"><meta name="machine-bridge-browser-token" content="${token}"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Machine Bridge browser pairing</title></head><body><h1>Machine Bridge browser pairing</h1><p>The installed extension reads pairing material from this loopback-only page and stores it in browser-local extension storage. It is not sent to any website.</p><p id="status">Waiting for the Machine Bridge extension.</p></body></html>`;
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="machine-bridge-browser-pair" content="1"><meta name="machine-bridge-browser-port" content="${port}"><meta name="machine-bridge-browser-token" content="${token}"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Machine Bridge browser pairing</title></head><body><h1>Machine Bridge browser pairing</h1><p>Expected extension build: <strong>${EXPECTED_EXTENSION_VERSION}</strong>. Reload the unpacked extension after every Machine Bridge upgrade.</p><p>The installed extension reads pairing material from this loopback-only page and stores it in browser-local extension storage. It is not sent to any website.</p><p id="status">Waiting for the Machine Bridge extension.</p></body></html>`;
+}
+
+function isAllowedExtensionOrigin(origin) {
+  let parsed;
+  try { parsed = new URL(String(origin || "")); } catch { return false; }
+  return parsed.protocol === "chrome-extension:"
+    && /^[a-p]{32}$/.test(parsed.hostname)
+    && !parsed.username
+    && !parsed.password
+    && !parsed.port
+    && (parsed.pathname === "" || parsed.pathname === "/")
+    && !parsed.search
+    && !parsed.hash;
 }
 
 function isAllowedLoopbackHost(host, port) {
@@ -697,42 +914,6 @@ function sendJson(response, value) {
   response.end(`${JSON.stringify(value)}\n`);
 }
 
-function normalizeBrowserAction(value) {
-  const action = String(value || "").trim();
-  if (!["navigate", "click", "fill", "select", "check", "uncheck", "focus", "press", "submit", "reload", "back", "forward"].includes(action)) {
-    throw new Error("unsupported browser action");
-  }
-  return action;
-}
-
-function normalizeFormAction(value) {
-  const action = String(value || "").trim();
-  if (!["fill", "select", "check", "uncheck", "click"].includes(action)) throw new Error("unsupported form field action");
-  return action;
-}
-
-function normalizeBrowserSelector(value, action) {
-  if (["navigate", "reload", "back", "forward"].includes(action)) return null;
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("selector must be an object");
-  const allowed = new Set(["css", "id", "name", "label", "text", "role", "placeholder", "index"]);
-  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`unknown selector field: ${key}`);
-  const output = {};
-  for (const key of ["css", "id", "name", "label", "text", "role", "placeholder"]) {
-    if (value[key] !== undefined) output[key] = optionalString(value[key], `selector.${key}`, 2000);
-  }
-  if (value.index !== undefined) output.index = optionalInteger(value.index, "selector.index", 0, 10000);
-  if (!Object.keys(output).length) throw new Error("selector requires at least one field");
-  return output;
-}
-
-function validateNavigationUrl(value) {
-  if (!value) throw new Error("navigate requires url");
-  let parsed;
-  try { parsed = new URL(value); } catch { throw new Error("url must be an absolute URL"); }
-  if (!["http:", "https:", "file:"].includes(parsed.protocol)) throw new Error("url protocol must be http, https, or file");
-  return parsed.href;
-}
-
 function normalizeUploadFilename(value, { derived = false } = {}) {
   let name = String(value || "");
   if (derived) name = name.replace(/[\u0000-\u001f\u007f/\\]+/g, "_").trim();
@@ -760,13 +941,6 @@ function optionalStringArray(value, label, maxItems, maxLength) {
   });
 }
 
-function normalizeWait(value) {
-  if (value === undefined || value === null || value === "") return "none";
-  const wait = String(value);
-  if (!["none", "domcontentloaded", "complete"].includes(wait)) throw new Error("wait_for must be none, domcontentloaded, or complete");
-  return wait;
-}
-
 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`);
@@ -778,23 +952,3 @@ function validateResource(value) {
   if (!RESOURCE_NAME.test(name)) throw new Error("value_resource is invalid");
   return name;
 }
-
-function optionalString(value, label, maxLength) {
-  if (value === undefined || value === null || value === "") return "";
-  if (typeof value !== "string" || value.includes("\0") || value.length > maxLength) throw new Error(`${label} must be a string of at most ${maxLength} characters without NUL bytes`);
-  return value;
-}
-
-function optionalInteger(value, label, min, max) {
-  if (value === undefined || value === null || value === "") return null;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
-  return number;
-}
-
-function clampInt(value, fallback, min, max) {
-  if (value === undefined || value === null || value === "") return fallback;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`expected an integer from ${min} to ${max}`);
-  return number;
-}