Chrome DevTools for coding agents
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import os from 'node:os';
// Node 22 has no global URLPattern. The CLI bundle exports Puppeteer's
// polyfill, so this module does not need the full third-party bundle.
import {URLPattern} from '../third_party/cli.js';
const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'ws:', 'wss:']);
const IPV4_LOOPBACK_REGEX = /^127(?:\.(?:25[0-5]|2[0-4]\d|[01]?\d\d?)){3}$/;
const IPV4_MAPPED_LOOPBACK_REGEX = /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/;
/**
* Determines whether a given URL string points to a localhost / loopback address.
*
* @param url The URL string to test.
* @returns true if the URL is a valid network URL pointing to localhost or a loopback IP.
*/
export function isLocalhost(url?: string): boolean {
if (!url || typeof url !== 'string' || url.trim() === '') {
return false;
}
let parsed: URL;
try {
parsed = new URL(url);
} catch {
return false;
}
if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
return false;
}
const hostname = parsed.hostname.toLowerCase().replace(/\.$/, '');
// 1. Check localhost and RFC 6761 *.localhost subdomains
if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
return true;
}
// 2. Check IPv6 loopback ([::1] as returned by URL.hostname, or ::1)
if (hostname === '[::1]' || hostname === '::1') {
return true;
}
// 3. Check IPv4 loopback (127.0.0.0/8)
if (IPV4_LOOPBACK_REGEX.test(hostname)) {
return true;
}
// 4. Check IPv4-mapped IPv6 loopback. URL serializes [::ffff:127.0.0.1]
// as [::ffff:7f00:1].
if (IPV4_MAPPED_LOOPBACK_REGEX.test(hostname)) {
return true;
}
return false;
}
// URL serializes `0`, `0x0` and `0.0` as 0.0.0.0, `[::0]` as [::], and
// [::ffff:0.0.0.0] as [::ffff:0:0].
const UNSPECIFIED_HOSTNAMES = new Set(['0.0.0.0', '[::]', '[::ffff:0:0]']);
/**
* Serializes a host name or IP address the way `URL#hostname` does, or returns
* undefined if it is not a valid host.
*/
function toUrlHostname(host: string): string | undefined {
try {
return new URL(`http://${host.includes(':') ? `[${host}]` : host}`)
.hostname;
} catch {
return undefined;
}
}
/**
* Checks whether a `URL#hostname` is the host name of the local machine or an
* address of one of its network interfaces.
*/
function isLocalMachineHostname(hostname: string): boolean {
const normalized = hostname.replace(/\.$/, '');
if (normalized === toUrlHostname(os.hostname())) {
return true;
}
let interfaces: ReturnType<typeof os.networkInterfaces>;
try {
interfaces = os.networkInterfaces();
} catch {
// Some platforms cannot enumerate interfaces; keep the loopback checks.
return false;
}
for (const addresses of Object.values(interfaces)) {
for (const {address} of addresses ?? []) {
if (toUrlHostname(address) === normalized) {
return true;
}
}
}
return false;
}
/**
* Determines whether a browser endpoint URL points to the local machine.
*
* In addition to {@link isLocalhost}, this accepts the unspecified addresses
* 0.0.0.0 and [::], the local host name, and the addresses of the local
* network interfaces (for example a LAN or Docker bridge IP). A connection to
* any of these reaches the local machine.
*
* @param url The browser endpoint URL (for example, a WebSocket endpoint).
* @returns true if the endpoint is on the local machine.
*/
export function isLocalBrowserEndpoint(url: string): boolean {
if (isLocalhost(url)) {
return true;
}
let parsed: URL;
try {
parsed = new URL(url);
} catch {
return false;
}
if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
return false;
}
return (
UNSPECIFIED_HOSTNAMES.has(parsed.hostname) ||
isLocalMachineHostname(parsed.hostname)
);
}
export interface ValidateUrlOptions {
javascriptEvaluation: boolean | undefined;
categoryExtensions: boolean | undefined;
fileNavigations: boolean | undefined;
}
export interface IsAllowedUrlOptions {
categoryExtensions: boolean | undefined;
}
/**
* Determines whether a URL is allowed for navigation and page tracking.
*
* Disallowed schemes:
* - chrome: (except chrome://newtab/ and chrome://inspect*)
* - chrome-untrusted:
* - chrome-extension: (unless categoryExtensions is true)
*
* @param url The URL string to test.
* @param options Configuration specifying whether extensions are enabled.
* @returns true if the URL is allowed.
*/
export function isAllowedUrl(
url: string,
options: IsAllowedUrlOptions,
): boolean {
let parsed: URL;
try {
parsed = new URL(url);
} catch {
return false;
}
if (parsed.protocol === 'chrome:') {
const host = parsed.hostname.toLowerCase();
const path = parsed.pathname.toLowerCase();
if (host === 'newtab' || host === 'new-tab-page' || host === 'inspect') {
return true;
}
if (
host === '' &&
(path === 'newtab' ||
path === 'new-tab-page' ||
path.startsWith('inspect'))
) {
return true;
}
}
if (
parsed.protocol === 'chrome:' ||
parsed.protocol === 'chrome-untrusted:'
) {
return false;
}
if (!options.categoryExtensions && parsed.protocol === 'chrome-extension:') {
return false;
}
return true;
}
const DISALLOWED_PROTOCOLS = new Set(['javascript:', 'data:', 'vbscript:']);
/**
* Checks whether a compiled URLPattern component contains an unescaped `:`
* (which always represents a `:name` group in URLPattern syntax).
*/
function hasNamedGroup(component: string): boolean {
return component.replaceAll('\\\\', '').replaceAll('\\:', '').includes(':');
}
/**
* Checks whether a URLPattern string has a partial IPv4 wildcard in the
* hostname (for example `127.0.0.*`, `*.0.0.1`, `*1*`, or `{127.0.0.*}`),
* which Chrome cannot enforce on redirects or subresources.
*/
function hasPartialIpv4Hostname(pattern: string): boolean {
const authority = /:\/\/([^/?#]+)/.exec(pattern)?.[1] ?? '';
const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
if (hostPort.startsWith('[')) {
return false;
}
const hostname = hostPort.replace(/:.*$/, '');
if (!hostname.includes('*')) {
return false;
}
const stripped = hostname.replaceAll(/[{}*\\]/g, '').replace(/\.+$/, '');
const lastLabel = stripped.split('.').at(-1) ?? '';
return /^(?:\d+|0[xX][0-9a-fA-F]*)$/.test(lastLabel);
}
/**
* Validates that every pattern can be enforced by Chrome on redirects and subresources:
* - Rejects patterns with a partial IPv4 wildcard in the hostname (for example `127.0.0.*`).
* - Rejects patterns containing a regexp group (for example `(foo|bar)`).
* - Rejects patterns containing a named group (`:name`, for example `*://127.0.0.1::port/path`).
*
* @param patterns The `--blockedUrlPattern`/`--allowedUrlPattern` values to check.
* @param flagName The CLI flag name used in error messages.
* @throws Error if a pattern's syntax is invalid (via `new URLPattern`) or uses an unenforceable construct.
*/
export function validateUrlPatterns(
patterns: string[],
flagName: string,
): void {
for (const raw of patterns) {
if (hasPartialIpv4Hostname(raw)) {
throw new Error(
`Invalid ${flagName} "${raw}": a partial IPv4 wildcard is not enforced on redirects or subresources. Use an exact IPv4 address or a "*" wildcard instead.`,
);
}
let parsed: URLPattern;
try {
parsed = new URLPattern(raw);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
throw new Error(`Invalid ${flagName} "${raw}": ${message}`, {
cause: error,
});
}
if (parsed.hasRegExpGroups) {
throw new Error(
`Invalid ${flagName} "${raw}": a regexp group is not enforced on redirects or subresources. Use an exact value or a "*" wildcard instead.`,
);
}
const components = [
parsed.protocol,
parsed.username,
parsed.password,
parsed.hostname,
parsed.port,
parsed.pathname,
parsed.search,
parsed.hash,
];
if (components.some(hasNamedGroup)) {
throw new Error(
`Invalid ${flagName} "${raw}": a ":name" named group is not enforced on redirects or subresources. Use an exact value or a "*" wildcard instead.`,
);
}
}
}
/**
* Unwraps nested `view-source:` prefixes so every scheme check below runs
* against the URL Chrome will actually resolve and load — not the
* wrapper. `view-source:` wraps another URL and Chrome resolves the inner
* target (potentially through multiple levels of wrapping), so
* `view-source:file:///etc/passwd` reads the file just as
* `file:///etc/passwd` does, and `view-source:devtools://devtools/...`
* loads under the `devtools://devtools` origin just as the bare
* `devtools:` URL would. The inner URL is re-parsed rather than
* string-matched so that an uppercase inner scheme
* (`view-source:FILE:///etc/passwd`) is normalised.
*
* @param url The already-parsed URL to unwrap.
* @returns The fully unwrapped URL, or the original URL unchanged if it
* is not `view-source:`. Returns null if any wrapped layer is not itself
* a valid URL.
*/
function unwrapViewSource(url: URL): URL | null {
let current = url;
// Bounded in case of a pathologically nested `view-source:` chain.
for (let i = 0; i < 5 && current.protocol === 'view-source:'; i++) {
try {
current = new URL(current.pathname);
} catch {
return null;
}
}
return current.protocol === 'view-source:' ? null : current;
}
/**
* Validates a URL string by parsing it with `new URL` and checking for disallowed protocols and restricted schemes.
*
* Any `view-source:` wrapping is unwrapped first (see {@link unwrapViewSource}),
* since Chrome resolves the wrapper at navigation time and loads the page
* under the wrapped URL's own origin, so every scheme check below must run
* against the unwrapped target rather than the outer `view-source:` URL.
*
* @param url The URL string to validate.
* @param options Options object containing javascriptEvaluation, categoryExtensions and fileNavigations.
* @returns The parsed URL.
* @throws Error if the URL does not parse with `new URL`, or if JavaScript evaluation is disabled and a disallowed URL is passed,
* or if file navigations are disabled and a `file:` URL is passed, or if navigating to a restricted scheme.
*/
export function validateUrl(url: string, options: ValidateUrlOptions): URL {
const {javascriptEvaluation, categoryExtensions, fileNavigations} = options;
let parsed: URL;
try {
parsed = new URL(url);
} catch {
throw new Error(
`Invalid URL: "${url}". URLs must be valid according to the URL standard.`,
);
}
const target = unwrapViewSource(parsed);
if (!target) {
throw new Error(
`Invalid URL: "${url}". The view-source: wrapped content is not a valid URL.`,
);
}
if (
javascriptEvaluation === false &&
DISALLOWED_PROTOCOLS.has(target.protocol)
) {
throw new Error(
`Navigating to ${target.protocol} URLs is not allowed when JavaScript evaluation is disabled.`,
);
}
if (fileNavigations === false && target.protocol === 'file:') {
throw new Error(
`Navigating to file: URLs is not allowed when --file-navigations is disabled.`,
);
}
if (target.protocol === 'devtools:') {
throw new Error(`Navigating to devtools: URLs is not allowed.`);
}
if (!isAllowedUrl(target.href, {categoryExtensions})) {
if (target.protocol === 'chrome-extension:') {
throw new Error(
`Navigating to chrome-extension: URLs is not allowed without --categoryExtensions.`,
);
}
throw new Error(`Navigating to ${target.protocol} URLs is not allowed.`);
}
return parsed;
}