SOCKS5 Client for Node.js

1.2.8 · maintenance · verified Tue Apr 21

This package provides a low-level, unopinionated SOCKS v5 client socket implementation specifically designed for Node.js. It allows developers to proxy raw TCP connections through a SOCKSv5 server by wrapping a standard `net.Socket` and performing the SOCKSv5 handshake. First published in 2012 and last updated seven years ago (version 1.2.8), its release cadence is effectively abandoned, although the package remains available and functional for its specific niche. It serves as a foundational component for other packages like `socks5-http-client` and `socks5-https-client`. Unlike more modern SOCKS client libraries, `socks5-client` focuses solely on the SOCKSv5 protocol, operates synchronously, and does not include modern JavaScript features like Promises or built-in TypeScript definitions. Its key differentiator is its minimalist approach, providing direct control over the underlying socket stream for advanced use cases.

Common errors

Warnings

Install

Imports

Quickstart

This example demonstrates how to establish a SOCKSv5 proxied TCP connection to `example.com` on port 80. It first connects a raw `net.Socket` to the SOCKS5 proxy, then uses `socks5-client` to perform the SOCKS5 handshake and obtain a `destinationSocket` which is then used to send an HTTP GET request to the target host.

const net = require('net');
const SocksClient = require('socks5-client');

const PROXY_HOST = process.env.SOCKS5_PROXY_HOST || '127.0.0.1';
const PROXY_PORT = parseInt(process.env.SOCKS5_PROXY_PORT || '1080', 10);
const TARGET_HOST = 'example.com';
const TARGET_PORT = 80;

// Create a raw TCP socket to connect to the SOCKS5 proxy
const proxySocket = net.connect(PROXY_PORT, PROXY_HOST, () => {
  console.log(`Connected to SOCKS5 proxy at ${PROXY_HOST}:${PROXY_PORT}`);

  // Instantiate SocksClient with the proxy connection
  const socksClient = new SocksClient();

  // Initiate the SOCKS5 handshake to connect to the target host
  socksClient.connect(
    TARGET_PORT,
    TARGET_HOST,
    // Optional: add 'socksUsername', 'socksPassword' to options for auth
    // { socksUsername: 'user', socksPassword: 'pass' },
    proxySocket, // Pass the connected proxySocket
    (err, destinationSocket) => {
      if (err) {
        console.error('SOCKS5 connection failed:', err.message);
        proxySocket.end();
        return;
      }
      console.log(`Successfully connected to ${TARGET_HOST}:${TARGET_PORT} via SOCKS5 proxy.`);

      // Now destinationSocket is the proxied socket, ready for application data
      const request = [
        'GET / HTTP/1.1',
        `Host: ${TARGET_HOST}`,
        'Connection: close',
        '',
        ''
      ].join('\r\n');

      destinationSocket.write(request);

      destinationSocket.on('data', (data) => {
        console.log('Received data from target:', data.toString().substring(0, 200) + '...');
      });

      destinationSocket.on('end', () => {
        console.log('Target connection ended.');
        proxySocket.end();
      });

      destinationSocket.on('error', (data) => {
        console.error('Target socket error:', data.message);
        proxySocket.end();
      });
    }
  );
});

proxySocket.on('error', (err) => {
  console.error('Proxy socket error:', err.message);
});

view raw JSON →