@phi-code-admin/camofox-browser 1.0.0

package/lib/openapi.js

@@ -0,0 +1,105 @@
+/**
+ * OpenAPI spec generation via swagger-jsdoc + docs UI (swagger-stripey).
+ *
+ * swagger-jsdoc scans JSDoc `@openapi` comments on route handlers in server.js
+ * (and any file passed in `apis`) to build the spec at startup.
+ * Docs UI lives in docs/api.html (swagger-stripey: Stripe-style 3-panel renderer).
+ *
+ * Usage:
+ *   import { mountDocs } from './lib/openapi.js';
+ *   // After all routes are registered:
+ *   mountDocs(app);
+ */
+
+import swaggerJsdoc from 'swagger-jsdoc';
+import express from 'express';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let version = 'unknown';
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  version = pkg.version;
+} catch { /* ignore */ }
+
+const swaggerDefinition = {
+  openapi: '3.0.3',
+  info: {
+    title: 'camofox-browser',
+    version,
+    description:
+      'Anti-detection browser automation server for AI agents. ' +
+      'Accessibility snapshots, element refs, session isolation, cookie import, proxy rotation, and structured logs.',
+    license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' },
+    contact: { name: 'Jo Inc', url: 'https://askjo.ai', email: 'oss@askjo.ai' },
+  },
+  servers: [{ url: 'http://localhost:9377', description: 'Local development' }],
+  tags: [
+    { name: 'System', description: 'Server health, metrics, and status.' },
+    { name: 'Tabs', description: 'Create, list, inspect, and destroy browser tabs.' },
+    { name: 'Navigation', description: 'Navigate tabs to URLs or via search macros.' },
+    { name: 'Interaction', description: 'Click, type, scroll, press keys, evaluate JS.' },
+    { name: 'Content', description: 'Accessibility snapshots, screenshots, links, images, downloads.' },
+    { name: 'Sessions', description: 'Per-user session state: cookies, teardown.' },
+    { name: 'Browser', description: 'Global browser lifecycle (start/stop).' },
+    { name: 'Legacy', description: 'OpenClaw-compatible endpoints (deprecated).' },
+  ],
+  components: {
+    securitySchemes: {
+      BearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        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: {
+      Error: {
+        type: 'object',
+        required: ['error'],
+        properties: { error: { type: 'string' } },
+      },
+    },
+  },
+};
+
+/**
+ * Mount GET /openapi.json and GET /docs on the Express app.
+ * Call AFTER all routes are registered so swagger-jsdoc can scan them.
+ *
+ * @param {import('express').Application} app
+ * @param {Object} [opts]
+ * @param {string[]} [opts.apis] - Glob patterns for files with @openapi JSDoc (default: ['./server.js'])
+ */
+export function mountDocs(app, opts = {}) {
+  const apis = opts.apis || ['./server.js'];
+
+  const spec = swaggerJsdoc({
+    definition: swaggerDefinition,
+    apis,
+  });
+
+  app.get('/openapi.json', (_req, res) => {
+    res.json(spec);
+  });
+
+  // Serve docs static assets (api.html, fox.png, openapi.json)
+  const docsDir = join(__dirname, '..', 'docs');
+  app.use('/docs', express.static(docsDir, { index: 'api.html' }));
+
+  // Also serve fox.png at root for backward compat with old Swagger UI HTML
+  app.get('/fox.png', (_req, res) => {
+    res.sendFile(join(docsDir, 'fox.png'));
+  });
+
+  return spec;
+}
+
+export { swaggerDefinition };

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,175 @@
+/**
+ * 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:destroying      { userId, reason }               -- before context close (context still alive)
+ *     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/proxy.js

@@ -0,0 +1,277 @@
+import crypto from 'crypto';
+
+// ---------------------------------------------------------------------------
+// Credential helpers
+// ---------------------------------------------------------------------------
+
+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),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Session helpers
+// ---------------------------------------------------------------------------
+
+function makeSessionId(prefix = 'sess') {
+  return `${prefix}-${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Provider interface
+// ---------------------------------------------------------------------------
+//
+// A proxy provider shapes credentials and declares capabilities.
+//
+//   {
+//     name:              string   -- e.g. 'decodo', 'brightdata', 'generic'
+//     canRotateSessions: bool     -- per-context session rotation supported
+//     launchRetries:     number   -- how many browser launch attempts
+//     launchTimeoutMs:   number   -- per-attempt timeout
+//     buildSessionUsername(baseUsername, options) -> string
+//     buildProxyUrl(proxy, config) -> string | null
+//   }
+//
+// options: { country, state, city, zip, sessionId, sessionDurationMinutes }
+// ---------------------------------------------------------------------------
+
+function sanitizeBackconnectValue(value) {
+  if (!value) return '';
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '_')
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+/**
+ * Decodo residential proxy provider.
+ * Username DSL: user-{base}-country-{cc}-state-{st}-session-{id}-sessionduration-{min}
+ */
+export const decodoProvider = {
+  name: 'decodo',
+  canRotateSessions: true,
+  launchRetries: 10,
+  launchTimeoutMs: 180000,
+
+  buildSessionUsername(baseUsername, options = {}) {
+    const username = sanitizeBackconnectValue(baseUsername);
+    if (!username) return '';
+
+    const parts = [`user-${username}`];
+    const country = sanitizeBackconnectValue(options.country);
+    const state = sanitizeBackconnectValue(options.state);
+    const city = sanitizeBackconnectValue(options.city);
+    const zip = sanitizeBackconnectValue(options.zip);
+    const sessionId = sanitizeBackconnectValue(options.sessionId);
+    const sessionDurationMinutes = Number.isFinite(options.sessionDurationMinutes)
+      ? Math.max(1, Math.min(1440, Math.trunc(options.sessionDurationMinutes)))
+      : null;
+
+    if (country) parts.push(`country-${country}`);
+    if (state) parts.push(`state-${state}`);
+    if (city) parts.push(`city-${city}`);
+    if (zip) parts.push(`zip-${zip}`);
+    if (sessionId) parts.push(`session-${sessionId}`);
+    if (sessionDurationMinutes) parts.push(`sessionduration-${sessionDurationMinutes}`);
+
+    return parts.join('-');
+  },
+
+  buildProxyUrl(proxy, config) {
+    if (!proxy?.username || !config?.password) return null;
+    const user = encodeURIComponent(proxy.username);
+    const pass = encodeURIComponent(config.password);
+    const host = config.backconnectHost;
+    const port = config.backconnectPort;
+    return `http://${user}:${pass}@${host}:${port}`;
+  },
+};
+
+/**
+ * Generic backconnect provider -- no username rewriting, just pass-through.
+ * Works with any SOCKS/HTTP proxy that supports sticky sessions via
+ * separate session IDs in the username field (e.g. BrightData, Oxylabs).
+ */
+export const genericBackconnectProvider = {
+  name: 'generic',
+  canRotateSessions: true,
+  launchRetries: 5,
+  launchTimeoutMs: 120000,
+
+  buildSessionUsername(baseUsername, options = {}) {
+    // Simple pass-through: base username + session suffix
+    const base = String(baseUsername || '').trim();
+    const sessionId = options.sessionId ? `-${String(options.sessionId).trim()}` : '';
+    return `${base}${sessionId}`;
+  },
+
+  buildProxyUrl(proxy, config) {
+    if (!proxy?.username || !config?.password) return null;
+    const user = encodeURIComponent(proxy.username);
+    const pass = encodeURIComponent(config.password);
+    const host = config.backconnectHost;
+    const port = config.backconnectPort;
+    return `http://${user}:${pass}@${host}:${port}`;
+  },
+};
+
+// Provider registry
+const providers = {
+  decodo: decodoProvider,
+  generic: genericBackconnectProvider,
+};
+
+export function getProvider(name) {
+  return providers[name] || null;
+}
+
+export function registerProvider(name, provider) {
+  providers[name] = provider;
+}
+
+// ---------------------------------------------------------------------------
+// Proxy pool factory
+// ---------------------------------------------------------------------------
+
+function buildBackconnectProxy(config, provider, sessionId) {
+  const username = provider.buildSessionUsername(config.username, {
+    country: config.country,
+    state: config.state,
+    city: config.city,
+    zip: config.zip,
+    sessionId,
+    sessionDurationMinutes: config.sessionDurationMinutes,
+  });
+
+  return {
+    server: `http://${config.backconnectHost}:${config.backconnectPort}`,
+    username,
+    password: config.password,
+    sessionId,
+  };
+}
+
+/**
+ * Create proxy strategy helpers.
+ * - round_robin: per-context port rotation across a fixed pool
+ * - backconnect: residential backconnect endpoint with sticky sessions (provider-shaped)
+ */
+export function createProxyPool(config) {
+  const {
+    strategy = 'round_robin',
+    host,
+    ports,
+    username,
+    password,
+    backconnectHost,
+    backconnectPort,
+    providerName,
+  } = config;
+
+  if (strategy === 'backconnect') {
+    if (!backconnectHost || !backconnectPort || !username || !password) return null;
+
+    const provider = getProvider(providerName || 'decodo') || decodoProvider;
+
+    return {
+      mode: 'backconnect',
+      provider,
+      canRotateSessions: provider.canRotateSessions,
+      launchRetries: provider.launchRetries,
+      launchTimeoutMs: provider.launchTimeoutMs,
+      size: 1,
+
+      getLaunchProxy(sessionId = makeSessionId('browser')) {
+        return buildBackconnectProxy(config, provider, sessionId);
+      },
+
+      getNext(sessionId = makeSessionId('ctx')) {
+        return buildBackconnectProxy(config, provider, sessionId);
+      },
+    };
+  }
+
+  // round_robin -- no session rotation, single attempt
+  if (!host || !ports || ports.length === 0) return null;
+
+  let index = 0;
+
+  function makeProxy(port) {
+    return {
+      server: `http://${host}:${port}`,
+      username,
+      password,
+    };
+  }
+
+  return {
+    mode: 'round_robin',
+    provider: null,
+    canRotateSessions: false,
+    launchRetries: 1,
+    launchTimeoutMs: 60000,
+    size: ports.length,
+
+    getLaunchProxy() {
+      return makeProxy(ports[0]);
+    },
+
+    getNext() {
+      const port = ports[index % ports.length];
+      index++;
+      return makeProxy(port);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// URL builder (for CLI tools like yt-dlp)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a proxy URL string (http://user:pass@host:port) suitable for
+ * CLI tools like yt-dlp --proxy.
+ */
+export function buildProxyUrl(pool, config) {
+  if (!pool) return null;
+
+  if (pool.mode === 'backconnect') {
+    const proxy = pool.getLaunchProxy(makeSessionId('ytdlp'));
+    if (pool.provider?.buildProxyUrl) {
+      return pool.provider.buildProxyUrl(proxy, config);
+    }
+    // Fallback for pools without provider
+    if (!proxy?.username || !config?.password) return null;
+    const user = encodeURIComponent(proxy.username);
+    const pass = encodeURIComponent(config.password);
+    return `http://${user}:${pass}@${config.backconnectHost}:${config.backconnectPort}`;
+  }
+
+  // round_robin -- pick the first port
+  if (!config?.host || !config?.ports?.length) return null;
+  const user = config.username ? encodeURIComponent(config.username) : '';
+  const pass = config.password ? encodeURIComponent(config.password) : '';
+  const auth = user ? `${user}:${pass}@` : '';
+  return `http://${auth}${config.host}:${config.ports[0]}`;
+}
+
+// Legacy alias for backward compatibility
+export function buildDecodoBackconnectUsername(baseUsername, options) {
+  return decodoProvider.buildSessionUsername(baseUsername, options);
+}