AuraVPN/docs/split-tunnel.md

# Aura Split Tunnel

Split tunneling decides, per destination IP, whether a packet travels **through the encrypted
VPN** or **egresses directly** (bypassing the tunnel). It lets you keep, say, RFC1918 LAN
traffic local while sending the rest through Aura — or the reverse.

It is implemented in the `aura-tunnel` crate (`routes.rs`, `router.rs`, `dns.rs`), configured
statically via the `[tunnel.split]` section of `client.toml`
(`crates/aura-cli/src/config.rs`), and managed live via the `aura route` / `aura status`
admin commands (`crates/aura-cli/src/admin.rs`).

---

## Concept: VPN vs DIRECT

Every outbound IP packet read from the TUN device is classified into one of two actions
(`RouteAction`):

- **`Vpn`** — encrypt and send the packet over the Aura connection to the server.
- **`Direct`** — let the packet egress directly, bypassing the tunnel.

The router (`AuraRouter::run`, `router.rs`) parses each packet's destination IP, classifies
it, and dispatches:

```
TUN read --> parse dst IP --> RouteTable.classify(dst) --> Vpn?    -> conn.send_packet()
                                                          \ Direct? -> send_direct()  (v1 stub)
```

> **v1 limitation — `Direct` is a stub.** `send_direct` currently **logs and drops** the
> packet; real raw-socket / OS-stack re-injection is out of scope for v1. The method is
> already `async` and fallible so a real egress path can slot in without changing call sites.
> The VPN path is fully functional end-to-end. Packets whose destination cannot be parsed
> (not IPv4/IPv6, or too short) are dropped with a trace.

The inbound direction is straightforward: decrypted IP packets received from the peer are
written back to the TUN device.

---

## Rules

The routing table (`RouteTable`, `routes.rs`) holds three things: a set of **CIDR rules**, a
set of **domain rules**, and a **default action**.

### CIDR rules

A CIDR rule is an `IpNetwork` (e.g. `10.0.0.0/8`) plus an action. CIDR rules are keyed by
network, so re-adding the same network **overwrites** its action.

### Domain rules

A domain rule is a domain name plus an action. Domains do **not** match IPs directly. Instead
`AuraDns` (`dns.rs`) resolves the domain via the system resolver (hickory) and inserts each
resulting address as a **host route** — `/32` for IPv4, `/128` for IPv6 — so it participates
in the normal longest-prefix match. Resolution results are cached.

> Because domain rules become host routes at resolution time, they only take effect once the
> domain has been resolved (at startup, or on demand). They reflect the addresses seen at
> resolution time and are not continuously re-resolved in v1.

### Default action

If no CIDR rule (including resolved domain host routes) matches a destination, the table's
**default action** applies.

---

## Longest-prefix precedence

`classify(dst_ip)` performs a **longest-prefix match** (`routes.rs`):

> Among all CIDR rules whose network contains the destination, the rule with the **largest
> prefix length** (most specific) wins. If no rule matches, the default action is returned.

This lets a specific range override a broader one regardless of insertion order. IPv4 rules
only match IPv4 destinations and IPv6 rules only match IPv6 destinations.

Example (from the shipped config): with `default = VPN`, `10.0.0.0/8 = Direct`, and
`10.7.0.0/24 = Vpn`:

| Destination  | Matched rule         | Action |
|--------------|----------------------|--------|
| `10.1.2.3`   | `10.0.0.0/8`         | Direct |
| `10.7.0.9`   | `10.7.0.0/24` (more specific, wins over `/8`) | Vpn |
| `192.168.1.1`| `192.168.0.0/16`     | Direct |
| `8.8.8.8`    | (none) → default     | Vpn    |

> Edge case: if two rules share the **same** prefix length, the **last-inserted** one wins
> (it overwrites the earlier entry, since rules are keyed by network).

---

## Static config: `[tunnel.split]`

The split tunnel is configured in `client.toml` under `[tunnel.split]`
(`crates/aura-cli/src/config.rs`). `build_route_table` turns it into a `RouteTable`: CIDR
rules are applied directly; domain rules are recorded and returned for the client to resolve
at startup.

### Schema

| Key                          | Type            | Default | Meaning                                            |
|------------------------------|-----------------|---------|----------------------------------------------------|
| `default`                    | string          | `"VPN"` | Action when no rule matches: `VPN` / `DIRECT` (case-insensitive) |
| `[[tunnel.split.direct]]`    | array of rules  | `[]`    | Rules forcing matching destinations to **Direct**  |
| `[[tunnel.split.vpn]]`       | array of rules  | `[]`    | Rules forcing matching destinations through the **VPN** |

Each rule in `direct` / `vpn` is a table with **exactly one** of:

| Key      | Type   | Example             |
|----------|--------|---------------------|
| `cidr`   | string | `"192.168.0.0/16"`  |
| `domain` | string | `"intranet.example.com"` |

