@moxxy/plugin-browser 0.27.0

package/src/sidecar/types.ts

@@ -0,0 +1,114 @@
+export type BrowserKind = 'chromium' | 'firefox' | 'webkit';
+
+export type ErrorKind =
+  | 'init'
+  | 'needs-install' // the `playwright` npm package itself isn't installed yet
+  | 'navigation'
+  | 'runtime'
+  | 'timeout'
+  | 'unknown';
+
+export interface Req {
+  readonly id: string;
+  readonly method: string;
+  readonly params?: Record<string, unknown>;
+}
+
+export interface Ok {
+  readonly id: string;
+  readonly ok: true;
+  readonly result?: unknown;
+  /** One-shot human-readable note (e.g. "Auto-installed Chromium"). */
+  readonly notice?: string;
+}
+
+export interface Err {
+  readonly id: string;
+  readonly ok: false;
+  readonly error: { message: string; kind: ErrorKind };
+}
+
+export type Reply = Ok | Err;
+
+export interface BrowserType {
+  launch(opts: {
+    headless: boolean;
+  }): Promise<{ close(): Promise<void>; newContext(opts?: unknown): Promise<unknown> }>;
+}
+
+export interface PageHandle {
+  goto(url: string, opts?: unknown): Promise<unknown>;
+  click(selector: string, opts?: unknown): Promise<void>;
+  fill(selector: string, value: string, opts?: unknown): Promise<void>;
+  textContent(selector: string): Promise<string | null>;
+  content(): Promise<string>;
+  screenshot(opts?: unknown): Promise<Buffer>;
+  evaluate(fn: string): Promise<unknown>;
+  url(): string;
+  close(): Promise<void>;
+  // Coordinate-based input + viewport control for the live browser surface
+  // (loosely typed — the real Playwright Page provides all of these).
+  viewportSize(): { width: number; height: number } | null;
+  setViewportSize(size: { width: number; height: number }): Promise<void>;
+  goBack(opts?: unknown): Promise<unknown>;
+  goForward(opts?: unknown): Promise<unknown>;
+  reload(opts?: unknown): Promise<unknown>;
+  readonly mouse: {
+    move(x: number, y: number, opts?: unknown): Promise<void>;
+    click(x: number, y: number, opts?: unknown): Promise<void>;
+    wheel(dx: number, dy: number): Promise<void>;
+  };
+  readonly keyboard: {
+    press(key: string): Promise<void>;
+    type(text: string): Promise<void>;
+  };
+}
+
+/** Minimal slice of Playwright's `Request` used by the navigation SSRF guard. */
+export interface RouteRequest {
+  url(): string;
+  isNavigationRequest(): boolean;
+}
+
+/** Minimal slice of Playwright's `Route` used by the navigation SSRF guard. */
+export interface RouteHandle {
+  request(): RouteRequest;
+  abort(errorCode?: string): Promise<void>;
+  continue(): Promise<void>;
+}
+
+export interface PlaywrightHandle {
+  // Loosely typed so we can avoid importing the playwright types at compile time —
+  // they're an optional peer dependency.
+  readonly browser: { close(): Promise<void> };
+  readonly context: {
+    newPage(): Promise<unknown>;
+    close(): Promise<void>;
+    /** Optional because the type is a loose projection; real Playwright contexts always have it. */
+    route?(pattern: string, handler: (route: RouteHandle) => Promise<void> | void): Promise<void>;
+  };
+  readonly page: PageHandle;
+}
+
+export function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * An error carrying a typed {@link ErrorKind} so the dispatch layer can map it
+ * onto the wire reply's `error.kind` without poking an untyped `kind` property
+ * onto a bare `Error`.
+ */
+export class SidecarError extends Error {
+  constructor(
+    message: string,
+    readonly kind: ErrorKind,
+  ) {
+    super(message);
+    this.name = 'SidecarError';
+  }
+}
+
+export function badParams(msg: string): SidecarError {
+  return new SidecarError(msg, 'runtime');
+}

