machine-bridge-mcp 0.15.0 → 0.16.0

package/src/local/agent-context.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { commandMatchText, recommendTools, relevanceScore } from "./capability-ranking.mjs";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -24,36 +25,6 @@ const MAX_COMMANDS = 128;
 const MAX_COMMAND_ARGV = 128;
 const MAX_COMMAND_ARGUMENT_BYTES = 256 * 1024;
 const COMMAND_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
-const TOKEN_STOP_WORDS = new Set(["the", "and", "for", "with", "from", "this", "that", "use", "using", "into", "of", "to", "a", "an", "in", "on", "is", "are", "or", "及", "和", "的", "了", "在", "用", "使用", "进行", "根据"]);
-const ENGLISH_TOKEN_CANONICAL = new Map([
-  ["created", "create"], ["creating", "create"], ["creation", "create"], ["creator", "create"],
-  ["improved", "improve"], ["improving", "improve"], ["improvement", "improve"],
-  ["installed", "install"], ["installing", "install"], ["installation", "install"], ["installer", "install"],
-  ["searched", "search"], ["searching", "search"], ["finder", "find"],
-  ["documentation", "docs"], ["document", "docs"], ["documents", "docs"],
-  ["validated", "verify"], ["validate", "verify"], ["validation", "verify"], ["verification", "verify"],
-  ["factcheck", "verify"], ["fact-check", "verify"], ["testing", "test"], ["tests", "test"],
-  ["building", "build"], ["built", "build"], ["deployment", "deploy"], ["deployed", "deploy"],
-]);
-const HAN_TOKEN_ALIASES = Object.freeze([
-  [/创建|新建|编写/u, ["create", "creator"]],
-  [/改进|优化|更新|维护/u, ["improve", "update"]],
-  [/技能/u, ["skill"]],
-  [/安装/u, ["install", "installer"]],
-  [/部署/u, ["deploy", "deployment"]],
-  [/查找|搜索|检索/u, ["search", "find"]],
-  [/最新|当前/u, ["latest", "current"]],
-  [/官方/u, ["official"]],
-  [/文档|资料/u, ["docs", "documentation"]],
-  [/事实核查|核查|验证|校验/u, ["verify", "factcheck"]],
-  [/测试/u, ["test"]],
-  [/前端/u, ["frontend"]],
-  [/设计/u, ["design"]],
-  [/邮件|邮箱/u, ["email"]],
-  [/浏览器|网页|网站/u, ["browser", "web"]],
-  [/性能/u, ["performance"]],
-  [/安全|漏洞/u, ["security", "audit"]],
-]);
 const CONFIG_KEYS = new Set(["version", "builtin_instructions", "automatic_project_context", "model_instructions_file", "instruction_files", "instruction_max_bytes", "skill_roots", "commands"]);
 const COMMAND_KEYS = new Set(["description", "argv", "cwd", "timeout_seconds", "allow_extra_args"]);
 
@@ -760,79 +731,6 @@ function capabilityFingerprint(state, skills) {
   }));
 }
 