A rule with both `cidr` and `domain`, or neither, is rejected when the route table is built.

### Example

```toml
# Split-tunnel routing: the default action plus per-destination overrides.
[tunnel.split]
# Default for destinations matching no rule below: "VPN" or "DIRECT".
default = "VPN"

# Send these directly (bypass the tunnel): RFC1918 ranges stay on the LAN...
[[tunnel.split.direct]]
cidr = "192.168.0.0/16"

[[tunnel.split.direct]]
cidr = "10.0.0.0/8"

# ...and a corporate domain egresses directly (resolved to host routes at startup).
[[tunnel.split.direct]]
domain = "intranet.example.com"

# Force a more-specific range back through the VPN (longest-prefix wins over 10.0.0.0/8).
[[tunnel.split.vpn]]
cidr = "10.7.0.0/24"
```

This is the configuration shipped in `config/client.toml.example`.

---

## Live management: `aura route` / `aura status`

A running `aura client` (or `aura server`) hosts an **admin socket** — a tiny JSON
line-protocol over a **Unix domain socket** (`crates/aura-cli/src/admin.rs`). The `aura
route` and `aura status` subcommands connect to it to inspect and mutate the live routing
table without restarting the tunnel. The default socket path is `/tmp/aura-admin.sock`
(override with `--admin-socket`).

> Platform note: the admin socket uses Unix domain sockets (Linux/macOS). On Windows it is a
> `cfg`-gated stub that returns an explanatory error (a named-pipe transport is future work),
> so the rest of the CLI still compiles there.

### Commands

```
aura route add    (--cidr <CIDR> | --domain <DOMAIN>) --action <vpn|direct> [--admin-socket <PATH>]
aura route list                                                             [--admin-socket <PATH>]
aura route remove --cidr <CIDR>                                             [--admin-socket <PATH>]
aura status                                                                 [--admin-socket <PATH>]
```

`route add` takes **exactly one** of `--cidr` / `--domain` (they are mutually exclusive, and
one is required), plus `--action vpn` or `--action direct`.

```bash
# Send a CIDR directly, live.
aura route add --cidr 8.8.8.0/24 --action direct
# ok

# Route a domain through the VPN (resolved into host routes).
aura route add --domain example.com --action vpn
# ok

# Inspect the current rules and default.
aura route list
# default: vpn
#   cidr   8.8.8.0/24           direct
#   domain example.com          vpn

# Remove a CIDR rule.
aura route remove --cidr 8.8.8.0/24
# ok (removed)            # or: "ok (nothing to remove)" if it wasn't present

# Tunnel status / counters.
aura status
# Aura tunnel status
#   peer:       client-1
#   default:    vpn
#   rules:      1
#   rx packets: 0
#   tx packets: 0
```

### Behavior notes

- **`route remove` only removes CIDR rules** — it takes `--cidr` and has no domain form. The
  library `RouteTable` has no per-rule remove API, so a removal **rebuilds** the table from
  the surviving rules (preserving the default). Domain rules are re-added on rebuild, but
  their previously resolved host routes are dropped and re-resolved on demand.
- **`route list` enumerates a rule mirror.** The live `RouteTable` is the source of truth for
  classification but does not expose iteration, so the admin layer keeps a parallel mirror in
  lockstep with every mutation; `list` echoes that mirror while `classify` still uses the real
  table.
- **`status`** reports the verified peer id, the default action, the total rule count
  (CIDR + domain), and inbound/outbound packet counters.

### Wire protocol (for reference)

One JSON object per line, request then response (`crates/aura-cli/src/admin.rs`):

```text
-> {"cmd":"route_add","cidr":"8.8.8.0/24","action":"direct"}
<- {"ok":true}
-> {"cmd":"route_list"}
<- {"ok":true,"default":"vpn","cidrs":[{"cidr":"8.8.8.0/24","action":"direct"}],"domains":[]}
-> {"cmd":"route_remove","cidr":"8.8.8.0/24"}
<- {"ok":true,"removed":true}
-> {"cmd":"status"}
<- {"ok":true,"peer_id":"client-1","rx_packets":0,"tx_packets":0,"default":"vpn","rules":1}
```

On error the response is `{"ok":false,"error":"..."}`.

---

## v1 limitations summary

- **`Direct` egress is a stub** — `Direct` packets are logged and dropped, not re-injected to
  the OS stack. The VPN path is fully functional.
- **Domain rules are resolved once** (at startup / on demand) into host routes; no continuous
  re-resolution.
- **`route remove` is CIDR-only** and rebuilds the table (domain host routes are re-resolved
  on demand afterward).
- **Admin socket is Unix-only**; Windows is a `cfg`-gated stub.
- The server is a **single shared TUN** in v1, and the tunnel resolver `dns` config field is
  informational (the system resolver is used).