package/src/sidecar.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { enqueueLine } from './sidecar.js';
+import type { Reply } from './sidecar/types.js';
+
+/**
+ * The serial request queue chains each link off the previous one. A throw from
+ * the reply sink (real run: a broken stdout pipe on `process.stdout.write`) used
+ * to reject the shared `queue` promise permanently, stranding EVERY subsequent
+ * request. The `.catch` on the chained link must keep the queue alive so the
+ * next request still serves. We drive `enqueueLine` directly with a stub sink
+ * (and an unknown method, so dispatch never touches Playwright).
+ */
+describe('sidecar request queue resilience', () => {
+  it('keeps serving after the reply sink throws once', async () => {
+    const writes: Reply[] = [];
+    let firstWriteThrew = false;
+    const out = (reply: Reply): void => {
+      if (!firstWriteThrew) {
+        firstWriteThrew = true;
+        throw new Error('EPIPE: broken pipe'); // poison the first reply write
+      }
+      writes.push(reply);
+    };
+
+    // Request 1: its reply write throws; the link's `.catch` retries the write
+    // (now succeeding) instead of poisoning the queue.
+    await enqueueLine(JSON.stringify({ id: 'a', method: 'noop' }), out);
+    // Request 2: must STILL get a reply — the queue wasn't stranded.
+    await enqueueLine(JSON.stringify({ id: 'b', method: 'noop' }), out);
+
+    expect(firstWriteThrew).toBe(true);
+    const ids = writes.map((r) => r.id);
+    expect(ids).toContain('b'); // the next request was served
+    // Request 1's error reply lands too (its catch-path re-wrote it).
+    expect(ids).toContain('a');
+  });
+
+  it('echoes the real id on a missing-method error so the parent can settle the call', async () => {
+    const writes: Reply[] = [];
+    const out = (reply: Reply): void => void writes.push(reply);
+    // id round-trips, only `method` is missing — the reply MUST carry the real
+    // id (not 'unknown') so the parent's pending map matches and the caller is
+    // rejected instead of left waiting for its timeout.
+    await enqueueLine(JSON.stringify({ id: 'real-id' }), out);
+    expect(writes).toHaveLength(1);
+    expect(writes[0]!.id).toBe('real-id');
+    expect(writes[0]!.ok).toBe(false);
+  });
+
+  it('falls back to "unknown" for wholly unparseable input', async () => {
+    const writes: Reply[] = [];
+    const out = (reply: Reply): void => void writes.push(reply);
+    await enqueueLine('{not json', out);
+    expect(writes[0]!.id).toBe('unknown');
+    expect(writes[0]!.ok).toBe(false);
+  });
+});

