or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdudp-frames.mdvalidation-utilities.md
tile.json

tessl/npm-socks

Fully featured SOCKS proxy client supporting SOCKSv4, SOCKSv4a, and SOCKSv5 with Bind and Associate functionality.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/socks@2.8.x

To install, run

npx @tessl/cli install tessl/npm-socks@2.8.0

index.mddocs/

SOCKS

SOCKS is a fully featured SOCKS proxy client supporting SOCKSv4, SOCKSv4a, and SOCKSv5 protocols. It provides comprehensive connection management with CONNECT, BIND, and ASSOCIATE functionality, including proxy chaining, authentication, and UDP frame handling.

Package Information

  • Package Name: socks
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install socks

Core Imports

import { 
  SocksClient, 
  SocksClientOptions, 
  SocksClientChainOptions,
  SocksClientError,
  SocksRemoteHost,
  SocksProxy,
  SocksUDPFrameDetails,
  SocksCommand,
  Socks4Response,
  Socks5Auth,
  Socks5Response,
  Socks5HostType,
  SocksClientState,
  validateSocksClientOptions,
  validateSocksClientChainOptions,
  ipv4ToInt32,
  int32ToIpv4,
  ipToBuffer
} from "socks";

For CommonJS:

const { 
  SocksClient, 
  SocksClientOptions, 
  SocksClientChainOptions,
  SocksClientError,
  SocksRemoteHost,
  SocksProxy,
  SocksUDPFrameDetails,
  SocksCommand,
  Socks4Response,
  Socks5Auth,
  Socks5Response,
  Socks5HostType,
  SocksClientState,
  validateSocksClientOptions,
  validateSocksClientChainOptions,
  ipv4ToInt32,
  int32ToIpv4,
  ipToBuffer
} = require("socks");

Basic Usage

import { SocksClient } from "socks";

// Create a SOCKS connection
const info = await SocksClient.createConnection({
  proxy: {
    host: '127.0.0.1',
    port: 1080,
    type: 5
  },
  command: 'connect',
  destination: {
    host: 'example.com',
    port: 80
  }
});

console.log('Connected through SOCKS proxy');
// Use info.socket for data transmission

Architecture

SOCKS client is built around several key components:

  • SocksClient Class: Core client implementation extending EventEmitter for connection management
  • Static Factory Methods: createConnection() and createConnectionChain() for easy connection setup
  • Protocol Support: Full implementation of SOCKS v4, v4a, and v5 protocols with authentication
  • Event-Driven Model: Connection lifecycle managed through events (error, bound, established)
  • Proxy Chaining: Support for chaining multiple SOCKS proxies for enhanced privacy
  • UDP Support: UDP frame creation and parsing for SOCKS v5 ASSOCIATE command

Capabilities

SOCKS Connection Management

Core SOCKS proxy connection functionality supporting all major SOCKS protocol versions and commands.

class SocksClient extends EventEmitter {
  constructor(options: SocksClientOptions);
  
  static createConnection(
    options: SocksClientOptions,
    callback?: (error: Error | null, info?: SocksClientEstablishedEvent) => void
  ): Promise<SocksClientEstablishedEvent>;
  
  static createConnectionChain(
    options: SocksClientChainOptions,
    callback?: (error: Error | null, socket?: SocksClientEstablishedEvent) => void
  ): Promise<SocksClientEstablishedEvent>;
  
  connect(existingSocket?: Duplex): void;
  get socksClientOptions(): SocksClientOptions;
}

UDP Frame Management

SOCKS v5 UDP frame creation and parsing for use with the ASSOCIATE command.

static createUDPFrame(options: SocksUDPFrameDetails): Buffer;
static parseUDPFrame(data: Buffer): SocksUDPFrameDetails;

UDP Frame Handling

IP Address Utilities

Utility functions for converting between IP address formats used internally by SOCKS protocols.

function ipv4ToInt32(ip: string): number;
function int32ToIpv4(int32: number): string;
function ipToBuffer(ip: string): Buffer;

Validation Functions

Configuration validation functions for ensuring SOCKS client options are properly formatted.

function validateSocksClientOptions(
  options: SocksClientOptions,
  acceptedCommands?: string[]
): void;

function validateSocksClientChainOptions(
  options: SocksClientChainOptions
): void;

Validation and Utility Functions

Types and Interfaces

Core Configuration Types

type SocksProxyType = 4 | 5;
type SocksCommandOption = 'connect' | 'bind' | 'associate';

