@askjo/camofox-browser 1.5.1 → 1.6.0

package/plugins/vnc/index.js

@@ -0,0 +1,142 @@
+/**
+ * VNC plugin for camofox-browser.
+ *
+ * Exposes Camoufox's virtual display via noVNC so a human can interact with
+ * the browser visually — log into sites, solve CAPTCHAs, approve OAuth prompts.
+ * After interactive login, export the storage state via the API endpoint this
+ * plugin registers.
+ *
+ * Architecture:
+ *   Plugin replaces the default 1x1 Xvfb with a 1920x1080 display (via
+ *   ctx.createVirtualDisplay factory override). vnc-watcher.sh detects the
+ *   Xvfb process, attaches x11vnc, and noVNC (websockify) proxies it to a
+ *   web UI on port 6080.
+ *
+ * Configuration (camofox.config.json):
+ *   {
+ *     "plugins": {
+ *       "vnc": {
+ *         "enabled": true,
+ *         "resolution": "1920x1080",
+ *         "password": "",
+ *         "viewOnly": false,
+ *         "vncPort": 5900,
+ *         "novncPort": 6080
+ *       }
+ *     }
+ *   }
+ *
+ * Or via environment variables (override config):
+ *   ENABLE_VNC=1           Enable the plugin
+ *   VNC_RESOLUTION=1920x1080
+ *   VNC_PASSWORD=secret    Optional password for x11vnc
+ *   VIEW_ONLY=1            View-only mode (no mouse/keyboard input)
+ *   VNC_PORT=5900          x11vnc listen port
+ *   NOVNC_PORT=6080        noVNC web UI port
+ *
+ * Registers:
+ *   GET /sessions/:userId/storage_state — export Playwright storageState as JSON
+ *
+ * Events emitted:
+ *   vnc:watcher:started    { pid }
+ *   vnc:watcher:stopped    { code, signal }
+ *   vnc:storage:exported   { userId, cookies, origins }
+ */
+
+import { resolveVncConfig, startWatcher } from './vnc-launcher.js';
+import { requireAuth } from '../../lib/auth.js';
+
+export async function register(app, ctx, pluginConfig = {}) {
+  const { events, config, log, sessions, VirtualDisplay, safeError } = ctx;
+
+  // Resolve all config (env vars + pluginConfig) via the launcher module
+  const vncConfig = resolveVncConfig(pluginConfig);
+
+  if (!vncConfig.enabled) {
+    log('info', 'vnc plugin: disabled (set ENABLE_VNC=1 or plugins.vnc.enabled=true)');
+    return;
+  }
+
+  // --- Override Xvfb resolution ---
+  const { resolution } = vncConfig;
+
+  class VncVirtualDisplay extends VirtualDisplay {
+    get xvfb_args() {
+      const args = super.xvfb_args;
+      const idx = args.indexOf('0');
+      if (idx > 0 && args[idx - 1] === '-screen') {
+        const patched = [...args];
+        patched[idx + 1] = resolution;
+        return patched;
+      }
+      return args;
+    }
+  }
+
+  ctx.createVirtualDisplay = () => new VncVirtualDisplay();
+  log('info', 'vnc plugin: overriding Xvfb resolution', { resolution });
+
+  // --- VNC watcher process ---
+  log('info', 'vnc plugin enabled', {
+    resolution,
+    novncPort: vncConfig.novncPort,
+    vncPort: vncConfig.vncPort,
+    viewOnly: vncConfig.viewOnly,
+    passwordProtected: !!vncConfig.vncPassword,
+  });
+
+  const watcher = startWatcher({
+    resolution: vncConfig.resolution,
+    vncPassword: vncConfig.vncPassword,
+    viewOnly: vncConfig.viewOnly,
+    vncPort: vncConfig.vncPort,
+    novncPort: vncConfig.novncPort,
+    log,
+    events,
+  });
+
+  // Clean up watcher on server shutdown
+  events.on('server:shutdown', () => {
+    if (watcher.exitCode === null) {
+      log('info', 'killing vnc watcher on shutdown');
+      watcher.kill('SIGTERM');
+    }
+  });
+
+  // --- HTTP endpoint: GET /sessions/:userId/storage_state ---
+  const authMiddleware = requireAuth(config);
+
+  app.get('/sessions/:userId/storage_state', authMiddleware, async (req, res) => {
+    try {
+      const userId = req.params.userId;
+      const session = sessions.get(String(userId));
+      if (!session) {
+        return res.status(404).json({ error: `No active session for userId="${userId}"` });
+      }
+
+      const state = await session.context.storageState();
+
+      log('info', 'storage_state exported', {
+        reqId: req.reqId,
+        userId: String(userId),
+        cookies: state.cookies?.length || 0,
+        origins: state.origins?.length || 0,
+      });
+
+      events.emit('vnc:storage:exported', {
+        userId: String(userId),
+        cookies: state.cookies?.length || 0,
+        origins: state.origins?.length || 0,
+      });
+
+      events.emit('session:storage:export', { userId: String(userId) });
+
+      res.json(state);
+    } catch (err) {
+      log('error', 'storage_state export failed', { reqId: req.reqId, error: err.message });
+      res.status(500).json({ error: safeError(err) });
+    }
+  });
+
+  log('info', 'vnc plugin: registered GET /sessions/:userId/storage_state');
+}