-function commandMatchText(command) {
-  return `${command.name} ${command.description} ${command.argv.join(" ")} ${command.searchTerms || ""}`;
-}
-
-function relevanceScore(task, candidate, identity = "") {
-  const taskTokens = tokenize(task);
-  const candidateTokens = tokenize(candidate);
-  if (!taskTokens.size || !candidateTokens.size) return 0;
-  const identityTokens = tokenize(identity);
-  let score = 0;
-  for (const token of taskTokens) {
-    if (candidateTokens.has(token)) score += token.length >= 6 ? 2 : 1;
-    if (identityTokens.has(token)) score += token.length >= 6 ? 4 : 3;
-  }
-  const taskComparable = comparableText(task);
-  const candidateComparable = comparableText(candidate);
-  const identityComparable = comparableText(identity);
-  if (candidateComparable.includes(taskComparable) || taskComparable.includes(candidateComparable)) score += 4;
-  if (identityComparable.length >= 3 && ` ${taskComparable} `.includes(` ${identityComparable} `)) score += 12;
-  return score;
-}
-
-function comparableText(value) {
-  return String(value || "")
-    .toLowerCase()
-    .replace(/[^a-z0-9\p{Script=Han}]+/gu, " ")
-    .trim()
-    .replace(/\s+/g, " ");
-}
-
-function tokenize(value) {
-  const text = String(value || "").toLowerCase();
-  const tokens = new Set();
-  for (const raw of text.match(/[a-z0-9_][a-z0-9_.-]{1,}/g) || []) {
-    const token = raw.replace(/^[.-]+|[.-]+$/g, "");
-    addToken(tokens, token);
-    for (const part of token.split(/[._-]+/)) addToken(tokens, part);
-  }
-  for (const sequence of text.match(/[\p{Script=Han}]{1,}/gu) || []) {
-    addToken(tokens, sequence);
-    const minimumSize = sequence.length === 1 ? 1 : 2;
-    for (let size = minimumSize; size <= Math.min(3, sequence.length); size += 1) {
-      for (let index = 0; index + size <= sequence.length; index += 1) addToken(tokens, sequence.slice(index, index + size));
-    }
-  }
-  for (const [pattern, aliases] of HAN_TOKEN_ALIASES) {
-    if (!pattern.test(text)) continue;
-    for (const alias of aliases) addToken(tokens, alias);
-  }
-  return tokens;
-}
-
-function addToken(tokens, raw) {
-  const token = String(raw || "").replace(/^[.-]+|[.-]+$/g, "");
-  if (token.length < 2 || TOKEN_STOP_WORDS.has(token)) return;
-  tokens.add(token);
-  const canonical = ENGLISH_TOKEN_CANONICAL.get(token);
-  if (canonical) tokens.add(canonical);
-}
-
-function recommendTools(task, { commandsAvailable, commandRelevant, skillRelevant }) {
-  const lower = task.toLowerCase();
-  const tools = ["agent_context"];
-  if (skillRelevant) tools.push("load_local_skill");
-  if (commandRelevant) tools.push("run_local_command");
-  if (/browser|chrome|edge|brave|网页|浏览器|表单|网站/.test(lower)) tools.push("browser_status", "browser_list_tabs", "browser_manage_tabs", "browser_inspect_page", "browser_wait", "browser_action", "browser_fill_form");
-  if (/app|application|gui|window|应用|软件|窗口|界面/.test(lower)) tools.push("list_local_applications", "inspect_local_application", "operate_local_application");
-  if (/git|commit|branch|diff|仓库|提交|分支/.test(lower)) tools.push("git_status", "git_diff");
-  if (/test|build|lint|command|terminal|测试|构建|命令|终端/.test(lower)) tools.push(commandsAvailable ? "run_local_command" : "run_process");
-  if (/file|code|source|edit|write|文件|代码|源码|修改|写入/.test(lower)) tools.push("read_file", "search_text", "edit_file", "apply_patch");
-  return [...new Set(tools)];
-}
-
 function publicSkill(skill, displayPath) {
   return {
     id: skill.id,

package/src/local/app-automation.mjs

@@ -1,6 +1,7 @@
 import { opendir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, extname, join } from "node:path";
+import { createToolAuthorizer } from "./policy.mjs";
 
 const MAX_APPLICATIONS = 1000;
 const MAX_APPLICATION_SCAN_ENTRIES = 20_000;
@@ -12,8 +13,9 @@ const APP_NAME_PATTERN = /^[^\0\r\n]{1,300}$/;
 const DEFAULT_APPLICATION_CACHE_MS = 30_000;
 
 export class AppAutomationManager {
-  constructor({ policy, displayPath, runProcess, readResourceText, throwIfCancelled = () => {}, platform = process.platform, home = homedir(), applicationRoots = null, applicationCacheMs = DEFAULT_APPLICATION_CACHE_MS, now = () => Date.now() }) {
+  constructor({ policy, authorizeTool = null, displayPath, runProcess, readResourceText, throwIfCancelled = () => {}, platform = process.platform, home = homedir(), applicationRoots = null, applicationCacheMs = DEFAULT_APPLICATION_CACHE_MS, now = () => Date.now() }) {
     this.policy = policy || {};
+    this.authorizeTool = createToolAuthorizer(this.policy, authorizeTool);
     this.displayPath = displayPath;
     this.runProcess = runProcess;
     this.readResourceText = readResourceText;
@@ -41,6 +43,7 @@ export class AppAutomationManager {
   }
 
   async listApplications(args = {}, context = {}) {
+    this.authorizeTool("list_local_applications");
     this.throwIfCancelled(context);
     const query = String(args.query || "").trim().toLowerCase();
     const limit = clampInt(args.max_results, 200, 1, MAX_APPLICATIONS);
@@ -86,7 +89,7 @@ export class AppAutomationManager {
   }
 
   async openApplication(args = {}, context = {}) {
-    this.assertFull("open_local_application");
+    this.authorizeTool("open_local_application");
     const application = requiredApplication(args.application);
     const target = optionalString(args.target, "target", 32768);
     this.throwIfCancelled(context);
@@ -113,7 +116,7 @@ export class AppAutomationManager {
   }
 
   async inspectApplication(args = {}, context = {}) {
-    this.assertFull("inspect_local_application");
+    this.authorizeTool("inspect_local_application");
     assertMacAccessibility(this.platform);
     const application = requiredApplication(args.application);
     const processName = applicationProcessName(application);
@@ -136,7 +139,7 @@ export class AppAutomationManager {
   }
 
   async operateApplication(args = {}, context = {}) {
-    this.assertFull("operate_local_application");
+    this.authorizeTool("operate_local_application");
     assertMacAccessibility(this.platform);
     const application = requiredApplication(args.application);
     const processName = applicationProcessName(application);
@@ -196,11 +199,6 @@ export class AppAutomationManager {
     return parsed;
   }
 
-  assertFull(tool) {
-    if (this.policy.profile !== "full" || this.policy.execMode !== "shell" || this.policy.unrestrictedPaths !== true) {
-      throw new Error(`${tool} requires the canonical full profile`);
-    }
-  }
 }
 
 async function listMacApplications(roots, context, throwIfCancelled) {

package/src/local/browser-bridge.mjs

@@ -1,40 +1,38 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { 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 { createToolAuthorizer } from "./policy.mjs";
+import { assertStateMaintenanceAvailable, packageRoot } from "./state.mjs";
+import {
+  BROWSER_EXTENSION_PROTOCOL, EXPECTED_EXTENSION_VERSION, MAX_BROWSER_MESSAGE_BYTES, REQUIRED_EXTENSION_CAPABILITIES,
+  closeProtocolSocket, normalizeCompatibleExtensionInfo, parseBrowserSocketMessage, parseExtensionHello, safeSocketSend,
+} from "./browser-extension-protocol.mjs";
+import {
+  DEFAULT_BROWSER_PORT, 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";
 
-const DEFAULT_PORT = 39393;
 const MAX_PORT_ATTEMPTS = 10;
-const MAX_BROWSER_MESSAGE_BYTES = 8 * 1024 * 1024;
 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 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 = () => {} }) {
+  constructor({ policy, authorizeTool = null, stateRoot = "", runProcess, readResourceText, readResourceBinary, throwIfCancelled = () => {} }) {
     this.policy = policy || {};
+    this.authorizeTool = createToolAuthorizer(this.policy, authorizeTool);
     this.stateRoot = stateRoot ? resolve(stateRoot) : "";
     this.runProcess = runProcess;
     this.readResourceText = readResourceText;
@@ -62,6 +60,7 @@ export class BrowserBridgeManager {
   }
 
   async status(context = {}) {
+    this.authorizeTool("browser_status");
     await this.ensureStarted(context);
     return {
       available: true,
@@ -102,7 +101,7 @@ export class BrowserBridgeManager {
   }
 
   async pair(args = {}, context = {}) {
-    this.assertFull("pair_browser_extension");
+    this.authorizeTool("pair_browser_extension");
     const status = await this.status(context);
     if (args.open !== false) {
       const command = process.platform === "darwin"
@@ -125,6 +124,7 @@ export class BrowserBridgeManager {
   }
 
   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,
@@ -133,16 +133,19 @@ export class BrowserBridgeManager {
   }
 
   async manageTabs(args = {}, context = {}) {
+    this.authorizeTool("browser_manage_tabs");
     return this.request("manage_tabs", normalizeTabCommand(args), clampInt(args.timeout_seconds, 30, 1, 120), 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);
   }
 
   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),
@@ -153,6 +156,7 @@ export class BrowserBridgeManager {
   }
 
   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),
@@ -163,7 +167,7 @@ export class BrowserBridgeManager {
   }
 
   async act(args = {}, context = {}) {
-    this.assertFull("browser_action");
+    this.authorizeTool("browser_action");
     const action = normalizeBrowserAction(args.action);
     const rawUrl = optionalString(args.url, "url", 32768);
     const payload = {
@@ -200,7 +204,7 @@ export class BrowserBridgeManager {
   }
 
   async fillForm(args = {}, context = {}) {
-    this.assertFull("browser_fill_form");
+    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 = [];
@@ -242,7 +246,7 @@ export class BrowserBridgeManager {
   }
 
   async uploadFiles(args = {}, context = {}) {
-    this.assertFull("browser_upload_files");
+    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);
@@ -274,6 +278,7 @@ export class BrowserBridgeManager {
   }
 
   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",
@@ -296,7 +301,6 @@ export class BrowserBridgeManager {
   }
 
   async request(method, params, timeoutSeconds, context = {}) {
-    this.assertFull(method);
     await this.ensureStarted(context);
     this.throwIfCancelled(context);
     const transport = this.server ? this.socket : this.upstream;
@@ -778,140 +782,6 @@ export class BrowserBridgeManager {
       : 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`);
-    }
-  }
-}
-
-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);
-  await mkdir(stateRoot, { recursive: true, mode: 0o700 });
-  const file = join(stateRoot, PAIRING_FILE);
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    if (existsSync(file)) {
-      ownerOnlyFile(file);
-      let parsed;
-      try { parsed = JSON.parse(readBoundedRegularFileSync(file, 64 * 1024).toString("utf8")); } catch { throw new Error("browser pairing state is not valid bounded JSON"); }
-      if (!/^[A-Za-z0-9_-]{32,100}$/.test(parsed.token) || !Number.isInteger(parsed.port) || parsed.port < 1024 || parsed.port > 65535) {
-        throw new Error("browser pairing state is invalid");
-      }
-      return parsed;
-    }
-    const value = { token: randomBytes(32).toString("base64url"), port: DEFAULT_PORT };
-    try {
-      createExclusiveFileSync(file, `${JSON.stringify(value, null, 2)}
-`, { mode: 0o600 });
-      ownerOnlyFile(file);
-      return value;
-    } catch (error) {
-      if (error?.code !== "EEXIST") throw error;
-    }
-  }
-  throw new Error("browser pairing state could not be initialized");
-}
-
-async function savePairing(stateRoot, value) {
-  assertStateMaintenanceAvailable(stateRoot);
-  const file = join(stateRoot, PAIRING_FILE);
-  replaceFileAtomicallySync(file, `${JSON.stringify(value, null, 2)}
-`, { mode: 0o600 });
-  ownerOnlyFile(file);
-}
-
-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>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) {
-  const normalized = String(host || "").toLowerCase();
-  return normalized === `127.0.0.1:${port}` || normalized === `localhost:${port}` || normalized === `[::1]:${port}`;
-}
-
-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",
-  };
-}
-
-function parseBrowserSocketMessage(data) {
-  if (Buffer.byteLength(data) > MAX_BROWSER_MESSAGE_BYTES) return { ok: false, code: 1009, reason: "message too large" };
-  let text;
-  try { text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(data)); }
-  catch { return { ok: false, code: 1007, reason: "invalid UTF-8" }; }
-  let message;
-  try { message = JSON.parse(text); }
-  catch { return { ok: false, code: 1007, reason: "invalid JSON" }; }
-  if (!message || typeof message !== "object" || Array.isArray(message)) return { ok: false, code: 1002, reason: "invalid protocol message" };
-  return { ok: true, message };
-}
-
-function closeProtocolSocket(socket, code, reason) {
-  try { socket.close(code, reason); } catch {}
-}
-
-function safeSocketSend(socket, value) {
-  if (!socket || socket.readyState !== 1) return false;
-  try {
-    socket.send(typeof value === "string" ? value : JSON.stringify(value));
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function sendJson(response, value) {
-  response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
-  response.end(`${JSON.stringify(value)}\n`);
 }
 
 function normalizeUploadFilename(value, { derived = false } = {}) {

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

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { packageRoot } from "./state.mjs";
+
+export const BROWSER_EXTENSION_PROTOCOL = 3;
+export const EXPECTED_EXTENSION_VERSION = extensionVersion();
+export const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
+  "semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
+]);
+export const MAX_BROWSER_MESSAGE_BYTES = 8 * 1024 * 1024;
+
+export 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;
+}
+
+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`);
+  }
+  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;
+}
+
+export function parseBrowserSocketMessage(data) {
+  if (Buffer.byteLength(data) > MAX_BROWSER_MESSAGE_BYTES) return { ok: false, code: 1009, reason: "message too large" };
+  let text;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(data)); }
+  catch { return { ok: false, code: 1007, reason: "invalid UTF-8" }; }
+  let message;
+  try { message = JSON.parse(text); }
+  catch { return { ok: false, code: 1007, reason: "invalid JSON" }; }
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    return { ok: false, code: 1002, reason: "invalid protocol message" };
+  }
+  return { ok: true, message };
+}
+
+export function closeProtocolSocket(socket, code, reason) {
+  try { socket.close(code, reason); } catch {}
+}
+
+export function safeSocketSend(socket, value) {
+  if (!socket || socket.readyState !== 1) return false;
+  try {
+    socket.send(typeof value === "string" ? value : JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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 };
+}
+
+function extensionVersion() {
+  const manifest = JSON.parse(readFileSync(resolve(packageRoot, "browser-extension", "manifest.json"), "utf8"));
+  return String(manifest.version_name || manifest.version || "");
+}

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

@@ -0,0 +1,83 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { assertStateMaintenanceAvailable, ownerOnlyFile } from "./state.mjs";
+import { EXPECTED_EXTENSION_VERSION } from "./browser-extension-protocol.mjs";
+
+export const DEFAULT_BROWSER_PORT = 39393;
+const PAIRING_FILE = "browser-bridge.json";
+
+export async function loadOrCreatePairing(stateRoot) {
+  if (!stateRoot) return { token: randomBytes(32).toString("base64url"), port: DEFAULT_BROWSER_PORT };
+  assertStateMaintenanceAvailable(stateRoot);
+  await mkdir(stateRoot, { recursive: true, mode: 0o700 });
+  const file = join(stateRoot, PAIRING_FILE);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    if (existsSync(file)) {
+      ownerOnlyFile(file);
+      let parsed;
+      try { parsed = JSON.parse(readBoundedRegularFileSync(file, 64 * 1024).toString("utf8")); }
+      catch { throw new Error("browser pairing state is not valid bounded JSON"); }
+      if (!/^[A-Za-z0-9_-]{32,100}$/.test(parsed.token) || !Number.isInteger(parsed.port) || parsed.port < 1024 || parsed.port > 65535) {
+        throw new Error("browser pairing state is invalid");
+      }
+      return parsed;
+    }
+    const value = { token: randomBytes(32).toString("base64url"), port: DEFAULT_BROWSER_PORT };
+    try {
+      createExclusiveFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+      ownerOnlyFile(file);
+      return value;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  }
+  throw new Error("browser pairing state could not be initialized");
+}
+
+export async function savePairing(stateRoot, value) {
+  assertStateMaintenanceAvailable(stateRoot);
+  const file = join(stateRoot, PAIRING_FILE);
+  replaceFileAtomicallySync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  ownerOnlyFile(file);
+}
+
+export 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>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>`;
+}
+
+export 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;
+}
+
+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`);
+}