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。

18.3 KB
Raw Blame
/**
 * SOCKS5 出站代理支持(RFC 1928 + RFC 1929 用户名/密码认证)——
 *
 * 背景:出站代理原先只认明文 HTTP 代理(见 outbound-proxy.ts)。代理软件跑「系统代理」
 * 模式却只提供 SOCKS 出口时,解析器全部跳过 → 回落裸直连 → 由 **本机** 解析上游域名;
 * 本地 DNS 解不出(污染 / 公司 DNS / 依赖代理软件的远端 DNS)就必然
 * `getaddrinfo ENOTFOUND <上游>` → 客户端收 502 "upstream unreachable"。
 *
 * 本模块手写 SOCKS5 客户端(本包对外部署要求零运行时依赖,见 build.mjs),提供:
 *   - socks5Connect:完成协商 / 认证 / CONNECT,返回已就绪的隧道 socket
 *   - Socks5HttpsAgent:隧道之上做 TLS(端到端,代理只见密文),keep-alive 复用
 *   - Socks5HttpAgent :隧道直接当 http 连接用(http 上游无需 TLS 包装)
 *
 * **DNS 一律交给代理端解析**:目标是域名时用 ATYP=0x03 原样送出,不在本地预解析。
 * curl 用 `socks5://` / `socks5h://` 区分本地 / 远端解析,本模块不做这个区分 ——
 * 本地解析正是上面那条故障链的起点,在这里没有任何收益。只有上游本身写成 IP 字面量
 * 时才用 ATYP=0x01 / 0x04。
 */

import { Agent as HttpAgent, type ClientRequestArgs } from 'node:http';
import { Agent as HttpsAgent, type AgentOptions } from 'node:https';
import { connect as netConnect, isIPv4, isIPv6, type Socket, type TcpSocketConnectOpts } from 'node:net';
import type { Duplex } from 'node:stream';

import {
  formatAuthority,
  SOCKS5_CREDENTIAL_MAX_BYTES,
  stripIpv6Brackets,
  type OutboundProxyTarget,
} from './outbound-proxy.js';

// 握手整体超时(TCP 连上代理 → CONNECT 回复读完)。与 HTTP 代理 CONNECT 的
// PROXY_CONNECT_TIMEOUT_MS 对齐:代理通常在本机/局域网,正常毫秒级完成,上限只防
// 代理软件假死时无限悬挂;不宜过短,代理背后可能还要现拨远端节点。
const SOCKS5_HANDSHAKE_TIMEOUT_MS = 15 * 1000;

// 连接代理自身的 Happy Eyeballs 单地址握手超时,同样与 HTTP 代理路径一致
// (代理写成 DNS 名且解出多地址时,Node 默认 250ms per-attempt 会把候选逐个砍死)。
const SOCKS5_CONNECT_ATTEMPT_TIMEOUT_MS = 2500;

const VERSION = 0x05;
const AUTH_NONE = 0x00;
const AUTH_USERPASS = 0x02;
const AUTH_NONE_ACCEPTABLE = 0xff;
const USERPASS_SUBNEGOTIATION_VERSION = 0x01;
const CMD_CONNECT = 0x01;
const ATYP_IPV4 = 0x01;
const ATYP_DOMAIN = 0x03;
const ATYP_IPV6 = 0x04;
const REP_SUCCEEDED = 0x00;

/** RFC 1928 §6 的 REP 码 → 可读原因;未知码回落十六进制,不吞掉信息。 */
function replyErrorText(rep: number): string {
  switch (rep) {
    case 0x01: return 'general SOCKS server failure';
    case 0x02: return 'connection not allowed by ruleset';
    case 0x03: return 'network unreachable';
    case 0x04: return 'host unreachable';
    case 0x05: return 'connection refused';
    case 0x06: return 'TTL expired';
    case 0x07: return 'command not supported';
    case 0x08: return 'address type not supported';
    default: return `unknown reply code 0x${rep.toString(16).padStart(2, '0')}`;
  }
}

