@askjo/camofox-browser 1.0.13 → 1.1.0

package/README.md

@@ -9,11 +9,14 @@
     <a href="https://hub.docker.com"><img src="https://img.shields.io/badge/docker-ready-blue" alt="Docker" /></a>
   </p>
   <p>
-    Built on <a href="https://camoufox.com">Camoufox</a> — a Firefox fork with fingerprint spoofing at the C++ level.<br/>
+    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>
 </div>
 
+<br/>
+
 ---
 
 ## Why
@@ -30,7 +33,10 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **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
+- **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
@@ -41,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
 
@@ -52,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
 
@@ -67,6 +73,70 @@ docker run -p 9377:9377 camofox-browser
 
 ## Usage
 
+### Cookie Injection (Netscape cookie file → Playwright cookies)
+
+If you’re using the OpenClaw plugin, you can import a Netscape-format cookie file (e.g., exported from a browser) to authenticate sessions without interactive login.
+
+- Tool: `camofox_import_cookies`
+- Server endpoint: `POST /sessions/:userId/cookies`
+
+**Security:** this endpoint is disabled unless `CAMOFOX_API_KEY` is set on the server. When enabled, callers must include `Authorization: Bearer <CAMOFOX_API_KEY>`.
+
+```bash
+# OpenClaw tool usage (conceptual)
+# camofox_import_cookies({ cookiesPath: "linkedin.txt", domainSuffix: "linkedin.com" })
+
+# Direct server usage (Playwright cookie objects)
+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}]}'
+```
+
+### 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 \
@@ -131,9 +201,32 @@ 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
 
@@ -167,8 +260,13 @@ npm install @askjo/camofox-browser
 ## Credits
 
 - [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
 
+## Crypto Scam Warning
+
+Sketchy people are doing sketchy things with crypto tokens named "Camofox" now that this project is getting attention. **Camofox is not a crypto project and will never be one.** Any token, coin, or NFT using the Camofox name has nothing to do with us.
+
 ## License
 
 MIT

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.13",
+  "version": "1.1.0",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "main": "server.js",
   "license": "MIT",
@@ -56,7 +56,6 @@
   },
   "dependencies": {
     "camoufox-js": "^0.8.5",
-    "dotenv": "^17.2.3",
     "express": "^4.18.2",
     "playwright": "^1.50.0",
     "playwright-core": "^1.58.0",

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 => {
@@ -108,7 +110,19 @@ async function startServer(
   const serverPath = join(pluginDir, "server.js");
   const proc = spawn("node", [serverPath], {
     cwd: pluginDir,
-    env: { ...process.env, CAMOFOX_PORT: String(port) },
+    env: {
+      PATH: process.env.PATH,
+      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,
   });
@@ -187,11 +201,56 @@ 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 pluginDir = getPluginDir();
+  const fallbackUserId = `camofox-${randomUUID()}`;
 
   // Auto-start server if configured (default: true)
   if (autoStart) {
@@ -222,7 +281,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 }),
@@ -244,7 +303,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);
     },
@@ -264,7 +323,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 }),
@@ -289,7 +348,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 }),
@@ -332,7 +391,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 }),
@@ -355,7 +414,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 }),
@@ -376,9 +435,24 @@ export default function register(api: PluginApi) {
     },
     async execute(_id, params) {
       const { tabId } = params as { tabId: string };
-      const userId = ctx.agentId || "openclaw";
-      const result = await fetchApi(baseUrl, `/tabs/${tabId}/screenshot?userId=${userId}`);
-      return toToolResult(result);
+      const userId = ctx.agentId || fallbackUserId;
+      const url = `${baseUrl}/tabs/${tabId}/screenshot?userId=${userId}`;
+      const res = await fetch(url);
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`${res.status}: ${text}`);
+      }
+      const arrayBuffer = await res.arrayBuffer();
+      const base64 = Buffer.from(arrayBuffer).toString("base64");
+      return {
+        content: [
+          {
+            type: "image",
+            data: base64,
+            mimeType: "image/png",
+          },
+        ],
+      };
     },
   }));
 
@@ -394,7 +468,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",
       });
@@ -411,12 +485,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)",

