@askjo/camofox-browser 1.5.2 → 1.7.0

package/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-slim
+FROM node:20-slim AS camofox-browser
 
 # Pinned Camoufox version for reproducible builds
 # Update these when upgrading Camoufox
@@ -36,6 +36,7 @@ RUN apt-get update && apt-get install -y \
     fontconfig \
     # Utils
     ca-certificates \
+    curl \
     unzip \
     # yt-dlp runtime dependency
     python3-minimal \
@@ -60,11 +61,25 @@ COPY package.json ./
 RUN npm install --production
 
 COPY server.js ./
+COPY camofox.config.json ./
 COPY lib/ ./lib/
+COPY plugins/ ./plugins/
+COPY scripts/ ./scripts/
+
+# Install default plugin dependencies (apt packages + post-install hooks)
+RUN scripts/install-plugin-deps.sh
 
 ENV NODE_ENV=production
-ENV CAMOFOX_PORT=3000
+ENV CAMOFOX_PORT=9377
 
 EXPOSE 9377
 
 CMD ["sh", "-c", "node --max-old-space-size=${MAX_OLD_SPACE_SIZE:-128} server.js"]
+
+# Optional: rebuild plugin deps after adding third-party plugins
+# Usage: docker build --target with-plugins -t camofox-browser .
+FROM camofox-browser AS with-plugins
+COPY plugins/ ./plugins/
+COPY camofox.config.json ./
+COPY scripts/install-plugin-deps.sh /tmp/install-plugin-deps.sh
+RUN /tmp/install-plugin-deps.sh && rm /tmp/install-plugin-deps.sh

package/README.md

@@ -3,20 +3,24 @@
   <h1>camofox-browser</h1>
   <p><strong>Anti-detection browser server for AI agents, powered by Camoufox</strong></p>
   <p>
-    <a href="https://github.com/jo-inc/camofox-browser/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build" /></a>
-    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a>
-    <a href="https://camoufox.com"><img src="https://img.shields.io/badge/engine-Camoufox-red" alt="Camoufox" /></a>
-    <a href="https://hub.docker.com"><img src="https://img.shields.io/badge/docker-ready-blue" alt="Docker" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+    <a href="https://github.com/jo-inc/camofox-browser/stargazers"><img src="https://img.shields.io/github/stars/jo-inc/camofox-browser" alt="GitHub stars" /></a>
+    <a href="https://www.npmjs.com/package/camofox-browser"><img src="https://img.shields.io/npm/v/camofox-browser" alt="npm version" /></a>
+    <a href="https://github.com/jo-inc/camofox-browser/commits"><img src="https://img.shields.io/github/last-commit/jo-inc/camofox-browser" alt="GitHub last commit" /></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.
-    <br/><br/>
-    The same engine behind <a href="https://askjo.ai?ref=camofox">Jo</a> — an AI assistant that doesn't need you to babysit it. Runs half on your Mac, half on a dedicated cloud machine that only you use. Available on macOS, Telegram, and WhatsApp. <a href="https://askjo.ai?ref=camofox">Try the beta free →</a>
   </p>
 </div>
 
 <br/>
 
