@activeagents/browser-sidecar 0.0.0-stage → 1.9.0

package/lib/mcp-gateway.mjs

@@ -0,0 +1,339 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { sep } from 'node:path';
+
+import { TAKEOVER_META } from './control-lock.mjs';
+
+// Never offered and never called: browser_run_code_unsafe runs JavaScript in
+// this process, where the tokens are.
+export const DENIED_TOOLS = new Set(['browser_run_code_unsafe']);
+
+// The tool argument holding the URL a tool opens, for the tools that open one.
+const NAVIGATION_ARGUMENTS = {
+  browser_navigate: () => 'url',
+  browser_tabs: (args) => (args.action === 'new' && args.url !== undefined ? 'url' : null),
+};
+
+const JSONRPC = '2.0';
+// A page snapshot an action wrote to a file, and how much of one is inlined.
+const SNAPSHOT_LINK = /(?:- )?\[Snapshot\]\(([^)\n]+)\)/g;
+const SNAPSHOT_LIMIT = 256 * 1024;
+
+function rpcError(id, code, message) {
+  return { jsonrpc: JSONRPC, id: id ?? null, error: { code, message } };
+}
+
+function toolError(id, text) {
+  return { jsonrpc: JSONRPC, id, result: { content: [{ type: 'text', text: `### Error\n${text}` }], isError: true } };
+}
+
+// The answer to an agent's call refused because a person held control for
+// all of `waitedMs`. Its _meta names who, for a client that pauses the run
+// until they hand back rather than reading the error.
+function takeoverError(id, holder, waitedMs) {
+  const who = holder.user.name ? `${holder.user.name} is` : 'A person is';
+  const text = `${who} driving this browser by hand and did not hand it back within ${Math.round(waitedMs / 1000)} seconds. ` +
+    'Nothing was done. Try again once they hand it back.';
+  const result = toolError(id, text);
+  result.result._meta = { [TAKEOVER_META]: { held_by: holder.user.name, since: new Date(holder.since).toISOString(), waited_ms: waitedMs } };
+  return result;
+}
+
+function isRequest(message) {
+  return typeof message.method === 'string' && message.id !== undefined && message.id !== null;
+}
+
+// The server side of one MCP session, held in memory: a request goes in
+// through `request` and its response comes back through the server's call to
+// `send`.
+// Notifications and requests the server sends on its own are dropped, since
+// a JSON response has nowhere to carry them.
+class MemoryTransport {
+  constructor(timeoutMs) {
+    this.timeoutMs = timeoutMs;
+    this.pending = new Map();
+  }
+
+  async start() {}
+
+  async send(message) {
+    const isResponse = message && message.id !== undefined && ('result' in message || 'error' in message);
+    if (!isResponse) return;
+
+    const waiter = this.pending.get(message.id);
+    if (!waiter) return;
+    this.pending.delete(message.id);
+    clearTimeout(waiter.timer);
+    waiter.resolve(message);
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const [id, waiter] of this.pending) {
+      clearTimeout(waiter.timer);
+      waiter.resolve(rpcError(id, -32000, 'The session closed'));
+    }
+    this.pending.clear();
+    this.onclose?.();
+  }
+
+  request(message) {
+    if (this.closed) return Promise.resolve(rpcError(message.id, -32000, 'The session closed'));
+    if (this.pending.has(message.id)) return Promise.resolve(rpcError(message.id, -32600, 'A request with this id is in flight'));
+
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(message.id);
+        resolve(rpcError(message.id, -32001, 'The request timed out'));
+      }, this.timeoutMs);
+      this.pending.set(message.id, { resolve, timer });
+      this.onmessage?.(message);
+    });
+  }
+
+  notify(message) {
+    this.onmessage?.(message);
+  }
+}
+
+/**
+ * Used to serve MCP over plain JSON responses: each POST carries one JSON-RPC
+ * message and gets the response back as the body.
+ *
+ * Every session gets its own server from `connect`, all of them driving the
+ * same browser. The gateway reads each message on its way in and out, so a
+ * denied tool is neither listed nor called, a navigation is checked against
+ * the network policy before it reaches the browser, and the client declares
+ * no capability the server would call back for (such as roots, which would
+ * move where files are read from).
+ *
+ * Playwright MCP writes the page snapshot an action produces to a file and
+ * answers with a link to it, which a client on another machine cannot open.
+ * With `snapshotDir` set, a link to a file in that directory is replaced by
+ * the snapshot itself.
+ *
+ * With `guard` set, a tool call during which a page was redirected off the
+ * app gets an error instead of its result, which could describe that page.
+ *
+ * With `lock` set, a tool call that would change the page waits while a
+ * person holds control (ControlLock#admit), for up to `agentWaitMs`, and is
+ * answered with an error naming them when they have not handed it back by
+ * then.
+ */
+export class McpGateway {
+  /**
+   * @param {object} options
+   * @param {() => Promise<{ connect(transport: object): Promise<void>, close(): Promise<void> }>} options.connect
+   *   returns a new MCP server for a session
+   * @param {{ navigationTarget(url: string): { url: string, refusal: string | null } }} options.policy
+   * @param {Set<string>} [options.deniedTools]
+   * @param {number} [options.maxSessions] sessions kept at once; the least recently used idle one is closed for a new one
+   * @param {number} [options.idleMs] how long an unused session is kept
+   * @param {number} [options.requestTimeoutMs] how long a request may take
+   * @param {string} [options.snapshotDir] the real path of the directory snapshots are written to
+   * @param {{ escapes: number, refusalSince(since: number): Promise<string | null> }} [options.guard] a NavigationGuard
+   * @param {import('./control-lock.mjs').ControlLock} [options.lock]
+   * @param {number} [options.agentWaitMs]
+   * @param {(name: string, args: object) => void} [options.afterCall] told of each tool call that succeeded
+   */
+  constructor({
+    connect, policy, deniedTools = DENIED_TOOLS, maxSessions = 8, idleMs = 30 * 60_000, requestTimeoutMs = 120_000, snapshotDir = null,
+    guard = null, lock = null, agentWaitMs = 0, afterCall = () => {},
+  }) {
+    this.connect = connect;
+    this.policy = policy;
+    this.guard = guard;
+    this.lock = lock;
+    this.agentWaitMs = agentWaitMs;
+    this.afterCall = afterCall;
+    this.snapshotDir = snapshotDir;
+    this.deniedTools = deniedTools;
+    this.maxSessions = maxSessions;
+    this.idleMs = idleMs;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.sessions = new Map();
+    this.uses = 0;
+  }
+
+  /**
+   * Answers one POSTed message.
+   *
+   * @param {unknown} message the parsed body
+   * @param {string | undefined} sessionId the Mcp-Session-Id header
+   * @returns {Promise<{ status: number, headers?: object, body?: object }>}
+   */
+  async handle(message, sessionId) {
+    if (!message || typeof message !== 'object' || Array.isArray(message) || message.jsonrpc !== JSONRPC) {
+      return { status: 400, body: rpcError(null, -32600, 'The body must be one JSON-RPC 2.0 message') };
+    }
+
+    if (message.method === 'initialize') return this.initialize(message);
+
+    if (!sessionId) return { status: 400, body: rpcError(message.id, -32600, 'Mcp-Session-Id header is required') };
+    const session = this.sessions.get(sessionId);
+    if (!session) return { status: 404, body: rpcError(message.id, -32001, 'Session not found') };
+
+    if (!isRequest(message)) {
+      if (typeof message.method === 'string') session.transport.notify(message);
+      return { status: 202 };
+    }
+
+    const inbound = this.inbound(message);
+    if (inbound.answer) return { status: 200, body: inbound.answer };
+
+    this.touch(session);
+    session.busy += 1;
+    try {
+      const call = message.method === 'tools/call' ? inbound.message.params : null;
+      if (call && this.lock) {
+        const waitStarted = Date.now();
+        const refusal = await this.lock.admit(call.name, call.arguments, this.agentWaitMs);
+        if (refusal?.stopping) return { status: 200, body: toolError(message.id, 'The browser is stopping. Nothing was done.') };
+        if (refusal) return { status: 200, body: takeoverError(message.id, refusal.holder, Date.now() - waitStarted) };
+      }
+
+      const escapes = this.guard?.escapes ?? 0;
+      const response = await session.transport.request(inbound.message);
+      const refusal = call ? await this.guard?.refusalSince(escapes) : null;
+      if (refusal) return { status: 200, body: toolError(message.id, refusal) };
+      if (call && response.result && !response.result.isError) this.afterCall(call.name, call.arguments);
+
+      return { status: 200, body: await this.outbound(message, response) };
+    } finally {
+      session.busy -= 1;
+      this.touch(session);
+    }
+  }
+
+  async initialize(message) {
+    if (!isRequest(message)) return { status: 400, body: rpcError(null, -32600, 'initialize must be a request') };
+    this.closeIdleSessions();
+    if (this.sessions.size >= this.maxSessions && !this.closeLeastRecentlyUsed()) {
+      return { status: 503, body: rpcError(message.id, -32000, 'Too many sessions are busy; try again shortly') };
+    }
+
+    const server = await this.connect();
+    const transport = new MemoryTransport(this.requestTimeoutMs);
+    await server.connect(transport);
+
+    const id = randomUUID();
+    const session = { server, transport, busy: 1 };
+    this.touch(session);
+    this.sessions.set(id, session);
+    try {
+      const params = { ...(message.params ?? {}), capabilities: {} };
+      const response = await transport.request({ ...message, params });
+      if (response.error) {
+        await this.closeSession(id);
+        return { status: 200, body: response };
+      }
+      return { status: 200, headers: { 'mcp-session-id': id }, body: response };
+    } finally {
+      session.busy -= 1;
+    }
+  }
+
+  // The message as the server should see it, or the answer to give without
+  // asking the server at all.
+  inbound(message) {
+    if (message.method !== 'tools/call') return { message };
+
+    const name = message.params?.name;
+    if (this.deniedTools.has(name)) return { answer: toolError(message.id, `The ${name} tool is not available in this browser`) };
+
+    const args = { ...(message.params?.arguments ?? {}) };
+    // _meta can move the directory file names resolve against.
+    delete args._meta;
+
+    const argument = NAVIGATION_ARGUMENTS[name]?.(args);
+    if (argument) {
+      const target = this.policy.navigationTarget(args[argument]);
+      if (target.refusal) return { answer: toolError(message.id, target.refusal) };
+      args[argument] = target.url;
+    }
+
+    return { message: { ...message, params: { ...message.params, arguments: args } } };
+  }
+
+  async outbound(request, response) {
+    if (request.method === 'tools/list' && Array.isArray(response.result?.tools)) {
+      const tools = response.result.tools.filter((tool) => !this.deniedTools.has(tool.name));
+      return { ...response, result: { ...response.result, tools } };
+    }
+    if (request.method === 'tools/call' && this.snapshotDir && Array.isArray(response.result?.content)) {
+      const content = await Promise.all(response.result.content.map((block) => this.inlineSnapshots(block)));
+      return { ...response, result: { ...response.result, content } };
+    }
+    return response;
+  }
+
+  async inlineSnapshots(block) {
+    if (block?.type !== 'text' || typeof block.text !== 'string' || !block.text.includes('[Snapshot](')) return block;
+
+    const snapshots = new Map();
+    for (const [, path] of block.text.matchAll(SNAPSHOT_LINK)) snapshots.set(path, await this.readSnapshot(path));
+
+    const text = block.text.replace(SNAPSHOT_LINK, (link, path) => {
+      const snapshot = snapshots.get(path);
+      return snapshot === null ? link : `\`\`\`yaml\n${snapshot}\n\`\`\``;
+    });
+    return { ...block, text };
+  }
+
+  // The snapshot at `path`, cut to SNAPSHOT_LIMIT, or null when the path is
+  // not a file in snapshotDir.
+  async readSnapshot(path) {
+    try {
+      const resolved = await realpath(path);
+      if (!resolved.startsWith(`${this.snapshotDir}${sep}`)) return null;
+
+      const text = await readFile(resolved, 'utf8');
+      return text.length > SNAPSHOT_LIMIT ? `${text.slice(0, SNAPSHOT_LIMIT)}\n# … (truncated, ${text.length} characters in all)` : text;
+    } catch {
+      return null;
+    }
+  }
+
+  // lastUsed is when, for the idle timeout; use orders sessions by recency,
+  // which two uses in the same millisecond still tell apart.
+  touch(session) {
+    session.lastUsed = Date.now();
+    session.use = ++this.uses;
+  }
+
+  closeIdleSessions() {
+    const cutoff = Date.now() - this.idleMs;
+    for (const [id, session] of this.sessions) {
+      if (session.busy === 0 && session.lastUsed < cutoff) void this.closeSession(id);
+    }
+  }
+
+  closeLeastRecentlyUsed() {
+    const idle = [...this.sessions].filter(([, session]) => session.busy === 0).sort(([, a], [, b]) => a.use - b.use);
+    if (idle.length === 0) return false;
+
+    void this.closeSession(idle[0][0]);
+    return true;
+  }
+
+  /**
+   * Closes one session's server. The browser stays open.
+   *
+   * @param {string} id
+   * @returns {Promise<boolean>} whether there was such a session
+   */
+  async closeSession(id) {
+    const session = this.sessions.get(id);
+    if (!session) return false;
+
+    this.sessions.delete(id);
+    await session.server.close().catch(() => {});
+    await session.transport.close();
+    return true;
+  }
+
+  async closeAll() {
+    await Promise.all([...this.sessions.keys()].map((id) => this.closeSession(id)));
+  }
+}

