@phi-code-admin/camofox-browser 1.0.0 → 1.0.2

package/lib/persistence.js

@@ -1,89 +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,
-};
+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

@@ -1,175 +1,178 @@
-/**
- * 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;
-}
+/**
+ * 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, pathToFileURL } 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 {
+      // PHI-VENDOR: on Windows, Node's ESM loader refuses raw absolute paths
+      // (e.g. "C:\foo\plugin.js") and demands a file:// URL. Convert before
+      // calling dynamic import so plugin loading works cross-platform.
+      const mod = await import(pathToFileURL(indexPath).href);
+      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;
+}