interface SocksProxy {
  /** IP address of the proxy (equivalent to host) */
  ipaddress?: string;
  /** Hostname of the proxy (equivalent to ipaddress) */
  host?: string;
  /** Port number of the proxy */
  port: number;
  /** SOCKS protocol version (4 or 5) */
  type: SocksProxyType;
  /** User ID for SOCKS v4 or username for SOCKS v5 authentication */
  userId?: string;
  /** Password for SOCKS v5 username/password authentication */
  password?: string;
  /** Custom authentication method (0x80-0xFE range) */
  custom_auth_method?: number;
  /** Handler for custom authentication request */
  custom_auth_request_handler?: () => Promise<Buffer>;
  /** Expected response size for custom authentication */
  custom_auth_response_size?: number;
  /** Handler for custom authentication response validation */
  custom_auth_response_handler?: (data: Buffer) => Promise<boolean>;
}

interface SocksRemoteHost {
  /** IPv4, IPv6 address, or hostname */
  host: string;
  /** Port number (0-65535) */
  port: number;
}

Connection Options

interface SocksClientOptions {
  /** SOCKS command to execute */
  command: SocksCommandOption;
  /** Remote destination host to connect to via proxy */
  destination: SocksRemoteHost;
  /** SOCKS proxy server configuration */
  proxy: SocksProxy;
  /** Connection timeout in milliseconds (default: 30000) */
  timeout?: number;
  /** Existing socket for proxy chaining (internal use) */
  existing_socket?: Duplex;
  /** Whether to set TCP_NODELAY on the socket */
  set_tcp_nodelay?: boolean;
  /** Additional TCP socket connection options */
  socket_options?: SocketConnectOpts;
}

interface SocksClientChainOptions {
  /** Only 'connect' command supported for chaining */
  command: 'connect';
  /** Final destination host */
  destination: SocksRemoteHost;
  /** Array of SOCKS proxies to chain through */
  proxies: SocksProxy[];
  /** Connection timeout in milliseconds */
  timeout?: number;
  /** Whether to randomize the proxy chain order */
  randomizeChain?: boolean;
}

Event Types

interface SocksClientEstablishedEvent {
  /** The connected socket ready for data transmission */
  socket: Socket;
  /** Remote host information (for BIND connections) */
  remoteHost?: SocksRemoteHost;
}

type SocksClientBoundEvent = SocksClientEstablishedEvent;

UDP Frame Types

interface SocksUDPFrameDetails {
  /** Frame number identifier */
  frameNumber?: number;
  /** Remote host information */
  remoteHost: SocksRemoteHost;
  /** UDP packet data */
  data: Buffer;
}

Protocol Enums

Constants and enumerations used by the SOCKS protocol implementation.

enum SocksCommand {
  connect = 0x01,
  bind = 0x02,
  associate = 0x03
}

enum Socks4Response {
  Granted = 0x5a,
  Failed = 0x5b,
  Rejected = 0x5c,
  RejectedIdent = 0x5d
}

enum Socks5Auth {
  NoAuth = 0x00,
  GSSApi = 0x01,
  UserPass = 0x02
}

enum Socks5Response {
  Granted = 0x00,
  Failure = 0x01,
  NotAllowed = 0x02,
  NetworkUnreachable = 0x03,
  HostUnreachable = 0x04,
  ConnectionRefused = 0x05,
  TTLExpired = 0x06,
  CommandNotSupported = 0x07,
  AddressNotSupported = 0x08
}

enum Socks5HostType {
  IPv4 = 0x01,
  Hostname = 0x03,
  IPv6 = 0x04
}

enum SocksClientState {
  Created = 0,
  Connecting = 1,
  Connected = 2,
  SentInitialHandshake = 3,
  ReceivedInitialHandshakeResponse = 4,
  SentAuthentication = 5,
  ReceivedAuthenticationResponse = 6,
  SentFinalHandshake = 7,
  ReceivedFinalResponse = 8,
  BoundWaitingForConnection = 9,
  Established = 10,
  Disconnected = 11,
  Error = 99
}

Error Handling

class SocksClientError extends Error {
  constructor(message: string, options: SocksClientOptions | SocksClientChainOptions);
  options: SocksClientOptions | SocksClientChainOptions;
}

The client emits detailed error events with descriptive messages for various failure scenarios including connection timeouts, authentication failures, and protocol errors.

Event Usage

const client = new SocksClient(options);

client.on('error', (err: SocksClientError) => {
  console.error('SOCKS connection failed:', err.message);
});

client.on('established', (info: SocksClientEstablishedEvent) => {
  console.log('Connection established');
  // Use info.socket for data transmission
});

client.on('bound', (info: SocksClientBoundEvent) => {
  console.log('BIND connection ready, waiting for incoming connection');
});

client.connect();