@lobu/cli 6.1.1 → 7.1.0

package/dist/connectors/browser/evaluate.ts

@@ -0,0 +1,120 @@
+/**
+ * Browser Evaluate Connector — Owletto for Chrome only.
+ *
+ * Runs on the Owletto Chrome extension, which advertises capability
+ * `browser.debugger`. The extension attaches `chrome.debugger` to a tab,
+ * optionally navigates + waits for a selector, runs the supplied JS via
+ * `Runtime.evaluate`, and emits one event with the JSON-serialised result.
+ *
+ * This is the generic "agent runs JS in a user's signed-in Chrome" primitive
+ * — most bridge connectors (Revolut feed, banking, sites that fingerprint
+ * a managed Chromium) compose on top of `browser.evaluate` rather than
+ * shipping their own connector. The trust boundary is `config.script`: only
+ * the gateway-side connector author should mint it. The extension defaults
+ * to opening a fresh background tab so a compromised gateway / leaked token
+ * can't drive the tab a user is actively using; see executor.js in
+ * owletto-web for the full threat model.
+ *
+ * Cloud-side `sync()` / `execute()` throw — actual work happens in the
+ * extension's service worker (lobu-ai/owletto: apps/chrome/executor.js).
+ */
+
+import {
+  type ActionResult,
+  type ConnectorDefinition,
+  ConnectorRuntime,
+  type SyncContext,
+  type SyncResult,
+} from '@lobu/connector-sdk';
+
+const BRIDGE_ONLY =
+  'browser.evaluate runs only on a worker advertising capability "browser.debugger" (Owletto for Chrome).';
+
+export default class BrowserEvaluateConnector extends ConnectorRuntime {
+  readonly definition: ConnectorDefinition = {
+    key: 'browser.evaluate',
+    name: 'Browser Evaluate',
+    description:
+      'Runs a JS snippet in a page via chrome.debugger and emits the result. The primitive most bridge connectors build on.',
+    version: '0.1.0',
+    faviconDomain: 'google.com',
+    requiredCapability: 'browser.debugger',
+    runtime: { platforms: ['chrome-extension'] },
+    authSchema: { methods: [{ type: 'none' }] },
+    feeds: {
+      evaluate: {
+        key: 'evaluate',
+        name: 'Evaluate JS',
+        description:
+          'Executes a JS expression in the page and emits one event with the JSON-serialised return value.',
+        // `script` is required and gateway-author-supplied. Auto-wire would
+        // insert a feed row with config=NULL and produce a runs-but-fails
+        // loop. Bridge connectors (Revolut, banking, etc.) compose by
+        // creating explicit feed instances per call site.
+        userManaged: true,
+        configSchema: {
+          type: 'object',
+          required: ['script'],
+          properties: {
+            url: {
+              type: 'string',
+              format: 'uri',
+              description: 'If set, navigate the tab here before evaluating.',
+            },
+            script: {
+              type: 'string',
+              description:
+                'JS expression evaluated with Runtime.evaluate(awaitPromise: true). Return value is JSON-serialised — keep it small.',
+            },
+            wait_for_selector: {
+              type: 'string',
+              description:
+                'CSS selector to wait for before evaluating (polled every 200ms via Runtime.evaluate).',
+            },
+            wait_timeout_ms: {
+              type: 'integer',
+              minimum: 100,
+              maximum: 60_000,
+              description: 'Timeout for wait_for_selector. Default 10000.',
+            },
+            open_in_new_tab: {
+              type: 'boolean',
+              description:
+                'Open a fresh background tab instead of driving the active tab. DEFAULT TRUE — opt out only when you specifically need the user-active tab.',
+            },
+            close_tab_after: {
+              type: 'boolean',
+              description:
+                'Close the tab when the run completes. Defaults to true when open_in_new_tab is true.',
+            },
+          },
+        },
+        eventKinds: {
+          browser_evaluate: {
+            description:
+              'One event per run with the JSON-serialised Runtime.evaluate result.',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id'],
+              properties: {
+                source: { type: 'string', const: 'browser_evaluate' },
+                origin_id: { type: 'string' },
+                url: { type: 'string' },
+                title: { type: 'string' },
+                tab_id: { type: 'integer' },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+
+  async sync(_ctx: SyncContext): Promise<SyncResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+
+  async execute(): Promise<ActionResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+}

package/dist/connectors/browser/fill_form.ts

@@ -0,0 +1,107 @@
+/**
+ * Browser Fill Form Connector — Owletto for Chrome only.
+ *
+ * Thin wrapper around browser.evaluate that bakes in a "fill these inputs
+ * by selector and dispatch the right input/change events" script.
+ *
+ * The extension's executor branch for `browser.fill_form` substitutes the
+ * canonical fill-form script when this connector_key is dispatched. The
+ * server-side definition just exposes the URL + fields config to the
+ * admin UI.
+ *
+ * Cloud-side `sync()` / `execute()` throw — actual work happens in the
+ * extension's service worker (lobu-ai/owletto: apps/chrome/executor.js).
+ */
+
+import {
+  type ActionResult,
+  type ConnectorDefinition,
+  ConnectorRuntime,
+  type SyncContext,
+  type SyncResult,
+} from '@lobu/connector-sdk';
+
+const BRIDGE_ONLY =
+  'browser.fill_form runs only on a worker advertising capability "browser.debugger" (Owletto for Chrome).';
+
+export default class BrowserFillFormConnector extends ConnectorRuntime {
+  readonly definition: ConnectorDefinition = {
+    key: 'browser.fill_form',
+    name: 'Browser Fill Form',
+    description:
+      'Fills inputs on a page by CSS selector and dispatches input/change events. Returns the filled field count.',
+    version: '0.1.0',
+    faviconDomain: 'google.com',
+    requiredCapability: 'browser.debugger',
+    runtime: { platforms: ['chrome-extension'] },
+    authSchema: { methods: [{ type: 'none' }] },
+    feeds: {
+      fill: {
+        key: 'fill',
+        name: 'Fill form',
+        description:
+          'Sets values on input/textarea/select elements matched by CSS selector.',
+        // Required url + fields; instances are minted by composing bridge
+        // connectors, not auto-wired by device-reconcile.
+        userManaged: true,
+        configSchema: {
+          type: 'object',
+          required: ['url', 'fields'],
+          properties: {
+            url: {
+              type: 'string',
+              format: 'uri',
+              description: 'Page to load before filling.',
+            },
+            fields: {
+              type: 'object',
+              description:
+                'Map of CSS selector → value to set. e.g. { "#email": "x@y.com", "#submit": "click" } — the literal string "click" triggers a click instead of a value set.',
+              additionalProperties: { type: 'string' },
+            },
+            wait_for_selector: {
+              type: 'string',
+              description:
+                'CSS selector to wait for before filling (defaults to the first key of fields).',
+            },
+            wait_timeout_ms: {
+              type: 'integer',
+              minimum: 100,
+              maximum: 60_000,
+            },
+            submit_selector: {
+              type: 'string',
+              description:
+                'Optional selector to click after filling all fields (e.g. "button[type=submit]").',
+            },
+          },
+        },
+        eventKinds: {
+          form_filled: {
+            description:
+              'One event per run with the count of fields filled + whether submit was clicked.',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id', 'url', 'filled_count'],
+              properties: {
+                source: { type: 'string', const: 'browser_fill_form' },
+                origin_id: { type: 'string' },
+                url: { type: 'string', format: 'uri' },
+                filled_count: { type: 'integer' },
+                submitted: { type: 'boolean' },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+
+  async sync(_ctx: SyncContext): Promise<SyncResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+
+  async execute(): Promise<ActionResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+}

package/dist/connectors/browser/page_text.ts

@@ -0,0 +1,108 @@
+/**
+ * Browser Page Text Connector — Owletto for Chrome only.
+ *
+ * Thin wrapper around browser.evaluate that bakes in a "return cleaned-up
+ * page text" script. Saves the connector author from re-deriving the
+ * text-extraction recipe for every page-scrape feed.
+ *
+ * The extension's executor branch for `browser.page_text` is responsible
+ * for substituting the canonical script when this connector_key is
+ * dispatched — gateway-side this connector definition just exposes the
+ * URL + selector-scope config to the admin UI.
+ *
+ * Cloud-side `sync()` / `execute()` throw — actual work happens in the
+ * extension's service worker (lobu-ai/owletto: apps/chrome/executor.js).
+ */
+
+import {
+  type ActionResult,
+  type ConnectorDefinition,
+  ConnectorRuntime,
+  type SyncContext,
+  type SyncResult,
+} from '@lobu/connector-sdk';
+
+const BRIDGE_ONLY =
+  'browser.page_text runs only on a worker advertising capability "browser.debugger" (Owletto for Chrome).';
+
+export default class BrowserPageTextConnector extends ConnectorRuntime {
+  readonly definition: ConnectorDefinition = {
+    key: 'browser.page_text',
+    name: 'Browser Page Text',
+    description:
+      'Fetches a page in the paired Chrome and returns its readable text content. Wraps browser.evaluate with a canonical text-extraction script.',
+    version: '0.1.0',
+    faviconDomain: 'google.com',
+    requiredCapability: 'browser.debugger',
+    runtime: { platforms: ['chrome-extension'] },
+    authSchema: { methods: [{ type: 'none' }] },
+    feeds: {
+      page: {
+        key: 'page',
+        name: 'Page text',
+        description: 'Snapshot of the text content of a single page.',
+        // Required url; instances are minted by composing bridge connectors,
+        // not auto-wired by device-reconcile.
+        userManaged: true,
+        configSchema: {
+          type: 'object',
+          required: ['url'],
+          properties: {
+            url: {
+              type: 'string',
+              format: 'uri',
+              description: 'Page to load and read text from.',
+            },
+            selector: {
+              type: 'string',
+              description:
+                'CSS selector to scope the extraction to (defaults to body.innerText).',
+            },
+            wait_for_selector: {
+              type: 'string',
+              description:
+                'CSS selector to wait for before reading (defaults to body).',
+            },
+            wait_timeout_ms: {
+              type: 'integer',
+              minimum: 100,
+              maximum: 60_000,
+            },
+            max_chars: {
+              type: 'integer',
+              minimum: 100,
+              maximum: 1_000_000,
+              description: 'Truncate output past this length. Default 200000.',
+            },
+          },
+        },
+        eventKinds: {
+          page_text: {
+            description:
+              'One event per run containing the page text (truncated to max_chars).',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id', 'url'],
+              properties: {
+                source: { type: 'string', const: 'browser_page_text' },
+                origin_id: { type: 'string' },
+                url: { type: 'string', format: 'uri' },
+                title: { type: 'string' },
+                char_count: { type: 'integer' },
+                truncated: { type: 'boolean' },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+
+  async sync(_ctx: SyncContext): Promise<SyncResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+
+  async execute(): Promise<ActionResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+}

package/dist/connectors/browser-scraper-utils.ts

@@ -24,12 +24,42 @@ export function getBrowserCookies(
 ): any[] {
   const sessionCookies = (sessionState?.cookies as any[]) ?? [];
   const cookies = (checkpoint as any)?.cookies ?? sessionCookies;
-  if (!cookies || cookies.length === 0) {
+  // Device-bound browser profiles ship cookies via --user-data-dir on disk
+  // rather than this jsonb blob; the persistent context loads them itself.
+  if ((!cookies || cookies.length === 0) && !sessionState?.user_data_dir) {
     throw new Error(
       `No browser cookies found. Run: lobu memory browser-auth --connector ${connectorKey} --auth-profile-slug <SLUG>`
     );
   }
-  return cookies;
+  return cookies ?? [];
+}
+
+/**
+ * Pull the device-bound managed --user-data-dir from session_state, if the
+ * connection's auth profile is owned by a device worker. When set, callers
+ * should pass it to openStealthBrowser instead of relying on the cookies/CDP
+ * cascade — Chrome reads cookies from that profile dir directly.
+ */
+export function getBrowserUserDataDir(
+  sessionState: Record<string, unknown> | null | undefined
+): string | undefined {
+  const value = sessionState?.user_data_dir;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Pull the device-bound CDP endpoint URL from session_state (set when the
+ * user picked "Attach via CDP" mode on their browser profile). When set,
+ * callers should pass it through as `cdpUrl` so the connector attaches to
+ * the exact running Chrome the user chose — instead of `'auto'`, which can
+ * land on the wrong browser when several debuggable Chromiums are running
+ * or a non-default port was configured.
+ */
+export function getBrowserCdpUrl(
+  sessionState: Record<string, unknown> | null | undefined
+): string | undefined {
+  const value = sessionState?.cdp_url;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 
 export function validateCookieNotExpired(
@@ -52,6 +82,82 @@ export function validateCookieNotExpired(
 // URL validation
 // -----------------------------------------------------------------------------
 
+/**
+ * Validates a URL is safe for server-side fetching.
+ * Blocks private/internal network addresses to prevent SSRF attacks.
+ *
+ * Returns silently when the URL is safe; throws with a descriptive message
+ * otherwise. Connectors that fetch URLs derived from remote/untrusted input
+ * (sitemaps, HN story links, RSS feeds configured by users, etc.) MUST call
+ * this at the trust boundary before issuing the request.
+ */
+export function validatePublicUrl(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`URL must use http: or https: protocol, got ${parsed.protocol}`);
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+
+  // Block localhost variants
+  if (hostname === 'localhost' || hostname === '[::1]' || hostname.endsWith('.localhost')) {
+    throw new Error(`URL must not point to localhost: ${hostname}`);
+  }
+
+  // IPv4 private/loopback/link-local/cloud-metadata/CGNAT ranges
+  const ipv4Match = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4Match) {
+    const [, a, b] = ipv4Match.map(Number);
+    if (
+      a === 127 || // loopback
+      a === 10 || // private
+      (a === 172 && b >= 16 && b <= 31) || // private
+      (a === 192 && b === 168) || // private
+      (a === 169 && b === 254) || // link-local incl. 169.254.169.254 cloud metadata
+      (a === 100 && b >= 64 && b <= 127) || // CGNAT 100.64.0.0/10
+      a === 0
+    ) {
+      throw new Error(`URL must not point to a private/internal IP address: ${hostname}`);
+    }
+  }
+
+  // IPv6 private ranges (bracketed notation)
+  if (hostname.startsWith('[')) {
+    const ipv6 = hostname.slice(1, -1).toLowerCase();
+    // Link-local fe80::/10 covers fe80:..fec0: (first byte 1111 1110 1x).
+    const linkLocalPrefix = /^fe[89ab][0-9a-f]?:/;
+    // Multicast ff00::/8 — any address starting with ff.
+    const multicastPrefix = /^ff[0-9a-f]{2}:/;
+    if (
+      ipv6 === '::1' ||
+      linkLocalPrefix.test(ipv6) ||
+      multicastPrefix.test(ipv6) ||
+      ipv6.startsWith('fc') || // unique local fc00::/7
+      ipv6.startsWith('fd') ||
+      ipv6 === '::' ||
+      ipv6.startsWith('::ffff:') // IPv4-mapped IPv6
+    ) {
+      throw new Error(`URL must not point to a private/internal IPv6 address: ${hostname}`);
+    }
+  }
+
+  // Common internal hostnames
+  if (
+    hostname.endsWith('.internal') ||
+    hostname.endsWith('.local') ||
+    hostname.endsWith('.corp') ||
+    hostname.endsWith('.lan')
+  ) {
+    throw new Error(`URL must not point to an internal hostname: ${hostname}`);
+  }
+}
+
 /**
  * Validate that a URL is well-formed, uses HTTPS, and belongs to the expected
  * domain (hostname ends with `expectedDomain`).
@@ -103,12 +209,14 @@ export async function openStealthBrowser(opts?: {
   cdpUrl?: string | 'auto' | null;
   cookies?: Cookie[];
   authDomains?: string[];
+  userDataDir?: string;
 }): Promise<BrowserSession> {
   const acquired = await acquireBrowser({
-    cdpUrl: opts?.cdpUrl ?? null,
+    cdpUrl: opts?.userDataDir ? null : (opts?.cdpUrl ?? null),
     cookies: opts?.cookies ?? [],
     authDomains: opts?.authDomains ?? [],
     stealth: true,
+    userDataDir: opts?.userDataDir,
   });
 
   const page = acquired.cdpPage ?? acquired.page;

package/dist/connectors/capterra.ts

@@ -14,6 +14,8 @@ import {
   type SyncResult,
 } from '@lobu/connector-sdk';
 import {
+  getBrowserCdpUrl,
+  getBrowserUserDataDir,
   handleCookieConsent,
   openStealthBrowser,
   validateUrlDomain,
@@ -132,7 +134,9 @@ export default class CapterraConnector extends ConnectorRuntime {
       : `https://www.capterra.com/p/${productId}/reviews`;
     validateUrlDomain(baseUrl, 'capterra.com');
 
-    const session = await openStealthBrowser({ cdpUrl: 'auto' });
+    const userDataDir = getBrowserUserDataDir(ctx.sessionState);
+    const cdpUrl = getBrowserCdpUrl(ctx.sessionState) ?? 'auto';
+    const session = await openStealthBrowser({ cdpUrl, userDataDir });
 
     return withBrowserErrorCapture(session, 'capterra-sync', async (page) => {
       await page.goto(baseUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });

package/dist/connectors/chrome_tabs.ts

@@ -0,0 +1,74 @@
+/**
+ * Chrome Tabs Connector — Owletto for Chrome only.
+ *
+ * Runs on the Owletto Chrome extension, which advertises capability
+ * `browser.tabs`. The extension uses `chrome.tabs.query()` to list the tabs
+ * currently open in the user's paired Chrome profile. No persistent backfill
+ * — each sync returns the live tab list at that moment.
+ *
+ * This connector is the smallest end-to-end demo of the Chrome-extension
+ * device protocol: it proves a connector definition can declare a browser
+ * capability, get auto-wired into the user's personal org when a
+ * `chrome-extension` device polls, and route runs to it.
+ *
+ * The cloud-side `sync()` / `execute()` throw — actual work happens in the
+ * extension's service worker (lobu-ai/owletto: apps/chrome/background.js).
+ */
+
+import {
+  type ActionResult,
+  type ConnectorDefinition,
+  ConnectorRuntime,
+  type SyncContext,
+  type SyncResult,
+} from '@lobu/connector-sdk';
+
+const BRIDGE_ONLY =
+  'Chrome Tabs runs only on a worker advertising capability "browser.tabs" (Owletto for Chrome).';
+
+export default class ChromeTabsConnector extends ConnectorRuntime {
+  readonly definition: ConnectorDefinition = {
+    key: 'chrome.tabs',
+    name: 'Chrome Tabs',
+    description:
+      'Lists the tabs currently open in the paired Chrome profile. Read-only; no history or content.',
+    version: '0.1.0',
+    faviconDomain: 'google.com',
+    requiredCapability: 'browser.tabs',
+    runtime: { platforms: ['chrome-extension'] },
+    authSchema: { methods: [{ type: 'none' }] },
+    feeds: {
+      open_tabs: {
+        key: 'open_tabs',
+        name: 'Open tabs',
+        description: 'Snapshot of the tabs currently open in this Chrome profile.',
+        configSchema: { type: 'object', properties: {} },
+        eventKinds: {
+          tab_snapshot: {
+            description: 'One row per tab observed in the active poll cycle.',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id', 'url'],
+              properties: {
+                source: { type: 'string', const: 'chrome_tabs' },
+                origin_id: { type: 'string' },
+                url: { type: 'string', format: 'uri' },
+                title: { type: 'string' },
+                window_id: { type: 'integer' },
+                active: { type: 'boolean' },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+
+  async sync(_ctx: SyncContext): Promise<SyncResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+
+  async execute(): Promise<ActionResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+}

package/dist/connectors/g2.ts

@@ -15,6 +15,8 @@ import {
   type SyncResult,
 } from '@lobu/connector-sdk';
 import {
+  getBrowserCdpUrl,
+  getBrowserUserDataDir,
   handleCookieConsent,
   openStealthBrowser,
   validateUrlDomain,
@@ -114,7 +116,9 @@ export default class G2Connector extends ConnectorRuntime {
     const baseUrl = productUrl;
     const allEvents: EventEnvelope[] = [];
 
-    const session = await openStealthBrowser({ cdpUrl: 'auto' });
+    const userDataDir = getBrowserUserDataDir(ctx.sessionState);
+    const cdpUrl = getBrowserCdpUrl(ctx.sessionState) ?? 'auto';
+    const session = await openStealthBrowser({ cdpUrl, userDataDir });
 
     return withBrowserErrorCapture(session, 'g2-sync', async (page) => {
       const maxPages = 5;