@auxiora/browser 1.0.0

package/dist/url-validator.js

@@ -0,0 +1,189 @@
+import { isIP } from 'node:net';
+import { BLOCKED_PROTOCOLS } from './types.js';
+/**
+ * Check if an IP address (v4 or v6) falls within private/internal ranges.
+ * Uses numeric comparison instead of string prefix matching to prevent
+ * bypass via decimal, hex, or octal IP encodings.
+ */
+function isPrivateIP(ip) {
+    // IPv6 checks
+    if (ip.includes(':')) {
+        const normalized = normalizeIPv6(ip);
+        // ::1 (loopback)
+        if (normalized === '0000:0000:0000:0000:0000:0000:0000:0001')
+            return true;
+        // :: (unspecified)
+        if (normalized === '0000:0000:0000:0000:0000:0000:0000:0000')
+            return true;
+        // fe80::/10 (link-local)
+        if (normalized.startsWith('fe8') || normalized.startsWith('fe9') ||
+            normalized.startsWith('fea') || normalized.startsWith('feb'))
+            return true;
+        // fc00::/7 (unique local)
+        if (normalized.startsWith('fc') || normalized.startsWith('fd'))
+            return true;
+        // ::ffff:x.x.x.x (IPv4-mapped IPv6)
+        if (normalized.startsWith('0000:0000:0000:0000:0000:ffff:')) {
+            const lastTwo = normalized.slice(30); // e.g., "7f00:0001"
+            const hi = parseInt(lastTwo.slice(0, 4), 16);
+            const lo = parseInt(lastTwo.slice(5, 9), 16);
+            const ipv4 = ((hi << 16) | lo) >>> 0;
+            return isPrivateIPv4Numeric(ipv4);
+        }
+        return false;
+    }
+    // IPv4: parse to numeric
+    const num = parseIPv4ToNumber(ip);
+    if (num === null)
+        return false;
+    return isPrivateIPv4Numeric(num);
+}
+/**
+ * Parse an IPv4 address string to a 32-bit unsigned number.
+ * Handles standard dotted-decimal (e.g. "127.0.0.1").
+ */
+function parseIPv4ToNumber(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return null;
+    let result = 0;
+    for (const part of parts) {
+        const n = parseInt(part, 10);
+        if (isNaN(n) || n < 0 || n > 255)
+            return null;
+        result = (result << 8) | n;
+    }
+    return result >>> 0; // unsigned
+}
+/**
+ * Check if a numeric IPv4 address is in a private/internal range.
+ */
+function isPrivateIPv4Numeric(ip) {
+    // 127.0.0.0/8 (loopback)
+    if ((ip >>> 24) === 127)
+        return true;
+    // 10.0.0.0/8
+    if ((ip >>> 24) === 10)
+        return true;
+    // 172.16.0.0/12
+    if ((ip >>> 20) === (172 << 4 | 1))
+        return true; // 0xAC1 = 172.16-31
+    // 192.168.0.0/16
+    if ((ip >>> 16) === (192 << 8 | 168))
+        return true; // 0xC0A8
+    // 169.254.0.0/16 (link-local)
+    if ((ip >>> 16) === (169 << 8 | 254))
+        return true; // 0xA9FE
+    // 0.0.0.0
+    if (ip === 0)
+        return true;
+    return false;
+}
+/**
+ * Normalize an IPv6 address to its full expanded form.
+ */
+function normalizeIPv6(ip) {
+    // Handle IPv4-mapped addresses like ::ffff:127.0.0.1
+    const v4MappedMatch = ip.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (v4MappedMatch) {
+        const v4num = parseIPv4ToNumber(v4MappedMatch[1]);
+        if (v4num !== null) {
+            const hi = (v4num >>> 16) & 0xffff;
+            const lo = v4num & 0xffff;
+            return `0000:0000:0000:0000:0000:ffff:${hi.toString(16).padStart(4, '0')}:${lo.toString(16).padStart(4, '0')}`;
+        }
+    }
+    let parts = ip.split(':');
+    // Handle :: expansion
+    const emptyIndex = parts.indexOf('');
+    if (ip.includes('::')) {
+        const before = ip.split('::')[0].split(':').filter(Boolean);
+        const after = ip.split('::')[1].split(':').filter(Boolean);
+        const missing = 8 - before.length - after.length;
+        parts = [...before, ...Array(missing).fill('0'), ...after];
+    }
+    return parts.map((p) => (p || '0').padStart(4, '0').toLowerCase()).join(':');
+}
+/**
+ * Check if a hostname looks like a numeric IP (decimal, hex, octal)
+ * that could bypass string-based checks.
+ */
+function isNumericHostname(hostname) {
+    // Pure decimal number (e.g., 2130706433 for 127.0.0.1)
+    if (/^\d+$/.test(hostname))
+        return true;
+    // Hex number (e.g., 0x7f000001)
+    if (/^0x[0-9a-fA-F]+$/i.test(hostname))
+        return true;
+    // Octal parts (e.g., 0177.0.0.1)
+    if (/^[0-7]+\./.test(hostname) && hostname.startsWith('0') && !hostname.startsWith('0.'))
+        return true;
+    return false;
+}
+/**
+ * Validates a URL for browser navigation.
+ * Returns null if valid, or an error message string.
+ *
+ * Blocks:
+ * - Non http/https protocols (file:, javascript:, data:, blob:)
+ * - Private/internal IP addresses (127.x, 10.x, 192.168.x, 172.16-31.x, 169.254.x, localhost)
+ * - Numeric IP bypasses (decimal, hex, octal encodings)
+ * - IPv6-mapped IPv4 addresses (::ffff:127.0.0.1)
+ */
+export function validateUrl(url, options) {
+    if (!url || typeof url !== 'string') {
+        return 'URL must be a non-empty string';
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return 'Invalid URL format';
+    }
+    // Check blocked protocols
+    if (BLOCKED_PROTOCOLS.includes(parsed.protocol)) {
+        return `Blocked protocol: ${parsed.protocol} — only http: and https: are allowed`;
+    }
+    // Only allow http and https
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return `Blocked protocol: ${parsed.protocol} — only http: and https: are allowed`;
+    }
+    const hostname = parsed.hostname;
+    // Check blocklist first (takes priority)
+    if (options?.blockedUrls?.some((pattern) => hostname.includes(pattern))) {
+        return `URL blocked by blocklist: ${hostname}`;
+    }
+    // Check if in allowlist (skip private IP check if allowed)
+    const isAllowed = options?.allowedUrls?.some((pattern) => hostname.includes(pattern));
+    if (isAllowed) {
+        return null;
+    }
+    // Block numeric IP encodings (decimal, hex, octal) that could bypass string checks
+    if (isNumericHostname(hostname)) {
+        return `Blocked numeric IP encoding: ${hostname}`;
+    }
+    // Block localhost
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+        return `Blocked private/internal address: ${hostname}`;
+    }
+    // Check if hostname is an IP address
+    const ipVersion = isIP(hostname);
+    if (ipVersion > 0) {
+        // It's a direct IP — check against private ranges numerically
+        if (isPrivateIP(hostname)) {
+            return `Blocked private/internal address: ${hostname}`;
+        }
+    }
+    // Check hostnames that resolve to IPv6 loopback patterns
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        const innerIP = hostname.slice(1, -1);
+        if (isPrivateIP(innerIP)) {
+            return `Blocked private/internal address: ${hostname}`;
+        }
+    }
+    return null;
+}
+// Export for testing
+export { isPrivateIP, parseIPv4ToNumber, isNumericHostname, normalizeIPv6 };
+//# sourceMappingURL=url-validator.js.map

