@askjo/camofox-browser 1.0.14 → 1.1.1

package/README.md

@@ -9,7 +9,7 @@
     <a href="https://hub.docker.com"><img src="https://img.shields.io/badge/docker-ready-blue" alt="Docker" /></a>
   </p>
   <p>
-    Standing on the mighty shoulders of <a href="https://camoufox.com">Camoufox</a> — a Firefox fork with fingerprint spoofing at the C++ level.
+    Standing on the mighty shoulders of <a href="https://camoufox.com">Camoufox</a> - a Firefox fork with fingerprint spoofing at the C++ level.
     <br/><br/>
     The same engine behind <a href="https://askjo.ai">askjo.ai</a>'s web browsing.
   </p>
@@ -23,18 +23,21 @@
 
 AI agents need to browse the real web. Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint.
 
-Camoufox patches Firefox at the **C++ implementation level** — `navigator.hardwareConcurrency`, WebGL renderers, AudioContext, screen geometry, WebRTC — all spoofed before JavaScript ever sees them. No shims, no wrappers, no tells.
+Camoufox patches Firefox at the **C++ implementation level** - `navigator.hardwareConcurrency`, WebGL renderers, AudioContext, screen geometry, WebRTC - all spoofed before JavaScript ever sees them. No shims, no wrappers, no tells.
 
 This project wraps that engine in a REST API built for agents: accessibility snapshots instead of bloated HTML, stable element refs for clicking, and search macros for common sites.
 
 ## Features
 
-- **C++ Anti-Detection** — bypasses Google, Cloudflare, and most bot detection
-- **Element Refs** — stable `e1`, `e2`, `e3` identifiers for reliable interaction
-- **Token-Efficient** — accessibility snapshots are ~90% smaller than raw HTML
-- **Session Isolation** — separate cookies/storage per user
-- **Search Macros** — `@google_search`, `@youtube_search`, `@amazon_search`, and 10 more
-- **Deploy Anywhere** — Docker, Fly.io, Railway
+- **C++ Anti-Detection** - bypasses Google, Cloudflare, and most bot detection
+- **Element Refs** - stable `e1`, `e2`, `e3` identifiers for reliable interaction
+- **Token-Efficient** - accessibility snapshots are ~90% smaller than raw HTML
+- **Session Isolation** - separate cookies/storage per user
+- **Cookie Import** - inject Netscape-format cookie files for authenticated browsing
+- **Proxy + GeoIP** - route traffic through residential proxies with automatic locale/timezone
+- **Structured Logging** - JSON log lines with request IDs for production observability
+- **Search Macros** - `@google_search`, `@youtube_search`, `@amazon_search`, `@reddit_subreddit`, and 10 more
+- **Deploy Anywhere** - Docker, Fly.io, Railway
 
 ## Quick Start
 
@@ -44,7 +47,7 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 openclaw plugins install @askjo/camofox-browser
 ```
 
-**Tools:** `camofox_create_tab` · `camofox_snapshot` · `camofox_click` · `camofox_type` · `camofox_navigate` · `camofox_scroll` · `camofox_screenshot` · `camofox_close_tab` · `camofox_list_tabs`
+**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`
 
 ### Standalone
 
