# Tor Transport

Burrow now has a `Tor` network type that boots an in-process [Arti](https://gitlab.torproject.org/tpo/core/arti) client and exposes a transparent TCP listener for outbound stream forwarding.

The first implementation is intentionally narrow:

- `tcp_stack.kind = "system"` is the only supported TCP stack backend.
- transparent destination recovery uses Linux `SO_ORIGINAL_DST` and macOS PF lookups.
- on macOS, Burrow first tries PF `DIOCNATLOOK`, then falls back to a `pflog0` observer backed by an in-memory flow cache keyed by the redirected socket tuple.
- Burrow does not yet install firewall redirect rules for you.
- traffic reaches Arti only if the host already redirects outbound TCP flows to Burrow's local listener.
- the macOS observer fallback only works when the redirect rule is logged to `pflog0` and Burrow listens on an explicit local address such as `127.0.0.1:9040`.
- destination handling is IP-and-port based, so this does not yet capture DNS or `.onion` names before local resolution.
- Burrow still does not install loop-avoidance rules for Arti's own relay connections, so redirect rules must exempt those flows externally for now.

## Payload format

`Network.payload` can be JSON or TOML.

```json
{
  "address": ["100.64.0.2/32"],
  "tun_name": "burrow-tor",
  "mtu": 1400,
  "arti": {
    "state_dir": "/var/lib/burrow/arti/state",
    "cache_dir": "/var/cache/burrow/arti"
  },
  "tcp_stack": {
    "kind": "system",
    "listen": "127.0.0.1:9040"
  }
}
```

## Next steps

- teach Burrow to program and tear down redirect rules safely.
- add loop-avoidance for Arti's own relay connections before enabling automatic redirect.
- add DNS capture or hostname-aware forwarding for `.onion` and other unresolved destinations.
- add alternate pure-Rust TCP stack backends behind the same `tcp_stack` enum.