machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/browser-operation-service.mjs

@@ -1,51 +1,72 @@
 import {
-  clampInt, normalizeBrowserAction, normalizeBrowserSelector, normalizeBrowserWait, normalizeFormAction,
-  normalizeInputMode, normalizeNavigationWait, normalizeTabCommand, optionalInteger, optionalString,
+  browserPairingLaunchUnavailable, browserPairingLaunchUnknown, clampInt, normalizeBrowserAction, normalizeBrowserSelector, normalizeBrowserWait,
+  normalizeBrowserSnapshotIdentity, normalizeImageFormat, normalizeInputMode, normalizeNavigationWait, normalizeTabCommand, optionalBoolean, optionalInteger, optionalString,
   validateNavigationUrl,
 } from "./browser-command.mjs";
-
+import { BrowserComputerObservationService } from "./browser-computer-observation-service.mjs";
+import { BrowserTrustedInputHealth, TRUSTED_INPUT_QUARANTINE_FALLBACK } from "./browser-trusted-input-health.mjs";
+import {
+  boundedBrowserValue, normalizeMimeType, normalizeUploadFilename, optionalStringArray, prepareBrowserFormField,
+  resolveBrowserActionValue, validateBrowserResource,
+} from "./browser-resource-input.mjs";
 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}$/;