+> <a href="https://askjo.ai?ref=camofox"><img src="jo-logo.png" alt="Jo" width="80" height="80" align="left" /></a>
+>
+> Built by the team behind <a href="https://askjo.ai?ref=camofox"><strong>jo — a personal AI agent</strong></a> that runs half on your Mac, half on a dedicated cloud machine just for you — with zero maintenance needed. Available on macOS, Telegram, WhatsApp, and email. <a href="https://askjo.ai?ref=camofox">Try the beta free →</a>
+
+<br/>
+
 ```bash
 git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
 npm install && npm start
@@ -50,6 +54,11 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **Download Capture** - capture browser downloads and fetch them via API (optional inline base64)
 - **DOM Image Extraction** - list `<img>` src/alt and optionally return inline data URLs
 - **Deploy Anywhere** - Docker, Fly.io, Railway
+- **VNC Interactive Login** - log into sites visually via noVNC, export storage state for agent reuse
+- **OpenAPI Docs** - auto-generated spec at [`/openapi.json`](http://localhost:9377/openapi.json) and interactive docs at [`/docs`](http://localhost:9377/docs)
+- **Structured Extract** - `POST /tabs/:tabId/extract` with a JSON Schema that maps properties to snapshot refs via `x-ref`
+- **Session Tracing** - opt-in per-session Playwright trace capture (screenshots + DOM snapshots + network) with API endpoints to list, fetch, and delete trace zips
+- **Crash Reporter** - automatic [anonymized crash/hang reporting](lib/reporter.js#L28-L290) via GitHub Issues. Identifies which sites cause failures and common failure patterns. Private domains are HMAC-hashed, paths/params stripped, tokens/IPs redacted. Opt-out with `CAMOFOX_CRASH_REPORT_ENABLED=false`.
 
 ## Optional Dependencies
 
@@ -102,11 +111,11 @@ make up ARCH=x86_64
 make up VERSION=135.0.1 RELEASE=beta.24
 ```
 
-Note: `make fetch` (or `make build`) must be run first — the Dockerfile expects pre-downloaded binaries in `dist/`.
+> **⚠️ 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.toml` and `railway.toml` are included. Deploy with `fly deploy` or connect the repo to Railway.
+`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.
 
 ## Usage
 
@@ -178,6 +187,62 @@ Camoufox browser session                 (authenticated browsing)
 - Max 500 cookies per request, 5MB file size limit
 - Cookie objects are sanitized to an allowlist of Playwright fields
 
