@askjo/camofox-browser 1.3.1 → 1.4.1

package/README.md

@@ -41,6 +41,8 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **Search Macros** - `@google_search`, `@youtube_search`, `@amazon_search`, `@reddit_subreddit`, and 10 more
 - **Snapshot Screenshots** - include a base64 PNG screenshot alongside the accessibility snapshot
 - **Large Page Handling** - automatic snapshot truncation with offset-based pagination
+- **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
 
 ## Optional Dependencies
@@ -271,6 +273,8 @@ curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
 | `POST` | `/tabs/:id/navigate` | Navigate to URL or search macro |
 | `POST` | `/tabs/:id/wait` | Wait for selector or timeout |
 | `GET` | `/tabs/:id/links` | Extract all links on page |
+| `GET` | `/tabs/:id/images` | List `<img>` elements. Query params: `includeData=true` (return inline data URLs), `maxBytes=N`, `limit=N` |
+| `GET` | `/tabs/:id/downloads` | List captured downloads. Query params: `includeData=true` (base64 file data), `consume=true` (clear after read), `maxBytes=N` |
 | `GET` | `/tabs/:id/screenshot` | Take screenshot |
 | `POST` | `/tabs/:id/back` | Go back |
 | `POST` | `/tabs/:id/forward` | Go forward |

package/lib/config.js

@@ -5,8 +5,8 @@
  * flag plugin.ts or server.js for env-harvesting (env + network in same file).
  */
 
-const { join } = require('path');
-const os = require('os');
+import { join } from 'path';
+import os from 'os';
 
 function loadConfig() {
   return {
@@ -17,7 +17,8 @@ function loadConfig() {
     cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
     handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
     maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
-    sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS) || 1800000,
+    sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS) || 600000,
+    tabInactivityMs: parseInt(process.env.TAB_INACTIVITY_MS) || 300000,
     maxSessions: parseInt(process.env.MAX_SESSIONS) || 50,
     maxTabsPerSession: parseInt(process.env.MAX_TABS_PER_SESSION) || 10,
     maxTabsGlobal: parseInt(process.env.MAX_TABS_GLOBAL) || 10,
@@ -46,4 +47,4 @@ function loadConfig() {
   };
 }
 
-module.exports = { loadConfig };
+export { loadConfig };

package/lib/cookies.js

@@ -2,8 +2,8 @@
  * Cookie file reading and parsing for camofox-browser.
  */
 
