feat: initial SOCKS5 proxy with chain support

Asyncio-based SOCKS5 server that tunnels connections through
configurable chains of SOCKS5, SOCKS4/4a, and HTTP CONNECT proxies.
Tor integration via standard SOCKS5 hop.

docs/CHEATSHEET.md

@@ -0,0 +1,46 @@
+# s5p -- Cheatsheet
+
+## CLI
+
+```
+s5p                                         # direct, listen :1080
+s5p -C socks5://127.0.0.1:9050             # through Tor
+s5p -C socks5://tor:9050,http://px:8080    # Tor + HTTP proxy
+s5p -c config/example.yaml                  # from config file
+s5p -l 0.0.0.0:9999                         # custom listen address
+s5p -t 30                                   # 30s per-hop timeout
+s5p -v                                      # debug logging
+s5p -q                                      # errors only
+```
+
+## Proxy URLs
+
+```
+socks5://host:port
+socks5://user:pass@host:port
+socks4://host:port
+http://host:port
+http://user:pass@host:port
+```
+
+## Testing
+
+```bash
+# Check exit IP
+curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip
+
+# Verbose curl
+curl -v -x socks5h://127.0.0.1:1080 https://example.com
+
+# With timeout
+curl --max-time 30 -x socks5h://127.0.0.1:1080 https://example.com
+```
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| Connection refused | Is Tor running? `ss -tlnp \| grep 9050` |
+| Timeout | Increase `-t`, check proxy reachability |
+| DNS leak | Use `socks5h://` (not `socks5://`) in client |
+| Auth failed | Verify credentials in proxy URL |

docs/INSTALL.md

@@ -0,0 +1,39 @@
+# s5p -- Installation
+
+## Prerequisites
+
+- Python >= 3.11
+- pip
+- Tor (optional, for Tor-based chains)
+
+## Install
+
+```bash
+cd ~/git/s5p
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Verify
+
+```bash
+s5p --version
+which s5p
+```
+
+## Install Tor (optional)
+
+```bash
+sudo apt install tor
+sudo systemctl enable --now tor
+
+# Verify Tor SOCKS5 port
+ss -tlnp | grep 9050
+```
+
+## Symlink (alternative)
+
+```bash
+ln -sf ~/git/s5p/.venv/bin/s5p ~/.local/bin/s5p
+```

docs/USAGE.md

@@ -0,0 +1,73 @@
+# s5p -- Usage
+
+## Basic Usage
+
+```bash
+# Direct proxy (no chain, just a SOCKS5 server)
+s5p
+
+# Through Tor
+s5p -C socks5://127.0.0.1:9050
+
+# Through Tor + another proxy
+s5p -C socks5://127.0.0.1:9050,socks5://proxy:1080
+
+# Custom listen address
+s5p -l 0.0.0.0:9999 -C socks5://127.0.0.1:9050
+
+# From config file
+s5p -c config/example.yaml
+
+# Debug mode
+s5p -v -C socks5://127.0.0.1:9050
+```
+
+## Config File
+
+```yaml
+listen: 127.0.0.1:1080
+timeout: 10
+log_level: info
+
+chain:
+  - socks5://127.0.0.1:9050
+  - http://user:pass@proxy:8080
+```
+
+## Proxy URL Format
+
+```
+protocol://[username:password@]host[:port]
+```
+
+| Protocol | Default Port | Auth Support |
+|----------|-------------|-------------|
+| socks5   | 1080        | username/password |
+| socks4   | 1080        | none |
+| http     | 8080        | Basic |
+
+## Testing the Proxy
+
+```bash
+# Check exit IP via Tor
+curl --proxy socks5h://127.0.0.1:1080 https://check.torproject.org/api/ip
+
+# Fetch a page
+curl --proxy socks5h://127.0.0.1:1080 https://example.com
+
+# Use with Firefox: set SOCKS5 proxy to 127.0.0.1:1080, enable remote DNS
+```
+
+Note: use `socks5h://` (not `socks5://`) with curl to send DNS through the proxy.
+
+## Chain Order
+
+Hops are traversed left-to-right:
+
+```
+-C hop1,hop2,hop3
+
+Client -> s5p -> hop1 -> hop2 -> hop3 -> Destination
+```
+
+Each hop only sees its immediate neighbors.