barebrowse 0.1.0 → 0.2.1

package/src/auth.js

@@ -0,0 +1,279 @@
+/**
+ * auth.js — Cookie extraction from browser profiles + CDP injection.
+ *
+ * Extracts cookies from Chromium/Firefox SQLite databases,
+ * decrypts Chromium cookies via OS keyring (KWallet or GNOME keyring),
+ * and injects them into a CDP session via Network.setCookie.
+ *
+ * Requires Node >= 22 (node:sqlite built-in).
+ */
+
+import { DatabaseSync } from 'node:sqlite';
+import { pbkdf2Sync, createDecipheriv } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+// --- Browser profile paths ---
+
+const HOME = homedir();
+
+const CHROMIUM_PATHS = {
+  chromium: `${HOME}/.config/chromium/Default/Cookies`,
+  chrome: `${HOME}/.config/google-chrome/Default/Cookies`,
+  brave: `${HOME}/.config/BraveSoftware/Brave-Browser/Default/Cookies`,
+  edge: `${HOME}/.config/microsoft-edge/Default/Cookies`,
+  vivaldi: `${HOME}/.config/vivaldi/Default/Cookies`,
+};
+
+/**
+ * Find first available Chromium cookie database.
+ * @returns {{ path: string, browser: string } | null}
+ */
+function findChromiumCookieDb() {
+  for (const [browser, path] of Object.entries(CHROMIUM_PATHS)) {
+    if (existsSync(path)) return { path, browser };
+  }
+  return null;
+}
+
+/**
+ * Find Firefox default profile cookies.
+ * @returns {string | null} Path to cookies.sqlite
+ */
+function findFirefoxCookieDb() {
+  const base = `${HOME}/.mozilla/firefox`;
+  try {
+    for (const entry of readdirSync(base)) {
+      if (entry.endsWith('.default-release') || entry.endsWith('.default')) {
+        const p = `${base}/${entry}/cookies.sqlite`;
+        if (existsSync(p)) return p;
+      }
+    }
+  } catch { /* no firefox */ }
+  return null;
+}
+
+// --- Chromium cookie decryption (Linux) ---
+
+/**
+ * Get Chromium encryption password from OS keyring.
+ * Tries KWallet (KDE) first, then GNOME keyring, then fallback.
+ */
+function getChromiumPassword() {
+  // KDE / KWallet
+  try {
+    const b64 = execSync(
+      'kwallet-query -r "Chromium Safe Storage" -f "Chromium Keys" kdewallet',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    ).trim();
+    if (b64) return Buffer.from(b64, 'base64').toString('binary');
+  } catch { /* not KDE or no entry */ }
+
+  // GNOME keyring / libsecret
+  try {
+    const pw = execSync(
+      'secret-tool lookup application chrome',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    ).trim();
+    if (pw) return pw;
+  } catch { /* not GNOME */ }
+
+  // Fallback when no keyring is configured
+  return 'peanuts';
+}
+
+/**
+ * Derive AES key from Chromium keyring password.
+ * Chrome Linux: PBKDF2-SHA1, salt='saltysalt', 1 iteration, 16-byte key.
+ */
+function deriveKey(password) {
+  return pbkdf2Sync(password, 'saltysalt', 1, 16, 'sha1');
+}
+
+/**
+ * Decrypt a Chromium encrypted cookie value.
+ * @param {Uint8Array} encrypted - encrypted_value from SQLite
+ * @param {Buffer} aesKey - Derived AES key
+ * @returns {string} Decrypted cookie value
+ */
+function decryptCookie(encrypted, aesKey) {
+  const buf = Buffer.from(encrypted);
+  if (buf.length === 0) return '';
+
+  const prefix = buf.subarray(0, 3).toString('ascii');
+  if (prefix !== 'v10' && prefix !== 'v11') {
+    // Not encrypted
+    return buf.toString('utf8');
+  }
+
+  const iv = Buffer.alloc(16, ' '); // 16 space characters
+  const decipher = createDecipheriv('aes-128-cbc', aesKey, iv);
+  const payload = buf.subarray(3);
+  return Buffer.concat([decipher.update(payload), decipher.final()]).toString('utf8');
+}
+
+// --- Extractors ---
+
+/**
+ * Extract cookies from a Chromium-based browser.
+ * @param {string} dbPath - Path to Cookies SQLite database
+ * @param {string} [domain] - Filter by domain (e.g. '.github.com')
+ * @returns {Array<object>} Cookies in CDP Network.setCookie format
+ */
+function extractChromiumCookies(dbPath, domain) {
+  const password = getChromiumPassword();
+  const aesKey = deriveKey(password);
+
+  // immutable=1 bypasses WAL lock on live databases
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+
+  let sql = `SELECT host_key, name, value, encrypted_value, path,
+    CAST(expires_utc AS TEXT) AS expires_utc, is_secure, is_httponly, samesite
+    FROM cookies`;
+  const params = [];
+  if (domain) {
+    sql += ` WHERE host_key LIKE ?`;
+    params.push(`%${domain}%`);
+  }
+
+  const stmt = db.prepare(sql);
+  const rows = params.length ? stmt.all(...params) : stmt.all();
+  db.close();
+
+  const SAMESITE = { 0: 'None', 1: 'Lax', 2: 'Strict' };
+
+  return rows.map((row) => {
+    const enc = Buffer.from(row.encrypted_value);
+    let value;
+    try {
+      value = enc.length > 0 ? decryptCookie(enc, aesKey) : row.value;
+    } catch {
+      value = row.value || '';
+    }
+
+    // Chrome timestamp: microseconds since 1601-01-01
+    const CHROME_EPOCH = 11644473600000000n;
+    const expiresUtc = row.expires_utc ? BigInt(row.expires_utc) : 0n;
+    const expires = expiresUtc > 0n
+      ? Number((expiresUtc - CHROME_EPOCH) / 1000000n)
+      : -1;
+
+    return {
+      name: row.name,
+      value,
+      domain: row.host_key,
+      path: row.path,
+      expires,
+      secure: row.is_secure === 1,
+      httpOnly: row.is_httponly === 1,
+      sameSite: SAMESITE[row.samesite] || 'Lax',
+    };
+  }).filter((c) => c.value); // drop empty cookies
+}
+
+/**
+ * Extract cookies from Firefox (no encryption).
+ * @param {string} dbPath - Path to cookies.sqlite
+ * @param {string} [domain] - Filter by domain
+ * @returns {Array<object>} Cookies in CDP Network.setCookie format
+ */
+function extractFirefoxCookies(dbPath, domain) {
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+
+  let sql = `SELECT host, name, value, path, expiry, isSecure, isHttpOnly, sameSite
+    FROM moz_cookies`;
+  const params = [];
+  if (domain) {
+    sql += ` WHERE host LIKE ?`;
+    params.push(`%${domain}%`);
+  }
+
+  const stmt = db.prepare(sql);
+  const rows = params.length ? stmt.all(...params) : stmt.all();
+  db.close();
+
+  const SAMESITE = { 0: 'None', 1: 'Lax', 2: 'Strict' };
+
+  return rows.map((row) => ({
+    name: row.name,
+    value: row.value,
+    domain: row.host,
+    path: row.path,
+    expires: row.expiry || -1,
+    secure: row.isSecure === 1,
+    httpOnly: row.isHttpOnly === 1,
+    sameSite: SAMESITE[row.sameSite] || 'Lax',
+  })).filter((c) => c.value);
+}
+
+// --- Public API ---
+
+/**
+ * Extract cookies from the user's browser, auto-detecting which browser to use.
+ * @param {object} [opts]
+ * @param {string} [opts.browser] - 'chromium', 'chrome', 'brave', 'edge', 'firefox', or 'auto'
+ * @param {string} [opts.domain] - Filter by domain
+ * @returns {Array<object>} Cookies in CDP-compatible format
+ */
+export function extractCookies(opts = {}) {
+  const browser = opts.browser || 'auto';
+  const domain = opts.domain;
+
+  if (browser === 'firefox') {
+    const db = findFirefoxCookieDb();
+    if (!db) throw new Error('Firefox cookie database not found');
+    return extractFirefoxCookies(db, domain);
+  }
+
+  if (browser !== 'auto' && CHROMIUM_PATHS[browser]) {
+    const path = CHROMIUM_PATHS[browser];
+    if (!existsSync(path)) throw new Error(`${browser} cookie database not found at ${path}`);
+    return extractChromiumCookies(path, domain);
+  }
+
+  // Auto-detect: try Chromium browsers first, then Firefox
+  const chromium = findChromiumCookieDb();
+  if (chromium) return extractChromiumCookies(chromium.path, domain);
+
+  const firefox = findFirefoxCookieDb();
+  if (firefox) return extractFirefoxCookies(firefox, domain);
+
+  throw new Error('No browser cookie database found');
+}
+
+/**
+ * Inject cookies into a CDP session via Network.setCookie.
+ * @param {object} session - CDP session handle (from cdp.session())
+ * @param {Array<object>} cookies - Cookies from extractCookies()
+ */
+export async function injectCookies(session, cookies) {
+  for (const cookie of cookies) {
+    await session.send('Network.setCookie', {
+      name: cookie.name,
+      value: cookie.value,
+      domain: cookie.domain,
+      path: cookie.path,
+      secure: cookie.secure,
+      httpOnly: cookie.httpOnly,
+      sameSite: cookie.sameSite,
+      expires: cookie.expires > 0 ? cookie.expires : undefined,
+    });
+  }
+}
+
+/**
+ * Extract cookies for a URL and inject them into a CDP session.
+ * Convenience function combining extractCookies + injectCookies.
+ * @param {object} session - CDP session handle
+ * @param {string} url - URL to extract cookies for
+ * @param {object} [opts] - Options passed to extractCookies
+ */
+export async function authenticate(session, url, opts = {}) {
+  const domain = new URL(url).hostname.replace(/^www\./, '');
+  const cookies = extractCookies({ ...opts, domain });
+  if (cookies.length > 0) {
+    await injectCookies(session, cookies);
+  }
+  return cookies.length;
+}

