A modern SOCKS5 server implementation with TypeScript support, forked from simple-socks
npm install @apofasi/socksA modern SOCKS5 server implementation with TypeScript support. This package is a modernized TypeScript fork of simple-socks, providing enhanced type safety and modern JavaScript features.
This project is based on simple-socks by brozeph. We've made the following improvements:
- Full TypeScript rewrite with complete type definitions
- Modern JavaScript features and best practices
- Enhanced error handling and type safety
- Improved documentation and examples
- Zero production dependencies
- Full SOCKS5 protocol support (RFC 1928)
- Username/password authentication (RFC 1929)
- TypeScript support with complete type definitions
- Support for IPv4, IPv6, and domain name resolution
- Customizable socket factory for connection handling
- Connection filtering capabilities
- Event-based architecture
- Zero production dependencies
``bash`
npm install @apofasi/socks
`typescript
import { createServer } from '@apofasi/socks';
// Create a server without authentication
const server = createServer();
// Start listening
server.listen(1080, '127.0.0.1', () => {
console.log('SOCKS5 server listening on 127.0.0.1:1080');
});
`
`typescript
import { createServer } from '@apofasi/socks';
// Create a server with authentication
const server = createServer({
authenticate: (username, password, socket, callback) => {
if (username === 'user' && password === 'pass') {
callback(); // Authentication successful
} else {
callback(new Error('Authentication failed'));
}
}
});
server.listen(1080, '127.0.0.1', () => {
console.log('SOCKS5 server with authentication listening on 127.0.0.1:1080');
});
`
`typescript
import { createServer } from '@apofasi/socks';
import { SocksClient } from 'socks';
// Create a server that chains to another SOCKS5 proxy
const server = createServer({
socketFactory: async (destinationAddress, destinationPort) => {
const { socket } = await SocksClient.createConnection({
proxy: {
host: 'next-proxy.example.com',
port: 1080,
type: 5,
},
command: 'connect',
destination: {
host: destinationAddress,
port: destinationPort,
},
});
return socket;
}
});
server.listen(1080);
`
Creates a new SOCKS5 server instance.
#### Options
- authenticate?: (username: string, password: string, socket: Socket, callback: (err?: Error) => void) => void
- Optional authentication handler
- Called when a client attempts to authenticate
- Call callback() for success, callback(error) for failure
- socketFactory?: (address: string, port: number) => Promise
- Optional custom socket factory
- Called when establishing connections to destinations
- Useful for chaining proxies or custom connection handling
- connectionFilter?: (destination: { address: string, port: number }, origin: { address: string, port: number }, callback: (err?: Error) => void) => void
- Optional connection filter
- Called before establishing connections
- Can be used to implement access control
- authenticate - Emitted on successful authenticationauthenticateError
- - Emitted on authentication failureconnectionFilter
- - Emitted when connection filtering occursproxyConnect
- - Emitted when a proxy connection is establishedproxyData
- - Emitted when data is transferredproxyError
- - Emitted on proxy errorsproxyEnd
- - Emitted when a proxy connection ends
`bash`
npm test
This project is a fork of simple-socks and follows its core design principles while adding modern TypeScript support. Contributions are welcome! Here's how you can contribute:
1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)npm test
3. Make your changes
4. Run the tests ()git commit -m 'feat: add amazing feature'
5. Commit your changes ()git push origin feature/amazing-feature
6. Push to the branch ()
7. Open a Pull Request
`bashInstall dependencies
npm install
MIT
- simple-socks - The original project this is forked from
- RFC 1928 - SOCKS Protocol Version 5
- RFC 1929 - Username/Password Authentication for SOCKS V5