feat(camoufox): expose fingerprint introspection

Author: yfe404

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 3.3.2 — 2026-05-17
+
+- **Camoufox OS default + introspection:** `interceptor_camoufox_launch` now
+  defaults fingerprint generation to the host OS instead of Camoufox's upstream
+  random OS list, while still allowing explicit `os` overrides. Launch/list/info
+  responses now include a safe fingerprint summary (resolved OS, UA, platform,
+  OSCPU, screen/window, WebGL, font/voice counts) without exposing raw Camoufox
+  config or process environment.
+
 ## 3.3.1 — 2026-05-17
 
 - **Camoufox MCP parity:** `camoufox_*` targets now work with console and
@@ -24,7 +33,7 @@ Consequences for callers:
 
 - `inject_init_script` patches NOW reach the page (`Object.defineProperty(navigator, 'webdriver', ...)` actually affects what site scripts see) — the camoufox#48 limitation no longer applies on this build. The trade: those patches are observable by anti-bot code via `Function.prototype.toString` and `window` enumeration.
 - `interceptor_browser_evaluate` mutations (writes to `window`, prototype patches) become observable to page scripts. Read-only evals stay safe.
-- `world: "main"` and `world: "isolated"` accept the same args for API compatibility but run in the same realm on cloverlabs/FF150. `mw:` prefix and `main_world_eval: true` launch flag are inert.
+- `world: "main"` and `world: "isolated"` accept the same script args for API compatibility but run in the same realm on cloverlabs/FF150. `main_world_eval: true` still gates explicit `world: "main"` calls; once enabled, the `mw:` prefix does not create a separate realm on this build.
 
 Tool descriptions, README "Worlds and isolation" section, and `test/integration/browser-js-inject.test.ts` were updated to reflect the new behavior. The probe at `scripts/camoufox-world-probe.ts` re-verifies the model on any installed build.
 
@@ -50,7 +59,7 @@ Tool descriptions, README "Worlds and isolation" section, and `test/integration/
 
 ### Notes
 
-- Host requirements (only when using camoufox): Python 3 + `pip install "camoufox[geoip]"` + `python3 -m camoufox fetch` + NSS `certutil` (`libnss3-tools`/`nss-tools`/`brew install nss`). If `certutil` is missing the launcher still runs but the proxy CA is not trusted — HTTPS pages show cert errors and proxy traffic is still captured.
+- Original host requirements used the daijro/camoufox package line. Current Camoufox users should follow the cloverlabs/Firefox 150 install note in 3.3.0 above. NSS `certutil` (`libnss3-tools`/`nss-tools`/`brew install nss`) is still required for proxy CA trust.
 - No new npm dependencies. `playwright-core` (already a runtime dep for cloakbrowser) provides the `firefox.connect(wsUrl)` client.
 - All proxy-side capabilities — traffic capture, TLS fingerprint capture, rules, header injection, mocks, sessions, replay, upstream chaining, JA3 spoofing — apply to camoufox automatically because the proxy sits in front of it.
 

DEMO.md

@@ -28,8 +28,9 @@ explain what *would* have happened and return to the menu. Never stop the demo o
 a failure. First `interceptor_browser_launch` call may take 30–60 s while the
 ~200 MB stealth Chromium binary downloads.
 
-**Tool prefix:** All tools are from the `proxy` MCP server — call them as
-`mcp__proxy__<tool_name>`.
+**Tool prefix:** All tools are from this MCP server. If configured with the
+README's `proxy-mcp` alias, call them as `mcp__proxy-mcp__<tool_name>`. If the
+local client aliases the server as `proxy`, call them as `mcp__proxy__<tool_name>`.
 
 ---
 

README.md

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

package-lock.json

@@ -109,15 +109,14 @@ export function getEntry(targetId: string): BrowserTargetEntry | CamoufoxEntryWi
 
 /**
  * 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.
+ * internals rather than the shared page/context helpers. 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.`,
+      `Internal cloakbrowser-only entry requested for camoufox target ('${targetId}'). ` +
+      "Use the shared browser tools for camoufox targets.",
     );
   }
   const entry = getBrowserInterceptor().getEntry(targetId);

package.json