package/src/bareagent.js

@@ -0,0 +1,161 @@
+/**
+ * bareagent.js — Tool adapter for bareagent's Loop.
+ *
+ * Usage:
+ *   import { createBrowseTools } from 'barebrowse/src/bareagent.js';
+ *   const { tools, close } = createBrowseTools();
+ *   const result = await loop.run(messages, tools);
+ *   await close();
+ *
+ * Action tools auto-return a fresh snapshot so the LLM always sees the result.
+ * 300ms settle delay after actions for DOM updates.
+ */
+
+import { browse, connect } from './index.js';
+
+const SETTLE_MS = 300;
+const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
+
+/**
+ * Create bareagent-compatible browse tools.
+ * @param {object} [opts] - Options passed to connect() for session tools
+ * @returns {{ tools: Array, close: () => Promise<void> }}
+ */
+export function createBrowseTools(opts = {}) {
+  let _page = null;
+
+  async function getPage() {
+    if (!_page) _page = await connect(opts);
+    return _page;
+  }
+
+  async function actionAndSnapshot(fn) {
+    const page = await getPage();
+    await fn(page);
+    await settle();
+    return await page.snapshot();
+  }
+
+  const tools = [
+    {
+      name: 'browse',
+      description: 'One-shot: navigate to a URL and return a pruned ARIA snapshot. Stateless.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'URL to browse' },
+        },
+        required: ['url'],
+      },
+      execute: async ({ url }) => await browse(url, opts),
+    },
+    {
+      name: 'goto',
+      description: 'Navigate to a URL and return the page snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'URL to navigate to' },
+        },
+        required: ['url'],
+      },
+      execute: async ({ url }) => actionAndSnapshot((page) => page.goto(url)),
+    },
+    {
+      name: 'snapshot',
+      description: 'Get the current ARIA snapshot. Returns a YAML-like tree with [ref=N] markers on interactive elements.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        return await page.snapshot();
+      },
+    },
+    {
+      name: 'click',
+      description: 'Click an element by its ref from the snapshot. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'string', description: 'Element ref from snapshot' },
+        },
+        required: ['ref'],
+      },
+      execute: async ({ ref }) => actionAndSnapshot((page) => page.click(ref)),
+    },
+    {
+      name: 'type',
+      description: 'Type text into an element by its ref. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'string', description: 'Element ref from snapshot' },
+          text: { type: 'string', description: 'Text to type' },
+          clear: { type: 'boolean', description: 'Clear existing content first' },
+        },
+        required: ['ref', 'text'],
+      },
+      execute: async ({ ref, text, clear }) => actionAndSnapshot((page) => page.type(ref, text, { clear })),
+    },
+    {
+      name: 'press',
+      description: 'Press a special key (Enter, Tab, Escape, etc.). Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'Key name (Enter, Tab, Escape, Backspace, Delete, arrows, Home, End, PageUp, PageDown, Space)' },
+        },
+        required: ['key'],
+      },
+      execute: async ({ key }) => actionAndSnapshot((page) => page.press(key)),
+    },
+    {
+      name: 'scroll',
+      description: 'Scroll the page. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up)' },
+        },
+        required: ['deltaY'],
+      },
+      execute: async ({ deltaY }) => actionAndSnapshot((page) => page.scroll(deltaY)),
+    },
+    {
+      name: 'select',
+      description: 'Select a value in a dropdown/select element. Returns the updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'string', description: 'Element ref from snapshot' },
+          value: { type: 'string', description: 'Value or visible text to select' },
+        },
+        required: ['ref', 'value'],
+      },
+      execute: async ({ ref, value }) => actionAndSnapshot((page) => page.select(ref, value)),
+    },
+    {
+      name: 'screenshot',
+      description: 'Take a screenshot of the current page. Returns base64-encoded image.',
+      parameters: {
+        type: 'object',
+        properties: {
+          format: { type: 'string', enum: ['png', 'jpeg', 'webp'], description: 'Image format (default: png)' },
+        },
+      },
+      execute: async ({ format } = {}) => {
+        const page = await getPage();
+        return await page.screenshot({ format });
+      },
+    },
+  ];
+
+  return {
+    tools,
+    async close() {
+      if (_page) {
+        await _page.close();
+        _page = null;
+      }
+    },
+  };
+}