package/src/sidecar.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * Playwright sidecar — owns a single browser context. Speaks newline-delimited
+ * JSON-RPC over stdio so the parent (`browser_session` tool) doesn't load
+ * Playwright into its own process. Crash isolation, lazy install: the parent
+ * only spawns this when the heavy tier is actually needed.
+ *
+ * Wire format (one line per message):
+ *   { "id": "uuid", "method": "goto"|"click"|"fill"|"text"|"html"|"screenshot"|"eval"|"close", "params": {...} }
+ *   { "id": "uuid", "ok": true,  "result": ... }
+ *   { "id": "uuid", "ok": false, "error": { "message": "...", "kind": "init"|"navigation"|"runtime"|"timeout" } }
+ *
+ * Run with `node dist/sidecar.js` (the package's `bin` entry is
+ * `moxxy-browser-sidecar`). Parent terminates by closing stdin or sending
+ * `{method:'close'}`.
+ */
+
+import * as readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { dispatch, teardown, type SidecarState } from './sidecar/dispatch.js';
+import { errMsg, type Reply, type Req } from './sidecar/types.js';
+
+const state: SidecarState = { handle: null, pendingInstallNotice: null };
+
+function write(reply: Reply): void {
+  // Drain the install-notice flag into the first reply that goes out
+  // after the install completed, then clear it. Errors get the notice
+  // too — sometimes the launch retry surfaces a different problem and
+  // the user still wants to know we tried to install.
+  if (state.pendingInstallNotice) {
+    if (reply.ok) {
+      reply = { ...reply, notice: state.pendingInstallNotice };
+    } else {
+      reply = {
+        ...reply,
+        error: {
+          ...reply.error,
+          message: `${state.pendingInstallNotice} Then: ${reply.error.message}`,
+        },
+      };
+    }
+    state.pendingInstallNotice = null;
+  }
+  process.stdout.write(JSON.stringify(reply) + '\n');
+}
+
+/**
+ * Tears down the browser context AND exits the process. Used both by
+ * the explicit `close` RPC path and the parent-loss / stdin-close
+ * paths so all cleanup goes through one routine.
+ */
+async function shutdownAndExit(code: number): Promise<void> {
+  await teardown(state);
+  process.exit(code);
+}
+
+/**
+ * Parent watchdog: if the moxxy process that spawned this sidecar
+ * disappears (crash, SIGKILL, terminal hangup), there's no stdin EOF
+ * to rely on — orphan Chromium would keep running and chew CPU/memory
+ * until the user notices. Poll the parent PID every few seconds and
+ * self-terminate when it goes away.
+ *
+ * `process.kill(pid, 0)` is the POSIX trick for "does this PID
+ * exist?" — no signal is actually delivered. Throws ESRCH when the
+ * process is gone (or EPERM when it exists but we can't signal it —
+ * still alive, so don't treat as gone).
+ */
+function startParentWatchdog(): void {
+  const parentPid = process.ppid;
+  if (!parentPid || parentPid <= 1) return; // already orphaned (init), nothing to watch
+  const interval = setInterval(() => {
+    try {
+      process.kill(parentPid, 0);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ESRCH') {
+        clearInterval(interval);
+        void shutdownAndExit(0);
+      }
+      // EPERM means the process exists but we can't signal it — still alive.
+    }
+  }, 2000);
+  interval.unref?.(); // never block the event loop from exiting
+}
+
+let queue: Promise<void> = Promise.resolve();
+
+/**
+ * Parse one input line and chain its dispatch onto the serial request queue.
+ * `out` is the sink for replies (real run: {@link write}; tests inject a stub).
+ * Exported so a test can drive the queue without spinning up the whole stdio
+ * loop. Returns the queue tail so callers can await it.
+ *
+ * The `.catch` on the chained link is load-bearing: a throw from `out` (e.g. a
+ * broken stdout pipe) would otherwise reject `queue` permanently and strand
+ * EVERY subsequent request, since each link chains off the previous one.
+ * Swallow it here — after emitting a best-effort error reply — so the next
+ * request still serves.
+ */
+export function enqueueLine(line: string, out: (reply: Reply) => void): Promise<void> {
+  if (!line.trim()) return queue;
+  let req: Req;
+  try {
+    req = JSON.parse(line) as Req;
+  } catch {
+    // Wholly unparseable — there's no id to recover, so the parent can't match
+    // this reply; it's best-effort diagnostic output only.
+    out({ id: 'unknown', ok: false, error: { message: 'invalid JSON', kind: 'runtime' } });
+    return queue;
+  }
+  if (!req.id || !req.method) {
+    // Echo the request's real id whenever it round-tripped (only `method` was
+    // missing), so the parent can SETTLE the matching pending call instead of
+    // dropping the reply and stranding the caller until its timeout. Fall back
+    // to 'unknown' only when the id genuinely can't be recovered.
+    out({
+      id: typeof req.id === 'string' && req.id ? req.id : 'unknown',
+      ok: false,
+      error: { message: 'request requires { id, method }', kind: 'runtime' },
+    });
+    return queue;
+  }
+  // Sequentially serve requests on the single page. Parent can pipeline by
+  // sending more requests; we serialize them inside the sidecar so a goto
+  // doesn't race a click.
+  queue = queue
+    .then(async () => {
+      const reply = await dispatch(state, req);
+      out(reply);
+    })
+    .catch((err) => {
+      try {
+        out({ id: req.id, ok: false, error: { message: errMsg(err), kind: 'runtime' } });
+      } catch {
+        /* stdout is gone too — nothing left to do but keep the queue alive */
+      }
+    });
+  return queue;
+}
+
+async function main(): Promise<void> {
+  startParentWatchdog();
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on('line', (line) => {
+    void enqueueLine(line, write);
+  });
+  rl.once('close', () => {
+    void shutdownAndExit(0);
+  });
+  // Defensive: if our stdout pipe breaks (parent died mid-write), Node
+  // would otherwise throw an uncaught EPIPE on the next write. Treat
+  // it as a signal to clean up gracefully instead.
+  process.stdout.on('error', (err) => {
+    if ((err as NodeJS.ErrnoException).code === 'EPIPE') {
+      void shutdownAndExit(0);
+    }
+  });
+}
+
+// Auto-run only when executed as the bin script — not when imported (tests).
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().catch((err) => {
+    process.stderr.write(`sidecar fatal: ${errMsg(err)}\n`);
+    void shutdownAndExit(1);
+  });
+}