-
 export class BrowserOperationService {
   constructor({
     authorizeTool,
     ensureStarted,
     request,
     bridgeStatus,
+    createPairingLaunch,
     extensionPath,
     expectedExtensionVersion,
+    expectedExtensionId,
     runProcess,
     readResourceText,
     readResourceBinary,
+    throwIfCancelled = () => {},
+    logger = null,
   }) {
     this.authorizeTool = authorizeTool;
     this.ensureStarted = ensureStarted;
     this.request = request;
     this.bridgeStatus = bridgeStatus;
+    this.createPairingLaunch = createPairingLaunch;
     this.extensionPath = extensionPath;
     this.expectedExtensionVersion = expectedExtensionVersion;
+    this.expectedExtensionId = expectedExtensionId;
     this.runProcess = runProcess;
     this.readResourceText = readResourceText;
     this.readResourceBinary = readResourceBinary;
+    this.throwIfCancelled = throwIfCancelled;
+    this.trustedInputHealth = new BrowserTrustedInputHealth({ logger });
+    this.computerObservation = new BrowserComputerObservationService({
+      authorizeTool: (tool) => this.authorizeTool(tool),
+      request: (...args) => this.requestComputerObservation(...args),
+      bridgeStatus: () => this.bridgeStatus(),
+      inspectPage: (args, context) => this.inspectPage(args, context),
+      screenshot: (args, context) => this.screenshot(args, context),
+    });
   }
-
   async status(context = {}) {
     this.authorizeTool("browser_status");
     await this.ensureStarted(context);
     const bridge = this.bridgeStatus();
     const extension = bridge.extensionInfo;
+    const trustedHealth = this.trustedInputHealth.status(bridge);
     return {
       available: true,
       connected: bridge.extensionConnected,
       broker_role: bridge.brokerRole,
+      runtime_clients: Number(bridge.runtime_clients) || 0,
+      routed_requests: Number(bridge.routed_requests) || 0,
       endpoint: `ws://127.0.0.1:${bridge.port}/extension`,
       pairing_url: `http://127.0.0.1:${bridge.port}/pair`,
       extension_path: this.extensionPath,
       expected_extension_version: this.expectedExtensionVersion,
+      expected_extension_id: this.expectedExtensionId,
+      extension_id: extension?.extension_id || "",
       extension_protocol: extension?.protocol || null,
       extension_version: extension?.version || "",
       extension_capabilities: extension?.capabilities || [],
@@ -60,53 +81,71 @@ export class BrowserOperationService {
       source_access: true,
       semantic_snapshot_refs: true,
       actionability_waits: true,
-      trusted_input: true,
+      trusted_input: trustedHealth.available,
+      trusted_input_quarantined: trustedHealth.quarantined,
+      trusted_input_health: !bridge.extensionConnected ? "disconnected" : trustedHealth.quarantined ? "quarantined" : trustedHealth.supported ? "ready" : "unsupported",
       input_modes: ["auto", "trusted", "dom"],
       complex_form_fill: true,
       tab_management: true,
       explicit_waits: true,
       screenshots: true,
+      computer_observation_v1: extension?.capabilities?.includes("computer_observation_v1") === true,
+      cdp_accessibility_snapshot: extension?.capabilities?.includes("cdp_accessibility_snapshot") === true,
+      cdp_surface_screenshot: extension?.capabilities?.includes("cdp_surface_screenshot") === true,
+      backend_node_trusted_input: extension?.capabilities?.includes("backend_node_trusted_input") === true && !trustedHealth.quarantined,
       restricted_pages: ["browser-internal pages", "extension stores", "some PDF/plugin viewers", "pages blocked by enterprise policy"],
       security: {
         loopback_only: true,
-        bearer_pairing_token: true,
+        bearer_pairing_token: false,
+        short_lived_pairing_grant: true,
+        ephemeral_pairing_listener: true,
+        one_time_hmac_socket_auth: true,
+        long_lived_tokens_on_wire: false,
+        pinned_extension_identity: true,
         arbitrary_extension_code_from_mcp: false,
         resource_values_returned_to_model: false,
       },
     };
   }
-
   async pair(args = {}, context = {}) {
     this.authorizeTool("pair_browser_extension");
     const status = await this.status(context);
-    if (args.open !== false) {
+    const open = optionalBoolean(args.open, "open", true);
+    if (open) {
+      const launch = await this.createPairingLaunch(this.bridgeStatus().port);
       const command = process.platform === "darwin"
-        ? { cmd: "open", argv: [status.pairing_url] }
+        ? { cmd: "open", argv: [launch.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);
+          ? { cmd: "cmd.exe", argv: ["/d", "/s", "/c", "start", "", launch.url] }
+          : { cmd: "xdg-open", argv: [launch.url] };
+      this.throwIfCancelled(context);
+      try {
+        await this.runProcess(command.cmd, command.argv, 30_000, false, 128 * 1024, context, undefined, null, { nonReplayableMutation: true });
+      } catch (error) {
+        launch.close();
+        if (error?.details?.reason === "process_outcome_unknown_after_spawn") throw browserPairingLaunchUnknown();
+        if (error?.details?.reason === "process_failed_before_spawn") throw browserPairingLaunchUnavailable();
+        throw error;
+      }
     }
     return {
       ...status,
-      opened_pairing_page: args.open !== false,
+      opened_pairing_page: open,
       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.",
+        "Run pair_browser_extension with opening enabled; the sanitized pairing_url alone contains no pairing grant.",
+        "After upgrades, reload the same unpacked extension path and accept any newly requested browser permission; older local-candidate installs may need one Load unpacked migration to the current stable extension_path.",
       ],
     };
   }
-
   async listTabs(args = {}, context = {}) {
     this.authorizeTool("browser_list_tabs");
     return this.request("list_tabs", {
-      currentWindow: args.current_window === true,
-      includePinned: args.include_pinned !== false,
+      currentWindow: optionalBoolean(args.current_window, "current_window", false),
+      includePinned: optionalBoolean(args.include_pinned, "include_pinned", true),
     }, clampInt(args.timeout_seconds, 30, 1, 120), 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);
@@ -124,7 +163,7 @@ export class BrowserOperationService {
     return 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,
+      allFrames: optionalBoolean(args.all_frames, "all_frames", false),
       maxBytes: clampInt(args.max_bytes, 1024 * 1024, 1, MAX_SOURCE_BYTES),
     }, clampInt(args.timeout_seconds, 30, 1, 120), context);
   }
@@ -134,15 +173,36 @@ export class BrowserOperationService {
     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,
+      allFrames: optionalBoolean(args.all_frames, "all_frames", true),
       maxElements: clampInt(args.max_elements, 300, 1, 1000),
-      includeValues: args.include_values === true,
+      includeValues: optionalBoolean(args.include_values, "include_values", false),
+      focusQuery: optionalString(args.focus_query, "focus_query", 1000),
     }, clampInt(args.timeout_seconds, 30, 1, 120), context);
   }
 
