onion-transit/README.md

# Onion-Transit

A centralized Tor proxy daemon that embeds [Arti](https://gitlab.torproject.org/tpo/core/arti) (Rust Tor implementation) and exposes SOCKS5 + optional transparent proxy interfaces for LAN/VPS clients.

## What it does

Clients on a local network or VPN delegate Tor circuit building to a single Onion-Transit node instead of running Tor locally. This trades some anonymity guarantees for simplified deployment and lower per-client overhead.

**Standard Tor .onion access:**

```
Client (3 hops) → Rendezvous ← Service (3 hops)   = 6 hops total
```

**With Onion-Transit:**

```
Client → LAN → Transit (3 hops) → Rendezvous ← Service (3 hops)
```

The client's path is a single LAN hop to the Transit node. One Arti instance shares bootstrap, directory cache, and guard nodes across all clients.

## Security Warning

> **Onion-Transit centralizes Tor traffic and can see destination .onion names.
> Anonymity assumptions differ significantly from Tor Browser.**

This tool is designed for:

- Lab / office / team environments
- Development and testing
- VPS gateway for a trusted user group

It is **NOT** appropriate for: journalists, activists, or scenarios with adversarial threat models.

## Deployment Modes

| Mode | Binds to | Use case |
|------|----------|----------|
| `gateway` | `0.0.0.0:1080` | Shared SOCKS5 for LAN/VPN clients |
| `app-embedded` | `127.0.0.1` only | Sidecar for a single application |

## Quick Start

```bash
# Build
cargo build --release

# Check config before running
onion-transit config-check --config config.toml

# Start in gateway mode
onion-transit start --config config.toml

# Check runtime status
onion-transit status --json
```

## Configuration

See [config.example.toml](config.example.toml) for all options with documentation.

Key settings:

```toml
mode = "gateway"          # or "app-embedded"
trust_domain = "team"     # "lab", "team", or "personal"

[security]
mode = "standard"         # "reduced" requires feature flag + explicit opt-in
allowed_clients = ["10.0.0.0/8", "192.168.0.0/16"]
```

## Transparent Proxy (Linux only)

Build with the `tproxy` feature and use the separate binary:

```bash
cargo build --release --features tproxy
```

The transparent proxy requires iptables/nftables DNAT/REDIRECT rules. It does **not** support other interception methods. Example:

```bash
iptables -t nat -A OUTPUT -p tcp -d '*.onion' --dport 80 \
  -j REDIRECT --to-ports 9040
```

Run the dedicated binary (may require elevated privileges):

```bash
onion-transit-tproxy --config config.toml
```

## Building

```bash
# Standard build (SOCKS5 only)
cargo build --release

# With transparent proxy support
cargo build --release --features tproxy

# With reduced-security mode (DANGER)
cargo build --release --features reduced-security
```

## Connection Profiles

| Profile | Description |
|---------|-------------|
| `OnionStrict` | Full 3-hop circuit, stream isolation per destination (default) |
| `OnionFast` | Reduced isolation, shared circuits where possible |
| `ClearnetDefault` | Standard Tor exit policy |

## License

MIT