@@ -55,7 +58,7 @@ npm install
 npm start  # downloads Camoufox on first run (~300MB)
 ```
 
-Default port is `9377`. Set `CAMOFOX_PORT` to override.
+Default port is `9377`. See [Environment Variables](#environment-variables) for all options.
 
 ### Docker
 
@@ -70,6 +73,141 @@ docker run -p 9377:9377 camofox-browser
 
 ## Usage
 
+### Cookie Import
+
+Import cookies from your browser into Camoufox to skip interactive login on sites like LinkedIn, Amazon, etc.
+
+#### Setup
+
+**1. Generate a secret key:**
+
+```bash
+# macOS / Linux
+openssl rand -hex 32
+```
+
+**2. Set the environment variable before starting OpenClaw:**
+
+```bash
+export CAMOFOX_API_KEY="your-generated-key"
+openclaw start
+```
+
+The same key is used by both the plugin (to authenticate requests) and the server (to verify them). Both run from the same environment — set it once.
+
+> **Why an env var?** The key is a secret. Plugin config in `openclaw.json` is stored in plaintext, so secrets don't belong there. Set `CAMOFOX_API_KEY` in your shell profile, systemd unit, Docker env, or Fly.io secrets.
+
+> **Cookie import is disabled by default.** If `CAMOFOX_API_KEY` is not set, the server rejects all cookie requests with 403.
+
+**3. Export cookies from your browser:**
+
+Install a browser extension that exports Netscape-format cookie files (e.g., "cookies.txt" for Chrome/Firefox). Export the cookies for the site you want to authenticate.
+
+**4. Place the cookie file:**
+
+```bash
+mkdir -p ~/.camofox/cookies
+cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt
+```
+
+The default directory is `~/.camofox/cookies/`. Override with `CAMOFOX_COOKIES_DIR`.
+
+**5. Ask your agent to import them:**
+
+> Import my LinkedIn cookies from linkedin.txt
+
+The agent calls `camofox_import_cookies` → reads the file → POSTs to the server with the Bearer token → cookies are injected into the browser session. Subsequent `camofox_create_tab` calls to linkedin.com will be authenticated.
+
+#### How it works
+
+```
+~/.camofox/cookies/linkedin.txt          (Netscape format, on disk)
+        │
+        ▼
+camofox_import_cookies tool              (parses file, filters by domain)
+        │
+        ▼  POST /sessions/:userId/cookies
+        │  Authorization: Bearer <CAMOFOX_API_KEY>
+        │  Body: { cookies: [Playwright cookie objects] }
+        ▼
+camofox server                           (validates, sanitizes, injects)
+        │
+        ▼  context.addCookies(...)
+        │
+Camoufox browser session                 (authenticated browsing)
+```
+
+- `cookiesPath` is resolved relative to the cookies directory — path traversal outside it is blocked
+- Max 500 cookies per request, 5MB file size limit
+- Cookie objects are sanitized to an allowlist of Playwright fields
+
+#### Standalone server usage
+
+```bash
+curl -X POST http://localhost:9377/sessions/agent1/cookies \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
+  -d '{"cookies":[{"name":"foo","value":"bar","domain":"example.com","path":"/","expires":-1,"httpOnly":false,"secure":false}]}'
+```
+
+#### Docker / Fly.io
+
+```bash
+docker run -p 9377:9377 \
+  -e CAMOFOX_API_KEY="your-generated-key" \
+  -v ~/.camofox/cookies:/home/node/.camofox/cookies:ro \
+  camofox-browser
+```
+
+For Fly.io:
+```bash
+fly secrets set CAMOFOX_API_KEY="your-generated-key"
+```
+
+### Proxy + GeoIP
+
+Route all browser traffic through a proxy with automatic locale, timezone, and geolocation derived from the proxy's IP address via Camoufox's built-in GeoIP.
+
+Set these environment variables before starting the server:
+
+```bash
+export PROXY_HOST=166.88.179.132
+export PROXY_PORT=46040
+export PROXY_USERNAME=myuser
+export PROXY_PASSWORD=mypass
+npm start
+```
+
+Or in Docker:
+
+```bash
+docker run -p 9377:9377 \
+  -e PROXY_HOST=166.88.179.132 \
+  -e PROXY_PORT=46040 \
+  -e PROXY_USERNAME=myuser \
+  -e PROXY_PASSWORD=mypass \
+  camofox-browser
+```
+
+When a proxy is configured:
+- All traffic routes through the proxy
+- Camoufox's GeoIP automatically sets `locale`, `timezone`, and `geolocation` to match the proxy's exit IP
+- Browser fingerprint (language, timezone, coordinates) is consistent with the proxy location
+- Without a proxy, defaults to `en-US`, `America/Los_Angeles`, San Francisco coordinates
+
+### Structured Logging
+
+All log output is JSON (one object per line) for easy parsing by log aggregators:
+
+```json
+{"ts":"2026-02-11T23:45:01.234Z","level":"info","msg":"req","reqId":"a1b2c3d4","method":"POST","path":"/tabs","userId":"agent1"}
+{"ts":"2026-02-11T23:45:01.567Z","level":"info","msg":"res","reqId":"a1b2c3d4","status":200,"ms":333}
+```
+
+Health check requests (`/health`) are excluded from request logging to reduce noise.
+
+### Basic Browsing
+
 ```bash
 # Create a tab
 curl -X POST http://localhost:9377/tabs \
