@moxxy/plugin-browser 0.27.0

package/src/html-extract.ts

@@ -0,0 +1,152 @@
+/**
+ * Minimal HTML → text / markdown extractors used by `web_fetch`. Not a
+ * full DOM parser: regex-based, intentionally limited. For stricter
+ * extraction use the markdown converter with a selector or upgrade to
+ * browser_session.
+ */
+
+export interface ExtractOptions {
+  selector?: string;
+}
+
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+const SCRIPT_RE = /<script\b[^>]*>[\s\S]*?<\/script>/gi;
+const STYLE_RE = /<style\b[^>]*>[\s\S]*?<\/style>/gi;
+
+/**
+ * Hard ceiling on the HTML fed to the regex extractors. web_fetch caps the raw
+ * body at up to 20MB (maxBytes), but the lazy `[\s\S]*?` passes here run
+ * SYNCHRONOUSLY on the runner event loop — a multi-MB adversarial page with
+ * many unmatched open tags could block it. Truncating to a generous 4MB bounds
+ * that worst case while still covering virtually every real article.
+ */
+const MAX_EXTRACT_INPUT = 4 * 1024 * 1024;
+
+/** Bound the regex-extractor input so a hostile, oversized page can't stall the
+ *  event loop. Cuts at a tag boundary when one is near the limit to avoid
+ *  splitting an entity/tag mid-token. */
+function capInput(html: string): string {
+  if (html.length <= MAX_EXTRACT_INPUT) return html;
+  const slice = html.slice(0, MAX_EXTRACT_INPUT);
+  const lastLt = slice.lastIndexOf('<');
+  return lastLt > MAX_EXTRACT_INPUT - 1024 ? slice.slice(0, lastLt) : slice;
+}
+
+/**
+ * Minimal HTML → plain text. Strips <script>, <style>, comments, and tags.
+ * Collapses whitespace. Decodes the common HTML entities.
+ */
+export function htmlToPlainText(html: string, opts: ExtractOptions = {}): string {
+  let body = sliceBySelector(capInput(html), opts.selector);
+  body = body.replace(COMMENT_RE, '');
+  body = body.replace(SCRIPT_RE, '');
+  body = body.replace(STYLE_RE, '');
+  body = body.replace(/<br\b[^>]*>/gi, '\n');
+  body = body.replace(/<\/(p|div|li|tr|h[1-6])>/gi, '\n');
+  body = body.replace(/<[^>]+>/g, '');
+  body = decodeEntities(body);
+  return collapseWhitespace(body);
+}
+
+/**
+ * Minimal HTML → markdown. Maps headings, lists, links, code blocks, and
+ * paragraphs. Falls through to plain-text rules for unknown structure.
+ */
+export function htmlToMarkdown(html: string, opts: ExtractOptions = {}): string {
+  let body = sliceBySelector(capInput(html), opts.selector);
+  body = body.replace(COMMENT_RE, '');
+  body = body.replace(SCRIPT_RE, '');
+  body = body.replace(STYLE_RE, '');
+
+  // headings
+  body = body.replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_, lvl: string, inner: string) =>
+    `\n\n${'#'.repeat(Number(lvl))} ${stripTags(inner).trim()}\n\n`,
+  );
+
+  // links: keep text + url. Accept double-quoted, single-quoted, and unquoted
+  // hrefs — real-world HTML uses all three, and matching only "double" silently
+  // dropped the URL (the link text survived via the later tag-strip).
+  body = body.replace(
+    /<a\b[^>]*\bhref=(?:"([^"]+)"|'([^']+)'|([^\s>]+))[^>]*>([\s\S]*?)<\/a>/gi,
+    (_, dq: string | undefined, sq: string | undefined, uq: string | undefined, inner: string) =>
+      `[${stripTags(inner).trim()}](${dq ?? sq ?? uq})`,
+  );
+
+  // code
+  body = body.replace(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi, (_, inner: string) =>
+    `\n\n\`\`\`\n${stripTags(inner)}\n\`\`\`\n\n`,
+  );
+  body = body.replace(/<code\b[^>]*>([\s\S]*?)<\/code>/gi, (_, inner: string) =>
+    `\`${stripTags(inner)}\``,
+  );
+
+  // lists
+  body = body.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (_, inner: string) =>
+    `\n- ${stripTags(inner).trim()}`,
+  );
+  body = body.replace(/<\/?(ul|ol)\b[^>]*>/gi, '\n');
+
+  // line breaks
+  body = body.replace(/<br\b[^>]*>/gi, '\n');
+  body = body.replace(/<\/?p\b[^>]*>/gi, '\n\n');
+  body = body.replace(/<[^>]+>/g, '');
+  body = decodeEntities(body);
+  return collapseWhitespace(body);
+}
+
+function sliceBySelector(html: string, selector?: string): string {
+  if (!selector) return html;
+  const slice = extractFirstTagBlock(html, selector);
+  return slice ?? html;
+}
+
+function collapseWhitespace(s: string): string {
+  return s.replace(/[ \t]+/g, ' ').replace(/\n[ \t]+/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+function stripTags(s: string): string {
+  return s.replace(/<[^>]+>/g, '');
+}
+
+function decodeEntities(s: string): string {
+  const map: Record<string, string> = {
+    '&amp;': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&#39;': "'",
+    '&apos;': "'",
+    '&nbsp;': ' ',
+  };
+  return s.replace(/&[a-zA-Z]+;|&#\d+;/g, (m) => {
+    if (m in map) return map[m as keyof typeof map]!;
+    const numMatch = /^&#(\d+);$/.exec(m);
+    if (numMatch) return String.fromCharCode(Number(numMatch[1]));
+    return m;
+  });
+}
+
+/**
+ * Pull the first <tag>...</tag> block (or self-closing tag with id="x") whose
+ * tag name OR id matches `selector`. Very limited — supports `tagName` and
+ * `#id` only. For richer querying upgrade to browser_session.
+ */
+function extractFirstTagBlock(html: string, selector: string): string | null {
+  if (selector.startsWith('#')) {
+    const id = selector.slice(1);
+    const re = new RegExp(
+      `<([a-z][a-z0-9-]*)\\b[^>]*\\bid=["']${escapeReSelector(id)}["'][^>]*>([\\s\\S]*?)<\\/\\1>`,
+      'i',
+    );
+    const match = re.exec(html);
+    return match ? match[2]! : null;
+  }
+  const tag = selector.toLowerCase();
+  const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'i');
+  const match = re.exec(html);
+  return match ? match[1]! : null;
+}
+
+function escapeReSelector(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import { definePlugin } from '@moxxy/sdk';
+import { webFetchTool } from './web-fetch.js';
+import { buildBrowserSessionTool, closeBrowserSidecar, type BrowserSessionDeps } from './browser-session.js';
+import { buildBrowserSurface } from './browser-surface.js';
+
+export { webFetchTool, htmlToPlainText, htmlToMarkdown } from './web-fetch.js';
+export {
+  buildBrowserSessionTool,
+  browserSidecarCall,
+  closeBrowserSidecar,
+  type BrowserSessionDeps,
+  type SidecarStream,
+} from './browser-session.js';
+export { buildBrowserSurface } from './browser-surface.js';
+
+export interface BuildBrowserPluginOptions extends BrowserSessionDeps {}
+
+export function buildBrowserPlugin(opts: BuildBrowserPluginOptions = {}) {
+  return definePlugin({
+    name: '@moxxy/plugin-browser',
+    version: '0.0.0',
+    tools: [webFetchTool, buildBrowserSessionTool(opts)],
+    surfaces: [buildBrowserSurface(opts)],
+    hooks: {
+      onShutdown: async () => {
+        // Make sure the sidecar process exits with the session.
+        await closeBrowserSidecar();
+      },
+    },
+  });
+}
+
+export const browserPlugin = buildBrowserPlugin();
+
+export default browserPlugin;

package/src/sidecar/dispatch.test.ts

@@ -0,0 +1,313 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { dispatch, type SidecarState } from './dispatch.js';
+import type { Err, Ok, PlaywrightHandle } from './types.js';
+import { setSsrfDnsResolver } from '../ssrf-guard.js';
+
+/**
+ * Dispatch-level SSRF tests: the sidecar is a separate process that must not
+ * trust the parent to have validated `goto` URLs. The guard must fire BEFORE
+ * Playwright is touched — these tests run with `state.handle` unset for
+ * blocked URLs, so reaching `ensurePlaywright` (and its `import('playwright')`)
+ * would fail loudly.
+ */
+
+interface HandleCalls {
+  gotos: string[];
+  clicks: Array<{ x: number; y: number }>;
+  wheels: Array<{ dx: number; dy: number }>;
+  presses: string[];
+  types: string[];
+  evals: string[];
+}
+
+function makeFakeHandle(opts?: {
+  evalResult?: unknown;
+  textContent?: string | null;
+  content?: string;
+  viewport?: { width: number; height: number } | null;
+}): { handle: PlaywrightHandle; gotos: string[]; calls: HandleCalls } {
+  const calls: HandleCalls = { gotos: [], clicks: [], wheels: [], presses: [], types: [], evals: [] };
+  let current = 'about:blank';
+  const handle: PlaywrightHandle = {
+    browser: { close: async () => {} },
+    context: { newPage: async () => ({}), close: async () => {} },
+    page: {
+      goto: async (url: string) => {
+        calls.gotos.push(url);
+        current = url;
+        return undefined;
+      },
+      click: async () => {},
+      fill: async () => {},
+      textContent: async () => (opts && 'textContent' in opts ? (opts.textContent ?? null) : null),
+      content: async () => opts?.content ?? '',
+      screenshot: async () => Buffer.from('screenshot-bytes'),
+      evaluate: async (expr: string) => {
+        calls.evals.push(expr);
+        return opts && 'evalResult' in opts ? opts.evalResult : undefined;
+      },
+      url: () => current,
+      close: async () => {},
+      viewportSize: () => (opts && 'viewport' in opts ? (opts.viewport ?? null) : { width: 800, height: 600 }),
+      mouse: {
+        click: async (x: number, y: number) => {
+          calls.clicks.push({ x, y });
+        },
+        wheel: async (dx: number, dy: number) => {
+          calls.wheels.push({ dx, dy });
+        },
+      },
+      keyboard: {
+        press: async (key: string) => {
+          calls.presses.push(key);
+        },
+        type: async (text: string) => {
+          calls.types.push(text);
+        },
+      },
+    },
+  };
+  return { handle, gotos: calls.gotos, calls };
+}
+
+function req(method: string, params: Record<string, unknown> = {}): { id: string; method: string; params: Record<string, unknown> } {
+  return { id: 'r1', method, params };
+}
+
+function gotoReq(url: string): { id: string; method: string; params: { url: string } } {
+  return { id: 'r1', method: 'goto', params: { url } };
+}
+
+describe('sidecar dispatch goto SSRF guard', () => {
+  beforeEach(() => {
+    // Hermetic DNS: any hostname "resolves" public unless a test overrides.
+    setSsrfDnsResolver(async () => ['93.184.216.34']);
+  });
+  afterEach(() => {
+    setSsrfDnsResolver(null);
+    vi.restoreAllMocks();
+  });
+
+  it.each([
+    'http://169.254.169.254/latest/meta-data/',
+    'http://localhost:8080/',
+    'http://10.0.0.5/internal',
+    'file:///etc/passwd',
+  ])('rejects %s without launching a browser', async (url) => {
+    const state: SidecarState = { handle: null, pendingInstallNotice: null };
+    const reply = (await dispatch(state, gotoReq(url))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('navigation');
+    expect(reply.error.message).toMatch(/loopback|private|scheme/);
+    expect(state.handle).toBeNull(); // never reached ensurePlaywright
+  });
+
+  it('rejects a hostname that resolves to a private address', async () => {
+    setSsrfDnsResolver(async () => ['192.168.0.10']);
+    const state: SidecarState = { handle: null, pendingInstallNotice: null };
+    const reply = (await dispatch(state, gotoReq('https://intranet.example.com/'))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.message).toMatch(/private|loopback/);
+  });
+
+  it('navigates a public URL on the (pre-seeded) page', async () => {
+    const { handle, gotos } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, gotoReq('https://example.com/'))) as Ok;
+    expect(reply.ok).toBe(true);
+    expect(reply.result).toEqual({ url: 'https://example.com/' });
+    expect(gotos).toEqual(['https://example.com/']);
+  });
+});
+
+describe('sidecar dispatch removed screencast methods', () => {
+  // The CDP screencast push path was orphaned by the PR #205 polling revert and
+  // deleted. Its former methods must now fall through to the default branch and
+  // report `unknown method` (not silently succeed). Uses a pre-seeded handle so
+  // we never reach `ensurePlaywright` / a real Playwright import.
+  it.each(['startScreencast', 'stopScreencast'])(
+    'reports %s as an unknown method',
+    async (method) => {
+      const { handle } = makeFakeHandle();
+      const state: SidecarState = { handle, pendingInstallNotice: null };
+      const reply = (await dispatch(state, { id: 'r1', method, params: {} })) as Err;
+      expect(reply.ok).toBe(false);
+      expect(reply.error.kind).toBe('runtime');
+      expect(reply.error.message).toBe(`unknown method: ${method}`);
+    },
+  );
+});
+
+describe('sidecar dispatch protocol methods (against a pre-seeded handle)', () => {
+  // Each test pre-seeds state.handle so `ensurePlaywright` short-circuits and no
+  // real Playwright import / launch happens. These assert the exact wire shapes
+  // the surface + tool callers consume.
+
+  it('text without a selector reads whole-document innerText via evaluate', async () => {
+    const { handle, calls } = makeFakeHandle({ evalResult: 'page body text' });
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('text'))) as Ok;
+    expect(reply.ok).toBe(true);
+    expect(reply.result).toBe('page body text');
+    expect(calls.evals).toHaveLength(1);
+  });
+
+  it('text with a selector returns its textContent (empty string when null)', async () => {
+    const { handle } = makeFakeHandle({ textContent: null });
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('text', { selector: 'main' }))) as Ok;
+    expect(reply.ok).toBe(true);
+    expect(reply.result).toBe('');
+  });
+
+  it('html returns the page content', async () => {
+    const { handle } = makeFakeHandle({ content: '<html>x</html>' });
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('html'))) as Ok;
+    expect(reply.result).toBe('<html>x</html>');
+  });
+
+  it('screenshot returns a png mediaType + base64 payload', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('screenshot'))) as Ok;
+    expect(reply.result).toEqual({
+      mediaType: 'image/png',
+      base64: Buffer.from('screenshot-bytes').toString('base64'),
+    });
+  });
+
+  it('frame returns jpeg + url + viewport dimensions', async () => {
+    const { handle } = makeFakeHandle({ viewport: { width: 1024, height: 768 } });
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('frame'))) as Ok;
+    expect(reply.result).toEqual({
+      mediaType: 'image/jpeg',
+      base64: Buffer.from('screenshot-bytes').toString('base64'),
+      url: 'about:blank',
+      width: 1024,
+      height: 768,
+    });
+  });
+
+  it('frame falls back to 1280x720 when viewportSize() is null', async () => {
+    const { handle } = makeFakeHandle({ viewport: null });
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('frame'))) as Ok;
+    expect(reply.result).toMatchObject({ width: 1280, height: 720 });
+  });
+
+  it('mouse forwards finite coords to page.mouse.click and returns the url', async () => {
+    const { handle, calls } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('mouse', { x: 12, y: 34 }))) as Ok;
+    expect(reply.ok).toBe(true);
+    expect(reply.result).toEqual({ url: 'about:blank' });
+    expect(calls.clicks).toEqual([{ x: 12, y: 34 }]);
+  });
+
+  it.each([
+    ['missing both', {}],
+    ['missing y', { x: 5 }],
+    ['NaN x', { x: Number.NaN, y: 2 }],
+  ])('mouse with %s coords returns a runtime badParams without touching the page', async (_label, params) => {
+    const { handle, calls } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('mouse', params))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('runtime');
+    expect(calls.clicks).toHaveLength(0);
+  });
+
+  it('key types a single printable char and presses a named key', async () => {
+    const { handle, calls } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    expect(((await dispatch(state, req('key', { key: 'a' }))) as Ok).ok).toBe(true);
+    expect(((await dispatch(state, req('key', { key: 'Enter' }))) as Ok).ok).toBe(true);
+    expect(calls.types).toEqual(['a']);
+    expect(calls.presses).toEqual(['Enter']);
+  });
+
+  it('key without a key value returns a runtime badParams', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('key', {}))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('runtime');
+  });
+
+  it('scroll forwards dy to mouse.wheel and defaults missing dy to 0', async () => {
+    const { handle, calls } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    await dispatch(state, req('scroll', { dy: 120 }));
+    await dispatch(state, req('scroll', {}));
+    expect(calls.wheels).toEqual([
+      { dx: 0, dy: 120 },
+      { dx: 0, dy: 0 },
+    ]);
+  });
+
+  it('eval forwards the expression and returns its value', async () => {
+    const { handle, calls } = makeFakeHandle({ evalResult: 42 });
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('eval', { expression: '1 + 41' }))) as Ok;
+    expect(reply.result).toBe(42);
+    expect(calls.evals).toEqual(['1 + 41']);
+  });
+
+  it('eval without an expression returns a runtime badParams', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('eval', {}))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('runtime');
+  });
+
+  it('url returns the current page url', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('url'))) as Ok;
+    expect(reply.result).toBe('about:blank');
+  });
+
+  it('close tears down the handle and is idempotent', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    expect(((await dispatch(state, req('close'))) as Ok).ok).toBe(true);
+    expect(state.handle).toBeNull();
+    // A second close (handle already null) still replies ok.
+    expect(((await dispatch(state, req('close'))) as Ok).ok).toBe(true);
+  });
+
+  it.each([
+    ['setviewport', { width: 1e9, height: 100 }],
+    ['setviewport', { width: 100, height: 1e9 }],
+    ['capture', { x: 0, y: 0, width: 100_000, height: 10 }],
+    ['capture', { x: 0, y: 0, width: 10, height: 100_000 }],
+  ])('%s with an over-limit dimension returns badParams without launching a browser', async (method, params) => {
+    // state.handle stays null so reaching ensurePlaywright (a real Playwright
+    // import) would fail loudly — the dimension clamp must fire first.
+    const state: SidecarState = { handle: null, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req(method, params))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('runtime');
+    expect(reply.error.message).toMatch(/<=|must be/);
+    expect(state.handle).toBeNull();
+  });
+
+  it('click requires a selector', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('click', {}))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('runtime');
+  });
+
+  it('fill requires a selector', async () => {
+    const { handle } = makeFakeHandle();
+    const state: SidecarState = { handle, pendingInstallNotice: null };
+    const reply = (await dispatch(state, req('fill', { value: 'x' }))) as Err;
+    expect(reply.ok).toBe(false);
+    expect(reply.error.kind).toBe('runtime');
+  });
+});