+### Session Persistence
+
+By default, camofox persists each user's cookies and localStorage to `~/.camofox/profiles/`. Sessions survive browser restarts — log in once (via cookies or VNC), and subsequent sessions restore the authenticated state automatically.
+
+```
+~/.camofox/
+├── cookies/          # Bootstrap cookie files (Netscape format)
+└── profiles/         # Persisted session state (auto-managed)
+    └── <hashed-userId>/
+        └── storage_state.json
+```
+
+Override the directory with `CAMOFOX_PROFILE_DIR` or set `"profileDir"` in the persistence plugin config. To disable persistence, set `"persistence": { "enabled": false }` in `camofox.config.json`.
+
+### Session Tracing
+
+Capture a Playwright trace of every action in a session: page screenshots, DOM snapshots, network requests, and console output. Output is a single `.zip` file you can open in Playwright's built-in Trace Viewer.
+
+Opt-in per session by passing `trace: true` when opening the first tab:
+
+```bash
+curl -X POST http://localhost:9377/tabs \
+  -H 'Content-Type: application/json' \
+  -d '{"userId":"agent1","sessionKey":"task1","url":"https://example.com","trace":true}'
+```
+
+The trace is written when the session closes. Close the session to flush it, then list, fetch, and view:
+
+```bash
+# Close the session to flush the trace
+curl -X DELETE http://localhost:9377/sessions/agent1
+
+# List trace files
+curl http://localhost:9377/sessions/agent1/traces
+# {"traces":[{"filename":"trace-2026-04-18T04-05-00-...zip","sizeBytes":42810,"createdAt":...}]}
+
+# Download (Content-Type: application/zip)
+curl http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip > session.zip
+
+# View it in Playwright's Trace Viewer
+npx playwright show-trace session.zip
+
+# Delete
+curl -X DELETE http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip
+```
+
+Why traces instead of video: Camoufox is Firefox-based, and Playwright's `recordVideo` is Chromium-only. Traces work on Firefox and give you more than video (network + DOM + console + screenshots).
+
+Tracing cannot be toggled on an existing session. `DELETE /sessions/:userId` first if you need to change the flag.
+
+Storage defaults to `~/.camofox/traces/<hashed-userId>/` and is swept on server startup:
+
+- `CAMOFOX_TRACES_DIR` - base directory (default: `~/.camofox/traces`)
+- `CAMOFOX_TRACES_MAX_BYTES` - max size per trace, removed at next startup if exceeded (default: 50MB)
+- `CAMOFOX_TRACES_TTL_HOURS` - traces older than this are removed at next startup (default: 24)
+
 #### Standalone server usage
 
 ```bash
@@ -247,6 +312,60 @@ When a proxy is configured:
 - Browser fingerprint (language, timezone, coordinates) is consistent with the proxy location
 - Without a proxy, defaults to `en-US`, `America/Los_Angeles`, San Francisco coordinates
 
+### Crash Reporter
+
+Browser automation fails in ways that are hard to predict — Cloudflare challenges, site redesigns breaking selectors, redirect loops, dialog storms, renderer crashes. The scope is wide and the failure modes are diverse. Without telemetry, the only signal is "it didn't work."
+
+The crash reporter gives us structured data on *which sites fail*, *how they fail*, and *how often*, so we can prioritize fixes for the patterns that actually affect users. It files GitHub Issues automatically when:
+
+- **Uncaught exceptions** crash the process
+- **Event loop stalls** exceed 5 seconds (watchdog detection)
+- **Frustration patterns** — 3+ consecutive failures (timeout, dead context, navigation abort) on the same tab
+
+Each report includes the failure type, stack trace, tab health counters (HTTP status histogram, console errors, request failures, redirect depth), and the target URL — all anonymized.
+
+#### Privacy
+
+All reported data goes through paranoid anonymization ([`lib/reporter.js` L28–290](lib/reporter.js#L28-L290)) before leaving the process:
+
+- **URLs** — well-known public domains (Google, Amazon, Reddit, Cloudflare, etc.) are shown verbatim so we can identify which sites cause problems. Private/unknown domains are replaced with a stable HMAC hash (`site-a1b2c3d4`) — same hash across reports for correlation, but not reversible to the original domain. Path segments become `•/•/•` (depth only). Query params become `?[3]` (count only). No keys, values, or path content is ever included.
+- **File paths** → stripped to filename only (`<path>/server.js`)
+- **Tokens, secrets, API keys** → `<token>`
+- **IPs, emails, env vars** → redacted
+- **Docker/Fly machine IDs** → `<id>`
+- **Tab health** — pure counters (crash count, error count, status code histogram). No page content, no URLs, no user data.
+
+Duplicate issues are detected by stack signature and get a `+1` comment instead of a new issue.
+
+Uses a dedicated GitHub App ([Camofox Crash/Stuck Reporter](https://github.com/apps/camofox-crash-stuck-reporter)) with issues-only permissions — no PAT or configuration required.
+
+```bash
+# Disable crash reporting
+export CAMOFOX_CRASH_REPORT_ENABLED=false
+
+# Report to a different repo (default: jo-inc/camofox-browser)
+export CAMOFOX_CRASH_REPORT_REPO=your-org/your-repo
+
+# Adjust rate limit (default: 10 per hour)
+export CAMOFOX_CRASH_REPORT_RATE_LIMIT=5
+```
+
+#### Reporting to your own repo
+
+By default, reports go to `jo-inc/camofox-browser`. To file issues in your own repo instead, create a GitHub App:
+
+1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Set permissions: **Repository → Issues → Read & Write**. Uncheck **Webhook → Active**.
+3. Click **Generate a private key** — downloads a `.pem` file
+4. Install the app on your target repo (Install App → select repo)
+5. Note your **App ID** (number on the app's settings page) and **Installation ID** (from the URL after installing: `github.com/settings/installations/{id}`)
+6. Base64-encode the private key and split it into two halves:
+   ```bash
+   base64 < your-app.pem | tr -d '\n' | fold -w $(($(base64 < your-app.pem | tr -d '\n' | wc -c) / 2)) | head -2
+   ```
+7. Replace `_GH_APP_ID`, `_GH_INSTALL_ID`, `_K_A`, and `_K_B` in `lib/reporter.js` with your values
+8. Set `CAMOFOX_CRASH_REPORT_REPO=your-org/your-repo`
+
 ### Structured Logging
 
 All log output is JSON (one object per line) for easy parsing by log aggregators:
@@ -346,6 +465,7 @@ Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) when available (fast, no browser
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `POST` | `/sessions/:userId/cookies` | Add cookies to a user session (Playwright cookie objects) |
+| `GET` | `/sessions/:userId/storage_state` | Export cookies + localStorage ([VNC plugin](plugins/vnc/)) |
 
 ## Search Macros
 
@@ -364,6 +484,10 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `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` |
+| `CAMOFOX_PROFILE_DIR` | Directory for persisted session profiles | `~/.camofox/profiles` |
+| `CAMOFOX_TRACES_DIR` | Directory for session trace zips | `~/.camofox/traces` |
+| `CAMOFOX_TRACES_MAX_BYTES` | Max size per trace, removed on next startup if exceeded | `52428800` (50MB) |
+| `CAMOFOX_TRACES_TTL_HOURS` | Traces older than this are swept on startup | `24` |
 | `MAX_SESSIONS` | Max concurrent browser sessions | `50` |
 | `MAX_TABS_PER_SESSION` | Max tabs per session | `10` |
 | `SESSION_TIMEOUT_MS` | Session inactivity timeout | `1800000` (30min) |
@@ -382,6 +506,12 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `PROXY_COUNTRY` | Target country for proxy geo-targeting | - |
 | `PROXY_STATE` | Target state/region for proxy geo-targeting | - |
 | `TAB_INACTIVITY_MS` | Close tabs idle longer than this | `300000` (5min) |
+| `CAMOFOX_CRASH_REPORT_ENABLED` | Enable anonymized crash/hang reporter (`false` to disable) | `true` |
+| `CAMOFOX_CRASH_REPORT_REPO` | GitHub repo for issue reports | `jo-inc/camofox-browser` |
+| `CAMOFOX_CRASH_REPORT_RATE_LIMIT` | Max reports per hour | `10` |
+| `ENABLE_VNC` | Enable VNC plugin for interactive browser access (`1`) | - |
+| `VNC_PASSWORD` | Password for VNC access (recommended in production) | - |
+| `NOVNC_PORT` | noVNC web UI port | `6080` |
 
 ## Architecture
 

package/camofox.config.json

@@ -0,0 +1,18 @@
+{
+  "id": "camofox-browser",
+  "name": "Camofox Browser",
+  "version": "1.6.0",
+  "plugins": {
+    "youtube": { "enabled": true },
+    "persistence": { "enabled": true },
+    "vnc": { "resolution": "1920x1080" }
+  },
+  "crashReporter": {
+    "appId": "3503870",
+    "installationId": "127089401",
+    "repo": "jo-inc/camofox-browser",
+    "userAgent": "camofox-crash-reporter",
+    "keyA": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb2dJQkFBS0NBUUVBMDRQRDBWWkNRb1pYdkpCNmYwUHdGRk1scEVzbjF2blFYaHJNSkxlSDdBWElmdGhCCmtpbElUb0xNeWFCVU9aWEdUbXNNYnE2MEd5R1p4RGFQVSt4bGRQdmc2Y2QrUElUNmxSbjB2TCsrd2FNT0llMDQKUEdrallSWW1YZzhqZHFCNEhQcmlKbkQwa2srU0EwVUxBYm5jUHVhTitKNEVFYjBDZUZQRUpzNEJqd0dvcENZMwpaM1VBS2ZBVjh5Slpzc3JVM0lvVlBzckc4dHVnRFhya3JTc2Y0K1Jmdm5lejRibGk1YXJKQ1h3cXJPVE0xRERNCk9mUFhOMENQMWNIWW1XL1p0TVNiRlpsbFRobVdMb05NUXNNdlFEZ3lmWjRXbG9rL1doaWVhTWttWFB6YzFuUkkKMVltNCs0YzZVS2kzOURFSS9MODA5RUZ6OHU0K2lnN1dzaEdsZHdJREFRQUJBb0lCQVFDcC8xQWw4cjhrZXBjUApqY3QyZCtNQVl1ZHhDWnFHbEplYzJzclNnOU94cGVCRDJvbXc4SThWMHRqSEFKNVEvZ2k1UkI1azR2TU1qMC9uCnZMWXJqR2Jxdy9vN3lzT3gzbXNMNVNXbmdqRE5yc0NRRWZuTnkrN01mQ0h3SFJpeW9qeUhoamkzRHJmeTFCTVYKbjZzK0F1UjZoWkQ3amZ6VlNPVXdVcHJuV1ZFMVhuaVBaZmZSd29BQmxEQi92Zm9wWWZpKzhKaXpYQTNVaytlMwp1TEdIZHc2bzJlUkp1bW90RFBubWtsVkVSKy8vcUZpa1BqTGJBSHprNGRTM3hkMWF1ZEFUNU5hczdiUkhGeXFoCkt2eGk2blM4cTAzanBIS0JMQ0hsN212Y1JQUWhYek1XcHVQblVsNGpvRFVDQ0RITG5CcWNmZ3FjTnlzOGhuSkIKaFpueE5pbGhBb0dCQVBKNm04QXo5KytnbzZjMGoxNnFsSXk3V3NyU0liSW80bXZSUEtRc0lnQUxOYTB3TXluNgozWms3NHlTdWJVaWY5c0pwM0pCNFEzdlBqVm",
+    "keyB": "9pSHBDaVZ3ZEttNFFLeC9mMVJITUtCTzVDOFlHK0VsaTlUSWllCkVjWFJMN2VyUmpValIvNjJoZVAvVG96ZXdPckxYbHFlVEEySEJ2S2RJbTFrL2ozNnlWNFVUdm1SQW9HQkFOOVAKSkRpWCt4Y083RnMwOUxxWlYxRFVhK1Rja1RQR1BMMVdlelBEeHc0M0lLVERyL2F1RWs0Mm1pK0NYY0huQk5CagpDT0Y3bEVhRTVENzdVVlZFL3JxR0E3dGdLVER3M2N5cDhQb2x3T1IwK01LUmh5MFpjeG1wcFhlb1dlZm9LVEJaCmtyQjlRbXZrZTMvdWhHUWNqemt3M2dxcE1QRmdFdFlNUUdBY3RtcUhBb0dCQUtobGNnbFhqaGJERHlTdUlldHkKdDl2TXVjOGxnL1ZBNDQ1Ukw3WXNXQ2lEb0hGNGllL2JvMDRxQXlPVVo1MEtTc3JWempJZTgyN213NW9YRy9jQwpaMEpQRkJYdGp0YXJaVEFuZ3lrZElMQWtHb1c2WVk1M2lJeERMTXAzamppVkdnalJKY2NqcForN2kyc0VkYkNsClF0Z2FNRDhKMWNEM1pJSVN5d29sUEh1aEFuOHYrZERPVjlpYUc1cXIvYlNXWWx0Z0FrTXI2RGRKNkUwa1lIQVgKcnZnVlRNSzJvMVFxcXp0RHlYZFd2YXRtL1RzTGlqdGVOaTZrOStnUm4relpaUGxWR1hXenkvVU5qcklZUm1wLwpVNTBkZUFQNXlVcEJaalpVVFI0L2x1dTU1eWJ5UEV4SG5xR21qRy84REVKbFA3MkZpL29vVURFenFuQmhqRUJJClplTExBb0dBWUQxSkp2S0d5U2NtZWVCU0J3TTRlSUF2b3RCMWR2L0NvaThDNVR2Z1F6QWRySE1BTGhIbDNtbVEKajJ3ZnpPOFlEbW45ZmdreDVvVTMyWjJNQTEyVS9mQklJLzVFYWFLK045MVVJanlFUHd1ZU42emR3c0MwT0NXWQovTVYyaFI3dlk1bmN5SUxubG1yRHNRU3htTzIrZmFhUlAxQUVtUit5aUpOUUw2ZlE1RGc9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg=="
+  }
+}

package/lib/auth.js

@@ -0,0 +1,71 @@
+/**
+ * Shared auth middleware for camofox-browser.
+ *
+ * Extracts the duplicated auth pattern from cookie/storage_state endpoints
+ * into a reusable Express middleware factory.
+ *
+ * Policy:
+ *   - 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).
+ *   - Otherwise, reject.
+ */
+
+import crypto from 'crypto';
+
+/**
+ * Timing-safe string comparison.
+ */
+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) {
+    // Compare against self to burn constant time, then return false
+    crypto.timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Check if an address is loopback.
+ */
+function isLoopbackAddress(address) {
+  if (!address) return false;
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
+/**
+ * Create an Express middleware that enforces API key auth.
+ *
+ * @param {object} config - Must have { apiKey, nodeEnv }
+ * @param {object} [options]
+ * @param {string} [options.errorMessage] - Custom error message when rejecting unauthenticated requests
+ * @returns {function} Express middleware (req, res, next)
+ */
+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 next();
+    }
+
+    const remoteAddress = req.socket?.remoteAddress || '';
+    const allowUnauthedLocal = config.nodeEnv !== 'production' && isLoopbackAddress(remoteAddress);
+    if (!allowUnauthedLocal) {
+      return res.status(403).json({ error: errorMessage });
+    }
+
+    next();
+  };
+}
+
+// Re-export utilities so server.js can still use them directly
+export { timingSafeCompare, isLoopbackAddress };

package/lib/config.js

@@ -5,9 +5,22 @@
  * flag plugin.ts or server.js for env-harvesting (env + network in same file).
  */
 
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
 import os from 'os';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, '..');
+
+/** Read crashReporter section from camofox.config.json (if present). */
+function readCrashReporterConfig() {
+  try {
+    const raw = readFileSync(join(ROOT_DIR, 'camofox.config.json'), 'utf-8');
+    return JSON.parse(raw).crashReporter || {};
+  } catch { return {}; }
+}
+
 /**
  * Parse PROXY_PORTS env var into an array of port numbers.
  * Supports range ("10001-10010") or comma-separated ("10001,10002,10003").
@@ -46,6 +59,10 @@ function loadConfig() {
     adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
     apiKey: process.env.CAMOFOX_API_KEY || '',
     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'),
+    tracesMaxBytes: parseInt(process.env.CAMOFOX_TRACES_MAX_BYTES || String(50 * 1024 * 1024), 10),
+    tracesTtlHours: parseInt(process.env.CAMOFOX_TRACES_TTL_HOURS || '24', 10),
     handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
     maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
     sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS) || 600000,
@@ -81,6 +98,9 @@ function loadConfig() {
       CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
       CAMOFOX_API_KEY: process.env.CAMOFOX_API_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,
+      CAMOFOX_TRACES_TTL_HOURS: process.env.CAMOFOX_TRACES_TTL_HOURS,
       PROXY_STRATEGY: process.env.PROXY_STRATEGY,
       PROXY_PROVIDER: process.env.PROXY_PROVIDER,
       PROXY_HOST: process.env.PROXY_HOST,
@@ -96,6 +116,12 @@ function loadConfig() {
       PROXY_ZIP: process.env.PROXY_ZIP,
       PROXY_SESSION_DURATION_MINUTES: process.env.PROXY_SESSION_DURATION_MINUTES,
     },
+    // Crash reporter (opt-in, uses embedded GitHub App credentials)
+    // Crash reporter (opt-in, credentials from camofox.config.json)
+    crashReportEnabled:   process.env.CAMOFOX_CRASH_REPORT_ENABLED !== 'false',
+    crashReportRepo:      process.env.CAMOFOX_CRASH_REPORT_REPO,
+    crashReportRateLimit: parseInt(process.env.CAMOFOX_CRASH_REPORT_RATE_LIMIT, 10) || 10,
+    crashReporterConfig:  readCrashReporterConfig(),
   };
 }
 

package/lib/cookies.js

@@ -79,4 +79,41 @@ async function readCookieFile({ cookiesDir, cookiesPath, domainSuffix, maxBytes
   }));
 }
 
-export { parseNetscapeCookieFile, readCookieFile };
+/**
+ * Import all cookies from the default bootstrap cookie file into a Playwright context.
+ * Intended for first-run session seeding before any persistent storage state exists.
+ * Missing file is treated as a no-op.
+ * @param {object} opts
+ * @param {string} opts.cookiesDir - Base directory for cookie files
+ * @param {object} opts.context - Playwright BrowserContext
+ * @param {string} [opts.cookiesPath='cookies.txt'] - Relative cookie file path within cookiesDir
+ * @param {object} [opts.logger=console] - Logger with warn()
+ * @returns {Promise<{imported: number, source: string|null}>}
+ */
+async function importBootstrapCookies({ cookiesDir, context, cookiesPath = 'cookies.txt', logger = console }) {
+  if (!cookiesDir || !context) {
+    return { imported: 0, source: null };
+  }
+
+  const resolved = path.resolve(cookiesDir, cookiesPath);
+
+  try {
+    const cookies = await readCookieFile({ cookiesDir, cookiesPath });
+    if (cookies.length === 0) {
+      return { imported: 0, source: resolved };
+    }
+    await context.addCookies(cookies);
+    return { imported: cookies.length, source: resolved };
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      return { imported: 0, source: null };
+    }
+    logger?.warn?.('failed to import bootstrap cookies', {
+      cookiesPath: resolved,
+      error: err?.message || String(err),
+    });
+    return { imported: 0, source: resolved };
+  }
+}
+
+export { parseNetscapeCookieFile, readCookieFile, importBootstrapCookies };

package/lib/downloads.js

@@ -60,7 +60,7 @@ async function clearSessionDownloads(session) {
   await Promise.all(tasks);
 }
 
-function attachDownloadListener(tabState, tabId, log) {
+function attachDownloadListener(tabState, tabId, log, pluginEvents, userId) {
   if (tabState.downloadListenerAttached) return;
   tabState.downloadListenerAttached = true;
 
@@ -69,6 +69,11 @@ function attachDownloadListener(tabState, tabId, log) {
     const suggestedFilename = sanitizeFilename(download.suggestedFilename?.() || `download-${downloadId}.bin`);
     const filePath = path.join(os.tmpdir(), `camofox-download-${downloadId}-${suggestedFilename}`);
 
+    const url = String(download.url?.() || '').trim();
+    if (pluginEvents) {
+      pluginEvents.emit('tab:download:start', { userId: userId || null, tabId, filename: suggestedFilename, url });
+    }
+
     let failure = null;
     let bytes = null;
 
@@ -86,7 +91,6 @@ function attachDownloadListener(tabState, tabId, log) {
       failure = reportedFailure;
     }
 
-    const url = String(download.url?.() || '').trim();
     if (url) {
       tabState.visitedUrls.add(url);
     }
@@ -104,6 +108,10 @@ function attachDownloadListener(tabState, tabId, log) {
       failure,
     });
 
+    if (pluginEvents && !failure) {
+      pluginEvents.emit('tab:download:complete', { userId: userId || null, tabId, filename: suggestedFilename, path: filePath, size: bytes });
+    }
+
     await trimTabDownloads(tabState);
     log('info', 'download captured', {
       tabId, downloadId, suggestedFilename, mimeType, bytes,

package/lib/extract.js

@@ -0,0 +1,74 @@
+const SUPPORTED_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'null']);
+
+export function validateSchema(schema) {
+  if (!schema || typeof schema !== 'object') {
+    return { ok: false, error: 'schema must be an object' };
+  }
+  if (schema.type !== 'object') {
+    return { ok: false, error: 'top-level schema must have type: object' };
+  }
+  if (!schema.properties || typeof schema.properties !== 'object') {
+    return { ok: false, error: 'schema must have a properties object' };
+  }
+  for (const [prop, def] of Object.entries(schema.properties)) {
+    if (!def || typeof def !== 'object') {
+      return { ok: false, error: `property "${prop}" must be an object` };
+    }
+    if (def.type && !SUPPORTED_TYPES.has(def.type)) {
+      return { ok: false, error: `property "${prop}" has unsupported type "${def.type}"` };
+    }
+  }
+  return { ok: true };
+}
+
+function coerceValue(raw, type) {
+  if (raw == null) return null;
+  if (type === 'string' || !type) return String(raw).trim();
+  if (type === 'number') {
+    const n = parseFloat(String(raw).replace(/[^0-9.eE+-]/g, ''));
+    return Number.isFinite(n) ? n : null;
+  }
+  if (type === 'integer') {
+    const n = parseInt(String(raw).replace(/[^0-9-]/g, ''), 10);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (type === 'boolean') {
+    const s = String(raw).toLowerCase().trim();
+    if (s === 'true' || s === 'yes' || s === '1') return true;
+    if (s === 'false' || s === 'no' || s === '0') return false;
+    return null;
+  }
+  return raw;
+}
+
+function extractFromRef(refs, refId) {
+  const info = refs.get(refId);
+  if (!info) return null;
+  return info.name || null;
+}
+
+export function extractDeterministic({ schema, refs }) {
+  const check = validateSchema(schema);
+  if (!check.ok) throw new Error(check.error);
+
+  const result = {};
+  for (const [prop, def] of Object.entries(schema.properties)) {
+    const refId = def['x-ref'];
+
+    let value = null;
+    if (refId) {
+      value = extractFromRef(refs, refId);
+      if (value != null && def.type && def.type !== 'object') {
+        value = coerceValue(value, def.type);
+      }
+    }
+
+    if (value == null && Array.isArray(schema.required) && schema.required.includes(prop)) {
+      throw new Error(`required property "${prop}" could not be extracted (x-ref=${refId || 'n/a'})`);
+    }
+
+    result[prop] = value;
+  }
+
+  return result;
+}

package/lib/inflight.js

@@ -0,0 +1,16 @@
+async function coalesceInflight(map, key, factory) {
+  const existing = map.get(key);
+  if (existing) return existing;
+
+  const promise = (async () => {
+    try {
+      return await factory();
+    } finally {
+      map.delete(key);
+    }
+  })();
+  map.set(key, promise);
+  return promise;
+}
+
+export { coalesceInflight };

package/lib/metrics.js

@@ -12,6 +12,27 @@ const noopCounter = { inc() {}, labels() { return this; } };
 const noopHistogram = { observe() {}, startTimer() { return () => {}; }, labels() { return this; } };
 const noopGauge = { set() {}, inc() {}, dec() {}, labels() { return this; } };
 
+/**
+ * Create a metric (Counter, Histogram, or Gauge) registered to the shared registry.
+ * Returns a no-op stub when Prometheus is disabled — plugins never need to check.
+ *
+ * @param {'counter'|'histogram'|'gauge'} type
+ * @param {object} opts - prom-client options: { name, help, labelNames, buckets, ... }
+ * @returns {object} The metric instance or a no-op stub
+ */
+export async function createMetric(type, opts) {
+  if (!_register) {
+    if (type === 'histogram') return noopHistogram;
+    if (type === 'gauge') return noopGauge;
+    return noopCounter;
+  }
+  const client = (await import('prom-client')).default;
+  const MetricClass = type === 'histogram' ? client.Histogram
+    : type === 'gauge' ? client.Gauge
+    : client.Counter;
+  return new MetricClass({ ...opts, registers: [_register] });
+}
+
 function buildNoopMetrics() {
   return {
     requestsTotal: noopCounter,
@@ -24,6 +45,7 @@ function buildNoopMetrics() {
     tabsRecycledTotal: noopCounter,
     requestDuration: noopHistogram,
     pageLoadDuration: noopHistogram,
+    snapshotBytes: noopHistogram,
     activeTabsGauge: noopGauge,
     tabLockQueueDepth: noopGauge,
     memoryUsageBytes: noopGauge,
@@ -93,6 +115,13 @@ async function buildRealMetrics() {
       buckets: [0.5, 1, 2, 5, 10, 20, 30, 60],
       registers: [_register],
     }),
+    snapshotBytes: new client.Histogram({
+      name: 'camofox_snapshot_bytes',
+      help: 'Size of accessibility tree snapshots in bytes (before windowing)',
+      labelNames: ['type'],
+      buckets: [1000, 5000, 10000, 25000, 50000, 80000, 120000, 200000, 500000],
+      registers: [_register],
+    }),
     activeTabsGauge: new client.Gauge({
       name: 'camofox_active_tabs',
       help: 'Current number of open browser tabs',