camoufox-playwright-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# camoufox-playwright-cli
+
+Official [`@playwright/cli`](https://github.com/microsoft/playwright-cli) (Microsoft's Playwright CLI — open, click, fill, snapshot, tabs, network, tracing, video, ...), driven by [Camoufox](https://camoufox.com) instead of stock Chromium/Firefox, so the browser doesn't look automated.
+
+No fork of playwright-cli, no monkey-patching. Camoufox's stealth is just three standard Playwright launch options — `executablePath`, `firefoxUserPrefs`, and a `CAMOU_CONFIG_*` env blob — and playwright-cli already passes those through from a config file. This package generates that config for you and manages it as named **profiles**.
+
+Short alias: `cpw` (same binary as `camoufox-playwright-cli`).
+
+## Install
+
+```bash
+npm install -g camoufox-playwright-cli
+cpw install
+```
+
+`install` downloads the Camoufox browser binary (shared cache, only happens once even across other Camoufox-based tools) and generates a `default` profile.
+
+## Profiles
+
+A profile is a fingerprint identity + its own isolated browser data (cookies, localStorage, login sessions) — think of it as "one persona". The `default` profile is created automatically and its fingerprint is generated from **your actual machine** where possible:
+
+- Real GPU vendor (via `Get-CimInstance Win32_VideoController` on Windows) — matched to the closest vendor bucket in Camoufox's curated WebGL database. Camoufox only ships a fixed, vetted set of older reference GPU models per vendor (no RTX 20/30/40-series entries at all, for example), so the *vendor* will match your real hardware but the exact renderer string won't be your literal card model. That vendor-match is what fingerprinting scripts actually cross-check; matching the exact model isn't possible through Camoufox's public API without maintaining a separate spoofing database, which is out of scope here.
+- Real screen resolution, locale, and timezone (via `Intl` + WMI).
+
+If any of these can't be detected (non-Windows, sandboxed environment, etc.) that field silently falls back to Camoufox's own randomized default — it never errors out.
+
+```bash
+cpw profile list
+cpw profile create work
+cpw profile rotate work      # wipes cookies + regenerates fingerprint
+cpw profile delete work
+```
+
+Rotating or deleting a profile always wipes its browser session data first — keeping old cookies with a new fingerprint is itself an inconsistency signal, so we don't allow that combination.
+
+## Usage
+
+Everything besides `install` and `profile` is forwarded verbatim to the real `playwright-cli`, with `--profile` mapped to its `-s=` session flag and (for `open`) `--config=` pointed at that profile's generated config:
+
+```bash
+cpw open https://example.com
+cpw snapshot
+cpw click e3
+cpw fill e5 "hello"
+cpw screenshot --filename out.png
+cpw close
+
+cpw --profile=work open https://example.com   # separate identity + separate cookies
+```
+
+See the [playwright-cli command reference](https://github.com/microsoft/playwright-cli) for the full list — tabs, network routing, storage state, tracing, video recording, etc. all work unmodified.
+
+## How it works
+
+- [`camoufox-js`](https://github.com/apify/camoufox-js)'s `launchOptions()` computes `{executablePath, env, firefoxUserPrefs}` for a given fingerprint.
+- We write that into `~/.camoufox-playwright-cli/profiles/<name>/cli.config.json`, in the shape `@playwright/cli` expects (`browser.launchOptions`).
+- `cpw <command>` is a thin wrapper: it ensures that config exists, then spawns the real `playwright-cli` binary with `-s=<profile>` (and `--config=` on `open`) injected.
+
+Dependency versions (`@playwright/cli`, `camoufox-js`) are pinned exactly, not range-matched — both are young/prerelease packages and an unpinned `npm install` could silently pick up a breaking protocol change between Playwright's internal Firefox/Juggler driver and Camoufox's patched binary. Upgrades are deliberate, one version bump at a time, tested against the checks in this README before being released.
+
+## Security note
+
+The `env` passed to the Camoufox process is an explicit allowlist (`PATH`, temp dirs, etc.) — never your full shell environment. Don't widen it without checking what secrets might be sitting in `process.env`.

package/bin/cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+  DEFAULT_PROFILE,
+  ensureProfile,
+  profileConfigPath,
+  profileExists,
+  listProfiles,
+  deleteProfileFiles,
+} from "../src/profiles.js";
+import { playwrightCliBin, camoufoxJsBin } from "../src/paths.js";
+
+function extractProfileFlag(argv) {
+  let profile = DEFAULT_PROFILE;
+  const rest = [];
+  for (const arg of argv) {
+    if (arg.startsWith("--profile=")) {
+      profile = arg.slice("--profile=".length);
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { profile, rest };
+}
+
+async function main() {
+  const { profile, rest } = extractProfileFlag(process.argv.slice(2));
+  const [command, ...args] = rest;
+
+  switch (command) {
+    case "install":
+      return runInstall();
+    case "profile":
+      return runProfile(args);
+    case undefined:
+    case "-h":
+    case "--help":
+      return printHelp();
+    default:
+      return runPlaywrightCli(profile, rest);
+  }
+}
+
+function runCamoufoxFetch() {
+  const result = spawnSync(process.execPath, [camoufoxJsBin(), "fetch"], { stdio: "inherit" });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+// Stops the daemon (if running) and wipes its browser profile dir (cookies,
+// storage). Used before rotate/delete so a new fingerprint never keeps the
+// old identity's login state — a fingerprint change with stale cookies is
+// itself an inconsistency signal.
+function resetSessionData(profileName) {
+  spawnSync(process.execPath, [playwrightCliBin(), `-s=${profileName}`, "close"], { stdio: "ignore" });
+  spawnSync(process.execPath, [playwrightCliBin(), `-s=${profileName}`, "delete-data"], { stdio: "ignore" });
+}
+
+async function runInstall() {
+  console.log("Downloading Camoufox browser binary (this only needs to run once)...");
+  runCamoufoxFetch();
+
+  console.log("\nGenerating default profile from your machine's real parameters...");
+  const file = await ensureProfile(DEFAULT_PROFILE);
+  console.log(`Profile written to ${file}`);
+  console.log("\nDone. Try: camoufox-playwright-cli open https://example.com");
+}
+
+async function runProfile(args) {
+  const [sub, name] = args;
+  switch (sub) {
+    case "list": {
+      const profiles = await listProfiles();
+      if (profiles.length === 0) {
+        console.log("No profiles yet. Run `camoufox-playwright-cli install` first.");
+        return;
+      }
+      for (const p of profiles) {
+        console.log(`${p.name}${p.name === DEFAULT_PROFILE ? " (default)" : ""}`);
+        console.log(`  created: ${p.createdAt}`);
+        console.log(`  os: ${p.os}  locale: ${p.locale}  timezone: ${p.timezone}`);
+        console.log(`  screen: ${JSON.stringify(p.screen)}`);
+        console.log(`  gpu: ${JSON.stringify(p.gpu)}`);
+      }
+      return;
+    }
+    case "create": {
+      if (!name) return console.error("Usage: camoufox-playwright-cli profile create <name>");
+      if (profileExists(name)) return console.error(`Profile "${name}" already exists. Use \`profile rotate ${name}\` to regenerate it.`);
+      const file = await ensureProfile(name);
+      console.log(`Created profile "${name}" -> ${file}`);
+      return;
+    }
+    case "rotate": {
+      const target = name || DEFAULT_PROFILE;
+      if (!profileExists(target)) return console.error(`Profile "${target}" does not exist. Use \`profile create ${target}\` first.`);
+      resetSessionData(target);
+      const file = await ensureProfile(target, { rotate: true });
+      console.log(`Rotated profile "${target}" (browser data wiped, new fingerprint generated) -> ${file}`);
+      return;
+    }
+    case "delete": {
+      if (!name) return console.error("Usage: camoufox-playwright-cli profile delete <name>");
+      if (name === DEFAULT_PROFILE) return console.error(`Refusing to delete the "${DEFAULT_PROFILE}" profile. Use \`profile rotate\` instead.`);
+      resetSessionData(name);
+      const existed = await deleteProfileFiles(name);
+      console.log(existed ? `Deleted profile "${name}"` : `Profile "${name}" did not exist`);
+      return;
+    }
+    default:
+      console.log(`Usage:
+  camoufox-playwright-cli profile list
+  camoufox-playwright-cli profile create <name>
+  camoufox-playwright-cli profile rotate [name]   (defaults to "default")
+  camoufox-playwright-cli profile delete <name>`);
+  }
+}
+
+async function runPlaywrightCli(profile, argv) {
+  if (!profileExists(profile)) {
+    if (profile === DEFAULT_PROFILE) {
+      console.log("No default profile yet - running setup first...");
+      runCamoufoxFetch();
+      await ensureProfile(DEFAULT_PROFILE);
+    } else {
+      console.error(`Profile "${profile}" does not exist. Create it with: camoufox-playwright-cli profile create ${profile}`);
+      process.exit(1);
+    }
+  }
+
+  const configFile = profileConfigPath(profile);
+  const finalArgs = [...argv];
+
+  if (!finalArgs.some((a) => a === "-s" || a.startsWith("-s="))) {
+    finalArgs.push(`-s=${profile}`);
+  }
+  if (finalArgs[0] === "open" && !finalArgs.some((a) => a.startsWith("--config"))) {
+    finalArgs.push(`--config=${configFile}`);
+  }
+
+  const result = spawnSync(process.execPath, [playwrightCliBin(), ...finalArgs], { stdio: "inherit" });
+  process.exit(result.status ?? 0);
+}
+
+function printHelp() {
+  console.log(`camoufox-playwright-cli (alias: cpw) - Playwright CLI (@playwright/cli), driven by Camoufox (stealth Firefox)
+
+Setup (run once):
+  cpw install                 Download Camoufox + generate the "default" profile
+
+Profiles (fingerprint + isolated browser data, one per identity):
+  cpw profile list
+  cpw profile create <name>
+  cpw profile rotate [name]    Wipe cookies + regenerate fingerprint (defaults to "default")
+  cpw profile delete <name>
+
+Everything else is forwarded to the real playwright-cli, pointed at Camoufox.
+Use --profile=<name> to pick which identity to drive (defaults to "default"):
+  cpw open <url>
+  cpw --profile=work open <url>
+  cpw snapshot
+  cpw click <ref>
+  cpw fill <ref> <text>
+  cpw screenshot
+  cpw close
+
+("camoufox-playwright-cli" also works everywhere "cpw" does — same binary, two names.)
+
+See https://github.com/microsoft/playwright-cli for the full command reference.
+`);
+}
+
+main();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "camoufox-playwright-cli",
+  "version": "0.1.0",
+  "description": "Playwright CLI (@playwright/cli), driven by Camoufox for stealth browsing. Profile-based: auto-generated default fingerprint on install, create/rotate/delete named profiles.",
+  "type": "module",
+  "bin": {
+    "camoufox-playwright-cli": "bin/cli.js",
+    "cpw": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Shun",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShunL12324/camoufox-playwright-cli.git"
+  },
+  "keywords": [
+    "camoufox",
+    "playwright",
+    "stealth",
+    "anti-detect",
+    "browser-automation",
+    "cli",
+    "profiles"
+  ],
+  "dependencies": {
+    "@playwright/cli": "0.1.18",
+    "better-sqlite3": "13.0.1",
+    "camoufox-js": "0.12.0"
+  }
+}

package/src/host.js

@@ -0,0 +1,86 @@
+import { execFileSync } from "node:child_process";
+
+// Best-effort detection of real host parameters so the generated fingerprint
+// matches the machine it's actually running on (real GPU vendor, real
+// screen size, real locale/timezone) instead of a fully random combo that
+// can look inconsistent (e.g. a 4K screen paired with a decade-old GPU).
+// Every probe is independently wrapped in try/catch: if a probe fails
+// (unsupported OS, no PowerShell, sandboxed env, ...) that field is simply
+// omitted and camoufox-js falls back to its own randomized default for it.
+
+function detectOS() {
+  switch (process.platform) {
+    case "win32":
+      return "windows";
+    case "darwin":
+      return "macos";
+    case "linux":
+      return "linux";
+    default:
+      return undefined;
+  }
+}
+
+function detectLocaleAndTimezone() {
+  try {
+    const opts = Intl.DateTimeFormat().resolvedOptions();
+    return { locale: opts.locale, timezone: opts.timeZone };
+  } catch {
+    return {};
+  }
+}
+
+function detectScreen() {
+  if (process.platform !== "win32") return undefined;
+  try {
+    const out = execFileSync(
+      "powershell",
+      [
+        "-NoProfile",
+        "-Command",
+        "Get-CimInstance Win32_VideoController | Select-Object -First 1 CurrentHorizontalResolution,CurrentVerticalResolution | ConvertTo-Json",
+      ],
+      { encoding: "utf-8", timeout: 10_000 },
+    );
+    const data = JSON.parse(out);
+    const width = data.CurrentHorizontalResolution;
+    const height = data.CurrentVerticalResolution;
+    if (!width || !height) return undefined;
+    return { width, height };
+  } catch {
+    return undefined;
+  }
+}
+
+// Maps a real GPU name string to one of the vendor buckets Camoufox ships
+// curated (vendor, renderer) WebGL fingerprints for. Camoufox's database
+// only covers a fixed, vetted set of older GPU models per vendor (see
+// README for why) - we can match the real vendor, not the exact model.
+function detectGpuVendor() {
+  if (process.platform !== "win32") return undefined;
+  try {
+    const name = execFileSync(
+      "powershell",
+      ["-NoProfile", "-Command", "(Get-CimInstance Win32_VideoController | Select-Object -First 1).Name"],
+      { encoding: "utf-8", timeout: 10_000 },
+    ).trim();
+    if (!name) return undefined;
+    if (/nvidia|geforce|quadro|rtx|gtx/i.test(name)) return { raw: name, vendor: "nvidia" };
+    if (/amd|radeon/i.test(name)) return { raw: name, vendor: "amd" };
+    if (/intel/i.test(name)) return { raw: name, vendor: "intel" };
+    return { raw: name, vendor: undefined };
+  } catch {
+    return undefined;
+  }
+}
+
+export function detectHost() {
+  const { locale, timezone } = detectLocaleAndTimezone();
+  return {
+    os: detectOS(),
+    locale,
+    timezone,
+    screen: detectScreen(),
+    gpu: detectGpuVendor(),
+  };
+}

package/src/paths.js

@@ -0,0 +1,19 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export function playwrightCliBin() {
+  const pkgJsonPath = require.resolve("@playwright/cli/package.json");
+  const pkgDir = path.dirname(pkgJsonPath);
+  const pkg = require(pkgJsonPath);
+  return path.join(pkgDir, pkg.bin["playwright-cli"]);
+}
+
+export function camoufoxJsBin() {
+  const pkgJsonPath = require.resolve("camoufox-js/package.json");
+  const pkgDir = path.dirname(pkgJsonPath);
+  const pkg = require(pkgJsonPath);
+  const bin = typeof pkg.bin === "string" ? pkg.bin : Object.values(pkg.bin)[0];
+  return path.join(pkgDir, bin);
+}

package/src/profiles.js

@@ -0,0 +1,145 @@
+import { launchOptions } from "camoufox-js";
+import { existsSync } from "node:fs";
+import { mkdir, writeFile, readFile, rm, readdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { detectHost } from "./host.js";
+import { pickVendorMatchedWebgl } from "./webgl.js";
+
+export const DEFAULT_PROFILE = "default";
+
+// Only pass through what the Camoufox binary actually needs to start.
+// launchOptions() defaults env to process.env, which would leak every
+// secret in the caller's shell into the CAMOU_CONFIG env blob and into
+// the config.json file on disk. Never widen this without a reason.
+const SAFE_ENV_KEYS = [
+  "PATH",
+  "SYSTEMROOT",
+  "WINDIR",
+  "TEMP",
+  "TMP",
+  "USERPROFILE",
+  "HOME",
+  "DISPLAY", // Linux/X11 headed mode
+];
+
+function safeEnv() {
+  const env = {};
+  for (const key of SAFE_ENV_KEYS) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  return env;
+}
+
+const ROOT_DIR = path.join(os.homedir(), ".camoufox-playwright-cli");
+const PROFILES_DIR = path.join(ROOT_DIR, "profiles");
+
+function isValidName(name) {
+  return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+export function profileDir(name) {
+  if (!isValidName(name)) {
+    throw new Error(`Invalid profile name "${name}" (use letters, numbers, - and _ only)`);
+  }
+  return path.join(PROFILES_DIR, name);
+}
+
+export function profileConfigPath(name) {
+  return path.join(profileDir(name), "cli.config.json");
+}
+
+function profileMetaPath(name) {
+  return path.join(profileDir(name), "meta.json");
+}
+
+export function profileExists(name) {
+  return existsSync(profileConfigPath(name));
+}
+
+export async function listProfiles() {
+  if (!existsSync(PROFILES_DIR)) return [];
+  const names = await readdir(PROFILES_DIR);
+  const profiles = [];
+  for (const name of names) {
+    if (!profileExists(name)) continue;
+    const meta = JSON.parse(await readFile(profileMetaPath(name), "utf-8").catch(() => "{}"));
+    profiles.push({ name, ...meta });
+  }
+  return profiles;
+}
+
+export async function readProfileConfig(name) {
+  if (!profileExists(name)) return null;
+  return JSON.parse(await readFile(profileConfigPath(name), "utf-8"));
+}
+
+// Creates a profile if it doesn't exist, or regenerates it in place when
+// `rotate` is true. The generated fingerprint prefers real host parameters
+// (GPU vendor, screen size, locale/timezone) over random ones — see
+// host.js and webgl.js for what's detected and why exact GPU model spoofing
+// isn't possible. Any detection failure just falls back to camoufox-js's
+// own randomized default for that field; it never throws.
+export async function ensureProfile(name, { rotate = false } = {}) {
+  if (!rotate && profileExists(name)) {
+    return profileConfigPath(name);
+  }
+
+  await mkdir(profileDir(name), { recursive: true });
+
+  const host = detectHost();
+  const targetOs = host.os || "windows";
+  const webglConfig = host.gpu?.vendor
+    ? pickVendorMatchedWebgl(targetOs, host.gpu.vendor)
+    : undefined;
+
+  const opts = await launchOptions({
+    os: targetOs,
+    humanize: true,
+    locale: host.locale ? [host.locale] : undefined,
+    screen: host.screen
+      ? {
+          minWidth: host.screen.width,
+          maxWidth: host.screen.width,
+          minHeight: host.screen.height,
+          maxHeight: host.screen.height,
+        }
+      : undefined,
+    webgl_config: webglConfig,
+    env: safeEnv(),
+  });
+
+  const config = {
+    browser: {
+      browserName: "firefox",
+      launchOptions: {
+        executablePath: opts.executablePath,
+        args: opts.args,
+        env: opts.env,
+        firefoxUserPrefs: opts.firefoxUserPrefs,
+        headless: opts.headless,
+      },
+    },
+  };
+
+  const meta = {
+    createdAt: new Date().toISOString(),
+    os: targetOs,
+    locale: host.locale ?? "randomized (host detection failed)",
+    timezone: host.timezone ?? "randomized (host detection failed)",
+    screen: host.screen ?? "randomized (host detection failed)",
+    gpu: host.gpu
+      ? { real: host.gpu.raw, spoofedAs: webglConfig ? webglConfig[1] : "no vendor match in Camoufox DB, randomized" }
+      : "randomized (host detection failed or non-Windows)",
+  };
+
+  await writeFile(profileConfigPath(name), JSON.stringify(config, null, 2));
+  await writeFile(profileMetaPath(name), JSON.stringify(meta, null, 2));
+  return profileConfigPath(name);
+}
+
+export async function deleteProfileFiles(name) {
+  if (!existsSync(profileDir(name))) return false;
+  await rm(profileDir(name), { recursive: true, force: true });
+  return true;
+}

package/src/webgl.js

@@ -0,0 +1,49 @@
+import Database from "better-sqlite3";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+// Camoufox ships a curated SQLite DB of (vendor, renderer) WebGL pairs that
+// have been vetted to render a consistent, believable fingerprint. It does
+// NOT cover every real GPU (no RTX 20/30/40-series entries, for example) -
+// only a fixed set of older reference models per vendor bucket. We can't
+// spoof the exact real GPU model through this API, but we CAN pick a combo
+// whose *vendor* matches the real GPU, which is the part fingerprinting
+// scripts actually cross-check against other signals (CPU core count,
+// platform string, etc). Exact-model spoofing would require building and
+// maintaining our own WebGL fingerprint database - out of scope here.
+
+const VENDOR_BUCKET_TO_CAMOUFOX = {
+  nvidia: "Google Inc. (NVIDIA)",
+  amd: "Google Inc. (AMD)",
+  intel: "Google Inc. (Intel)",
+};
+
+const OS_COLUMN = { windows: "win", macos: "mac", linux: "lin" };
+
+function dbPath() {
+  const camoufoxJsPkg = require.resolve("camoufox-js/package.json");
+  return path.join(path.dirname(camoufoxJsPkg), "dist", "data-files", "webgl_data.db");
+}
+
+// Returns a [vendor, renderer] tuple for camoufox-js's `webgl_config` option,
+// or undefined if the real vendor couldn't be detected / has no bucket.
+export function pickVendorMatchedWebgl(os, gpuVendorBucket) {
+  const camoufoxVendor = VENDOR_BUCKET_TO_CAMOUFOX[gpuVendorBucket];
+  const osColumn = OS_COLUMN[os];
+  if (!camoufoxVendor || !osColumn) return undefined;
+
+  const db = new Database(dbPath(), { readonly: true });
+  try {
+    const rows = db
+      .prepare(
+        `SELECT vendor, renderer FROM webgl_fingerprints WHERE vendor = ? AND ${osColumn} > 0`,
+      )
+      .all(camoufoxVendor);
+    if (rows.length === 0) return undefined;
+    return [rows[0].vendor, rows[0].renderer];
+  } finally {
+    db.close();
+  }
+}