# rustunnel

`rustunnel` is a cross-platform Rust tool for lab and development tunneling over HTTPS with mutual TLS and an application auth token. It exposes a local SOCKS5 proxy on the connector side and forwards traffic only after the HTTPS, certificate, and auth checks succeed.

## Legitimate use

Use `rustunnel` for local labs, development environments, and controlled testing where you own or are authorized to operate both endpoints. Do not use it to access systems without permission.

## Build and test

```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo check
cargo test --all-targets
cargo build
```

## Generate credentials

Generate local certificate and auth material into an explicit directory:

```sh
rustunnel generate --out ./creds
```

This creates `ca.pem`, `ca.key`, `server.crt`, `server.key`, `client.crt`, `client.key`, `token.txt`, and `config.json`.

## Run a tunnel

Start the HTTPS listener:

```sh
rustunnel listen \
  --listen 127.0.0.1:4180 \
  --cert ./creds/server.crt \
  --key ./creds/server.key \
  --ca-cert ./creds/ca.pem \
  --auth-token-file ./creds/token.txt
```

Start the connector and local SOCKS5 proxy:

```sh
rustunnel connect \
  --target 127.0.0.1:4180 \
  --socks 127.0.0.1:1180 \
  --cert ./creds/client.crt \
  --key ./creds/client.key \
  --ca-cert ./creds/ca.pem \
  --auth-token-file ./creds/token.txt
```

Use the SOCKS5 proxy from a local client:

```sh
curl --proxy socks5h://127.0.0.1:1180 http://127.0.0.1:4181/
```

## Defaults and custom ports

- HTTPS listener: `127.0.0.1:4180`
- SOCKS5 proxy: `127.0.0.1:1180`

Override ports with `--listen`, `--target`, and `--socks`, as shown above.

## Security posture

HTTPS is the default tunnel carrier. The listener requires a trusted client certificate and a valid auth token; the connector validates the server certificate before establishing the tunnel. Private keys and auth tokens are treated as sensitive and are redacted from normal logs.

## Cross-platform CI

CI runs on Linux, macOS, and Windows. It checks formatting, Clippy, tests, builds, CLI smoke commands, release artifacts, and a minimal local generate/listen/connect/SOCKS5 end-to-end flow.