Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

15.9 KB
Raw Blame
import {
  isBlockedHostnameOrIp,
  matchesHostnameAllowlist,
  normalizeHostname,
  resolvePinnedHostnameWithPolicy,
  type LookupFn,
} from './shim/security-runtime.js';

export type { LookupFn };

/**
 * Browser proxy routes accepted by the neutral browser-control contract.
 *
 * The credential fields are intentionally in-memory only. Callers must use
 * `server` for launch arguments and safe reporting; username/password are
 * consumed by an authentication coordinator and are never serialized.
 */
export interface BrowserProxyRoute {
  readonly mode: 'direct' | 'proxied';
  readonly server?: string;
  readonly username?: string;
  readonly password?: string;
  /** Public navigation hostnames explicitly permitted while this proxy is active. */
  readonly allowedHostnames?: readonly string[];
}

const SUPPORTED_SCHEMES = new Set(['http:', 'https:', 'socks:', 'socks4:', 'socks5:']);
const MAX_ALLOWED_HOSTNAMES = 32;
// DNS limits (RFC 1035): 253 chars per name, 63 per label. WHATWG URL accepts
// far longer hostnames, and oversized input is not merely invalid — parsing
// succeeds, `startInRoute` stops the running browser, and only then does the
// PAC/argv built from it risk exceeding the platform command-line limit,
// losing the user's tabs to a launch failure. Reject at the parse boundary,
// before anything destructive happens.
const MAX_HOSTNAME_LENGTH = 253;
const MAX_DNS_LABEL_LENGTH = 63;
const MAX_PROXY_SERVER_LENGTH = 2_048;
// LDH (RFC 952/1123): letters, digits, hyphen; a label must not start or end
// with a hyphen. Both call sites see lowercase input (allowlist entries are
// lowercased before this check, proxy hosts come from URL.hostname), and IDNs
// arrive here already punycoded, so the ASCII form is the complete alphabet.
const DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;

function assertValidDnsName(hostname: string, what: string): void {
  if (hostname.length > MAX_HOSTNAME_LENGTH) {
    throw invalidProxy(`${what} must be at most ${MAX_HOSTNAME_LENGTH} characters`);
  }
  for (const label of hostname.split('.')) {
    // WHATWG URL preserves empty and non-LDH labels (`example..com`,
    // `_foo.example.com`, `-foo.example.com`), so length checks alone would
    // pass names that later fail PAC/DNS matching — after the route switch has
    // already stopped the running browser. Reject them here, fail-closed.
    if (label.length === 0) {
      throw invalidProxy(`${what} must not contain empty DNS labels`);
    }
    if (label.length > MAX_DNS_LABEL_LENGTH) {
      throw invalidProxy(`${what} labels must be at most ${MAX_DNS_LABEL_LENGTH} characters`);
    }
    if (!DNS_LABEL_PATTERN.test(label)) {
      throw invalidProxy(
        `${what} labels must contain only letters, digits, and non-edge hyphens`,
      );
    }
  }
}

function invalidProxy(message: string): Error {
  return new Error(`invalid proxyServer: ${message}`);
}

function parseAllowedProxyHostname(raw: string): string {
  const value = raw.trim().toLowerCase();
  if (!value || /[\s\u0000-\u001f\u007f]/.test(value)) {
    throw invalidProxy('allowed hostnames must be non-empty DNS names without whitespace');
  }
  const wildcard = value.startsWith('*.');
  const hostname = wildcard ? value.slice(2) : value;
  if (!hostname || hostname === 'localhost' || hostname.endsWith('.localhost')) {
    throw invalidProxy('allowed hostnames must be public DNS names');
  }
  assertValidDnsName(hostname, 'allowed hostnames');
  let parsed: URL;
  try {
    parsed = new URL(`https://${hostname}`);
  } catch {
    throw invalidProxy('allowed hostnames must be valid DNS names');
  }
  if (
    parsed.hostname !== hostname
    || parsed.port
    || parsed.username
    || parsed.password
    || parsed.pathname !== '/'
    || parsed.search
    || parsed.hash
  ) {
    throw invalidProxy('allowed hostnames must not include a scheme, port, path, or credentials');
  }
  if (
    !hostname.includes('.')
    || hostname.startsWith('.')
    || hostname.endsWith('.')
    || /^\d+(?:\.\d+){3}$/.test(hostname)
    || hostname.includes(':')
    || hostname.endsWith('.local')
    || hostname.endsWith('.internal')
  ) {
    throw invalidProxy('allowed hostnames must be public DNS names, not IP or local-network targets');
  }
  return wildcard ? `*.${hostname}` : hostname;
}