+  documentState(args = {}, context = {}) { return this.computerObservation.documentState(args, context); }
+  observeComputer(args = {}, context = {}) { return this.computerObservation.observe(args, context); }
+  pointAction(args = {}, context = {}) { return this.computerObservation.pointAction(args, context); }
+  async backendNodeAction(args = {}, context = {}) {
+    const action = args.action;
+    if (typeof action !== "string" || !["click", "double_click", "hover", "drag", "scroll", "press", "type_text", "fill", "check", "uncheck", "submit"].includes(action)) throw new Error("snapshot backend action must be click, double_click, hover, drag, scroll, press, type_text, fill, check, uncheck, or submit");
+    if (!["fill", "type_text"].includes(action) && (args.value !== undefined || args.value_resource !== undefined)) throw new Error(`value and value_resource are not valid for snapshot backend ${action}`);
+    if (action !== "press" && args.key !== undefined) throw new Error(`key is not valid for snapshot backend ${action}`);
+    this.computerObservation.preflightBackendNodeAction(args);
+    this.trustedInputHealth.assertTrustedAvailable(this.bridgeStatus());
+    const resolved = await resolveBrowserActionValue(args, this.readResourceText);
+    return this.computerObservation.backendNodeAction({ ...args, value: resolved.value ?? undefined }, context);
+  }
   async act(args = {}, context = {}) {
     this.authorizeTool("browser_action");
     const action = normalizeBrowserAction(args.action);
+    const valueActions = new Set(["fill", "type_text", "select"]);
+    if (!valueActions.has(action) && (args.value !== undefined || args.value_resource !== undefined)) {
+      throw new Error(`value and value_resource are not valid for browser action ${action}`);
+    }
+    if (valueActions.has(action) && args.value === undefined && args.value_resource === undefined) {
+      throw new Error(`browser action ${action} requires value or value_resource`);
+    }
     const rawUrl = optionalString(args.url, "url", 32768);
     const payload = {
       tabId: optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER),
@@ -155,70 +215,83 @@ export class BrowserOperationService {
       waitFor: normalizeNavigationWait(args.wait_for),
       inputMode: normalizeInputMode(args.input_mode),
       elementTimeoutMs: clampInt(args.element_timeout_seconds, 10, 1, 60) * 1000,
+      expectedIdentity: normalizeBrowserSnapshotIdentity(args.expected_ref_identity),
+      expectedTabUrl: optionalString(args.expected_tab_url, "expected_tab_url", 32768),
+      expectedDocumentEpoch: optionalString(args.expected_document_epoch, "expected_document_epoch", 9000), expectedHistoryEntryKey: optionalString(args.expected_history_entry_key, "expected_history_entry_key", 512),
     };
+    if (!["navigate", "reload", "back", "forward"].includes(action) && payload.expectedTabUrl) throw new Error("expected_tab_url is only valid for snapshot-bound navigation actions");
+    if (!["reload", "back", "forward"].includes(action) && payload.expectedDocumentEpoch) throw new Error("expected_document_epoch is only valid for snapshot-bound reload, back, or forward");
+    if (!["reload", "back", "forward"].includes(action) && payload.expectedHistoryEntryKey) throw new Error("expected_history_entry_key is only valid for snapshot-bound reload, back, or forward");
     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");
-    }
+    const trustedDecision = this.trustedInputHealth.pageInputMode({ inputMode: payload.inputMode, action, bridge: this.bridgeStatus() });
+    payload.inputMode = trustedDecision.inputMode;
+    const resolvedValue = await resolveBrowserActionValue(args, this.readResourceText);
+    payload.value = resolvedValue.value;
     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);
