machine-bridge-mcp 0.11.1 → 0.12.1

package/scripts/privacy-check.mjs

@@ -12,16 +12,23 @@ const findings = [];
 for (const relativePath of candidates) {
   if (relativePath === ".privacy-denylist") continue;
   scanDenylistPath(relativePath, denylist, findings);
+  scanSensitivePath(relativePath, findings);
   const fullPath = path.join(root, relativePath);
   let info;
-  try { info = lstatSync(fullPath); } catch { continue; }
+  try { info = lstatSync(fullPath); } catch {
+    findings.push({ path: relativePath, line: 1, rule: "publication file metadata could not be read" });
+    continue;
+  }
   if (info.isSymbolicLink()) {
     findings.push({ path: relativePath, line: 1, rule: "symbolic link in publication surface" });
     continue;
   }
   if (!info.isFile()) continue;
   let buffer;
-  try { buffer = readFileSync(fullPath); } catch { continue; }
+  try { buffer = readFileSync(fullPath); } catch {
+    findings.push({ path: relativePath, line: 1, rule: "publication file content could not be read" });
+    continue;
+  }
   if (buffer.length > 5 * 1024 * 1024) {
     findings.push({ path: relativePath, line: 1, rule: "file exceeds privacy scanner size limit and requires manual review" });
     continue;
@@ -36,6 +43,7 @@ for (const relativePath of candidates) {
     continue;
   }
   if (relativePath !== selfPath) scanBuiltIn(relativePath, text, findings);
+  if (path.basename(relativePath).toLowerCase() === ".npmrc") scanNpmrc(relativePath, text, findings);
   scanDenylist(relativePath, text, denylist, findings);
 }
 
@@ -65,7 +73,9 @@ function collectCandidateFiles(directory) {
       const relative = stack.pop();
       const absolute = path.join(directory, relative);
       let entries;
-      try { entries = readdirSync(absolute, { withFileTypes: true }); } catch { continue; }
+      try { entries = readdirSync(absolute, { withFileTypes: true }); } catch {
+        throw new Error("privacy fallback traversal could not read a repository directory");
+      }
       for (const entry of entries) {
         if (excluded.has(entry.name) || entry.name === ".privacy-denylist") continue;
         const child = relative ? path.join(relative, entry.name) : entry.name;
@@ -92,10 +102,17 @@ function escapeRegExp(value) {
 
 function scanBuiltIn(relativePath, text, out) {
   const rules = [
-    ["private key material", /-----BEGIN\s+(?:OPENSSH|RSA|EC|DSA)\s+PRIVATE\s+KEY-----/g],
+    ["private key material", /-----BEGIN\s+(?:(?:OPENSSH|RSA|EC|DSA)\s+|ENCRYPTED\s+)?PRIVATE\s+KEY-----/g],
     ["AWS access key", /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g],
     ["GitHub access token", /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/g],
+    ["GitLab access token", /\bglpat-[A-Za-z0-9_-]{20,}\b/g],
+    ["npm access token", /\bnpm_[A-Za-z0-9]{30,}\b/g],
+    ["Slack access token", /\bxox[aboprs]-[A-Za-z0-9-]{10,}\b/g],
+    ["Google API key", /\bAIza[A-Za-z0-9_-]{30,}\b/g],
+    ["live payment API key", /\b(?:sk|rk|pk)_live_[A-Za-z0-9]{16,}\b/g],
     ["API secret token", /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g],
+    ["JWT-like bearer token", /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g],
+    ["URL with embedded credentials", /https?:\/\/[^\s/@:"'<>]+:[^\s/@"'<>]+@[^\s/"'<>]+/gi],
     ["absolute macOS/Linux home path", /(?:^|[\s"'=(:,])\/(?:Users|home)\/([^/\s"'<>]+)\//gm],
     ["absolute Windows home path", /(?:^|[\s"'=(:,])\b[A-Za-z]:\\Users\\([^\\\s"'<>]+)\\/gm],
   ];
@@ -105,6 +122,11 @@ function scanBuiltIn(relativePath, text, out) {
       out.push({ path: relativePath, line: lineNumber(text, match.index || 0), rule });
     }
   }
+  const emailLike = /\b[A-Z0-9._%+-]+@([A-Z0-9.-]+\.[A-Z]{2,})\b/gi;
+  for (const match of text.matchAll(emailLike)) {
+    if (isReservedExampleHost(match[1]) || String(match[1]).toLowerCase().endsWith(".noreply.github.com")) continue;
+    out.push({ path: relativePath, line: lineNumber(text, match.index || 0), rule: "non-example email address" });
+  }
   const sshLike = /\b[A-Za-z_][A-Za-z0-9._-]*@([A-Za-z0-9.-]+)\b/g;
   for (const match of text.matchAll(sshLike)) {
     if (isReservedExampleHost(match[1]) || !hasNearbySshContext(text, match.index || 0)) continue;
@@ -112,6 +134,40 @@ function scanBuiltIn(relativePath, text, out) {
   }
 }
 
+
+function scanSensitivePath(relativePath, out) {
+  const normalized = String(relativePath).split(path.sep).join("/");
+  const base = path.posix.basename(normalized).toLowerCase();
+  const sensitive = base === ".dev.vars"
+    || /^\.env(?:\.|$)/.test(base)
+    || /\.(?:pem|p12|pfx|sqlite|sqlite3|db|log)$/i.test(base)
+    || /^(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)(?:\.|$)/i.test(base)
+    || /^(?:credentials?|secrets?|cookies?|sessions?|tokens?)(?:\.|$)/i.test(base);
+  if (sensitive) out.push({ path: relativePath, line: 1, rule: "credential- or private-data-shaped publication filename" });
+}
+
+function scanNpmrc(relativePath, text, out) {
+  const forbiddenKey = /(?:^|:)(?:_auth|_authtoken|_password|username|email|certfile|keyfile|cafile)$/i;
+  const lines = text.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+    const separator = line.indexOf("=");
+    if (separator < 1) {
+      out.push({ path: relativePath, line: index + 1, rule: "unparseable tracked .npmrc line requires manual review" });
+      continue;
+    }
+    const key = line.slice(0, separator).trim().toLowerCase();
+    const value = line.slice(separator + 1).trim();
+    if (forbiddenKey.test(key) || /(?:^|[:/])(?:_auth|_authtoken|_password|username|email|certfile|keyfile|cafile)$/i.test(key)) {
+      out.push({ path: relativePath, line: index + 1, rule: "tracked .npmrc contains authentication or identity configuration" });
+    }
+    if (/\$\{[^}]+\}/.test(value) || /https?:\/\/[^/@\s]+:[^/@\s]+@/i.test(value)) {
+      out.push({ path: relativePath, line: index + 1, rule: "tracked .npmrc contains environment interpolation or embedded credentials" });
+    }
+  }
+}
+
 function scanDenylistPath(relativePath, entries, out) {
   const lower = relativePath.toLocaleLowerCase("en-US");
   for (const entry of entries) {
@@ -133,7 +189,9 @@ function scanDenylist(relativePath, text, entries, out) {
 function loadDenylist(file) {
   if (!existsSync(file)) return [];
   let text;
-  try { text = readFileSync(file, "utf8"); } catch { return []; }
+  try { text = readFileSync(file, "utf8"); } catch {
+    throw new Error("local privacy denylist exists but could not be read");
+  }
   return [...new Set(text.split(/\r?\n/)
     .map((line) => line.trim())
     .filter((line) => line && !line.startsWith("#") && line.length >= 3)
@@ -163,6 +221,9 @@ function isReservedExampleHost(host) {
     || value === "127.0.0.1"
     || value === "::1"
     || value === "example"
+    || value === "example.com"
+    || value === "example.net"
+    || value === "example.org"
     || value.endsWith(".example")
     || value.endsWith(".example.com")
     || value.endsWith(".example.net")

package/scripts/release-state.mjs

@@ -0,0 +1,10 @@
+export function tagSyncError({ scope = "local", tag, head, commit }) {
+  const label = scope === "remote" ? "remote tag" : "local tag";
+  if (!commit) {
+    return `${label} ${tag} is missing; run npm run release:publish before npm publish`;
+  }
+  if (commit !== head) {
+    return `${label} ${tag} points to ${commit}, not HEAD ${head}`;
+  }
+  return "";
+}

package/scripts/syntax-check.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const roots = ["bin", "src/local", "scripts", "tests", "browser-extension"];
+const files = roots.flatMap((entry) => collect(join(root, entry)))
+  .filter((file) => [".js", ".mjs"].includes(extname(file)))
+  .sort();
+
+for (const file of files) {
+  const result = spawnSync(process.execPath, ["--check", file], {
+    cwd: root,
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    process.stderr.write(`syntax check failed: ${relative(root, file)}\n${result.stderr || result.stdout}`);
+    process.exit(1);
+  }
+}
+
+if (process.platform !== "win32") {
+  const shell = spawnSync("sh", ["-n", join(root, "mbm")], {
+    cwd: root,
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (shell.error) throw shell.error;
+  if (shell.status !== 0) {
+    process.stderr.write(`shell syntax check failed: mbm\n${shell.stderr || shell.stdout}`);
+    process.exit(1);
+  }
+}
+
+console.log(`syntax check ok (${files.length} JavaScript files${process.platform === "win32" ? "" : "; mbm shell wrapper"})`);
+
+function collect(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const target = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...collect(target));
+    else if (entry.isFile()) files.push(target);
+  }
+  return files;
+}

package/src/local/agent-context.mjs

@@ -112,12 +112,12 @@ export class AgentContextManager {
     const discovered = await this.discoverSkills(state, { maxResults: MAX_SKILL_RESULTS }, context);
     const maxSkills = clampInt(args.max_skills, 10, 1, 50);
     const skillMatches = discovered.skills
-      .map((skill) => ({ skill, score: relevanceScore(task, `${skill.name} ${skill.description}`) }))
+      .map((skill) => ({ skill, score: relevanceScore(task, `${skill.name} ${skill.description}`, skill.name) }))
       .filter((item) => item.score > 0)
       .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
       .slice(0, maxSkills);
     const commandMatches = [...state.commands.values()]
-      .map((command) => ({ command, score: relevanceScore(task, `${command.name} ${command.description} ${command.argv.join(" ")}`) }))
+      .map((command) => ({ command, score: relevanceScore(task, `${command.name} ${command.description} ${command.argv.join(" ")}`, command.name) }))
       .filter((item) => item.score > 0)
       .sort((a, b) => b.score - a.score || a.command.name.localeCompare(b.command.name))
       .slice(0, 20);
@@ -718,7 +718,7 @@ function capabilityFingerprint(state, skills) {
   }));
 }
 
-function relevanceScore(task, candidate) {
+function relevanceScore(task, candidate, identity = "") {
   const taskTokens = tokenize(task);
   const candidateTokens = tokenize(candidate);
   if (!taskTokens.size || !candidateTokens.size) return 0;
@@ -726,18 +726,31 @@ function relevanceScore(task, candidate) {
   for (const token of taskTokens) {
     if (candidateTokens.has(token)) score += token.length >= 6 ? 2 : 1;
   }
-  const taskLower = task.toLowerCase();
-  const candidateLower = candidate.toLowerCase();
-  if (candidateLower.includes(taskLower) || taskLower.includes(candidateLower)) score += 4;
+  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, "");
     if (token.length >= 2 && !TOKEN_STOP_WORDS.has(token)) tokens.add(token);
+    for (const part of token.split(/[._-]+/)) {
+      if (part.length >= 2 && !TOKEN_STOP_WORDS.has(part)) tokens.add(part);
+    }
   }
   for (const sequence of text.match(/[\p{Script=Han}]{1,}/gu) || []) {
     if (!TOKEN_STOP_WORDS.has(sequence)) tokens.add(sequence);

package/src/local/app-automation.mjs

@@ -109,6 +109,7 @@ export class AppAutomationManager {
       maxDepth: clampInt(args.max_depth, 6, 1, MAX_UI_DEPTH),
       maxElements: clampInt(args.max_elements, 200, 1, MAX_UI_ELEMENTS),
       includeValues: args.include_values === true,
+      includeMenus: args.include_menus === true,
     };
     const result = await this.runJxa(payload, clampInt(args.timeout_seconds, 30, 1, 120), context);
     return {
@@ -132,7 +133,9 @@ export class AppAutomationManager {
       if (value !== null) throw new Error("value and value_resource are mutually exclusive");
       value = await this.readResourceText(requiredResourceName(args.value_resource));
     }
-    if (value !== null && value.length > MAX_TEXT_CHARS) throw new Error(`application action value exceeds ${MAX_TEXT_CHARS} characters`);
+    if (value !== null && (value.includes("\0") || value.length > MAX_TEXT_CHARS)) {
+      throw new Error(`application action value exceeds ${MAX_TEXT_CHARS} characters or contains a NUL byte`);
+    }
     const payload = {
       operation: "act",
       application: processName,
@@ -141,6 +144,7 @@ export class AppAutomationManager {
       value,
       maxDepth: clampInt(args.max_depth, 8, 1, MAX_UI_DEPTH),
       maxElements: MAX_UI_ELEMENTS,
+      includeMenus: args.include_menus === true,
     };
     const result = await this.runJxa(payload, clampInt(args.timeout_seconds, 30, 1, 120), context);
     return {
@@ -166,9 +170,11 @@ export class AppAutomationManager {
       undefined,
       input,
     );
+    const output = result.stdout.trim();
+    if (!output) throw new Error("macOS accessibility helper returned no JSON output");
     let parsed;
     try {
-      parsed = JSON.parse(result.stdout.trim() || "{}");
+      parsed = JSON.parse(output);
     } catch {
       throw new Error("macOS accessibility helper returned invalid JSON");
     }
@@ -335,7 +341,7 @@ function describe(element, index, includeValues) {
   return item;
 }
 function childrenOf(element) { return safe(() => element.uiElements(), []); }
-function flatten(root, maxDepth, maxElements, includeValues) {
+function flatten(root, maxDepth, maxElements, includeValues, includeMenus) {
   const output = [];
   const elements = [];
   const stack = [{ element: root, depth: 0 }];
@@ -344,10 +350,12 @@ function flatten(root, maxDepth, maxElements, includeValues) {
     const children = childrenOf(current.element);
     for (let i = children.length - 1; i >= 0; i--) {
       const child = children[i];
+      const item = describe(child, output.length, includeValues);
       elements.push(child);
-      output.push(describe(child, output.length, includeValues));
+      output.push(item);
       if (output.length >= maxElements) break;
-      if (current.depth + 1 < maxDepth) stack.push({ element: child, depth: current.depth + 1 });
+      const isMenuTree = String(item.role || '').startsWith('AXMenu');
+      if (current.depth + 1 < maxDepth && (includeMenus || !isMenuTree)) stack.push({ element: child, depth: current.depth + 1 });
     }
   }
   return { output, elements, truncated: stack.length > 0 || output.length >= maxElements };
@@ -364,14 +372,14 @@ function main() {
   const process = se.applicationProcesses.byName(payload.application);
   if (!safe(() => process.exists(), false)) throw new Error('application process not found or Accessibility access denied');
   if (payload.operation === 'inspect') {
-    const flattened = flatten(process, payload.maxDepth, payload.maxElements, payload.includeValues === true);
-    return { frontmost: safe(() => process.frontmost(), false), elements: flattened.output, truncated: flattened.truncated };
+    const flattened = flatten(process, payload.maxDepth, payload.maxElements, payload.includeValues === true, payload.includeMenus === true);
+    return { frontmost: safe(() => process.frontmost(), false), elements: flattened.output, truncated: flattened.truncated, menus_included: payload.includeMenus === true };
   }
   if (payload.action === 'activate') {
     process.frontmost = true;
     return { ok: true, matched: 1 };
   }
-  const flattened = flatten(process, payload.maxDepth, payload.maxElements, true);
+  const flattened = flatten(process, payload.maxDepth, payload.maxElements, true, payload.includeMenus === true);
   const matchesList = [];
   for (let i = 0; i < flattened.output.length; i++) if (matches(flattened.output[i], payload.selector)) matchesList.push(i);
   const chosen = payload.selector.index !== undefined ? matchesList[payload.selector.index] : matchesList[0];
@@ -396,5 +404,5 @@ function main() {
   }
   return { ok: true, matched: matchesList.length, selected_index: chosen, element: describe(element, chosen, false) };
 }
-try { console.log(JSON.stringify(main())); } catch (error) { console.log(JSON.stringify({ error: String(error.message || error) })); }
+(() => { try { return JSON.stringify(main()); } catch (error) { return JSON.stringify({ error: String(error.message || error) }); } })()
 `;

package/src/local/browser-bridge.mjs

@@ -1,12 +1,12 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, openSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { WebSocket, WebSocketServer } from "ws";
-import { replaceFileSync } from "./atomic-fs.mjs";
+import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
-import { ownerOnlyFile, packageRoot } from "./state.mjs";
+import { assertStateMaintenanceAvailable, ownerOnlyFile, packageRoot } from "./state.mjs";
 
 const DEFAULT_PORT = 39393;
 const MAX_PORT_ATTEMPTS = 10;
@@ -200,9 +200,11 @@ export class BrowserBridgeManager {
       const resource = this.readResourceBinary(name);
       total += resource.buffer.length;
       if (total > 5 * 1024 * 1024) throw new Error("browser upload resources exceed 5 MiB total");
+      const suppliedFilename = filenames[files.length];
+      const derivedFilename = resource.path.split(/[\\/]/).pop() || name;
       files.push({
-        filename: String(args.filenames?.[files.length] || resource.path.split(/[\\/]/).pop() || name).slice(0, 255),
-        mime: String(args.mime_types?.[files.length] || "application/octet-stream").slice(0, 200),
+        filename: normalizeUploadFilename(suppliedFilename || derivedFilename, { derived: !suppliedFilename }),
+        mime: normalizeMimeType(mimeTypes[files.length] || "application/octet-stream"),
         data: resource.buffer.toString("base64"),
       });
     }
@@ -271,6 +273,7 @@ export class BrowserBridgeManager {
 
   async ensureStarted(context = {}) {
     this.throwIfCancelled(context);
+    if (this.stateRoot) assertStateMaintenanceAvailable(this.stateRoot);
     this.stopping = false;
     if (this.server || this.upstream?.readyState === 1) return;
     if (!this.startPromise) this.startPromise = this.start();
@@ -356,15 +359,23 @@ export class BrowserBridgeManager {
         resolvePromise(ok);
       };
       ws.on("message", (data) => {
-        let message;
-        try { message = JSON.parse(Buffer.from(data).toString("utf8")); } catch { return; }
-        if (!settled && message?.type === "hello" && message?.role === "runtime") {
+        const parsed = parseBrowserSocketMessage(data);
+        if (!parsed.ok) {
+          closeProtocolSocket(ws, parsed.code, parsed.reason);
+          return;
+        }
+        const message = parsed.message;
+        if (!settled) {
+          if (message.type !== "hello" || message.role !== "runtime") {
+            closeProtocolSocket(ws, 1002, "runtime hello required");
+            return;
+          }
           this.upstream = ws;
           this.proxyExtensionConnected = message.extension_connected === true;
           finish(true);
           return;
         }
-        this.handleUpstreamMessage(message);
+        if (!this.handleUpstreamMessage(message)) closeProtocolSocket(ws, 1002, "invalid broker protocol message");
       });
       ws.once("error", () => finish(false));
       ws.once("close", () => {
@@ -398,7 +409,7 @@ export class BrowserBridgeManager {
     }
     if (this.socket && this.socket.readyState === 1) this.socket.close(4001, "superseded");
     this.socket = ws;
-    ws.on("message", (data) => this.handleExtensionMessage(data));
+    ws.on("message", (data) => this.handleExtensionMessage(ws, data));
     ws.on("close", () => {
       if (this.socket !== ws) return;
       this.socket = null;
@@ -415,11 +426,18 @@ export class BrowserBridgeManager {
     this.broadcastRuntimeStatus(true);
   }
 
-  handleExtensionMessage(data) {
-    if (Buffer.byteLength(data) > MAX_BROWSER_MESSAGE_BYTES) return;
-    let message;
-    try { message = JSON.parse(Buffer.from(data).toString("utf8")); } catch { return; }
-    if (!message || message.type !== "response" || typeof message.id !== "string") return;
+  handleExtensionMessage(socket, data) {
+    if (this.socket !== socket) return;
+    const parsed = parseBrowserSocketMessage(data);
+    if (!parsed.ok) {
+      closeProtocolSocket(socket, parsed.code, parsed.reason);
+      return;
+    }
+    const message = parsed.message;
+    if (message.type !== "response" || typeof message.id !== "string") {
+      closeProtocolSocket(socket, 1002, "invalid extension protocol message");
+      return;
+    }
     const pending = this.pending.get(message.id);
     if (pending) {
       clearTimeout(pending.timeout);
@@ -436,11 +454,14 @@ export class BrowserBridgeManager {
   }
 
   handleRuntimeClientMessage(socket, data) {
-    if (Buffer.byteLength(data) > MAX_BROWSER_MESSAGE_BYTES) return;
-    let message;
-    try { message = JSON.parse(Buffer.from(data).toString("utf8")); } catch { return; }
-    if (message?.type === "ping") return;
-    if (message?.type === "cancel" && typeof message.id === "string") {
+    const parsed = parseBrowserSocketMessage(data);
+    if (!parsed.ok) {
+      closeProtocolSocket(socket, parsed.code, parsed.reason);
+      return;
+    }
+    const message = parsed.message;
+    if (message.type === "ping") return;
+    if (message.type === "cancel" && typeof message.id === "string") {
       for (const [routedId, route] of this.proxyRoutes) {
         if (route.socket !== socket || route.id !== message.id) continue;
         clearTimeout(route.timeout);
@@ -449,7 +470,10 @@ export class BrowserBridgeManager {
       }
       return;
     }
-    if (!message || message.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") return;
+    if (message.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") {
+      closeProtocolSocket(socket, 1002, "invalid runtime protocol message");
+      return;
+    }
     if (!this.socket || this.socket.readyState !== 1) {
       safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension is not connected" });
       return;
@@ -469,13 +493,13 @@ export class BrowserBridgeManager {
       const route = this.proxyRoutes.get(routedId);
       if (!route) return;
       this.proxyRoutes.delete(routedId);
-      try { this.socket?.send(JSON.stringify({ type: "cancel", id: routedId })); } catch {}
       safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser broker request timed out" });
+      try { this.socket?.send(JSON.stringify({ type: "cancel", id: routedId })); } catch {}
     }, timeoutMs);
     timeout.unref?.();
     this.proxyRoutes.set(routedId, { socket, id: message.id, timeout });
     try {
-      this.socket.send(JSON.stringify({ ...message, id: routedId }));
+      this.socket.send(JSON.stringify({ ...message, id: routedId, timeout_ms: timeoutMs }));
     } catch {
       clearTimeout(timeout);
       this.proxyRoutes.delete(routedId);
@@ -484,19 +508,19 @@ export class BrowserBridgeManager {
   }
 
   handleUpstreamMessage(message) {
-    if (!message || typeof message !== "object") return;
-    if (message.type === "status") {
-      this.proxyExtensionConnected = message.extension_connected === true;
+    if (message.type === "status" && typeof message.extension_connected === "boolean") {
+      this.proxyExtensionConnected = message.extension_connected;
       if (!this.proxyExtensionConnected) this.rejectPending("browser extension disconnected");
-      return;
+      return true;
     }
-    if (message.type !== "response" || typeof message.id !== "string") return;
+    if (message.type !== "response" || typeof message.id !== "string") return false;
     const pending = this.pending.get(message.id);
-    if (!pending) return;
+    if (!pending) return true;
     clearTimeout(pending.timeout);
     this.pending.delete(message.id);
     if (message.ok === false) pending.reject(new Error(String(message.error || "browser operation failed").slice(0, 2000)));
     else pending.resolve(message.result);
+    return true;
   }
 
   broadcastRuntimeStatus(connected) {
@@ -587,6 +611,7 @@ export class BrowserBridgeManager {
 
 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) {
@@ -600,18 +625,12 @@ async function loadOrCreatePairing(stateRoot) {
       return parsed;
     }
     const value = { token: randomBytes(32).toString("base64url"), port: DEFAULT_PORT };
-    let fd;
     try {
-      fd = openSync(file, "wx", 0o600);
-      writeFileSync(fd, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-      fsyncSync(fd);
-      closeSync(fd);
-      fd = undefined;
+      createExclusiveFileSync(file, `${JSON.stringify(value, null, 2)}
+`, { mode: 0o600 });
       ownerOnlyFile(file);
       return value;
     } catch (error) {
-      if (fd !== undefined) try { closeSync(fd); } catch {}
       if (error?.code !== "EEXIST") throw error;
     }
   }
@@ -619,23 +638,11 @@ async function loadOrCreatePairing(stateRoot) {
 }
 
 async function savePairing(stateRoot, value) {
+  assertStateMaintenanceAvailable(stateRoot);
   const file = join(stateRoot, PAIRING_FILE);
-  const temp = `${file}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
-  let fd;
-  try {
-    fd = openSync(temp, "wx", 0o600);
-    writeFileSync(fd, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-    fsyncSync(fd);
-    closeSync(fd);
-    fd = undefined;
-    replaceFileSync(temp, file);
-    ownerOnlyFile(file);
-  } catch (error) {
-    if (fd !== undefined) try { closeSync(fd); } catch {}
-    try { unlinkSync(temp); } catch {}
-    throw error;
-  }
+  replaceFileAtomicallySync(file, `${JSON.stringify(value, null, 2)}
+`, { mode: 0o600 });
+  ownerOnlyFile(file);
 }
 
 function pairingHtml(port, token) {
@@ -657,6 +664,22 @@ function securityHeaders(contentType) {
   };
 }
 
+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 {
@@ -708,6 +731,24 @@ function validateNavigationUrl(value) {
   return parsed.href;
 }
 
+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`);