package/lib/navigation-guard.mjs

@@ -0,0 +1,87 @@
+// How many of the latest escapes are kept to name in a refusal.
+const KEPT_ESCAPES = 10;
+
+/**
+ * Used to keep every tab on the sandbox app. A navigation that starts
+ * elsewhere never leaves (see NetworkPolicy#allows), but Chromium follows an
+ * HTTP redirect from an app page without asking the policy again, and the
+ * egress proxy only refuses private addresses. A tab that lands on another
+ * origin that way has escaped. It is closed at once, which also discards
+ * what Playwright MCP collected from it (its requests and console messages),
+ * and the escape is counted so the MCP gateway can withhold the result of
+ * any tool call it happened during. When it was the only tab, a blank one is
+ * opened first, so the browser keeps a page.
+ */
+export class NavigationGuard {
+  /**
+   * @param {object} options
+   * @param {{ onApp(url: string): boolean }} options.policy
+   * @param {(message: string) => void} [options.log]
+   */
+  constructor({ policy, log = () => {} }) {
+    this.policy = policy;
+    this.log = log;
+    this.escapes = 0;
+    this.recent = [];
+    this.pages = new Set();
+    this.closing = new Set();
+  }
+
+  /**
+   * Watches every page `context` has and opens.
+   *
+   * @param {import('playwright').BrowserContext} context
+   */
+  attach(context) {
+    this.context = context;
+    for (const page of context.pages()) this.watch(page);
+    context.on('page', (page) => this.watch(page));
+  }
+
+  watch(page) {
+    this.pages.add(page);
+    page.on('close', () => this.pages.delete(page));
+    page.on('framenavigated', (frame) => {
+      if (frame !== page.mainFrame() || this.policy.onApp(frame.url())) return;
+
+      const { origin } = new URL(frame.url());
+      this.escapes += 1;
+      this.recent = [...this.recent, { count: this.escapes, origin }].slice(-KEPT_ESCAPES);
+      this.log(`closed a page that was redirected to ${origin}`);
+      const closing = this.close(page);
+      this.closing.add(closing);
+      closing.finally(() => this.closing.delete(closing));
+    });
+  }
+
+  async close(page) {
+    try {
+      if (this.context.pages().every((other) => other === page)) await this.context.newPage();
+      await page.close();
+    } catch {
+      // The browser is closing.
+    }
+  }
+
+  /**
+   * Why a tool call that began when `escapes` was `since` may not return its
+   * result: a page escaped while it ran, or one is still off the app. Null
+   * when neither. Resolves once the escaped pages are closed, so the next
+   * call finds the browser on a page it may use.
+   *
+   * @param {number} since
+   * @returns {Promise<string | null>}
+   */
+  async refusalSince(since) {
+    await Promise.all(this.closing);
+    const origins = new Set(this.recent.filter((escape) => escape.count > since).map((escape) => escape.origin));
+    for (const page of this.pages) {
+      if (!this.policy.onApp(page.url())) origins.add(new URL(page.url()).origin);
+    }
+    if (this.escapes === since && origins.size === 0) return null;
+
+    const where = origins.size > 0 ? ` to ${[...origins].join(', ')}` : '';
+    return `A page was redirected${where}, outside the sandbox app, and was closed. ` +
+      'This browser may only show pages of the sandbox app, so the result of this call is withheld.';
+  }
+}