@@ -134,15 +272,38 @@ curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
 | `POST` | `/start` | Start browser engine |
 | `POST` | `/stop` | Stop browser engine |
 
+### Sessions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/sessions/:userId/cookies` | Add cookies to a user session (Playwright cookie objects) |
+
 ## Search Macros
 
-`@google_search` · `@youtube_search` · `@amazon_search` · `@reddit_search` · `@wikipedia_search` · `@twitter_search` · `@yelp_search` · `@spotify_search` · `@netflix_search` · `@linkedin_search` · `@instagram_search` · `@tiktok_search` · `@twitch_search`
+`@google_search` · `@youtube_search` · `@amazon_search` · `@reddit_search` · `@reddit_subreddit` · `@wikipedia_search` · `@twitter_search` · `@yelp_search` · `@spotify_search` · `@netflix_search` · `@linkedin_search` · `@instagram_search` · `@tiktok_search` · `@twitch_search`
+
+Reddit macros return JSON directly (no HTML parsing needed):
+- `@reddit_search` - search all of Reddit, returns JSON with 25 results
+- `@reddit_subreddit` - browse a subreddit (e.g., query `"programming"` → `/r/programming.json`)
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CAMOFOX_PORT` | Server port | `9377` |
+| `CAMOFOX_API_KEY` | Enable cookie import endpoint (disabled if unset) | - |
+| `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - |
+| `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` |
+| `PROXY_HOST` | Proxy hostname or IP | - |
+| `PROXY_PORT` | Proxy port | - |
+| `PROXY_USERNAME` | Proxy auth username | - |
+| `PROXY_PASSWORD` | Proxy auth password | - |
 
 ## Architecture
 
 ```
 Browser Instance (Camoufox)
-└── User Session (BrowserContext) — isolated cookies/storage
+└── User Session (BrowserContext) - isolated cookies/storage
     ├── Tab Group (sessionKey: "conv1")
     │   ├── Tab (google.com)
     │   └── Tab (github.com)
@@ -169,9 +330,9 @@ npm install @askjo/camofox-browser
 
 ## Credits
 
-- [Camoufox](https://camoufox.com) — Firefox-based browser with C++ anti-detection
+- [Camoufox](https://camoufox.com) - Firefox-based browser with C++ anti-detection
 - [Donate to Camoufox's original creator daijro](https://camoufox.com/about/)
-- [OpenClaw](https://openclaw.ai) — Open-source AI agent framework
+- [OpenClaw](https://openclaw.ai) - Open-source AI agent framework
 
 ## Crypto Scam Warning
 

package/lib/macros.js

@@ -2,7 +2,8 @@ const MACROS = {
   '@google_search': (query) => `https://www.google.com/search?q=${encodeURIComponent(query || '')}`,
   '@youtube_search': (query) => `https://www.youtube.com/results?search_query=${encodeURIComponent(query || '')}`,
   '@amazon_search': (query) => `https://www.amazon.com/s?k=${encodeURIComponent(query || '')}`,