+    let response;
+    try {
+      response = await this.request("action", payload, clampInt(args.timeout_seconds, defaultTimeout, 1, 120), context);
+    } catch (error) {
+      this.trustedInputHealth.noteAmbiguousFailure(error, this.bridgeStatus());
+      throw error;
+    }
     return {
       ...response,
-      value_source: args.value_resource !== undefined ? "local-resource" : payload.value === null ? "none" : "mcp-argument",
+      ...(trustedDecision.fallback ? {
+        input_mode: "dom",
+        trusted_input_fallback: true,
+        fallback_reason: TRUSTED_INPUT_QUARANTINE_FALLBACK,
+      } : {}),
+      value_source: resolvedValue.source,
       value_exposed: false,
     };
   }
 
+  async requestComputerObservation(method, params, timeoutSeconds, context) {
+    const trustedMethod = method === "point_action" || method === "backend_node_action";
+    if (trustedMethod) this.trustedInputHealth.assertTrustedAvailable(this.bridgeStatus());
+    try {
+      return await this.request(method, params, timeoutSeconds, context);
+    } catch (error) {
+      if (trustedMethod) this.trustedInputHealth.noteAmbiguousFailure(error, this.bridgeStatus());
+      throw error;
+    }
+  }
+
   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 tabId = optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER);
+    const frameId = optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER);
+    const submit = optionalBoolean(args.submit, "submit", false);
+    const submitSelector = args.submit_selector === undefined ? null : normalizeBrowserSelector(args.submit_selector, "click");
+    const waitFor = normalizeNavigationWait(args.wait_for);
+    const elementTimeoutSeconds = clampInt(args.element_timeout_seconds, 10, 1, 60);
+    const timeoutSeconds = clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180);
+    const prepared = args.fields.map((input, index) => prepareBrowserFormField(input, index));
     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`);
-      }
+    for (const field of prepared) {
+      let value = field.value;
+      if (field.resourceName) value = boundedBrowserValue(await this.readResourceText(field.resourceName), `fields[${field.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,
-      });
+      fields.push({ selector: field.selector, value, action: field.action, sensitive: field.sensitive || Boolean(field.resourceName) });
     }
-    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);
+      tabId, frameId, fields, submit, submitSelector, waitFor, elementTimeoutMs: elementTimeoutSeconds * 1000,
+    }, timeoutSeconds, context);
   }
 
   async uploadFiles(args = {}, context = {}) {
@@ -226,15 +299,20 @@ export class BrowserOperationService {
     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 tabId = optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER);
+    const frameId = optionalInteger(args.frame_id, "frame_id", 0, Number.MAX_SAFE_INTEGER);
+    const selector = normalizeBrowserSelector(args.selector, "fill");
+    const elementTimeoutSeconds = clampInt(args.element_timeout_seconds, 10, 1, 60);
+    const timeoutSeconds = clampInt(args.timeout_seconds, Math.max(60, elementTimeoutSeconds + 5), 1, 180);
+    const resourceNames = args.resources.map(validateBrowserResource);
     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) {
+    if (filenames.length > resourceNames.length || mimeTypes.length > resourceNames.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);
+    for (const name of resourceNames) {
       const resource = this.readResourceBinary(name);
       total += resource.buffer.length;
       if (total > 5 * 1024 * 1024) throw new Error("browser upload resources exceed 5 MiB total");
@@ -246,25 +324,20 @@ export class BrowserOperationService {
         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 };
+      tabId, frameId, selector, files, elementTimeoutMs: elementTimeoutSeconds * 1000,
+    }, timeoutSeconds, context);
+    return { ...result, resource_names: resourceNames, resource_contents_exposed: false };
   }
 
   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",
+      format: normalizeImageFormat(args.format, "format"),
       quality: clampInt(args.quality, 90, 1, 100),
     }, clampInt(args.timeout_seconds, 30, 1, 120), context);
-    const data = String(result.data || "");
+    const data = typeof result.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 {
@@ -273,53 +346,10 @@ export class BrowserOperationService {
         structuredContent: {
           tab_id: result.tab_id,
           url: result.url,
-          title: result.title,
+          title: result.title, tab_metadata_verified: result.tab_metadata_verified === true,
           mime_type: match[1],
         },
       },
     };
   }
 }
