@askjo/camofox-browser 1.8.8 → 1.8.11

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "camofox-browser",
   "name": "Camofox Browser",
   "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
-  "version": "1.8.8",
+  "version": "1.8.11",
   "envVars": {
     "CAMOFOX_API_KEY": {
       "description": "Secret key for the cookie-import endpoint. Cookie import is disabled when unset. Only set this if you need to import browser cookies and the server is local or access-controlled.",
@@ -163,5 +163,101 @@
       "label": "Crash Report Relay URL",
       "placeholder": "https://camofox-crash-relay.askjo.workers.dev/report"
     }
+  },
+  "tools": [
+    "camofox_create_tab",
+    "camofox_snapshot",
+    "camofox_click",
+    "camofox_type",
+    "camofox_navigate",
+    "camofox_scroll",
+    "camofox_screenshot",
+    "camofox_close_tab",
+    "camofox_list_tabs",
+    "camofox_import_cookies"
+  ],
+  "runtimeDependencies": {
+    "camoufox": {
+      "description": "Camoufox anti-detection browser (Firefox fork). Downloaded at install time by camoufox-js from the official Camoufox GitHub releases.",
+      "source": "https://github.com/nicedayzhu/camoufox/releases",
+      "installer": "camoufox-js (npm)",
+      "installedBy": "postinstall script: npx camoufox-js fetch",
+      "sizeApprox": "300MB",
+      "platforms": [
+        "linux-x86_64",
+        "linux-aarch64",
+        "macos-x86_64",
+        "macos-aarch64"
+      ],
+      "verifiedBy": "camoufox-js verifies download integrity via GitHub release checksums"
+    }
+  },
+  "permissions": {
+    "network": {
+      "outbound": [
+        {
+          "target": "User-specified URLs (browsed pages)",
+          "purpose": "Browser automation -- navigating to URLs the agent requests",
+          "gatedBy": "Agent request via API"
+        },
+        {
+          "target": "https://camofox-crash-relay.askjo.workers.dev/report",
+          "purpose": "Anonymized crash/hang reporting",
+          "gatedBy": "CAMOFOX_CRASH_REPORT_ENABLED (default: true, set false to disable)"
+        }
+      ],
+      "inbound": {
+        "target": "localhost:9377 (default)",
+        "purpose": "REST API for browser automation",
+        "gatedBy": "CAMOFOX_ACCESS_KEY (optional -- when set, all routes require Bearer auth)"
+      }
+    },
+    "filesystem": {
+      "read": [
+        {
+          "path": "~/.camofox/cookies/",
+          "purpose": "Read Netscape cookie files for authenticated browsing",
+          "gatedBy": "CAMOFOX_API_KEY (disabled entirely when unset)"
+        },
+        {
+          "path": "/proc/self/status (Linux only)",
+          "purpose": "Memory and resource metrics for crash reports",
+          "gatedBy": "Only read when crash reporting is enabled"
+        }
+      ],
+      "write": [
+        {
+          "path": "~/.camofox/profiles/<hashed-userId>/",
+          "purpose": "Persisted session state (cookies + localStorage) so users stay logged in across restarts",
+          "gatedBy": "persistence plugin (enabled by default, disable via camofox.config.json)"
+        },
+        {
+          "path": "~/.camofox/traces/<hashed-userId>/",
+          "purpose": "Optional Playwright session traces for debugging",
+          "gatedBy": "trace: true flag on tab creation (opt-in per session, off by default)"
+        }
+      ]
+    },
+    "subprocess": [
+      {
+        "binary": "Camoufox (Firefox fork)",
+        "purpose": "The browser engine -- core functionality",
+        "isolation": "lib/launcher.js (child_process isolated from route handlers)"
+      },
+      {
+        "binary": "yt-dlp (optional)",
+        "purpose": "YouTube transcript extraction (fast path)",
+        "isolation": "plugins/youtube/youtube.js (child_process isolated from route handlers)"
+      }
+    ]
+  },
+  "securityModel": {
+    "architecture": "All process.env reads are in lib/config.js. All child_process usage is in lib/launcher.js and plugins/youtube/youtube.js. server.js has route handlers but zero process.env reads and zero child_process imports. No single file combines secrets access with network sends.",
+    "cookieImport": "DISABLED by default. Requires CAMOFOX_API_KEY to be explicitly set. Without the key, the server rejects all cookie requests with 403. Cookie files are read from a sandboxed directory (~/.camofox/cookies/) with path traversal protection.",
+    "accessControl": "CAMOFOX_ACCESS_KEY provides global bearer auth for all routes (except /health). Recommended for any non-localhost deployment.",
+    "crashReporting": "Anonymized via lib/reporter.js (L28-290). Private domains are HMAC-hashed. No page content, cookies, tokens, IPs, or user data is ever sent. Relay source is in-repo and auditable. Verification endpoint: GET /source returns commit hash and sha256.",
+    "binaryDownload": "Camoufox is downloaded at npm install time by camoufox-js (an npm package from the Camoufox project). Downloaded from official GitHub releases with integrity verification by camoufox-js.",
+    "sessionPersistence": "User sessions are persisted to ~/.camofox/profiles/ so authenticated browsing survives restarts. UserIds are hashed for directory names. Disable via persistence plugin config.",
+    "noEmbeddedSecrets": "Zero credentials, private keys, or tokens ship in this package. All secrets are environment variables or Cloudflare Worker secrets."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.8.8",
+  "version": "1.8.11",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "type": "module",
   "main": "server.js",
@@ -45,7 +45,8 @@
     "run.sh",
     "Dockerfile",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "AGENTS.md"
   ],
   "openclaw": {
     "extensions": [
@@ -56,7 +57,49 @@
     },
     "build": {
       "openclawVersion": "2026.4.26"
-    }
+    },
+    "tools": [
+      {
+        "name": "camofox_create_tab",
+        "description": "Open a new browser tab at a URL"
+      },
+      {
+        "name": "camofox_snapshot",
+        "description": "Get accessibility snapshot with element refs"
+      },
+      {
+        "name": "camofox_click",
+        "description": "Click an element by ref or CSS selector"
+      },
+      {
+        "name": "camofox_type",
+        "description": "Type text into an element"
+      },
+      {
+        "name": "camofox_navigate",
+        "description": "Navigate to URL or search macro"
+      },
+      {
+        "name": "camofox_scroll",
+        "description": "Scroll page up/down/left/right"
+      },
+      {
+        "name": "camofox_screenshot",
+        "description": "Capture page screenshot"
+      },
+      {
+        "name": "camofox_close_tab",
+        "description": "Close a browser tab"
+      },
+      {
+        "name": "camofox_list_tabs",
+        "description": "List open tabs for a user"
+      },
+      {
+        "name": "camofox_import_cookies",
+        "description": "Import Netscape cookie file (requires CAMOFOX_API_KEY)"
+      }
+    ]
   },
   "scripts": {
     "start": "node server.js",

package/plugins/vnc/index.js

@@ -2,7 +2,7 @@
  * VNC plugin for camofox-browser.
  *
  * Exposes Camoufox's virtual display via noVNC so a human can interact with
- * the browser visually — log into sites, solve CAPTCHAs, approve OAuth prompts.
+ * the browser visually -- log into sites, solve CAPTCHAs, approve OAuth prompts.
  * After interactive login, export the storage state via the API endpoint this
  * plugin registers.
  *
@@ -35,7 +35,7 @@
  *   NOVNC_PORT=6080        noVNC web UI port
  *
  * Registers:
- *   GET /sessions/:userId/storage_state — export Playwright storageState as JSON
+ *   GET /sessions/:userId/storage_state -- export Playwright storageState as JSON
  *
  * Events emitted:
  *   vnc:watcher:started    { pid }

package/plugins/vnc/vnc-launcher.js

@@ -1,5 +1,5 @@
 /**
- * VNC launcher — owns all process spawning and env reads.
+ * VNC launcher -- owns all process spawning and env reads.
  * Isolated from route handlers for OpenClaw scanner compliance.
  */
 
@@ -11,7 +11,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
  * Resolve VNC configuration from pluginConfig + env var fallbacks.
- * All process.env reads live here — callers get a plain config object.
+ * All process.env reads live here -- callers get a plain config object.
  */
 export function resolveVncConfig(pluginConfig = {}) {
   const enabled = process.env.ENABLE_VNC === '1' || pluginConfig.enabled === true;

package/plugins/vnc/vnc-watcher.sh

@@ -32,7 +32,7 @@ else
   log "x11vnc: NO password (bind $NOVNC_PORT to 127.0.0.1 on host + SSH tunnel)"
 fi
 
-# Start noVNC (websockify) — proxies to x11vnc regardless of whether it's up yet
+# Start noVNC (websockify) -- proxies to x11vnc regardless of whether it's up yet
 NOVNC_DIR="/usr/share/novnc"
 if [ ! -d "$NOVNC_DIR" ]; then
   log "ERROR: $NOVNC_DIR not found; noVNC cannot start"
@@ -42,7 +42,7 @@ VNC_BIND="${VNC_BIND:-127.0.0.1}"
 log "Starting noVNC (websockify) on $VNC_BIND:$NOVNC_PORT -> 127.0.0.1:$VNC_PORT"
 websockify --web "$NOVNC_DIR" "$VNC_BIND:$NOVNC_PORT" "127.0.0.1:$VNC_PORT" >/var/log/novnc.log 2>&1 &
 
-log "VNC watcher started — will attach x11vnc when Camoufox's Xvfb appears"
+log "VNC watcher started -- will attach x11vnc when Camoufox's Xvfb appears"
 
 while true; do
   # Find Xvfb with our patched resolution
@@ -53,7 +53,7 @@ while true; do
   ' | head -1)
 
   if [ -n "$FOUND" ] && [ "$FOUND" != "$CURRENT_DISPLAY" ]; then
-    # New or changed display — (re)attach x11vnc
+    # New or changed display -- (re)attach x11vnc
     if [ -n "$X11VNC_PID" ] && kill -0 "$X11VNC_PID" 2>/dev/null; then
       log "Camoufox display changed ($CURRENT_DISPLAY -> $FOUND), restarting x11vnc"
       kill "$X11VNC_PID" 2>/dev/null || true

package/plugins/vnc/vnc.test.js

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events';
 import { jest } from '@jest/globals';
 
-// Mock the launcher module — index.js no longer imports child_process directly
+// Mock the launcher module -- index.js no longer imports child_process directly
 const mockWatcher = () => {
   const proc = new EventEmitter();
   proc.pid = 12345;
@@ -169,7 +169,7 @@ describe('vnc plugin', () => {
 
     await handler(req, res);
     expect(res.status).toHaveBeenCalledWith(500);
-    // safeError returns the message string — not the raw Error object
+    // safeError returns the message string -- not the raw Error object
     expect(res.json).toHaveBeenCalledWith({ error: 'context destroyed' });
   });
 

package/plugins/youtube/index.js

@@ -20,7 +20,7 @@ export async function register(app, ctx, pluginConfig = {}) {
   await detectYtDlp(log);
 
   // Auth is on by default; set { "auth": false } in camofox.config.json to disable
-  // Auth off by default — matches pre-plugin behavior. Set { "auth": true } to require auth.
+  // Auth off by default -- matches pre-plugin behavior. Set { "auth": true } to require auth.
   const middleware = pluginConfig.auth === true ? ctx.auth() : (_req, _res, next) => next();
 
   app.post('/youtube/transcript', middleware, async (req, res) => {
@@ -73,7 +73,7 @@ export async function register(app, ctx, pluginConfig = {}) {
     }
   });
 
-  // Browser fallback — play video, intercept timedtext network response
+  // Browser fallback -- play video, intercept timedtext network response
   async function browserTranscript(reqId, url, videoId, lang) {
     return await withUserLimit('__yt_transcript__', async () => {
       await ensureBrowser();

package/plugins/youtube/youtube.js

@@ -94,7 +94,7 @@ async function detectYtDlp(log) {
       return true;
     } catch {}
   }
-  log('warn', 'yt-dlp not found — YouTube transcript endpoint will use browser fallback');
+  log('warn', 'yt-dlp not found -- YouTube transcript endpoint will use browser fallback');
   return false;
 }
 

package/scripts/install-plugin-deps.sh

@@ -24,7 +24,7 @@ if [ -f "$CONFIG" ] && command -v node >/dev/null 2>&1; then
 fi
 
 if [ -z "$PLUGIN_LIST" ]; then
-  # No config or no plugins key — use all plugin directories
+  # No config or no plugins key -- use all plugin directories
   PLUGIN_LIST=""
   for d in "$PLUGINS_DIR"/*/; do
     [ -d "$d" ] || continue

package/scripts/plugin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * camofox plugin manager — install, remove, and list plugins.
+ * camofox plugin manager -- install, remove, and list plugins.
  *
  * Usage:
  *   node scripts/plugin.js install <source>   Install a plugin from git URL or local path
@@ -32,7 +32,7 @@ const ROOT = path.join(__dirname, '..');
 const PLUGINS_DIR = path.join(ROOT, 'plugins');
 const CONFIG_PATH = path.join(ROOT, 'camofox.config.json');
 
-// ── Config helpers ──────────────────────────────────────────────────────────
+// -- Config helpers ----------------------------------------------------------
 
 function readConfig() {
   try {
@@ -94,7 +94,7 @@ function removeFromConfig(name) {
   }
 }
 
-// ── Source parsing ──────────────────────────────────────────────────────────
+// -- Source parsing ----------------------------------------------------------
 
 function parseSource(source) {
   // Local path
@@ -109,11 +109,11 @@ function parseSource(source) {
     return { type: 'local', path: resolved, name: path.basename(resolved) };
   }
 
-  // Git URL — https://, ssh://, git@, git:
+  // Git URL -- https://, ssh://, git@, git:
   let gitUrl = source;
   if (gitUrl.startsWith('git:')) {
     gitUrl = gitUrl.slice(4);
-    // git:github.com/user/repo → https://github.com/user/repo
+    // git:github.com/user/repo -> https://github.com/user/repo
     if (!gitUrl.startsWith('http') && !gitUrl.startsWith('ssh://') && !gitUrl.startsWith('git@')) {
       gitUrl = `https://${gitUrl}`;
     }
@@ -132,7 +132,7 @@ function parseSource(source) {
   return { type: 'git', url: cloneUrl, name };
 }
 
-// ── Install ─────────────────────────────────────────────────────────────────
+// -- Install -----------------------------------------------------------------
 
 function isPluginDir(dir) {
   const indexPath = path.join(dir, 'index.js');
@@ -177,12 +177,12 @@ function installFromGit(url, name) {
         }
       }
       if (installed.length === 0) {
-        fatal(`No plugins found in ${url} — expected index.js with register() at root or in plugins/*/`);
+        fatal(`No plugins found in ${url} -- expected index.js with register() at root or in plugins/*/`);
       }
       return installed;
     }
 
-    fatal(`No plugins found in ${url} — expected index.js with register() at root or plugins/*/ subdirs`);
+    fatal(`No plugins found in ${url} -- expected index.js with register() at root or plugins/*/ subdirs`);
   } finally {
     if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true });
   }
@@ -198,16 +198,16 @@ function installPluginDeps(name) {
     execSync('npm install --omit=dev', { cwd: pluginDir, stdio: 'inherit' });
   }
 
-  // Check for apt.txt / post-install.sh (just warn — can't run apt locally)
+  // Check for apt.txt / post-install.sh (just warn -- can't run apt locally)
   if (fs.existsSync(path.join(pluginDir, 'apt.txt'))) {
-    console.log(`⚠  ${name} has apt.txt — system packages need Docker build or manual install`);
+    console.log(`WARNING  ${name} has apt.txt -- system packages need Docker build or manual install`);
   }
   if (fs.existsSync(path.join(pluginDir, 'post-install.sh'))) {
-    console.log(`⚠  ${name} has post-install.sh — run it manually or rebuild Docker image`);
+    console.log(`WARNING  ${name} has post-install.sh -- run it manually or rebuild Docker image`);
   }
 }
 
-// ── Remove ──────────────────────────────────────────────────────────────────
+// -- Remove ------------------------------------------------------------------
 
 function removePlugin(name) {
   const pluginDir = path.join(PLUGINS_DIR, name);
@@ -217,10 +217,10 @@ function removePlugin(name) {
 
   fs.rmSync(pluginDir, { recursive: true });
   removeFromConfig(name);
-  console.log(`✓ Removed plugin "${name}"`);
+  console.log(`[ok] Removed plugin "${name}"`);
 }
 
-// ── List ────────────────────────────────────────────────────────────────────
+// -- List --------------------------------------------------------------------
 
 function listPlugins() {
   const config = readConfig();
@@ -244,7 +244,7 @@ function listPlugins() {
   console.log('Installed plugins:\n');
   for (const name of plugins.sort()) {
     const enabled = configPlugins.size === 0 || configPlugins.has(name);
-    const status = enabled ? '✓' : '○';
+    const status = enabled ? '[ok]' : 'o';
     const hasTest = fs.existsSync(path.join(PLUGINS_DIR, name, `${name}.test.js`))
       || fs.readdirSync(path.join(PLUGINS_DIR, name)).some(f => f.endsWith('.test.js'));
     const hasDeps = fs.existsSync(path.join(PLUGINS_DIR, name, 'apt.txt'))
@@ -263,11 +263,11 @@ function listPlugins() {
   if (configPlugins.size > 0) {
     console.log(`\n${configPlugins.size} plugin(s) enabled in camofox.config.json`);
   } else {
-    console.log('\nNo plugins[] in config — all plugins are loaded');
+    console.log('\nNo plugins[] in config -- all plugins are loaded');
   }
 }
 
-// ── Helpers ─────────────────────────────────────────────────────────────────
+// -- Helpers -----------------------------------------------------------------
 
 function copyDirSync(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -289,7 +289,7 @@ function fatal(msg) {
   process.exit(1);
 }
 
-// ── CLI ─────────────────────────────────────────────────────────────────────
+// -- CLI ---------------------------------------------------------------------
 
 const [,, action, ...args] = process.argv;
 
@@ -308,7 +308,7 @@ switch (action) {
       installPluginDeps(name);
     }
 
-    console.log(`\n✓ Installed: ${installed.join(', ')}`);
+    console.log(`\n[ok] Installed: ${installed.join(', ')}`);
     console.log('  Restart the server to load new plugin(s).');
     break;
   }

package/scripts/plugin.test.js

@@ -1,5 +1,5 @@
 /**
- * Tests for scripts/plugin.js — plugin install, remove, list.
+ * Tests for scripts/plugin.js -- plugin install, remove, list.
  */
 
 import fs from 'fs';
@@ -32,7 +32,7 @@ describe('plugin list', () => {
   test('lists youtube as enabled', () => {
     const out = run('list');
     expect(out).toContain('youtube');
-    expect(out).toContain('✓');
+    expect(out).toContain('[ok]');
   });
 });