@postalsys/socks5

A SOCKS5 server interface library for Node.js that exposes each established connection as a Duplex stream with metadata information.

Features

• SOCKS5 protocol implementation (RFC 1928)
• Support for CONNECT command
• Optional username/password authentication (RFC 1929)
• Exposes connections as Node.js Duplex streams
• Connection metadata (client IP/port, target IP/port, username)
• IPv4, IPv6, and domain name address support
• Built for Node.js v20+
• Written in CommonJS
• TypeScript definitions included

Installation

npm install @postalsys/socks5

Quick Start

const { SOCKS5Server } = require('@postalsys/socks5');

// Create a SOCKS5 server without authentication
const server = new SOCKS5Server();

server.on('connection', connection => {
    console.log('New connection:', connection.metadata);

    // connection is a Duplex stream
    connection.on('readable', () => {
        let chunk;
        while ((chunk = connection.read()) !== null) {
            console.log('Received:', chunk.toString());
            // Echo back
            connection.write(chunk);
        }
    });

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

server.listen(1080, '127.0.0.1', () => {
    console.log('SOCKS5 server listening on port 1080');
});

Authentication

To enable username/password authentication:

const server = new SOCKS5Server({
    authRequired: true,
    authCallback: (username, password) => {
        // Synchronous authentication
        return username === 'user' && password === 'pass';
    }
});

For asynchronous authentication:

const server = new SOCKS5Server({
    authRequired: true,
    authCallback: (username, password, callback) => {
        // Async authentication (e.g., database lookup)
        checkCredentials(username, password)
            .then(isValid => callback(null, isValid))
            .catch(err => callback(err));
    }
});

Connection Metadata

Each connection provides metadata about the client and target:

server.on('connection', connection => {
    const metadata = connection.metadata;
    console.log('Client:', metadata.clientAddress, metadata.clientPort);
    console.log('Target:', metadata.targetAddress, metadata.targetPort);
    console.log('Username:', metadata.username); // null if no auth
});

API

See API.md for detailed API documentation.

Testing

Run tests using Node.js built-in test runner:

npm test

License

EUPL-1.2

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.