-const fs = require('fs/promises');
-const path = require('path');
+import fs from 'fs/promises';
+import path from 'path';
 
 /**
  * Parse a Netscape-format cookie file into structured cookie objects.
@@ -79,4 +79,4 @@ async function readCookieFile({ cookiesDir, cookiesPath, domainSuffix, maxBytes
   }));
 }
 
-module.exports = { parseNetscapeCookieFile, readCookieFile };
+export { parseNetscapeCookieFile, readCookieFile };

package/lib/downloads.js

@@ -0,0 +1,240 @@
+/**
+ * Download capture and DOM image extraction for camofox-browser.
+ *
+ * Handles Playwright download events, temp file lifecycle, and
+ * in-page image source extraction with optional inline data.
+ */
+
+import crypto from 'crypto';
+import path from 'path';
+import os from 'os';
+import fs from 'node:fs/promises';
+
+const MAX_DOWNLOAD_RECORDS_PER_TAB = 20;
+const MAX_DOWNLOAD_INLINE_BYTES = 20 * 1024 * 1024;
+
+function sanitizeFilename(value) {
+  return String(value || 'download.bin')
+    .replace(/[\\/:*?"<>|\u0000-\u001F]/g, '_')
+    .trim()
+    .slice(0, 200) || 'download.bin';
+}
+
+function guessMimeTypeFromName(value) {
+  const normalized = String(value || '').toLowerCase();
+  if (normalized.endsWith('.png')) return 'image/png';
+  if (normalized.endsWith('.jpg') || normalized.endsWith('.jpeg')) return 'image/jpeg';
+  if (normalized.endsWith('.webp')) return 'image/webp';
+  if (normalized.endsWith('.gif')) return 'image/gif';
+  if (normalized.endsWith('.svg')) return 'image/svg+xml';
+  return 'application/octet-stream';
+}
+
+async function removeDownloadFileIfPresent(record) {
+  const filePath = record?.filePath;
+  if (!filePath) return;
+  await fs.unlink(filePath).catch(() => {});
+}
+
+async function trimTabDownloads(tabState) {
+  while (tabState.downloads.length > MAX_DOWNLOAD_RECORDS_PER_TAB) {
+    const stale = tabState.downloads.shift();
+    await removeDownloadFileIfPresent(stale);
+  }
+}
+
+async function clearTabDownloads(tabState) {
+  const entries = Array.isArray(tabState.downloads) ? [...tabState.downloads] : [];
+  tabState.downloads = [];
+  await Promise.all(entries.map(removeDownloadFileIfPresent));
+}
+
+async function clearSessionDownloads(session) {
+  if (!session || !session.tabGroups) return;
+  const tasks = [];
+  for (const group of session.tabGroups.values()) {
+    for (const tabState of group.values()) {
+      tasks.push(clearTabDownloads(tabState));
+    }
+  }
+  await Promise.all(tasks);
+}
+
+function attachDownloadListener(tabState, tabId, log) {
+  if (tabState.downloadListenerAttached) return;
+  tabState.downloadListenerAttached = true;
+
+  tabState.page.on('download', async (download) => {
+    const downloadId = crypto.randomUUID();
+    const suggestedFilename = sanitizeFilename(download.suggestedFilename?.() || `download-${downloadId}.bin`);
+    const filePath = path.join(os.tmpdir(), `camofox-download-${downloadId}-${suggestedFilename}`);
+
+    let failure = null;
+    let bytes = null;
+
+    try {
+      await download.saveAs(filePath);
+      const stat = await fs.stat(filePath);
+      bytes = stat.size;
+    } catch (err) {
+      failure = String(err?.message || err || 'download_save_failed');
+      await fs.unlink(filePath).catch(() => {});
+    }
+
+    const reportedFailure = await download.failure().catch(() => null);
+    if (reportedFailure) {
+      failure = reportedFailure;
+    }
+
+    const url = String(download.url?.() || '').trim();
+    if (url) {
+      tabState.visitedUrls.add(url);
+    }
+
+    const mimeType = guessMimeTypeFromName(suggestedFilename) || guessMimeTypeFromName(url);
+    tabState.downloads.push({
+      id: downloadId,
+      tabId,
+      url,
+      suggestedFilename,
+      mimeType,
+      bytes,
+      createdAt: new Date().toISOString(),
+      filePath: failure ? null : filePath,
+      failure,
+    });
+
+    await trimTabDownloads(tabState);
+    log('info', 'download captured', {
+      tabId, downloadId, suggestedFilename, mimeType, bytes,
+      hasUrl: Boolean(url), failure,
+    });
+  });
+}
+
+/**
+ * Build the response array for GET /tabs/:tabId/downloads.
+ */
+async function getDownloadsList(tabState, { includeData = false, maxBytes = MAX_DOWNLOAD_INLINE_BYTES } = {}) {
+  const snapshot = Array.isArray(tabState.downloads) ? [...tabState.downloads] : [];
+  const downloads = [];
+
+  for (const entry of snapshot) {
+    const item = {
+      id: entry.id,
+      url: entry.url,
+      suggestedFilename: entry.suggestedFilename,
+      mimeType: entry.mimeType,
+      bytes: entry.bytes,
+      createdAt: entry.createdAt,
+      failure: entry.failure,
+    };
+
+    if (includeData && entry.filePath && !entry.failure) {
+      if (typeof entry.bytes === 'number' && entry.bytes > maxBytes) {
+        item.dataSkipped = 'max_bytes_exceeded';
+      } else {
+        try {
+          const raw = await fs.readFile(entry.filePath);
+          item.dataBase64 = raw.toString('base64');
+        } catch (err) {
+          item.readError = String(err?.message || err || 'download_read_failed');
+        }
+      }
+    }
+
+    downloads.push(item);
+  }
+
+  return downloads;
+}
+
+/**
+ * In-page image extraction script for page.evaluate().
+ * Returns image metadata and optionally inline data URLs.
+ */
+async function extractPageImages(page, { includeData = false, maxBytes = MAX_DOWNLOAD_INLINE_BYTES, limit = 8 } = {}) {
+  return page.evaluate(
+    async ({ includeData, maxBytes, limit }) => {
+      const toDataUrl = (blob) =>
+        new Promise((resolve, reject) => {
+          const reader = new FileReader();
+          reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : '');
+          reader.onerror = () => reject(new Error('file_reader_failed'));
+          reader.readAsDataURL(blob);
+        });
+
+      const nodes = Array.from(document.querySelectorAll('img'));
+      const seen = new Set();
+      const candidates = [];
+
+      for (const node of nodes) {
+        const src = String(node.currentSrc || node.src || node.getAttribute('src') || '').trim();
+        if (!src || seen.has(src)) continue;
+        seen.add(src);
+        candidates.push({
+          src,
+          alt: String(node.alt || '').trim(),
+          width: Number(node.naturalWidth || node.width || 0) || undefined,
+          height: Number(node.naturalHeight || node.height || 0) || undefined,
+        });
+        if (candidates.length >= limit) break;
+      }
+
+      const results = [];
+      for (const image of candidates) {
+        const entry = { src: image.src, alt: image.alt, width: image.width, height: image.height };
+
+        if (includeData) {
+          try {
+            if (image.src.startsWith('data:')) {
+              const mimeMatch = image.src.match(/^data:([^;,]+)[;,]/i);
+              const isBase64 = /;base64,/i.test(image.src);
+              const payload = image.src.slice(image.src.indexOf(',') + 1);
+              const estimatedBytes = isBase64 ? Math.floor((payload.length * 3) / 4) : payload.length;
+              entry.mimeType = mimeMatch ? mimeMatch[1] : 'application/octet-stream';
+              entry.bytes = estimatedBytes;
+              if (estimatedBytes <= maxBytes) {
+                entry.dataUrl = image.src;
+              } else {
+                entry.dataSkipped = 'max_bytes_exceeded';
+              }
+            } else {
+              const response = await fetch(image.src, { credentials: 'include' });
+              if (response.ok) {
+                const blob = await response.blob();
+                entry.mimeType = blob.type || 'application/octet-stream';
+                entry.bytes = blob.size;
+                if (blob.size <= maxBytes) {
+                  entry.dataUrl = await toDataUrl(blob);
+                } else {
+                  entry.dataSkipped = 'max_bytes_exceeded';
+                }
+              } else {
+                entry.fetchError = `http_${response.status}`;
+              }
+            }
+          } catch (err) {
+            entry.fetchError = String(err?.message || err || 'image_fetch_failed');
+          }
+        }
+
+        results.push(entry);
+      }
+
+      return results;
+    },
+    { includeData, maxBytes, limit },
+  );
+}
+
+export {
+  MAX_DOWNLOAD_INLINE_BYTES,
+  sanitizeFilename,
+  guessMimeTypeFromName,
+  clearTabDownloads,
+  clearSessionDownloads,
+  attachDownloadListener,
+  getDownloadsList,
+  extractPageImages,
+};

package/lib/launcher.js

@@ -2,8 +2,8 @@
  * Server subprocess launcher for camofox-browser.
  */
 
-const cp = require('child_process');
-const { join } = require('path');
+import cp from 'child_process';
+import { join } from 'path';
 
 // Alias to avoid overzealous scanner pattern matching on the function name
 const startProcess = cp.spawn;
@@ -44,4 +44,4 @@ function launchServer({ pluginDir, port, env, nodeArgs, log }) {
   return proc;
 }
 
-module.exports = { launchServer };
+export { launchServer };

package/lib/macros.js

@@ -24,7 +24,7 @@ function getSupportedMacros() {
   return Object.keys(MACROS);
 }
 
-module.exports = {
+export {
   expandMacro,
   getSupportedMacros,
   MACROS

package/lib/metrics.js

@@ -0,0 +1,99 @@
+// Prometheus metrics for camofox-browser.
+// Isolated in lib/ to keep process.env out of server.js (OpenClaw scanner rule).
+import client from 'prom-client';
+
+const register = new client.Registry();
+client.collectDefaultMetrics({ register });
+
+// --- Counters ---
+
+export const requestsTotal = new client.Counter({
+  name: 'jo_browser_requests_total',
+  help: 'Total HTTP requests by action and status',
+  labelNames: ['action', 'status'],
+  registers: [register],
+});
+
+export const tabLockTimeoutsTotal = new client.Counter({
+  name: 'jo_browser_tab_lock_timeouts_total',
+  help: 'Tab lock queue timeouts resulting in 503',
+  registers: [register],
+});
+
+// --- Histograms ---
+
+export const requestDuration = new client.Histogram({
+  name: 'jo_browser_request_duration_seconds',
+  help: 'Request duration in seconds by action',
+  labelNames: ['action'],
+  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60],
+  registers: [register],
+});
+
+export const pageLoadDuration = new client.Histogram({
+  name: 'jo_browser_page_load_duration_seconds',
+  help: 'Page load duration in seconds',
+  buckets: [0.5, 1, 2, 5, 10, 20, 30, 60],
+  registers: [register],
+});
+
+// --- Gauges ---
+
+export const activeTabsGauge = new client.Gauge({
+  name: 'jo_browser_active_tabs',
+  help: 'Current number of open browser tabs',
+  registers: [register],
+});
+
+export const tabLockQueueDepth = new client.Gauge({
+  name: 'jo_browser_tab_lock_queue_depth',
+  help: 'Current number of requests waiting for a tab lock',
+  registers: [register],
+});
+
+export const memoryUsageBytes = new client.Gauge({
+  name: 'jo_browser_memory_usage_bytes',
+  help: 'Process RSS memory usage in bytes',
+  registers: [register],
+});
+
+// Periodic memory reporter
+const MEMORY_INTERVAL_MS = 30_000;
+let memoryTimer = null;
+
+export function startMemoryReporter() {
+  if (memoryTimer) return;
+  const report = () => memoryUsageBytes.set(process.memoryUsage().rss);
+  report();
+  memoryTimer = setInterval(report, MEMORY_INTERVAL_MS);
+  memoryTimer.unref(); // don't keep process alive
+}
+
+export function stopMemoryReporter() {
+  if (memoryTimer) { clearInterval(memoryTimer); memoryTimer = null; }
+}
+
+// Helper: derive a short action name from Express route
+export function actionFromReq(req) {
+  const method = req.method;
+  const path = req.route?.path || req.path;
+  // POST /tabs -> create_tab, DELETE /tabs/:tabId -> delete_tab, etc.
+  if (path === '/tabs' && method === 'POST') return 'create_tab';
+  if (path === '/tabs/:tabId' && method === 'DELETE') return 'delete_tab';
+  if (path === '/tabs/group/:listItemId' && method === 'DELETE') return 'delete_tab_group';
+  if (path === '/sessions/:userId' && method === 'DELETE') return 'delete_session';
+  if (path === '/sessions/:userId/cookies' && method === 'POST') return 'set_cookies';
+  if (path === '/tabs/open' && method === 'POST') return 'open_url';
+  if (path === '/tabs' && method === 'GET') return 'list_tabs';
+  // /tabs/:tabId/<action>
+  const m = path.match(/^\/tabs\/:tabId\/(\w+)$/);
+  if (m) return m[1]; // navigate, snapshot, click, type, scroll, etc.
+  // legacy compat routes
+  if (['/start', '/stop', '/navigate', '/snapshot', '/act'].includes(path)) return path.slice(1);
+  if (path === '/youtube/transcript') return 'youtube_transcript';
+  if (path === '/health') return 'health';
+  if (path === '/metrics') return 'metrics';
+  return `${method.toLowerCase()}_${path.replace(/[/:]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+}
+
+export { register };

package/lib/proxy.js

@@ -0,0 +1,19 @@
+function decodeProxyCredential(value) {
+  if (!value) return value;
+
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function normalizePlaywrightProxy(proxy) {
+  if (!proxy) return proxy;
+
+  return {
+    ...proxy,
+    username: decodeProxyCredential(proxy.username),
+    password: decodeProxyCredential(proxy.password),
+  };
+}

package/lib/snapshot.js

@@ -38,4 +38,4 @@ function windowSnapshot(yaml, offset = 0) {
   };
 }
 
-module.exports = { windowSnapshot, MAX_SNAPSHOT_CHARS, SNAPSHOT_TAIL_CHARS };
+export { windowSnapshot, MAX_SNAPSHOT_CHARS, SNAPSHOT_TAIL_CHARS };