@askjo/camofox-browser 1.7.4 → 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/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.4",
+  "version": "1.8.0",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.7.4",
+  "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,
@@ -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