-
-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-pairing-grant.mjs

@@ -0,0 +1,109 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { createBrokerAuthChallenge } from "./browser-broker-auth.mjs";
+
+const GRANT = /^(\d{13})\.([A-Za-z0-9_-]{22})\.([A-Za-z0-9_-]{43})$/;
+const GRANT_ID = /^(\d{13})\.([A-Za-z0-9_-]{22})$/;
+const CHALLENGE = /^[A-Za-z0-9_-]{32}$/;
+const PROOF = /^[A-Za-z0-9_-]{43}$/;
+const TOKEN = /^[A-Za-z0-9_-]{32,100}$/;
+const PAIRING_GRANT_TTL_MS = 30_000;
+const EXCHANGE_TTL_MS = 5_000;
+const MAX_PENDING = 32;
+
+export function createBrowserPairingGrant(extensionToken, port, now = Date.now()) {
+  assertToken(extensionToken);
+  const expiresAt = Number(now) + PAIRING_GRANT_TTL_MS;
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0) throw new Error("browser pairing grant time is invalid");
+  const nonce = randomBytes(16).toString("base64url");
+  const proof = grantSecret(extensionToken, port, expiresAt, nonce);
+  return `${expiresAt}.${nonce}.${proof}`;
+}
+
+export function parseBrowserPairingGrant(grant, now = Date.now()) {
+  const match = GRANT.exec(String(grant || ""));
+  if (!match) return null;
+  const expiresAt = Number(match[1]);
+  const current = Number(now);
+  if (!Number.isFinite(current) || expiresAt < current || expiresAt - current > PAIRING_GRANT_TTL_MS) return null;
+  return { id: `${match[1]}.${match[2]}`, secret: match[3], expiresAt };
+}
+
+export function createPairingBootstrapRegistry(extensionToken, port, options = {}) {
+  assertToken(extensionToken);
+  const wallNow = typeof options.wallNow === "function" ? options.wallNow : Date.now;
+  const monotonicNow = typeof options.monotonicNow === "function" ? options.monotonicNow : undefined;
+  const pending = new Map();
+  const used = new Map();
+  return {
+    issue(grantId, clientChallenge, initProof) {
+      prune(used, pending, wallNow());
+      const grant = grantFromId(extensionToken, port, grantId, wallNow());
+      if (!grant || used.has(grant.id) || !CHALLENGE.test(String(clientChallenge || "")) || !PROOF.test(String(initProof || ""))) return null;
+      if (!safeEqual(bootstrapInitProof(grant.secret, grant.id, clientChallenge), initProof)) return null;
+      const existing = pending.get(grant.id);
+      if (existing && !existing.deadline.expired()) return existing.clientChallenge === clientChallenge ? { serverNonce: existing.serverNonce, serverProof: bootstrapProof(grant.secret, "server", grant.id, clientChallenge, existing.serverNonce) } : null;
+      if (used.size + pending.size >= MAX_PENDING) return null;
+      const serverNonce = createBrokerAuthChallenge();
+      pending.set(grant.id, { clientChallenge, serverNonce, deadline: createMonotonicDeadline(EXCHANGE_TTL_MS, monotonicNow) });
+      return { serverNonce, serverProof: bootstrapProof(grant.secret, "server", grant.id, clientChallenge, serverNonce) };
+    },
+    consume(grantId, clientChallenge, serverNonce, clientProof) {
+      prune(used, pending, wallNow());
+      const grant = grantFromId(extensionToken, port, grantId, wallNow());
+      if (!grant || used.has(grant.id) || !PROOF.test(String(clientProof || ""))) return false;
+      const current = pending.get(grant.id);
+      pending.delete(grant.id);
+      if (!current || current.deadline.expired()
+          || current.clientChallenge !== clientChallenge || current.serverNonce !== serverNonce) return false;
+      const expected = bootstrapProof(grant.secret, "client", grant.id, clientChallenge, serverNonce);
+      if (!safeEqual(expected, clientProof)) return false;
+      used.set(grant.id, grant.expiresAt);
+      return true;
+    },
+  };
+}
+
+export function createPairingBootstrapInitProof(grantSecret, grantId, clientChallenge) {
+  if (!PROOF.test(String(grantSecret || "")) || !GRANT_ID.test(String(grantId || "")) || !CHALLENGE.test(String(clientChallenge || ""))) throw new Error("browser pairing bootstrap init proof input is invalid");
+  return bootstrapInitProof(grantSecret, grantId, clientChallenge);
+}
+
+export function createPairingBootstrapProof(grantSecret, direction, grantId, clientChallenge, serverNonce) {
+  if (!PROOF.test(String(grantSecret || "")) || (direction !== "server" && direction !== "client")
+      || !GRANT_ID.test(String(grantId || "")) || !CHALLENGE.test(String(clientChallenge || ""))
+      || !CHALLENGE.test(String(serverNonce || ""))) {
+    throw new Error("browser pairing bootstrap proof input is invalid");
+  }
+  return bootstrapProof(grantSecret, direction, grantId, clientChallenge, serverNonce);
+}
+
+function grantFromId(token, port, grantId, now) {
+  const match = GRANT_ID.exec(String(grantId || ""));
+  if (!match) return null;
+  const expiresAt = Number(match[1]);
+  if (!Number.isFinite(now) || expiresAt < now || expiresAt - now > PAIRING_GRANT_TTL_MS) return null;
+  return { id: grantId, secret: grantSecret(token, port, expiresAt, match[2]), expiresAt };
+}
+
+function grantSecret(token, port, expiresAt, nonce) {
+  const normalizedPort = Number(port);
+  if (!Number.isInteger(normalizedPort) || normalizedPort < 1024 || normalizedPort > 65535) throw new Error("browser pairing grant port is invalid");
+  return hmac(token, `machine-bridge-browser-pair-v2\0${normalizedPort}\0${expiresAt}\0${nonce}`);
+}
+function bootstrapInitProof(secret, grantId, clientChallenge) {
+  return hmac(secret, `machine-bridge-browser-pair-init-v2\0${grantId}\0${clientChallenge}`);
+}
+function bootstrapProof(secret, direction, grantId, clientChallenge, serverNonce) {
+  return hmac(secret, `machine-bridge-browser-pair-${direction}-v2\0${grantId}\0${clientChallenge}\0${serverNonce}`);
+}
+function hmac(key, message) { return createHmac("sha256", key).update(message).digest("base64url"); }
+function assertToken(value) { if (!TOKEN.test(String(value || ""))) throw new Error("browser broker credential is invalid"); }
+function safeEqual(left, right) {
+  const a = Buffer.from(String(left)); const b = Buffer.from(String(right));
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function prune(used, pending, now) {
+  for (const [id, expiresAt] of used) if (expiresAt < now) used.delete(id);
+  for (const [id, entry] of pending) if (entry.deadline.expired()) pending.delete(id);
+}

package/src/local/browser-pairing-http.mjs

@@ -0,0 +1,36 @@
+import { EXPECTED_EXTENSION_ID, normalizeExtensionId } from "./browser-extension-identity.mjs";
+import { EXPECTED_EXTENSION_VERSION } from "./browser-extension-protocol.mjs";
+
+export function pairingHtml(port) {
+  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="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>.</p><p>Expected extension ID: <code>${EXPECTED_EXTENSION_ID}</code>.</p><p>Reload the unpacked extension after every Machine Bridge upgrade.</p><p>Pairing credentials are never embedded in this HTTP page. Run pair_browser_extension with opening enabled to create a short-lived extension bootstrap.</p><p id="status">Waiting for the Machine Bridge extension bootstrap.</p></body></html>`;
+}
+
+export function isAllowedExtensionOrigin(origin, expectedExtensionId = EXPECTED_EXTENSION_ID) {
+  const expected = normalizeExtensionId(expectedExtensionId);
+  if (!expected) return false;
+  let parsed;
+  try { parsed = new URL(String(origin || "")); } catch { return false; }
+  return parsed.protocol === "chrome-extension:" && parsed.hostname === expected
+    && !parsed.username && !parsed.password && !parsed.port
+    && (parsed.pathname === "" || parsed.pathname === "/") && !parsed.search && !parsed.hash;
+}
+
+export function isAllowedLoopbackHost(host, port) {
+  const normalized = String(host || "").toLowerCase();
+  return normalized === `127.0.0.1:${port}` || normalized === `localhost:${port}` || normalized === `[::1]:${port}`;
+}
+
+export function securityHeaders(contentType) {
+  return {
+    "content-type": contentType,
+    "cache-control": "no-store",
+    "content-security-policy": "default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+  };
+}
+
+export function sendJson(response, value) {
+  response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
+  response.end(`${JSON.stringify(value)}\n`);
+}

package/src/local/browser-pairing-launch.mjs

@@ -0,0 +1,58 @@
+import { createServer } from "node:http";
+import { pairingHtml, securityHeaders } from "./browser-pairing-http.mjs";
+import { createBrowserPairingGrant } from "./browser-pairing-grant.mjs";
+
+const LAUNCH_TTL_MS = 30_000;
+
+export async function startBrowserPairingLaunch({ brokerPort, extensionToken, timeoutMs = LAUNCH_TTL_MS } = {}) {
+  const targetPort = Number(brokerPort);
+  if (!Number.isInteger(targetPort) || targetPort < 1024 || targetPort > 65535) throw new Error("browser pairing broker port is invalid");
+  const grant = createBrowserPairingGrant(extensionToken, targetPort);
+  const ttl = Number(timeoutMs);
+  if (!Number.isInteger(ttl) || ttl < 1 || ttl > LAUNCH_TTL_MS) throw new Error("browser pairing launch timeout is invalid");
+
+  let listenerPort = 0;
+  let closed = false;
+  let timer;
+  let resolveClosed;
+  const closedPromise = new Promise((resolvePromise) => { resolveClosed = resolvePromise; });
+  const server = createServer((request, response) => {
+    const host = String(request.headers.host || "");
+    if (!listenerPort || host.toLowerCase() !== `127.0.0.1:${listenerPort}`) {
+      response.writeHead(403, securityHeaders("text/plain; charset=utf-8")).end("forbidden\n");
+      return;
+    }
+    let url;
+    try { url = new URL(request.url || "/", `http://${host}`); }
+    catch { response.writeHead(400, securityHeaders("text/plain; charset=utf-8")).end("bad request\n"); return; }
+    if (request.method !== "GET" || url.pathname !== "/pair" || url.search) {
+      response.writeHead(404, securityHeaders("text/plain; charset=utf-8")).end("not found\n");
+      return;
+    }
+    const html = pairingHtml(targetPort);
+    response.writeHead(200, { ...securityHeaders("text/html; charset=utf-8"), "content-length": Buffer.byteLength(html) });
+    response.end(html, () => close());
+  });
+
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    if (timer) clearTimeout(timer);
+    try { server.close(() => resolveClosed()); } catch { resolveClosed(); }
+  };
+  await new Promise((resolvePromise, rejectPromise) => {
+    const onError = (error) => { server.off("listening", onListening); rejectPromise(error); };
+    const onListening = () => { server.off("error", onError); resolvePromise(); };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(0, "127.0.0.1");
+  });
+  server.on("error", close);
+  const address = server.address();
+  if (!address || typeof address === "string") { close(); throw new Error("browser pairing launch listener address is unavailable"); }
+  listenerPort = address.port;
+  timer = setTimeout(close, ttl);
+  timer.unref?.();
+  const fragment = new URLSearchParams({ broker_port: String(targetPort), grant: String(grant) }).toString();
+  return { url: `http://127.0.0.1:${listenerPort}/pair#${fragment}`, close, closed: closedPromise, listenerPort, brokerPort: targetPort };
+}