package/dist/url-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-validator.js","sourceRoot":"","sources":["../src/url-validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@auxiora/browser",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "playwright": "^1.50.0",
+    "@auxiora/logger": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/browser-manager.ts

@@ -0,0 +1,284 @@
+import type { Browser, Page, BrowserContext } from 'playwright';
+import { getLogger } from '@auxiora/logger';
+import type { BrowserConfig, ScreenshotOptions, ExtractResult, BrowseStep, PageInfo } from './types.js';
+import { DEFAULT_BROWSER_CONFIG } from './types.js';
+import { validateUrl } from './url-validator.js';
+
+const logger = getLogger('browser:manager');
+
+type BrowserFactory = (config: BrowserConfig) => Promise<Browser>;
+
+export interface BrowserManagerOptions {
+  config?: BrowserConfig;
+  browserFactory?: BrowserFactory;
+}
+
+const MAX_SCREENSHOT_SIZE = 5 * 1024 * 1024; // 5MB
+const MAX_RESULT_SIZE = 100 * 1024; // 100KB
+
+export class BrowserManager {
+  private config: BrowserConfig;
+  private browser: Browser | null = null;
+  private context: BrowserContext | null = null;
+  private pages = new Map<string, Page>();
+  private browserFactory: BrowserFactory;
+
+  constructor(options: BrowserManagerOptions = {}) {
+    this.config = { ...DEFAULT_BROWSER_CONFIG, ...options.config };
+    this.browserFactory = options.browserFactory || defaultBrowserFactory;
+  }
+
+  async launch(): Promise<void> {
+    if (this.browser?.isConnected()) {
+      return;
+    }
+
+    logger.info('Launching browser', { headless: this.config.headless });
+    this.browser = await this.browserFactory(this.config);
+    this.context = await this.browser.newContext();
+    logger.info('Browser launched');
+  }
+
+  private async ensureBrowser(): Promise<void> {
+    if (!this.browser || !this.browser.isConnected()) {
+      this.pages.clear();
+      this.context = null;
+      this.browser = null;
+
+      logger.warn('Browser disconnected, re-launching');
+      await this.launch();
+    }
+  }
+
+  async getPage(sessionId: string): Promise<Page> {
+    await this.ensureBrowser();
+
+    const existing = this.pages.get(sessionId);
+    if (existing && !existing.isClosed()) {
+      return existing;
+    }
+
+    if (this.pages.size >= this.config.maxConcurrentPages) {
+      throw new Error(`Max concurrent pages (${this.config.maxConcurrentPages}) reached`);
+    }
+
+    const page = await this.context!.newPage();
+    await page.setViewportSize(this.config.viewport);
+    page.setDefaultNavigationTimeout(this.config.navigationTimeout);
+    page.setDefaultTimeout(this.config.actionTimeout);
+
+    this.pages.set(sessionId, page);
+    logger.info('Page created', { sessionId });
+    return page;
+  }
+
+  async closePage(sessionId: string): Promise<void> {
+    const page = this.pages.get(sessionId);
+    if (page) {
+      await page.close();
+      this.pages.delete(sessionId);
+      logger.info('Page closed', { sessionId });
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    for (const [sessionId, page] of this.pages) {
+      try {
+        if (!page.isClosed()) {
+          await page.close();
+        }
+      } catch (error) {
+        logger.warn('Error closing page', { sessionId, error: error instanceof Error ? error : new Error(String(error)) });
+      }
+    }
+    this.pages.clear();
+
+    if (this.browser) {
+      try {
+        await this.browser.close();
+      } catch (error) {
+        logger.warn('Error closing browser', { error: error instanceof Error ? error : new Error(String(error)) });
+      }
+      this.browser = null;
+      this.context = null;
+    }
+
+    logger.info('Browser shutdown complete');
+  }
+
+  async navigate(sessionId: string, url: string): Promise<PageInfo> {
+    const validationError = validateUrl(url, {
+      allowedUrls: this.config.allowedUrls,
+      blockedUrls: this.config.blockedUrls,
+    });
+    if (validationError) {
+      throw new Error(validationError);
+    }
+
+    const page = await this.getPage(sessionId);
+    await page.goto(url, { waitUntil: 'domcontentloaded' });
+
+    const title = await page.title();
+    const content = await this.getPageMarkdown(page);
+
+    return { url: page.url(), title, content };
+  }
+
+  async click(sessionId: string, selector: string): Promise<void> {
+    const page = await this.getPage(sessionId);
+    await page.click(selector, { timeout: this.config.actionTimeout });
+  }
+
+  async type(sessionId: string, selector: string, text: string, pressEnter?: boolean): Promise<void> {
+    const page = await this.getPage(sessionId);
+    await page.fill(selector, text);
+    if (pressEnter) {
+      await page.keyboard.press('Enter');
+    }
+  }
+
+  async screenshot(sessionId: string, options?: ScreenshotOptions): Promise<{ base64: string; path?: string }> {
+    const page = await this.getPage(sessionId);
+
+    const screenshotOptions: any = {
+      fullPage: options?.fullPage ?? true,
+      type: 'png',
+    };
+
+    if (options?.selector) {
+      const element = await page.$(options.selector);
+      if (!element) {
+        throw new Error(`Element not found: ${options.selector}`);
+      }
+      const buffer = await element.screenshot(screenshotOptions);
+      return this.processScreenshot(buffer, sessionId);
+    }
+
+    const buffer = await page.screenshot(screenshotOptions);
+    return this.processScreenshot(buffer, sessionId);
+  }
+
+  private async processScreenshot(buffer: Buffer, sessionId: string): Promise<{ base64: string; path?: string }> {
+    if (buffer.length > MAX_SCREENSHOT_SIZE) {
+      logger.warn('Screenshot exceeds size limit', { size: buffer.length });
+    }
+
+    const base64 = buffer.toString('base64');
+
+    let filePath: string | undefined;
+    if (this.config.screenshotDir) {
+      const { mkdir, writeFile } = await import('node:fs/promises');
+      const { join } = await import('node:path');
+      const dir = this.config.screenshotDir;
+      await mkdir(dir, { recursive: true });
+      const timestamp = Date.now();
+      filePath = join(dir, `${timestamp}-${sessionId}.png`);
+      await writeFile(filePath, buffer);
+    }
+
+    return { base64, path: filePath };
+  }
+
+  async extract(sessionId: string, selector: string): Promise<ExtractResult> {
+    const page = await this.getPage(sessionId);
+
+    const elements = await page.$$eval(selector, (els) =>
+      els.map((el) => ({
+        text: (el as any).innerText || el.textContent || '',
+        tagName: el.tagName.toLowerCase(),
+        attributes: Object.fromEntries(
+          Array.from(el.attributes).map((attr: any) => [attr.name, attr.value])
+        ),
+      }))
+    );
+
+    return { selector, elements };
+  }
+
+  async wait(sessionId: string, selectorOrMs: string | number): Promise<void> {
+    const page = await this.getPage(sessionId);
+
+    if (typeof selectorOrMs === 'number') {
+      const delay = Math.min(selectorOrMs, 30_000);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    } else {
+      await page.waitForSelector(selectorOrMs, { timeout: this.config.actionTimeout });
+    }
+  }
+
+  async runScript(sessionId: string, script: string): Promise<string> {
+    const page = await this.getPage(sessionId);
+    // Using Playwright's page.evaluate API to run script in browser context
+    const result = await page.evaluate(script);
+    const json = JSON.stringify(result);
+
+    if (json.length > MAX_RESULT_SIZE) {
+      throw new Error(`Result too large (${json.length} bytes, max ${MAX_RESULT_SIZE})`);
+    }
+
+    return json;
+  }
+
+  async browse(sessionId: string, task: string): Promise<{ result: string; steps: BrowseStep[] }> {
+    const steps: BrowseStep[] = [];
+
+    const mutationKeywords = ['click', 'type', 'fill', 'submit', 'login', 'sign in', 'purchase', 'buy', 'send', 'post', 'delete'];
+    const needsMutation = mutationKeywords.some((kw) => task.toLowerCase().includes(kw));
+
+    if (needsMutation) {
+      return {
+        result: 'This task requires page interactions (clicking, typing). Please use the primitive browser tools (browser_click, browser_type) for these actions, which require user approval for safety.',
+        steps: [],
+      };
+    }
+
+    return {
+      result: `Browse task queued: "${task}". Use browser_navigate to go to a page, then browser_extract to get data.`,
+      steps,
+    };
+  }
+
+  private async getPageMarkdown(page: Page): Promise<string> {
+    const html = await page.content();
+    return this.htmlToMarkdown(html);
+  }
+
+  private htmlToMarkdown(html: string): string {
+    let text = html;
+    text = text.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
+    text = text.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');
+    text = text.replace(/<h1[^>]*>(.*?)<\/h1>/gi, '\n# $1\n');
+    text = text.replace(/<h2[^>]*>(.*?)<\/h2>/gi, '\n## $1\n');
+    text = text.replace(/<h3[^>]*>(.*?)<\/h3>/gi, '\n### $1\n');
+    text = text.replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, '[$2]($1)');
+    text = text.replace(/<li[^>]*>(.*?)<\/li>/gi, '- $1\n');
+    text = text.replace(/<p[^>]*>(.*?)<\/p>/gi, '$1\n\n');
+    text = text.replace(/<br\s*\/?>/gi, '\n');
+    text = text.replace(/<[^>]+>/g, '');
+    text = text.replace(/&nbsp;/g, ' ');
+    text = text.replace(/&amp;/g, '&');
+    text = text.replace(/&lt;/g, '<');
+    text = text.replace(/&gt;/g, '>');
+    text = text.replace(/&quot;/g, '"');
+    text = text.replace(/&#39;/g, "'");
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text.replace(/[ \t]{2,}/g, ' ');
+    return text.trim();
+  }
+
+  getActiveSessionIds(): string[] {
+    return Array.from(this.pages.keys());
+  }
+
+  getPageCount(): number {
+    return this.pages.size;
+  }
+}
+
+async function defaultBrowserFactory(config: BrowserConfig): Promise<Browser> {
+  const { chromium } = await import('playwright');
+  return chromium.launch({
+    headless: config.headless,
+    args: ['--disable-extensions', '--disable-dev-shm-usage', '--no-sandbox'],
+  });
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+  BrowserConfig,
+  PageInfo,
+  BrowseStep,
+  ScreenshotOptions,
+  ExtractResult,
+} from './types.js';
+export {
+  DEFAULT_BROWSER_CONFIG,
+  BLOCKED_PROTOCOLS,
+} from './types.js';
+export { validateUrl } from './url-validator.js';
+export { BrowserManager, type BrowserManagerOptions } from './browser-manager.js';

package/src/types.ts

@@ -0,0 +1,49 @@
+export interface BrowserConfig {
+  headless: boolean;
+  viewport: { width: number; height: number };
+  navigationTimeout: number;
+  actionTimeout: number;
+  maxConcurrentPages: number;
+  screenshotDir: string;
+  allowedUrls?: string[];
+  blockedUrls?: string[];
+}
+
+export const DEFAULT_BROWSER_CONFIG: BrowserConfig = {
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+  navigationTimeout: 30_000,
+  actionTimeout: 10_000,
+  maxConcurrentPages: 10,
+  screenshotDir: 'screenshots',
+};
+
+export const BLOCKED_PROTOCOLS = ['file:', 'javascript:', 'data:', 'blob:'];
+
+export interface PageInfo {
+  url: string;
+  title: string;
+  content?: string;
+}
+
+export interface BrowseStep {
+  action: string;
+  params: Record<string, unknown>;
+  result?: string;
+  error?: string;
+}
+
+export interface ScreenshotOptions {
+  fullPage?: boolean;
+  selector?: string;
+  quality?: number;
+}
+
+export interface ExtractResult {
+  selector: string;
+  elements: Array<{
+    text: string;
+    attributes: Record<string, string>;
+    tagName: string;
+  }>;
+}