@lunora/browser 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -1,24 +1,45 @@
 /**
-* Structural projection of the Cloudflare **Browser Rendering** binding
-* (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
-* drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
-* marker) so unit tests can pass a plain-object double and the real binding
-* satisfies the same shape without importing `@cloudflare/workers-types` into
-* the public surface. See https://developers.cloudflare.com/browser-rendering/.
-*
-* It is intentionally opaque: callers never touch the binding directly, they
-* hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
-* consumes it. Typed as a non-empty marker so an arbitrary value (e.g. `{}`)
-* doesn't silently type-check where a binding is required.
-*/
+ * Structural projection of the Cloudflare **Browser Rendering** binding
+ * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
+ * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
+ * marker) so unit tests can pass a plain-object double and the real binding
+ * satisfies the same shape without importing `@cloudflare/workers-types` into
+ * the public surface. See https://developers.cloudflare.com/browser-rendering/.
+ *
+ * It is intentionally opaque: callers never touch the binding directly, they
+ * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
+ * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
+ * always has one) so the marker actually excludes an arbitrary value like `{}` —
+ * a bare object fails to type-check where a binding is required, catching the
+ * misuse at the call site instead of deferring to an opaque launch error.
+ * @experimental
+ */
 interface BrowserBindingLike {
-  readonly fetch?: (...args: never[]) => unknown;
+  readonly fetch: (...args: never[]) => unknown;
 }
 /**
-* 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).
-*/
+ * 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).
+ * @experimental
+ */
 interface PageLike {
   /** Return the page's serialized HTML after the navigation settles. */
   content: () => Promise<string>;
@@ -31,6 +52,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). */
@@ -40,132 +68,175 @@ interface PageLike {
   }) => Promise<void>;
 }
 /**
-* Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
-* declared structurally for the same test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
+ * declared structurally for the same test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserContextLike {
   newPage: () => Promise<PageLike>;
 }
 /**
-* Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
-* Only `newContext`/`close` are used; declared structurally for the same
-* test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
+ * Only `newContext`/`close` are used; declared structurally for the same
+ * test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserLike {
   close: () => Promise<void>;
   newContext: () => Promise<BrowserContextLike>;
 }
 /**
-* Structural projection of `@cloudflare/playwright`'s `launch` export
-* (`import { launch } from "@cloudflare/playwright"`). Injected via
-* {@link LunoraBrowserOptions.launch} so the factory never imports
-* `@cloudflare/playwright` at module top — that keeps the heavy optional peer
-* dep out of the bundle for apps that never screenshot, and lets tests pass a
-* fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
-*/
+ * Structural projection of `@cloudflare/playwright`'s `launch` export
+ * (`import { launch } from "@cloudflare/playwright"`). Injected via
+ * {@link LunoraBrowserOptions.launch} so the factory never imports
+ * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
+ * dep out of the bundle for apps that never screenshot, and lets tests pass a
+ * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
+ * @experimental
+ */
 type BrowserLaunchLike = (binding: BrowserBindingLike, options?: Record<string, unknown>) => Promise<BrowserLike>;
-/** Options shared by the page-driving helpers ({@link Browser.screenshot} etc.). */
+/**
+ * Options shared by the page-driving helpers ({@link Browser.screenshot} etc.).
+ * @experimental
+ */
 interface NavigateOptions {
   /**
-  * Hard timeout in milliseconds for the navigation + operation. Clamped to a
-  * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
-  */
+   * Hard timeout in milliseconds for the navigation + operation. Clamped to a
+   * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
+   */
   timeoutMs?: number;
   /**
-  * Playwright navigation wait condition. Playwright's set differs from
-  * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
-  * Default `load`.
-  */
+   * Playwright navigation wait condition. Playwright's set differs from
+   * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
+   * Default `load`.
+   */
   waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
 }
