@askjo/camofox-browser 1.5.2 → 1.6.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

@@ -50,6 +50,7 @@ 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
 
 ## Optional Dependencies
 
@@ -178,6 +179,20 @@ 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`.
+
 #### Standalone server usage
 
 ```bash
@@ -346,6 +361,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 +380,7 @@ 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` |
 | `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 +399,9 @@ 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) |
+| `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,10 @@
+{
+  "id": "camofox-browser",
+  "name": "Camofox Browser",
+  "version": "1.6.0",
+  "plugins": {
+    "youtube": { "enabled": true },
+    "persistence": { "enabled": true },
+    "vnc": { "resolution": "1920x1080" }
+  }
+}

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

@@ -46,6 +46,7 @@ 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'),
     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,

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/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',

package/lib/persistence.js

@@ -0,0 +1,89 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+function getUserPersistencePaths(profileDir, userId) {
+  const rootDir = path.resolve(profileDir);
+  const safeUserDir = crypto
+    .createHash('sha256')
+    .update(String(userId))
+    .digest('hex')
+    .slice(0, 32);
+
+  const userDir = path.join(rootDir, safeUserDir);
+  return {
+    rootDir,
+    userDir,
+    storageStatePath: path.join(userDir, 'storage-state.json'),
+    metaPath: path.join(userDir, 'meta.json'),
+  };
+}
+
+async function loadPersistedStorageState(profileDir, userId, logger = console) {
+  if (!profileDir) return undefined;
+
+  const { storageStatePath } = getUserPersistencePaths(profileDir, userId);
+
+  try {
+    const raw = await fs.readFile(storageStatePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return undefined;
+    if (!Array.isArray(parsed.cookies)) return undefined;
+    if (parsed.origins !== undefined && !Array.isArray(parsed.origins)) return undefined;
+    return storageStatePath;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return undefined;
+    logger?.warn?.('failed to load persisted storage state', {
+      userId: String(userId),
+      storageStatePath,
+      error: err?.message || String(err),
+    });
+    return undefined;
+  }
+}
+
+async function persistStorageState({ profileDir, userId, context, logger = console }) {
+  if (!profileDir || !context) {
+    return { persisted: false, reason: 'disabled' };
+  }
+
+  const { userDir, storageStatePath, metaPath } = getUserPersistencePaths(profileDir, userId);
+  const suffix = `.tmp-${process.pid}-${Date.now()}`;
+  const tmpStoragePath = `${storageStatePath}${suffix}`;
+  const tmpMetaPath = `${metaPath}${suffix}`;
+
+  try {
+    await fs.mkdir(userDir, { recursive: true });
+    await context.storageState({ path: tmpStoragePath });
+    await fs.rename(tmpStoragePath, storageStatePath);
+    await fs.writeFile(
+      tmpMetaPath,
+      JSON.stringify(
+        {
+          userId: String(userId),
+          updatedAt: new Date().toISOString(),
+          storageStatePath,
+        },
+        null,
+        2
+      )
+    );
+    await fs.rename(tmpMetaPath, metaPath);
+    return { persisted: true, userDir, storageStatePath, metaPath };
+  } catch (err) {
+    await fs.unlink(tmpStoragePath).catch(() => {});
+    await fs.unlink(tmpMetaPath).catch(() => {});
+    logger?.warn?.('failed to persist storage state', {
+      userId: String(userId),
+      storageStatePath,
+      error: err?.message || String(err),
+    });
+    return { persisted: false, reason: 'error', error: err };
+  }
+}
+
+export {
+  getUserPersistencePaths,
+  loadPersistedStorageState,
+  persistStorageState,
+};

package/lib/plugins.js

@@ -0,0 +1,174 @@
+/**
+ * Camofox-browser plugin system.
+ *
+ * Plugins live in plugins/<name>/index.js and export a register(app, ctx) function.
+ * The ctx object provides access to sessions, config, logging, auth middleware,
+ * core functions, and an EventEmitter for lifecycle hooks.
+ *
+ * 29 events across 7 categories:
+ *
+ *   BROWSER LIFECYCLE
+ *     browser:launching       { options }                      — mutate launch options
+ *     browser:launched        { browser, display }             — after launch
+ *     browser:restart         { reason }                       — before restart cycle
+ *     browser:closed          { reason }                       — after browser closed
+ *     browser:error           { error }                        — uncaught browser error
+ *
+ *   SESSION LIFECYCLE
+ *     session:creating        { userId, contextOptions }       — mutate context options
+ *     session:created         { userId, context }              — after context stored
+ *     session:destroyed       { userId, reason }               — after cleanup
+ *     session:expired         { userId, idleMs }               — reaper triggered
+ *
+ *   TAB LIFECYCLE
+ *     tab:created             { userId, tabId, page, url }
+ *     tab:navigated           { userId, tabId, url, prevUrl }
+ *     tab:destroyed           { userId, tabId, reason }
+ *     tab:recycled            { userId, tabId }
+ *     tab:error               { userId, tabId, error }
+ *
+ *   CONTENT
+ *     tab:snapshot            { userId, tabId, snapshot }
+ *     tab:screenshot          { userId, tabId, buffer }
+ *     tab:evaluate            { userId, tabId, expression }
+ *     tab:evaluated           { userId, tabId, result }
+ *
+ *   INPUT
+ *     tab:click               { userId, tabId, ref, selector }
+ *     tab:type                { userId, tabId, text, ref, mode }
+ *     tab:scroll              { userId, tabId, direction, amount }
+ *     tab:press               { userId, tabId, key }
+ *
+ *   DOWNLOADS
+ *     tab:download:start      { userId, tabId, filename, url }
+ *     tab:download:complete   { userId, tabId, filename, path, size }
+ *
+ *   COOKIES / AUTH
+ *     session:cookies:import  { userId, count }
+ *     session:storage:export  { userId }
+ *
+ *   SERVER
+ *     server:starting         { port }
+ *     server:started          { port, pid }
+ *     server:shutdown         { signal }
+ *
+ * Mutating hooks (browser:launching, session:creating) pass the options object
+ * by reference — plugins can modify it in place before core uses it.
+ */
+
+import { EventEmitter } from 'events';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = path.join(__dirname, '..');
+const PLUGINS_DIR = path.join(ROOT_DIR, 'plugins');
+const CONFIG_PATH = path.join(ROOT_DIR, 'camofox.config.json');
+
+/**
+ * Read plugin configuration from camofox.config.json.
+ * Supports two formats:
+ *   - Array of strings: ["youtube", "persistence"] (no per-plugin config)
+ *   - Object with per-plugin config: { "youtube": { "enabled": true }, "persistence": { "enabled": true, "profileDir": "/data" } }
+ * Returns { list: string[] | null, configs: Map<string, object> }
+ */
+function readPluginConfig() {
+  const configs = new Map();
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+    const config = JSON.parse(raw);
+    if (!config.plugins) return { list: null, configs };
+    if (Array.isArray(config.plugins)) {
+      return { list: config.plugins, configs };
+    }
+    if (typeof config.plugins === 'object') {
+      const list = [];
+      for (const [name, pluginConf] of Object.entries(config.plugins)) {
+        if (pluginConf === false || (typeof pluginConf === 'object' && pluginConf.enabled === false)) continue;
+        list.push(name);
+        if (typeof pluginConf === 'object') configs.set(name, pluginConf);
+      }
+      return { list, configs };
+    }
+  } catch {}
+  return { list: null, configs };
+}
+
+/**
+ * Create the plugin event bus.
+ */
+export function createPluginEvents() {
+  const events = new EventEmitter();
+  events.setMaxListeners(50); // generous for many plugins
+
+  /**
+   * Emit an event and await all listeners (including async ones).
+   * Use for mutating hooks where plugins must finish before core continues.
+   * Regular emit() is still used for fire-and-forget observational events.
+   */
+  events.emitAsync = async function emitAsync(eventName, payload) {
+    const listeners = this.listeners(eventName);
+    await Promise.all(listeners.map(fn => fn(payload)));
+  };
+
+  return events;
+}
+
+/**
+ * Load and register all plugins from plugins/<name>/index.js.
+ *
+ * @param {object} app - Express app
+ * @param {object} ctx - Plugin context: { sessions, config, log, events, auth, ensureBrowser, getSession, destroySession }
+ *                       Mutable — plugins can replace ctx.createVirtualDisplay etc.
+ * @returns {string[]} - Names of loaded plugins
+ */
+export async function loadPlugins(app, ctx) {
+  const loaded = [];
+
+  if (!fs.existsSync(PLUGINS_DIR)) {
+    ctx.log('info', 'no plugins directory found, skipping plugin load');
+    return loaded;
+  }
+
+  const { list: allowList, configs: pluginConfigs } = readPluginConfig();
+  const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+
+    // Skip directories starting with _ or .
+    if (name.startsWith('_') || name.startsWith('.')) continue;
+
+    // If camofox.config.json specifies a plugins list, only load those
+    if (allowList && !allowList.includes(name)) {
+      ctx.log('debug', `plugin "${name}" not in camofox.config.json plugins list, skipping`);
+      continue;
+    }
+
+    const indexPath = path.join(PLUGINS_DIR, name, 'index.js');
+    if (!fs.existsSync(indexPath)) {
+      ctx.log('warn', `plugin "${name}" has no index.js, skipping`);
+      continue;
+    }
+
+    try {
+      const mod = await import(indexPath);
+      const register = mod.default || mod.register;
+      if (typeof register !== 'function') {
+        ctx.log('warn', `plugin "${name}" does not export a register function, skipping`);
+        continue;
+      }
+
+      const pluginConfig = pluginConfigs.get(name) || {};
+      await register(app, ctx, pluginConfig);
+      loaded.push(name);
+      ctx.log('info', 'plugin loaded', { plugin: name });
+    } catch (err) {
+      ctx.log('error', 'plugin load failed', { plugin: name, error: err.message, stack: err.stack });
+    }
+  }
+
+  return loaded;
+}

package/lib/tmp-cleanup.js

@@ -0,0 +1,40 @@
+import fs from 'fs';
+import path from 'path';
+
+const ORPHAN_PATTERNS = [
+  /^\.fea5[a-f0-9]+\.so$/,
+  /^\.5ef7[a-f0-9]+\.node$/,
+];
+
+export function cleanupOrphanedTempFiles({ tmpDir, minAgeMs = 5 * 60 * 1000, now = Date.now() } = {}) {
+  const result = { scanned: 0, removed: 0, bytes: 0, skipped: 0 };
+  if (!tmpDir) return result;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(tmpDir);
+  } catch {
+    return result;
+  }
+
+  for (const name of entries) {
+    if (!ORPHAN_PATTERNS.some((re) => re.test(name))) continue;
+    result.scanned++;
+    const full = path.join(tmpDir, name);
+    try {
+      const st = fs.statSync(full);
+      if (!st.isFile()) continue;
+      if (now - st.mtimeMs < minAgeMs) {
+        result.skipped++;
+        continue;
+      }
+      fs.unlinkSync(full);
+      result.removed++;
+      result.bytes += st.size;
+    } catch {
+      // file vanished, permission denied, or race with another process - skip silently
+    }
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "type": "module",
   "main": "server.js",
@@ -37,6 +37,8 @@
   "files": [
     "server.js",
     "lib/",
+    "plugins/",
+    "camofox.config.json",
     "plugin.ts",
     "openclaw.plugin.json",
     "scripts/",
@@ -54,8 +56,10 @@
     "start": "node server.js",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest --runInBand --forceExit",
     "test:e2e": "NODE_OPTIONS='--experimental-vm-modules' jest --runInBand --forceExit tests/e2e",
+    "test:plugins": "NODE_OPTIONS='--experimental-vm-modules' jest --forceExit plugins/",
     "test:live": "RUN_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest --runInBand --forceExit tests/live",
     "test:debug": "DEBUG_SERVER=1 NODE_OPTIONS='--experimental-vm-modules' jest --runInBand --forceExit",
+    "plugin": "node scripts/plugin.js",
     "version:sync": "node scripts/sync-version.js",
     "version": "node scripts/sync-version.js && git add openclaw.plugin.json",
     "postinstall": "npx camoufox-js fetch || true"