feat(camoufox): drive targets via interceptor_browser_*; file-based ws handshake; v3.1.0 (#17)

Camoufox targets are now first-class citizens of the interceptor_browser_* /
humanizer_* tool surface. Callers don't have to reach for `firefox.connect`
themselves; passing a `camoufox_*` target_id through navigate / snapshot /
screenshot / click / scroll just works, same as cloakbrowser.

Headline changes:

- session.ts: lazy `firefox.connect(wsUrl)` + cached Browser/Context/Page on
  the camoufox entry. `getPageForTarget` is now async and dispatches on
  target_id prefix. Callers in humanizer engine + devtools tools updated.
  New `getBrowserEntry` for the cloakbrowser-only paths (consoleBuffer,
  context.cookies) — camoufox callers get a clear "not yet supported"
  error instead of a deep type-mismatch.

- File-based ws-endpoint handshake: replaces the stdout WS_REGEX with an
  atomic JSON drop at `${launcherDir}/ws-endpoint.json`. The python
  wrapper around `camoufox.server.launch_server` pipes the underlying
  Playwright Node child's stdout, strips ANSI, and writes the URL once;
  Node side polls the file. ANSI / log-level / locale changes upstream
  no longer affect Node's parser.

- firefox_user_prefs forwarded through `FORWARDED_PARAMS`, with the proxy
  CA path auto-setting `security.enterprise_roots.enabled = true` when
  `trust_proxy_cert` is true. Without it, hardened-Firefox builds ignore
  the imported NSS CA and HTTPS pages return SEC_ERROR_UNKNOWN_ISSUER.

- Launcher cwd hardened: spawn cwd is the launcher temp dir, AND a
  `package.json` with `{\"type\":\"commonjs\"}` lands there before spawn.
  This isolates camoufox's CommonJS launcher from any stale ancestor
  `package.json` (notably `/tmp/package.json` from other tools) that
  would otherwise force Node to load `launchServer.js` as ESM.

- `interceptor_browser_close` now closes camoufox targets too, dispatching
  the deactivate to the right interceptor based on target_id prefix.

- `proxy_check_fingerprint_runtime` now returns a `runtimes[]` array per
  backend — keeps the contract forward-compatible if more backends land.

- `proxy_list_traffic` exposes `count` alongside `total` for the
  historical alias.

Tests:

- Unit suite rewired around the file-handshake contract (5 new cases:
  resolve via file, stderr-tail capture on early exit, ANSI noise on
  stderr is irrelevant to the resolve path, etc.).
- Integration: new test that drives the camoufox target via
  \`interceptor_browser_navigate\` (skipped pending an upstream Playwright
  fix for proxy propagation through \`BrowserServer.newContext\`; the
  mscdirect-actor end-to-end smoke covers the production path).
- mcp-server preflight + HAR-replay tests: schema fixes (runtimes array,
  \`count\` alias).

Out of band:

- /tmp/package.json poisoning fix is now baked into the launcher (cwd +
  cjs marker). Operator hosts no longer need to keep /tmp clean.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: yfe404

package.json

@@ -1,6 +1,6 @@
 {
   "name": "proxy-mcp",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "MCP server for HTTP/HTTPS MITM proxy via mockttp",
   "type": "module",
   "engines": {

src/browser/session.ts

@@ -1,28 +1,108 @@
 /**
  * Shared helpers for resolving a Playwright Page from a browser interceptor target ID.
  * Used by humanizer and browser tools so they don't each re-walk the interceptor map.
+ *
+ * Resolves both cloakbrowser ("browser_*") and camoufox ("camoufox_*") targets.
+ * Camoufox entries don't carry a Page eagerly — the interceptor returns a WS
+ * endpoint and stops there. We connect lazily on first use via
+ * `firefox.connect(wsUrl)` and cache the Browser/Context/Page on the entry, so
+ * every `interceptor_browser_*` and `humanizer_*` tool call works identically
+ * across both engines.
  */
 
-import type { Page } from "playwright-core";
+import { firefox, type Browser, type BrowserContext, type Page } from "playwright-core";
 import { interceptorManager } from "../interceptors/manager.js";
 import type { BrowserInterceptor, BrowserTargetEntry } from "../interceptors/browser.js";
+import type { CamoufoxInterceptor, CamoufoxTargetEntry } from "../interceptors/camoufox.js";
+
+interface CamoufoxDriverHandle {
+  browser?: Browser;
+  context?: BrowserContext;
+  page?: Page;
+}
+type CamoufoxEntryWithDriver = CamoufoxTargetEntry & CamoufoxDriverHandle;
 
 function getBrowserInterceptor(): BrowserInterceptor {
   const it = interceptorManager.get("browser") as BrowserInterceptor | undefined;
   if (!it) throw new Error("Browser interceptor not registered.");
   return it;
 }
 
-export function getEntry(targetId: string): BrowserTargetEntry {
+function getCamoufoxInterceptor(): CamoufoxInterceptor | undefined {
+  return interceptorManager.get("camoufox") as CamoufoxInterceptor | undefined;
+}
+
+function isCamoufoxTargetId(targetId: string): boolean {
+  return typeof targetId === "string" && targetId.startsWith("camoufox_");
+}
+
+async function ensureCamoufoxPage(entry: CamoufoxEntryWithDriver): Promise<Page> {
+  if (entry.page && !entry.page.isClosed()) return entry.page;
+  if (!entry.browser) {
+    entry.browser = await firefox.connect(entry.wsUrl);
+  }
+  let ctx = entry.browser.contexts()[0];
+  if (!ctx) {
+    // BrowserServer + persistent_context: the persistent context lives
+    // server-side and `Browser.contexts()` from a fresh `firefox.connect()`
+    // returns empty. New contexts created here do NOT inherit the
+    // launch-level proxy, so we have to wire the MITM proxy explicitly
+    // or the firefox process reaches the internet directly and bypasses
+    // capture. Pull the port back out of the entry details (set at
+    // activate() time).
+    const proxyPort = (entry.target.details as { proxyPort?: number } | undefined)?.proxyPort;
+    ctx = await entry.browser.newContext({
+      ignoreHTTPSErrors: true,
+      ...(proxyPort ? { proxy: { server: `http://127.0.0.1:${proxyPort}` } } : {}),
+    });
+  }
+  let page = ctx.pages()[0];
+  if (!page) {
+    page = await ctx.newPage();
+  }
+  entry.context = ctx;
+  entry.page = page;
+  return page;
+}
+
+export function getEntry(targetId: string): BrowserTargetEntry | CamoufoxEntryWithDriver {
+  if (isCamoufoxTargetId(targetId)) {
+    const cam = getCamoufoxInterceptor();
+    const entry = cam?.getEntry(targetId) as CamoufoxEntryWithDriver | undefined;
+    if (!entry) throw new Error(`Browser target '${targetId}' not found. Is it still running?`);
+    return entry;
+  }
+  const entry = getBrowserInterceptor().getEntry(targetId);
+  if (!entry) throw new Error(`Browser target '${targetId}' not found. Is it still running?`);
+  return entry;
+}
+
+/**
+ * Cloakbrowser-only entry getter. Use when the caller needs cloakbrowser
+ * features that camoufox doesn't implement yet — `consoleBuffer` (event
+ * recording) or pre-warmed `context` (synchronous cookie access). Camoufox
+ * targets get a clear error instead of a deep type-mismatch.
+ */
+export function getBrowserEntry(targetId: string): BrowserTargetEntry {
+  if (isCamoufoxTargetId(targetId)) {
+    throw new Error(
+      `Tool not yet supported on camoufox targets ('${targetId}'). Use cloakbrowser ` +
+      `(interceptor_browser_launch) for console / cookie inspection until camoufox parity lands.`,
+    );
+  }
   const entry = getBrowserInterceptor().getEntry(targetId);
   if (!entry) throw new Error(`Browser target '${targetId}' not found. Is it still running?`);
   return entry;
 }
 