-/** Options for {@link Browser.screenshot}. */
+/**
+ * Options for {@link Browser.screenshot}.
+ * @experimental
+ */
 interface ScreenshotOptions extends NavigateOptions {
   /** Capture the full scrollable page rather than just the viewport. */
   fullPage?: boolean;
   /** Image encoding. Default `png`. */
   type?: "jpeg" | "png";
   /**
-  * Viewport size. Each dimension is hard-capped (see the factory's
-  * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
-  */
+   * Viewport size. Each dimension is hard-capped (see the factory's
+   * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
-/** Options for {@link Browser.pdf}. */
+/**
+ * Options for {@link Browser.pdf}.
+ * @experimental
+ */
 interface PdfOptions extends NavigateOptions {
   /** Paper format (`A4`, `Letter`, …) forwarded to Playwright. */
   format?: string;
   /** Print background graphics. Default `false`. */
   printBackground?: boolean;
   /**
-  * Viewport used while laying out the page before printing. Hard-capped like
-  * {@link ScreenshotOptions.viewport}.
-  */
+   * Viewport used while laying out the page before printing. Hard-capped like
+   * {@link ScreenshotOptions.viewport}.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
+/**
+ * `LunoraBrowserOptions` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 interface LunoraBrowserOptions {
   /**
-  * 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`,
-  * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
-  * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
-  * `false` (the default) unless every caller-supplied URL is trusted — e.g.
-  * you deliberately drive the browser at an internal service reachable through
-  * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
-  * the SSRF surface, so never combine it with caller-controlled URLs.
-  */
+   * 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`,
+   * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
+   * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
+   * `false` (the default) unless every caller-supplied URL is trusted — e.g.
+   * you deliberately drive the browser at an internal service reachable through
+   * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
+   * the SSRF surface, so never combine it with caller-controlled URLs.
+   */
   allowPrivateTargets?: boolean;
   /** The Cloudflare Browser Rendering binding (`env.BROWSER`). Required. */
   binding: BrowserBindingLike;
   /**
-  * The `@cloudflare/playwright` `launch` function. Injected rather than
-  * imported at module top so the optional peer dep stays out of the bundle
-  * for non-browser apps and tests can pass a double. The generated worker
-  * passes the real function; omitting it makes the helper throw on first use
-  * with a clear "install `@cloudflare/playwright`" error.
-  */
+   * The `@cloudflare/playwright` `launch` function. Injected rather than
+   * imported at module top so the optional peer dep stays out of the bundle
+   * for non-browser apps and tests can pass a double. The generated worker
+   * passes the real function; omitting it makes the helper throw on first use
+   * with a clear "install `@cloudflare/playwright`" error.
+   */
   launch?: BrowserLaunchLike;
   /**
-  * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
-  * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
-  */
+   * 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.
+   */
   timeoutMs?: number;
 }
 /**
-* The `ctx.browser` surface — Cloudflare Browser Rendering driven through
-* `@cloudflare/playwright`. **Action-only**: every method performs
-* non-deterministic network I/O (it navigates a real headless browser to a
-* URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
-* `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
-* browser, opens a context + page, navigates, performs the op, and always
-* closes the browser in a `finally` (a leaked session is billed and
-* rate-limited).
-*/
+ * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
+ * `@cloudflare/playwright`. **Action-only**: every method performs
+ * non-deterministic network I/O (it navigates a real headless browser to a
+ * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
+ * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
+ * browser, opens a context + page, navigates, performs the op, and always
+ * closes the browser in a `finally` (a leaked session is billed and
+ * rate-limited).
+ * @experimental
+ */
 interface Browser {
   /** Serialized HTML of `url` after navigation settles. */
   content: (url: string, options?: NavigateOptions) => Promise<string>;
   /**
-  * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
-  * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
-  * **always closed** when `fn` resolves or throws — do not retain references
-  * to it past the callback.
-  */
+   * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
+   * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
+   * **always closed** when `fn` resolves or throws — do not retain references
+   * to it past the callback.
+   */
   launch: <T>(function_: (browser: BrowserLike) => Promise<T>) => Promise<T>;
   /** Render `url` to a PDF buffer. */
   pdf: (url: string, options?: PdfOptions) => Promise<Uint8Array>;
   /**
-  * Navigate to `url`, run `fn` inside the page context, and return its
-  * (serializable) result. `fn` runs in the browser, not the worker — it
-  * cannot close over worker-side variables.
-  */
+   * Navigate to `url`, run `fn` inside the page context, and return its
+   * (serializable) result. `fn` runs in the browser, not the worker — it
+   * cannot close over worker-side variables.
+   */
   scrape: <T>(url: string, function_: (...args: never[]) => T, options?: NavigateOptions) => Promise<T>;
   /** Render `url` to an image buffer (PNG by default). */
   screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
 }
+/**
+ * `createBrowser` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 declare const createBrowser: (options: LunoraBrowserOptions) => Browser;
 export { type Browser, type BrowserBindingLike, type BrowserContextLike, type BrowserLaunchLike, type BrowserLike, type LunoraBrowserOptions, type NavigateOptions, type PageLike, type PdfOptions, type ScreenshotOptions, createBrowser };

package/dist/index.d.ts

@@ -1,24 +1,45 @@
 /**
-* Structural projection of the Cloudflare **Browser Rendering** binding
-* (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
-* drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
-* marker) so unit tests can pass a plain-object double and the real binding
-* satisfies the same shape without importing `@cloudflare/workers-types` into
-* the public surface. See https://developers.cloudflare.com/browser-rendering/.
-*
-* It is intentionally opaque: callers never touch the binding directly, they
-* hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
-* consumes it. Typed as a non-empty marker so an arbitrary value (e.g. `{}`)
-* doesn't silently type-check where a binding is required.
-*/
+ * Structural projection of the Cloudflare **Browser Rendering** binding
+ * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
+ * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
+ * marker) so unit tests can pass a plain-object double and the real binding
+ * satisfies the same shape without importing `@cloudflare/workers-types` into
+ * the public surface. See https://developers.cloudflare.com/browser-rendering/.
+ *
+ * It is intentionally opaque: callers never touch the binding directly, they
+ * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
+ * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
+ * always has one) so the marker actually excludes an arbitrary value like `{}` —
+ * a bare object fails to type-check where a binding is required, catching the
+ * misuse at the call site instead of deferring to an opaque launch error.
+ * @experimental
+ */
 interface BrowserBindingLike {
-  readonly fetch?: (...args: never[]) => unknown;
+  readonly fetch: (...args: never[]) => unknown;
 }
 /**
-* 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).
-*/
+ * 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).
+ * @experimental
+ */
 interface PageLike {
   /** Return the page's serialized HTML after the navigation settles. */
   content: () => Promise<string>;
@@ -31,6 +52,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). */
@@ -40,132 +68,175 @@ interface PageLike {
   }) => Promise<void>;
 }
 /**
-* Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
-* declared structurally for the same test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
+ * declared structurally for the same test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserContextLike {
   newPage: () => Promise<PageLike>;
 }
 /**
-* Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
-* Only `newContext`/`close` are used; declared structurally for the same
-* test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
+ * Only `newContext`/`close` are used; declared structurally for the same
+ * test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserLike {
   close: () => Promise<void>;
   newContext: () => Promise<BrowserContextLike>;
 }
 /**
-* Structural projection of `@cloudflare/playwright`'s `launch` export
-* (`import { launch } from "@cloudflare/playwright"`). Injected via
-* {@link LunoraBrowserOptions.launch} so the factory never imports
-* `@cloudflare/playwright` at module top — that keeps the heavy optional peer
-* dep out of the bundle for apps that never screenshot, and lets tests pass a
-* fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
-*/
+ * Structural projection of `@cloudflare/playwright`'s `launch` export
+ * (`import { launch } from "@cloudflare/playwright"`). Injected via
+ * {@link LunoraBrowserOptions.launch} so the factory never imports
+ * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
+ * dep out of the bundle for apps that never screenshot, and lets tests pass a
+ * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
+ * @experimental
+ */
 type BrowserLaunchLike = (binding: BrowserBindingLike, options?: Record<string, unknown>) => Promise<BrowserLike>;