/**
 * IPv6 字面量 → 16 字节。Node 没有内置 API,这里按 RFC 4291 文本形式手解:支持 `::`
 * 压缩与末段内嵌 IPv4(`::ffff:1.2.3.4`)。调用方已用 isIPv6 校验过格式,解析失败
 * (理论上不可达)返回 null 由调用方回落成错误,不静默发出错误地址。
 */
export function ipv6ToBytes(address: string): Buffer | null {
  // 去掉可能的 zone id(`fe80::1%en0`)—— SOCKS5 目标地址里没有 zone 的位置。
  const bare = address.split('%')[0];
  const doubleColon = bare.indexOf('::');
  const headText = doubleColon === -1 ? bare : bare.slice(0, doubleColon);
  const tailText = doubleColon === -1 ? '' : bare.slice(doubleColon + 2);

  const toGroups = (text: string): number[] | null => {
    if (!text) return [];
    const groups: number[] = [];
    for (const part of text.split(':')) {
      if (!part) return null;
      if (part.includes('.')) {
        // 内嵌 IPv4 只可能出现在最后,占两个 16-bit 组。
        if (!isIPv4(part)) return null;
        const octets = part.split('.').map(Number);
        groups.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
        continue;
      }
      if (!/^[0-9a-fA-F]{1,4}$/.test(part)) return null;
      groups.push(parseInt(part, 16));
    }
    return groups;
  };

  const head = toGroups(headText);
  const tail = toGroups(tailText);
  if (!head || !tail) return null;
  const fill = 8 - head.length - tail.length;
  if (doubleColon === -1 ? fill !== 0 : fill < 0) return null;
  const groups = [...head, ...new Array<number>(Math.max(fill, 0)).fill(0), ...tail];
  if (groups.length !== 8) return null;
  const out = Buffer.alloc(16);
  groups.forEach((group, i) => out.writeUInt16BE(group, i * 2));
  return out;
}

/**
 * 把目标地址编码成 SOCKS5 的 ATYP + ADDR 段。域名走 ATYP_DOMAIN 交给代理解析
 * (见文件头注释);域名超 255 字节无法表达,返回 null。
 *
 * 先剥 IPv6 方括号:上游 URL 里的 `https://[2001:db8::1]` 经 WHATWG URL 解析后
 * hostname 恒带方括号,且 Node 把它原样传到 agent 的 `options.host`(实测)。
 * 不剥的话 isIPv6 判否,地址会被当成**域名**连括号一起发出去,代理拿去做 DNS
 * 解析必然失败。
 */
function encodeDestination(rawHost: string): Buffer | null {
  const host = stripIpv6Brackets(rawHost);
  if (isIPv4(host)) {
    return Buffer.concat([Buffer.of(ATYP_IPV4), Buffer.from(host.split('.').map(Number))]);
  }
  if (isIPv6(host)) {
    const bytes = ipv6ToBytes(host);
    return bytes ? Buffer.concat([Buffer.of(ATYP_IPV6), bytes]) : null;
  }
  const domain = Buffer.from(host, 'utf8');
  if (domain.length === 0 || domain.length > 255) return null;
  return Buffer.concat([Buffer.of(ATYP_DOMAIN, domain.length), domain]);
}

/** 回复里 BND.ADDR 段的长度(不含 ATYP 本身);域名形态的长度前缀由调用方先读一字节。 */
function boundAddressLength(atyp: number, domainLength: number): number | null {
  if (atyp === ATYP_IPV4) return 4;
  if (atyp === ATYP_IPV6) return 16;
  if (atyp === ATYP_DOMAIN) return domainLength;
  return null;
}

/**
 * 顺序读取器 —— 握手是严格的请求/应答往返,用 `read(n)` 表达最直观。socket 出错或
 * 提前关闭时唤醒等待者,不留悬挂 Promise;`release()` 摘掉 listener 并把多读的字节
 * 塞回流(合规代理不会提前发数据,但不合规的会)。
 */
