Jayden/PSK-Proxy-Tunnel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

use socks5 instead of HTTP Proxy to allow more protocols

Browse Source
This commit is contained in:
Jaydenha09
2025-09-05 14:26:57 +08:00
parent 0e1980df9b
commit b98cd1bb22
4 changed files with 902 additions and 547 deletions
Download Patch File Download Diff File Expand all files Collapse all files

383
BUILD.md
View File

@@ -1,37 +1,45 @@
# PSK-Proxy-Tunnel Build Guide
# PSK-Proxy-Tunnel Build & Usage Guide
This guide explains how to build single executable binaries for the PSK-Proxy-Tunnel project using the `pkg` tool.
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
- Node.js: Version 18.0.0 or higher
- npm: Usually comes with Node.js
- Git: To clone the repository
## Quick Start
### 1. Install Dependencies
### 1) Install dependencies
```bash
npm install
```
### 2. Build for Current Platform
### 2) Build for your current platform
```bash
# macOS/Linux: auto-detect current platform via script
# macOS/Linux
./build.sh
# Windows: auto-detect Windows via script
# Windows
build.bat
# Or run a specific platform via npm
npm run build:macos # macOS
npm run build:linux # Linux
npm run build:windows # Windows
```
### 3. Build for All Platforms
Or via npm directly:
```bash
npm run build:macos # macOS
npm run build:linux # Linux
npm run build:windows # Windows
```
### 3) Build for all platforms
```bash
npm run build
@@ -39,133 +47,217 @@ npm run build
## Build Scripts
### Using the Build Scripts
### Using the build scripts
#### Unix/Linux/macOS
Unix/Linux/macOS:
```bash
# Make the script executable
chmod +x build.sh
# Build for current platform
./build.sh
# Build for specific platform
./build.sh # current platform
./build.sh --platform macos
./build.sh --platform linux
./build.sh --platform windows
# Build for all platforms
./build.sh --all
# Clean build artifacts
./build.sh --clean
# Show help
./build.sh --all # all platforms
./build.sh --clean # remove dist/
./build.sh --help
```
#### Windows
Windows:
```cmd
# Build for Windows (default)
build.bat
# Build for all platforms
build.bat --all
# Clean build artifacts
build.bat # Windows (default)
build.bat --all # all platforms
build.bat --clean
# Show help
build.bat --help
```
### Using npm Scripts Directly
### Using npm scripts directly
```bash
# Build for specific platform
npm run build:macos
npm run build:linux
npm run build:windows
# Build for all platforms
npm run build
# Clean build artifacts
npm run clean
npm run build # all platforms
npm run clean # remove dist/
```
## Build Output
After building, you'll find the executables in the `dist/` directory:
Executables are created in `dist/`:
```
dist/
├── psk-proxy-server-macos # macOS server executable
├── psk-proxy-client-macos # macOS client executable
├── psk-proxy-server-linux # Linux server executable
├── psk-proxy-client-linux # Linux client executable
├── psk-proxy-server-windows.exe # Windows server executable
└── psk-proxy-client-windows.exe # Windows client executable
├── 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
```
## Platform-Specific Builds
## Running the Server and Client
### macOS
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:
```bash
npm run build:macos
# Creates: psk-proxy-server-macos, psk-proxy-client-macos
./dist/psk-proxy-server-macos \
--tunnel-port 8443 \
--host 0.0.0.0 \
--psk-file /path/to/psk.hex
```
### Linux
Windows:
```cmd
.\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:
```bash
npm run build:linux
# Creates: psk-proxy-server-linux, psk-proxy-client-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
Windows:
```cmd
.\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):
```bash
curl -x socks5h://127.0.0.1:1080 http://example.com/
```
- HTTPS over SOCKS5:
```bash
curl -x socks5h://127.0.0.1:1080 https://ifconfig.me
```
- SSH over SOCKS5 (using `nc` as ProxyCommand):
```bash
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"
```bash
npm run build:windows
# Creates: psk-proxy-server-windows.exe, psk-proxy-client-windows.exe
npm install -g pkg
# or
npx pkg proxy-server.js
```
## Cross-Platform Building
You can build for other platforms from any operating system:
2) Build fails with permission errors
```bash
# Build for all platforms from macOS
npm run build
# Build for all platforms from Linux
npm run build
# Build for all platforms from Windows
npm run build
chmod +x build.sh
sudo npm run build # if necessary
```
## Using the Built Executables
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
### Server
```bash
# macOS/Linux
./dist/psk-proxy-server-macos --tunnel-port 8443 --tcp-port 8080 --host 0.0.0.0 --psk-file /path/to/psk.key
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
# Windows
.\dist\psk-proxy-server-windows.exe --tunnel-port 8443 --tcp-port 8080 --host 0.0.0.0 --psk-file C:\path\to\psk.key
```
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
### Client
```bash
# macOS/Linux
./dist/psk-proxy-client-macos --server-host server.example.com --server-port 8443 --origin-host 127.0.0.1 --origin-port 8080 --psk-file /path/to/psk.key --identity client1
## Performance Considerations
# Windows
.\dist\psk-proxy-client-windows.exe --server-host server.example.com --server-port 8443 --origin-host 127.0.0.1 --origin-port 8080 --psk-file C:\path\to\psk.key --identity client1
```
- 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
The build configuration is defined in `package.json` under the `pkg` section:
Defined in `package.json` under `pkg`:
```json
{
@@ -174,110 +266,15 @@ The build configuration is defined in `package.json` under the `pkg` section:
"scripts": [],
"targets": [
"node18-macos-x64",
"node18-linux-x64",
"node18-linux-x64",
"node18-win-x64"
]
}
}
```
### Available Targets
- `node18-macos-x64`: macOS 64-bit
- `node18-linux-x64`: Linux 64-bit
- `node18-win-x64`: Windows 64-bit
You can modify these targets to support different Node.js versions or architectures.
## Troubleshooting
### Common Issues
1. **"pkg command not found"**
```bash
npm install -g pkg
# or use the local version
npx pkg proxy-server.js
```
2. **Build fails with permission errors**
```bash
# Make sure the build script is executable
chmod +x build.sh
# Or run with sudo if needed
sudo npm run build
```
3. **Executable doesn't run on target platform**
- Ensure you're building for the correct target platform
- Check that the target platform supports the Node.js version you're using
- Verify the executable has proper permissions
4. **Missing dependencies in built executable**
- The `pkg` tool automatically bundles Node.js built-in modules
- External dependencies are included automatically
- If you have custom assets, add them to the `pkg.assets` array
### Performance Considerations
- **File Size**: Single executables are larger than the source code because they include Node.js runtime
- **Startup Time**: Slightly slower startup compared to running with `node` directly
- **Memory Usage**: Similar to running with Node.js directly
### Security Notes
- Built executables contain your source code (though it's compiled)
- The `pkg` tool doesn't obfuscate or encrypt your code
- Consider this when distributing executables with sensitive information
## Advanced Configuration
### Custom pkg Options
You can customize the build process by modifying the `pkg` section in `package.json`:
```json
{
"pkg": {
"assets": [
"config/*.json",
"templates/*.html"
],
"scripts": [
"scripts/**/*.js"
],
"targets": [
"node18-macos-x64",
"node18-linux-x64",
"node18-win-x64"
],
"outputPath": "custom-dist"
}
}
```
### Environment Variables
You can set environment variables to customize the build:
```bash
# Set custom output directory
PKG_OUTPUT_PATH=./my-dist npm run build
# Set custom Node.js version
PKG_NODE_VERSION=16 npm run build
```
## Contributing
When adding new build targets or modifying the build process:
1. Update the `package.json` scripts
2. Update the build scripts (`build.sh` and `build.bat`)
3. Test builds on all target platforms
4. Update this documentation
## License
This build system is part of the PSK-Proxy-Tunnel project and follows the same license terms.
- 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.