package/server.js

@@ -1,4 +1,3 @@
-require('dotenv').config();
 const { Camoufox, launchOptions } = require('camoufox-js');
 const { firefox } = require('playwright-core');
 const express = require('express');
@@ -6,8 +5,149 @@ const crypto = require('crypto');
 const os = require('os');
 const { expandMacro } = require('./lib/macros');
 
+// --- Structured logging ---
+function log(level, msg, fields = {}) {
+  const entry = {
+    ts: new Date().toISOString(),
+    level,
+    msg,
+    ...fields,
+  };
+  const line = JSON.stringify(entry);
+  if (level === 'error') {
+    process.stderr.write(line + '\n');
+  } else {
+    process.stdout.write(line + '\n');
+  }
+}
+
 const app = express();
-app.use(express.json({ limit: '5mb' }));
+app.use(express.json({ limit: '100kb' }));
+
+// Request logging middleware
+app.use((req, res, next) => {
+  if (req.path === '/health') return next();
+  const reqId = crypto.randomUUID().slice(0, 8);
+  req.reqId = reqId;
+  req.startTime = Date.now();
+  const userId = req.body?.userId || req.query?.userId || '-';
+  log('info', 'req', { reqId, method: req.method, path: req.path, userId });
+  const origEnd = res.end.bind(res);
+  res.end = function (...args) {
+    const ms = Date.now() - req.startTime;
+    log('info', 'res', { reqId, status: res.statusCode, ms });
+    return origEnd(...args);
+  };
+  next();
+});
+
+const ALLOWED_URL_SCHEMES = ['http:', 'https:'];
+
+function timingSafeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) {
+    crypto.timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+function safeError(err) {
+  if (process.env.NODE_ENV === 'production') {
+    log('error', 'internal error', { error: err.message, stack: err.stack });
+    return 'Internal server error';
+  }
+  return err.message;
+}
+
+function validateUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (!ALLOWED_URL_SCHEMES.includes(parsed.protocol)) {
+      return `Blocked URL scheme: ${parsed.protocol} (only http/https allowed)`;
+    }
+    return null;
+  } catch {
+    return `Invalid URL: ${url}`;
+  }
+}
+
+// Import cookies into a user's browser context (Playwright cookies format)
+// POST /sessions/:userId/cookies { cookies: Cookie[] }
+//
+// SECURITY:
+// Cookie injection moves this from "anonymous browsing" to "authenticated browsing".
+// This endpoint is DISABLED unless CAMOFOX_API_KEY is set.
+// When enabled, caller must send: Authorization: Bearer <CAMOFOX_API_KEY>
+app.post('/sessions/:userId/cookies', express.json({ limit: '512kb' }), async (req, res) => {
+  try {
+    const apiKey = process.env.CAMOFOX_API_KEY;
+    if (!apiKey) {
+      return res.status(403).json({
+        error: 'Cookie import is disabled. Set CAMOFOX_API_KEY to enable this endpoint.',
+      });
+    }
+
+    const auth = String(req.headers['authorization'] || '');
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    if (!match || !timingSafeCompare(match[1], apiKey)) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+
+    const userId = req.params.userId;
+    if (!req.body || !('cookies' in req.body)) {
+      return res.status(400).json({ error: 'Missing "cookies" field in request body' });
+    }
+    const cookies = req.body.cookies;
+    if (!Array.isArray(cookies)) {
+      return res.status(400).json({ error: 'cookies must be an array' });
+    }
+
+    if (cookies.length > 500) {
+      return res.status(400).json({ error: 'Too many cookies. Maximum 500 per request.' });
+    }
+
+    const invalid = [];
+    for (let i = 0; i < cookies.length; i++) {
+      const c = cookies[i];
+      const missing = [];
+      if (!c || typeof c !== 'object') {
+        invalid.push({ index: i, error: 'cookie must be an object' });
+        continue;
+      }
+      if (typeof c.name !== 'string' || !c.name) missing.push('name');
+      if (typeof c.value !== 'string') missing.push('value');
+      if (typeof c.domain !== 'string' || !c.domain) missing.push('domain');
+      if (missing.length) invalid.push({ index: i, missing });
+    }
+    if (invalid.length) {
+      return res.status(400).json({
+        error: 'Invalid cookie objects: each cookie must include name, value, and domain',
+        invalid,
+      });
+    }
+
+    const allowedFields = ['name', 'value', 'domain', 'path', 'expires', 'httpOnly', 'secure', 'sameSite'];
+    const sanitized = cookies.map(c => {
+      const clean = {};
+      for (const k of allowedFields) {
+        if (c[k] !== undefined) clean[k] = c[k];
+      }
+      return clean;
+    });
+
+    const session = await getSession(userId);
+    await session.context.addCookies(sanitized);
+    const result = { ok: true, userId: String(userId), count: sanitized.length };
+    log('info', 'cookies imported', { reqId: req.reqId, userId: String(userId), count: sanitized.length });
+    res.json(result);
+  } catch (err) {
+    log('error', 'cookie import failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
+  }
+});
 
 let browser = null;
 // userId -> { context, tabGroups: Map<sessionKey, Map<tabId, TabState>>, lastAccess }
@@ -17,18 +157,8 @@ const sessions = new Map();
 
 const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 min
 const MAX_SNAPSHOT_NODES = 500;
-const DEBUG_RESPONSES = true; // Log response payloads
-
-function logResponse(endpoint, data) {
-  if (!DEBUG_RESPONSES) return;
-  let logData = data;
-  // Truncate snapshot for readability
-  if (data && data.snapshot) {
-    const snap = data.snapshot;
-    logData = { ...data, snapshot: `[${snap.length} chars] ${snap.slice(0, 300)}...` };
-  }
-  console.log(`📤 ${endpoint} ->`, JSON.stringify(logData, null, 2));
-}
+const MAX_SESSIONS = 50;
+const MAX_TABS_PER_SESSION = 10;
 
 // Per-tab locks to serialize operations on the same tab
 // tabId -> Promise (the currently executing operation)
@@ -67,20 +197,43 @@ function getHostOS() {
   return 'linux';
 }
 
+function buildProxyConfig() {
+  const host = process.env.PROXY_HOST;
+  const port = process.env.PROXY_PORT;
+  const username = process.env.PROXY_USERNAME;
+  const password = process.env.PROXY_PASSWORD;
+  
+  if (!host || !port) {
+    log('info', 'no proxy configured');
+    return null;
+  }
+  
+  log('info', 'proxy configured', { host, port });
+  return {
+    server: `http://${host}:${port}`,
+    username,
+    password,
+  };
+}
+
 async function ensureBrowser() {
   if (!browser) {
     const hostOS = getHostOS();
-    console.log(`Launching Camoufox browser (host OS: ${hostOS})...`);
+    const proxy = buildProxyConfig();
+    
+    log('info', 'launching camoufox', { hostOS, geoip: !!proxy });
     
     const options = await launchOptions({
       headless: true,
       os: hostOS,
       humanize: true,
       enable_cache: true,
+      proxy: proxy,
+      geoip: !!proxy,
     });
     
     browser = await firefox.launch(options);
-    console.log('Camoufox browser launched');
+    log('info', 'camoufox launched');
   }
   return browser;
 }
@@ -94,18 +247,26 @@ async function getSession(userId) {
   const key = normalizeUserId(userId);
   let session = sessions.get(key);
   if (!session) {
+    if (sessions.size >= MAX_SESSIONS) {
+      throw new Error('Maximum concurrent sessions reached');
+    }
     const b = await ensureBrowser();
-    const context = await b.newContext({
+    const contextOptions = {
       viewport: { width: 1280, height: 720 },
-      locale: 'en-US',
-      timezoneId: 'America/Los_Angeles',
-      geolocation: { latitude: 37.7749, longitude: -122.4194 },
       permissions: ['geolocation'],
-    });
+    };
+    // When geoip is active (proxy configured), camoufox auto-configures
+    // locale/timezone/geolocation from the proxy IP. Without proxy, use defaults.
+    if (!process.env.PROXY_HOST) {
+      contextOptions.locale = 'en-US';
+      contextOptions.timezoneId = 'America/Los_Angeles';
+      contextOptions.geolocation = { latitude: 37.7749, longitude: -122.4194 };
+    }
+    const context = await b.newContext(contextOptions);
     
     session = { context, tabGroups: new Map(), lastAccess: Date.now() };
     sessions.set(key, session);
-    console.log(`Session created for user ${key}`);
+    log('info', 'session created', { userId: key });
   }
   session.lastAccess = Date.now();
   return session;
@@ -147,7 +308,7 @@ async function waitForPageReady(page, options = {}) {
     
     if (waitForNetwork) {
       await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {
-        console.log('waitForPageReady: networkidle timeout (continuing anyway)');
+        log('warn', 'networkidle timeout, continuing');
       });
     }
     
@@ -168,7 +329,7 @@ async function waitForPageReady(page, options = {}) {
         await new Promise(r => setTimeout(r, 250));
       }
     }).catch(() => {
-      console.log('waitForPageReady: framework hydration wait failed (continuing anyway)');
+      log('warn', 'hydration wait failed, continuing');
     });
     
     await page.waitForTimeout(200);