package/src/ssrf-guard.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { assertPublicUrl, isBlockedIp, setSsrfDnsResolver, SsrfBlockedError } from './ssrf-guard.js';
+
+afterEach(() => setSsrfDnsResolver(null));
+
+describe('assertPublicUrl (shared SSRF guard)', () => {
+  it('blocks the cloud metadata IP literal', async () => {
+    await expect(assertPublicUrl('http://169.254.169.254/latest/meta-data/')).rejects.toThrow(
+      /private|loopback/,
+    );
+  });
+
+  it('blocks localhost without consulting DNS', async () => {
+    setSsrfDnsResolver(async () => {
+      throw new Error('resolver should not be consulted for localhost');
+    });
+    await expect(assertPublicUrl('http://localhost:8080/admin')).rejects.toThrow(/loopback/);
+  });
+
+  it('blocks RFC-1918 literals', async () => {
+    await expect(assertPublicUrl('http://10.0.0.5/')).rejects.toThrow(/private|loopback/);
+    await expect(assertPublicUrl('http://192.168.1.1/')).rejects.toThrow(/private|loopback/);
+    await expect(assertPublicUrl('http://172.16.0.1/')).rejects.toThrow(/private|loopback/);
+  });
+
+  it('blocks IPv6 loopback / link-local / unique-local', async () => {
+    await expect(assertPublicUrl('http://[::1]:3000/')).rejects.toThrow(/private|loopback/);
+    await expect(assertPublicUrl('http://[fe80::1]/')).rejects.toThrow(/private|loopback/);
+    await expect(assertPublicUrl('http://[fd00::1]/')).rejects.toThrow(/private|loopback/);
+  });
+
+  it('blocks v4-mapped IPv6 in the HEX form the URL parser actually produces', async () => {
+    // new URL('http://[::ffff:127.0.0.1]/').hostname === '::ffff:7f00:1' — the
+    // dotted spelling never reaches the guard via a real URL, so the guard must
+    // recognize the hex form. Driving through assertPublicUrl exercises the same
+    // canonicalization a real request hits (the regression the dotted-only check
+    // missed: loopback AND the cloud-metadata endpoint slipped straight past).
+    await expect(assertPublicUrl('http://[::ffff:127.0.0.1]/')).rejects.toThrow(/private|loopback/);
+    await expect(assertPublicUrl('http://[::ffff:169.254.169.254]/latest/meta-data/')).rejects.toThrow(
+      /private|loopback/,
+    );
+    await expect(assertPublicUrl('http://[::ffff:192.168.1.1]/')).rejects.toThrow(/private|loopback/);
+    await expect(assertPublicUrl('http://[::ffff:10.0.0.1]/')).rejects.toThrow(/private|loopback/);
+  });
+
+  it('still allows a v4-mapped PUBLIC address (the embedded v4 is what matters)', async () => {
+    // ::ffff:93.184.216.34 → public; must NOT be blocked just for being v4-mapped.
+    await expect(assertPublicUrl('http://[::ffff:93.184.216.34]/')).resolves.toBeNull();
+  });
+
+  it('fail-closed mode rejects an unresolvable host (browser paths)', async () => {
+    setSsrfDnsResolver(async () => {
+      throw new Error('NXDOMAIN');
+    });
+    // Default (web_fetch) fails OPEN: a name it can't resolve is no vector.
+    await expect(assertPublicUrl('https://nope.invalid/')).resolves.toBeNull();
+    // failClosed (browser goto / navigation guard) SOFT-BLOCKS instead.
+    await expect(
+      assertPublicUrl('https://nope.invalid/', 'goto', { failClosed: true }),
+    ).rejects.toThrow(/DNS resolution failed/);
+  });
+
+  it('blocks non-HTTP(S) schemes', async () => {
+    await expect(assertPublicUrl('file:///etc/passwd')).rejects.toThrow(/scheme/);
+    await expect(assertPublicUrl('javascript:alert(1)')).rejects.toThrow(/scheme/);
+  });
+
+  it('blocks a hostname that resolves to a private address', async () => {
+    setSsrfDnsResolver(async () => ['10.0.0.5']);
+    await expect(assertPublicUrl('https://intranet.example.com/')).rejects.toThrow(
+      /private|loopback/,
+    );
+  });
+
+  it('allows a public IP literal and a publicly-resolving hostname', async () => {
+    // IP literal: nothing resolved, nothing to pin.
+    await expect(assertPublicUrl('https://93.184.216.34/')).resolves.toBeNull();
+    setSsrfDnsResolver(async () => ['93.184.216.34']);
+    // Hostname: the vetted addresses come back so callers can pin them.
+    await expect(assertPublicUrl('https://example.com/')).resolves.toEqual(['93.184.216.34']);
+  });
+
+  it('throws SsrfBlockedError with the caller label prefixed', async () => {
+    const err = await assertPublicUrl('http://127.0.0.1/', 'browser_session').catch((e) => e);
+    expect(err).toBeInstanceOf(SsrfBlockedError);
+    expect((err as Error).message).toMatch(/^browser_session:/);
+  });
+});
+
+describe('isBlockedIp', () => {
+  it('blocks unparseable input', () => {
+    expect(isBlockedIp('not-an-ip')).toBe(true);
+  });
+  it('passes public v4 and v6', () => {
+    expect(isBlockedIp('93.184.216.34')).toBe(false);
+    expect(isBlockedIp('2606:2800:220:1:248:1893:25c8:1946')).toBe(false);
+  });
+  it('blocks v4-mapped private v6', () => {
+    expect(isBlockedIp('::ffff:192.168.1.1')).toBe(true);
+  });
+  it('blocks v4-mapped private v6 in HEX form (the URL-canonicalized spelling)', () => {
+    expect(isBlockedIp('::ffff:7f00:1')).toBe(true); // 127.0.0.1
+    expect(isBlockedIp('::ffff:a9fe:a9fe')).toBe(true); // 169.254.169.254 metadata
+    expect(isBlockedIp('::ffff:c0a8:101')).toBe(true); // 192.168.1.1
+  });
+  it('does NOT block a v4-mapped PUBLIC address', () => {
+    expect(isBlockedIp('::ffff:5db8:d822')).toBe(false); // 93.184.216.34
+  });
+});

