0
# SOCKS
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: socks
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install socks`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  SocksClient, 
16
  SocksClientOptions, 
17
  SocksClientChainOptions,
18
  SocksClientError,
19
  SocksRemoteHost,
20
  SocksProxy,
21
  SocksUDPFrameDetails,
22
  SocksCommand,
23
  Socks4Response,
24
  Socks5Auth,
25
  Socks5Response,
26
  Socks5HostType,
27
  SocksClientState,
28
  validateSocksClientOptions,
29
  validateSocksClientChainOptions,
30
  ipv4ToInt32,
31
  int32ToIpv4,
32
  ipToBuffer
33
} from "socks";
34
```
35

36
For CommonJS:
37

38
```javascript
39
const { 
40
  SocksClient, 
41
  SocksClientOptions, 
42
  SocksClientChainOptions,
43
  SocksClientError,
44
  SocksRemoteHost,
45
  SocksProxy,
46
  SocksUDPFrameDetails,
47
  SocksCommand,
48
  Socks4Response,
49
  Socks5Auth,
50
  Socks5Response,
51
  Socks5HostType,
52
  SocksClientState,
53
  validateSocksClientOptions,
54
  validateSocksClientChainOptions,
55
  ipv4ToInt32,
56
  int32ToIpv4,
57
  ipToBuffer
58
} = require("socks");
59
```
60

61
## Basic Usage
62

63
```typescript
64
import { SocksClient } from "socks";
65

66
// Create a SOCKS connection
67
const info = await SocksClient.createConnection({
68
  proxy: {
69
    host: '127.0.0.1',
70
    port: 1080,
71
    type: 5
72
  },
73
  command: 'connect',
74
  destination: {
75
    host: 'example.com',
76
    port: 80
77
  }
78
});
79

80
console.log('Connected through SOCKS proxy');
81
// Use info.socket for data transmission
82
```
83

84
## Architecture
85

86
SOCKS client is built around several key components:
87

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

95
## Capabilities
96

97
### SOCKS Connection Management
98

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

101
```typescript { .api }
102
class SocksClient extends EventEmitter {
103
  constructor(options: SocksClientOptions);
104
  
105
  static createConnection(
106
    options: SocksClientOptions,
107
    callback?: (error: Error | null, info?: SocksClientEstablishedEvent) => void
108
  ): Promise<SocksClientEstablishedEvent>;
109
  
110
  static createConnectionChain(
111
    options: SocksClientChainOptions,
112
    callback?: (error: Error | null, socket?: SocksClientEstablishedEvent) => void
113
  ): Promise<SocksClientEstablishedEvent>;
114
  
115
  connect(existingSocket?: Duplex): void;
116
  get socksClientOptions(): SocksClientOptions;
117
}
118
```
119

120
### UDP Frame Management
121

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

124
```typescript { .api }
125
static createUDPFrame(options: SocksUDPFrameDetails): Buffer;
126
static parseUDPFrame(data: Buffer): SocksUDPFrameDetails;
127
```
128

129
[UDP Frame Handling](./udp-frames.md)
130

131
### IP Address Utilities
132

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

135
```typescript { .api }
136
function ipv4ToInt32(ip: string): number;
137
function int32ToIpv4(int32: number): string;
138
function ipToBuffer(ip: string): Buffer;
139
```
140

141
### Validation Functions
142

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

145
```typescript { .api }
146
function validateSocksClientOptions(
147
  options: SocksClientOptions,
148
  acceptedCommands?: string[]
149
): void;
150

151
function validateSocksClientChainOptions(
152
  options: SocksClientChainOptions
153
): void;
154
```
155

156
[Validation and Utility Functions](./validation-utilities.md)
157

158
## Types and Interfaces
159

160
### Core Configuration Types
161

162
```typescript { .api }
163
type SocksProxyType = 4 | 5;
164
type SocksCommandOption = 'connect' | 'bind' | 'associate';
165

166
interface SocksProxy {
167
  /** IP address of the proxy (equivalent to host) */
168
  ipaddress?: string;
169
  /** Hostname of the proxy (equivalent to ipaddress) */
170
  host?: string;
171
  /** Port number of the proxy */
172
  port: number;
173
  /** SOCKS protocol version (4 or 5) */
174
  type: SocksProxyType;
175
  /** User ID for SOCKS v4 or username for SOCKS v5 authentication */
176
  userId?: string;
177
  /** Password for SOCKS v5 username/password authentication */
178
  password?: string;
179
  /** Custom authentication method (0x80-0xFE range) */
180
  custom_auth_method?: number;
181
  /** Handler for custom authentication request */
182
  custom_auth_request_handler?: () => Promise<Buffer>;
183
  /** Expected response size for custom authentication */
184
  custom_auth_response_size?: number;
185
  /** Handler for custom authentication response validation */
186
  custom_auth_response_handler?: (data: Buffer) => Promise<boolean>;
187
}
188

189
interface SocksRemoteHost {
190
  /** IPv4, IPv6 address, or hostname */
191
  host: string;
192
  /** Port number (0-65535) */
193
  port: number;
194
}
195
```
196

