gatuna/README.md

# gatuna

**gata** (Spanish: *cat*) + **atún** (Spanish: *tuna*) — a cat fishing a
tunnel. The "tun" root is also the commonplace shorthand for a network tunnel
(as in `/dev/net/tun`, `wintun`, `tuntap`), so the name works in both languages:
a Spanish portmanteau that sounds like "gatuna" (feline), and an English pun on
"cat-tun" — a cat that tunnels.

## Attribution

Entirely vibe-coded with [GLM 5.2](https://github.com/zai-org/GLM-5.2). No
human-typed source code; all implementation was directed through natural
language and reviewed by the human in the loop.

## Why this works

WireGuard-for-Windows installs its killswitch as WFP filters at the ALE layers
only (`ALE_AUTH_CONNECT_V4/V6`, `ALE_AUTH_RECV_ACCEPT_V4/V6`). It never installs
MAC-layer callouts — the L2 code in `tunnel/firewall/` is commented out. Raw
Ethernet frames sent via a packet driver (Npcap on Windows, `AF_PACKET` on
Linux) never enter the IP stack, so they never reach the ALE classify path and
pass unimpeded. See `wireguard-windows/tunnel/firewall/blocker.go:156`.

## Components

- **`gatunad`** — Rust server (`gatunad/`). Runs on the peer (Linux) that owns
  the real services. Announces upstreams and relays TCP between the tunnel and
  `127.0.0.1:<port>`.
- **`gatuna`** — .NET 8 WinForms client (`gatuna-win/`). Runs on the
  killswitched Windows box. Discovers the server, presents its upstreams as
  local loopback listeners, and hauls bytes over the same L2 protocol. Includes
  a network test (PING/PONG) for measuring latency, jitter, and loss.

## Transport

- **Medium:** raw Ethernet frames on a shared L2 segment.
- **Ethertype:** `0x6969` (hardcoded).
- **No IP stack involvement.** Frames carry only our 8-byte header + payload.
- **BPF:** both sides filter on ethertype — the server via classic BPF on
  `AF_PACKET` (`SO_ATTACH_FILTER`), the client via Npcap's compiled filter.
  No eBPF authoring.

## Protocol

See [`PROTOCOL.md`](PROTOCOL.md) for the full wire format. Summary:

- 8-byte header, big-endian:
  `[ version:1 ][ type:1 ][ session_id:4 ][ payload_len:2 ][ payload:N ]`.
- `version` = `2`. `payload_len` lets the receiver ignore Ethernet padding
  (frames under 60 bytes are zero-padded by the NIC).
- DATA frames carry an extended 16-byte header with `seq` and `ack_seq` fields
  for L2-level reliability (retransmit + in-order delivery), preventing lost
  Ethernet frames from corrupting TCP sessions.
- Discovery: client broadcasts `DISCOVER`; server unicasts `MANIFEST` (with
  hostname and upstream list) back.
- Sessions: `OPEN` → `OPEN_ACK` (or `OPEN_NAK`) → `DATA`* ↔ `DATA`* → `CLOSE`.
- Network test: `PING` (with 8-byte nonce) → `PONG` (nonce echoed).
- TCP only. UDP frame types are reserved but unimplemented.

## `gatunad` usage

```
gatunad IFACE PORT [PORT...]
```

- `IFACE` — L2 interface name (e.g. `eth0`).
- `PORT` — `int[:label]`; a TCP upstream relayed to `127.0.0.1:int`. The label
  is optional, max 255 bytes, carried in the MANIFEST for the client to display.
  At least one required. Upstream ID = 1-based positional index in cmdline order.

Example:
```
sudo ./gatunad eth0 22 8800:site-a 8080:site-b
```
Exposes upstreams `1→127.0.0.1:22`, `2→127.0.0.1:8800` (label `site-a`),
`3→127.0.0.1:8080` (label `site-b`).

## `gatuna` usage

1. Launch `gatuna.exe` (UAC prompt expected — Npcap requires admin).
2. Select the network adapter connected to the same L2 segment as the server.
3. Click **Discover**. The server's hostname and MAC appear; the upstream list
   populates.
4. Check the upstreams you want to use. The **Mirror** column shows the local
   loopback port to connect to.
5. Connect your app to `127.0.0.1:<mirror_port>`.
6. Click **Test** to run a PING/PONG network test (latency, jitter, loss).
7. Minimize to tray; close to exit.

### Mirror ports

Mirror ports are deterministic: `port ^ (mac[0]<<8 | mac[5])`, clamped to
≥1024. The same server + upstream always yields the same local port, so you
know where to connect without checking the UI. If the computed port is already
in use, the client falls back to an OS-assigned port.

## Building from source

### Prerequisites

- **Server:** Rust toolchain (edition 2021, MSRV 1.70+), Linux with `AF_PACKET`
  support.
- **Client:** .NET 8 SDK with Windows Desktop workload, Npcap installed
  (bundled with Wireshark or standalone from <https://npcap.com>).

### Build the server (Linux)

```sh
cd gatunad
cargo build --release
```

The binary is at `gatunad/target/release/gatunad`.

### Build the client (Windows)

```powershell
cd gatuna-win
dotnet build -c Release
```

Or run directly:
```powershell
dotnet run --project gatuna-win -c Release
```

### Npcap

The client requires Npcap's `wpcap.dll` and `Packet.dll` in the system path.
These are installed by the Npcap installer (also bundled with Wireshark). No
additional NuGet packages or driver installs are needed — SharpPcap talks to
the existing Npcap installation.

## Privileges

**Server (Linux):** `AF_PACKET` requires `CAP_NET_RAW`. Run as root, or grant
the binary the capability once:
```
sudo setcap cap_net_raw+ep ./target/release/gatunad
```

**Client (Windows):** Npcap requires admin by default (`AdminOnly=1` in
`HKLM\SYSTEM\CurrentControlSet\Services\npcap\Parameters`). The client's
`app.manifest` requests `requireAdministrator`, so a UAC prompt appears on
launch. See the [Npcap docs](https://npcap.com/guide/npcap-dev-guide-1.html)
for details on the `AdminOnly` flag if you want to change this.

## Logging

**Server:** errors only, to stdout. Normal lifecycle (DISCOVER/OPEN/CLOSE) is
silent.

**Client:** status line in the UI. Errors are not logged to disk.

## Limitations

- TCP only. UDP wire types reserved, code paths stubbed.
- No auth/crypto. Anyone on the same L2 segment can `DISCOVER` and `OPEN`.
- Single server instance per interface.
- One outstanding `OPEN` at a time on the client (serialized via queue).
- L2 retransmit caps at 10 retries × 5 ms = 50 ms. A permanently dead link
  closes the session with `reason = max_retries`.

## Repository layout

```
gatuna/
├── README.md
├── PROTOCOL.md
├── LICENSE                  # CC0 1.0 Universal
├── .gitignore
├── gatunad/                 # Rust server
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs          # cmdline, rx dispatch, tx task
│       ├── link.rs          # AF_PACKET, classic BPF, raw Ethernet I/O
│       ├── frame.rs         # wire protocol encode/decode
│       ├── upstream.rs      # cmdline parsing, hostname, upstream table
│       └── session.rs       # session store, socket→tunnel pump
└── gatuna-win/              # .NET 8 WinForms client
    ├── gatuna.csproj
    ├── app.manifest         # requireAdministrator
    ├── Program.cs           # tray icon, entry point
    ├── MainForm.cs          # UI: adapter picker, discover, test, upstream list
    ├── TunnelLink.cs        # SharpPcap wrapper, raw Ethernet send/recv
    ├── Frame.cs             # wire protocol encode/decode (mirrors Rust frame.rs)
    ├── SessionManager.cs    # session lifecycle, listeners, OPEN serialization
    └── PingTest.cs          # PING/PONG network test with stats
```

## Versioning

Both programs use `MAJOR.MINOR.PATCH` where:

- **MAJOR** matches the wire protocol version. A v2.x program rejects any frame
  with `version != 2`. No cross-major compatibility.
- **MINOR** is the main change indicator for features and fixes within a major
  version.
- **PATCH** is reserved for bug fixes; generally unused.

Current version: **2.0.0** (wire protocol v2).

Check versions:
```sh
gatunad --version          # Rust server
```
The Windows client shows its version in the title bar and tray tooltip.

## License

CC0 1.0 Universal. See [`LICENSE`](LICENSE).