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