197
### Connection Options
198

199
```typescript { .api }
200
interface SocksClientOptions {
201
  /** SOCKS command to execute */
202
  command: SocksCommandOption;
203
  /** Remote destination host to connect to via proxy */
204
  destination: SocksRemoteHost;
205
  /** SOCKS proxy server configuration */
206
  proxy: SocksProxy;
207
  /** Connection timeout in milliseconds (default: 30000) */
208
  timeout?: number;
209
  /** Existing socket for proxy chaining (internal use) */
210
  existing_socket?: Duplex;
211
  /** Whether to set TCP_NODELAY on the socket */
212
  set_tcp_nodelay?: boolean;
213
  /** Additional TCP socket connection options */
214
  socket_options?: SocketConnectOpts;
215
}
216

217
interface SocksClientChainOptions {
218
  /** Only 'connect' command supported for chaining */
219
  command: 'connect';
220
  /** Final destination host */
221
  destination: SocksRemoteHost;
222
  /** Array of SOCKS proxies to chain through */
223
  proxies: SocksProxy[];
224
  /** Connection timeout in milliseconds */
225
  timeout?: number;
226
  /** Whether to randomize the proxy chain order */
227
  randomizeChain?: boolean;
228
}
229
```
230

231
### Event Types
232

233
```typescript { .api }
234
interface SocksClientEstablishedEvent {
235
  /** The connected socket ready for data transmission */
236
  socket: Socket;
237
  /** Remote host information (for BIND connections) */
238
  remoteHost?: SocksRemoteHost;
239
}
240

241
type SocksClientBoundEvent = SocksClientEstablishedEvent;
242
```
243

244
### UDP Frame Types
245

246
```typescript { .api }
247
interface SocksUDPFrameDetails {
248
  /** Frame number identifier */
249
  frameNumber?: number;
250
  /** Remote host information */
251
  remoteHost: SocksRemoteHost;
252
  /** UDP packet data */
253
  data: Buffer;
254
}
255
```
256

257
### Protocol Enums
258

259
Constants and enumerations used by the SOCKS protocol implementation.
260

261
```typescript { .api }
262
enum SocksCommand {
263
  connect = 0x01,
264
  bind = 0x02,
265
  associate = 0x03
266
}
267

268
enum Socks4Response {
269
  Granted = 0x5a,
270
  Failed = 0x5b,
271
  Rejected = 0x5c,
272
  RejectedIdent = 0x5d
273
}
274

275
enum Socks5Auth {
276
  NoAuth = 0x00,
277
  GSSApi = 0x01,
278
  UserPass = 0x02
279
}
280

281
enum Socks5Response {
282
  Granted = 0x00,
283
  Failure = 0x01,
284
  NotAllowed = 0x02,
285
  NetworkUnreachable = 0x03,
286
  HostUnreachable = 0x04,
287
  ConnectionRefused = 0x05,
288
  TTLExpired = 0x06,
289
  CommandNotSupported = 0x07,
290
  AddressNotSupported = 0x08
291
}
292

293
enum Socks5HostType {
294
  IPv4 = 0x01,
295
  Hostname = 0x03,
296
  IPv6 = 0x04
297
}
298

299
enum SocksClientState {
300
  Created = 0,
301
  Connecting = 1,
302
  Connected = 2,
303
  SentInitialHandshake = 3,
304
  ReceivedInitialHandshakeResponse = 4,
305
  SentAuthentication = 5,
306
  ReceivedAuthenticationResponse = 6,
307
  SentFinalHandshake = 7,
308
  ReceivedFinalResponse = 8,
309
  BoundWaitingForConnection = 9,
310
  Established = 10,
311
  Disconnected = 11,
312
  Error = 99
313
}
314
```
315

316
## Error Handling
317

318
```typescript { .api }
319
class SocksClientError extends Error {
320
  constructor(message: string, options: SocksClientOptions | SocksClientChainOptions);
321
  options: SocksClientOptions | SocksClientChainOptions;
322
}
323
```
324

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

327
## Event Usage
328

329
```typescript
330
const client = new SocksClient(options);
331

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

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

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

345
client.connect();
346
```