@lunora/browser 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/index.d.mts

@@ -15,6 +15,23 @@ interface BrowserBindingLike {
   readonly fetch?: (...args: never[]) => unknown;
 }
 /**
+* Minimal projection of a Playwright `Route` (the argument the `page.route`
+* handler receives). Only the members the SSRF redirect guard drives are
+* declared: inspect the intercepted request's URL / navigation-ness, then either
+* let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
+*/
+interface RouteLike {
+  /** Reject the intercepted request (fail-closed); `errorCode` is a Playwright abort reason. */
+  abort: (errorCode?: string) => Promise<void>;
+  /** Allow the intercepted request to proceed. */
+  continue: () => Promise<void>;
+  /** The intercepted request: its URL and (when available) whether it is a top-level navigation. */
+  request: () => {
+    isNavigationRequest?: () => boolean;
+    url: () => string;
+  };
+}
+/**
 * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
 * Declared structurally so a test can inject a plain stub instead of a real
 * headless page (which needs workerd + the Browser Rendering binding).
@@ -31,6 +48,13 @@ interface PageLike {
   }) => Promise<unknown>;
   /** Render the page to a PDF buffer. */
   pdf: (options?: Record<string, unknown>) => Promise<Uint8Array>;
+  /**
+  * Register a request interceptor (Playwright `page.route`). Optional: a fake
+  * or older page double without it still works — the SSRF redirect guard only
+  * activates when interception is available, and the initial-URL guard applies
+  * regardless. `pattern` follows Playwright's glob/URL matcher.
+  */
+  route?: (pattern: string, handler: (route: RouteLike) => unknown) => Promise<void>;
   /** Render the page to a PNG/JPEG buffer. */
   screenshot: (options?: Record<string, unknown>) => Promise<Uint8Array>;
   /** Constrain the page viewport (a hard cap so a hostile page can't pin the worker). */
