@moxxy/plugin-browser 0.27.0

package/dist/sidecar/types.d.ts

@@ -0,0 +1,97 @@
+export type BrowserKind = 'chromium' | 'firefox' | 'webkit';
+export type ErrorKind = 'init' | 'needs-install' | '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>;
+    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 {
+    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 declare function errMsg(err: unknown): string;
+/**
+ * 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 declare class SidecarError extends Error {
+    readonly kind: ErrorKind;
+    constructor(message: string, kind: ErrorKind);
+}
+export declare function badParams(msg: string): SidecarError;
+//# sourceMappingURL=types.d.ts.map

package/dist/sidecar/types.d.ts.map

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

package/dist/sidecar/types.js

@@ -0,0 +1,20 @@
+export function errMsg(err) {
+    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 {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = 'SidecarError';
+    }
+}
+export function badParams(msg) {
+    return new SidecarError(msg, 'runtime');
+}
+//# sourceMappingURL=types.js.map

package/dist/sidecar/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sidecar/types.ts"],"names":[],"mappings":"AA4FA,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAG1B;IAFX,YACE,OAAe,EACN,IAAe;QAExB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,SAAI,GAAJ,IAAI,CAAW;QAGxB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,IAAI,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AAC1C,CAAC"}

package/dist/sidecar.d.ts

@@ -0,0 +1,31 @@
+#!/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 { type Reply } from './sidecar/types.js';
+/**
+ * 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 declare function enqueueLine(line: string, out: (reply: Reply) => void): Promise<void>;
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAU,KAAK,KAAK,EAAY,MAAM,oBAAoB,CAAC;AAoElE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCpF"}

package/dist/sidecar.js

@@ -0,0 +1,165 @@
+#!/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 } from './sidecar/dispatch.js';
+import { errMsg } from './sidecar/types.js';
+const state = { handle: null, pendingInstallNotice: null };
+function write(reply) {
+    // 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) {
+    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() {
+    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.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.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, out) {
+    if (!line.trim())
+        return queue;
+    let req;
+    try {
+        req = JSON.parse(line);
+    }
+    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() {
+    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.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);
+    });
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

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

package/dist/ssrf-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 declare class SsrfBlockedError extends Error {
+    constructor(message: string);
+}
+export type DnsResolver = (host: string) => Promise<ReadonlyArray<string>>;
+/** Test seam: override DNS resolution so SSRF tests stay hermetic. Pass null to reset. */
+export declare function setSsrfDnsResolver(fn: DnsResolver | null): void;
+export declare function isBlockedIp(ip: string): boolean;
+/**
+ * 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 declare function assertPublicUrl(raw: string, label?: string, opts?: {
+    failClosed?: boolean;
+}): Promise<ReadonlyArray<string> | null>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../src/ssrf-guard.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,+FAA+F;AAC/F,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;AAK3E,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAE/D;AA0DD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,KAAK,SAAY,EACjB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CA4CvC"}

package/dist/ssrf-guard.js

@@ -0,0 +1,164 @@
+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) {
+        super(message);
+        this.name = 'SsrfBlockedError';
+    }
+}
+const defaultResolver = async (host) => (await dnsLookup(host, { all: true })).map((a) => a.address);
+let resolver = defaultResolver;
+/** Test seam: override DNS resolution so SSRF tests stay hermetic. Pass null to reset. */
+export function setSsrfDnsResolver(fn) {
+    resolver = fn ?? defaultResolver;
+}
+function isBlockedIpv4(ip) {
+    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;
+    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) {
+    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) {
+    // 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) {
+    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, label = 'request', opts = {}) {
+    let u;
+    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;
+    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;
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/ssrf-guard.js.map

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

package/dist/web-fetch.d.ts

@@ -0,0 +1,23 @@
+import type { LookupFunction } from 'node:net';
+import { type DnsResolver } from './ssrf-guard.js';
+/**
+ * Light-tier web fetch: a single HTTP GET (or HEAD) with HTML→text/markdown
+ * post-processing for the common case of "read this page". Zero new
+ * dependencies — uses Node's built-in `fetch`.
+ *
+ * For JS-heavy / interactive pages, use `browser_session` (Playwright
+ * sidecar) instead. The web-research skill picks the tier.
+ */
+export { htmlToMarkdown, htmlToPlainText } from './html-extract.js';
+export type { DnsResolver } from './ssrf-guard.js';
+/** Test seam: override DNS resolution so SSRF tests stay hermetic. Pass null to reset. */
+export declare function setWebFetchDnsResolver(fn: DnsResolver | null): void;
+/**
+ * DNS-rebinding (TOCTOU) defense: a lookup function that always answers with
+ * the addresses the SSRF guard just vetted, so the connection provably goes
+ * to the IP that was checked — a second, attacker-controlled DNS answer
+ * between check and connect can never be consulted. Exported for tests.
+ */
+export declare function createPinnedLookup(addresses: ReadonlyArray<string>): LookupFunction;
+export declare const webFetchTool: import("@moxxy/sdk").ToolDef;
+//# sourceMappingURL=web-fetch.d.ts.map

package/dist/web-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../src/web-fetch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI/C,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAcpE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,0FAA0F;AAC1F,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEnE;AAmBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,cAAc,CAwBnF;AAOD,eAAO,MAAM,YAAY,8BAsFvB,CAAC"}