@askjo/camofox-browser 1.7.3 → 1.8.0

package/README.md

@@ -483,6 +483,7 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `PORT` | Server port (fallback, for platforms like Fly.io) | `9377` |
 | `CAMOFOX_API_KEY` | Enable cookie import endpoint (disabled if unset) | - |
 | `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - |
+| `CAMOFOX_ACCESS_KEY` | If set, all routes (except `/health`, cookie import, and `/stop`) require `Authorization: Bearer <key>`. Lets you safely expose the server beyond loopback. | - |
 | `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` |
 | `CAMOFOX_PROFILE_DIR` | Directory for persisted session profiles | `~/.camofox/profiles` |
 | `CAMOFOX_TRACES_DIR` | Directory for session trace zips | `~/.camofox/traces` |

package/lib/auth.js

@@ -4,10 +4,16 @@
  * Extracts the duplicated auth pattern from cookie/storage_state endpoints
  * into a reusable Express middleware factory.
  *
- * Policy:
+ * Policy (requireAuth / per-route):
  *   - If CAMOFOX_API_KEY is set, require Bearer token match (timing-safe).
- *   - If not set and NODE_ENV !== production, allow loopback (127.0.0.1 / ::1).
+ *   - If CAMOFOX_ACCESS_KEY is set, also accept it as an alternative (superkey).
+ *   - If neither key set and NODE_ENV !== production, allow loopback (127.0.0.1 / ::1).
  *   - Otherwise, reject.
+ *
+ * Policy (accessKeyMiddleware / global):
+ *   - If CAMOFOX_ACCESS_KEY is set, require Bearer match on all routes except
+ *     /health, cookie import (when CAMOFOX_API_KEY set), and /stop (when CAMOFOX_ADMIN_KEY set).
+ *   - If not set, pass through (backward-compatible).
  */
 
 import crypto from 'crypto';
@@ -38,7 +44,12 @@ function isLoopbackAddress(address) {
 /**
  * Create an Express middleware that enforces API key auth.
  *
- * @param {object} config - Must have { apiKey, nodeEnv }
+ * Accepts CAMOFOX_API_KEY as primary token. When CAMOFOX_ACCESS_KEY is also
+ * configured, it is accepted as an alternative ("superkey") so that routes
+ * gated by both the global access-key middleware AND this per-route middleware
+ * don't require two different tokens in a single Authorization header.
+ *
+ * @param {object} config - Must have { apiKey, nodeEnv }; optionally { accessKey }
  * @param {object} [options]
  * @param {string} [options.errorMessage] - Custom error message when rejecting unauthenticated requests
  * @returns {function} Express middleware (req, res, next)
@@ -47,16 +58,27 @@ export function requireAuth(config, options = {}) {
   const errorMessage = options.errorMessage ||
     'This endpoint requires CAMOFOX_API_KEY except for loopback requests in non-production environments.';
 
-  return (req, res, next) => {
-    if (config.apiKey) {
-      const auth = String(req.headers['authorization'] || '');
-      const match = auth.match(/^Bearer\s+(.+)$/i);
-      if (!match || !timingSafeCompare(match[1], config.apiKey)) {
-        return res.status(403).json({ error: 'Forbidden' });
-      }
+  return function requireAuthCheck(req, res, next) {
+    const auth = String(req.headers['authorization'] || '');
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    const token = match ? match[1]?.trim() : null;
+
+    // Accept API key
+    if (config.apiKey && token && timingSafeCompare(token, config.apiKey)) {
+      return next();
+    }
+
+    // Accept access key as alternative (superkey)
+    if (config.accessKey && token && timingSafeCompare(token, config.accessKey)) {
       return next();
     }
 
+    // If any key is configured, a valid token was required — reject
+    if (config.apiKey || config.accessKey) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+
+    // No keys configured — allow loopback in non-production
     const remoteAddress = req.socket?.remoteAddress || '';
     const allowUnauthedLocal = config.nodeEnv !== 'production' && isLoopbackAddress(remoteAddress);
     if (!allowUnauthedLocal) {
@@ -67,5 +89,46 @@ export function requireAuth(config, options = {}) {
   };
 }
 
+/**
+ * Global access-key middleware factory.
+ *
+ * When CAMOFOX_ACCESS_KEY is set, requires `Authorization: Bearer <key>` on
+ * every route except:
+ *   - GET /health (Docker/Fly healthcheck)
+ *   - POST /sessions/:userId/cookies (only when CAMOFOX_API_KEY is also set — has its own gate)
+ *   - POST /stop (only when CAMOFOX_ADMIN_KEY is also set — has its own gate)
+ *
+ * When a route's dedicated key is NOT configured, the access-key middleware
+ * does NOT exempt it — defense-in-depth prevents unprotected endpoints.
+ *
+ * When CAMOFOX_ACCESS_KEY is not set, passes through (backward-compatible).
+ *
+ * @param {object} config - Must have { accessKey }; optionally { apiKey, adminKey }
+ * @returns {function} Express middleware (req, res, next)
+ */
+export function accessKeyMiddleware(config) {
+  return function accessKeyCheck(req, res, next) {
+    if (!config.accessKey) return next();
+
+    // Exempt healthcheck
+    if (req.path === '/health') return next();
+
+    // Exempt routes with their own dedicated auth — but only when their key is configured.
+    // If the dedicated key is NOT set, the access key gates the route (defense-in-depth).
+    if (config.apiKey && req.method === 'POST' && /^\/sessions\/[^/]+\/cookies$/.test(req.path)) return next();
+    if (config.adminKey && req.method === 'POST' && req.path === '/stop') return next();
+
+    const auth = String(req.headers['authorization'] || '');
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    const token = match ? match[1]?.trim() : null;
+    if (!token || !timingSafeCompare(token, config.accessKey)) {
+      return res.status(401)
+        .set('WWW-Authenticate', 'Bearer realm="camofox"')
+        .json({ error: 'Unauthorized' });
+    }
+    next();
+  };
+}
+
 // Re-export utilities so server.js can still use them directly
 export { timingSafeCompare, isLoopbackAddress };

package/lib/config.js

@@ -58,6 +58,7 @@ function loadConfig() {
     flyApiToken: process.env.FLY_API_TOKEN || '',
     adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
     apiKey: process.env.CAMOFOX_API_KEY || '',
+    accessKey: (process.env.CAMOFOX_ACCESS_KEY || '').trim(),
     cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
     profileDir: process.env.CAMOFOX_PROFILE_DIR || join(os.homedir(), '.camofox', 'profiles'),
     tracesDir: process.env.CAMOFOX_TRACES_DIR || join(os.homedir(), '.camofox', 'traces'),
@@ -97,6 +98,7 @@ function loadConfig() {
       NODE_ENV: process.env.NODE_ENV,
       CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
       CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
+      CAMOFOX_ACCESS_KEY: process.env.CAMOFOX_ACCESS_KEY,
       CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
       CAMOFOX_TRACES_DIR: process.env.CAMOFOX_TRACES_DIR,
       CAMOFOX_TRACES_MAX_BYTES: process.env.CAMOFOX_TRACES_MAX_BYTES,

package/lib/openapi.js

@@ -52,7 +52,12 @@ const swaggerDefinition = {
       BearerAuth: {
         type: 'http',
         scheme: 'bearer',
-        description: 'Bearer token matching CAMOFOX_API_KEY.',
+        description: 'Bearer token matching CAMOFOX_API_KEY (per-route auth for sensitive endpoints like cookie import and traces).',
+      },
+      AccessKeyAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        description: 'Bearer token matching CAMOFOX_ACCESS_KEY. When set, gates all routes except /health, cookie import, and /stop. Acts as a superkey — also accepted by endpoints that normally require CAMOFOX_API_KEY.',
       },
     },
     schemas: {

package/lib/reporter.js

@@ -789,7 +789,13 @@ export function createReporter(config) {
 
   const enabled = config.crashReportEnabled !== false && !!_GH_APP_ID;
   const repo = config.crashReportRepo || cr.repo || 'jo-inc/camofox-browser';
-  const rateLimiter = new RateLimiter(config.crashReportRateLimit || 10);
+  const rateLimiters = {
+    crash: new RateLimiter(5),   // 5 crashes/hr
+    hang: new RateLimiter(5),    // 5 hangs/hr
+    stuck: new RateLimiter(2),   // 2 stalls/hr (with active tabs only)
+    leak: new RateLimiter(2),    // 2 leak alerts/hr
+    _default: new RateLimiter(config.crashReportRateLimit || 10),
+  };
   const version = config.version || 'unknown';
 
   let watchdogInterval = null;
@@ -816,7 +822,9 @@ export function createReporter(config) {
 
   /** Core: file or deduplicate a report. NEVER throws. */
   async function fileReport(type, labels, detail) {
-    if (!rateLimiter.tryAcquire()) return;
+    const bucket = type.startsWith('stuck:') ? 'stuck' : type.startsWith('hang:') ? 'hang' : type.startsWith('leak:') ? 'leak' : 'crash';
+    const limiter = rateLimiters[bucket] || rateLimiters._default;
+    if (!limiter.tryAcquire()) return;
 
     const reportPromise = (async () => {
       try {
@@ -990,7 +998,7 @@ export function createReporter(config) {
 
     // Suppress false positives from OS sleep/suspend (laptop lid close, VM pause).
     // Stalls > 120s are almost certainly not event-loop bugs.
-    const MAX_REPORTABLE_DRIFT_MS = 120_000;
+    const MAX_REPORTABLE_DRIFT_MS = 60_000;
     let suppressTicksRemaining = 0;
     const SUPPRESS_TICKS_AFTER_WAKE = 5;
 
@@ -1100,6 +1108,11 @@ export function createReporter(config) {
         // Remove resourceOpts from extra so it doesn't end up in context
         delete extra.resourceOpts;
 
+        // Don't report idle-server stalls — no user impact
+        if ((resources.activeTabs || 0) === 0 && (resources.browserContexts || 0) === 0) {
+          return;
+        }
+
         // Event loop delay histogram snapshot
         let elDelay = null;
         if (elHistogram) {
@@ -1118,6 +1131,8 @@ export function createReporter(config) {
 
         fileReport('stuck:event-loop', labels, {
           message: `Event loop stalled for ${Math.round(drift / 1000)}s (threshold: ${Math.round(thresholdMs / 1000)}s)`,
+          // Stable signature: duration is NOT included — all stalls on the same route dedup
+          error: { name: 'EventLoopStall', message: _lastRoute || 'idle', stack: '' },
           uptimeMinutes: typeof process !== 'undefined'
             ? Math.round(process.uptime() / 60) : undefined,
           resources,
@@ -1177,6 +1192,6 @@ export function createReporter(config) {
     resetNativeMemBaseline,
     _anonymize: anonymize,
     _stackSignature: stackSignature,
-    _rateLimiter: rateLimiter,
+    _rateLimiter: rateLimiters,
   };
 }

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.7.3",
+  "version": "1.8.0",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

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

package/server.js

@@ -10,7 +10,7 @@ import { loadConfig } from './lib/config.js';
 import { normalizePlaywrightProxy, createProxyPool, buildProxyUrl } from './lib/proxy.js';
 import { createFlyHelpers } from './lib/fly.js';
 import { createPluginEvents, loadPlugins } from './lib/plugins.js';
-import { requireAuth, timingSafeCompare as _timingSafeCompare, isLoopbackAddress as _isLoopbackAddress } from './lib/auth.js';
+import { requireAuth, accessKeyMiddleware, timingSafeCompare as _timingSafeCompare, isLoopbackAddress as _isLoopbackAddress } from './lib/auth.js';
 import { windowSnapshot } from './lib/snapshot.js';
 import {
   MAX_DOWNLOAD_INLINE_BYTES,
@@ -55,7 +55,7 @@ function _browserPid() {
 function _resourceOpts() {
   return { sessionCount: sessions.size, tabCount: _countTabs(), browserPid: _browserPid() };
 }
-reporter.startWatchdog(5000, () => {
+reporter.startWatchdog(30_000, () => {
   const summary = [];
   for (const [sid, session] of sessions) {
     const tabUrls = [];
@@ -142,6 +142,12 @@ const FLY_MACHINE_ID = fly.machineId;
 // Route tab requests to the owning machine via fly-replay header.
 app.use('/tabs/:tabId', fly.replayMiddleware(log));
 
+// Access-key middleware: gates every route when CAMOFOX_ACCESS_KEY is set.
+// Exempts /health (Docker healthcheck) and routes that have their own
+// dedicated keys (cookie import → CAMOFOX_API_KEY, /stop → CAMOFOX_ADMIN_KEY)
+// so each key gates a distinct surface. When unset, behavior is unchanged.
+app.use(accessKeyMiddleware(CONFIG));
+
 const ALLOWED_URL_SCHEMES = ['http:', 'https:'];
 
 // Interactive roles to include - exclude combobox to avoid opening complex widgets