package/plugins/vnc/vnc-launcher.js

@@ -0,0 +1,64 @@
+/**
+ * VNC launcher — owns all child_process spawning and process.env reads.
+ * Isolated from route handlers for OpenClaw scanner compliance.
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve VNC configuration from pluginConfig + env var fallbacks.
+ * All process.env reads live here — callers get a plain config object.
+ */
+export function resolveVncConfig(pluginConfig = {}) {
+  const enabled = process.env.ENABLE_VNC === '1' || pluginConfig.enabled === true;
+
+  const rawResolution = process.env.VNC_RESOLUTION || pluginConfig.resolution || '1920x1080';
+  const resolution = rawResolution.includes('x', rawResolution.indexOf('x') + 1)
+    ? rawResolution
+    : `${rawResolution}x24`;
+
+  const vncPassword = process.env.VNC_PASSWORD || pluginConfig.password || '';
+  const viewOnly = process.env.VIEW_ONLY === '1' || pluginConfig.viewOnly === true;
+  const vncPort = process.env.VNC_PORT || pluginConfig.vncPort || '5900';
+  const novncPort = process.env.NOVNC_PORT || pluginConfig.novncPort || '6080';
+
+  return { enabled, resolution, vncPassword, viewOnly, vncPort, novncPort };
+}
+
+/**
+ * Start the vnc-watcher.sh child process.
+ * Returns the spawned ChildProcess.
+ */
+export function startWatcher({ resolution, vncPassword, viewOnly, vncPort, novncPort, log, events }) {
+  const watcherPath = path.join(__dirname, 'vnc-watcher.sh');
+  const watcher = spawn('sh', [watcherPath], {
+    env: {
+      ...process.env,
+      VNC_PASSWORD: vncPassword,
+      VNC_RESOLUTION: resolution,
+      VIEW_ONLY: viewOnly ? '1' : '0',
+      VNC_PORT: String(vncPort),
+      NOVNC_PORT: String(novncPort),
+    },
+    stdio: ['ignore', 'inherit', 'inherit'],
+    detached: false,
+  });
+
+  watcher.on('error', (err) => {
+    log('error', 'vnc watcher failed to start', { error: err.message });
+  });
+
+  watcher.on('exit', (code, signal) => {
+    log('warn', 'vnc watcher exited', { code, signal });
+    events.emit('vnc:watcher:stopped', { code, signal });
+  });
+
+  log('info', 'vnc watcher started', { pid: watcher.pid });
+  events.emit('vnc:watcher:started', { pid: watcher.pid });
+
+  return watcher;
+}

package/plugins/vnc/vnc-watcher.sh