@@ -178,7 +339,7 @@ async function waitForPageReady(page, options = {}) {
     
     return true;
   } catch (err) {
-    console.log(`waitForPageReady: ${err.message}`);
+    log('warn', 'page ready failed', { error: err.message });
     return false;
   }
 }
@@ -218,7 +379,7 @@ async function dismissConsentDialogs(page) {
       const button = page.locator(selector).first();
       if (await button.isVisible({ timeout: 100 })) {
         await button.click({ timeout: 1000 }).catch(() => {});
-        console.log(`🍪 Auto-dismissed consent dialog via: ${selector}`);
+        log('info', 'dismissed consent dialog', { selector });
         await page.waitForTimeout(300); // Brief pause after dismiss
         break; // Only dismiss one dialog per page load
       }
@@ -232,7 +393,7 @@ async function buildRefs(page) {
   const refs = new Map();
   
   if (!page || page.isClosed()) {
-    console.log('buildRefs: Page is closed or invalid');
+    log('warn', 'buildRefs: page closed or invalid');
     return refs;
   }
   
@@ -245,7 +406,7 @@ async function buildRefs(page) {
   try {
     ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 10000 });
   } catch (err) {
-    console.log('buildRefs: ariaSnapshot failed, retrying after navigation settles');
+    log('warn', 'ariaSnapshot failed, retrying');
     await page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
     ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 10000 });
   }