@@ -109,6 +133,16 @@ interface PdfOptions extends NavigateOptions {
   };
 }
 interface LunoraBrowserOptions {
+  /**
+  * Strict host allowlist. When set (non-empty), a navigation URL is refused
+  * unless its hostname exactly matches one of these entries (case-insensitive,
+  * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
+  * that fully closes DNS rebinding: a public hostname that resolves to a
+  * private/metadata IP can still be pinned out if it isn't on the list. Set it
+  * whenever you pass client-controlled URLs to the browser. Leave it unset (the
+  * default) to keep the previous behavior (only the string-based SSRF guard).
+  */
+  allowedHosts?: string[];
   /**
   * Opt out of the SSRF guard that, by default, refuses to navigate to a
   * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
@@ -131,6 +165,18 @@ interface LunoraBrowserOptions {
   */
   launch?: BrowserLaunchLike;
   /**
+  * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
+  * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
+  * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
+  * resolved A/AAAA record is a private/internal address — closing the gap
+  * where a public hostname resolves to a private IP after the string guard
+  * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
+  * (the browser re-resolves independently). If the DoH lookup itself fails, it
+  * falls back to the string guard rather than allowing a resolved private IP.
+  * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
+  */
+  resolveDns?: boolean;
+  /**
   * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
   * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
   */

package/dist/index.d.ts

@@ -15,6 +15,23 @@ interface BrowserBindingLike {
   readonly fetch?: (...args: never[]) => unknown;
 }
 /**
+* Minimal projection of a Playwright `Route` (the argument the `page.route`
+* handler receives). Only the members the SSRF redirect guard drives are
+* declared: inspect the intercepted request's URL / navigation-ness, then either
+* let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
+*/
+interface RouteLike {
+  /** Reject the intercepted request (fail-closed); `errorCode` is a Playwright abort reason. */
+  abort: (errorCode?: string) => Promise<void>;
+  /** Allow the intercepted request to proceed. */
+  continue: () => Promise<void>;
+  /** The intercepted request: its URL and (when available) whether it is a top-level navigation. */
+  request: () => {
+    isNavigationRequest?: () => boolean;
+    url: () => string;
+  };
+}
+/**
 * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
 * Declared structurally so a test can inject a plain stub instead of a real
 * headless page (which needs workerd + the Browser Rendering binding).
@@ -31,6 +48,13 @@ interface PageLike {
   }) => Promise<unknown>;
   /** Render the page to a PDF buffer. */
   pdf: (options?: Record<string, unknown>) => Promise<Uint8Array>;
+  /**
+  * Register a request interceptor (Playwright `page.route`). Optional: a fake
+  * or older page double without it still works — the SSRF redirect guard only
+  * activates when interception is available, and the initial-URL guard applies
+  * regardless. `pattern` follows Playwright's glob/URL matcher.
+  */
+  route?: (pattern: string, handler: (route: RouteLike) => unknown) => Promise<void>;
   /** Render the page to a PNG/JPEG buffer. */
   screenshot: (options?: Record<string, unknown>) => Promise<Uint8Array>;
   /** Constrain the page viewport (a hard cap so a hostile page can't pin the worker). */
@@ -109,6 +133,16 @@ interface PdfOptions extends NavigateOptions {
   };
 }
 interface LunoraBrowserOptions {
+  /**
+  * Strict host allowlist. When set (non-empty), a navigation URL is refused
+  * unless its hostname exactly matches one of these entries (case-insensitive,
+  * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
+  * that fully closes DNS rebinding: a public hostname that resolves to a
+  * private/metadata IP can still be pinned out if it isn't on the list. Set it
+  * whenever you pass client-controlled URLs to the browser. Leave it unset (the
+  * default) to keep the previous behavior (only the string-based SSRF guard).
+  */
+  allowedHosts?: string[];
   /**
   * Opt out of the SSRF guard that, by default, refuses to navigate to a
   * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
@@ -131,6 +165,18 @@ interface LunoraBrowserOptions {
   */
   launch?: BrowserLaunchLike;
   /**
+  * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
+  * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
+  * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
+  * resolved A/AAAA record is a private/internal address — closing the gap
+  * where a public hostname resolves to a private IP after the string guard
+  * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
+  * (the browser re-resolves independently). If the DoH lookup itself fails, it
+  * falls back to the string guard rather than allowing a resolved private IP.
+  * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
+  */
+  resolveDns?: boolean;
+  /**
   * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
   * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
   */

package/dist/index.mjs

@@ -1 +1 @@
-export { createBrowser } from './packem_shared/createBrowser-6RQ-H1k9.mjs';
+export { createBrowser } from './packem_shared/createBrowser-BaV8oQ-4.mjs';

package/dist/packem_shared/{createBrowser-6RQ-H1k9.mjs → createBrowser-BaV8oQ-4.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const DEFAULT_TIMEOUT_MS = 3e4;
 const MAX_TIMEOUT_MS = 12e4;
 const MAX_VIEWPORT_WIDTH = 3840;
@@ -9,6 +11,7 @@ const IPV6_COMPATIBLE_DOTTED = /^::(\d{1,3}(?:\.\d{1,3}){3})$/;
 const IPV6_COMPATIBLE_HEX = /^::([\da-f]{1,4}):([\da-f]{1,4})$/;
 const IPV6_NAT64_HEX = /^64:ff9b::[\da-f]{1,4}:[\da-f]{1,4}$/;
 const IPV6_BRACKETS = /^\[|\]$/g;
+const TRAILING_DOT = /\.$/;
 const parseIpv4 = (host) => {
   const parts = host.split(".");
   if (parts.length !== 4) {
@@ -67,33 +70,88 @@ const isPrivateIpv6 = (host) => {
   ip.startsWith("fe8") || // fe80::/10 link-local
   ip.startsWith("fe9") || ip.startsWith("fea") || ip.startsWith("feb");
 };
+const DOH_ENDPOINT = "https://cloudflare-dns.com/dns-query";
+const DOH_TIMEOUT_MS = 5e3;
+const DNS_TYPE_A = 1;
+const DNS_TYPE_AAAA = 28;
+const normalizeHost = (host) => host.replaceAll(IPV6_BRACKETS, "").replace(TRAILING_DOT, "").toLowerCase();
+const isPrivateResolvedIp = (data, type) => {
+  if (type === DNS_TYPE_A) {
+    const v4 = parseIpv4(data);
+    return v4 === void 0 || isPrivateIpv4(v4);
+  }
+  return isPrivateIpv6(data.toLowerCase());
+};
+const dohLookup = async (hostname, type, timeoutMs = DOH_TIMEOUT_MS) => {
+  try {
+    const response = await fetch(`${DOH_ENDPOINT}?name=${encodeURIComponent(hostname)}&type=${String(type)}`, {
+      headers: { accept: "application/dns-json" },
+      // Bound the lookup so a stalled resolver can't hang the worker; an
+      // abort surfaces as a rejection caught below → `undefined` → the
+      // caller falls back to the (already-passed) string guard.
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+      return void 0;
+    }
+    const body = await response.json();
+    return body.Answer ?? [];
+  } catch {
+    return void 0;
+  }
+};
+const assertResolvedHostIsPublic = async (target, timeoutMs = DOH_TIMEOUT_MS) => {
+  const host = normalizeHost(new URL(target).hostname);
+  if (host.includes(":") || parseIpv4(host) !== void 0) {
+    return;
+  }
+  const [aRecords, aaaaRecords] = await Promise.all([dohLookup(host, DNS_TYPE_A, timeoutMs), dohLookup(host, DNS_TYPE_AAAA, timeoutMs)]);
+  if (aRecords === void 0 && aaaaRecords === void 0) {
+    return;
+  }
+  for (const answer of [...aRecords ?? [], ...aaaaRecords ?? []]) {
+    if ((answer.type === DNS_TYPE_A || answer.type === DNS_TYPE_AAAA) && isPrivateResolvedIp(answer.data, answer.type)) {
+      throw new LunoraError(
+        "FORBIDDEN",
+        `@lunora/browser: url host "${host}" resolves to a private/internal address (${answer.data}); refusing to navigate (DNS-rebinding guard)`
+      );
+    }
+  }
+};
 const isPrivateHostname = (host) => host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".home.arpa");
 const isPrivateTarget = (parsed) => {
-  const host = parsed.hostname.replaceAll(IPV6_BRACKETS, "");
+  const host = parsed.hostname.replaceAll(IPV6_BRACKETS, "").replace(TRAILING_DOT, "");
   if (host.includes(":")) {
     return isPrivateIpv6(host);
   }
   const v4 = parseIpv4(host);
   return v4 === void 0 ? isPrivateHostname(host.toLowerCase()) : isPrivateIpv4(v4);
 };
-const validateUrl = (url, allowPrivateTargets) => {
+const validateUrl = (url, allowPrivateTargets, allowedHosts) => {
   if (typeof url !== "string" || url.length === 0) {
-    throw new Error("@lunora/browser: url must be a non-empty string");
+    throw new TypeError("@lunora/browser: url must be a non-empty string");
   }
   let parsed;
   try {
     parsed = new URL(url);
   } catch {
-    throw new Error(`@lunora/browser: url must be an absolute http(s) URL (got "${url}")`);
+    throw new TypeError(`@lunora/browser: url must be an absolute http(s) URL (got "${url}")`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`@lunora/browser: url protocol must be http(s) (got "${parsed.protocol}")`);
+    throw new TypeError(`@lunora/browser: url protocol must be http(s) (got "${parsed.protocol}")`);
   }
   if (parsed.username !== "" || parsed.password !== "") {
-    throw new Error("@lunora/browser: url must not embed credentials (strip the `user:pass@` userinfo)");
+    throw new LunoraError("INTERNAL", "@lunora/browser: url must not embed credentials (strip the `user:pass@` userinfo)");
+  }
+  if (allowedHosts && allowedHosts.length > 0) {
+    const host = normalizeHost(parsed.hostname);
+    if (!allowedHosts.some((entry) => normalizeHost(entry) === host)) {
+      throw new LunoraError("FORBIDDEN", `@lunora/browser: url host "${parsed.hostname}" is not in the configured allowedHosts allowlist`);
+    }
   }
   if (!allowPrivateTargets && isPrivateTarget(parsed)) {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `@lunora/browser: url host "${parsed.hostname}" is a private/internal address; pass createBrowser({ …, allowPrivateTargets: true }) to allow it`
     );
   }
@@ -118,11 +176,12 @@ const resolveTimeout = (callTimeout, factoryTimeout) => {
 };
 const createBrowser = (options) => {
   if (!options.binding) {
-    throw new Error("@lunora/browser: `binding` is required (env.BROWSER)");
+    throw new TypeError("@lunora/browser: `binding` is required (env.BROWSER)");
   }
   const getLaunch = () => {
     if (!options.launch) {
-      throw new Error(
+      throw new LunoraError(
+        "INTERNAL",
         '@lunora/browser: `launch` is not available — install the `@cloudflare/playwright` peer dependency. The generated worker wires it for you; outside codegen pass it via createBrowser({ binding, launch }) (import { launch } from "@cloudflare/playwright").'
       );
     }
@@ -140,11 +199,40 @@ const createBrowser = (options) => {
     }
   };
   const withPage = async (url, navigate, use, viewport) => {
-    const target = validateUrl(url, options.allowPrivateTargets ?? false);
+    const allowPrivateTargets = options.allowPrivateTargets ?? false;
+    const target = validateUrl(url, allowPrivateTargets, options.allowedHosts);
     const timeout = resolveTimeout(navigate.timeoutMs, options.timeoutMs);
+    const resolveDns = options.resolveDns ?? false;
+    const dohTimeout = Math.min(timeout, DOH_TIMEOUT_MS);
+    if (!allowPrivateTargets && resolveDns) {
+      await assertResolvedHostIsPublic(target, dohTimeout);
+    }
+    const assertNavigationAllowed = async (requestUrl) => {
+      validateUrl(requestUrl, allowPrivateTargets, options.allowedHosts);
+      if (resolveDns) {
+        await assertResolvedHostIsPublic(requestUrl, dohTimeout);
+      }
+    };
     return withBrowser(async (browser) => {
       const context = await browser.newContext();
       const page = await context.newPage();
+      if (!allowPrivateTargets && page.route) {
+        await page.route("**/*", async (route) => {
+          const request = route.request();
+          const isNavigation = request.isNavigationRequest?.() ?? true;
+          if (!isNavigation) {
+            await route.continue();
+            return;
+          }
+          try {
+            await assertNavigationAllowed(request.url());
+          } catch {
+            await route.abort("blockedbyclient");
+            return;
+          }
+          await route.continue();
+        });
+      }
       if (viewport && page.setViewportSize) {
         await page.setViewportSize(clampViewport(viewport));
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/browser",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Cloudflare Browser Rendering for Lunora: ctx.browser screenshots, PDF, and scraping in actions",
   "keywords": [
     "browser-rendering",
@@ -45,6 +45,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@lunora/errors": "1.0.0-alpha.1"
+  },
   "peerDependencies": {
     "@cloudflare/playwright": ">=1.0.0"
   },