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
```