function createSocketReader(socket: Socket): {
  read: (n: number) => Promise<Buffer>;
  fail: (err: Error) => void;
  release: () => void;
} {
  // 显式标注 Buffer(默认 ArrayBufferLike):socket 'data' 给的 chunk 与 alloc 出来的
  // 具体 ArrayBuffer 类型参数不同,不标注会在 concat 赋值处类型不兼容。
  let buffered: Buffer = Buffer.alloc(0);
  let waiter: { need: number; resolve: (b: Buffer) => void; reject: (e: Error) => void } | null = null;
  // socket 出错 / 提前关闭后记在这里,让后续 read 同步失败而不是空等到握手超时。
  let terminalError: Error | null = null;

  const settleIfReady = (): void => {
    if (!waiter || buffered.length < waiter.need) return;
    const { need, resolve } = waiter;
    waiter = null;
    resolve(buffered.subarray(0, need));
    buffered = buffered.subarray(need);
  };
  const onData = (chunk: Buffer): void => {
    buffered = buffered.length === 0 ? chunk : Buffer.concat([buffered, chunk]);
    settleIfReady();
  };
  socket.on('data', onData);

  return {
    read(n: number): Promise<Buffer> {
      return new Promise<Buffer>((resolve, reject) => {
        // socket 已经出错 / 关闭:立刻失败,不要挂到握手超时才发现。今天的握手是
        // 一条线性 await 链(每次 read resolve 后的微任务里就挂上了下一个 waiter,
        // 早于任何 I/O 回调),所以「无 waiter 时出错」这个窗口够不到;记住终止错误
        // 是为了将来万一在两次 read 之间插入 await,不至于静默退化成 15s 空等。
        if (terminalError) { reject(terminalError); return; }
        // 握手是串行的,同一时刻只会有一个等待者;并发读是编码错误。
        if (waiter) { reject(new Error('socks5: concurrent read')); return; }
        waiter = { need: n, resolve, reject };
        settleIfReady();
      });
    },
    fail(err: Error): void {
      // 保留第一个错误 —— 它最接近根因(后续的 close 只是它的后果)。
      terminalError ??= err;
      const pending = waiter;
      waiter = null;
      pending?.reject(err);
    },
    release(): void {
      socket.off('data', onData);
      // 失败路径上 socket 可能已经销毁,此时 unshift 会抛;只在还活着时塞回。
      if (buffered.length > 0 && !socket.destroyed) socket.unshift(buffered);
      // 注意:这里**不能** pause()。挂过 'data' 已把流切进 flowing,显式 pause 会让
      // readableFlowing=false,而 http.Agent / tls 接管时只是 on('data'),不会主动
      // resume —— 那才是真正的挂起。flowing 状态下的空档只存在于「release 到下一个
      // 消费者接管」之间,调用方必须在同一个同步块里把 socket 交出去(见两个 agent)。
    },
  };
}

/**
 * 连到 SOCKS5 代理并把隧道打到 `destHost:destPort`,返回已就绪的裸 socket
 * (之后可直接当 TCP 用,或在其上做 TLS)。任何失败都 destroy socket 并抛错,
 * 错误信息统一带上代理地址(脱敏形态)与目标,便于从 502 body 一眼定位失败在哪一跳。
 */
