Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
16.0 KB
Raw Blame
import { readFile } from "node:fs/promises";
import { isIP } from "node:net";
import tls from "node:tls";
import type { ConnectionOptions, DetailedPeerCertificate, TLSSocket } from "node:tls";

import { sanitizeDiagnosticString } from "./diagnostic-sanitizer.js";

const DEFAULT_TIMEOUT_MS = 6_000;
const MAX_ENDPOINT_LENGTH = 2 * 1024;
const REQUIRED_TERMINAL_PATH = "/mcp/agent";
const MAX_CERT_FIELD_CHARS = 120;
const MAX_CHAIN_ENTRIES = 5;
const TLS_VERSION_FALLBACK_TIMEOUT_MS = 1_500;

export type CloudEndpointTransportHandshake = "ok" | "failed" | "not-performed";

export type CloudEndpointTransportSkipReason =
  | "perform_probe_false"
  | "missing_endpoint"
  | "invalid_endpoint"
  | "http_loopback_no_tls";

export type ServedCertificateEvidence = {
  subjectCN: string | null;
  issuerCN: string | null;
  selfIssued: boolean;
  notAfter: string | null;
};

export type CloudEndpointTransportProbe = {
  endpointOrigin: string | null;
  endpointProtocol: "https:" | "http:" | null;
  skipReason: CloudEndpointTransportSkipReason | null;
  performed: boolean;
  verifiedHandshake: CloudEndpointTransportHandshake;
  verifyErrorCode: string | null;
  tls13Handshake: CloudEndpointTransportHandshake | null;
  tls13ErrorCode: string | null;
  tls12Handshake: CloudEndpointTransportHandshake | null;
  tls12ErrorCode: string | null;
  tls12Protocol: string | null;
  dnsResolved: boolean | null;
  tcpConnected: boolean | null;
  servedChain: ServedCertificateEvidence[];
  servedChainLength: number | null;
  systemCaCertificateCount: number | null;
  bundledCaCertificateCount: number | null;
  nodeExtraCaCertsSet: boolean;
  nodeExtraCaCertsFileReadable: boolean | null;
  nodeExtraCaCertsCertCount: number | null;
};

export type TransportProbeTlsSocket = Pick<
  TLSSocket,
  "destroy" | "getPeerCertificate" | "once" | "removeListener" | "setTimeout"
> & {
  getProtocol?: () => string | null;
};

export type TransportProbeConnector = (
  options: ConnectionOptions,
  secureConnectListener: () => void,
) => TransportProbeTlsSocket;

export type TransportProbeTlsModule = {
  connect: TransportProbeConnector;
  getCACertificates?: (type?: "default" | "system" | "bundled" | "extra") => string[];
};

export type ProbeCloudEndpointTransportInput = {
  endpointUrl: string | null;
  performProbe: boolean;
  timeoutMs?: number;
  connector?: TransportProbeConnector;
  tlsModule?: TransportProbeTlsModule;
  env?: NodeJS.ProcessEnv;
  caFileReader?: (path: string) => Promise<string> | string;
  signal?: AbortSignal;
};

type PreparedEndpoint = {
  url: URL;
  skipReason: CloudEndpointTransportSkipReason | null;
};

type TlsAttemptResult = {
  status: "ok";
  certificate: DetailedPeerCertificate | null;
  protocol: string | null;
} | {
  status: "failed";
  errorCode: string | null;
  dnsResolved: boolean | null;
  tcpConnected: boolean | null;
};

const tlsWithOptionalCa: { getCACertificates?: (type?: "default" | "system" | "bundled" | "extra") => string[] } = tls;
const defaultTlsModule: TransportProbeTlsModule = {
  connect: (options, secureConnectListener) => tls.connect(options, secureConnectListener),
  getCACertificates: tlsWithOptionalCa.getCACertificates,
};

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isLoopbackHostname(hostname: string): boolean {
  const value = hostname.toLowerCase();
  if (value === "localhost" || value === "::1" || value === "[::1]") return true;
  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(value);
  if (!match) return false;
  return Number(match[1]) === 127 && match.slice(1).every((part) => Number(part) <= 255);
}