@@ -1,10 +1,10 @@
 /**
- * Humanizer engine — thin wrappers over cloakbrowser-patched Playwright.
+ * Humanizer engine — thin wrappers over backend Playwright pages.
  *
- * cloakbrowser's `humanize: true` already patches page.click / page.mouse.move /
- * page.mouse.click / page.keyboard.type / page.hover / page.type with Bezier
- * paths, realistic typing, and CDP-trusted Shift handling. This engine just
- * routes tool calls to those patched methods — no duplicate timing code.
+ * The engine routes tool calls to page.mouse / page.keyboard / locator methods.
+ * Backend-level humanization comes from the launched browser config
+ * (cloakbrowser humanize patches or Camoufox options), not from a local timing
+ * model in proxy-mcp.
  */
 
 import type { Page, Locator } from "playwright-core";

src/browser/session.ts

@@ -55,7 +55,7 @@ function arg(name: string, fallback: string): string {
 /* ------------------------------------------------------------------ */
 
 function createMcpServer(): McpServer {
-  const server = new McpServer({ name: "proxy", version: "3.3.1" });
+  const server = new McpServer({ name: "proxy", version: "3.3.2" });
 
   initInterceptors();
 

src/humanizer/engine.ts

@@ -31,6 +31,8 @@ import type {
   Interceptor, InterceptorMetadata, ActivateOptions, ActivateResult, ActiveTarget,
 } from "./types.js";
 
+type CamoufoxOs = "windows" | "macos" | "linux";
+
 export interface CamoufoxTargetEntry {
   target: ActiveTarget;
   process: ChildProcess;
@@ -48,6 +50,55 @@ const FORWARDED_PARAMS = [
 
 type CamoufoxParam = (typeof FORWARDED_PARAMS)[number];
 
+interface CamoufoxFingerprintSummary {
+  os?: CamoufoxOs;
+  requested_os?: unknown;
+  os_source?: "caller" | "host_default" | "resolved";
+  user_agent?: string;
+  platform?: string;
+  oscpu?: string;
+  app_version?: string;
+  locale?: unknown;
+  accept_language?: string;
+  timezone?: string;
+  screen?: Record<string, unknown>;
+  window?: Record<string, unknown>;
+  webgl?: Record<string, unknown>;
+  fonts_count?: number;
+  voices_count?: number;
+}
+
+interface WsHandshake {
+  wsUrl: string;
+  ts: number;
+  fingerprint?: CamoufoxFingerprintSummary;
+}
+
+export function hostFingerprintOs(platform: NodeJS.Platform = process.platform): CamoufoxOs | undefined {
+  if (platform === "win32") return "windows";
+  if (platform === "darwin") return "macos";
+  if (platform === "linux") return "linux";
+  return undefined;
+}
+
+function firstString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
+
+function inferOsFromFingerprint(fingerprint: CamoufoxFingerprintSummary | undefined): CamoufoxOs | undefined {
+  if (fingerprint?.os) return fingerprint.os;
+  const haystack = [
+    fingerprint?.user_agent,
+    fingerprint?.platform,
+    fingerprint?.oscpu,
+    fingerprint?.app_version,
+  ].filter(Boolean).join(" ").toLowerCase();
+  if (haystack.includes("windows") || haystack.includes("win32")) return "windows";
+  if (haystack.includes("macintosh") || haystack.includes("mac os") || haystack.includes("macintel")) return "macos";
+  if (haystack.includes("linux") || haystack.includes("x11")) return "linux";
+  return undefined;
+}
+
 export class CamoufoxInterceptor implements Interceptor {
   readonly id = "camoufox";
   readonly name = "Camoufox (anti-detect Firefox via Playwright)";
@@ -84,12 +135,17 @@ export class CamoufoxInterceptor implements Interceptor {
     const pythonExe = typeof options.python_executable === "string" && options.python_executable
       ? options.python_executable
       : "python3";
+    const requestedOs = options.os;
+    const defaultOs = requestedOs === undefined ? hostFingerprintOs() : undefined;
+    const osForLaunch = requestedOs ?? defaultOs;
+    const osSource = requestedOs === undefined ? "host_default" : "caller";
 
     const params: Record<string, unknown> = {
       proxy: { server: `http://127.0.0.1:${proxyPort}` },
       headless,
       block_webrtc: blockWebrtc,
       geoip,
+      ...(osForLaunch !== undefined ? { os: osForLaunch } : {}),
     };
 
     for (const key of FORWARDED_PARAMS as readonly CamoufoxParam[]) {
@@ -143,9 +199,9 @@ export class CamoufoxInterceptor implements Interceptor {
       },
     });
 
-    let wsUrl: string;
+    let handshake: WsHandshake;
     try {
-      wsUrl = await awaitWsEndpoint(proc, wsEndpointFile, DEFAULT_LAUNCH_TIMEOUT_MS);
+      handshake = await awaitWsHandshake(proc, wsEndpointFile, DEFAULT_LAUNCH_TIMEOUT_MS);
     } catch (e) {
       try { proc.kill("SIGKILL"); } catch { /* already gone */ }
       await rm(launcherDir, { recursive: true, force: true }).catch(() => {});
@@ -155,20 +211,30 @@ export class CamoufoxInterceptor implements Interceptor {
 
     const pid = typeof proc.pid === "number" ? proc.pid : 0;
     const targetId = `camoufox_${pid}_${Date.now()}`;
+    const fingerprint: CamoufoxFingerprintSummary = {
+      ...(handshake.fingerprint ?? {}),
+      requested_os: requestedOs ?? null,
+      os_source: osSource,
+    };
+    const effectiveOs = inferOsFromFingerprint(fingerprint) ?? firstString(osForLaunch) ?? null;
+    if (effectiveOs) fingerprint.os = effectiveOs as CamoufoxOs;
 
     const details: Record<string, unknown> = {
-      wsUrl,
+      wsUrl: handshake.wsUrl,
       proxyPort,
       headless,
       humanize: options.humanize ?? null,
       geoip,
       block_webrtc: blockWebrtc,
       main_world_eval: Boolean(params.main_world_eval),
-      ...(options.os !== undefined ? { os: options.os } : {}),
+      os: effectiveOs,
+      requested_os: requestedOs ?? null,
+      default_os: defaultOs ?? null,
+      fingerprint,
       ...(options.locale !== undefined ? { locale: options.locale } : {}),
       profileDir,
       certutil: profileDir !== null,
-      playwright_connect: `await firefox.connect('${wsUrl}')`,
+      playwright_connect: `await firefox.connect('${handshake.wsUrl}')`,
     };
 
     const target: ActiveTarget = {
@@ -178,7 +244,7 @@ export class CamoufoxInterceptor implements Interceptor {
       details,
     };
 
-    const entry: CamoufoxTargetEntry = { target, process: proc, wsUrl, profileDir, launcherDir };
+    const entry: CamoufoxTargetEntry = { target, process: proc, wsUrl: handshake.wsUrl, profileDir, launcherDir };
     this.launched.set(targetId, entry);
 
     proc.once("exit", () => {
@@ -236,6 +302,7 @@ export class CamoufoxInterceptor implements Interceptor {
       name: this.name,
       description:
         "Launch camoufox (anti-detect Firefox) as a Playwright WS server with proxy + NSS CA trust. " +
+        "Defaults fingerprint generation to the host OS and returns safe fingerprint introspection. " +
         "Drive the returned target_id through the same `interceptor_browser_*` and `humanizer_*` " +
         "tools as cloakbrowser. Requires Python + `pip install cloverlabs-camoufox[geoip]`.",
       isActivable: await this.isActivable(),
@@ -326,6 +393,67 @@ export function buildLauncherScript(
     "",
     `params = json.loads('${escapedParams}')`,
     "config = launch_options(**params)",
+    "",
+    "def _pick(src, key):",
+    "    return src.get(key) if isinstance(src, dict) and key in src else None",
+    "",
+    "def _count_list(value):",
+    "    return len(value) if isinstance(value, list) else None",
+    "",
+    "def _infer_os(cam):",
+    "    haystack = ' '.join(str(x or '') for x in [",
+    "        _pick(cam, 'navigator.userAgent'),",
+    "        _pick(cam, 'navigator.platform'),",
+    "        _pick(cam, 'navigator.oscpu'),",
+    "        _pick(cam, 'navigator.appVersion'),",
+    "    ]).lower()",
+    "    if 'windows' in haystack or 'win32' in haystack:",
+    "        return 'windows'",
+    "    if 'macintosh' in haystack or 'mac os' in haystack or 'macintel' in haystack:",
+    "        return 'macos'",
+    "    if 'linux' in haystack or 'x11' in haystack:",
+    "        return 'linux'",
+    "    return None",
+    "",
+    "def _fingerprint_summary(config):",
+    "    env = config.get('env') if isinstance(config, dict) else {}",
+    "    raw = env.get('CAMOU_CONFIG_1') if isinstance(env, dict) else None",
+    "    if not raw:",
+    "        return None",
+    "    try:",
+    "        cam = json.loads(raw)",
+    "    except Exception:",
+    "        return None",
+    "    return {",
+    "        'os': _infer_os(cam),",
+    "        'user_agent': _pick(cam, 'navigator.userAgent'),",
+    "        'platform': _pick(cam, 'navigator.platform'),",
+    "        'oscpu': _pick(cam, 'navigator.oscpu'),",
+    "        'app_version': _pick(cam, 'navigator.appVersion'),",
+    "        'locale': _pick(cam, 'locale:language') or _pick(cam, 'headers.Accept-Language'),",
+    "        'accept_language': _pick(cam, 'headers.Accept-Language'),",
+    "        'timezone': _pick(cam, 'timezone'),",
+    "        'screen': {",
+    "            'width': _pick(cam, 'screen.width'),",
+    "            'height': _pick(cam, 'screen.height'),",
+    "            'avail_width': _pick(cam, 'screen.availWidth'),",
+    "            'avail_height': _pick(cam, 'screen.availHeight'),",
+    "            'color_depth': _pick(cam, 'screen.colorDepth'),",
+    "            'pixel_depth': _pick(cam, 'screen.pixelDepth'),",
+    "        },",
+    "        'window': {",
+    "            'outer_width': _pick(cam, 'window.outerWidth'),",
+    "            'outer_height': _pick(cam, 'window.outerHeight'),",
+    "        },",
+    "        'webgl': {",
+    "            'vendor': _pick(cam, 'webGl:vendor'),",
+    "            'renderer': _pick(cam, 'webGl:renderer'),",
+    "        },",
+    "        'fonts_count': _count_list(_pick(cam, 'fonts')),",
+    "        'voices_count': _count_list(_pick(cam, 'voices')),",
+    "    }",
+    "",
+    "fingerprint_summary = _fingerprint_summary(config)",
     "nodejs = get_nodejs()",
     "data = orjson.dumps(to_camel_case_dict(config))",
     "",
@@ -355,7 +483,7 @@ export function buildLauncherScript(
     "        m = _WS_RE.search(_ANSI.sub('', line))",
     "        if m:",
     "            _ws_done = True",
-    "            payload = json.dumps({'wsUrl': m.group(1), 'ts': int(time.time())})",
+    "            payload = json.dumps({'wsUrl': m.group(1), 'ts': int(time.time()), 'fingerprint': fingerprint_summary})",
     "            d = os.path.dirname(_WS_FILE) or '.'",
     "            fd, tmp = tempfile.mkstemp(prefix='.ws-', dir=d)",
     "            with os.fdopen(fd, 'w') as f:",
@@ -368,11 +496,6 @@ export function buildLauncherScript(
   ].join("\n");
 }
 
-interface WsHandshake {
-  wsUrl: string;
-  ts: number;
-}
-
 /**
  * Poll `wsEndpointFile` until the python wrapper writes the handshake
  * JSON, or `proc` exits, or the timeout fires — whichever happens first.
@@ -383,11 +506,20 @@ interface WsHandshake {
  * wrapper's problem (it can update its own regex), and Node only
  * reads a structured file.
  */
-export function awaitWsEndpoint(
+export async function awaitWsEndpoint(
   proc: ChildProcess,
   wsEndpointFile: string,
   timeoutMs: number,
 ): Promise<string> {
+  const handshake = await awaitWsHandshake(proc, wsEndpointFile, timeoutMs);
+  return handshake.wsUrl;
+}
+
+export function awaitWsHandshake(
+  proc: ChildProcess,
+  wsEndpointFile: string,
+  timeoutMs: number,
+): Promise<WsHandshake> {
   return new Promise((resolve, reject) => {
     let settled = false;
     let stderrTail = "";
@@ -438,7 +570,7 @@ export function awaitWsEndpoint(
         if (typeof handshake.wsUrl === "string" && handshake.wsUrl.startsWith("ws://")) {
           settled = true;
           cleanup();
-          resolve(handshake.wsUrl);
+          resolve(handshake);
           return;
         }
         // File present but malformed — keep polling; the python wrapper