export async function socks5Connect(
  proxy: OutboundProxyTarget,
  destHost: string,
  destPort: number,
): Promise<Socket> {
  const authority = formatAuthority(destHost, destPort);
  // cause 保留底层 errno:server.ts 的 502 分类要沿错误链找 ECONNREFUSED + 回环地址。
  const fail = (message: string, cause?: unknown): Error =>
    new Error(`outbound proxy ${proxy.url} ${message}`, cause === undefined ? undefined : { cause });

  const destination = encodeDestination(destHost);
  if (!destination) throw fail(`cannot encode destination ${authority}`);

  const connectOptions: TcpSocketConnectOpts & { autoSelectFamilyAttemptTimeout?: number } = {
    host: proxy.hostname,
    port: proxy.port,
    autoSelectFamilyAttemptTimeout: SOCKS5_CONNECT_ATTEMPT_TIMEOUT_MS,
  };
  const socket = netConnect(connectOptions);
  socket.setNoDelay(true);
  const reader = createSocketReader(socket);

  let timedOut = false;
  const timer = setTimeout(() => {
    timedOut = true;
    const err = fail(`CONNECT ${authority} timed out`);
    reader.fail(err);
    socket.destroy(err);
  }, SOCKS5_HANDSHAKE_TIMEOUT_MS);
  // 握手期的定时器不该拖住进程退出(Node 允许 unref;某些运行时无此方法)。
  timer.unref?.();

  // socket 层错误 / 提前 EOF 唤醒等待中的 read,避免握手 Promise 永久悬挂。
  const onError = (err: Error): void => {
    reader.fail(timedOut ? fail(`CONNECT ${authority} timed out`) : fail(`unreachable: ${err.message}`, err));
  };
  const onClose = (): void => {
    reader.fail(timedOut
      ? fail(`CONNECT ${authority} timed out`)
      : fail(`closed the connection during the SOCKS5 handshake`));
  };
  socket.on('error', onError);
  socket.on('close', onClose);

  try {
    await new Promise<void>((resolve, reject) => {
      if (!socket.connecting) { resolve(); return; }
      socket.once('connect', resolve);
      socket.once('error', (err: Error) => reject(fail(`unreachable: ${err.message}`, err)));
      socket.once('close', () => reject(fail('unreachable: connection closed')));
    });

    // ── 方法协商 ──────────────────────────────────────────────────────────
    const methods = proxy.username ? [AUTH_NONE, AUTH_USERPASS] : [AUTH_NONE];
    socket.write(Buffer.from([VERSION, methods.length, ...methods]));
    const greeting = await reader.read(2);
    if (greeting[0] !== VERSION) throw fail(`is not a SOCKS5 proxy (server version 0x${greeting[0].toString(16)})`);
    const method = greeting[1];
    if (method === AUTH_NONE_ACCEPTABLE) {
      throw fail(proxy.username
        ? 'rejected both anonymous and username/password authentication'
        : 'requires authentication but none is configured');
    }

    // ── RFC 1929 用户名/密码认证 ──────────────────────────────────────────
    if (method === AUTH_USERPASS) {
      if (!proxy.username) throw fail('requires username/password authentication but none is configured');
      const user = Buffer.from(proxy.username, 'utf8');
      const pass = Buffer.from(proxy.password ?? '', 'utf8');
      // UNAME / PASSWD 都是单字节长度前缀。parseOutboundProxyUrl 已把超长凭证降级成
      // 「无凭证」,但两个 agent 是公开导出的,宿主可以自己造 target —— 那条路上长度
      // 会静默溢出成错误的帧(300 → 44),把乱码凭证发给代理。fail fast。
      if (user.length > SOCKS5_CREDENTIAL_MAX_BYTES || pass.length > SOCKS5_CREDENTIAL_MAX_BYTES) {
        throw fail(`credentials exceed the RFC 1929 limit of ${SOCKS5_CREDENTIAL_MAX_BYTES} bytes`);
      }
      socket.write(Buffer.concat([
        Buffer.of(USERPASS_SUBNEGOTIATION_VERSION, user.length),
        user,
        Buffer.of(pass.length),
        pass,
      ]));
      const authReply = await reader.read(2);
      // 版本必须是子协商的 0x01。对不上说明流已经错位(代理实现不合规或读串了),
      // 此时 status 字节也不可信,不能当成认证成功继续往下走。
      if (authReply[0] !== USERPASS_SUBNEGOTIATION_VERSION) {
        throw fail(`returned an unexpected auth subnegotiation version 0x${authReply[0].toString(16).padStart(2, '0')}`);
      }
      // 状态非 0 即失败(不回显任何凭证内容)。
      if (authReply[1] !== 0x00) throw fail('rejected the username/password credentials');
    } else if (method !== AUTH_NONE) {
      throw fail(`selected unsupported authentication method 0x${method.toString(16).padStart(2, '0')}`);
    }

    // ── CONNECT ──────────────────────────────────────────────────────────
    const portBytes = Buffer.alloc(2);
    portBytes.writeUInt16BE(destPort);
    socket.write(Buffer.concat([Buffer.of(VERSION, CMD_CONNECT, 0x00), destination, portBytes]));

    const reply = await reader.read(4);
    if (reply[1] !== REP_SUCCEEDED) {
      throw fail(`CONNECT ${authority} failed: ${replyErrorText(reply[1])}`);
    }
    // BND.ADDR / BND.PORT 用不上,但必须读完,否则残留字节会污染隧道数据。
    const atyp = reply[3];
    const domainLength = atyp === ATYP_DOMAIN ? (await reader.read(1))[0] : 0;
    const addrLength = boundAddressLength(atyp, domainLength);
    if (addrLength === null) throw fail(`returned an unsupported bound address type 0x${atyp.toString(16)}`);
    await reader.read(addrLength + 2);

    clearTimeout(timer);
    socket.off('error', onError);
    socket.off('close', onClose);
    reader.release();
    return socket;
  } catch (err) {
    clearTimeout(timer);
    socket.off('error', onError);
    socket.off('close', onClose);
    reader.release();
    // 摘掉上面的 listener 后 socket 就没有 'error' 消费者了,销毁过程中再冒出的
    // ECONNRESET 会变成未捕获异常;挂一个空 listener 兜住。
    socket.on('error', () => {});
    socket.destroy();
    throw err instanceof Error ? err : new Error(String(err));
  }
}