function safeTransportEndpoint(rawValue: string | null): PreparedEndpoint | CloudEndpointTransportSkipReason {
  if (rawValue === null) return "missing_endpoint";
  const raw = rawValue.trim();
  if (!raw || raw.length > MAX_ENDPOINT_LENGTH || raw.includes("?") || raw.includes("#")) return "invalid_endpoint";
  if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/iu.test(raw)) return "invalid_endpoint";
  try {
    const url = new URL(raw);
    if (url.username || url.password || url.search || url.hash) return "invalid_endpoint";
    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) {
      return "invalid_endpoint";
    }
    if (!url.pathname.endsWith(REQUIRED_TERMINAL_PATH) || url.pathname.endsWith(REQUIRED_TERMINAL_PATH + "/")) {
      return "invalid_endpoint";
    }
    if (url.origin !== raw.slice(0, raw.length - url.pathname.length)) return "invalid_endpoint";
    return {
      url,
      skipReason: url.protocol === "http:" ? "http_loopback_no_tls" : null,
    };
  } catch {
    return "invalid_endpoint";
  }
}

function boundedDiagnosticString(value: string, maxChars: number): string | null {
  const sanitized = sanitizeDiagnosticString(value).trim().slice(0, maxChars);
  return sanitized || null;
}

function endpointOrigin(url: URL): string | null {
  return boundedDiagnosticString(url.origin, 240);
}

function endpointProtocol(url: URL | null): "https:" | "http:" | null {
  if (!url) return null;
  if (url.protocol === "https:" || url.protocol === "http:") return url.protocol;
  return null;
}

function errorCode(error: unknown): string | null {
  if (isRecord(error) && typeof error.code === "string") {
    return boundedDiagnosticString(error.code, MAX_CERT_FIELD_CHARS);
  }
  if (error instanceof Error) return boundedDiagnosticString(error.message, MAX_CERT_FIELD_CHARS);
  return boundedDiagnosticString(String(error), MAX_CERT_FIELD_CHARS);
}

function isCertificateVerificationError(code: string | null): boolean {
  if (code === null) return false;
  const value = code.toLowerCase();
  return value.includes("cert")
    || value.includes("certificate")
    || value.includes("tls")
    || value.includes("ssl")
    || value.includes("unable_to_")
    || value.includes("depth_zero")
    || value.includes("self_signed");
}

function networkEvidenceForError(code: string | null): { dnsResolved: boolean | null; tcpConnected: boolean | null } {
  if (code === null) return { dnsResolved: null, tcpConnected: null };
  const value = code.toLowerCase();
  if (value.includes("enotfound") || value.includes("eai_again") || value.includes("getaddrinfo")) {
    return { dnsResolved: false, tcpConnected: false };
  }
  if (value.includes("econnrefused")) return { dnsResolved: true, tcpConnected: false };
  if (isCertificateVerificationError(code)) return { dnsResolved: true, tcpConnected: true };
  if (value.includes("econnreset") || value.includes("epipe") || value.includes("socket hang up")) {
    return { dnsResolved: true, tcpConnected: true };
  }
  return { dnsResolved: null, tcpConnected: null };
}

function endpointPort(url: URL): number {
  if (!url.port) return 443;
  const port = Number(url.port);
  return Number.isInteger(port) && port > 0 && port <= 65_535 ? port : 443;
}

function stripIpv6HostnameBrackets(hostname: string): string {
  return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
}

function tlsOptions(url: URL, rejectUnauthorized: boolean, version?: "TLSv1.2" | "TLSv1.3"): ConnectionOptions {
  const host = stripIpv6HostnameBrackets(url.hostname);
  const options: ConnectionOptions = {
    host,
    port: endpointPort(url),
    rejectUnauthorized,
    ALPNProtocols: ["http/1.1"],
  };
  if (version) {
    options.minVersion = version;
    options.maxVersion = version;
  }
  // SNI forbids IP literals; Node throws ERR_INVALID_ARG_VALUE if servername is an IP address.
  if (isIP(host) === 0) options.servername = host;
  return options;
}