package/src/cdp.js

@@ -0,0 +1,148 @@
+/**
+ * cdp.js — Minimal Chrome DevTools Protocol client over WebSocket.
+ *
+ * Sends JSON-RPC commands, receives responses and events.
+ * Uses Node 22's built-in WebSocket (no external deps).
+ *
+ * Supports flattened sessions: when a sessionId is provided,
+ * it's sent at the top level of the message (not inside params).
+ * Events from sessions are also dispatched by sessionId.
+ */
+
+/**
+ * Create a CDP client connected to the given WebSocket URL.
+ * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
+ * @returns {Promise<CDPClient>}
+ */
+export async function createCDP(wsUrl) {
+  const ws = new WebSocket(wsUrl);
+  let nextId = 1;
+  const pending = new Map();   // id → { resolve, reject }
+  const listeners = new Map(); // "method" or "sessionId:method" → Set<callback>
+
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('CDP connection timeout (5s)')), 5000);
+    ws.onopen = () => { clearTimeout(timeout); resolve(); };
+    ws.onerror = (e) => {
+      clearTimeout(timeout);
+      reject(new Error(`CDP WebSocket connection failed: ${e.message || 'unknown error'}`));
+    };
+  });
+
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());
+
+    // Response to a command (has id)
+    if (msg.id !== undefined) {
+      const handler = pending.get(msg.id);
+      if (handler) {
+        pending.delete(msg.id);
+        if (msg.error) {
+          handler.reject(new Error(`CDP error: ${msg.error.message} (${msg.error.code})`));
+        } else {
+          handler.resolve(msg.result);
+        }
+      }
+      return;
+    }
+
+    // Event (has method, optionally sessionId for flattened sessions)
+    if (msg.method) {
+      // Dispatch to session-scoped listeners first
+      if (msg.sessionId) {
+        const key = `${msg.sessionId}:${msg.method}`;
+        const scoped = listeners.get(key);
+        if (scoped) {
+          for (const cb of scoped) cb(msg.params);
+        }
+      }
+      // Also dispatch to global listeners
+      const global = listeners.get(msg.method);
+      if (global) {
+        for (const cb of global) cb(msg.params, msg.sessionId);
+      }
+    }
+  };
+
+  ws.onerror = (e) => {
+    for (const [id, handler] of pending) {
+      handler.reject(new Error(`CDP WebSocket error: ${e.message || 'unknown'}`));
+      pending.delete(id);
+    }
+  };
+
+  const client = {
+    /**
+     * Send a CDP command and wait for the response.
+     * @param {string} method - CDP method (e.g. 'Page.navigate')
+     * @param {object} [params] - Command parameters
+     * @param {string} [sessionId] - Target session (for flattened mode)
+     * @returns {Promise<object>} Response result
+     */
+    send(method, params = {}, sessionId) {
+      const id = nextId++;
+      const msg = { id, method, params };
+      if (sessionId) msg.sessionId = sessionId;
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        ws.send(JSON.stringify(msg));
+      });
+    },
+
+    /**
+     * Subscribe to a CDP event.
+     * @param {string} method - Event name (e.g. 'Page.loadEventFired')
+     * @param {function} callback - Event handler
+     * @param {string} [sessionId] - Scope to a specific session
+     * @returns {function} Unsubscribe function
+     */
+    on(method, callback, sessionId) {
+      const key = sessionId ? `${sessionId}:${method}` : method;
+      if (!listeners.has(key)) listeners.set(key, new Set());
+      listeners.get(key).add(callback);
+      return () => listeners.get(key).delete(callback);
+    },
+
+    /**
+     * Wait for a specific CDP event to fire once.
+     * @param {string} method - Event name
+     * @param {number} [timeout=30000] - Timeout in ms
+     * @param {string} [sessionId] - Scope to a specific session
+     * @returns {Promise<object>} Event params
+     */
+    once(method, timeout = 30000, sessionId) {
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          unsub();
+          reject(new Error(`Timeout waiting for CDP event: ${method}`));
+        }, timeout);
+        const unsub = client.on(method, (params) => {
+          clearTimeout(timer);
+          unsub();
+          resolve(params);
+        }, sessionId);
+      });
+    },
+
+    /**
+     * Create a session-scoped handle for a specific target.
+     * All send/on/once calls are automatically scoped to the session.
+     * @param {string} sessionId
+     * @returns {object} Session-scoped CDP handle
+     */
+    session(sessionId) {
+      return {
+        send: (method, params = {}) => client.send(method, params, sessionId),
+        on: (method, callback) => client.on(method, callback, sessionId),
+        once: (method, timeout = 30000) => client.once(method, timeout, sessionId),
+      };
+    },
+
+    /** Close the WebSocket connection. */
+    close() {
+      ws.close();
+    },
+  };
+
+  return client;
+}