@@ -271,7 +432,7 @@ async function buildRefs(page) {
   }).catch(() => []);
   
   if (!ariaYaml) {
-    console.log('buildRefs: No aria snapshot available');
+    log('warn', 'buildRefs: no aria snapshot');
     return refs;
   }
   
@@ -354,11 +515,10 @@ app.get('/health', async (req, res) => {
     res.json({ 
       ok: true, 
       engine: 'camoufox',
-      sessions: sessions.size,
       browserConnected: b.isConnected()
     });
   } catch (err) {
-    res.status(500).json({ ok: false, error: err.message });
+    res.status(500).json({ ok: false, error: safeError(err) });
   }
 });
 
@@ -373,6 +533,13 @@ app.post('/tabs', async (req, res) => {
     }
     
     const session = await getSession(userId);
+    
+    let totalTabs = 0;
+    for (const group of session.tabGroups.values()) totalTabs += group.size;
+    if (totalTabs >= MAX_TABS_PER_SESSION) {
+      return res.status(429).json({ error: 'Maximum tabs per session reached' });
+    }
+    
     const group = getTabGroup(session, resolvedSessionKey);
     
     const page = await session.context.newPage();
@@ -381,15 +548,17 @@ app.post('/tabs', async (req, res) => {
     group.set(tabId, tabState);
     
     if (url) {
+      const urlErr = validateUrl(url);
+      if (urlErr) return res.status(400).json({ error: urlErr });
       await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
       tabState.visitedUrls.add(url);
     }
     
-    console.log(`Tab ${tabId} created for user ${userId}, session ${resolvedSessionKey}`);
+    log('info', 'tab created', { reqId: req.reqId, tabId, userId, sessionKey: resolvedSessionKey, url: page.url() });
     res.json({ tabId, url: page.url() });
   } catch (err) {
-    console.error('Create tab error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'tab create failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -415,6 +584,9 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
       return res.status(400).json({ error: 'url or macro required' });
     }
     
+    const urlErr = validateUrl(targetUrl);
+    if (urlErr) return res.status(400).json({ error: urlErr });
+    
     // Serialize navigation operations on the same tab
     const result = await withTabLock(tabId, async () => {
       await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
@@ -423,11 +595,11 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
       return { ok: true, url: tabState.page.url() };
     });
     
-    logResponse(`POST /tabs/${tabId}/navigate`, result);
+    log('info', 'navigated', { reqId: req.reqId, tabId, url: result.url });
     res.json(result);
   } catch (err) {
-    console.error('Navigate error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'navigate failed', { reqId: req.reqId, tabId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -499,11 +671,11 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
       snapshot: annotatedYaml,
       refsCount: tabState.refs.size
     };
-    logResponse(`GET /tabs/${req.params.tabId}/snapshot`, result);
+    log('info', 'snapshot', { reqId: req.reqId, tabId: req.params.tabId, url: result.url, snapshotLen: result.snapshot?.length, refsCount: result.refsCount });
     res.json(result);
   } catch (err) {
-    console.error('Snapshot error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'snapshot failed', { reqId: req.reqId, tabId: req.params.tabId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -520,8 +692,8 @@ app.post('/tabs/:tabId/wait', async (req, res) => {
     
     res.json({ ok: true, ready });
   } catch (err) {
-    console.error('Wait error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'wait failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -561,7 +733,7 @@ app.post('/tabs/:tabId/click', async (req, res) => {
         await tabState.page.waitForTimeout(50);
         await tabState.page.mouse.up();
         
-        console.log(`🖱️ Dispatched full mouse sequence at (${x.toFixed(0)}, ${y.toFixed(0)})`);
+        log('info', 'mouse sequence dispatched', { x: x.toFixed(0), y: y.toFixed(0) });
       };
       
       const doClick = async (locatorOrSelector, isLocator) => {
@@ -573,17 +745,17 @@ app.post('/tabs/:tabId/click', async (req, res) => {
         } catch (err) {
           // Fallback 1: If intercepted by overlay, retry with force
           if (err.message.includes('intercepts pointer events')) {
-            console.log('Click intercepted, retrying with force:true');
+            log('warn', 'click intercepted, retrying with force');
             try {
               await locator.click({ timeout: 5000, force: true });
             } catch (forceErr) {
               // Fallback 2: Full mouse event sequence for stubborn JS handlers
-              console.log('Force click failed, trying full mouse sequence');
+              log('warn', 'force click failed, trying mouse sequence');
               await dispatchMouseSequence(locator);
             }
           } else if (err.message.includes('not visible') || err.message.includes('timeout')) {
             // Fallback 2: Element not responding to click, try mouse sequence
-            console.log('Click timeout/not visible, trying full mouse sequence');
+            log('warn', 'click timeout, trying mouse sequence');
             await dispatchMouseSequence(locator);
           } else {
             throw err;
@@ -610,11 +782,11 @@ app.post('/tabs/:tabId/click', async (req, res) => {
       return { ok: true, url: newUrl };
     });
     
-    logResponse(`POST /tabs/${tabId}/click`, result);
+    log('info', 'clicked', { reqId: req.reqId, tabId, url: result.url });
     res.json(result);
   } catch (err) {
-    console.error('Click error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'click failed', { reqId: req.reqId, tabId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -647,8 +819,8 @@ app.post('/tabs/:tabId/type', async (req, res) => {
     
     res.json({ ok: true });
   } catch (err) {
-    console.error('Type error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'type failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -671,8 +843,8 @@ app.post('/tabs/:tabId/press', async (req, res) => {
     
     res.json({ ok: true });
   } catch (err) {
-    console.error('Press error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'press failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -693,8 +865,8 @@ app.post('/tabs/:tabId/scroll', async (req, res) => {
     
     res.json({ ok: true });
   } catch (err) {
-    console.error('Scroll error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'scroll failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -719,8 +891,8 @@ app.post('/tabs/:tabId/back', async (req, res) => {
     
     res.json(result);
   } catch (err) {
-    console.error('Back error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'back failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -745,8 +917,8 @@ app.post('/tabs/:tabId/forward', async (req, res) => {
     
     res.json(result);
   } catch (err) {
-    console.error('Forward error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'forward failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -771,8 +943,8 @@ app.post('/tabs/:tabId/refresh', async (req, res) => {
     
     res.json(result);
   } catch (err) {
-    console.error('Refresh error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'refresh failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -785,7 +957,7 @@ app.get('/tabs/:tabId/links', async (req, res) => {
     const session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, req.params.tabId);
     if (!found) {
-      console.log(`GET /tabs/${req.params.tabId}/links -> 404 (userId=${userId}, hasSession=${!!session}, sessionUsers=${[...sessions.keys()].join(',')})`);
+      log('warn', 'links: tab not found', { reqId: req.reqId, tabId: req.params.tabId, userId, hasSession: !!session });
       return res.status(404).json({ error: 'Tab not found' });
     }
     
@@ -812,8 +984,8 @@ app.get('/tabs/:tabId/links', async (req, res) => {
       pagination: { total, offset, limit, hasMore: offset + limit < total }
     });
   } catch (err) {
-    console.error('Links error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'links failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -831,8 +1003,8 @@ app.get('/tabs/:tabId/screenshot', async (req, res) => {
     res.set('Content-Type', 'image/png');
     res.send(buffer);
   } catch (err) {
-    console.error('Screenshot error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'screenshot failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -855,8 +1027,8 @@ app.get('/tabs/:tabId/stats', async (req, res) => {
       refsCount: tabState.refs.size
     });
   } catch (err) {
-    console.error('Stats error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'stats failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -869,15 +1041,16 @@ app.delete('/tabs/:tabId', async (req, res) => {
     if (found) {
       await found.tabState.page.close();
       found.group.delete(req.params.tabId);
+      tabLocks.delete(req.params.tabId);
       if (found.group.size === 0) {
         session.tabGroups.delete(found.listItemId);
       }
-      console.log(`Tab ${req.params.tabId} closed for user ${userId}`);
+      log('info', 'tab closed', { reqId: req.reqId, tabId: req.params.tabId, userId });
     }
     res.json({ ok: true });
   } catch (err) {
-    console.error('Close tab error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'tab close failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -890,31 +1063,32 @@ app.delete('/tabs/group/:listItemId', async (req, res) => {
     if (group) {
       for (const [tabId, tabState] of group) {
         await tabState.page.close().catch(() => {});
+        tabLocks.delete(tabId);
       }
       session.tabGroups.delete(req.params.listItemId);
-      console.log(`Tab group ${req.params.listItemId} closed for user ${userId}`);
+      log('info', 'tab group closed', { reqId: req.reqId, listItemId: req.params.listItemId, userId });
     }
     res.json({ ok: true });
   } catch (err) {
-    console.error('Close tab group error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'tab group close failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
 // Close session
 app.delete('/sessions/:userId', async (req, res) => {
   try {
-    const userId = req.params.userId;
-    const session = sessions.get(normalizeUserId(userId));
+    const userId = normalizeUserId(req.params.userId);
+    const session = sessions.get(userId);
     if (session) {
       await session.context.close();
       sessions.delete(userId);
-      console.log(`Session closed for user ${userId}`);
+      log('info', 'session closed', { userId });
     }
     res.json({ ok: true });
   } catch (err) {
-    console.error('Close session error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'session close failed', { error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -925,7 +1099,7 @@ setInterval(() => {
     if (now - session.lastAccess > SESSION_TIMEOUT_MS) {
       session.context.close().catch(() => {});
       sessions.delete(userId);
-      console.log(`Session expired for user ${userId}`);
+      log('info', 'session expired', { userId });
     }
   }
 }, 60_000);
@@ -944,11 +1118,10 @@ app.get('/', async (req, res) => {
       enabled: true,
       running: b.isConnected(),
       engine: 'camoufox',
-      sessions: sessions.size,
       browserConnected: b.isConnected()
     });
   } catch (err) {
-    res.status(500).json({ ok: false, error: err.message });
+    res.status(500).json({ ok: false, error: safeError(err) });
   }
 });
 
@@ -977,20 +1150,33 @@ app.get('/tabs', async (req, res) => {
     
     res.json({ running: true, tabs });
   } catch (err) {
-    console.error('List tabs error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'list tabs failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
 // POST /tabs/open - Open tab (alias for POST /tabs, OpenClaw format)
 app.post('/tabs/open', async (req, res) => {
   try {
-    const { url, userId = 'openclaw', listItemId = 'default' } = req.body;
+    const { url, userId, listItemId = 'default' } = req.body;
+    if (!userId) {
+      return res.status(400).json({ error: 'userId is required' });
+    }
     if (!url) {
       return res.status(400).json({ error: 'url is required' });
     }
     
+    const urlErr = validateUrl(url);
+    if (urlErr) return res.status(400).json({ error: urlErr });
+    
     const session = await getSession(userId);
+    
+    let totalTabs = 0;
+    for (const g of session.tabGroups.values()) totalTabs += g.size;
+    if (totalTabs >= MAX_TABS_PER_SESSION) {
+      return res.status(429).json({ error: 'Maximum tabs per session reached' });
+    }
+    
     const group = getTabGroup(session, listItemId);
     
     const page = await session.context.newPage();
@@ -1001,7 +1187,7 @@ app.post('/tabs/open', async (req, res) => {
     await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
     tabState.visitedUrls.add(url);
     
-    console.log(`[OpenClaw] Tab ${tabId} opened: ${url}`);
+    log('info', 'openclaw tab opened', { reqId: req.reqId, tabId, url: page.url() });
     res.json({ 
       ok: true,
       targetId: tabId,
@@ -1010,8 +1196,8 @@ app.post('/tabs/open', async (req, res) => {
       title: await page.title().catch(() => '')
     });
   } catch (err) {
-    console.error('Open tab error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'openclaw tab open failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -1021,13 +1207,17 @@ app.post('/start', async (req, res) => {
     await ensureBrowser();
     res.json({ ok: true, profile: 'camoufox' });
   } catch (err) {
-    res.status(500).json({ ok: false, error: err.message });
+    res.status(500).json({ ok: false, error: safeError(err) });
   }
 });
 
 // POST /stop - Stop browser (OpenClaw expects this)
 app.post('/stop', async (req, res) => {
   try {
+    const adminKey = req.headers['x-admin-key'];
+    if (!adminKey || !timingSafeCompare(adminKey, process.env.CAMOFOX_ADMIN_KEY || '')) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
     if (browser) {
       await browser.close().catch(() => {});
       browser = null;
@@ -1035,18 +1225,24 @@ app.post('/stop', async (req, res) => {
     sessions.clear();
     res.json({ ok: true, stopped: true, profile: 'camoufox' });
   } catch (err) {
-    res.status(500).json({ ok: false, error: err.message });
+    res.status(500).json({ ok: false, error: safeError(err) });
   }
 });
 
 // POST /navigate - Navigate (OpenClaw format with targetId in body)
 app.post('/navigate', async (req, res) => {
   try {
-    const { targetId, url, userId = 'openclaw' } = req.body;
+    const { targetId, url, userId } = req.body;
+    if (!userId) {
+      return res.status(400).json({ error: 'userId is required' });
+    }
     if (!url) {
       return res.status(400).json({ error: 'url is required' });
     }
     
+    const urlErr = validateUrl(url);
+    if (urlErr) return res.status(400).json({ error: urlErr });
+    
     const session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, targetId);
     if (!found) {
@@ -1065,15 +1261,18 @@ app.post('/navigate', async (req, res) => {
     
     res.json(result);
   } catch (err) {
-    console.error('Navigate error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'openclaw navigate failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
 // GET /snapshot - Snapshot (OpenClaw format with query params)
 app.get('/snapshot', async (req, res) => {
   try {
-    const { targetId, userId = 'openclaw', format = 'text' } = req.query;
+    const { targetId, userId, format = 'text' } = req.query;
+    if (!userId) {
+      return res.status(400).json({ error: 'userId is required' });
+    }
     
     const session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, targetId);
@@ -1120,8 +1319,8 @@ app.get('/snapshot', async (req, res) => {
       refsCount: tabState.refs.size
     });
   } catch (err) {
-    console.error('Snapshot error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'openclaw snapshot failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
   }
 });
 
@@ -1129,7 +1328,10 @@ app.get('/snapshot', async (req, res) => {
 // Routes to click/type/scroll/press/etc based on 'kind' parameter
 app.post('/act', async (req, res) => {
   try {
-    const { kind, targetId, userId = 'openclaw', ...params } = req.body;
+    const { kind, targetId, userId, ...params } = req.body;
+    if (!userId) {
+      return res.status(400).json({ error: 'userId is required' });
+    }
     
     if (!kind) {
       return res.status(400).json({ error: 'kind is required' });
@@ -1253,6 +1455,7 @@ app.post('/act', async (req, res) => {
         case 'close': {
           await tabState.page.close();
           found.group.delete(targetId);
+          tabLocks.delete(targetId);
           return { ok: true, targetId };
         }
         
@@ -1263,9 +1466,37 @@ app.post('/act', async (req, res) => {
     
     res.json(result);
   } catch (err) {
-    console.error('Act error:', err);
-    res.status(500).json({ error: err.message });
+    log('error', 'act failed', { reqId: req.reqId, kind: req.body?.kind, error: err.message });
+    res.status(500).json({ error: safeError(err) });
+  }
+});
+
+// Periodic stats beacon (every 5 min)
+setInterval(() => {
+  const mem = process.memoryUsage();
+  let totalTabs = 0;
+  for (const [, session] of sessions) {
+    for (const [, group] of session.tabGroups) {
+      totalTabs += group.size;
+    }
   }
+  log('info', 'stats', {
+    sessions: sessions.size,
+    tabs: totalTabs,
+    rssBytes: mem.rss,
+    heapUsedBytes: mem.heapUsed,
+    uptimeSeconds: Math.floor(process.uptime()),
+    browserConnected: browser?.isConnected() ?? false,
+  });
+}, 5 * 60_000);
+
+// Crash logging
+process.on('uncaughtException', (err) => {
+  log('error', 'uncaughtException', { error: err.message, stack: err.stack });
+  process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+  log('error', 'unhandledRejection', { reason: String(reason) });
 });
 
 // Graceful shutdown
@@ -1274,10 +1505,10 @@ let shuttingDown = false;
 async function gracefulShutdown(signal) {
   if (shuttingDown) return;
   shuttingDown = true;
-  console.log(`${signal} received, shutting down...`);
+  log('info', 'shutting down', { signal });
 
   const forceTimeout = setTimeout(() => {
-    console.error('Shutdown timed out after 10s, forcing exit');
+    log('error', 'shutdown timed out, forcing exit');
     process.exit(1);
   }, 10000);
   forceTimeout.unref();
@@ -1294,19 +1525,19 @@ async function gracefulShutdown(signal) {
 process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
 process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 
-const PORT = process.env.CAMOFOX_PORT || 9377;
+const PORT = process.env.CAMOFOX_PORT || process.env.PORT || 9377;
 const server = app.listen(PORT, () => {
-  console.log(`camofox-browser listening on port ${PORT}`);
+  log('info', 'server started', { port: PORT, pid: process.pid, nodeVersion: process.version });
   ensureBrowser().catch(err => {
-    console.error('Failed to pre-launch browser:', err.message);
+    log('error', 'browser pre-launch failed', { error: err.message });
   });
 });
 
 server.on('error', (err) => {
   if (err.code === 'EADDRINUSE') {
-    console.error(`FATAL: Port ${PORT} is already in use. Set CAMOFOX_PORT env var to use a different port.`);
+    log('error', 'port in use', { port: PORT });
     process.exit(1);
   }
-  console.error('Server error:', err);
+  log('error', 'server error', { error: err.message });
   process.exit(1);
 });