-  '@reddit_search': (query) => `https://www.reddit.com/search/?q=${encodeURIComponent(query || '')}`,
+  '@reddit_search': (query) => `https://www.reddit.com/search.json?q=${encodeURIComponent(query || '')}&limit=25`,
+  '@reddit_subreddit': (query) => `https://www.reddit.com/r/${encodeURIComponent(query || 'all')}.json?limit=25`,
   '@wikipedia_search': (query) => `https://en.wikipedia.org/wiki/Special:Search?search=${encodeURIComponent(query || '')}`,
   '@twitter_search': (query) => `https://twitter.com/search?q=${encodeURIComponent(query || '')}`,
   '@yelp_search': (query) => `https://www.yelp.com/search?find_desc=${encodeURIComponent(query || '')}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.0.14",
+  "version": "1.1.1",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "main": "server.js",
   "license": "MIT",

package/plugin.ts

@@ -6,8 +6,10 @@
  */
 
 import { spawn, ChildProcess } from "child_process";
-import { join, dirname } from "path";
+import { join, dirname, resolve, sep } from "path";
 import { fileURLToPath } from "url";
+import { randomUUID } from "crypto";
+import { homedir } from "os";
 
 // Get plugin directory - works in both ESM and CJS contexts
 const getPluginDir = (): string => {
@@ -91,7 +93,8 @@ interface PluginApi {
     name: string,
     check: () => Promise<HealthCheckResult>
   ) => void;
-  config: PluginConfig;
+  config: Record<string, unknown>;
+  pluginConfig?: PluginConfig;
   log: {
     info: (msg: string) => void;
     error: (msg: string) => void;
@@ -113,6 +116,13 @@ async function startServer(
       HOME: process.env.HOME,
       NODE_ENV: process.env.NODE_ENV,
       CAMOFOX_PORT: String(port),
+      CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
+      CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
+      CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
+      PROXY_HOST: process.env.PROXY_HOST,
+      PROXY_PORT: process.env.PROXY_PORT,
+      PROXY_USERNAME: process.env.PROXY_USERNAME,
+      PROXY_PASSWORD: process.env.PROXY_PASSWORD,
     },
     stdio: ["ignore", "pipe", "pipe"],
     detached: false,
@@ -192,11 +202,57 @@ function toToolResult(data: unknown): ToolResult {
   };
 }
 
+function parseNetscapeCookieFile(text: string) {
+  // Netscape cookie file format:
+  // domain \t includeSubdomains \t path \t secure \t expires \t name \t value
+  // HttpOnly cookies are prefixed with: #HttpOnly_
+  const cookies: Array<{
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+  }> = [];
+
+  const cleaned = text.replace(/^\uFEFF/, '');
+
+  for (const rawLine of cleaned.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith('#') && !line.startsWith('#HttpOnly_')) continue;
+
+    let httpOnly = false;
+    let working = line;
+    if (working.startsWith('#HttpOnly_')) {
+      httpOnly = true;
+      working = working.replace(/^#HttpOnly_/, '');
+    }
+
+    const parts = working.split('\t');
+    if (parts.length < 7) continue;
+
+    const domain = parts[0];
+    const path = parts[2];
+    const secure = parts[3].toUpperCase() === 'TRUE';
+    const expires = Number(parts[4]);
+    const name = parts[5];
+    const value = parts.slice(6).join('\t');
+
+    cookies.push({ name, value, domain, path, expires, httpOnly, secure });
+  }
+
+  return cookies;
+}
+
 export default function register(api: PluginApi) {
-  const port = api.config.port || 9377;
-  const baseUrl = api.config.url || `http://localhost:${port}`;
-  const autoStart = api.config.autoStart !== false; // default true
+  const cfg = api.pluginConfig ?? (api.config as unknown as PluginConfig);
+  const port = cfg.port || 9377;
+  const baseUrl = cfg.url || `http://localhost:${port}`;
+  const autoStart = cfg.autoStart !== false; // default true
   const pluginDir = getPluginDir();