function parseAllowedProxyHostnames(raw: unknown): readonly string[] | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_ALLOWED_HOSTNAMES) {
    throw invalidProxy(`allowed hostnames must contain 1-${MAX_ALLOWED_HOSTNAMES} DNS patterns`);
  }
  const normalized = Array.from(new Set(raw.map((value) => {
    if (typeof value !== 'string') {
      throw invalidProxy('allowed hostnames must be strings');
    }
    return parseAllowedProxyHostname(value);
  })));
  return normalized.toSorted();
}

/** Parse and canonicalize a per-start proxy route without exposing credentials. */
export function parseBrowserProxyServer(
  raw: unknown,
  rawAllowedHostnames?: unknown,
): BrowserProxyRoute {
  if (raw === undefined || raw === null) {
    if (rawAllowedHostnames !== undefined && rawAllowedHostnames !== null) {
      throw invalidProxy('allowed hostnames require proxyServer');
    }
    return { mode: 'direct' };
  }
  if (typeof raw !== 'string') {
    throw invalidProxy('expected a URL string');
  }
  const value = raw.trim();
  if (!value || /[\s\u0000-\u001f\u007f]/.test(value)) {
    throw invalidProxy('must be a non-empty URL without whitespace');
  }
  if (value.length > MAX_PROXY_SERVER_LENGTH) {
    throw invalidProxy(`must be at most ${MAX_PROXY_SERVER_LENGTH} characters`);
  }
  if (value.includes(',') || value.includes(';') || value.includes('"') || value.includes("'")) {
    throw invalidProxy('proxy lists and argument quoting are not supported');
  }

  // Validate the caller's spelling before WHATWG URL canonicalization. Inputs
  // such as `/.` and `/%2e` normalize to `/`; accepting them would violate the
  // authority-only contract while looking indistinguishable after parsing.
  const schemeSeparator = value.indexOf('://');
  const authorityAndSuffix = schemeSeparator >= 0 ? value.slice(schemeSeparator + 3) : '';
  const authority = authorityAndSuffix.endsWith('/')
    ? authorityAndSuffix.slice(0, -1)
    : authorityAndSuffix;
  if (!authority || /[/?#]/.test(authority)) {
    throw invalidProxy('path, query, and fragment are not supported');
  }
  const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
  if (hostPort.startsWith('[')) {
    const closingBracket = hostPort.indexOf(']');
    if (closingBracket < 0) throw invalidProxy('port is malformed');
    const suffix = hostPort.slice(closingBracket + 1);
    if (suffix !== '' && !/^:\d+$/.test(suffix)) {
      throw invalidProxy('port is malformed');
    }
  } else {
    const colon = hostPort.lastIndexOf(':');
    if (colon >= 0 && !/^\d+$/.test(hostPort.slice(colon + 1))) {
      throw invalidProxy('port is malformed');
    }
  }

  let parsed: URL;
  try {
    parsed = new URL(value);
  } catch {
    throw invalidProxy('must use a supported proxy URL format');
  }
  if (!SUPPORTED_SCHEMES.has(parsed.protocol)) {
    throw invalidProxy('scheme must be http, https, socks, socks4, or socks5');
  }
  if (!parsed.hostname || parsed.host === '') {
    throw invalidProxy('host is required');
  }
  // IPv6 literals are bracketed by URL.hostname and carry no DNS labels.
  if (!parsed.hostname.startsWith('[')) {
    assertValidDnsName(parsed.hostname, 'proxy host');
  }
  if (parsed.port && (!/^\d+$/.test(parsed.port) || Number(parsed.port) > 65535)) {
    throw invalidProxy('port is malformed');
  }
  if ((parsed.pathname !== '' && parsed.pathname !== '/') || parsed.search || parsed.hash) {
    throw invalidProxy('path, query, and fragment are not supported');
  }

  // Authenticated proxies are NOT supported: the only mechanism that answers a
  // proxy challenge over connectOverCDP (Playwright's context-wide
  // setHTTPCredentials) also sends the credentials to any origin that returns
  // WWW-Authenticate, and allowlisted page content is untrusted — a visited
  // site could harvest the proxy credentials (verified against Chrome 151).
  // Reject userinfo at the parse boundary so this is a loud, fail-closed error
  // rather than a browser that silently launches without working auth. See the
  // authenticated-proxy follow-up before re-enabling.
  if (parsed.username !== '' || parsed.password !== '') {
    throw invalidProxy('authenticated proxies are not supported; omit the username and password');
  }
  const allowedHostnames = parseAllowedProxyHostnames(rawAllowedHostnames);

  // URL.host is already normalized (including bracketed IPv6 literals and a
  // canonicalized port).
  const server = `${parsed.protocol}//${parsed.host}`;
  return {
    mode: 'proxied',
    server,
    ...(allowedHostnames ? { allowedHostnames } : {}),
  };
}

/** Return a stable route key suitable for idempotence checks. */
export function browserProxyRouteKey(route: BrowserProxyRoute): string {
  return JSON.stringify([
    route.mode,
    route.server ?? null,
    route.username ?? null,
    route.password ?? null,
    route.allowedHostnames ?? null,
  ]);
}

/** Safe status/result representation; credentials are deliberately omitted. */
export function redactBrowserProxyRoute(route: BrowserProxyRoute | undefined): {
  mode: 'direct' | 'proxied' | 'unknown';
  server?: string;
} {
  if (!route) return { mode: 'unknown' };
  return route.mode === 'direct'
    ? { mode: 'direct' }
    : { mode: 'proxied', server: route.server };
}

/**
 * Whether a page request URL is permitted while a proxied route is active.
 *
 * Mirrors the vendored navigation guard's fail-closed explicit-proxy policy at
 * the request level: HTTPS only, hostname must match the launch allowlist, and
 * an absent/empty allowlist permits nothing. Uses the same normalization and
 * wildcard semantics (`*.example.com` matches subdomains, not the apex) as the
 * navigation-time checks so both layers agree.
 */
export function isBrowserProxyRequestUrlAllowed(
  rawUrl: string,
  route: BrowserProxyRoute,
): boolean {
  if (route.mode !== 'proxied') return true;
  let parsed: URL;
  try {
    parsed = new URL(rawUrl);
  } catch {
    return false;
  }
  if (parsed.protocol !== 'https:') return false;
  const hostname = normalizeHostname(parsed.hostname);
  // An allowlist entry is only a NAME, so matching it does not prove the target
  // is public. Apply the same host/IP policy the navigation guard uses, which
  // rejects loopback/RFC1918/metadata literals and known-internal names.
  //
  // This name-only check is the first half of the gate; callers on the request
  // path use `isBrowserProxyRequestUrlAllowedAsync`, which adds DNS-answer
  // verification for names that only reveal a private address on resolution.
  if (isBlockedHostnameOrIp(hostname)) return false;
  const allowlist = (route.allowedHostnames ?? []).map((pattern) => normalizeHostname(pattern));
  if (allowlist.length === 0) return false;
  return matchesHostnameAllowlist(hostname, allowlist);
}

const dnsVerdictCache = new Map<string, { allowed: boolean; expiresAt: number }>();
const DNS_VERDICT_TTL_MS = 30_000;
const DNS_VERDICT_CACHE_MAX = 256;

/**
 * Request-level gate including DNS-answer verification.
 *
 * Extends {@link isBrowserProxyRequestUrlAllowed} by resolving the destination
 * and rejecting private/special-use answers, so a name that passes the textual
 * allowlist but resolves inward (`127.0.0.1.nip.io`, or a rebinding answer) is
 * refused before the paused request is continued.
 *
 * SCOPE: this verifies what *this host* resolves. Under an explicit proxy the
 * proxy performs its own resolution, so a proxy with split-horizon DNS can
 * still map an allowlisted public name to an address only it can reach. That
 * residual trust is inherent to delegating egress to an operator-chosen proxy —
 * the same reason the vendored navigation guard demands an explicit allowlist
 * for proxied navigation rather than relying on resolution alone.
 *
 * Only DENIALS are cached (short TTL, bounded). An allow is never cached: that
 * would give a name whose DNS an attacker controls a stable window in which
 * requests skip resolution entirely, which is precisely the rebinding this
 * check exists to catch.
 */
export async function isBrowserProxyRequestUrlAllowedAsync(
  rawUrl: string,
  route: BrowserProxyRoute,
  deps: { lookupFn?: LookupFn; now?: () => number } = {},
): Promise<boolean> {
  // Name-level policy first: cheap, and it denies most traffic without a lookup.
  if (!isBrowserProxyRequestUrlAllowed(rawUrl, route)) return false;
  if (route.mode !== 'proxied') return true;

  let hostname: string;
  try {
    hostname = normalizeHostname(new URL(rawUrl).hostname);
  } catch {
    return false;
  }

  const now = deps.now ?? Date.now;
  const cached = dnsVerdictCache.get(hostname);
  // Only DENIALS are cached. Caching an allow would hand an attacker a stable
  // bypass: an allowlisted name under their control answers publicly once,
  // then repoints at loopback/RFC1918, and every request inside the window
  // skips resolution here while the proxy connects to the new private answer.
  // Re-resolving each time costs a lookup the OS resolver has usually already
  // cached; a cached allow costs correctness.
  if (cached && !cached.allowed && cached.expiresAt > now()) return false;

  let allowed: boolean;
  try {
    // Deliberately NOT forwarding the route allowlist as `hostnameAllowlist`:
    // that field grants exact-host trust and would skip the very private-answer
    // check this call exists to perform.
    //
    // ONE range exemption is forwarded, and it must match what the managed
    // config grants the navigation guard (browser-managed-config.ts) — a policy
    // that differed from the guard's would mean the two layers disagree about
    // the same hostname. It covers fake-IP DNS from Clash/Surge/sing-box, where
    // ordinary public hostnames resolve into 198.18.0.0/15; without it this gate
    // refuses every request on such a machine and proxy mode is unusable. That
    // range is reserved for benchmarking, so exempting it cannot reach a real
    // service.
    //
    // IPv6 ULA is deliberately NOT exempted here. fc00::/7 is where real
    // internal services live and the flag cannot distinguish one from a fake
    // IP, so exempting it would let an allowlisted name that answers with a
    // private AAAA through — the exact inward resolution this call exists to
    // refuse. An IPv6 fake-IP setup therefore has to use direct mode.
    await resolvePinnedHostnameWithPolicy(hostname, {
      ...(deps.lookupFn ? { lookupFn: deps.lookupFn } : {}),
      policy: {
        allowRfc2544BenchmarkRange: true,
      },
    });
    allowed = true;
  } catch {
    // Blocked answer, or the name did not resolve — fail closed either way.
    allowed = false;
  }

  if (allowed) {
    // A name that previously resolved privately may legitimately recover, so a
    // stale denial must not outlive its TTL either.
    dnsVerdictCache.delete(hostname);
    return true;
  }
  if (dnsVerdictCache.size >= DNS_VERDICT_CACHE_MAX) {
    const oldest = dnsVerdictCache.keys().next();
    if (!oldest.done) dnsVerdictCache.delete(oldest.value);
  }
  dnsVerdictCache.set(hostname, { allowed: false, expiresAt: now() + DNS_VERDICT_TTL_MS });
  return false;
}

/** Test seam: drop cached DNS verdicts. */
export function resetBrowserProxyDnsVerdictCache(): void {
  dnsVerdictCache.clear();
}

/** Redact proxy URL credentials in arbitrary error/log text. */
export function redactBrowserProxyText(value: unknown): string {
  const text = value instanceof Error ? value.message : String(value);
  return text.replace(/([a-z][a-z0-9+.-]*:\/\/)(\S+)/gi, (match, scheme: string, rest: string) => {
    // Use the last delimiter so even malformed/unescaped @ in credentials is
    // fully removed rather than leaving the password suffix visible.
    const delimiter = rest.lastIndexOf('@');
    return delimiter < 0 ? match : `${scheme}[REDACTED]@${rest.slice(delimiter + 1)}`;
  });
}