From cc1eb55c58378032a1aa87c71f232401398f0357 Mon Sep 17 00:00:00 2001
From: c4ch3c4d3 <23181631+c4ch3c4d3@users.noreply.github.com>
Date: Thu, 4 Jun 2026 08:43:11 -0600
Subject: [PATCH] docs: add rustunnel README

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..783a024
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# 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.