@@ -0,0 +1,82 @@
+#!/bin/sh
+# VNC watcher: detects Camoufox's dynamically-assigned Xvfb display and attaches
+# x11vnc + noVNC to it. Handles browser restarts (re-attaches on display change).
+#
+# Called by the VNC plugin via child_process.spawn. Not meant to run standalone.
+#
+# Env vars (set by the plugin):
+#   VNC_PASSWORD    If set, x11vnc requires this password
+#   VIEW_ONLY       "1" for view-only mode
+#   VNC_PORT        VNC port (default: 5900)
+#   NOVNC_PORT      noVNC websocket port (default: 6080)
+
+set -e
+
+VNC_PORT="${VNC_PORT:-5900}"
+NOVNC_PORT="${NOVNC_PORT:-6080}"
+VNC_RESOLUTION="${VNC_RESOLUTION:-1920x1080x24}"
+
+log() { printf '[vnc-watcher] %s\n' "$*" >&2; }
+
+CURRENT_DISPLAY=""
+X11VNC_PID=""
+
+# Prepare password file if requested
+PASSFILE=""
+if [ -n "${VNC_PASSWORD:-}" ]; then
+  mkdir -p /tmp/.vnc
+  x11vnc -storepasswd "$VNC_PASSWORD" /tmp/.vnc/passwd >/dev/null 2>&1
+  PASSFILE="/tmp/.vnc/passwd"
+  log "x11vnc: password protected"
+else
+  log "x11vnc: NO password (bind $NOVNC_PORT to 127.0.0.1 on host + SSH tunnel)"
+fi
+
+# Start noVNC (websockify) — proxies to x11vnc regardless of whether it's up yet
+NOVNC_DIR="/usr/share/novnc"
+if [ ! -d "$NOVNC_DIR" ]; then
+  log "ERROR: $NOVNC_DIR not found; noVNC cannot start"
+  exit 1
+fi
+VNC_BIND="${VNC_BIND:-127.0.0.1}"
+log "Starting noVNC (websockify) on $VNC_BIND:$NOVNC_PORT -> 127.0.0.1:$VNC_PORT"
+websockify --web "$NOVNC_DIR" "$VNC_BIND:$NOVNC_PORT" "127.0.0.1:$VNC_PORT" >/var/log/novnc.log 2>&1 &
+
+log "VNC watcher started — will attach x11vnc when Camoufox's Xvfb appears"
+
+while true; do
+  # Find Xvfb with our patched resolution
+  FOUND=$(ps -eo args= 2>/dev/null | awk -v res="$VNC_RESOLUTION" '
+    /\/Xvfb :[0-9]+/ && index($0, res) {
+      for (i=1;i<=NF;i++) if ($i ~ /^:[0-9]+$/) { print $i; exit }
+    }
+  ' | head -1)
+
+  if [ -n "$FOUND" ] && [ "$FOUND" != "$CURRENT_DISPLAY" ]; then
+    # New or changed display — (re)attach x11vnc
+    if [ -n "$X11VNC_PID" ] && kill -0 "$X11VNC_PID" 2>/dev/null; then
+      log "Camoufox display changed ($CURRENT_DISPLAY -> $FOUND), restarting x11vnc"
+      kill "$X11VNC_PID" 2>/dev/null || true
+      sleep 0.5
+    fi
+
+    CURRENT_DISPLAY="$FOUND"
+    log "Attaching x11vnc to DISPLAY=$CURRENT_DISPLAY"
+
+    X11VNC_ARGS="-display $CURRENT_DISPLAY -forever -shared -rfbport $VNC_PORT -noxdamage -quiet -bg -o /var/log/x11vnc.log"
+    [ "${VIEW_ONLY:-0}" = "1" ] && X11VNC_ARGS="$X11VNC_ARGS -viewonly"
+    if [ -n "$PASSFILE" ]; then
+      X11VNC_ARGS="$X11VNC_ARGS -rfbauth $PASSFILE"
+    else
+      X11VNC_ARGS="$X11VNC_ARGS -nopw"
+    fi
+
+    # shellcheck disable=SC2086
+    x11vnc $X11VNC_ARGS
+    sleep 1
+    X11VNC_PID=$(pgrep -f "x11vnc.*-display $CURRENT_DISPLAY" | head -1)
+    log "x11vnc running (pid=$X11VNC_PID) on DISPLAY=$CURRENT_DISPLAY"
+  fi
+
+  sleep 2
+done

package/plugins/vnc/vnc.test.js

@@ -0,0 +1,204 @@
+import { EventEmitter } from 'node:events';
+import { jest } from '@jest/globals';
+
+// Mock the launcher module — index.js no longer imports child_process directly
+const mockWatcher = () => {
+  const proc = new EventEmitter();
+  proc.pid = 12345;
+  proc.exitCode = null;
+  proc.kill = jest.fn();
+  return proc;
+};
+const mockStartWatcher = jest.fn(mockWatcher);
+const mockResolveVncConfig = jest.fn((pluginConfig = {}) => ({
+  enabled: pluginConfig.enabled || false,
+  resolution: pluginConfig.resolution
+    ? (pluginConfig.resolution.split('x').length > 2 ? pluginConfig.resolution : `${pluginConfig.resolution}x24`)
+    : '1920x1080x24',
+  vncPassword: pluginConfig.password || '',
+  viewOnly: pluginConfig.viewOnly || false,
+  vncPort: pluginConfig.vncPort || '5900',
+  novncPort: pluginConfig.novncPort || '6080',
+}));
+
+jest.unstable_mockModule('./vnc-launcher.js', () => ({
+  resolveVncConfig: mockResolveVncConfig,
+  startWatcher: mockStartWatcher,
+}));
+
+// Mock auth middleware
+jest.unstable_mockModule('../../lib/auth.js', () => ({
+  requireAuth: () => (_req, _res, next) => next(),
+}));
+
+// Minimal VirtualDisplay mock (real class has side-effects that break in test)
+class MockVirtualDisplay {
+  get xvfb_args() {
+    return ['-screen', '0', '1x1x24', '-ac', '-nolisten', 'tcp'];
+  }
+}
+
+const { register } = await import('./index.js');
+
+describe('vnc plugin', () => {
+  let events, ctx, mockApp, routes;
+
+  beforeEach(() => {
+    events = new EventEmitter();
+    events.setMaxListeners(50);
+    routes = {};
+    mockApp = {
+      get: jest.fn((path, ...handlers) => { routes[`GET ${path}`] = handlers; }),
+    };
+    ctx = {
+      events,
+      config: {},
+      log: jest.fn(),
+      sessions: new Map(),
+      safeError: (err) => typeof err === 'string' ? err : (err?.message || 'Internal error'),
+      VirtualDisplay: MockVirtualDisplay,
+      createVirtualDisplay: () => new MockVirtualDisplay(),
+    };
+    mockStartWatcher.mockClear();
+    mockStartWatcher.mockImplementation(mockWatcher);
+    mockResolveVncConfig.mockClear();
+    mockResolveVncConfig.mockImplementation((pluginConfig = {}) => ({
+      enabled: pluginConfig.enabled || false,
+      resolution: pluginConfig.resolution
+        ? (pluginConfig.resolution.split('x').length > 2 ? pluginConfig.resolution : `${pluginConfig.resolution}x24`)
+        : '1920x1080x24',
+      vncPassword: pluginConfig.password || '',
+      viewOnly: pluginConfig.viewOnly || false,
+      vncPort: pluginConfig.vncPort || '5900',
+      novncPort: pluginConfig.novncPort || '6080',
+    }));
+  });
+
+  test('does not register when disabled', async () => {
+    await register(mockApp, ctx, {});
+    expect(mockStartWatcher).not.toHaveBeenCalled();
+    expect(mockApp.get).not.toHaveBeenCalled();
+  });
+
+  test('registers when pluginConfig.enabled is true', async () => {
+    await register(mockApp, ctx, { enabled: true });
+    expect(mockStartWatcher).toHaveBeenCalled();
+    expect(mockApp.get).toHaveBeenCalledWith(
+      '/sessions/:userId/storage_state',
+      expect.any(Function),
+      expect.any(Function),
+    );
+  });
+
+  test('passes resolved config to startWatcher', async () => {
+    await register(mockApp, ctx, { enabled: true, password: 'secret', vncPort: 5901 });
+    expect(mockStartWatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        vncPassword: 'secret',
+        vncPort: 5901,
+        log: ctx.log,
+        events,
+      }),
+    );
+  });
+
+  test('overrides createVirtualDisplay with custom resolution', async () => {
+    await register(mockApp, ctx, { enabled: true, resolution: '1280x720' });
+
+    const vd = ctx.createVirtualDisplay();
+    const args = vd.xvfb_args;
+    const screenIdx = args.indexOf('0');
+    expect(args[screenIdx + 1]).toBe('1280x720x24');
+  });
+
+  test('appends x24 depth to WxH resolution', async () => {
+    await register(mockApp, ctx, { enabled: true, resolution: '1920x1080' });
+
+    const vd = ctx.createVirtualDisplay();
+    const args = vd.xvfb_args;
+    const screenIdx = args.indexOf('0');
+    expect(args[screenIdx + 1]).toBe('1920x1080x24');
+  });
+
+  test('preserves explicit depth in resolution', async () => {
+    await register(mockApp, ctx, { enabled: true, resolution: '1920x1080x32' });
+
+    const vd = ctx.createVirtualDisplay();
+    const args = vd.xvfb_args;
+    const screenIdx = args.indexOf('0');
+    expect(args[screenIdx + 1]).toBe('1920x1080x32');
+  });
+
+  test('storage_state endpoint returns 404 for unknown user', async () => {
+    await register(mockApp, ctx, { enabled: true });
+
+    const handler = routes['GET /sessions/:userId/storage_state'].at(-1);
+    const req = { params: { userId: 'unknown' }, reqId: 'test' };
+    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
+
+    await handler(req, res);
+    expect(res.status).toHaveBeenCalledWith(404);
+  });
+
+  test('storage_state endpoint returns state for active session', async () => {
+    await register(mockApp, ctx, { enabled: true });
+
+    const mockState = { cookies: [{ name: 'sid', value: 'abc' }], origins: [] };
+    ctx.sessions.set('user-1', {
+      context: { storageState: jest.fn(async () => mockState) },
+    });
+
+    const handler = routes['GET /sessions/:userId/storage_state'].at(-1);
+    const req = { params: { userId: 'user-1' }, reqId: 'test' };
+    const res = { json: jest.fn() };
+
+    await handler(req, res);
+    expect(res.json).toHaveBeenCalledWith(mockState);
+  });
+
+  test('storage_state endpoint uses safeError on failure', async () => {
+    await register(mockApp, ctx, { enabled: true });
+
+    ctx.sessions.set('user-1', {
+      context: { storageState: jest.fn(async () => { throw new Error('context destroyed'); }) },
+    });
+
+    const handler = routes['GET /sessions/:userId/storage_state'].at(-1);
+    const req = { params: { userId: 'user-1' }, reqId: 'test' };
+    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
+
+    await handler(req, res);
+    expect(res.status).toHaveBeenCalledWith(500);
+    // safeError returns the message string — not the raw Error object
+    expect(res.json).toHaveBeenCalledWith({ error: 'context destroyed' });
+  });
+
+  test('emits vnc:storage:exported and session:storage:export on export', async () => {
+    await register(mockApp, ctx, { enabled: true });
+
+    ctx.sessions.set('user-1', {
+      context: { storageState: jest.fn(async () => ({ cookies: [], origins: [] })) },
+    });
+
+    const exported = [];
+    events.on('vnc:storage:exported', (e) => exported.push(e));
+    events.on('session:storage:export', (e) => exported.push(e));
+
+    const handler = routes['GET /sessions/:userId/storage_state'].at(-1);
+    await handler(
+      { params: { userId: 'user-1' }, reqId: 'test' },
+      { json: jest.fn() },
+    );
+
+    expect(exported).toHaveLength(2);
+    expect(exported[0]).toMatchObject({ userId: 'user-1' });
+  });
+
+  test('watcher is killed on server:shutdown', async () => {
+    await register(mockApp, ctx, { enabled: true });
+
+    const proc = mockStartWatcher.mock.results[0].value;
+    events.emit('server:shutdown');
+    expect(proc.kill).toHaveBeenCalledWith('SIGTERM');
+  });
+});

package/plugins/youtube/AGENTS.md

@@ -0,0 +1,25 @@
+# YouTube Plugin — Agent Guide
+
+Extracts video transcripts via yt-dlp (preferred) with Playwright browser fallback.
+
+## Endpoint
+
+`POST /youtube/transcript` — unauthenticated by default (set `"auth": true` in plugin config to require auth).
+
+## Key Files
+
+- `index.js` — route handler + browser fallback logic
+- `youtube.js` — yt-dlp process management + transcript parsing (`child_process` isolated here)
+- `youtube.test.js` — parser unit tests
+- `apt.txt` — system deps (python3-minimal for yt-dlp)
+- `post-install.sh` — downloads yt-dlp binary
+
+## Scanner Compliance
+
+`child_process` is in `youtube.js`, route handlers are in `index.js` — separate files per OpenClaw scanner rules.
+
+## Maintainers
+
+- [@pradeepe](https://github.com/pradeepe) — extracted from core into plugin system
+
+For PRs touching this plugin, tag the maintainers above for review.

package/plugins/youtube/apt.txt

@@ -0,0 +1 @@
+python3-minimal