@ulpi/browse 0.1.0 → 0.2.0

package/src/constants.ts

@@ -1,9 +1,11 @@
+const BROWSE_TIMEOUT = parseInt(process.env.BROWSE_TIMEOUT || '0', 10);
+
 export const DEFAULTS = {
   PORT_RANGE_START: 9400,
   PORT_RANGE_END: 10400,
   IDLE_TIMEOUT_MS: 30 * 60 * 1000,       // 30 min
-  COMMAND_TIMEOUT_MS: 15_000,              // 15s for navigation
-  ACTION_TIMEOUT_MS: 5_000,               // 5s for clicks/fills
+  COMMAND_TIMEOUT_MS: BROWSE_TIMEOUT || 15_000,    // 15s for navigation
+  ACTION_TIMEOUT_MS: BROWSE_TIMEOUT || 5_000,      // 5s for clicks/fills
   HEALTH_CHECK_TIMEOUT_MS: 2_000,
   BUFFER_HIGH_WATER_MARK: 50_000,
   BUFFER_FLUSH_INTERVAL_MS: 1_000,

package/src/domain-filter.ts

@@ -0,0 +1,134 @@
+/**
+ * Domain filter — blocks navigation and sub-resource requests outside an allowlist.
+ *
+ * Supports:
+ *   - Exact domain: "example.com" matches only example.com
+ *   - Wildcard: "*.example.com" matches example.com AND any subdomain
+ *   - Case-insensitive matching
+ */
+
+export class DomainFilter {
+  private domains: string[];
+
+  constructor(domains: string[]) {
+    this.domains = domains.map(d => d.toLowerCase());
+  }
+
+  /**
+   * Check if a URL's domain is in the allowlist.
+   * Returns true if allowed, false if blocked.
+   * Non-HTTP URLs (about:blank, data:, etc.) are always allowed.
+   */
+  isAllowed(url: string): boolean {
+    // Non-HTTP(S) URLs are always allowed
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+      return true;
+    }
+
+    let hostname: string;
+    try {
+      hostname = new URL(url).hostname.toLowerCase();
+    } catch {
+      return false; // Invalid URL = blocked
+    }
+
+    for (const pattern of this.domains) {
+      if (pattern.startsWith('*.')) {
+        // Wildcard: *.example.com matches example.com itself AND any subdomain
+        const base = pattern.slice(2); // "example.com"
+        if (hostname === base || hostname.endsWith('.' + base)) {
+          return true;
+        }
+      } else {
+        // Exact match
+        if (hostname === pattern) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get a human-readable error message for a blocked URL.
+   */
+  blockedMessage(url: string): string {
+    let hostname = url;
+    try {
+      hostname = new URL(url).hostname;
+    } catch {}
+    return `Domain "${hostname}" is not in the allowed list: ${this.domains.join(', ')}`;
+  }
+
+  /**
+   * Generate a JS init script that wraps WebSocket, EventSource, and
+   * navigator.sendBeacon with domain checks. Playwright's context.route()
+   * only covers HTTP — these JS-level APIs bypass it entirely.
+   *
+   * Injected via context.addInitScript() so it runs before any page JS.
+   */
+  generateInitScript(): string {
+    const domainsJson = JSON.stringify(this.domains);
+    return `(function() {
+  const __allowedDomains = ${domainsJson};
+
+  function __isAllowed(url) {
+    if (!url) return true;
+    var str = String(url);
+    // Normalize ws/wss to http/https for URL parsing
+    if (str.startsWith('ws://')) str = 'http://' + str.slice(5);
+    else if (str.startsWith('wss://')) str = 'https://' + str.slice(6);
+    // Non-HTTP(S) always allowed (data:, blob:, etc.)
+    if (!str.startsWith('http://') && !str.startsWith('https://')) return true;
+    var hostname;
+    try { hostname = new URL(str).hostname.toLowerCase(); } catch(e) { return false; }
+    for (var i = 0; i < __allowedDomains.length; i++) {
+      var pattern = __allowedDomains[i];
+      if (pattern.startsWith('*.')) {
+        var base = pattern.slice(2);
+        if (hostname === base || hostname.endsWith('.' + base)) return true;
+      } else {
+        if (hostname === pattern) return true;
+      }
+    }
+    return false;
+  }
+
+  // Wrap WebSocket
+  var OrigWebSocket = window.WebSocket;
+  if (OrigWebSocket) {
+    window.WebSocket = function(url, protocols) {
+      if (!__isAllowed(url)) throw new Error('WebSocket blocked by domain filter: ' + url);
+      if (protocols !== undefined) return new OrigWebSocket(url, protocols);
+      return new OrigWebSocket(url);
+    };
+    window.WebSocket.prototype = OrigWebSocket.prototype;
+    window.WebSocket.CONNECTING = OrigWebSocket.CONNECTING;
+    window.WebSocket.OPEN = OrigWebSocket.OPEN;
+    window.WebSocket.CLOSING = OrigWebSocket.CLOSING;
+    window.WebSocket.CLOSED = OrigWebSocket.CLOSED;
+  }
+
+  // Wrap EventSource
+  var OrigEventSource = window.EventSource;
+  if (OrigEventSource) {
+    window.EventSource = function(url, opts) {
+      if (!__isAllowed(url)) throw new Error('EventSource blocked by domain filter: ' + url);
+      if (opts !== undefined) return new OrigEventSource(url, opts);
+      return new OrigEventSource(url);
+    };
+    window.EventSource.prototype = OrigEventSource.prototype;
+  }
+
+  // Wrap navigator.sendBeacon
+  if (navigator.sendBeacon) {
+    var origSendBeacon = navigator.sendBeacon.bind(navigator);
+    navigator.sendBeacon = function(url, data) {
+      if (!__isAllowed(url)) return false;
+      return origSendBeacon(url, data);
+    };
+  }
+})();`;
+  }
+}

package/src/har.ts

@@ -0,0 +1,66 @@
+/**
+ * HAR 1.2 export — converts NetworkEntry[] to HTTP Archive format
+ */
+
+import type { NetworkEntry } from './buffers';
+
+export interface HarRecording {
+  startTime: number;
+  active: boolean;
+}
+
+function parseQueryString(url: string): Array<{ name: string; value: string }> {
+  try {
+    const u = new URL(url);
+    return [...u.searchParams.entries()].map(([name, value]) => ({ name, value }));
+  } catch {
+    return [];
+  }
+}
+
+export function formatAsHar(entries: NetworkEntry[], startTime: number): object {
+  const harEntries = entries
+    .filter(e => e.timestamp >= startTime)
+    .map(e => ({
+      startedDateTime: new Date(e.timestamp).toISOString(),
+      time: e.duration || 0,
+      request: {
+        method: e.method,
+        url: e.url,
+        httpVersion: 'HTTP/1.1',
+        cookies: [],
+        headers: [],
+        queryString: parseQueryString(e.url),
+        headersSize: -1,
+        bodySize: -1,
+      },
+      response: {
+        status: e.status || 0,
+        statusText: '',
+        httpVersion: 'HTTP/1.1',
+        cookies: [],
+        headers: [],
+        content: {
+          size: e.size || 0,
+          mimeType: '',
+        },
+        redirectURL: '',
+        headersSize: -1,
+        bodySize: e.size || -1,
+      },
+      cache: {},
+      timings: {
+        send: 0,
+        wait: e.duration || 0,
+        receive: 0,
+      },
+    }));
+
+  return {
+    log: {
+      version: '1.2',
+      creator: { name: '@ulpi/browse', version: '0.2.0' },
+      entries: harEntries,
+    },
+  };
+}

package/src/policy.ts

@@ -0,0 +1,94 @@
+/**
+ * Action policy — gate commands via JSON config
+ *
+ * File: browse-policy.json (project root) or BROWSE_POLICY env var
+ * Format: { default: "allow"|"deny", deny?: string[], confirm?: string[], allow?: string[] }
+ * Precedence: deny > confirm > allow whitelist > default
+ * Hot-reloads on mtime change.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface ActionPolicy {
+  default?: 'allow' | 'deny';
+  deny?: string[];
+  confirm?: string[];
+  allow?: string[];
+}
+
+export type PolicyResult = 'allow' | 'deny' | 'confirm';
+
+/**
+ * Walk up from cwd looking for a file by name.
+ * Returns the full path if found, or null.
+ */
+function findFileUpward(filename: string): string | null {
+  let dir = process.cwd();
+  for (let i = 0; i < 20; i++) {
+    const candidate = path.join(dir, filename);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export class PolicyChecker {
+  private filePath: string | null = null;
+  private lastMtime: number = 0;
+  private policy: ActionPolicy | null = null;
+  private confirmOverrides: Set<string> | null = null;
+
+  constructor(filePath?: string) {
+    // Explicit path from env or argument, or walk up from cwd to find browse-policy.json.
+    this.filePath = filePath || process.env.BROWSE_POLICY || findFileUpward('browse-policy.json') || 'browse-policy.json';
+
+    // Parse BROWSE_CONFIRM_ACTIONS env var
+    const confirmEnv = process.env.BROWSE_CONFIRM_ACTIONS;
+    if (confirmEnv) {
+      this.confirmOverrides = new Set(
+        confirmEnv.split(',').map(s => s.trim()).filter(Boolean)
+      );
+    }
+
+    this.reload();
+  }
+
+  private reload(): void {
+    if (!this.filePath) return;
+    try {
+      const stat = fs.statSync(this.filePath);
+      if (stat.mtimeMs === this.lastMtime) return;
+      this.lastMtime = stat.mtimeMs;
+
+      const raw = fs.readFileSync(this.filePath, 'utf-8');
+      this.policy = JSON.parse(raw);
+    } catch {
+      // File missing or invalid — if it was loaded before, keep last-known-good.
+      // If it never existed, policy stays null (everything allowed).
+    }
+  }
+
+  check(command: string): PolicyResult {
+    this.reload();
+
+    // Env var overrides take priority for confirm
+    if (this.confirmOverrides?.has(command)) return 'confirm';
+
+    if (!this.policy) return 'allow';
+
+    // Precedence: deny > confirm > allow whitelist > default
+    if (this.policy.deny?.includes(command)) return 'deny';
+    if (this.policy.confirm?.includes(command)) return 'confirm';
+    if (this.policy.allow) {
+      return this.policy.allow.includes(command) ? 'allow' : 'deny';
+    }
+    return this.policy.default || 'allow';
+  }
+
+  isActive(): boolean {
+    return this.policy !== null || this.confirmOverrides !== null;
+  }
+}

package/src/sanitize.ts

@@ -0,0 +1,11 @@
+/**
+ * Sanitize a user-supplied name for safe use in file paths.
+ * Strips path separators and parent directory references.
+ */
+export function sanitizeName(name: string): string {
+  const sanitized = name.replace(/[\/\\]/g, '_').replace(/\.\./g, '_');
+  if (!sanitized || /^[._]+$/.test(sanitized)) {
+    throw new Error(`Invalid name: "${name}"`);
+  }
+  return sanitized;
+}