package/src/ssrf-guard.ts

@@ -0,0 +1,165 @@
+import { isIP } from 'node:net';
+import { lookup as dnsLookup } from 'node:dns/promises';
+
+/**
+ * Shared SSRF guard for every model-drivable navigation/fetch path in this
+ * plugin: `web_fetch` (initial URL + every redirect hop), `browser_session`'s
+ * goto (parent side), the sidecar's goto dispatch (child-process side), and
+ * the sidecar's in-page navigation interceptor.
+ *
+ * Blocks non-HTTP(S) schemes, loopback (incl. `localhost`/`*.localhost`),
+ * 0.0.0.0/8, RFC-1918 private ranges, link-local 169.254/16 (incl. the
+ * 169.254.169.254 cloud metadata endpoint), CGNAT 100.64/10, multicast/
+ * reserved, and IPv6 loopback/link-local/unique-local (+ v4-mapped). Hostnames
+ * are resolved so an internal DNS name (or rebinding) can't smuggle a private
+ * target past the literal-IP checks.
+ *
+ * NOTE: deliberately NO `@moxxy/sdk` import. The Playwright sidecar — a
+ * separate child process whose bundle must stay free of non-builtin deps —
+ * imports this module too. Parent-side callers wrap `SsrfBlockedError` into
+ * `MoxxyError` themselves.
+ */
+
+/** Thrown for every guard rejection (bad scheme, private/loopback target, unparseable URL). */
+export class SsrfBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SsrfBlockedError';
+  }
+}
+
+export type DnsResolver = (host: string) => Promise<ReadonlyArray<string>>;
+const defaultResolver: DnsResolver = async (host) =>
+  (await dnsLookup(host, { all: true })).map((a) => a.address);
+let resolver: DnsResolver = defaultResolver;
+
+/** Test seam: override DNS resolution so SSRF tests stay hermetic. Pass null to reset. */
+export function setSsrfDnsResolver(fn: DnsResolver | null): void {
+  resolver = fn ?? defaultResolver;
+}
+
+function isBlockedIpv4(ip: string): boolean {
+  const parts = ip.split('.').map((p) => Number(p));
+  if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) return true;
+  const [a, b] = parts as [number, number, number, number];
+  if (a === 0) return true; // 0.0.0.0/8 "this host"
+  if (a === 127) return true; // loopback
+  if (a === 10) return true; // private
+  if (a === 172 && b >= 16 && b <= 31) return true; // private
+  if (a === 192 && b === 168) return true; // private
+  if (a === 169 && b === 254) return true; // link-local incl. 169.254.169.254 metadata
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64/10
+  if (a >= 224) return true; // multicast / reserved
+  return false;
+}
+
+function isBlockedIpv6(ip: string): boolean {
+  const addr = ip.toLowerCase().replace(/^\[|\]$/g, '').split('%')[0]!; // strip zone id
+  if (addr === '::1' || addr === '::') return true; // loopback / unspecified
+  if (addr.startsWith('fe80')) return true; // link-local
+  if (addr.startsWith('fc') || addr.startsWith('fd')) return true; // unique-local fc00::/7
+  // Embedded-v4 forms: re-run the v4 policy against the embedded address.
+  // The WHATWG URL parser canonicalizes [::ffff:127.0.0.1] to its HEX form
+  // ::ffff:7f00:1, so the dotted regex alone NEVER matches a real URL — we must
+  // also reconstruct the dotted quad from the trailing hex groups. Covers
+  // v4-mapped (::ffff:a.b.c.d / ::ffff:0:a.b.c.d), v4-compatible (::a.b.c.d),
+  // and NAT64 (64:ff9b::/96) — any of which could otherwise smuggle a private
+  // v4 target (loopback / 169.254.169.254 metadata) past the guard.
+  const embeddedV4 = extractEmbeddedV4(addr);
+  if (embeddedV4) return isBlockedIpv4(embeddedV4);
+  return false;
+}
+
+/**
+ * Pull the embedded IPv4 out of any v4-mapped / v4-compatible / NAT64 IPv6
+ * address, returning it as a dotted quad, or null if there is none. Handles
+ * both the dotted spelling (`::ffff:127.0.0.1`) and — critically — the HEX
+ * spelling the URL parser actually produces (`::ffff:7f00:1`).
+ */
+function extractEmbeddedV4(addr: string): string | null {
+  // Dotted spelling: ::ffff:a.b.c.d, ::ffff:0:a.b.c.d, ::a.b.c.d, 64:ff9b::a.b.c.d
+  const dotted = addr.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (dotted && (addr.startsWith('::ffff:') || addr.startsWith('::') || addr.startsWith('64:ff9b:'))) {
+    return dotted[1]!;
+  }
+  // Hex spelling: the embedded v4 lives in the two trailing 16-bit groups.
+  const hex = addr.match(/^(?:::ffff:|::ffff:0:|64:ff9b:(?::|.*:)|::)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1]!, 16);
+    const lo = parseInt(hex[2]!, 16);
+    if (Number.isInteger(hi) && Number.isInteger(lo) && hi <= 0xffff && lo <= 0xffff) {
+      return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+    }
+  }
+  return null;
+}
+
+export function isBlockedIp(ip: string): boolean {
+  const kind = isIP(ip);
+  if (kind === 4) return isBlockedIpv4(ip);
+  if (kind === 6) return isBlockedIpv6(ip);
+  return true; // not a parseable IP → block
+}
+
+/**
+ * Reject `raw` unless it is an http(s) URL whose host is (and resolves to)
+ * a public address. `label` prefixes the error message so each caller's
+ * rejections stay attributable (e.g. "web_fetch", "browser_session").
+ *
+ * Returns the vetted resolved addresses so callers can PIN the subsequent
+ * connection to exactly what was checked (closing the DNS-rebinding TOCTOU
+ * where the guard resolves one answer and the fetch independently resolves
+ * another — see web-fetch's pinned undici dispatcher). Returns `null` when
+ * there is nothing to pin: the host is already an IP literal (vetted above,
+ * no DNS involved) or resolution failed (fail-open — a name the guard can't
+ * resolve, the fetch's identical system resolver can't reach either).
+ */
+export async function assertPublicUrl(
+  raw: string,
+  label = 'request',
+  opts: { failClosed?: boolean } = {},
+): Promise<ReadonlyArray<string> | null> {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new SsrfBlockedError(`${label}: invalid URL: ${raw}`);
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new SsrfBlockedError(`${label}: refusing non-HTTP(S) scheme "${u.protocol}"`);
+  }
+  const host = u.hostname.replace(/^\[|\]$/g, '');
+  if (host === 'localhost' || host.endsWith('.localhost')) {
+    throw new SsrfBlockedError(`${label}: refusing to fetch loopback host "${host}"`);
+  }
+  if (isIP(host)) {
+    if (isBlockedIp(host))
+      throw new SsrfBlockedError(`${label}: refusing private/loopback address "${host}"`);
+    return null;
+  }
+  // Resolve the name and block if it maps to a private range (internal name or
+  // DNS rebinding). web_fetch fails OPEN on resolution error (its identical
+  // system resolver + pinned dispatcher mean an unresolvable name is no vector),
+  // but the BROWSER paths hand the URL to Chromium's own resolver/cache — which
+  // may resolve a name node:dns just failed on — so they pass `failClosed` to
+  // SOFT-BLOCK instead of allowing an un-vetted name through to the browser.
+  let addrs: ReadonlyArray<string>;
+  try {
+    addrs = await resolver(host);
+  } catch {
+    if (opts.failClosed) {
+      throw new SsrfBlockedError(
+        `${label}: refusing host "${host}" — DNS resolution failed (cannot vet against private ranges)`,
+      );
+    }
+    return null;
+  }
+  for (const addr of addrs) {
+    if (isBlockedIp(addr)) {
+      throw new SsrfBlockedError(
+        `${label}: host "${host}" resolves to a private/loopback address (${addr})`,
+      );
+    }
+  }
+  return addrs;
+}