package/lib/network-policy.mjs

@@ -0,0 +1,264 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+// IPv4 ranges that are not the public internet: this host, private networks,
+// carrier-grade NAT, loopback, link-local (cloud metadata lives there),
+// benchmarking, multicast and reserved.
+const PRIVATE_IPV4 = [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['172.16.0.0', 12],
+  ['192.0.0.0', 24],
+  ['192.168.0.0', 16],
+  ['198.18.0.0', 15],
+  ['224.0.0.0', 4],
+  ['240.0.0.0', 4],
+];
+
+function ipv4ToInt(address) {
+  return address.split('.').reduce((total, part) => total * 256 + Number(part), 0);
+}
+
+function inIpv4Range(address, [base, bits]) {
+  const size = 2 ** (32 - bits);
+  return Math.floor(ipv4ToInt(address) / size) === Math.floor(ipv4ToInt(base) / size);
+}
+
+// The eight 16-bit groups of an IPv6 address, an embedded dotted IPv4 tail
+// included, or null when it is not one.
+function ipv6Groups(address) {
+  let text = address.toLowerCase().replace(/%.*$/, '');
+  const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  if (dotted) {
+    const value = ipv4ToInt(dotted[1]);
+    text = `${text.slice(0, -dotted[1].length)}${(value >>> 16).toString(16)}:${(value & 0xffff).toString(16)}`;
+  }
+
+  const halves = text.split('::');
+  if (halves.length > 2) return null;
+  const head = halves[0] === '' ? [] : halves[0].split(':');
+  const tail = halves.length === 2 && halves[1] !== '' ? halves[1].split(':') : [];
+  const missing = 8 - head.length - tail.length;
+  if (halves.length === 1 ? missing !== 0 : missing < 1) return null;
+
+  const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill('0'), ...tail].map((group) => parseInt(group, 16));
+  return groups.every((group) => Number.isInteger(group) && group >= 0 && group <= 0xffff) ? groups : null;
+}
+
+function groupsToIpv4(high, low) {
+  return [high >> 8, high & 255, low >> 8, low & 255].join('.');
+}
+
+function isPrivateIpv6(address) {
+  const groups = ipv6Groups(address);
+  if (!groups) return false;
+
+  const [first] = groups;
+  const leadingZeros = groups.findIndex((group) => group !== 0);
+  if (leadingZeros === -1) return true; // ::
+  if (leadingZeros === 7 && groups[7] === 1) return true; // ::1
+  // ::ffff:a.b.c.d (mapped) and ::a.b.c.d (compatible) carry an IPv4 address,
+  // and so does 64:ff9b::a.b.c.d (NAT64).
+  const mapped = leadingZeros >= 5 && (groups[5] === 0xffff || (leadingZeros >= 6 && groups[5] === 0));
+  const nat64 = first === 0x64 && groups[1] === 0xff9b && groups.slice(2, 6).every((group) => group === 0);
+  if (mapped || nat64) return isPrivateAddress(groupsToIpv4(groups[6], groups[7]));
+
+  // fc00::/7 unique local, fe80::/10 link-local, fec0::/10 site-local, ff00::/8 multicast.
+  return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80 || (first & 0xffc0) === 0xfec0 || (first & 0xff00) === 0xff00;
+}
+
+/**
+ * Whether `address`, an IP literal, is loopback, link-local, private or
+ * otherwise not on the public internet. A name that is not an IP is false.
+ *
+ * @param {string} address
+ * @returns {boolean}
+ */
+export function isPrivateAddress(address) {
+  const bare = address.replace(/^\[|\]$/g, '');
+  const family = isIP(bare);
+  if (family === 4) return PRIVATE_IPV4.some((range) => inIpv4Range(bare, range));
+  return family === 6 && isPrivateIpv6(bare);
+}
+
+/**
+ * Whether `hostname` names this machine or a local network by name alone.
+ *
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isLocalName(hostname) {
+  const name = hostname.toLowerCase().replace(/\.$/, '');
+  return name === 'localhost' || name.endsWith('.localhost') || name.endsWith('.local') || name.endsWith('.internal');
+}
+
+async function resolveAll(hostname) {
+  const records = await lookup(hostname, { all: true, verbatim: true });
+  return records.map((record) => record.address);
+}
+
+function bare(hostname) {
+  return hostname.toLowerCase().replace(/^\[|\]$/g, '');
+}
+
+function defaultPort(protocol) {
+  return protocol === 'https:' || protocol === 'wss:' ? 443 : 80;
+}
+
+/**
+ * Used to decide what the browser may load, at two levels.
+ *
+ * `allows` judges a request by its URL, before it is sent: a top-level
+ * navigation may only open the sandbox app's origin, and no URL may name a
+ * loopback, link-local or private address, or a local host name, other than
+ * the app's. Chromium follows an HTTP redirect without asking again, so this
+ * only sees the first URL of a redirect chain.
+ *
+ * `destination` judges each connection the browser opens, through the
+ * sidecar's egress proxy, whatever URL or redirect led to it. The app's own
+ * host and port are always reachable. Anything else must resolve only to
+ * public addresses, and the proxy connects to the address checked here, so a
+ * name whose answer changes between two lookups cannot move the connection
+ * onto a private address.
+ */
+export class NetworkPolicy {
+  /**
+   * @param {object} options
+   * @param {string} options.appOrigin the sandbox app's origin
+   * @param {(hostname: string) => Promise<string[]>} [options.resolve] how host names are resolved
+   * @param {(address: string) => boolean} [options.isPrivate] which IP addresses are refused
+   * @param {number} [options.cacheMs] how long a resolution is reused
+   */
+  constructor({ appOrigin, resolve = resolveAll, isPrivate = isPrivateAddress, cacheMs = 60_000 }) {
+    this.appOrigin = appOrigin;
+    const app = new URL(appOrigin);
+    this.appHost = bare(app.hostname);
+    this.appPort = Number(app.port || defaultPort(app.protocol));
+    this.resolve = resolve;
+    this.isPrivate = isPrivate;
+    this.cacheMs = cacheMs;
+    this.resolved = new Map();
+  }
+
+  /**
+   * Returns `url` as the absolute URL a navigation would open, and why it
+   * may not, if it may not. A path ("/login") is resolved against the app.
+   *
+   * @param {string} url
+   * @returns {{ url: string, refusal: string | null }}
+   */
+  navigationTarget(url) {
+    const text = String(url ?? '').trim();
+    if (text === 'about:blank') return { url: text, refusal: null };
+
+    let target;
+    try {
+      target = text.startsWith('/') && !text.startsWith('//') ? new URL(text, this.appOrigin) : new URL(text);
+    } catch {
+      return { url: text, refusal: this.refusalMessage(text) };
+    }
+    if (target.origin !== this.appOrigin) return { url: text, refusal: this.refusalMessage(text) };
+
+    return { url: target.toString(), refusal: null };
+  }
+
+  refusalMessage(url) {
+    return `Navigation to ${url} was refused: this browser may only open pages of the sandbox app at ${this.appOrigin}`;
+  }
+
+  /**
+   * Whether a page on `url` is one of the sandbox app's. A page that is not
+   * on the web (about:blank, an error page) is not elsewhere either.
+   *
+   * @param {string} url
+   * @returns {boolean}
+   */
+  onApp(url) {
+    let target;
+    try {
+      target = new URL(url);
+    } catch {
+      return true;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') return true;
+    return target.origin === this.appOrigin;
+  }
+
+  /**
+   * Whether the browser may send a request to `url`, judged by the URL alone.
+   *
+   * @param {string} url
+   * @param {{ topLevelNavigation?: boolean }} [options]
+   * @returns {boolean}
+   */
+  allows(url, { topLevelNavigation = false } = {}) {
+    let target;
+    try {
+      target = new URL(url);
+    } catch {
+      return false;
+    }
+
+    if (target.protocol !== 'http:' && target.protocol !== 'https:' && target.protocol !== 'ws:' && target.protocol !== 'wss:') {
+      return !topLevelNavigation || url === 'about:blank';
+    }
+    if (this.sameOriginAsApp(target)) return true;
+    if (topLevelNavigation) return false;
+
+    const hostname = bare(target.hostname);
+    return !this.isPrivate(hostname) && !isLocalName(hostname);
+  }
+
+  // A WebSocket URL is the app's when it names the app's host and port.
+  sameOriginAsApp(target) {
+    if (target.origin === this.appOrigin) return true;
+    if (target.protocol !== 'ws:' && target.protocol !== 'wss:') return false;
+
+    const http = new URL(target.toString());
+    http.protocol = target.protocol === 'ws:' ? 'http:' : 'https:';
+    return http.origin === this.appOrigin;
+  }
+
+  /**
+   * Returns the address a browser connection to `hostname`:`port` is to be
+   * made to, or why it may not be made.
+   *
+   * @param {string} hostname a host name or IP address, IPv6 with or without brackets
+   * @param {number} port
+   * @returns {Promise<{ address: string, refusal: null } | { address: null, refusal: string }>}
+   */
+  async destination(hostname, port) {
+    const host = bare(hostname);
+    if (this.isApp(host, port)) return { address: host, refusal: null };
+
+    const refused = (reason) => ({ address: null, refusal: `${host}:${port} ${reason}` });
+    if (isLocalName(host)) return refused('is a local host name');
+    if (isIP(host)) return this.isPrivate(host) ? refused('is a loopback, link-local or private address') : { address: host, refusal: null };
+
+    const addresses = await this.lookup(host);
+    if (addresses.length === 0) return refused('does not resolve');
+    if (addresses.some((address) => this.isPrivate(address))) return refused('resolves to a loopback, link-local or private address');
+    return { address: addresses[0], refusal: null };
+  }
+
+  isApp(hostname, port) {
+    return bare(hostname) === this.appHost && port === this.appPort;
+  }
+
+  async lookup(hostname) {
+    const cached = this.resolved.get(hostname);
+    if (cached && cached.until > Date.now()) return cached.addresses;
+
+    let addresses = [];
+    try {
+      addresses = await this.resolve(hostname);
+    } catch {
+      // A name that does not resolve is refused.
+    }
+    this.resolved.set(hostname, { addresses, until: Date.now() + this.cacheMs });
+    return addresses;
+  }
+}