pxyd

Lightweight HTTP, HTTPS, and SOCKS proxy server for Node.js.

Features

• HTTP proxy server with normal HTTP forwarding and CONNECT tunneling
• SOCKS proxy server with SOCKS4 and SOCKS5 support
• Optional upstream proxy chaining through HTTP, HTTPS, SOCKS4, or SOCKS5
• Optional HTTPS listener for the HTTP proxy server
• Optional username/password authentication
• Configurable request, tunnel connect, and tunnel idle timeouts
• Loop protection for self-targeting requests and upstream self-reference

Installation

npm install -g pxyd

pxyd --help

CLI

pxyd exposes two commands:

pxyd http [options]
pxyd socks [options]

HTTP Proxy

Starts an HTTP proxy server. If --tls-cert and --tls-key are provided, the proxy listener uses HTTPS.

pxyd http

Defaults:

• Host: 127.0.0.1
• Port: 8080
• Request timeout: 30000 ms
• Tunnel connect timeout: 10000 ms
• Tunnel idle timeout: 120000 ms

Options:

| Option | Description | | --- | --- | | --host <host> | Listen host | | --port <port> | Listen port | | --username <username> | Enable proxy auth with this username | | --password <password> | Enable proxy auth with this password | | --upstream <url> | Forward traffic through an upstream proxy | | --tls-cert <path> | TLS certificate path for HTTPS listener | | --tls-key <path> | TLS private key path for HTTPS listener | | --request-timeout <ms> | Timeout for HTTP proxy requests | | --tunnel-connect-timeout <ms> | Timeout while establishing tunnels | | --tunnel-idle-timeout <ms> | Idle timeout for established tunnels |

Examples:

pxyd http --host 127.0.0.1 --port 8080

curl -x http://127.0.0.1:8080 https://httpbin.org/ip

HTTP proxy authentication:

pxyd http --username admin --password secret

HTTPS proxy listener:

pxyd http \
  --tls-cert ./cert.pem \
  --tls-key ./key.pem

Then configure clients with an HTTPS proxy URL:

curl -x https://127.0.0.1:8080 https://httpbin.org/ip

SOCKS Proxy

Starts a SOCKS proxy server.

pxyd socks

Defaults:

• Host: 127.0.0.1
• Port: 1080
• Tunnel connect timeout: 10000 ms
• Tunnel idle timeout: 120000 ms

Options:

| Option | Description | | --- | --- | | --host <host> | Listen host | | --port <port> | Listen port | | --username <username> | Enable SOCKS username/password auth | | --password <password> | Enable SOCKS username/password auth | | --upstream <url> | Forward traffic through an upstream proxy | | --tunnel-connect-timeout <ms> | Timeout while establishing tunnels | | --tunnel-idle-timeout <ms> | Idle timeout for established tunnels |

Examples:

pxyd socks --host 127.0.0.1 --port 1080

curl --proxy socks5://127.0.0.1:1080 https://httpbin.org/ip

SOCKS authentication:

pxyd socks --username admin --password secret

curl --proxy socks5://admin:[email protected]:1080 https://httpbin.org/ip

Upstream Proxy Chaining

Both http and socks commands support --upstream.

Supported upstream URLs:

http://host:port
https://host:port
socks4://host:port
socks5://host:port

Username/password auth is supported in upstream URLs for HTTP, HTTPS, and SOCKS5:

pxyd http --upstream http://user:[email protected]:8081
pxyd socks --upstream socks5://user:[email protected]:1081

Default upstream ports:

| Protocol | Default port | | --- | --- | | http | 80 | | https | 443 | | socks4 | 1080 | | socks5 | 1080 |

pxyd rejects upstream configurations that point back to the proxy listener itself.

Notes

• --username and --password must be provided together.
• --tls-cert and --tls-key must be provided together.
• The HTTP proxy uses standard proxy authentication headers: Proxy-Authorization and Proxy-Authenticate.
• Requests and tunnels targeting the proxy listener itself are rejected to avoid proxy loops.

Development

npm install
npm run build
npm test

License

MIT Yuki Akai