function connectTls(input: {
  url: URL;
  rejectUnauthorized: boolean;
  version?: "TLSv1.2" | "TLSv1.3";
  connector: TransportProbeConnector;
  timeoutMs: number;
  inspectPeerCertificate: boolean;
  signal?: AbortSignal;
}): Promise<TlsAttemptResult> {
  input.signal?.throwIfAborted();
  return new Promise<TlsAttemptResult>((resolve, reject) => {
    let socket: TransportProbeTlsSocket | null = null;
    let settled = false;

    const settle = (result: TlsAttemptResult) => {
      if (settled) return;
      settled = true;
      input.signal?.removeEventListener("abort", onAbort);
      if (socket) {
        socket.removeListener("error", onError);
        socket.destroy();
      }
      resolve(result);
    };

    const fail = (error: unknown) => {
      const code = errorCode(error);
      settle({ status: "failed", errorCode: code, ...networkEvidenceForError(code) });
    };

    const onError = (error: Error) => fail(error);
    const onAbort = () => {
      if (settled) return;
      settled = true;
      if (socket) {
        socket.removeListener("error", onError);
        socket.destroy();
      }
      reject(input.signal?.reason ?? new Error("Transport probe aborted"));
    };

    input.signal?.addEventListener("abort", onAbort, { once: true });

    try {
      socket = input.connector(tlsOptions(input.url, input.rejectUnauthorized, input.version), () => {
        const certificate = input.inspectPeerCertificate && socket ? socket.getPeerCertificate(true) : null;
        settle({ status: "ok", certificate, protocol: socket?.getProtocol?.() ?? null });
      });
      socket.once("error", onError);
      socket.setTimeout(input.timeoutMs, () => {
        settle({ status: "failed", errorCode: "ETIMEDOUT", dnsResolved: null, tcpConnected: null });
      });
    } catch (error) {
      input.signal?.removeEventListener("abort", onAbort);
      fail(error);
    }
  });
}

function certificateField(value: unknown): string | null {
  return typeof value === "string" ? boundedDiagnosticString(value, MAX_CERT_FIELD_CHARS) : null;
}

function servedChainFromCertificate(certificate: DetailedPeerCertificate | null): ServedCertificateEvidence[] {
  if (!certificate || Object.keys(certificate).length === 0) return [];
  const chain: ServedCertificateEvidence[] = [];
  const seen = new Set<DetailedPeerCertificate>();
  let current: DetailedPeerCertificate | undefined = certificate;
  while (current && chain.length < MAX_CHAIN_ENTRIES && !seen.has(current)) {
    seen.add(current);
    const subjectCN = certificateField(current.subject?.CN);
    const issuerCN = certificateField(current.issuer?.CN);
    chain.push({
      subjectCN,
      issuerCN,
      selfIssued: current.issuerCertificate === current || (subjectCN !== null && subjectCN === issuerCN),
      notAfter: certificateField(current.valid_to),
    });
    if (!current.issuerCertificate || current.issuerCertificate === current) break;
    current = current.issuerCertificate;
  }
  return chain;
}

function caCertificateCount(tlsModule: TransportProbeTlsModule, type: "system" | "default"): number | null {
  try {
    const certificates = tlsModule.getCACertificates?.(type);
    return Array.isArray(certificates) ? certificates.length : null;
  } catch {
    return null;
  }
}

async function timeoutVersionEvidence(input: {
  url: URL;
  connector: TransportProbeConnector;
  timeoutMs: number;
  signal?: AbortSignal;
}): Promise<{
  tls13Handshake: CloudEndpointTransportHandshake | null;
  tls13ErrorCode: string | null;
  tls12Handshake: CloudEndpointTransportHandshake | null;
  tls12ErrorCode: string | null;
  tls12Protocol: string | null;
}> {
  const timeoutMs = Math.min(input.timeoutMs, TLS_VERSION_FALLBACK_TIMEOUT_MS);
  const tls13 = await connectTls({
    url: input.url,
    rejectUnauthorized: true,
    version: "TLSv1.3",
    connector: input.connector,
    timeoutMs,
    inspectPeerCertificate: false,
    signal: input.signal,
  });
  const tls12 = await connectTls({
    url: input.url,
    rejectUnauthorized: true,
    version: "TLSv1.2",
    connector: input.connector,
    timeoutMs,
    inspectPeerCertificate: false,
    signal: input.signal,
  });
  return {
    tls13Handshake: tls13.status === "ok" ? "ok" : "failed",
    tls13ErrorCode: tls13.status === "ok" ? null : tls13.errorCode,
    tls12Handshake: tls12.status === "ok" ? "ok" : "failed",
    tls12ErrorCode: tls12.status === "ok" ? null : tls12.errorCode,
    tls12Protocol: tls12.status === "ok" ? tls12.protocol : null,
  };
}