-/** Options shared by the page-driving helpers ({@link Browser.screenshot} etc.). */
+/**
+ * Options shared by the page-driving helpers ({@link Browser.screenshot} etc.).
+ * @experimental
+ */
 interface NavigateOptions {
   /**
-  * Hard timeout in milliseconds for the navigation + operation. Clamped to a
-  * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
-  */
+   * Hard timeout in milliseconds for the navigation + operation. Clamped to a
+   * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
+   */
   timeoutMs?: number;
   /**
-  * Playwright navigation wait condition. Playwright's set differs from
-  * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
-  * Default `load`.
-  */
+   * Playwright navigation wait condition. Playwright's set differs from
+   * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
+   * Default `load`.
+   */
   waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
 }
-/** Options for {@link Browser.screenshot}. */
+/**
+ * Options for {@link Browser.screenshot}.
+ * @experimental
+ */
 interface ScreenshotOptions extends NavigateOptions {
   /** Capture the full scrollable page rather than just the viewport. */
   fullPage?: boolean;
   /** Image encoding. Default `png`. */
   type?: "jpeg" | "png";
   /**
-  * Viewport size. Each dimension is hard-capped (see the factory's
-  * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
-  */
+   * Viewport size. Each dimension is hard-capped (see the factory's
+   * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
-/** Options for {@link Browser.pdf}. */
+/**
+ * Options for {@link Browser.pdf}.
+ * @experimental
+ */
 interface PdfOptions extends NavigateOptions {
   /** Paper format (`A4`, `Letter`, …) forwarded to Playwright. */
   format?: string;
   /** Print background graphics. Default `false`. */
   printBackground?: boolean;
   /**
-  * Viewport used while laying out the page before printing. Hard-capped like
-  * {@link ScreenshotOptions.viewport}.
-  */
+   * Viewport used while laying out the page before printing. Hard-capped like
+   * {@link ScreenshotOptions.viewport}.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
+/**
+ * `LunoraBrowserOptions` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 interface LunoraBrowserOptions {
   /**
-  * 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`,
-  * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
-  * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
-  * `false` (the default) unless every caller-supplied URL is trusted — e.g.
-  * you deliberately drive the browser at an internal service reachable through
-  * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
-  * the SSRF surface, so never combine it with caller-controlled URLs.
-  */
+   * 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`,
+   * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
+   * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
+   * `false` (the default) unless every caller-supplied URL is trusted — e.g.
+   * you deliberately drive the browser at an internal service reachable through
+   * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
+   * the SSRF surface, so never combine it with caller-controlled URLs.
+   */
   allowPrivateTargets?: boolean;
   /** The Cloudflare Browser Rendering binding (`env.BROWSER`). Required. */
   binding: BrowserBindingLike;
   /**
-  * The `@cloudflare/playwright` `launch` function. Injected rather than
-  * imported at module top so the optional peer dep stays out of the bundle
-  * for non-browser apps and tests can pass a double. The generated worker
-  * passes the real function; omitting it makes the helper throw on first use
-  * with a clear "install `@cloudflare/playwright`" error.
-  */
+   * The `@cloudflare/playwright` `launch` function. Injected rather than
+   * imported at module top so the optional peer dep stays out of the bundle
+   * for non-browser apps and tests can pass a double. The generated worker
+   * passes the real function; omitting it makes the helper throw on first use
+   * with a clear "install `@cloudflare/playwright`" error.
+   */
   launch?: BrowserLaunchLike;
   /**
-  * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
-  * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
-  */
+   * 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.
+   */
   timeoutMs?: number;
 }
 /**
-* The `ctx.browser` surface — Cloudflare Browser Rendering driven through
-* `@cloudflare/playwright`. **Action-only**: every method performs
-* non-deterministic network I/O (it navigates a real headless browser to a
-* URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
-* `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
-* browser, opens a context + page, navigates, performs the op, and always
-* closes the browser in a `finally` (a leaked session is billed and
-* rate-limited).
-*/
+ * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
+ * `@cloudflare/playwright`. **Action-only**: every method performs
+ * non-deterministic network I/O (it navigates a real headless browser to a
+ * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
+ * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
+ * browser, opens a context + page, navigates, performs the op, and always
+ * closes the browser in a `finally` (a leaked session is billed and
+ * rate-limited).
+ * @experimental
+ */
 interface Browser {
   /** Serialized HTML of `url` after navigation settles. */
   content: (url: string, options?: NavigateOptions) => Promise<string>;
   /**
-  * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
-  * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
-  * **always closed** when `fn` resolves or throws — do not retain references
-  * to it past the callback.
-  */
+   * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
+   * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
+   * **always closed** when `fn` resolves or throws — do not retain references
+   * to it past the callback.
+   */
   launch: <T>(function_: (browser: BrowserLike) => Promise<T>) => Promise<T>;
   /** Render `url` to a PDF buffer. */
   pdf: (url: string, options?: PdfOptions) => Promise<Uint8Array>;
   /**
-  * Navigate to `url`, run `fn` inside the page context, and return its
-  * (serializable) result. `fn` runs in the browser, not the worker — it
-  * cannot close over worker-side variables.
-  */
+   * Navigate to `url`, run `fn` inside the page context, and return its
+   * (serializable) result. `fn` runs in the browser, not the worker — it
+   * cannot close over worker-side variables.
+   */
   scrape: <T>(url: string, function_: (...args: never[]) => T, options?: NavigateOptions) => Promise<T>;
   /** Render `url` to an image buffer (PNG by default). */
   screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
 }
+/**
+ * `createBrowser` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 declare const createBrowser: (options: LunoraBrowserOptions) => Browser;
 export { type Browser, type BrowserBindingLike, type BrowserContextLike, type BrowserLaunchLike, type BrowserLike, type LunoraBrowserOptions, type NavigateOptions, type PageLike, type PdfOptions, type ScreenshotOptions, createBrowser };

package/dist/index.mjs

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