@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/browser/src/network.ts

@@ -0,0 +1,263 @@
+/**
+ * Browser egress policy and Playwright context routing (defense in depth).
+ * Production DNS/private egress containment remains a host firewall/proxy.
+ */
+import { BrowserError } from "./errors.js";
+import type { ResolvedBrowserLimits } from "./limits.js";
+import type { PlaywrightBrowserContext, PlaywrightRoute } from "./types.js";
+
+export type BrowserUrlDecision =
+  | { readonly allowed: true; readonly url: URL; readonly kind: "http" | "https" | "ws" | "wss" }
+  | { readonly allowed: false; readonly reason: string };
+
+export interface BrowserNetworkPolicy {
+  /**
+   * When true, external browsing requires `containedProxyAttestation`.
+   * Without attestation every non-blank request is aborted (fail closed).
+   */
+  readonly requireContainedProxy?: boolean;
+  /**
+   * Host attestation that real egress is forced through an isolated proxy/firewall.
+   * Playwright routing alone is never treated as DNS containment.
+   */
+  readonly containedProxyAttestation?: {
+    readonly proxyEndpoint: string;
+    readonly denyDirectEgress: true;
+  };
+  /** Allow loopback destinations (default false). */
+  readonly allowLoopback?: boolean;
+  /** Allow private/link-local/ULA destinations (default false). */
+  readonly allowPrivateHosts?: boolean;
+  /** Optional host callback consulted after scheme/host checks. */
+  readonly validateUrl?: (url: URL) => boolean | Promise<boolean>;
+}
+
+export interface NetworkBudget {
+  requestCount: number;
+  webSocketCount: number;
+  readonly redirects: Map<string, number>;
+}
+
+export function createNetworkBudget(): NetworkBudget {
+  return { requestCount: 0, webSocketCount: 0, redirects: new Map() };
+}
+
+const BLOCKED_SCHEMES = new Set([
+  "file:",
+  "data:",
+  "blob:",
+  "javascript:",
+  "chrome:",
+  "chrome-devtools:",
+  "chrome-extension:",
+  "devtools:",
+  "view-source:",
+]);
+
+export function classifyBrowserUrl(raw: string, policy: BrowserNetworkPolicy = {}): BrowserUrlDecision {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { allowed: false, reason: "url is not absolute" };
+  }
+
+  if (url.protocol === "about:") {
+    if (url.pathname === "blank" || url.href === "about:blank") {
+      return { allowed: false, reason: "about:blank is not a navigable egress target" };
+    }
+    return { allowed: false, reason: `scheme ${url.protocol} is blocked` };
+  }
+
+  if (BLOCKED_SCHEMES.has(url.protocol)) {
+    return { allowed: false, reason: `scheme ${url.protocol} is blocked` };
+  }
+
+  const kind =
+    url.protocol === "http:"
+      ? "http"
+      : url.protocol === "https:"
+        ? "https"
+        : url.protocol === "ws:"
+          ? "ws"
+          : url.protocol === "wss:"
+            ? "wss"
+            : undefined;
+  if (!kind) {
+    return { allowed: false, reason: `unsupported scheme ${url.protocol}` };
+  }
+
+  if (url.username || url.password) {
+    return { allowed: false, reason: "url userinfo is not allowed" };
+  }
+
+  const hostClass = classifyHost(url.hostname);
+  if (hostClass === "loopback" && !policy.allowLoopback) {
+    return { allowed: false, reason: "loopback destinations are denied by default" };
+  }
+  if ((hostClass === "private" || hostClass === "link-local" || hostClass === "ula") && !policy.allowPrivateHosts) {
+    return { allowed: false, reason: "private/link-local destinations are denied by default" };
+  }
+
+  if (policy.requireContainedProxy !== false) {
+    const attestation = policy.containedProxyAttestation;
+    if (attestation?.denyDirectEgress !== true || !attestation.proxyEndpoint) {
+      return {
+        allowed: false,
+        reason: "contained proxy attestation required for external browser egress",
+      };
+    }
+    try {
+      const proxy = new URL(attestation.proxyEndpoint);
+      if (proxy.protocol !== "http:" && proxy.protocol !== "https:" && proxy.protocol !== "socks5:") {
+        return { allowed: false, reason: "proxyEndpoint must be http(s) or socks5" };
+      }
+    } catch {
+      return { allowed: false, reason: "proxyEndpoint is not a valid URL" };
+    }
+  }
+
+  return { allowed: true, url, kind };
+}
+
+export function classifyHost(hostname: string): "public" | "loopback" | "private" | "link-local" | "ula" | "invalid" {
+  const host = hostname
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "");
+  if (!host) return "invalid";
+  if (host === "localhost" || host.endsWith(".localhost")) return "loopback";
+  if (host === "0.0.0.0" || host === "::" || host === "0:0:0:0:0:0:0:0") return "loopback";
+
+  if (isIpv4(host)) {
+    const parts = host.split(".").map((p) => Number(p));
+    const [a, b] = parts;
+    if (a === 127) return "loopback";
+    if (a === 10) return "private";
+    if (a === 172 && b !== undefined && b >= 16 && b <= 31) return "private";
+    if (a === 192 && b === 168) return "private";
+    if (a === 169 && b === 254) return "link-local";
+    if (a === 100 && b !== undefined && b >= 64 && b <= 127) return "private"; // CGNAT
+    if (a !== undefined && a >= 224) return "private"; // multicast/reserved treated as non-public
+    return "public";
+  }
+
+  if (host.includes(":")) {
+    if (host === "::1" || host.startsWith("::1/") || host === "0:0:0:0:0:0:0:1") return "loopback";
+    if (host.startsWith("fe80:") || host.startsWith("fe8") || host.startsWith("fe9") || host.startsWith("fea") || host.startsWith("feb")) {
+      return "link-local";
+    }
+    if (host.startsWith("fc") || host.startsWith("fd")) return "ula";
+    if (host.startsWith("ff")) return "private";
+    return "public";
+  }
+
+  // Hostnames without dots that are not localhost are still resolved by the browser;
+  // treat as public for URL classification — DNS containment remains host-owned.
+  return "public";
+}
+
+function isIpv4(host: string): boolean {
+  const parts = host.split(".");
+  if (parts.length !== 4) return false;
+  return parts.every((part) => {
+    if (!/^\d{1,3}$/.test(part)) return false;
+    const n = Number(part);
+    return n >= 0 && n <= 255;
+  });
+}
+
+export async function assertBrowserUrlAllowed(raw: string, policy: BrowserNetworkPolicy = {}): Promise<URL> {
+  const decision = classifyBrowserUrl(raw, policy);
+  if (!decision.allowed) {
+    throw new BrowserError("ERR_PRISM_BROWSER_NETWORK", decision.reason);
+  }
+  if (policy.validateUrl) {
+    const ok = await policy.validateUrl(decision.url);
+    if (!ok) {
+      throw new BrowserError("ERR_PRISM_BROWSER_NETWORK", "host validateUrl denied the URL");
+    }
+  }
+  return decision.url;
+}
+
+export interface InstallNetworkRoutingOptions {
+  readonly context: PlaywrightBrowserContext;
+  readonly policy: BrowserNetworkPolicy;
+  readonly limits: ResolvedBrowserLimits;
+  readonly budget: NetworkBudget;
+}
+
+/**
+ * Install context-wide request routing. Defense in depth only — not a DNS firewall.
+ * Requires `serviceWorkers: "block"` on the context so routes observe requests.
+ */
+export async function installNetworkRouting(options: InstallNetworkRoutingOptions): Promise<() => void> {
+  const { context, policy, limits, budget } = options;
+  if (typeof context.route !== "function") {
+    throw new BrowserError("ERR_PRISM_BROWSER", "BrowserContext.route is required for network policy enforcement");
+  }
+
+  const handler = async (route: PlaywrightRoute): Promise<void> => {
+    try {
+      const request = route.request();
+      const url = request.url();
+      // about:blank is the initial empty document — allow without charging egress budget.
+      if (url === "about:blank") {
+        await route.continue();
+        return;
+      }
+      const resourceType = typeof request.resourceType === "function" ? request.resourceType() : undefined;
+      const isWebSocket = resourceType === "websocket" || url.startsWith("ws:") || url.startsWith("wss:");
+
+      if (isWebSocket) {
+        if (budget.webSocketCount >= limits.maxWebSockets) {
+          await route.abort("blockedbyclient");
+          return;
+        }
+      } else if (budget.requestCount >= limits.maxNetworkRequests) {
+        await route.abort("blockedbyclient");
+        return;
+      }
+
+      const redirectedFrom = typeof request.redirectedFrom === "function" ? request.redirectedFrom() : null;
+      if (redirectedFrom) {
+        const key = redirectedFrom.url();
+        const count = (budget.redirects.get(key) ?? 0) + 1;
+        budget.redirects.set(key, count);
+        if (count > limits.maxRedirectsPerRequest) {
+          await route.abort("blockedbyclient");
+          return;
+        }
+      }
+
+      const decision = classifyBrowserUrl(url, policy);
+      if (!decision.allowed) {
+        await route.abort("blockedbyclient");
+        return;
+      }
+      if (policy.validateUrl) {
+        const ok = await policy.validateUrl(decision.url);
+        if (!ok) {
+          await route.abort("blockedbyclient");
+          return;
+        }
+      }
+
+      if (isWebSocket) budget.webSocketCount += 1;
+      else budget.requestCount += 1;
+      await route.continue();
+    } catch {
+      try {
+        await route.abort("failed");
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+
+  await context.route("**/*", handler);
+  return () => {
+    void context.unroute?.("**/*", handler).catch?.(() => undefined);
+  };
+}

package/browser/src/observe.ts

@@ -0,0 +1,178 @@
+/**
+ * Bounded console + network observation ring (0.1.4, plan 016 Task 4).
+ * CDP Runtime/Network events are recorded per page into bounded rings with
+ * drain-on-read semantics. Bodies, cookies, and auth headers are NEVER captured.
+ */
+import type { CdpConsoleEntry, CdpNetworkEntry, PlaywrightCdpSession } from "./types.js";
+
+export interface ObservationRing {
+  recordConsole(entry: CdpConsoleEntry): void;
+  recordNetwork(entry: CdpNetworkEntry): void;
+  /** Return entries since the previous drain and clear; truncated reflects eviction. */
+  drain(): { console: readonly CdpConsoleEntry[]; network: readonly CdpNetworkEntry[]; truncated: boolean };
+}
+
+export function createObservationRing(options: { maxConsoleEntries: number; maxNetworkRequests: number }): ObservationRing {
+  const consoleEntries: CdpConsoleEntry[] = [];
+  const networkEntries: CdpNetworkEntry[] = [];
+  let consoleSeq = 0;
+  let networkSeq = 0;
+  let truncated = false;
+
+  function push<T>(list: T[], entry: T, cap: number): void {
+    list.push(entry);
+    if (list.length > cap) {
+      list.shift();
+      truncated = true;
+    }
+  }
+
+  return {
+    recordConsole(entry) {
+      consoleSeq += 1;
+      push(consoleEntries, { ...entry, seq: consoleSeq }, options.maxConsoleEntries);
+    },
+    recordNetwork(entry) {
+      networkSeq += 1;
+      push(networkEntries, { ...entry, seq: networkSeq }, options.maxNetworkRequests);
+    },
+    drain() {
+      const out = {
+        console: consoleEntries.splice(0),
+        network: networkEntries.splice(0),
+        truncated,
+      };
+      truncated = false;
+      return out;
+    },
+  };
+}
+
+const MAX_URL_BYTES = 2_048;
+const MAX_ERROR_TEXT_BYTES = 512;
+const MAX_METHOD_BYTES = 32;
+const MAX_ARG_PREVIEW_BYTES = 512;
+const MAX_ARGS = 4;
+
+export type CdpConsoleType = CdpConsoleEntry["type"];
+
+/** CDP console API types that map 1:1; the rest collapse to "other". */
+const CONSOLE_TYPES = new Set<string>(["log", "error", "warning", "info", "debug", "assert", "exception"]);
+
+function consoleTypeOf(raw: unknown): CdpConsoleType {
+  if (typeof raw !== "string") return "other";
+  if (raw === "warning") return "warning";
+  if (CONSOLE_TYPES.has(raw)) return raw as CdpConsoleType;
+  return "other";
+}
+
+function previewOf(object: {
+  readonly type?: string;
+  readonly subtype?: string;
+  readonly value?: unknown;
+  readonly description?: string;
+}): string {
+  let text: string;
+  if (object.value !== undefined) {
+    try {
+      text = JSON.stringify(object.value);
+    } catch {
+      text = String(object.value);
+    }
+  } else if (typeof object.description === "string" && object.description.length > 0) {
+    text = object.description;
+  } else {
+    text = object.type ?? "object";
+  }
+  return truncateUtf8(text, MAX_ARG_PREVIEW_BYTES);
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.byteLength <= maxBytes) return text;
+  return `${buf.subarray(0, maxBytes).toString("utf8")}…`;
+}
+
+function truncateText(text: string | undefined, maxBytes: number): string | undefined {
+  if (text === undefined) return undefined;
+  return truncateUtf8(text, maxBytes);
+}
+
+/**
+ * Install CDP Runtime/Network observation handlers on a page session.
+ * Returns the unsubscribe function. Event params are treated as untrusted.
+ */
+export function installCdpObservation(session: PlaywrightCdpSession, ring: ObservationRing): () => void {
+  const onConsole = (params: Record<string, unknown>) => {
+    const type = consoleTypeOf(params.type);
+    const args = Array.isArray(params.args) ? (params.args as Array<Record<string, unknown>>).slice(0, MAX_ARGS).map(previewOf) : [];
+    ring.recordConsole({ seq: 0, type, args });
+  };
+  const onException = (params: Record<string, unknown>) => {
+    const details = params.exceptionDetails as Record<string, unknown> | undefined;
+    const exception = details?.exception as Record<string, unknown> | undefined;
+    const description = truncateText(
+      typeof exception?.description === "string" && exception.description.length > 0
+        ? exception.description
+        : typeof details?.text === "string"
+          ? details.text
+          : undefined,
+      MAX_ARG_PREVIEW_BYTES,
+    );
+    const url = truncateText(typeof details?.url === "string" ? details.url : undefined, MAX_URL_BYTES);
+    ring.recordConsole({
+      seq: 0,
+      type: "exception",
+      args: description !== undefined ? [description] : [],
+      ...(url !== undefined ? { text: url } : {}),
+    });
+  };
+  const onRequest = (params: Record<string, unknown>) => {
+    const request = params.request as Record<string, unknown> | undefined;
+    const url = truncateText(typeof request?.url === "string" ? request.url : undefined, MAX_URL_BYTES) ?? "";
+    const method = truncateText(typeof request?.method === "string" ? request.method : undefined, MAX_METHOD_BYTES);
+    ring.recordNetwork({
+      seq: 0,
+      phase: "request",
+      requestId: typeof params.requestId === "string" ? params.requestId.slice(0, 128) : "",
+      url,
+      ...(method !== undefined ? { method } : {}),
+    });
+  };
+  const onResponse = (params: Record<string, unknown>) => {
+    const response = params.response as Record<string, unknown> | undefined;
+    const url = truncateText(typeof response?.url === "string" ? response.url : undefined, MAX_URL_BYTES) ?? "";
+    ring.recordNetwork({
+      seq: 0,
+      phase: "response",
+      requestId: typeof params.requestId === "string" ? params.requestId.slice(0, 128) : "",
+      url,
+      ...(typeof response?.status === "number" ? { status: response.status } : {}),
+    });
+  };
+  const onFailed = (params: Record<string, unknown>) => {
+    ring.recordNetwork({
+      seq: 0,
+      phase: "failed",
+      requestId: typeof params.requestId === "string" ? params.requestId.slice(0, 128) : "",
+      url: "",
+      ...(truncateText(typeof params.errorText === "string" ? params.errorText : undefined, MAX_ERROR_TEXT_BYTES)
+        ? { errorText: truncateText(typeof params.errorText === "string" ? params.errorText : undefined, MAX_ERROR_TEXT_BYTES) }
+        : {}),
+    });
+  };
+
+  session.on("Runtime.consoleAPICalled", onConsole);
+  session.on("Runtime.exceptionThrown", onException);
+  session.on("Network.requestWillBeSent", onRequest);
+  session.on("Network.responseReceived", onResponse);
+  session.on("Network.loadingFailed", onFailed);
+
+  return () => {
+    session.off?.("Runtime.consoleAPICalled", onConsole);
+    session.off?.("Runtime.exceptionThrown", onException);
+    session.off?.("Network.requestWillBeSent", onRequest);
+    session.off?.("Network.responseReceived", onResponse);
+    session.off?.("Network.loadingFailed", onFailed);
+  };
+}

package/browser/src/policy.ts

@@ -0,0 +1,133 @@
+/**
+ * Observation vs side-effect classification for browser tools: feeds each tool's `effect`
+ * declaration and the manager's side-effect hook.
+ */
+import type { ToolEffectDeclaration } from "@arnilo/prism";
+import type { BrowserActionName } from "./types.js";
+
+export type BrowserRisk = "low" | "medium" | "high";
+export type BrowserEffectClass = "observation" | "mutation" | "high_impact";
+
+export interface BrowserOperationClass {
+  readonly operation: string;
+  readonly effect: BrowserEffectClass;
+  readonly risk: BrowserRisk;
+  readonly requiresSideEffectHook: boolean;
+}
+
+const OBSERVATION = new Set<string>(["open", "snapshot", "wait", "close", "observe"]);
+
+export function classifyBrowserOperation(
+  operation: string,
+  details: {
+    readonly dialogResponse?: "accept" | "dismiss";
+    readonly hasUrl?: boolean;
+    readonly pageKind?: "main" | "popup";
+  } = {},
+): BrowserOperationClass {
+  if (operation === "evaluate") {
+    // Arbitrary page-context code execution: highest-risk browser operation.
+    return {
+      operation,
+      effect: "high_impact",
+      risk: "high",
+      requiresSideEffectHook: true,
+    };
+  }
+  if (operation === "block_urls" || operation === "unblock_urls" || operation === "throttle" || operation === "emulate") {
+    // CDP network/emulation control changes what the page loads and how it renders.
+    return {
+      operation,
+      effect: "mutation",
+      risk: "medium",
+      requiresSideEffectHook: true,
+    };
+  }
+  if (operation === "open" && details.hasUrl) {
+    return {
+      operation: "open_navigate",
+      effect: "mutation",
+      risk: "medium",
+      requiresSideEffectHook: true,
+    };
+  }
+  if (OBSERVATION.has(operation)) {
+    return {
+      operation,
+      effect: "observation",
+      risk: "low",
+      requiresSideEffectHook: false,
+    };
+  }
+  if (operation === "select_page") {
+    const popup = details.pageKind === "popup";
+    return {
+      operation: popup ? "select_popup" : "select_page",
+      effect: popup ? "mutation" : "observation",
+      risk: popup ? "medium" : "low",
+      requiresSideEffectHook: popup,
+    };
+  }
+  if (operation === "dialog") {
+    const accept = details.dialogResponse === "accept";
+    return {
+      operation: accept ? "dialog_accept" : "dialog_dismiss",
+      effect: accept ? "high_impact" : "mutation",
+      risk: accept ? "high" : "medium",
+      requiresSideEffectHook: true,
+    };
+  }
+  if (operation === "download_release") {
+    return {
+      operation,
+      effect: "high_impact",
+      risk: "high",
+      requiresSideEffectHook: true,
+    };
+  }
+  if (operation === "upload" || operation === "screenshot") {
+    return {
+      operation,
+      effect: operation === "upload" ? "high_impact" : "mutation",
+      risk: operation === "upload" ? "high" : "medium",
+      requiresSideEffectHook: true,
+    };
+  }
+  if (
+    operation === "navigate" ||
+    operation === "click" ||
+    operation === "type" ||
+    operation === "fill" ||
+    operation === "select" ||
+    operation === "check" ||
+    operation === "uncheck" ||
+    operation === "scroll"
+  ) {
+    return {
+      operation,
+      effect: "mutation",
+      risk: "medium",
+      requiresSideEffectHook: true,
+    };
+  }
+  return {
+    operation,
+    effect: "mutation",
+    risk: "medium",
+    requiresSideEffectHook: true,
+  };
+}
+
+/** Browser mutations are external effects: browser state must reload+verify, never replay. */
+export function classifyBrowserToolEffect(
+  operation: string,
+  details: Parameters<typeof classifyBrowserOperation>[1] = {},
+): ToolEffectDeclaration {
+  return classifyBrowserOperation(operation, details).effect === "observation"
+    ? { kind: "none", idempotency: "none" }
+    : { kind: "external_mutation", idempotency: "unsupported" };
+}
+
+export function isSideEffectAction(action: BrowserActionName | "evaluate" | "observe"): boolean {
+  return classifyBrowserOperation(action).requiresSideEffectHook;
+}

package/browser/src/screenshot.ts

@@ -0,0 +1,107 @@
+/**
+ * Bounded screenshot capture returning Prism ImageContent.
+ */
+import type { ImageContent } from "@arnilo/prism";
+import { BrowserError } from "./errors.js";
+import type { ResolvedBrowserLimits } from "./limits.js";
+import type { PlaywrightPage } from "./types.js";
+
+export interface ScreenshotBudget {
+  count: number;
+}
+
+export function createScreenshotBudget(): ScreenshotBudget {
+  return { count: 0 };
+}
+
+export interface CaptureScreenshotOptions {
+  readonly page: PlaywrightPage;
+  readonly limits: ResolvedBrowserLimits;
+  readonly budget: ScreenshotBudget;
+  readonly fullPage?: boolean;
+  readonly clip?: { x: number; y: number; width: number; height: number };
+  readonly signal?: AbortSignal;
+}
+
+export interface ScreenshotResult {
+  readonly image: ImageContent;
+  readonly bytes: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly megapixels?: number;
+}
+
+function assertFinitePositive(name: string, value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new BrowserError("ERR_PRISM_BROWSER_INPUT", `${name} must be a positive finite number`);
+  }
+}
+
+export async function captureBoundedScreenshot(options: CaptureScreenshotOptions): Promise<ScreenshotResult> {
+  const { page, limits, budget } = options;
+  if (budget.count >= limits.maxScreenshots) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `maxScreenshots ${limits.maxScreenshots} exceeded`);
+  }
+  if (typeof page.screenshot !== "function") {
+    throw new BrowserError("ERR_PRISM_BROWSER", "Page.screenshot is unavailable");
+  }
+  if (options.signal?.aborted) {
+    throw new BrowserError("ERR_PRISM_BROWSER", "screenshot aborted");
+  }
+
+  if (options.clip) {
+    assertFinitePositive("clip.width", options.clip.width);
+    assertFinitePositive("clip.height", options.clip.height);
+    const megapixels = (options.clip.width * options.clip.height) / 1_000_000;
+    if (megapixels > limits.maxScreenshotMegapixels) {
+      throw new BrowserError(
+        "ERR_PRISM_BROWSER_LIMIT",
+        `screenshot clip exceeds maxScreenshotMegapixels ${limits.maxScreenshotMegapixels}`,
+      );
+    }
+  }
+
+  let buffer: Buffer;
+  try {
+    const raw = await page.screenshot({
+      type: "png",
+      fullPage: options.fullPage === true,
+      ...(options.clip ? { clip: options.clip } : {}),
+      timeout: limits.actionTimeoutMs,
+    });
+    buffer = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+  } catch (error) {
+    if (error instanceof BrowserError) throw error;
+    throw new BrowserError("ERR_PRISM_BROWSER_ARTIFACT", `screenshot failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  if (buffer.byteLength > limits.maxScreenshotBytes) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `screenshot exceeds maxScreenshotBytes ${limits.maxScreenshotBytes}`);
+  }
+  // PNG IHDR width/height at bytes 16..24
+  let width: number | undefined;
+  let height: number | undefined;
+  let megapixels: number | undefined;
+  if (buffer.byteLength >= 24 && buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+    width = buffer.readUInt32BE(16);
+    height = buffer.readUInt32BE(20);
+    megapixels = (width * height) / 1_000_000;
+    if (megapixels > limits.maxScreenshotMegapixels) {
+      throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `screenshot exceeds maxScreenshotMegapixels ${limits.maxScreenshotMegapixels}`);
+    }
+  }
+
+  budget.count += 1;
+  const image: ImageContent = {
+    type: "image",
+    mimeType: "image/png",
+    data: buffer.toString("base64"),
+    metadata: {
+      bytes: buffer.byteLength,
+      ...(width !== undefined ? { width } : {}),
+      ...(height !== undefined ? { height } : {}),
+      source: "browser_screenshot",
+    },
+  };
+  return { image, bytes: buffer.byteLength, width, height, megapixels };
+}