+  const fallbackUserId = `camofox-${randomUUID()}`;
 
   // Auto-start server if configured (default: true)
   if (autoStart) {
@@ -227,7 +283,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const sessionKey = ctx.sessionKey || "default";
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, "/tabs", {
         method: "POST",
         body: JSON.stringify({ ...params, userId, sessionKey }),
@@ -249,7 +305,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId } = params as { tabId: string };
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}`);
       return toToolResult(result);
     },
@@ -269,7 +325,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/click`, {
         method: "POST",
         body: JSON.stringify({ ...rest, userId }),
@@ -294,7 +350,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/type`, {
         method: "POST",
         body: JSON.stringify({ ...rest, userId }),
@@ -337,7 +393,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/navigate`, {
         method: "POST",
         body: JSON.stringify({ ...rest, userId }),
@@ -360,7 +416,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/scroll`, {
         method: "POST",
         body: JSON.stringify({ ...rest, userId }),
@@ -381,7 +437,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId } = params as { tabId: string };
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const url = `${baseUrl}/tabs/${tabId}/screenshot?userId=${userId}`;
       const res = await fetch(url);
       if (!res.ok) {
@@ -414,7 +470,7 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId } = params as { tabId: string };
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}?userId=${userId}`, {
         method: "DELETE",
       });
@@ -431,12 +487,84 @@ export default function register(api: PluginApi) {
       required: [],
     },
     async execute(_id, _params) {
-      const userId = ctx.agentId || "openclaw";
+      const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs?userId=${userId}`);
       return toToolResult(result);
     },
   }));
 
+  api.registerTool((ctx: ToolContext) => ({
+    name: "camofox_import_cookies",
+    description:
+      "Import cookies into the current Camoufox user session (Netscape cookie file). Use to authenticate to sites like LinkedIn without interactive login.",
+    parameters: {
+      type: "object",
+      properties: {
+        cookiesPath: { type: "string", description: "Path to Netscape-format cookies.txt file" },
+        domainSuffix: {
+          type: "string",
+          description: "Only import cookies whose domain ends with this suffix",
+        },
+      },
+      required: ["cookiesPath"],
+    },
+    async execute(_id, params) {
+      const { cookiesPath, domainSuffix } = params as {
+        cookiesPath: string;
+        domainSuffix?: string;
+      };
+
+      const userId = ctx.agentId || fallbackUserId;
+
+      const fs = await import("fs/promises");
+
+      const cookiesDir = resolve(process.env.CAMOFOX_COOKIES_DIR || join(homedir(), ".camofox", "cookies"));
+      const resolved = resolve(cookiesDir, cookiesPath);
+      if (!resolved.startsWith(cookiesDir + sep)) {
+        throw new Error("cookiesPath must be a relative path within the cookies directory");
+      }
+
+      const stat = await fs.stat(resolved);
+      if (stat.size > 5 * 1024 * 1024) {
+        throw new Error("Cookie file too large (max 5MB)");
+      }
+
+      const text = await fs.readFile(resolved, "utf8");
+      let cookies = parseNetscapeCookieFile(text);
+      if (domainSuffix) {
+        cookies = cookies.filter((c) => c.domain.endsWith(domainSuffix));
+      }
+
+      // Translate into Playwright cookie objects
+      const pwCookies = cookies.map((c) => ({
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        expires: c.expires,
+        httpOnly: !!c.httpOnly,
+        secure: !!c.secure,
+      }));
+
+      const apiKey = process.env.CAMOFOX_API_KEY;
+      if (!apiKey) {
+        throw new Error(
+          "CAMOFOX_API_KEY is not set. Cookie import is disabled unless you set CAMOFOX_API_KEY for both the server and the OpenClaw plugin environment."
+        );
+      }
+
+      const result = await fetchApi(baseUrl, `/sessions/${encodeURIComponent(userId)}/cookies`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ cookies: pwCookies }),
+      });
+
+      return toToolResult({ imported: pwCookies.length, userId, result });
+    },
+  }));
+
   api.registerCommand({
     name: "camofox",
     description: "Camoufox browser server control (status, start, stop)",