@askjo/camofox-browser 1.5.2 → 1.7.0

package/lib/openapi.js

@@ -0,0 +1,100 @@
+/**
+ * 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.',
+      },
+    },
+    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;
+}