@modelprofile.com/browser-runtime 1.0.0

package/ts/classes.egressproxy.ts

@@ -0,0 +1,1005 @@
+import * as plugins from './plugins.js';
+import type {
+  IBrowserEgressConnectionOptions,
+  IBrowserEgressProxyOptions,
+  IBrowserEgressProxyStats,
+  TBrowserDnsResolver,
+  TBrowserEgressConnector,
+} from './interfaces.js';
+import { BrowserRuntimeError } from './errors.js';
+import {
+  randomId,
+  validateBoundedString,
+  validateInteger,
+  validateOptionalInteger,
+  waitBounded,
+} from './utils.js';
+
+interface IResolvedTarget {
+  address: string;
+  family: 4 | 6;
+  hostname: string;
+  port: number;
+  path: string;
+  hostHeader: string;
+}
+
+const hopByHopHeaders = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+export class BrowserEgressProxy {
+  private readonly projectId: string;
+  private readonly allowedPorts: ReadonlySet<number>;
+  private readonly maxConnections: number;
+  private readonly maxActiveRequests: number;
+  private readonly maxHeaderBytes: number;
+  private readonly connectTimeoutMs: number;
+  private readonly idleTimeoutMs: number;
+  private readonly tunnelLifetimeMs: number;
+  private readonly requestTimeoutMs: number;
+  private readonly maxRequestBytes: number;
+  private readonly maxResponseBytes: number;
+  private readonly maxTunnelBytes: number;
+  private readonly resolver: TBrowserDnsResolver;
+  private readonly connector: TBrowserEgressConnector;
+  private readonly username = randomId(18);
+  private readonly password = randomId(32);
+  private readonly expectedAuthorization: plugins.Buffer;
+  private readonly clientSockets = new Set<plugins.net.Socket>();
+  private readonly upstreamSockets = new Set<plugins.net.Socket>();
+  private readonly activeOperations = new Set<Promise<void>>();
+  private server?: plugins.http.Server;
+  private listenPort?: number;
+  private startPromise?: Promise<void>;
+  private stopPromise?: Promise<void>;
+  private lifecycleState: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
+  private lifecycleController = new AbortController();
+  private ordinaryRequests = 0;
+  private upgradeRequests = 0;
+  private connectRequests = 0;
+  private rejectedRequests = 0;
+
+  constructor(options: IBrowserEgressProxyOptions) {
+    this.projectId = validateBoundedString(options.projectId, 'projectId', 1, 128);
+    const ports = options.allowedPorts ?? [80, 443];
+    if (!Array.isArray(ports) || ports.length < 1 || ports.length > 32) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'allowedPorts must contain 1 to 32 ports');
+    }
+    this.allowedPorts = new Set(ports.map((port) => validateInteger(port, 'allowedPort', 1, 65535)));
+    if (this.allowedPorts.size !== ports.length) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'allowedPorts must not contain duplicates');
+    }
+    this.maxConnections = validateOptionalInteger(
+      options.maxConnections,
+      'maxConnections',
+      1,
+      1024,
+      128,
+    );
+    this.maxActiveRequests = validateOptionalInteger(
+      options.maxActiveRequests,
+      'maxActiveRequests',
+      1,
+      1024,
+      this.maxConnections,
+    );
+    this.maxHeaderBytes = validateOptionalInteger(
+      options.maxHeaderBytes,
+      'maxHeaderBytes',
+      1024,
+      128 * 1024,
+      32 * 1024,
+    );
+    this.connectTimeoutMs = validateOptionalInteger(
+      options.connectTimeoutMs,
+      'connectTimeoutMs',
+      100,
+      60_000,
+      10_000,
+    );
+    this.idleTimeoutMs = validateOptionalInteger(
+      options.idleTimeoutMs,
+      'idleTimeoutMs',
+      1000,
+      10 * 60_000,
+      60_000,
+    );
+    this.tunnelLifetimeMs = validateOptionalInteger(
+      options.tunnelLifetimeMs,
+      'tunnelLifetimeMs',
+      1000,
+      60 * 60_000,
+      10 * 60_000,
+    );
+    this.requestTimeoutMs = validateOptionalInteger(
+      options.requestTimeoutMs,
+      'requestTimeoutMs',
+      1000,
+      60 * 60_000,
+      Math.min(this.tunnelLifetimeMs, 5 * 60_000),
+    );
+    this.maxRequestBytes = validateOptionalInteger(
+      options.maxRequestBytes,
+      'maxRequestBytes',
+      1024,
+      256 * 1024 * 1024,
+      16 * 1024 * 1024,
+    );
+    this.maxResponseBytes = validateOptionalInteger(
+      options.maxResponseBytes,
+      'maxResponseBytes',
+      1024,
+      1024 * 1024 * 1024,
+      64 * 1024 * 1024,
+    );
+    this.maxTunnelBytes = validateOptionalInteger(
+      options.maxTunnelBytes,
+      'maxTunnelBytes',
+      1024,
+      2 * 1024 * 1024 * 1024,
+      256 * 1024 * 1024,
+    );
+    this.resolver = options.resolver ?? (async (hostname, lookupOptions) => (
+      plugins.dns.promises.lookup(hostname, {
+        all: lookupOptions.all,
+        verbatim: lookupOptions.verbatim,
+      })
+    ));
+    this.connector = options.connector ?? ((connectionOptions) => plugins.net.connect({
+      host: connectionOptions.address,
+      family: connectionOptions.family,
+      port: connectionOptions.port,
+    }));
+    this.expectedAuthorization = plugins.Buffer.from(
+      `Basic ${plugins.Buffer.from(`${this.username}:${this.password}`, 'utf8').toString('base64')}`,
+      'utf8',
+    );
+  }
+
+  public get credentials(): { username: string; password: string } {
+    return { username: this.username, password: this.password };
+  }
+
+  public get port(): number {
+    if (this.listenPort === undefined) throw new BrowserRuntimeError('NOT_RUNNING');
+    return this.listenPort;
+  }
+
+  public get project(): string {
+    return this.projectId;
+  }
+
+  public get allowedTargetPorts(): number[] {
+    return [...this.allowedPorts];
+  }
+
+  public getStats(): IBrowserEgressProxyStats {
+    return {
+      ordinaryRequests: this.ordinaryRequests,
+      upgradeRequests: this.upgradeRequests,
+      connectRequests: this.connectRequests,
+      rejectedRequests: this.rejectedRequests,
+      activeConnections: this.clientSockets.size,
+    };
+  }
+
+  public start(): Promise<void> {
+    if (this.lifecycleState === 'running') return Promise.resolve();
+    if (this.startPromise) return this.startPromise;
+    if (this.stopPromise) return this.stopPromise.then(() => this.start());
+    this.stopPromise = undefined;
+    this.lifecycleState = 'starting';
+    this.lifecycleController = new AbortController();
+    this.startPromise = this.startInternal().then(() => {
+      if (this.lifecycleState !== 'starting') throw new BrowserRuntimeError('ABORTED');
+      this.lifecycleState = 'running';
+    }).catch((error) => {
+      if (this.lifecycleState === 'starting') this.lifecycleState = 'stopped';
+      throw error;
+    }).finally(() => {
+      this.startPromise = undefined;
+    });
+    return this.startPromise;
+  }
+
+  public stop(): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    if (this.lifecycleState === 'stopped' && !this.server && !this.startPromise) {
+      return Promise.resolve();
+    }
+    this.lifecycleState = 'stopping';
+    this.lifecycleController.abort(new BrowserRuntimeError('ABORTED'));
+    const startup = this.startPromise;
+    this.stopPromise = (async () => {
+      await startup?.catch(() => undefined);
+      await this.stopInternal();
+      this.lifecycleState = 'stopped';
+    })().finally(() => {
+      this.stopPromise = undefined;
+    });
+    return this.stopPromise;
+  }
+
+  private async startInternal(): Promise<void> {
+    const server = plugins.http.createServer(
+      { maxHeaderSize: this.maxHeaderBytes },
+      (request, response) => {
+        if (!this.admit()) {
+          this.rejectedRequests += 1;
+          this.sendSafeFailure(response, 503);
+          return;
+        }
+        this.track(this.handleHttpRequest(request, response));
+      },
+    );
+    this.server = server;
+    server.on('connection', (socket) => {
+      if (this.clientSockets.size >= this.maxConnections) {
+        socket.destroy();
+        return;
+      }
+      this.clientSockets.add(socket);
+      socket.on('error', () => socket.destroy());
+      socket.setTimeout(this.idleTimeoutMs, () => socket.destroy());
+      socket.once('close', () => this.clientSockets.delete(socket));
+    });
+    server.on('connect', (request, socket, head) => {
+      if (!this.admit()) {
+        this.rejectedRequests += 1;
+        this.rejectRawSocket(socket, 502, false);
+        return;
+      }
+      this.track(this.handleConnect(request, socket, head));
+    });
+    server.on('upgrade', (request, socket, head) => {
+      if (!this.admit()) {
+        this.rejectedRequests += 1;
+        this.rejectRawSocket(socket, 502, false);
+        return;
+      }
+      this.track(this.handleUpgrade(request, socket, head));
+    });
+    server.on('clientError', (_error, socket) => {
+      this.rejectedRequests += 1;
+      if (socket.writable) {
+        socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+      } else {
+        socket.destroy();
+      }
+    });
+    server.on('error', () => {
+      if (this.lifecycleState === 'running') void this.stop().catch(() => undefined);
+    });
+    server.headersTimeout = this.requestTimeoutMs;
+    server.requestTimeout = this.requestTimeoutMs;
+    server.maxRequestsPerSocket = this.maxActiveRequests;
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error): void => {
+        server.off('listening', onListening);
+        reject(error);
+      };
+      const onListening = (): void => {
+        server.off('error', onError);
+        resolve();
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(0, '127.0.0.1');
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string' || address.address !== '127.0.0.1') {
+      await this.stopInternal();
+      throw new BrowserRuntimeError('FENCED', 'proxy did not bind to IPv4 loopback');
+    }
+    this.listenPort = address.port;
+  }
+
+  private async stopInternal(): Promise<void> {
+    const server = this.server;
+    this.listenPort = undefined;
+    for (const socket of this.clientSockets) socket.destroy();
+    for (const socket of this.upstreamSockets) socket.destroy();
+    if (server) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error && (error as NodeJS.ErrnoException).code !== 'ERR_SERVER_NOT_RUNNING') {
+            reject(error);
+          } else {
+            resolve();
+          }
+        });
+      });
+    }
+    const settled = await waitBounded(
+      Promise.allSettled([...this.activeOperations]).then(() => undefined),
+      this.requestTimeoutMs,
+    );
+    if (!settled.settled) throw new BrowserRuntimeError('TIMEOUT');
+    this.server = undefined;
+    this.startPromise = undefined;
+  }
+
+  private track(operation: Promise<void>): void {
+    const observed = operation.catch(() => undefined).finally(() => {
+      this.activeOperations.delete(observed);
+    });
+    this.activeOperations.add(observed);
+  }
+
+  private admit(): boolean {
+    return this.lifecycleState !== 'stopping'
+      && this.activeOperations.size < this.maxActiveRequests;
+  }
+
+  private async handleHttpRequest(
+    request: plugins.http.IncomingMessage,
+    response: plugins.http.ServerResponse,
+  ): Promise<void> {
+    this.ordinaryRequests += 1;
+    if (!this.authorize(request)) {
+      this.sendProxyAuthenticationRequired(response);
+      return;
+    }
+    request.pause();
+    let upstreamRequest: plugins.http.ClientRequest | undefined;
+    let upstreamSocket: plugins.net.Socket | undefined;
+    let upstreamResponse: plugins.http.IncomingMessage | undefined;
+    let agent: plugins.http.Agent | undefined;
+    const operation = this.createOperationSignal();
+    const abort = (): void => operation.controller.abort(new BrowserRuntimeError('ABORTED'));
+    request.once('aborted', abort);
+    request.socket.once('close', abort);
+    response.once('close', () => {
+      if (!response.writableFinished) abort();
+    });
+    try {
+      const contentLength = Number(request.headers['content-length']);
+      if (
+        Number.isFinite(contentLength)
+        && contentLength > this.maxRequestBytes
+      ) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      const target = await this.resolveAbsoluteTarget(request.url, false, operation.signal);
+      operation.signal.throwIfAborted();
+      upstreamSocket = this.openUpstream(target, operation.signal);
+      await this.waitForConnect(upstreamSocket, operation.signal);
+      const headers = this.sanitizeHeaders(request.headers);
+      headers.host = target.hostHeader;
+      agent = new plugins.http.Agent({ keepAlive: false });
+      agent.createConnection = () => upstreamSocket!;
+      upstreamRequest = plugins.http.request({
+        method: request.method,
+        host: target.address,
+        family: target.family,
+        port: target.port,
+        path: target.path,
+        headers,
+        agent,
+        maxHeaderSize: this.maxHeaderBytes,
+      });
+      const onAbort = (): void => {
+        upstreamRequest?.destroy(operation.signal.reason);
+        upstreamResponse?.destroy(operation.signal.reason);
+        upstreamSocket?.destroy(operation.signal.reason);
+      };
+      operation.signal.addEventListener('abort', onAbort, { once: true });
+      let requestBytes = 0;
+      request.on('data', (chunk: plugins.Buffer) => {
+        requestBytes += chunk.byteLength;
+        if (requestBytes > this.maxRequestBytes) {
+          operation.controller.abort(new BrowserRuntimeError('QUOTA_EXCEEDED'));
+        }
+      });
+      const upstreamResponsePromise = new Promise<plugins.http.IncomingMessage>((resolve, reject) => {
+        upstreamRequest!.once('response', resolve);
+        upstreamRequest!.once('error', reject);
+      });
+      request.pipe(upstreamRequest);
+      upstreamResponse = await this.raceAbort(upstreamResponsePromise, operation.signal);
+      const responseLength = Number(upstreamResponse.headers['content-length']);
+      if (Number.isFinite(responseLength) && responseLength > this.maxResponseBytes) {
+        throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      }
+      const responseHeaders = this.sanitizeHeaders(upstreamResponse.headers);
+      response.writeHead(upstreamResponse.statusCode ?? 502, responseHeaders);
+      let responseBytes = 0;
+      upstreamResponse.on('data', (chunk: plugins.Buffer) => {
+        responseBytes += chunk.byteLength;
+        if (responseBytes > this.maxResponseBytes) {
+          operation.controller.abort(new BrowserRuntimeError('QUOTA_EXCEEDED'));
+        }
+      });
+      upstreamResponse.once('aborted', abort);
+      const responseFailure = new Promise<never>((_resolve, reject) => {
+        upstreamResponse!.once('error', reject);
+      });
+      upstreamResponse.pipe(response);
+      await Promise.race([this.waitForResponseCompletion(response), responseFailure]);
+      operation.signal.throwIfAborted();
+    } catch {
+      this.rejectedRequests += 1;
+      upstreamRequest?.destroy();
+      upstreamSocket?.destroy();
+      if (!response.headersSent) this.sendSafeFailure(response, 502);
+      else response.destroy();
+    } finally {
+      operation.dispose();
+      request.off('aborted', abort);
+      request.socket.off('close', abort);
+      upstreamResponse?.destroy();
+      upstreamRequest?.destroy();
+      upstreamSocket?.destroy();
+      agent?.destroy();
+    }
+  }
+
+  private async handleConnect(
+    request: plugins.http.IncomingMessage,
+    clientSocket: plugins.stream.Duplex,
+    head: plugins.Buffer,
+  ): Promise<void> {
+    this.connectRequests += 1;
+    if (!this.authorize(request)) {
+      this.rejectRawSocket(clientSocket, 407, true);
+      return;
+    }
+    clientSocket.pause();
+    const operation = this.createOperationSignal();
+    const abort = (): void => operation.controller.abort(new BrowserRuntimeError('ABORTED'));
+    clientSocket.once('close', abort);
+    let upstream: plugins.net.Socket | undefined;
+    try {
+      if (head.byteLength > this.maxTunnelBytes) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      const target = await this.resolveAuthority(request.url, operation.signal);
+      upstream = this.openUpstream(target, operation.signal);
+      await this.waitForConnect(upstream, operation.signal);
+      operation.signal.throwIfAborted();
+      clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      await this.pipeTunnel(clientSocket, upstream, {
+        toUpstream: head,
+        toClient: plugins.Buffer.alloc(0),
+      }, operation.signal);
+    } catch {
+      this.rejectedRequests += 1;
+      upstream?.destroy();
+      this.rejectRawSocket(clientSocket, 502, false);
+    } finally {
+      operation.dispose();
+      clientSocket.off('close', abort);
+    }
+  }
+
+  private async handleUpgrade(
+    request: plugins.http.IncomingMessage,
+    clientSocket: plugins.stream.Duplex,
+    head: plugins.Buffer,
+  ): Promise<void> {
+    this.upgradeRequests += 1;
+    if (!this.authorize(request)) {
+      this.rejectRawSocket(clientSocket, 407, true);
+      return;
+    }
+    clientSocket.pause();
+    const operation = this.createOperationSignal();
+    const abort = (): void => operation.controller.abort(new BrowserRuntimeError('ABORTED'));
+    clientSocket.once('close', abort);
+    let upstream: plugins.net.Socket | undefined;
+    try {
+      if (
+        request.method !== 'GET'
+        || String(request.headers.upgrade).toLowerCase() !== 'websocket'
+        || !String(request.headers.connection).toLowerCase().split(',')
+          .map((value) => value.trim()).includes('upgrade')
+      ) throw new BrowserRuntimeError('EGRESS_DENIED');
+      const webSocketKey = validateBoundedString(
+        request.headers['sec-websocket-key'],
+        'sec-websocket-key',
+        20,
+        32,
+      );
+      if (
+        request.headers['sec-websocket-version'] !== '13'
+        || !/^[A-Za-z0-9+/]{22}==$/.test(webSocketKey)
+        || plugins.Buffer.from(webSocketKey, 'base64').toString('base64') !== webSocketKey
+      ) throw new BrowserRuntimeError('EGRESS_DENIED');
+      const expectedAccept = plugins.crypto
+        .createHash('sha1')
+        .update(`${webSocketKey}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`, 'ascii')
+        .digest('base64');
+      if (head.byteLength > this.maxTunnelBytes) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      const target = await this.resolveAbsoluteTarget(request.url, true, operation.signal);
+      upstream = this.openUpstream(target, operation.signal);
+      await this.waitForConnect(upstream, operation.signal);
+      const headers = this.sanitizeHeaders(request.headers);
+      headers.host = target.hostHeader;
+      headers.connection = 'Upgrade';
+      headers.upgrade = 'websocket';
+      const headerLines = Object.entries(headers).flatMap(([name, value]) => (
+        Array.isArray(value)
+          ? value.map((entry) => `${name}: ${entry}`)
+          : value === undefined
+            ? []
+            : [`${name}: ${value}`]
+      ));
+      upstream.write(
+        `${request.method ?? 'GET'} ${target.path} HTTP/1.1\r\n${headerLines.join('\r\n')}\r\n\r\n`,
+      );
+      const handshake = await this.readWebSocketHandshake(
+        upstream,
+        operation.signal,
+        expectedAccept,
+      );
+      clientSocket.write(handshake.header);
+      await this.pipeTunnel(
+        clientSocket,
+        upstream,
+        { toUpstream: head, toClient: handshake.remaining },
+        operation.signal,
+      );
+    } catch {
+      this.rejectedRequests += 1;
+      upstream?.destroy();
+      this.rejectRawSocket(clientSocket, 502, false);
+    } finally {
+      operation.dispose();
+      clientSocket.off('close', abort);
+    }
+  }
+
+  private authorize(request: plugins.http.IncomingMessage): boolean {
+    const value = request.headers['proxy-authorization'];
+    if (typeof value !== 'string') {
+      this.rejectedRequests += 1;
+      return false;
+    }
+    const supplied = plugins.Buffer.from(value, 'utf8');
+    const accepted = supplied.byteLength === this.expectedAuthorization.byteLength
+      && plugins.crypto.timingSafeEqual(supplied, this.expectedAuthorization);
+    if (!accepted) this.rejectedRequests += 1;
+    return accepted;
+  }
+
+  private sendProxyAuthenticationRequired(response: plugins.http.ServerResponse): void {
+    response.writeHead(407, {
+      connection: 'close',
+      'content-length': '0',
+      'proxy-authenticate': 'Basic realm="browser-runtime"',
+    });
+    response.end();
+  }
+
+  private sendSafeFailure(response: plugins.http.ServerResponse, status: number): void {
+    response.writeHead(status, { connection: 'close', 'content-length': '0' });
+    response.end();
+  }
+
+  private rejectRawSocket(
+    socket: plugins.stream.Duplex,
+    status: 407 | 502,
+    authenticate: boolean,
+  ): void {
+    if (!socket.writable) {
+      socket.destroy();
+      return;
+    }
+    const statusText = status === 407 ? 'Proxy Authentication Required' : 'Bad Gateway';
+    const challenge = authenticate
+      ? 'Proxy-Authenticate: Basic realm="browser-runtime"\r\n'
+      : '';
+    socket.end(
+      `HTTP/1.1 ${status} ${statusText}\r\n${challenge}Connection: close\r\nContent-Length: 0\r\n\r\n`,
+    );
+  }
+
+  private sanitizeHeaders(
+    headers: plugins.http.IncomingHttpHeaders,
+  ): plugins.http.OutgoingHttpHeaders {
+    const connectionTokens = new Set(
+      (typeof headers.connection === 'string' ? headers.connection : '')
+        .split(',')
+        .map((token) => token.trim().toLowerCase())
+        .filter(Boolean),
+    );
+    const result: plugins.http.OutgoingHttpHeaders = {};
+    for (const [name, value] of Object.entries(headers)) {
+      const normalizedName = name.toLowerCase();
+      if (hopByHopHeaders.has(normalizedName) || connectionTokens.has(normalizedName)) continue;
+      result[normalizedName] = value;
+    }
+    return result;
+  }
+
+  private async resolveAbsoluteTarget(
+    rawUrl: string | undefined,
+    upgrade: boolean,
+    signal: AbortSignal,
+  ): Promise<IResolvedTarget> {
+    if (!rawUrl || plugins.Buffer.byteLength(rawUrl, 'utf8') > 8192) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(rawUrl);
+    } catch {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    const allowedProtocols = upgrade ? new Set(['http:', 'ws:']) : new Set(['http:']);
+    if (
+      !allowedProtocols.has(parsed.protocol)
+      || parsed.username
+      || parsed.password
+      || parsed.hash
+    ) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    const hostname = this.canonicalizeHostname(parsed.hostname);
+    const port = parsed.port
+      ? validateInteger(Number(parsed.port), 'target port', 1, 65535)
+      : 80;
+    const resolved = await this.resolveHost(hostname, port, signal);
+    return {
+      ...resolved,
+      path: `${parsed.pathname || '/'}${parsed.search}`,
+      hostHeader: parsed.host,
+    };
+  }
+
+  private async resolveAuthority(
+    rawAuthority: string | undefined,
+    signal: AbortSignal,
+  ): Promise<IResolvedTarget> {
+    if (
+      !rawAuthority
+      || rawAuthority.length > 512
+      || /[\/?#@]/.test(rawAuthority)
+    ) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    let hostnameValue: string;
+    let portValue: string;
+    if (rawAuthority.startsWith('[')) {
+      const closingBracket = rawAuthority.indexOf(']');
+      if (closingBracket < 2 || rawAuthority[closingBracket + 1] !== ':') {
+        throw new BrowserRuntimeError('EGRESS_DENIED');
+      }
+      hostnameValue = rawAuthority.slice(1, closingBracket);
+      portValue = rawAuthority.slice(closingBracket + 2);
+    } else {
+      const separator = rawAuthority.lastIndexOf(':');
+      if (separator < 1 || rawAuthority.indexOf(':') !== separator) {
+        throw new BrowserRuntimeError('EGRESS_DENIED');
+      }
+      hostnameValue = rawAuthority.slice(0, separator);
+      portValue = rawAuthority.slice(separator + 1);
+    }
+    if (!/^\d{1,5}$/.test(portValue)) throw new BrowserRuntimeError('EGRESS_DENIED');
+    const hostname = this.canonicalizeHostname(hostnameValue);
+    const port = validateInteger(Number(portValue), 'target port', 1, 65535);
+    const resolved = await this.resolveHost(hostname, port, signal);
+    return { ...resolved, path: '', hostHeader: rawAuthority };
+  }
+
+  private canonicalizeHostname(hostnameArg: string): string {
+    const unbracketed = hostnameArg.startsWith('[') && hostnameArg.endsWith(']')
+      ? hostnameArg.slice(1, -1)
+      : hostnameArg;
+    if (!unbracketed || unbracketed.length > 253 || unbracketed.includes('%')) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    if (plugins.ipaddr.isValid(unbracketed)) {
+      return plugins.ipaddr.parse(unbracketed).toNormalizedString();
+    }
+    const withoutTrailingDot = unbracketed.endsWith('.') ? unbracketed.slice(0, -1) : unbracketed;
+    const ascii = plugins.url.domainToASCII(withoutTrailingDot).toLowerCase();
+    if (
+      !ascii
+      || ascii.length > 253
+      || !ascii.includes('.')
+      || ascii.split('.').some((label) => (
+        label.length < 1
+        || label.length > 63
+        || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)
+      ))
+    ) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    return ascii;
+  }
+
+  private async resolveHost(
+    hostname: string,
+    port: number,
+    signal: AbortSignal,
+  ): Promise<Omit<IResolvedTarget, 'path' | 'hostHeader'>> {
+    if (!this.allowedPorts.has(port)) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    const answers = plugins.ipaddr.isValid(hostname)
+      ? [{ address: hostname, family: plugins.ipaddr.parse(hostname).kind() === 'ipv4' ? 4 : 6 }]
+      : await this.raceAbort(
+          this.resolver(hostname, { all: true, verbatim: true, signal }),
+          signal,
+        );
+    signal.throwIfAborted();
+    if (!Array.isArray(answers) || answers.length < 1 || answers.length > 64) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    const validated = answers.map((answer) => {
+      if (
+        !answer
+        || (answer.family !== 4 && answer.family !== 6)
+        || typeof answer.address !== 'string'
+        || answer.address.includes('%')
+        || !plugins.ipaddr.isValid(answer.address)
+      ) {
+        throw new BrowserRuntimeError('EGRESS_DENIED');
+      }
+      const parsed = plugins.ipaddr.parse(answer.address);
+      if (
+        (
+          parsed.kind() === 'ipv6'
+          && (parsed as plugins.ipaddr.IPv6).isIPv4MappedAddress()
+        )
+        || parsed.range() !== 'unicast'
+        || (
+          parsed.kind() === 'ipv6'
+          && !(parsed as plugins.ipaddr.IPv6).match(plugins.ipaddr.parse('2000::'), 3)
+        )
+      ) {
+        throw new BrowserRuntimeError('EGRESS_DENIED');
+      }
+      const family = parsed.kind() === 'ipv4' ? 4 : 6;
+      if (family !== answer.family) throw new BrowserRuntimeError('EGRESS_DENIED');
+      return { address: parsed.toNormalizedString(), family } as const;
+    });
+    return { ...validated[0]!, hostname, port };
+  }
+
+  private openUpstream(
+    target: Omit<IResolvedTarget, 'path' | 'hostHeader'>,
+    signal: AbortSignal,
+  ): plugins.net.Socket {
+    const options: IBrowserEgressConnectionOptions = {
+      address: target.address,
+      family: target.family,
+      port: target.port,
+      hostname: target.hostname,
+      signal,
+    };
+    const socket = this.connector(options);
+    if (!(socket instanceof plugins.net.Socket)) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    this.upstreamSockets.add(socket);
+    socket.on('error', () => socket.destroy());
+    socket.setTimeout(this.idleTimeoutMs, () => socket.destroy());
+    socket.once('close', () => this.upstreamSockets.delete(socket));
+    if (signal.aborted) socket.destroy(signal.reason);
+    else signal.addEventListener('abort', () => socket.destroy(signal.reason), { once: true });
+    return socket;
+  }
+
+  private async waitForConnect(socket: plugins.net.Socket, signal: AbortSignal): Promise<void> {
+    if (
+      !socket.connecting
+      && !socket.pending
+      && !socket.destroyed
+      && socket.remoteAddress
+    ) return;
+    if (!socket.connecting || socket.destroyed) throw new BrowserRuntimeError('EGRESS_DENIED');
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        socket.destroy();
+        reject(new BrowserRuntimeError('TIMEOUT'));
+      }, this.connectTimeoutMs);
+      timer.unref();
+      const cleanup = (): void => {
+        clearTimeout(timer);
+        socket.off('connect', onConnect);
+        socket.off('error', onError);
+        socket.off('close', onClose);
+        signal.removeEventListener('abort', onAbort);
+      };
+      const onConnect = (): void => {
+        cleanup();
+        resolve();
+      };
+      const onError = (): void => {
+        cleanup();
+        reject(new BrowserRuntimeError('EGRESS_DENIED'));
+      };
+      const onClose = (): void => {
+        cleanup();
+        reject(new BrowserRuntimeError('EGRESS_DENIED'));
+      };
+      const onAbort = (): void => {
+        cleanup();
+        socket.destroy(signal.reason);
+        reject(signal.reason);
+      };
+      socket.once('connect', onConnect);
+      socket.once('error', onError);
+      socket.once('close', onClose);
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+
+  private async pipeTunnel(
+    clientSocket: plugins.stream.Duplex,
+    upstream: plugins.net.Socket,
+    initial: { toUpstream: plugins.Buffer; toClient: plugins.Buffer },
+    signal: AbortSignal,
+  ): Promise<void> {
+    let transferred = initial.toUpstream.byteLength + initial.toClient.byteLength;
+    if (transferred > this.maxTunnelBytes) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    const lifetimeTimer = setTimeout(() => {
+      clientSocket.destroy();
+      upstream.destroy();
+    }, this.tunnelLifetimeMs);
+    lifetimeTimer.unref();
+    const count = (chunk: plugins.Buffer): void => {
+      transferred += chunk.byteLength;
+      if (transferred > this.maxTunnelBytes) {
+        clientSocket.destroy();
+        upstream.destroy();
+      }
+    };
+    clientSocket.on('data', count);
+    upstream.on('data', count);
+    const onAbort = (): void => {
+      clientSocket.destroy(signal.reason);
+      upstream.destroy(signal.reason);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (initial.toUpstream.byteLength > 0) upstream.write(initial.toUpstream);
+    if (initial.toClient.byteLength > 0) clientSocket.write(initial.toClient);
+    clientSocket.pipe(upstream);
+    upstream.pipe(clientSocket);
+    clientSocket.resume();
+    await Promise.race([
+      new Promise<void>((resolve) => clientSocket.once('close', resolve)),
+      new Promise<void>((resolve) => upstream.once('close', resolve)),
+    ]);
+    clearTimeout(lifetimeTimer);
+    clientSocket.off('data', count);
+    upstream.off('data', count);
+    signal.removeEventListener('abort', onAbort);
+    clientSocket.destroy();
+    upstream.destroy();
+  }
+
+  private async readWebSocketHandshake(
+    upstream: plugins.net.Socket,
+    signal: AbortSignal,
+    expectedAccept: string,
+  ): Promise<{ header: plugins.Buffer; remaining: plugins.Buffer }> {
+    const data = await new Promise<plugins.Buffer>((resolve, reject) => {
+      let buffered = plugins.Buffer.alloc(0);
+      const cleanup = (): void => {
+        upstream.off('data', onData);
+        upstream.off('error', onError);
+        upstream.off('close', onClose);
+        signal.removeEventListener('abort', onAbort);
+      };
+      const onData = (chunk: plugins.Buffer): void => {
+        buffered = plugins.Buffer.concat([buffered, chunk]);
+        const boundary = buffered.indexOf('\r\n\r\n');
+        if (boundary < 0 && buffered.byteLength > this.maxHeaderBytes) {
+          cleanup();
+          reject(new BrowserRuntimeError('QUOTA_EXCEEDED'));
+          return;
+        }
+        if (boundary < 0) return;
+        if (boundary + 4 > this.maxHeaderBytes) {
+          cleanup();
+          reject(new BrowserRuntimeError('QUOTA_EXCEEDED'));
+          return;
+        }
+        cleanup();
+        resolve(buffered);
+      };
+      const onError = (): void => {
+        cleanup();
+        reject(new BrowserRuntimeError('EGRESS_DENIED'));
+      };
+      const onClose = (): void => {
+        cleanup();
+        reject(new BrowserRuntimeError('EGRESS_DENIED'));
+      };
+      const onAbort = (): void => {
+        cleanup();
+        reject(signal.reason);
+      };
+      upstream.on('data', onData);
+      upstream.once('error', onError);
+      upstream.once('close', onClose);
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+    const boundary = data.indexOf('\r\n\r\n');
+    const header = data.subarray(0, boundary + 4);
+    const statusLine = header.subarray(0, header.indexOf('\r\n')).toString('latin1');
+    if (!/^HTTP\/1\.[01] 101(?: |$)/.test(statusLine)) {
+      throw new BrowserRuntimeError('EGRESS_DENIED');
+    }
+    const headerLines = header.toString('latin1').split('\r\n').slice(1, -2);
+    const headers = new Map<string, string[]>();
+    for (const headerLine of headerLines) {
+      const separator = headerLine.indexOf(':');
+      if (separator < 1) throw new BrowserRuntimeError('EGRESS_DENIED');
+      const name = headerLine.slice(0, separator).trim().toLowerCase();
+      const value = headerLine.slice(separator + 1).trim();
+      const values = headers.get(name) ?? [];
+      values.push(value);
+      headers.set(name, values);
+    }
+    const connectionTokens = (headers.get('connection') ?? [])
+      .flatMap((value) => value.split(','))
+      .map((value) => value.trim().toLowerCase());
+    if (
+      !connectionTokens.includes('upgrade')
+      || headers.get('upgrade')?.length !== 1
+      || headers.get('upgrade')?.[0]?.toLowerCase() !== 'websocket'
+      || headers.get('sec-websocket-accept')?.length !== 1
+      || headers.get('sec-websocket-accept')?.[0] !== expectedAccept
+    ) throw new BrowserRuntimeError('EGRESS_DENIED');
+    return { header, remaining: data.subarray(boundary + 4) };
+  }
+
+  private createOperationSignal(): {
+    controller: AbortController;
+    signal: AbortSignal;
+    dispose(): void;
+  } {
+    const controller = new AbortController();
+    const timeoutController = new AbortController();
+    const timeout = setTimeout(() => {
+      timeoutController.abort(new BrowserRuntimeError('TIMEOUT'));
+    }, this.requestTimeoutMs);
+    timeout.unref();
+    return {
+      controller,
+      signal: AbortSignal.any([
+        controller.signal,
+        timeoutController.signal,
+        this.lifecycleController.signal,
+      ]),
+      dispose: () => clearTimeout(timeout),
+    };
+  }
+
+  private async raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+    signal.throwIfAborted();
+    let onAbort!: () => void;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      onAbort = () => reject(signal.reason);
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+      return await Promise.race([promise, aborted]);
+    } finally {
+      signal.removeEventListener('abort', onAbort);
+    }
+  }
+
+  private async waitForResponseCompletion(response: plugins.http.ServerResponse): Promise<void> {
+    if (response.writableFinished || response.destroyed) return;
+    await new Promise<void>((resolve) => {
+      const settle = (): void => {
+        response.off('finish', settle);
+        response.off('close', settle);
+        resolve();
+      };
+      response.once('finish', settle);
+      response.once('close', settle);
+    });
+  }
+}