@askjo/camofox-browser 1.7.4 → 1.8.1

package/README.md

@@ -42,7 +42,7 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **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
-- **Runs on Anything** - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack — Raspberry Pi, $5 VPS, shared Railway infra.
+- **Runs on Anything** - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack — Raspberry Pi, $5 VPS, shared infra.
 - **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
@@ -113,9 +113,24 @@ make up VERSION=135.0.1 RELEASE=beta.24
 
 > **⚠️ Do not run `docker build` directly.** The Dockerfile uses bind mounts to pull pre-downloaded binaries from `dist/`. Always use `make up` (or `make fetch` then `make build`) — it downloads the binaries first.
 
-### Fly.io / Railway
+### Fly.io
 
-`railway.toml` is included. For Fly.io or other remote CI, you'll need a Dockerfile that downloads binaries at build time instead of using bind mounts — see [jo-browser](https://github.com/jo-inc/jo-browser) for an example.
+For Fly.io or other remote CI, you'll need a Dockerfile that downloads binaries at build time instead of using bind mounts.
+
+### Railway
+
+A `railway.toml` is included. It uses `Dockerfile.ci` (which downloads binaries at build time) and maps Railway's `PORT` env var to `CAMOFOX_PORT` automatically.
+
+```bash
+# Install Railway CLI, then:
+railway link
+railway up
+```
+
+Set secrets via the Railway dashboard or CLI:
+```bash
+railway variables set CAMOFOX_API_KEY="your-generated-key"
+```
 
 ## Usage
 
@@ -252,7 +267,7 @@ curl -X POST http://localhost:9377/sessions/agent1/cookies \
   -d '{"cookies":[{"name":"foo","value":"bar","domain":"example.com","path":"/","expires":-1,"httpOnly":false,"secure":false}]}'
 ```
 
-#### Docker / Fly.io
+#### Docker / Fly.io / Railway
 
 ```bash
 docker run -p 9377:9377 \
@@ -266,6 +281,11 @@ For Fly.io:
 fly secrets set CAMOFOX_API_KEY="your-generated-key"
 ```
 
+For Railway:
+```bash
+railway variables 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.
@@ -480,9 +500,10 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CAMOFOX_PORT` | Server port | `9377` |
-| `PORT` | Server port (fallback, for platforms like Fly.io) | `9377` |
+| `PORT` | Server port (fallback, for platforms like Fly.io, Railway) | `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.1",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

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