-export function getPageForTarget(targetId: string): Page {
+export async function getPageForTarget(targetId: string): Promise<Page> {
   const entry = getEntry(targetId);
-  if (entry.page.isClosed()) {
+  if (isCamoufoxTargetId(targetId)) {
+    return ensureCamoufoxPage(entry as CamoufoxEntryWithDriver);
+  }
+  const browserEntry = entry as BrowserTargetEntry;
+  if (browserEntry.page.isClosed()) {
     throw new Error(`Page for browser target '${targetId}' is closed.`);
   }
-  return entry.page;
+  return browserEntry.page;
 }

src/humanizer/engine.ts

@@ -81,7 +81,7 @@ class HumanizerEngine {
     x: number,
     y: number,
   ): Promise<{ totalMs: number; eventsDispatched: number }> {
-    const page = getPageForTarget(targetId);
+    const page = await getPageForTarget(targetId);
     const start = Date.now();
     await page.mouse.move(x, y);
     const state = getMouseState(targetId);
@@ -98,7 +98,7 @@ class HumanizerEngine {
       timeoutMs?: number;
     } = {},
   ): Promise<{ totalMs: number; eventsDispatched: number; clickedAt: Point; resolvedBy: string }> {
-    const page = getPageForTarget(targetId);
+    const page = await getPageForTarget(targetId);
     const button = opts.button ?? "left";
     const clickCount = opts.clickCount ?? 1;
     const timeout = opts.timeoutMs ?? 15_000;
@@ -139,7 +139,7 @@ class HumanizerEngine {
     text: string,
     opts: { delayMs?: number } = {},
   ): Promise<{ totalMs: number; eventsDispatched: number; charsTyped: number }> {
-    const page = getPageForTarget(targetId);
+    const page = await getPageForTarget(targetId);
     const start = Date.now();
     await page.keyboard.type(text, opts.delayMs !== undefined ? { delay: opts.delayMs } : undefined);
     return {
@@ -154,7 +154,7 @@ class HumanizerEngine {
     deltaY: number,
     deltaX?: number,
   ): Promise<{ totalMs: number; eventsDispatched: number }> {
-    const page = getPageForTarget(targetId);
+    const page = await getPageForTarget(targetId);
     const start = Date.now();
     await page.mouse.wheel(deltaX ?? 0, deltaY);
     return { totalMs: Date.now() - start, eventsDispatched: 1 };
@@ -165,7 +165,7 @@ class HumanizerEngine {
     durationMs: number,
     intensity: "subtle" | "normal" = "subtle",
   ): Promise<{ totalMs: number; eventsDispatched: number }> {
-    const page = getPageForTarget(targetId);
+    const page = await getPageForTarget(targetId);
     const state = getMouseState(targetId);
     const start = Date.now();
     let eventsDispatched = 0;