PSK-Proxy-Tunnel/BUILD.md

PSK-Proxy-Tunnel Build & Usage Guide

This guide explains how to build single executable binaries and how to run the TLS-PSK tunnel with a local SOCKS5 proxy client (supporting TCP CONNECT and UDP ASSOCIATE).

Key changes:

• Local proxy is now SOCKS5 (replaces the previous HTTP proxy).
• The tunnel supports multiplexed TCP and UDP relaying.
• Existing frame protocol extended with UDP_* frames for SOCKS5 UDP ASSOCIATE.

Prerequisites

• Node.js: Version 18.0.0 or higher
• npm: Usually comes with Node.js
• Git: To clone the repository

Quick Start

1) Install dependencies

npm install

2) Build for your current platform

# macOS/Linux
./build.sh

# Windows
build.bat

Or via npm directly:

npm run build:macos   # macOS
npm run build:linux   # Linux
npm run build:windows # Windows

3) Build for all platforms

npm run build

Build Scripts

Using the build scripts

Unix/Linux/macOS:

chmod +x build.sh
./build.sh                 # current platform
./build.sh --platform macos
./build.sh --platform linux
./build.sh --platform windows
./build.sh --all           # all platforms
./build.sh --clean         # remove dist/
./build.sh --help

Windows:

build.bat                  # Windows (default)
build.bat --all            # all platforms
build.bat --clean
build.bat --help

Using npm scripts directly

npm run build:macos
npm run build:linux
npm run build:windows
npm run build              # all platforms
npm run clean              # remove dist/

Build Output

Executables are created in dist/:

dist/
├── psk-proxy-server-macos
├── psk-proxy-client-macos
├── psk-proxy-server-linux
├── psk-proxy-client-linux
├── psk-proxy-server-windows.exe
└── psk-proxy-client-windows.exe

Running the Server and Client

The PSK (pre-shared key) file must contain a hex-encoded key string used by both sides. Example (256-bit key):

0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Server (Out-Node)

• Listens for a single TLS-PSK tunnel connection from the client.
• Performs outbound TCP connects and UDP sends on behalf of the client.

macOS/Linux:

./dist/psk-proxy-server-macos \
  --tunnel-port 8443 \
  --host 0.0.0.0 \
  --psk-file /path/to/psk.hex

Windows:

.\dist\psk-proxy-server-windows.exe ^
  --tunnel-port 8443 ^
  --host 0.0.0.0 ^
  --psk-file C:\path\to\psk.hex

Required options:

• --tunnel-port <port>: TLS-PSK tunnel port
• --host <host>: Bind host (e.g., 0.0.0.0)
• --psk-file <path>: File containing hex PSK

Optional:

• --connect-timeout <ms>: Outbound TCP connect timeout (default 10000)

Client (Local SOCKS5 Proxy)

• Runs a local SOCKS5 proxy (TCP CONNECT and UDP ASSOCIATE).
• Multiplexes many local connections over one TLS-PSK tunnel to the server.

macOS/Linux:

./dist/psk-proxy-client-macos \
  --server-host server.example.com \
  --server-port 8443 \
  --psk-file /path/to/psk.hex \
  --identity client1 \
  --socks-port 1080 \
  --bind-host 127.0.0.1

Windows:

.\dist\psk-proxy-client-windows.exe ^
  --server-host server.example.com ^
  --server-port 8443 ^
  --psk-file C:\path\to\psk.hex ^
  --identity client1 ^
  --socks-port 1080 ^
  --bind-host 127.0.0.1

Required options:

• --server-host <host>: Remote out-node address
• --server-port <port>: Remote out-node port
• --psk-file <path>: File containing hex PSK
• --identity <id>: Identity string (logged on server)
• --socks-port <port>: Local SOCKS5 proxy port

Optional:

• --bind-host <host>: Local bind host (default 127.0.0.1)
• --connect-timeout <ms>: Waiting time for OPEN/UDP_OPEN result (default 10000)
• --idle-timeout <ms>: Idle timeout for TCP sockets (default 60000, 0=disabled)
• --udp-idle-timeout <ms>: Idle timeout for UDP association (default 60000, 0=disabled)

Protocol Summary

All multiplexed over a single TLS-PSK socket:

Header (9 bytes):

• 1 byte type
• 4 bytes connection id (unsigned)
• 4 bytes payload length (unsigned)
• payload bytes

Types:

• TCP:
  • DATA (2): stream data
  • CLOSE (3): close stream
  • OPEN (4): payload = [2B hostLen][host][2B port]
  • OPEN_RESULT (5): payload = [1B status] (1=success, 0=failure)
• UDP (for SOCKS5 UDP ASSOCIATE):
  • UDP_OPEN (6): payload empty
  • UDP_OPEN_RESULT (7): payload = [1B status] (1=success, 0=failure)
  • UDP_SEND (8): payload = [2B hostLen][host][2B port][2B dataLen][data]
  • UDP_RECV (9): same layout as UDP_SEND
  • UDP_CLOSE (10): payload empty

Testing

Assuming the client runs a local SOCKS5 proxy at 127.0.0.1:1080:

• HTTP over SOCKS5 (remote DNS resolution via socks5h):

  curl -x socks5h://127.0.0.1:1080 http://example.com/
  

• HTTPS over SOCKS5:

  curl -x socks5h://127.0.0.1:1080 https://ifconfig.me
  

• SSH over SOCKS5 (using nc as ProxyCommand):

  ssh -o ProxyCommand="nc -x 127.0.0.1:1080 -X 5 %h %p" user@your.remote.host
  

• Applications with SOCKS5 (TCP and UDP):

  • Many apps support SOCKS5 TCP CONNECT (browsers, package managers, etc.).
  • For UDP ASSOCIATE (e.g., some torrent clients, DNS forwarders with SOCKS5-UDP support), configure them to use 127.0.0.1:1080 SOCKS5 and enable UDP if supported. Note: many CLI tools do not implement SOCKS5 UDP.

Notes:

• socks5h in curl ensures DNS names are resolved through the proxy.
• UDP test coverage depends on the client application having SOCKS5 UDP support.

Troubleshooting

1. "pkg command not found"

npm install -g pkg
# or
npx pkg proxy-server.js

2. Build fails with permission errors

chmod +x build.sh
sudo npm run build  # if necessary

3. Executable doesn't run on target platform

• Ensure you built for the correct target
• Verify executable permissions
• Confirm compatible Node target in pkg config

4. Tunnel connects but traffic fails

• Confirm both server and client use the exact same hex PSK
• Check connectivity from server to target hosts/ports (firewall, outbound rules)
• Use --connect-timeout to tune behavior

5. SOCKS5 UDP doesn't appear to work

• Confirm your application actually supports SOCKS5 UDP ASSOCIATE
• Check that the client printed "Local SOCKS5 proxy listening ..."
• Inspect server logs for UDP_* activity

Performance Considerations

• Single tunnel multiplexes many flows (reduced connection overhead).
• UDP sockets are ephemeral and idle-timed to conserve resources.
• TCP and UDP buffers are kept minimal; tune OS limits as needed.

Build Configuration

Defined in package.json under pkg:

{
  "pkg": {
    "assets": [],
    "scripts": [],
    "targets": [
      "node18-macos-x64",
      "node18-linux-x64",
      "node18-win-x64"
    ]
  }
}

Contributing

• Keep CLI flags in proxy-client.js and proxy-server.js in sync with this document.
• Update build scripts (build.sh, build.bat) when adding platforms.
• Test TCP (HTTP/HTTPS/SSH) and at least one UDP-capable client where possible.