async function extraCaEvidence(input: {
  env: NodeJS.ProcessEnv;
  caFileReader?: (path: string) => Promise<string> | string;
}): Promise<{
  nodeExtraCaCertsSet: boolean;
  nodeExtraCaCertsFileReadable: boolean | null;
  nodeExtraCaCertsCertCount: number | null;
}> {
  const extraCaPath = input.env.NODE_EXTRA_CA_CERTS;
  if (!extraCaPath) {
    return { nodeExtraCaCertsSet: false, nodeExtraCaCertsFileReadable: null, nodeExtraCaCertsCertCount: null };
  }
  try {
    const contents = await (input.caFileReader ?? ((path: string) => readFile(path, "utf8")))(extraCaPath);
    return {
      nodeExtraCaCertsSet: true,
      nodeExtraCaCertsFileReadable: true,
      nodeExtraCaCertsCertCount: contents.match(/-----BEGIN CERTIFICATE-----/g)?.length ?? 0,
    };
  } catch {
    return { nodeExtraCaCertsSet: true, nodeExtraCaCertsFileReadable: false, nodeExtraCaCertsCertCount: null };
  }
}

export async function probeCloudEndpointTransport(
  input: ProbeCloudEndpointTransportInput,
): Promise<CloudEndpointTransportProbe> {
  const tlsModule = input.tlsModule ?? defaultTlsModule;
  const env = input.env ?? process.env;
  const localTrust = {
    systemCaCertificateCount: caCertificateCount(tlsModule, "system"),
    bundledCaCertificateCount: caCertificateCount(tlsModule, "default"),
    ...await extraCaEvidence({ env, caFileReader: input.caFileReader }),
  };
  const prepared = safeTransportEndpoint(input.endpointUrl);
  const endpoint = typeof prepared === "string" ? null : prepared;
  const base = {
    endpointOrigin: endpoint ? endpointOrigin(endpoint.url) : null,
    endpointProtocol: endpointProtocol(endpoint?.url ?? null),
    tls13Handshake: null,
    tls13ErrorCode: null,
    tls12Handshake: null,
    tls12ErrorCode: null,
    tls12Protocol: null,
    ...localTrust,
  };
  const skipReason = typeof prepared === "string"
    ? prepared
    : !input.performProbe
      ? "perform_probe_false"
      : prepared.skipReason;
  if (skipReason || !endpoint) {
    return {
      ...base,
      skipReason,
      performed: false,
      verifiedHandshake: "not-performed",
      verifyErrorCode: null,
      dnsResolved: null,
      tcpConnected: null,
      servedChain: [],
      servedChainLength: null,
    };
  }

  const timeoutMs = Math.max(1, Math.min(input.timeoutMs ?? DEFAULT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS));
  const connector = input.connector ?? tlsModule.connect;
  const verified = await connectTls({
    url: endpoint.url,
    rejectUnauthorized: true,
    connector,
    timeoutMs,
    inspectPeerCertificate: false,
    signal: input.signal,
  });
  if (verified.status === "ok") {
    return {
      ...base,
      skipReason: null,
      performed: true,
      verifiedHandshake: "ok",
      verifyErrorCode: null,
      dnsResolved: true,
      tcpConnected: true,
      servedChain: [],
      servedChainLength: null,
    };
  }

  let servedChain: ServedCertificateEvidence[] = [];
  const versionEvidence = verified.errorCode === "ETIMEDOUT"
    ? await timeoutVersionEvidence({ url: endpoint.url, connector, timeoutMs, signal: input.signal })
    : null;
  const certificateVerificationFailure = isCertificateVerificationError(verified.errorCode);
  if (certificateVerificationFailure) {
    const chainAttempt = await connectTls({
      url: endpoint.url,
      rejectUnauthorized: false,
      connector,
      timeoutMs,
      inspectPeerCertificate: true,
      signal: input.signal,
    });
    if (chainAttempt.status === "ok") servedChain = servedChainFromCertificate(chainAttempt.certificate);
  }

  return {
    ...base,
    ...(versionEvidence ?? {}),
    skipReason: null,
    performed: true,
    verifiedHandshake: "failed",
    verifyErrorCode: verified.errorCode,
    dnsResolved: verified.dnsResolved,
    tcpConnected: verified.tcpConnected,
    servedChain,
    servedChainLength: certificateVerificationFailure ? servedChain.length : null,
  };
}

export function isCloudEndpointCertificateVerificationFailure(probe: CloudEndpointTransportProbe): boolean {
  return probe.verifiedHandshake === "failed" && isCertificateVerificationError(probe.verifyErrorCode);
}