🧅 hypertor
The Tor network library for Rust and Python
Consume AND host onion services with the simplicity of reqwest and axum.
State-of-the-art security features including PoW DoS protection, Vanguards, and traffic analysis defense.
Why hypertor?
Traditional Tor libraries force you to choose: either a complex low-level API for security researchers, or a simplified wrapper that sacrifices control. hypertor provides both: a batteries-included experience for common tasks, with full access to advanced security features when you need them.
🎯 Built For
Two Libraries in One
| Component | Purpose | Similar To |
|---|---|---|
| TorClient | Make HTTP requests over Tor anonymously | reqwest, httpx |
| OnionApp | Host .onion services with routing | axum, FastAPI |
Quick Examples
Rust — Anonymous Client
use hypertor::{TorClient, Result};
#[tokio::main]
async fn main() -> Result<()> {
let client = TorClient::new().await?;
let resp = client
.get("http://duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion")?
.send()
.await?;
println!("Status: {}", resp.status());
Ok(())
}
Rust — Onion Service
use hypertor::{OnionApp, ServeResponse};
#[tokio::main]
async fn main() -> hypertor::Result<()> {
let app = OnionApp::new()
.get("/", || async { ServeResponse::text("Hello from .onion!") })
.get("/api/status", || async {
ServeResponse::json(&serde_json::json!({"status": "operational"}))
});
let addr = app.run().await?;
println!("🧅 Live at: {}", addr);
Ok(())
}
Python — httpx-style Client
import asyncio
from hypertor import AsyncClient
async def main():
async with AsyncClient(timeout=60) as client:
resp = await client.get("https://check.torproject.org/api/ip")
print(f"Tor IP: {resp.json().get('IP')}")
asyncio.run(main())
Python — FastAPI-style Server
from hypertor import OnionApp
app = OnionApp()
@app.get("/")
async def home():
return "Welcome to my .onion service!"
@app.post("/api/echo")
async def echo(request):
data = await request.json()
return {"received": data}
if __name__ == "__main__":
app.run() # 🧅 Live at: xyz...xyz.onion
Security Features
🛡️ PoW DoS Protection
Tor 0.4.8+ Proof-of-Work defense with adaptive difficulty automatically protects your service from DDoS attacks without affecting legitimate users.
🔐 Client Authorization
Basic & Stealth authorization modes with x25519 key derivation. Restrict access to authorized clients while hiding service existence from others.
📊 Vanguards Protection
Vanguards-lite guard relay protection prevents circuit enumeration attacks that could reveal your service's location.
🎭 Traffic Analysis Defense
WTF-PAD, Tamaraw padding, and circuit padding machines resist website fingerprinting and correlation attacks.
🔍 Leak Detection
Comprehensive security scanner detects DNS leaks, header fingerprinting, timing patterns, and content leaks before they compromise anonymity.
⏱️ Timing Attack Protection
Built-in timing correlation defense with jitter injection and pattern detection to prevent traffic analysis attacks.
⚡ Congestion Control
Vegas RTT-based congestion control (Tor Proposal 324) provides optimal throughput without overwhelming the network.
🔌 WebSocket & gRPC
Real-time bidirectional WebSocket communication and gRPC services over Tor for modern application architectures.
🌉 Bridge Support
Full support for obfs4, snowflake, meek, and webtunnel pluggable transports for censorship circumvention.
📈 Prometheus Metrics
Production-ready observability with counters, gauges, histograms, and automatic /metrics endpoint for monitoring.
Security Presets
Choose your security level based on your threat model:
use hypertor::SecurityConfig;
// Basic Tor protection (fastest)
SecurityConfig::standard()
// PoW + Vanguards (recommended for most)
SecurityConfig::enhanced()
// Full Vanguards + Client Authorization
SecurityConfig::maximum()
// Stealth Auth + Max PoW + Tamaraw padding
SecurityConfig::paranoid()
| Preset | PoW | Vanguards | Client Auth | Traffic Padding | Use Case |
|---|---|---|---|---|---|
standard |
❌ | ❌ | ❌ | ❌ | Development, low-risk |
enhanced |
✅ | lite | ❌ | ❌ | Most production services |
maximum |
✅ | full | basic | ❌ | High-value targets |
paranoid |
✅ max | full | stealth | Tamaraw | State-level adversaries |
Architecture
┌─────────────────────────────────────────────────────────────────────┐ │ YOUR APPLICATION │ ├─────────────────────────────────────────────────────────────────────┤ │ TorClient │ OnionApp │ SOCKS5 Proxy │ │ (consume .onion) │ (host .onion) │ (bridge tools) │ ├─────────────────────────────────────────────────────────────────────┤ │ hypertor core │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │ │ Connection │ │ Privacy │ │ Security │ │ Observability│ │ │ │ Pooling │ │ Padding │ │ PoW/Auth │ │ Metrics │ │ │ │ Retry │ │ Vanguards │ │ Analysis │ │ Tracing │ │ │ └────────────┘ └────────────┘ └────────────┘ └──────────────┘ │ ├─────────────────────────────────────────────────────────────────────┤ │ arti-client (Tor Protocol) │ ├─────────────────────────────────────────────────────────────────────┤ │ Tor Network (6000+ relays) │ └─────────────────────────────────────────────────────────────────────┘
Performance
| Operation | Time | Notes |
|---|---|---|
| Circuit establishment | ~2-4s | Initial connection |
| HTTP request (warm) | ~200-500ms | With pooled circuit |
| OnionApp startup | ~3-5s | Service registration |
| Request throughput | ~50-100 req/s | Depends on circuit |
All benchmarks run with cargo bench — 71 benchmarks covering all major operations.
Installation
Rust
[dependencies]
hypertor = "0.3"
tokio = { version = "1", features = ["full"] }
Python
pip install hypertor
Documentation
📚 Quick Start
Get up and running in 5 minutes with basic examples for both client and server usage.
🌐 TorClient Guide
Deep dive into the HTTP client: requests, authentication, streaming, and advanced options.
🧅 OnionApp Guide
Build and deploy onion services with routing, middleware, and security configuration.
🔒 Security Guide
Configure PoW, Vanguards, client authorization, and traffic analysis defenses.