docs: document Tor control port integration

Adds Tor control port section to USAGE.md covering config,
auth modes, rate limiting, and API endpoints. Updates README
feature line and config example, CHEATSHEET with tor snippets,
and marks the feature complete in TASKS.md and ROADMAP.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -10,7 +10,7 @@ through configurable chains of SOCKS4, SOCKS5, and HTTP CONNECT proxies.
 - Supported hop protocols: SOCKS5, SOCKS4/4a, HTTP CONNECT
 - Per-hop authentication (username/password)
 - DNS leak prevention (domain names forwarded to proxies, never resolved locally)
-- Tor integration (Tor is just another SOCKS5 hop)
+- Tor integration (SOCKS5 hop + control port NEWNYM for circuit rotation)
 - Managed proxy pool: multiple sources (API + file), health-tested, weighted selection
 - Per-proxy failure backoff (60s cooldown), stale proxy expiry, chain pre-flight
 - Fast warm start (seconds on restart vs minutes on cold start)
@@ -76,6 +76,11 @@ api_listen: 127.0.0.1:1081           # control API (disabled by default)
 chain:
   - socks5://127.0.0.1:9050          # Tor
 
+tor:
+  control_port: 9051                  # Tor control port (NEWNYM)
+  password: ""                        # or cookie_file for auth
+  newnym_interval: 0                  # periodic circuit rotation (0 = manual)
+
 proxy_pool:
   sources:
     - url: http://10.200.1.250:8081/proxies

ROADMAP.md

@@ -24,7 +24,7 @@
 
 - [x] Built-in control API (runtime metrics, pool state, config reload)
 - [ ] SOCKS5 server authentication (username/password)
-- [ ] Tor control port integration (circuit renewal via NEWNYM)
+- [x] Tor control port integration (circuit renewal via NEWNYM)
 - [ ] Metrics (connections/sec, bytes relayed, hop latency)
 
 ## v0.3.0

TASKS.md

@@ -44,7 +44,8 @@
 - [x] Use k8s-file logging driver with rotation
 - [x] Built-in control API (`api.py`, `--api`, `api_listen`)
 
+- [x] Tor control port integration (NEWNYM signaling, periodic rotation)
+
 ## Next
 - [ ] Integration tests with mock proxy server
 - [ ] SOCKS5 server-side authentication
-- [ ] Tor control port integration

docs/CHEATSHEET.md

@@ -59,6 +59,20 @@ proxy_pool:
   report_url: ""     # POST dead proxies (optional)
 ```
 
+## Tor Control Port (config)
+
+```yaml
+tor:
+  control_port: 9051
+  password: ""               # or cookie_file: /path/to/cookie
+  newnym_interval: 60        # auto-rotate every 60s (0 = manual)
+```
+
+```bash
+curl -s http://127.0.0.1:1081/tor | jq .                  # status
+curl -s -X POST http://127.0.0.1:1081/tor/newnym | jq .   # new circuit
+```
+
 ## Hot Reload
 
 ```bash

docs/USAGE.md

@@ -281,6 +281,69 @@ curl -s -X POST http://127.0.0.1:1081/pool/refresh | jq .
 
 Settings that require a restart: `listen`, `chain`, `pool_size`, `pool_max_idle`, `api_listen`.
 
+## Tor Control Port
+
+Optional integration with Tor's control protocol for circuit management.
+When enabled, s5p connects to Tor's control port and can send NEWNYM signals
+to request new circuits (new exit node) on demand or on a timer.
+
+### Configuration
+
+```yaml
+tor:
+  control_host: 127.0.0.1      # Tor control address
+  control_port: 9051            # Tor control port
+  password: ""                  # HashedControlPassword (torrc)
+  cookie_file: ""               # CookieAuthentication file path
+  newnym_interval: 0            # periodic NEWNYM in seconds (0 = manual only)
+```
+
+Requires Tor's `ControlPort` enabled in `torrc`:
+
+```
+ControlPort 9051
+HashedControlPassword 16:...    # or CookieAuthentication 1
+```
+
+### Authentication modes
+
+| Mode | Config | torrc |
+|------|--------|-------|
+| Password | `password: "secret"` | `HashedControlPassword 16:...` |
+| Cookie | `cookie_file: /var/run/tor/control.authcookie` | `CookieAuthentication 1` |
+| None | (leave both empty) | No auth configured |
+
+### Rate limiting
+
+Tor enforces a minimum 10-second interval between NEWNYM signals. s5p
+applies the same client-side rate limit to avoid unnecessary rejections.
+
+### API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/tor` | Controller status (enabled, connected, last NEWNYM) |
+| `POST` | `/tor/newnym` | Trigger NEWNYM signal (new circuit) |
+
+```bash
+# Check tor controller status
+curl -s http://127.0.0.1:1081/tor | jq .
+
+# Request new circuit
+curl -s -X POST http://127.0.0.1:1081/tor/newnym | jq .
+```
+
+### Periodic NEWNYM
+
+Set `newnym_interval` to automatically rotate circuits:
+
+```yaml
+tor:
+  newnym_interval: 60    # new circuit every 60 seconds
+```
+
+Values below 10 are clamped to Tor's minimum interval.
+
 ## Connection Retry
 
 When a proxy pool is active, s5p retries failed connections with a different