/**
 * https 上游经 SOCKS5 隧道的 keep-alive Agent。握手拿到裸 socket 后交回
 * https.Agent 原生 createConnection(`socket` 选项)完成 TLS —— TLS 端到端,
 * SNI / 证书校验 / session 复用全部沿用 Node 原生逻辑,代理只见密文。
 * 与 HTTP 代理路径的 TunnelingHttpsAgent 同构。
 */
export class Socks5HttpsAgent extends HttpsAgent {
  private readonly proxy: OutboundProxyTarget;

  constructor(proxy: OutboundProxyTarget, opts?: AgentOptions) {
    super({ keepAlive: true, ...opts });
    this.proxy = proxy;
  }

  override createConnection(
    options: ClientRequestArgs,
    callback?: (err: Error | null, stream: Duplex) => void,
  ): Duplex | null | undefined {
    // http.Agent 运行时恒以 callback 形态调用(createSocket → oncreate);无 callback
    // 时无法异步建连,直接失败比静默直连安全。
    if (!callback) throw new Error('Socks5HttpsAgent requires callback-style createConnection');
    const settle = callback as (err: Error | null, stream?: Duplex) => void;
    socks5Connect(this.proxy, options.host ?? 'localhost', Number(options.port) || 443)
      .then((socket) => {
        try {
          const tlsSocket = (HttpsAgent.prototype as unknown as {
            createConnection: (opts: unknown) => Duplex;
          }).createConnection.call(this, { ...options, socket });
          settle(null, tlsSocket);
        } catch (err) {
          socket.destroy();
          settle(err instanceof Error ? err : new Error(String(err)));
        }
      })
      .catch((err: unknown) => settle(err instanceof Error ? err : new Error(String(err))));
    // socket 走异步 callback 交付;返回 undefined 告知调用方等 callback。
    return undefined;
  }
}

/**
 * http 上游经 SOCKS5 隧道的 keep-alive Agent。SOCKS 是 L4 隧道,隧道建好后就是一条
 * 普通 TCP 连接,请求仍按 origin-form 发给真实上游(不存在 HTTP 代理那种绝对形式)。
 */
export class Socks5HttpAgent extends HttpAgent {
  private readonly proxy: OutboundProxyTarget;

  constructor(proxy: OutboundProxyTarget, opts?: AgentOptions) {
    super({ keepAlive: true, ...opts });
    this.proxy = proxy;
  }

  override createConnection(
    options: ClientRequestArgs,
    callback?: (err: Error | null, stream: Duplex) => void,
  ): Duplex | null | undefined {
    if (!callback) throw new Error('Socks5HttpAgent requires callback-style createConnection');
    const settle = callback as (err: Error | null, stream?: Duplex) => void;
    socks5Connect(this.proxy, options.host ?? 'localhost', Number(options.port) || 80)
      .then((socket) => settle(null, socket))
      .catch((err: unknown) => settle(err instanceof Error ? err : new Error(String(err))));
    return undefined;
  }
}